Converting a number of inline commands to refs

Also reflowing text for line width.
Maybe look into supporting commands with options?

docs/source/yosys_internals/extensions.rst

@@ -58,7 +58,7 @@ about the internal data storage format used in Yosys and the classes that it
 provides.
 
 This document will focus on the much simpler version of RTLIL left after the
-commands ``proc`` and ``memory`` (or ``memory -nomap``):
+commands :cmd:ref:`proc` and :cmd:ref:`memory` (or ``memory -nomap``):
 
 .. figure:: ../../images/simplified_rtlil.*
     :class: width-helper
@@ -77,9 +77,10 @@ It is possible to only work on this simpler version:
     }
 
 When trying to understand what a command does, creating a small test case to
-look at the output of ``dump`` and ``show`` before and after the command has
-been executed can be helpful.  The :doc:`/using_yosys/more_scripting/selections`
-document has more information on using these commands.
+look at the output of :cmd:ref:`dump` and :cmd:ref:`show` before and after the
+command has been executed can be helpful.  The
+:doc:`/using_yosys/more_scripting/selections` document has more information on
+using these commands.
 
 .. todo:: copypaste
 
@@ -120,15 +121,16 @@ Most commands modify existing modules, not create new ones.
 
 When modifying existing modules, stick to the following DOs and DON'Ts:
 
-- Do not remove wires. Simply disconnect them and let a successive ``clean``
-  command worry about removing it.
+- Do not remove wires. Simply disconnect them and let a successive
+  :cmd:ref:`clean` command worry about removing it.
 - Use ``module->fixup_ports()`` after changing the ``port_*`` properties of
   wires.
 - You can safely remove cells or change the ``connections`` property of a cell,
   but be careful when changing the size of the ``SigSpec`` connected to a cell
   port.
 
-- Use the ``SigMap`` helper class (see next slide) when you need a unique handle for each signal bit.
+- Use the ``SigMap`` helper class (see next section) when you need a unique
+  handle for each signal bit.
 
 Using the SigMap helper class
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/source/yosys_internals/flow/command_ordering.rst

@@ -28,13 +28,13 @@ components, such as LUTs, gates, or half- and full-adders.
 The extract pass
 ~~~~~~~~~~~~~~~~
 
-- Like the ``techmap`` pass, the ``extract`` pass is called with a map file. It
-  compares the circuits inside the modules of the map file with the design and
-  looks for sub-circuits in the design that match any of the modules in the map
-  file.
-- If a match is found, the ``extract`` pass will replace the matching subcircuit
-  with an instance of the module from the map file.
-- In a way the ``extract`` pass is the inverse of the techmap pass.
+- Like the :cmd:ref:`techmap` pass, the :cmd:ref:`extract` pass is called with a
+  map file. It compares the circuits inside the modules of the map file with the
+  design and looks for sub-circuits in the design that match any of the modules
+  in the map file.
+- If a match is found, the :cmd:ref:`extract` pass will replace the matching
+  subcircuit with an instance of the module from the map file.
+- In a way the :cmd:ref:`extract` pass is the inverse of the techmap pass.
 
 .. todo:: copypaste
 
@@ -93,19 +93,19 @@ can also be used to implement 16x20-bit multiplication.
 A way of mapping such elements in coarse grain synthesis is the wrap-extract-unwrap method:
 
 wrap
-  Identify candidate-cells in the circuit and wrap them in a cell with a constant
-  wider bit-width using ``techmap``. The wrappers use the same parameters as the original cell, so
-  the information about the original width of the ports is preserved.
-  Then use the ``connwrappers`` command to connect up the bit-extended in- and
-  outputs of the wrapper cells.
+  Identify candidate-cells in the circuit and wrap them in a cell with a
+  constant wider bit-width using :cmd:ref:`techmap`. The wrappers use the same
+  parameters as the original cell, so the information about the original width
+  of the ports is preserved. Then use the ``connwrappers`` command to connect up
+  the bit-extended in- and outputs of the wrapper cells.
 
 extract
   Now all operations are encoded using the same bit-width as the coarse grain
-  element. The ``extract`` command can be used to replace circuits with cells
-  of the target architecture.
+  element. The :cmd:ref:`extract` command can be used to replace circuits with
+  cells of the target architecture.
 
 unwrap
-  The remaining wrapper cell can be unwrapped using ``techmap``.
+  The remaining wrapper cell can be unwrapped using :cmd:ref:`techmap`.
 
 Example: DSP48_MACC
 ~~~~~~~~~~~~~~~~~~~
@@ -144,7 +144,8 @@ Extract: ``macc_xilinx_xmap.v``
    :language: verilog
    :caption: ``docs/resources/PRESENTATION_ExAdv/macc_xilinx_xmap.v``
 
-... simply use the same wrapping commands on this module as on the design to create a template for the ``extract`` command.
+... simply use the same wrapping commands on this module as on the design to
+create a template for the :cmd:ref:`extract` command.
 
 Unwrapping multipliers: ``macc_xilinx_unwrap_map.v``
 

docs/source/yosys_internals/flow/model_checking.rst

@@ -17,7 +17,8 @@ passes in Yosys.
 
 Other applications include checking if a module conforms to interface standards.
 
-The ``sat`` command in Yosys can be used to perform Symbolic Model Checking.
+The :cmd:ref:`sat` command in Yosys can be used to perform Symbolic Model
+Checking.
 
 Checking techmap
 ~~~~~~~~~~~~~~~~

docs/source/yosys_internals/flow/verilog_frontend.rst

@@ -407,9 +407,9 @@ transformed into a set of d-type flip-flops and the
 multiplexers.
 
 In more complex examples (e.g. asynchronous resets) the part of the
-``RTLIL::CaseRule``/``RTLIL::SwitchRule`` tree that describes the
-asynchronous reset must first be transformed to the correct
-``RTLIL::SyncRule`` objects. This is done by the proc_adff pass.
+``RTLIL::CaseRule``/``RTLIL::SwitchRule`` tree that describes the asynchronous
+reset must first be transformed to the correct ``RTLIL::SyncRule`` objects. This
+is done by the :cmd:ref:`proc_adff` pass.
 
 The ProcessGenerator algorithm
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -591,16 +591,16 @@ The proc pass
 
 The ProcessGenerator converts a behavioural model in AST representation to a
 behavioural model in ``RTLIL::Process`` representation. The actual conversion
-from a behavioural model to an RTL representation is performed by the ``proc``
-pass and the passes it launches:
+from a behavioural model to an RTL representation is performed by the
+:cmd:ref:`proc` pass and the passes it launches:
 
--  | proc_clean and proc_rmdead 
+-  | :cmd:ref:`proc_clean` and :cmd:ref:`proc_rmdead` 
    | These two passes just clean up the ``RTLIL::Process`` structure. The
-     ``proc_clean`` pass removes empty parts (eg. empty assignments) from the
-     process and ``proc_rmdead`` detects and removes unreachable branches from
-     the process's decision trees.
+     :cmd:ref:`proc_clean` pass removes empty parts (eg. empty assignments) from
+     the process and :cmd:ref:`proc_rmdead` detects and removes unreachable
+     branches from the process's decision trees.
 
--  | proc_arst 
+-  | :cmd:ref:`proc_arst` 
    | This pass detects processes that describe d-type flip-flops with
      asynchronous resets and rewrites the process to better reflect what they
      are modelling: Before this pass, an asynchronous reset has two
@@ -608,22 +608,22 @@ pass and the passes it launches:
      reset path. After this pass the sync rule for the reset is level-sensitive
      and the top-level ``RTLIL::SwitchRule`` has been removed.
 
--  | proc_mux 
+-  | :cmd:ref:`proc_mux` 
    | This pass converts the ``RTLIL::CaseRule``/ ``RTLIL::SwitchRule``-tree to a
      tree of multiplexers per written signal. After this, the ``RTLIL::Process``
      structure only contains the ``RTLIL::SyncRule`` s that describe the output
      registers.
 
--  | proc_dff
+-  | :cmd:ref:`proc_dff`
    | This pass replaces the ``RTLIL::SyncRule`` s to d-type flip-flops (with
      asynchronous resets if necessary).
 
--  | proc_dff
+-  | :cmd:ref:`proc_dff`
    | This pass replaces the ``RTLIL::MemWriteAction`` s with ``$memwr`` cells.
 
--  | proc_clean
-   | A final call to ``proc_clean`` removes the now empty ``RTLIL::Process``
-     objects.
+-  | :cmd:ref:`proc_clean`
+   | A final call to :cmd:ref:`proc_clean` removes the now empty
+     ``RTLIL::Process`` objects.
 
 Performing these last processing steps in passes instead of in the Verilog
 frontend has two important benefits:

docs/source/yosys_internals/formats/cell_library.rst

@@ -255,8 +255,8 @@ additional two parameters:
 ``\ARST_VALUE``
    	The state of ``\Q`` will be set to this value when the reset is active.
 
-Usually these cells are generated by the ``proc`` pass using the information in
-the designs RTLIL::Process objects.
+Usually these cells are generated by the :cmd:ref:`proc` pass using the
+information in the designs RTLIL::Process objects.
 
 D-type flip-flops with synchronous reset are represented by ``$sdff`` cells. As
 the ``$dff`` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they
@@ -270,8 +270,8 @@ additional two parameters:
 ``\SRST_VALUE``
 	The state of ``\Q`` will be set to this value when the reset is active.
 
-Note that the ``$adff`` and ``$sdff`` cells can only be used when the reset value is
-constant.
+Note that the ``$adff`` and ``$sdff`` cells can only be used when the reset
+value is constant.
 
 D-type flip-flops with asynchronous load are represented by ``$aldff`` cells. As
 the ``$dff`` cells they have ``\CLK``, ``\D`` and ``\Q`` ports. In addition they
@@ -433,16 +433,17 @@ The ``$memwr_v2`` cells have a clock input ``\CLK``, an enable input ``\EN``
 	``1'b1`` and on the negative edge if this parameter is ``1'b0``.
 
 ``\PORTID``
-	An identifier for this write port, used to index write port bit mask parameters.
+	An identifier for this write port, used to index write port bit mask
+	parameters.
 
 ``\PRIORITY_MASK``
-	This parameter is a bitmask of write ports that this write port has
-	priority over in case of writing to the same address.  The bits of this
-	parameter are indexed by the other write port's ``\PORTID`` parameter.
-	Write ports can only have priority over write ports with lower port ID.
-	When two ports write to the same address and neither has priority over
-	the other, the result is undefined.  Priority can only be set between
-	two synchronous ports sharing the same clock domain.
+	This parameter is a bitmask of write ports that this write port has priority
+	over in case of writing to the same address.  The bits of this parameter are
+	indexed by the other write port's ``\PORTID`` parameter. Write ports can
+	only have priority over write ports with lower port ID. When two ports write
+	to the same address and neither has priority over the other, the result is
+	undefined.  Priority can only be set between two synchronous ports sharing
+	the same clock domain.
 
 The ``$meminit_v2`` cells have an address input ``\ADDR``, a data input
 ``\DATA``, with the width of the ``\DATA`` port equal to ``\WIDTH`` parameter
@@ -468,13 +469,13 @@ synthesis to succeed.
 	initialization conflict.
 
 The HDL frontend models a memory using RTLIL::Memory objects and asynchronous
-``$memrd_v2`` and ``$memwr_v2`` cells. The ``memory`` pass (i.e.~its various
-sub-passes) migrates ``$dff`` cells into the ``$memrd_v2`` and ``$memwr_v2``
-cells making them synchronous, then converts them to a single ``$mem_v2`` cell
-and (optionally) maps this cell type to ``$dff`` cells for the individual words
-and multiplexer-based address decoders for the read and write interfaces. When
-the last step is disabled or not possible, a ``$mem_v2`` cell is left in the
-design.
+``$memrd_v2`` and ``$memwr_v2`` cells. The :cmd:ref:`memory` pass (i.e.~its
+various sub-passes) migrates ``$dff`` cells into the ``$memrd_v2`` and
+``$memwr_v2`` cells making them synchronous, then converts them to a single
+``$mem_v2`` cell and (optionally) maps this cell type to ``$dff`` cells for the
+individual words and multiplexer-based address decoders for the read and write
+interfaces. When the last step is disabled or not possible, a ``$mem_v2`` cell
+is left in the design.
 
 The ``$mem_v2`` cell provides the following parameters:
 
@@ -600,15 +601,15 @@ The ``$mem_v2`` cell has the following ports:
 	This input is ``\WR_PORTS*\WIDTH`` bits wide, containing all data
 	signals for the write ports.
 
-The ``memory_collect`` pass can be used to convert discrete ``$memrd_v2``,
-``$memwr_v2``, and ``$meminit_v2`` cells belonging to the same memory to a
-single ``$mem_v2`` cell, whereas the ``memory_unpack`` pass performs the inverse
-operation. The ``memory_dff`` pass can combine asynchronous memory ports that
-are fed by or feeding registers into synchronous memory ports. The
-``memory_bram`` pass can be used to recognize ``$mem_v2`` cells that can be
-implemented with a block RAM resource on an FPGA. The ``memory_map`` pass can be
-used to implement ``$mem_v2`` cells as basic logic: word-wide DFFs and address
-decoders.
+The :cmd:ref:`memory_collect` pass can be used to convert discrete
+``$memrd_v2``, ``$memwr_v2``, and ``$meminit_v2`` cells belonging to the same
+memory to a single ``$mem_v2`` cell, whereas the :cmd:ref:`memory_unpack` pass
+performs the inverse operation. The :cmd:ref:`memory_dff` pass can combine
+asynchronous memory ports that are fed by or feeding registers into synchronous
+memory ports. The :cmd:ref:`memory_bram` pass can be used to recognize
+``$mem_v2`` cells that can be implemented with a block RAM resource on an FPGA.
+The :cmd:ref:`memory_map` pass can be used to implement ``$mem_v2`` cells as
+basic logic: word-wide DFFs and address decoders.
 
 Finite state machines
 ~~~~~~~~~~~~~~~~~~~~~

docs/source/yosys_internals/formats/rtlil_rep.rst

@@ -6,22 +6,22 @@ representation. The only exception are the high-level frontends that use the AST
 representation as an intermediate step before generating RTLIL data.
 
 In order to avoid reinventing names for the RTLIL classes, they are simply
-referred to by their full C++ name, i.e. including the ``RTLIL::`` namespace prefix,
-in this document.
+referred to by their full C++ name, i.e. including the ``RTLIL::`` namespace
+prefix, in this document.
 
 :numref:`Figure %s <fig:Overview_RTLIL>` shows a simplified Entity-Relationship
 Diagram (ER Diagram) of RTLIL. In :math:`1:N` relationships the arrow points
-from the :math:`N` side to the :math:`1`. For example one ``RTLIL::Design`` contains
-:math:`N` (zero to many) instances of ``RTLIL::Module`` . A two-pointed arrow
-indicates a :math:`1:1` relationship.
+from the :math:`N` side to the :math:`1`. For example one ``RTLIL::Design``
+contains :math:`N` (zero to many) instances of ``RTLIL::Module`` . A two-pointed
+arrow indicates a :math:`1:1` relationship.
 
 The ``RTLIL::Design`` is the root object of the RTLIL data structure. There is
 always one "current design" in memory which passes operate on, frontends add
 data to and backends convert to exportable formats. But in some cases passes
-internally generate additional ``RTLIL::Design`` objects. For example when a pass is
-reading an auxiliary Verilog file such as a cell library, it might create an
-additional ``RTLIL::Design`` object and call the Verilog frontend with this other
-object to parse the cell library.
+internally generate additional ``RTLIL::Design`` objects. For example when a
+pass is reading an auxiliary Verilog file such as a cell library, it might
+create an additional ``RTLIL::Design`` object and call the Verilog frontend with
+this other object to parse the cell library.
 
 .. figure:: ../../../images/overview_rtlil.*
 	:class: width-helper
@@ -31,9 +31,9 @@ object to parse the cell library.
 
 There is only one active ``RTLIL::Design`` object that is used by all frontends,
 passes and backends called by the user, e.g. using a synthesis script. The
-``RTLIL::Design`` then contains zero to many ``RTLIL::Module`` objects. This corresponds
-to modules in Verilog or entities in VHDL. Each module in turn contains objects
-from three different categories:
+``RTLIL::Design`` then contains zero to many ``RTLIL::Module`` objects. This
+corresponds to modules in Verilog or entities in VHDL. Each module in turn
+contains objects from three different categories:
 
 -  ``RTLIL::Cell`` and ``RTLIL::Wire`` objects represent classical netlist data.
 
@@ -44,8 +44,8 @@ from three different categories:
 -  ``RTLIL::Memory`` objects represent addressable memories (arrays).
 
 Usually the output of the synthesis procedure is a netlist, i.e. all
-``RTLIL::Process`` and ``RTLIL::Memory`` objects must be replaced by ``RTLIL::Cell`` and
-``RTLIL::Wire`` objects by synthesis passes.
+``RTLIL::Process`` and ``RTLIL::Memory`` objects must be replaced by
+``RTLIL::Cell`` and ``RTLIL::Wire`` objects by synthesis passes.
 
 All features of the HDL that cannot be mapped directly to these RTLIL classes
 must be transformed to an RTLIL-compatible representation by the HDL frontend.
@@ -78,9 +78,9 @@ This has three advantages:
 
 -  Second, the information about which identifiers were originally provided by
    the user is always available which can help guide some optimizations. For
-   example the ``opt_rmunused`` tries to preserve signals with a user-provided
-   name but doesn't hesitate to delete signals that have auto-generated names
-   when they just duplicate other signals.
+   example the :cmd:ref:`opt_rmunused` tries to preserve signals with a
+   user-provided name but doesn't hesitate to delete signals that have
+   auto-generated names when they just duplicate other signals.
 
 -  Third, the delicate job of finding suitable auto-generated public visible
    names is deferred to one central location. Internally auto-generated names
@@ -184,8 +184,8 @@ An ``RTLIL::Cell`` object has the following properties:
 -  A list of parameters (for parametric cells)
 -  Cell ports and the connections of ports to wires and constants
 
-The connections of ports to wires are coded by assigning an ``RTLIL::SigSpec`` to
-each cell port. The ``RTLIL::SigSpec`` data type is described in the next
+The connections of ports to wires are coded by assigning an ``RTLIL::SigSpec``
+to each cell port. The ``RTLIL::SigSpec`` data type is described in the next
 section.
 
 .. _sec:rtlil_sigspec:
@@ -320,8 +320,8 @@ trees before further processing them.
 
 One of the first actions performed on a design in RTLIL representation in most
 synthesis scripts is identifying asynchronous resets. This is usually done using
-the ``proc_arst`` pass. This pass transforms the above example to the following
-``RTLIL::Process``:
+the :cmd:ref:`proc_arst` pass. This pass transforms the above example to the
+following ``RTLIL::Process``:
 
 .. code:: RTLIL
    :number-lines:
@@ -381,8 +381,8 @@ synthesis tasks.
 RTLIL::Memory
 -------------
 
-For every array (memory) in the HDL code an ``RTLIL::Memory`` object is created. A
-memory object has the following properties:
+For every array (memory) in the HDL code an ``RTLIL::Memory`` object is created.
+A memory object has the following properties:
 
 -  The memory name
 -  A list of attributes

docs/source/yosys_internals/techmap.rst

@@ -111,10 +111,9 @@ Techmap by example
 
 .. todo:: copypaste
 
-As a quick recap, the ``techmap`` command replaces cells in the design with
-implementations given as Verilog code (called "map files"). It can replace
-Yosys' internal cell types (such as ``$or``) as well as user-defined cell
-types.
+As a quick recap, the :cmd:ref:`techmap` command replaces cells in the design
+with implementations given as Verilog code (called "map files"). It can replace
+Yosys' internal cell types (such as ``$or``) as well as user-defined cell types.
 
 - Verilog parameters are used extensively to customize the internal cell types.
 - Additional special parameters are used by techmap to communicate meta-data to
@@ -188,14 +187,15 @@ Scripting in map modules
 - You can even call techmap recursively!
 - Example use-cases:
 
-    - Using always blocks in map module: call ``proc``
-    - Perform expensive optimizations (such as ``freduce``) on cells where
-      this is known to work well.
+    - Using always blocks in map module: call :cmd:ref:`proc`
+    - Perform expensive optimizations (such as :cmd:ref:`freduce`) on cells
+      where this is known to work well.
     - Interacting with custom commands.
 
-.. note:: PROTIP: 
-    Commands such as ``shell``, ``show -pause``, and ``dump`` can be use
-    in the ``_TECHMAP_DO_*`` scripts for debugging map modules.
+.. note:: PROTIP:
+
+    Commands such as :cmd:ref:`shell`, ``show -pause``, and :cmd:ref:`dump` can
+    be used in the ``_TECHMAP_DO_*`` scripts for debugging map modules.
 
 Example: