Docs: Shorten cmd:ref

docs/source/using_yosys/synthesis/opt.rst

@@ -6,10 +6,10 @@ This chapter outlines these optimizations.
 
 .. todo:: "outlines these optimizations" or "outlines *some*.."?
 
-The :cmd:ref:`opt` macro command
+The `opt` macro command
 --------------------------------
 
-The Yosys pass :cmd:ref:`opt` runs a number of simple optimizations. This
+The Yosys pass `opt` runs a number of simple optimizations. This
 includes removing unused signals and cells and const folding. It is recommended
 to run this pass after each major step in the synthesis script.  As listed in
 :doc:`/cmd/opt`, this macro command calls the following ``opt_*`` commands:
@@ -17,11 +17,11 @@ to run this pass after each major step in the synthesis script.  As listed in
 .. literalinclude:: /code_examples/macro_commands/opt.ys
    :language: yoscrypt
    :start-after: #end:
-   :caption: Passes called by :cmd:ref:`opt`
+   :caption: Passes called by `opt`
 
 .. _adv_opt_expr:
 
-Constant folding and simple expression rewriting - :cmd:ref:`opt_expr`
+Constant folding and simple expression rewriting - `opt_expr`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. todo:: unsure if this is too much detail and should be in :doc:`/yosys_internals/index`
@@ -31,7 +31,7 @@ described in :doc:`/yosys_internals/formats/cell_library`. This means a cell
 with all constant inputs is replaced with the constant value this cell drives.
 In some cases this pass can also optimize cells with some constant inputs.
 
-.. table:: Const folding rules for `$_AND_` cells as used in :cmd:ref:`opt_expr`.
+.. table:: Const folding rules for `$_AND_` cells as used in `opt_expr`.
    :name: tab:opt_expr_and
    :align: center
 
@@ -69,7 +69,7 @@ undef.
 The last two lines simply replace an `$_AND_` gate with one constant-1 input
 with a buffer.
 
-Besides this basic const folding the :cmd:ref:`opt_expr` pass can replace 1-bit
+Besides this basic const folding the `opt_expr` pass can replace 1-bit
 wide `$eq` and `$ne` cells with buffers or not-gates if one input is
 constant.  Equality checks may also be reduced in size if there are redundant
 bits in the arguments (i.e. bits which are constant on both inputs).  This can,
@@ -77,7 +77,7 @@ for example, result in a 32-bit wide constant like ``255`` being reduced to the
 8-bit value of ``8'11111111`` if the signal being compared is only 8-bit as in
 :ref:`addr_gen_clean` of :doc:`/getting_started/example_synth`.
 
-The :cmd:ref:`opt_expr` pass is very conservative regarding optimizing `$mux`
+The `opt_expr` pass is very conservative regarding optimizing `$mux`
 cells, as these cells are often used to model decision-trees and breaking these
 trees can interfere with other optimizations.
 
@@ -85,14 +85,14 @@ trees can interfere with other optimizations.
    :language: Verilog
    :start-after: read_verilog <<EOT
    :end-before: EOT
-   :caption: example verilog for demonstrating :cmd:ref:`opt_expr`
+   :caption: example verilog for demonstrating `opt_expr`
 
 .. figure:: /_images/code_examples/opt/opt_expr.*
    :class: width-helper invert-helper
 
-   Before and after :cmd:ref:`opt_expr`
+   Before and after `opt_expr`
 
-Merging identical cells - :cmd:ref:`opt_merge`
+Merging identical cells - `opt_merge`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This pass performs trivial resource sharing. This means that this pass
@@ -101,21 +101,21 @@ of the cell.
 
 The option ``-nomux`` can be used to disable resource sharing for multiplexer
 cells (`$mux` and `$pmux`.) This can be useful as it prevents multiplexer
-trees to be merged, which might prevent :cmd:ref:`opt_muxtree` to identify
+trees to be merged, which might prevent `opt_muxtree` to identify
 possible optimizations.
 
 .. literalinclude:: /code_examples/opt/opt_merge.ys
    :language: Verilog
    :start-after: read_verilog <<EOT
    :end-before: EOT
-   :caption: example verilog for demonstrating :cmd:ref:`opt_merge`
+   :caption: example verilog for demonstrating `opt_merge`
 
 .. figure:: /_images/code_examples/opt/opt_merge.*
    :class: width-helper invert-helper
 
-   Before and after :cmd:ref:`opt_merge`
+   Before and after `opt_merge`
 
-Removing never-active branches from multiplexer tree - :cmd:ref:`opt_muxtree`
+Removing never-active branches from multiplexer tree - `opt_muxtree`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This pass optimizes trees of multiplexer cells by analyzing the select inputs.
@@ -125,19 +125,19 @@ Consider the following simple example:
    :language: Verilog
    :start-after: read_verilog <<EOT
    :end-before: EOT
-   :caption: example verilog for demonstrating :cmd:ref:`opt_muxtree`
+   :caption: example verilog for demonstrating `opt_muxtree`
 
 The output can never be ``c``, as this would require ``a`` to be 1 for the outer
-multiplexer and 0 for the inner multiplexer. The :cmd:ref:`opt_muxtree` pass
+multiplexer and 0 for the inner multiplexer. The `opt_muxtree` pass
 detects this contradiction and replaces the inner multiplexer with a constant 1,
 yielding the logic for ``y = a ? b : d``.
 
 .. figure:: /_images/code_examples/opt/opt_muxtree.*
    :class: width-helper invert-helper
 
-   Before and after :cmd:ref:`opt_muxtree`
+   Before and after `opt_muxtree`
 
-Simplifying large MUXes and AND/OR gates - :cmd:ref:`opt_reduce`
+Simplifying large MUXes and AND/OR gates - `opt_reduce`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This is a simple optimization pass that identifies and consolidates identical
@@ -155,7 +155,7 @@ Lastly this pass consolidates trees of `$reduce_and` cells and trees of
 These three simple optimizations are performed in a loop until a stable result
 is produced.
 
-Merging mutually exclusive cells with shared inputs - :cmd:ref:`opt_share`
+Merging mutually exclusive cells with shared inputs - `opt_share`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This pass identifies mutually exclusive cells of the same type that:
@@ -169,17 +169,17 @@ multiplexing its output to multiplexing the non-shared input signals.
    :language: Verilog
    :start-after: read_verilog <<EOT
    :end-before: EOT
-   :caption: example verilog for demonstrating :cmd:ref:`opt_share`
+   :caption: example verilog for demonstrating `opt_share`
 
 .. figure:: /_images/code_examples/opt/opt_share.*
    :class: width-helper invert-helper
 
-   Before and after :cmd:ref:`opt_share`
+   Before and after `opt_share`
 
-When running :cmd:ref:`opt` in full, the original `$mux` (labeled ``$3``) is
-optimized away by :cmd:ref:`opt_expr`.
+When running `opt` in full, the original `$mux` (labeled ``$3``) is
+optimized away by `opt_expr`.
 
-Performing DFF optimizations - :cmd:ref:`opt_dff`
+Performing DFF optimizations - `opt_dff`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This pass identifies single-bit d-type flip-flops (`$_DFF_`, `$dff`, and
@@ -190,30 +190,30 @@ removing unused control inputs.
 Called with ``-nodffe`` and ``-nosdff``, this pass is used to prepare a design
 for :doc:`/using_yosys/synthesis/fsm`.
 
-Removing unused cells and wires - :cmd:ref:`opt_clean` pass
+Removing unused cells and wires - `opt_clean` pass
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This pass identifies unused signals and cells and removes them from the design.
 It also creates an ``\unused_bits`` attribute on wires with unused bits. This
 attribute can be used for debugging or by other optimization passes.
 
-When to use :cmd:ref:`opt` or :cmd:ref:`clean`
+When to use `opt` or `clean`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Usually it does not hurt to call :cmd:ref:`opt` after each regular command in
+Usually it does not hurt to call `opt` after each regular command in
 the synthesis script. But it increases the synthesis time, so it is favourable
-to only call :cmd:ref:`opt` when an improvement can be achieved.
+to only call `opt` when an improvement can be achieved.
 
-It is generally a good idea to call :cmd:ref:`opt` before inherently expensive
-commands such as :cmd:ref:`sat` or :cmd:ref:`freduce`, as the possible gain is
+It is generally a good idea to call `opt` before inherently expensive
+commands such as `sat` or `freduce`, as the possible gain is
 much higher in these cases as the possible loss.
 
-The :cmd:ref:`clean` command, which is an alias for :cmd:ref:`opt_clean` with
+The `clean` command, which is an alias for `opt_clean` with
 fewer outputs, on the other hand is very fast and many commands leave a mess
 (dangling signal wires, etc). For example, most commands do not remove any wires
 or cells. They just change the connections and depend on a later call to clean
 to get rid of the now unused objects. So the occasional ``;;``, which itself is
-an alias for :cmd:ref:`clean`, is a good idea in every synthesis script, e.g:
+an alias for `clean`, is a good idea in every synthesis script, e.g:
 
 .. code-block:: yoscrypt
 
@@ -227,4 +227,4 @@ Other optimizations
 - :doc:`/cmd/wreduce`
 - :doc:`/cmd/peepopt`
 - :doc:`/cmd/share`
-- :cmd:ref:`abc` and :cmd:ref:`abc9`, see also: :doc:`abc`.
+- `abc` and `abc9`, see also: :doc:`abc`.