Docs: tidying

- Use `:file:` role for file names, as well as `:makevar:` and `:program:`.
- Remove deprecated `linux-arm` and `linux-riscv64` oss-cad-suite targets.
- Add link to ABC.
- More (and better) links to code examples.  Formatted `:file:` text with link
  to source on github.
- Includes a few extra todos (mostly picking up inline code blocks and a couple
  intro reminders).
- Fixing a few missing `:yoscrypt:` and `:cmd:ref:` tags.
- Reflowing some paragraphs for spacing/width.

docs/source/appendix/env_vars.rst

@@ -2,10 +2,10 @@ Yosys environment variables
 ===========================
 
 ``HOME``
-   Yosys command history is stored in ``$HOME/.yosys_history``.  Graphics (from
+   Yosys command history is stored in :file:`$HOME/.yosys_history`.  Graphics
-   :cmd:ref:`show` and :cmd:ref:`viz` commands) will output to this directory by
+   (from :cmd:ref:`show` and :cmd:ref:`viz` commands) will output to this
-   default.  This environment variable is also used in some cases for resolving
+   directory by default.  This environment variable is also used in some cases
-   filenames with ``~``.
+   for resolving filenames with :file:`~`.
 
 ``PATH``
    May be used in OpenBSD builds for finding the location of Yosys executable.
@@ -14,7 +14,7 @@ Yosys environment variables
    Used for storing temporary files.
 
 ``ABC``
-   When compiling Yosys with out-of-tree ABC using ``ABCEXTERNAL``, this
+   When compiling Yosys with out-of-tree ABC using :makevar:`ABCEXTERNAL`, this
    variable can be used to override the external ABC executable.
 
 ``YOSYS_NOVERIFIC``

docs/source/getting_started/example_synth.rst

@@ -26,7 +26,7 @@ First, let's quickly look at the design we'll be synthesizing:
 .. literalinclude:: /code_examples/fifo/fifo.v
    :language: Verilog
    :linenos:
-   :caption: ``fifo.v``
+   :caption: :file:`fifo.v`
    :name: fifo-v
 
 .. todo:: fifo.v description
@@ -36,7 +36,7 @@ Loading the design
 
 Let's load the design into Yosys.  From the command line, we can call ``yosys
 fifo.v``.  This will open an interactive Yosys shell session and immediately
-parse the code from ``fifo.v`` and convert it into an Abstract Syntax Tree
+parse the code from :ref:`fifo-v` and convert it into an Abstract Syntax Tree
 (AST).  If you are interested in how this happens, there is more information in
 the document, :doc:`/yosys_internals/flow/verilog_frontend`.  For now, suffice
 it to say that we do this to simplify further processing of the design.  You
@@ -214,7 +214,7 @@ could restart our shell session, but instead let's use two new commands:
    :language: doscon
    :start-at: design -reset
    :end-before: yosys> proc
-   :caption: reloading ``fifo.v`` and running :yoscrypt:`hierarchy -check -top fifo`
+   :caption: reloading :file:`fifo.v` and running :yoscrypt:`hierarchy -check -top fifo`
 
 Notice how this time we didn't see any of those `$abstract` modules?  That's
 because when we ran ``yosys fifo.v``, the first command Yosys called was
@@ -234,7 +234,7 @@ design.  If we know that our design won't run into this issue, we can skip the
    The number before a command's output increments with each command run.  Don't
    worry if your numbers don't match ours!  The output you are seeing comes from
    the same script that was used to generate the images in this document,
-   included in the source as ``fifo.ys``. There are extra commands being run
+   included in the source as :file:`fifo.ys`. There are extra commands being run
    which you don't see, but feel free to try them yourself, or play around with
    different commands.  You can always start over with a clean slate by calling
    ``exit`` or hitting ``ctrl+c`` (i.e. SIGINT) and re-launching the Yosys
@@ -305,8 +305,8 @@ optimizations between modules which would otherwise be missed.  Let's run
 
 The pieces have moved around a bit, but we can see :ref:`addr_gen_proc` from
 earlier has replaced the ``fifo_reader`` block in :ref:`rdata_proc`.  We can
-also see that the ``addr`` output has been renamed to ``fifo_reader.addr`` and
+also see that the ``addr`` output has been renamed to :file:`fifo_reader.addr`
-merged with the ``raddr`` wire feeding into the ``$memrd`` cell.  This wire
+and merged with the ``raddr`` wire feeding into the ``$memrd`` cell.  This wire
 merging happened during the call to :cmd:ref:`clean` which we can see in the
 :ref:`flat_clean`.  Note that in an interactive terminal the outputs of
 :cmd:ref:`flatten` and :cmd:ref:`clean` will be combined into a single
@@ -803,11 +803,11 @@ The iCE40 synthesis flow has the following output modes available:
 - :doc:`/cmd/write_json`.
 
 As an example, if we called :yoscrypt:`synth_ice40 -top fifo -json fifo.json`,
-our synthesized ``fifo`` design will be output as ``fifo.json``.  We can then
+our synthesized ``fifo`` design will be output as :file:`fifo.json`.  We can
-read the design back into Yosys with :cmd:ref:`read_json`, but make sure you use
+then read the design back into Yosys with :cmd:ref:`read_json`, but make sure
-:yoscrypt:`design -reset` or open a new interactive terminal first.  The JSON
+you use :yoscrypt:`design -reset` or open a new interactive terminal first.  The
-output we get can also be loaded into `nextpnr`_ to do place and route; but that
+JSON output we get can also be loaded into `nextpnr`_ to do place and route; but
-is beyond the scope of this documentation.
+that is beyond the scope of this documentation.
 
 .. _nextpnr: https://github.com/YosysHQ/nextpnr
 

docs/source/getting_started/installation.rst

@@ -49,9 +49,7 @@ The `OSS CAD Suite`_ releases `nightly builds`_ for the following architectures:
       - Targeted for Windows 10 and 11, but older 64-bit version of Windows 7,
         8, or 8.1 should work
 
-   - linux-arm |linux-arm|
    - linux-arm64 |linux-arm64|
-   - linux-riscv64 (untested) |linux-riscv64|
 
 .. _OSS CAD Suite: https://github.com/YosysHQ/oss-cad-suite-build
 .. _nightly builds: https://github.com/YosysHQ/oss-cad-suite-build/releases/latest
@@ -60,9 +58,7 @@ The `OSS CAD Suite`_ releases `nightly builds`_ for the following architectures:
 .. |darwin-x64| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/darwin-x64.yml/badge.svg
 .. |darwin-arm64| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/darwin-arm64.yml/badge.svg
 .. |windows-x64| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/windows-x64.yml/badge.svg
-.. |linux-arm| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/linux-arm.yml/badge.svg
 .. |linux-arm64| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/linux-arm64.yml/badge.svg
-.. |linux-riscv64| image:: https://github.com/YosysHQ/oss-cad-suite-build/actions/workflows/linux-riscv64.yml/badge.svg
 
 Building from source
 ~~~~~~~~~~~~~~~~~~~~
@@ -133,8 +129,10 @@ Then, simply run ``make`` in this directory.
    make
    sudo make install
 
-Note that this also downloads, builds, and installs ABC (using yosys-abc as the
+Note that this also downloads, builds, and installs `ABC`_ (using
-executable name).
+:program:`yosys-abc` as the executable name).
+
+.. _ABC: https://github.com/berkeley-abc/abc
 
 .. seealso:: 
 
@@ -167,11 +165,12 @@ directories:
 ``kernel/``
    This directory contains all the core functionality of Yosys. This includes
    the functions and definitions for working with the RTLIL data structures
-   (``rtlil.{h|cc}``), the ``main()`` function (``driver.cc``), the internal
+   (:file:`rtlil.{h|cc}`), the ``main()`` function (:file:`driver.cc`), the
-   framework for generating log messages (``log.{h|cc}``), the internal
+   internal framework for generating log messages (:file:`log.{h|cc}`), the
-   framework for registering and calling passes (``register.{h|cc}``), some core
+   internal framework for registering and calling passes
-   commands that are not really passes (``select.cc``, ``show.cc``, …) and a
+   (:file:`register.{h|cc}`), some core commands that are not really passes
-   couple of other small utility libraries.
+   (:file:`select.cc`, :file:`show.cc`, …) and a couple of other small utility
+   libraries.
 
 ``libs/``
    Libraries packaged with Yosys builds are contained in this folder.  See
@@ -182,7 +181,7 @@ directories:
 
 ``passes/``
    This directory contains a subdirectory for each pass or group of passes. For
-   example as of this writing the directory ``passes/hierarchy/`` contains the
+   example as of this writing the directory :file:`passes/hierarchy/` contains the
    code for three passes: :cmd:ref:`hierarchy`, :cmd:ref:`submod`, and
    :cmd:ref:`uniquify`.
 
@@ -194,15 +193,16 @@ directories:
    This directory contains the suite of unit tests and regression tests used by
    Yosys.  See :doc:`/test_suites`.
 
-The top-level Makefile includes ``frontends/*/Makefile.inc``,
+The top-level Makefile includes :file:`frontends/{*}/Makefile.inc`,
-``passes/*/Makefile.inc`` and ``backends/*/Makefile.inc``. So when extending
+:file:`passes/{*}/Makefile.inc` and :file:`backends/{*}/Makefile.inc`. So when
-Yosys it is enough to create a new directory in ``frontends/``, ``passes/`` or
+extending Yosys it is enough to create a new directory in :file:`frontends/`,
-``backends/`` with your sources and a ``Makefile.inc``. The Yosys kernel
+:file:`passes/` or :file:`backends/` with your sources and a
-automatically detects all commands linked with Yosys. So it is not needed to add
+:file:`Makefile.inc`. The Yosys kernel automatically detects all commands linked
-additional commands to a central list of commands.
+with Yosys. So it is not needed to add additional commands to a central list of
+commands.
 
 Good starting points for reading example source code to learn how to write
-passes are ``passes/opt/opt_dff.cc`` and ``passes/opt/opt_merge.cc``.
+passes are :file:`passes/opt/opt_dff.cc` and :file:`passes/opt/opt_merge.cc`.
 
 See the top-level README file for a quick Getting Started guide and build
 instructions. The Yosys build is based solely on Makefiles.

docs/source/getting_started/scripting_intro.rst

@@ -5,13 +5,13 @@ On the previous page we went through a synthesis script, running each command in
 the interactive Yosys shell.  On this page, we will be introducing the script
 file format and how you can make your own synthesis scripts.
 
-Yosys script files typically use the ``.ys`` extension and contain a set of
+Yosys script files typically use the :file:`.ys` extension and contain a set of
 commands for Yosys to run sequentially.  These commands are the same ones we
 were using on the previous page like :cmd:ref:`read_verilog` and
 :cmd:ref:`hierarchy`.  As with the interactive shell, each command consists of
 the command name, and an optional whitespace separated list of arguments.
-Commands are terminated with the newline character, or by a semicolon (;).
+Commands are terminated with the newline character, or by a semicolon (;). Empty
-Empty lines, and lines starting with the hash sign (#), are ignored.
+lines, and lines starting with the hash sign (#), are ignored.
 
 The synthesis starter script
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -21,7 +21,7 @@ The synthesis starter script
 
 All of the images and console output used in
 :doc:`/getting_started/example_synth` were generated by Yosys, using Yosys
-script files found in ``docs/source/code_examples/fifo``. If you haven't
+script files found in :file:`docs/source/code_examples/fifo`. If you haven't
 already, let's take a look at some of those script files now.
 
 .. literalinclude:: /code_examples/fifo/fifo.ys
@@ -29,7 +29,7 @@ already, let's take a look at some of those script files now.
    :lineno-match:
    :start-at: echo on
    :end-before: design -reset
-   :caption: A section of ``fifo.ys``, generating the images used for :ref:`addr_gen_example`
+   :caption: A section of :file:`fifo.ys`, generating the images used for :ref:`addr_gen_example`
    :name: fifo-ys
 
 The first command there, :yoscrypt:`echo on`, uses :cmd:ref:`echo` to enable
@@ -121,9 +121,9 @@ what the different symbols represent, see :ref:`interactive_show` and the
 .. _GraphViz: http://www.graphviz.org/
 .. _xdot: https://github.com/jrfonseca/xdot.py
 
-This is the first :yoscrypt:`show` command we called in ``fifo.ys``, :ref:`as we
+This is the first :yoscrypt:`show` command we called in :file:`fifo.ys`,
-saw above <fifo-ys>`.  If we look at the log output for this image we see the
+:ref:`as we saw above <fifo-ys>`.  If we look at the log output for this image
-following:
+we see the following:
 
 .. literalinclude:: /code_examples/fifo/fifo.out
    :language: doscon
@@ -131,14 +131,14 @@ following:
    :end-before: yosys> show
 
 Calling :cmd:ref:`show` with :yoscrypt:`-format dot` tells it we want to output
-a ``.dot`` file rather than opening it for display.  The :yoscrypt:`-prefix
+a :file:`.dot` file rather than opening it for display.  The :yoscrypt:`-prefix
-addr_gen_show` option indicates we want the file to be called `addr_gen_show.*`.
+addr_gen_show` option indicates we want the file to be called
-Remember, we do this in ``fifo.ys`` because we need to store the image for
+:file:`addr_gen_show.{*}`. Remember, we do this in :file:`fifo.ys` because we
-displaying in the documentation you're reading.  But if you just want to display
+need to store the image for displaying in the documentation you're reading.  But
-the images locally you can skip these two options.  The ``-format`` option
+if you just want to display the images locally you can skip these two options.
-internally calls the ``dot`` command line program from GraphViz to convert to
+The ``-format`` option internally calls the ``dot`` command line program from
-formats other than ``.dot``.  Check `GraphViz output docs`_ for more on
+GraphViz to convert to formats other than :file:`.dot`.  Check `GraphViz output
-available formats.
+docs`_ for more on available formats.
 
 .. _GraphViz output docs: https://graphviz.org/docs/outputs/
 

docs/source/using_yosys/more_scripting/interactive_investigation.rst

@@ -1,6 +1,8 @@
 Interactive design investigation
 --------------------------------
 
+.. todo:: interactive design opening text
+
 .. role:: yoscrypt(code)
    :language: yoscrypt
 
@@ -9,22 +11,24 @@ Interactive design investigation
 A look at the show command
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. TODO:: merge into :doc:`/getting_started/scripting_intro` show section
+
 This section explores the :cmd:ref:`show` command and explains the symbols used
-in the circuit diagrams generated by it.
+in the circuit diagrams generated by it. The code used is included in the Yosys
+code base under |code_examples/show|_.
+
+.. |code_examples/show| replace:: :file:`docs/source/code_examples/show`
+.. _code_examples/show: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/show
 
 A simple circuit
 ^^^^^^^^^^^^^^^^
 
 :ref:`example_v` below provides the Verilog code for a simple circuit which we
-will use to demonstrate the usage of :cmd:ref:`show` in a simple setting. The
+will use to demonstrate the usage of :cmd:ref:`show` in a simple setting.
-code used is included in the Yosys code base under
-`docs/source/code_examples/show`_.
-
-.. _docs/source/code_examples/show: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/show
 
 .. literalinclude:: /code_examples/show/example.v
    :language: Verilog
-   :caption: ``example.v``
+   :caption: :file:`example.v`
    :name: example_v
 
 The Yosys synthesis script we will be running is included as
@@ -36,7 +40,7 @@ synthesis.
 
 .. literalinclude:: /code_examples/show/example_show.ys
    :language: yoscrypt
-   :caption: ``example_show.ys``
+   :caption: :file:`example_show.ys`
    :name: example_ys
 
 This script, when executed, will show the design after each of the three
@@ -45,11 +49,11 @@ is shown.
 
 .. note::
 
-   The images uses in this document are generated from the ``example.ys`` file,
+   The images uses in this document are generated from the :file:`example.ys`
-   rather than ``example_show.ys``.  ``example.ys`` outputs the schematics as
+   file, rather than :file:`example_show.ys`.  :file:`example.ys` outputs the
-   ``.dot`` files rather than displaying them directly.  You can view these
+   schematics as :file:`.dot` files rather than displaying them directly.  You
-   images yourself by running ``yosys example.ys`` and then ``xdot
+   can view these images yourself by running :file:`yosys example.ys` and then
-   example_first.dot`` etc.
+   ``xdot example_first.dot`` etc.
 
 .. figure:: /_images/code_examples/show/example_first.*
    :class: width-helper
@@ -122,7 +126,7 @@ The code listing below shows a simple circuit which uses a lot of spliced signal
 accesses.
 
 .. literalinclude:: /code_examples/show/splice.v
-   :caption: ``docs/source/code_examples/show/splice.v``
+   :caption: :file:`splice.v`
    :name: splice_src
 
 Notice how the output for this circuit from the :cmd:ref:`show` command
@@ -199,15 +203,15 @@ library as Verilog file containing blackbox modules. There are two ways to load
 cell descriptions into Yosys: First the Verilog file for the cell library can be
 passed directly to the :cmd:ref:`show` command using the ``-lib <filename>``
 option. Secondly it is possible to load cell libraries into the design with the
-``read_verilog -lib <filename>`` command. The second method has the great
+:yoscrypt:`read_verilog -lib <filename>` command. The second method has the
-advantage that the library only needs to be loaded once and can then be used in
+great advantage that the library only needs to be loaded once and can then be
-all subsequent calls to the :cmd:ref:`show` command.
+used in all subsequent calls to the :cmd:ref:`show` command.
 
-In addition to that, :numref:`second_pitfall` was generated after ``splitnet
+In addition to that, :numref:`second_pitfall` was generated after
--ports`` was run on the design. This command splits all signal vectors into
+:yoscrypt:`splitnet -ports` was run on the design. This command splits all
-individual signal bits, which is often desirable when looking at gate-level
+signal vectors into individual signal bits, which is often desirable when
-circuits. The ``-ports`` option is required to also split module ports. Per
+looking at gate-level circuits. The ``-ports`` option is required to also split
-default the command only operates on interior signals.
+module ports. Per default the command only operates on interior signals.
 
 Miscellaneous notes
 ^^^^^^^^^^^^^^^^^^^
@@ -225,16 +229,16 @@ colors to the nets. The integer (> 0) is used as seed value for the random color
 assignments. Sometimes it is necessary it try some values to find an assignment
 of colors that looks good.
 
-The command ``help show`` prints a complete listing of all options supported by
+The command :yoscrypt:`help show` prints a complete listing of all options
-the :cmd:ref:`show` command.
+supported by the :cmd:ref:`show` command.
 
 Navigating the design
 ~~~~~~~~~~~~~~~~~~~~~
 
-Plotting circuit diagrams for entire modules in the design brings us
+Plotting circuit diagrams for entire modules in the design brings us only helps
-only helps in simple cases. For complex modules the generated circuit
+in simple cases. For complex modules the generated circuit diagrams are just
-diagrams are just stupidly big and are no help at all. In such cases one
+stupidly big and are no help at all. In such cases one first has to select the
-first has to select the relevant portions of the circuit.
+relevant portions of the circuit.
 
 In addition to *what* to display one also needs to carefully decide *when* to
 display it, with respect to the synthesis flow. In general it is a good idea to
@@ -244,10 +248,12 @@ reproduced. So if, for example, the internal state before calling the
 the coarse-grain version of the circuit before :cmd:ref:`techmap` than the
 gate-level circuit after :cmd:ref:`techmap`.
 
-.. Note:: It is generally recommended to verify the internal state of a
+.. Note:: 
-   design by writing it to a Verilog file using ``write_verilog -noexpr``
+
-   and using the simulation models from ``simlib.v`` and ``simcells.v`` 
+   It is generally recommended to verify the internal state of a design by
-   from the Yosys data directory (as printed by ``yosys-config --datdir``).
+   writing it to a Verilog file using :yoscrypt:`write_verilog -noexpr` and
+   using the simulation models from :file:`simlib.v` and :file:`simcells.v` from
+   the Yosys data directory (as printed by ``yosys-config --datdir``).
 
 Interactive navigation
 ^^^^^^^^^^^^^^^^^^^^^^
@@ -263,13 +269,14 @@ the synthesis script does not already narrow the selection). The command
 :cmd:ref:`ls` can now be used to create a list of all modules. The command
 :cmd:ref:`cd` can be used to switch to one of the modules (type ``cd ..`` to
 switch back). Now the :cmd:ref:`ls` command lists the objects within that
-module. This is demonstrated below using ``example.v`` from `A simple circuit`_:
+module. This is demonstrated below using :file:`example.v` from `A simple
+circuit`_:
 
 .. literalinclude:: /code_examples/show/example.out
    :language: doscon
    :start-at: yosys> ls
    :end-before: yosys [example]> dump
-   :caption: Output of :cmd:ref:`ls` and :cmd:ref:`cd` after running ``yosys example.v``
+   :caption: Output of :cmd:ref:`ls` and :cmd:ref:`cd` after running :file:`yosys example.v`
    :name: lscd
 
 When a module is selected using the :cmd:ref:`cd` command, all commands (with a
@@ -325,6 +332,12 @@ tools).
 - :doc:`/cmd/add` and :doc:`/cmd/delete` can be used to modify and reorganize a
   design dynamically.
   
+The code used is included in the Yosys code base under
+|code_examples/scrambler|_.
+
+.. |code_examples/scrambler| replace:: :file:`docs/source/code_examples/scrambler`
+.. _code_examples/scrambler: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/scrambler
+
 Changing design hierarchy
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -336,11 +349,11 @@ reorganizing a module in Yosys and checking the resulting circuit.
 
 .. literalinclude:: /code_examples/scrambler/scrambler.v
    :language: verilog
-   :caption: ``docs/source/code_examples/scrambler/scrambler.v``
+   :caption: :file:`scrambler.v`
 
 .. literalinclude:: /code_examples/scrambler/scrambler.ys
    :language: yoscrypt
-   :caption: ``docs/source/code_examples/scrambler/scrambler.ys``
+   :caption: :file:`scrambler.ys`
    :end-before: cd ..
 
 .. figure:: /_images/code_examples/scrambler/scrambler_p01.*
@@ -351,6 +364,8 @@ reorganizing a module in Yosys and checking the resulting circuit.
 
 Analyzing the resulting circuit with :doc:`/cmd/eval`:
 
+.. todo:: replace inline code
+
 .. code:: text
 
     > cd xorshift32
@@ -381,6 +396,8 @@ The following techmap map file replaces all positive-edge async reset flip-flops
 with positive-edge sync reset flip-flops. The code is taken from the example
 Yosys script for ASIC synthesis of the Amber ARMv2 CPU.
 
+.. todo:: replace inline code
+
 .. code:: verilog
 
     (* techmap_celltype = "$adff" *)
@@ -435,7 +452,7 @@ sections: ``outstage``, ``selstage``, and ``scramble``.
 
 .. literalinclude:: /code_examples/selections/submod.ys
    :language: yoscrypt
-   :caption: Using :cmd:ref:`submod` to break up the circuit from ``memdemo.v``
+   :caption: Using :cmd:ref:`submod` to break up the circuit from :file:`memdemo.v`
    :start-after: cd memdemo
    :end-before: cd ..
    :name: submod
@@ -467,6 +484,8 @@ The :cmd:ref:`eval` command can be used to evaluate combinatorial circuits. As
 an example, we will use the ``selstage`` subnet of ``memdemo`` which we found
 above and is shown in :numref:`selstage`.
 
+.. todo:: replace inline code
+
 ::
 
       yosys [selstage]> eval -set s2,s1 4'b1001 -set d 4'hc -show n2 -show n1
@@ -535,6 +554,8 @@ The :cmd:ref:`sat` command works very similar to the :cmd:ref:`eval` command.
 The main difference is that it is now also possible to set output values and
 find the corresponding input values. For Example:
 
+.. todo:: replace inline code
+
 ::
 
       yosys [selstage]> sat -show s1,s2,d -set s1 s2 -set n2,n1 4'b1001
@@ -569,7 +590,7 @@ circuit.)
 
 .. literalinclude:: /code_examples/primetest.v
    :language: verilog
-   :caption: ``primetest.v``, a simple miter circuit for testing if a number is
+   :caption: :file:`primetest.v`, a simple miter circuit for testing if a number is
              prime. But it has a problem.
    :name: primetest
 
@@ -577,8 +598,10 @@ circuit.)
 number test. If ``ok`` is 1 for all input values ``a`` and ``b`` for a given
 ``p``, then ``p`` is prime, or at least that is the idea.
 
+.. todo:: replace inline code
+
 .. code-block::
-   :caption: Experiments with the miter circuit from ``primetest.v``.
+   :caption: Experiments with the miter circuit from :file:`primetest.v`.
    :name: prime_shell
 
    yosys [primetest]> sat -prove ok 1 -set p 31
@@ -621,8 +644,10 @@ purpose of this document is to show off Yosys features) we can also simply force
 the upper 8 bits of ``a`` and ``b`` to zero for the :cmd:ref:`sat` call, as is
 done below.
 
+.. todo:: replace inline code
+
 .. code-block::
-   :caption: Miter circuit from ``primetest.v``, with the upper 8 bits of ``a``
+   :caption: Miter circuit from :file:`primetest.v`, with the upper 8 bits of ``a``
              and ``b`` constrained to prevent overflow.
    :name: prime_fixed
 
@@ -672,6 +697,8 @@ want to know which sequence of input values for ``d`` will cause the output y to
 produce the sequence 1, 2, 3 from any initial state. Let's use the following
 command:
 
+.. todo:: replace inline code?
+
 .. code-block:: yoscrypt
 
       sat -seq 6 -show y -show d -set-init-undef \
@@ -695,6 +722,8 @@ play the 1, 2, 3 sequence, starting with time step 4.
 
 This produces the following output:
 
+.. todo:: replace inline code
+
 .. code-block::
    :caption: Solving a sequential SAT problem in the ``memdemo`` module.
    :name: memdemo_sat

docs/source/using_yosys/more_scripting/model_checking.rst

@@ -25,23 +25,27 @@ Checking techmap
 
 .. todo:: add/expand supporting text
 
-Let's look at the following example:
+Let's take a look at an example included in the Yosys code base under
+|code_examples/synth_flow|_:
+
+.. |code_examples/synth_flow| replace:: :file:`docs/source/code_examples/synth_flow`
+.. _code_examples/synth_flow: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/synth_flow
 
 .. literalinclude:: /code_examples/synth_flow/techmap_01_map.v
    :language: verilog
-   :caption: ``docs/source/code_examples/synth_flow/techmap_01_map.v``
+   :caption: :file:`techmap_01_map.v`
 
 .. literalinclude:: /code_examples/synth_flow/techmap_01.v
    :language: verilog
-   :caption: ``docs/source/code_examples/synth_flow/techmap_01.v``
+   :caption: :file:`techmap_01.v`
 
 .. literalinclude:: /code_examples/synth_flow/techmap_01.ys
    :language: yoscrypt
-   :caption: ``docs/source/code_examples/synth_flow/techmap_01.ys``
+   :caption: :file:`techmap_01.ys`
 
 To see if it is correct we can use the following code:
 
-.. todo:: replace inline yosys script code
+.. todo:: replace inline code
 
 .. code:: yoscrypt
 
@@ -73,6 +77,12 @@ Result:
 AXI4 Stream Master
 ~~~~~~~~~~~~~~~~~~
 
+The code used in this section is included in the Yosys code base under
+|code_examples/axis|_.
+
+.. |code_examples/axis| replace:: :file:`docs/source/code_examples/axis`
+.. _code_examples/axis: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/axis
+
 The following AXI4 Stream Master has a bug. But the bug is not exposed if the
 slave keeps ``tready`` asserted all the time. (Something a test bench might do.)
 
@@ -83,24 +93,26 @@ values for ``tready`` that yield the incorrect behavior.
 
 .. literalinclude:: /code_examples/axis/axis_master.v
    :language: verilog
-   :caption: ``docs/source/code_examples/axis/axis_master.v``
+   :caption: :file:`axis_master.v`
 
 .. literalinclude:: /code_examples/axis/axis_test.v
    :language: verilog
-   :caption: ``docs/source/code_examples/axis/axis_test.v``
+   :caption: :file:`axis_test.v`
 
 .. literalinclude:: /code_examples/axis/axis_test.ys
    :language: yoscrypt
-   :caption: ``docs/source/code_examples/axis/test.ys``
+   :caption: :file:`test.ys`
 
-Result with unmodified ``axis_master.v``:
+Result with unmodified :file:`axis_master.v`:
+
+.. todo:: replace inline code
 
 .. code::
 
     Solving problem with 159344 variables and 442126 clauses..
     SAT proof finished - model found: FAIL!
 
-Result with fixed ``axis_master.v``:
+Result with fixed :file:`axis_master.v`:
 
 .. code::
 

docs/source/using_yosys/more_scripting/selections.rst

@@ -7,6 +7,8 @@ Selections
 The selection framework
 ~~~~~~~~~~~~~~~~~~~~~~~
 
+.. todo:: reduce overlap with :doc:`/getting_started/scripting_intro` select section
+
 The :cmd:ref:`select` command can be used to create a selection for subsequent
 commands. For example:
 
@@ -56,7 +58,7 @@ in synthesis scripts that are hand-tailored for a specific design.
 Module and design context
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Commands can be executed in *module/* or *design/* context. Until now all
+Commands can be executed in *module/* or *design/* context. Until now, all
 commands have been executed in design context. The :cmd:ref:`cd` command can be
 used to switch to module context.
 
@@ -83,9 +85,12 @@ Selecting by object property or type
 Special patterns can be used to select by object property or type. For example:
 
 - select all wires whose names start with ``reg_``: :yoscrypt:`select w:reg_*`
-- select all objects with the attribute ``foobar`` set: :yoscrypt:`select a:foobar`
+- select all objects with the attribute ``foobar`` set: :yoscrypt:`select
-- select all objects with the attribute ``foobar`` set to 42: :yoscrypt:`select a:foobar=42`
+  a:foobar`
-- select all modules with the attribute ``blabla`` set: :yoscrypt:`select A:blabla`
+- select all objects with the attribute ``foobar`` set to 42: :yoscrypt:`select
+  a:foobar=42`
+- select all modules with the attribute ``blabla`` set: :yoscrypt:`select
+  A:blabla`
 - select all $add cells from the module foo: :yoscrypt:`select foo/t:$add`
 
 A complete list of pattern expressions can be found in :doc:`/cmd/select`.
@@ -255,11 +260,11 @@ code is available in ``docs/source/code_examples/selections`` of the Yosys
 source repository.
 
 .. literalinclude:: /code_examples/selections/memdemo.v
-   :caption: ``memdemo.v``
+   :caption: :file:`memdemo.v`
    :name: memdemo_src
    :language: verilog
 
-The script ``memdemo.ys`` is used to generate the images included here. Let's
+The script :file:`memdemo.ys` is used to generate the images included here. Let's
 look at the first section:
 
 .. literalinclude:: /code_examples/selections/memdemo.ys
@@ -270,7 +275,7 @@ look at the first section:
 
 This loads :numref:`memdemo_src` and synthesizes the included module. Note that
 this code can be copied and run directly in a Yosys command line session,
-provided ``memdemo.v`` is in the same directory. We can now change to the
+provided :file:`memdemo.v` is in the same directory. We can now change to the
 ``memdemo`` module with ``cd memdemo``, and call :cmd:ref:`show` to see the
 diagram in :numref:`memdemo_00`.
 
@@ -397,15 +402,18 @@ Remember that select expressions can also be used directly as arguments to most
 commands. Some commands also accept a single select argument to some options. In
 those cases selection variables must be used to capture more complex selections.
 
-Example:
+Example code from |code_examples/selections|_:
+
+.. |code_examples/selections| replace:: :file:`docs/source/code_examples/selections`
+.. _code_examples/selections: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/selections
 
 .. literalinclude:: /code_examples/selections/select.v
    :language: verilog
-   :caption: ``docs/source/code_examples/selections/select.v``
+   :caption: :file:`select.v`
 
 .. literalinclude:: /code_examples/selections/select.ys
    :language: yoscrypt
-   :caption: ``docs/source/code_examples/selections/select.ys``
+   :caption: :file:`select.ys`
    :name: select_ys
 
 .. figure:: /_images/code_examples/selections/select.*

docs/source/using_yosys/synthesis/cell_libs.rst

@@ -7,16 +7,16 @@ Mapping to cell libraries
 While much of this documentation focuses on the use of Yosys with FPGAs, it is
 also possible to map to cell libraries which can be used in designing ASICs.
 This section will cover a brief `example project`_, available in the Yosys
-source code as ``docs/source/code_examples/intro/*``.  The project contains a
+source code under :file:`docs/source/code_examples/intro/`.  The project
-simple ASIC synthesis script (``counter.ys``), a digital design written in
+contains a simple ASIC synthesis script (:file:`counter.ys`), a digital design
-Verilog (``counter.v``), and a simple CMOS cell library (``mycells.lib``).  Many
+written in Verilog (:file:`counter.v`), and a simple CMOS cell library
-of the early steps here are already covered in more detail in the
+(:file:`mycells.lib`).  Many of the early steps here are already covered in more
-:doc:`/getting_started/example_synth` document.
+detail in the :doc:`/getting_started/example_synth` document.
 
 .. note::
 
-   The ``counter.ys`` script includes the commands used to generate the images
+   The :file:`counter.ys` script includes the commands used to generate the
-   in this document.  Code snippets in this document skip these commands;
+   images in this document.  Code snippets in this document skip these commands;
    including line numbers to allow the reader to follow along with the source.
    
    To learn more about these commands, check out :ref:`interactive_show`.
@@ -32,7 +32,7 @@ First, let's quickly look at the design:
    :language: Verilog
    :linenos:
    :name: counter-v
-   :caption: ``counter.v``
+   :caption: :file:`counter.v`
 
 This is a simple counter with reset and enable.  If the reset signal, ``rst``,
 is high then the counter will reset to 0.  Otherwise, if the enable signal,
@@ -46,7 +46,7 @@ Loading the design
    :language: yoscrypt
    :lines: 1-3
    :lineno-match:
-   :caption: ``counter.ys`` - read design
+   :caption: :file:`counter.ys` - read design
 
 Our circuit now looks like this:
 
@@ -63,7 +63,7 @@ Coarse-grain representation
    :language: yoscrypt
    :lines: 7-10
    :lineno-match:
-   :caption: ``counter.ys`` - the high-level stuff
+   :caption: :file:`counter.ys` - the high-level stuff
 
 .. figure:: /_images/code_examples/intro/counter_01.*
    :class: width-helper
@@ -77,7 +77,7 @@ Logic gate mapping
    :language: yoscrypt
    :lines: 14-15
    :lineno-match:
-   :caption: ``counter.ys`` - mapping to internal cell library
+   :caption: :file:`counter.ys` - mapping to internal cell library
 
 .. figure:: /_images/code_examples/intro/counter_02.*
    :class: width-helper
@@ -94,7 +94,7 @@ our internal cell library will be mapped to:
    :language: Liberty
    :linenos:
    :name: mycells-lib
-   :caption: ``mycells.lib``
+   :caption: :file:`mycells.lib`
 
 Recall that the Yosys built-in logic gate types are ``$_NOT_``, ``$_AND_``,
 ``$_OR_``, ``$_XOR_``, and ``$_MUX_`` with an assortment of dff memory types.
@@ -106,7 +106,7 @@ Recall that the Yosys built-in logic gate types are ``$_NOT_``, ``$_AND_``,
    :language: yoscrypt
    :lines: 20-27
    :lineno-match:
-   :caption: ``counter.ys`` - mapping to hardware
+   :caption: :file:`counter.ys` - mapping to hardware
 
 The final version of our ``counter`` module looks like this:
 
@@ -122,4 +122,4 @@ which can then be loaded into another tool:
    :language: yoscrypt
    :lines: 30-31
    :lineno-match:
-   :caption: ``counter.ys`` - write synthesized design
+   :caption: :file:`counter.ys` - write synthesized design

docs/source/using_yosys/synthesis/extract.rst

@@ -12,7 +12,11 @@ The extract pass
 .. todo:: add/expand supporting text, also mention custom pattern matching and
    pmgen
 
-Example code can be found in ``docs/source/code_examples/macc/``.
+Example code can be found in |code_examples/macc|_.
+
+.. |code_examples/macc| replace:: :file:`docs/source/code_examples/macc`
+.. _code_examples/macc: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/macc
+
 
 .. literalinclude:: /code_examples/macc/macc_simple_test.ys
     :language: yoscrypt
@@ -34,15 +38,15 @@ Example code can be found in ``docs/source/code_examples/macc/``.
 
 .. literalinclude:: /code_examples/macc/macc_simple_test.v
    :language: verilog
-   :caption: ``macc_simple_test.v``
+   :caption: :file:`macc_simple_test.v`
 
 .. literalinclude:: /code_examples/macc/macc_simple_xmap.v
    :language: verilog
-   :caption: ``macc_simple_xmap.v``
+   :caption: :file:`macc_simple_xmap.v`
 
 .. literalinclude:: /code_examples/macc/macc_simple_test_01.v
    :language: verilog
-   :caption: ``macc_simple_test_01.v``
+   :caption: :file:`macc_simple_test_01.v`
 
 .. figure:: /_images/code_examples/macc/macc_simple_test_01a.*
     :class: width-helper
@@ -52,7 +56,7 @@ Example code can be found in ``docs/source/code_examples/macc/``.
 
 .. literalinclude:: /code_examples/macc/macc_simple_test_02.v
    :language: verilog
-   :caption: ``macc_simple_test_02.v``
+   :caption: :file:`macc_simple_test_02.v`
 
 .. figure:: /_images/code_examples/macc/macc_simple_test_02a.*
     :class: width-helper
@@ -90,10 +94,9 @@ Example: DSP48_MACC
 
 This section details an example that shows how to map MACC operations of
 arbitrary size to MACC cells with a 18x25-bit multiplier and a 48-bit adder
-(such as the Xilinx DSP48 cells).  Source code can be found in
+(such as the Xilinx DSP48 cells).
-``docs/source/code_examples/macc/``.
 
-Preconditioning: ``macc_xilinx_swap_map.v``
+Preconditioning: :file:`macc_xilinx_swap_map.v`
 
 Make sure ``A`` is the smaller port on all multipliers
 
@@ -101,49 +104,49 @@ Make sure ``A`` is the smaller port on all multipliers
 
 .. literalinclude:: /code_examples/macc/macc_xilinx_swap_map.v
    :language: verilog
-   :caption: ``macc_xilinx_swap_map.v``
+   :caption: :file:`macc_xilinx_swap_map.v`
 
-Wrapping multipliers: ``macc_xilinx_wrap_map.v``
+Wrapping multipliers: :file:`macc_xilinx_wrap_map.v`
 
 .. literalinclude:: /code_examples/macc/macc_xilinx_wrap_map.v
    :language: verilog
    :lines: 1-46
-   :caption: ``macc_xilinx_wrap_map.v``
+   :caption: :file:`macc_xilinx_wrap_map.v`
 
-Wrapping adders: ``macc_xilinx_wrap_map.v``
+Wrapping adders: :file:`macc_xilinx_wrap_map.v`
 
 .. literalinclude:: /code_examples/macc/macc_xilinx_wrap_map.v
    :language: verilog
    :lines: 48-89
-   :caption: ``macc_xilinx_wrap_map.v``
+   :caption: :file:`macc_xilinx_wrap_map.v`
 
-Extract: ``macc_xilinx_xmap.v``
+Extract: :file:`macc_xilinx_xmap.v`
 
 .. literalinclude:: /code_examples/macc/macc_xilinx_xmap.v
    :language: verilog
-   :caption: ``macc_xilinx_xmap.v``
+   :caption: :file:`macc_xilinx_xmap.v`
 
 ... 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``
+Unwrapping multipliers: :file:`macc_xilinx_unwrap_map.v`
 
 .. literalinclude:: /code_examples/macc/macc_xilinx_unwrap_map.v
    :language: verilog
    :lines: 1-30
-   :caption: ``$__mul_wrapper`` module in ``macc_xilinx_unwrap_map.v``
+   :caption: ``$__mul_wrapper`` module in :file:`macc_xilinx_unwrap_map.v`
 
-Unwrapping adders: ``macc_xilinx_unwrap_map.v``
+Unwrapping adders: :file:`macc_xilinx_unwrap_map.v`
 
 .. literalinclude:: /code_examples/macc/macc_xilinx_unwrap_map.v
    :language: verilog
    :lines: 32-61
-   :caption: ``$__add_wrapper`` module in ``macc_xilinx_unwrap_map.v``
+   :caption: ``$__add_wrapper`` module in :file:`macc_xilinx_unwrap_map.v`
 
 .. literalinclude:: /code_examples/macc/macc_xilinx_test.v
    :language: verilog
    :lines: 1-6
-   :caption: ``test1`` of ``macc_xilinx_test.v``
+   :caption: ``test1`` of :file:`macc_xilinx_test.v`
 
 .. figure:: /_images/code_examples/macc/macc_xilinx_test1a.*
     :class: width-helper
@@ -154,7 +157,7 @@ Unwrapping adders: ``macc_xilinx_unwrap_map.v``
 .. literalinclude:: /code_examples/macc/macc_xilinx_test.v
    :language: verilog
    :lines: 8-13
-   :caption: ``test2`` of ``macc_xilinx_test.v``
+   :caption: ``test2`` of :file:`macc_xilinx_test.v`
 
 .. figure:: /_images/code_examples/macc/macc_xilinx_test2a.*
     :class: width-helper

docs/source/using_yosys/synthesis/memory.rst

@@ -33,27 +33,32 @@ Example
 
 .. todo:: describe ``memory`` images
 
+|code_examples/synth_flow|_.
+
+.. |code_examples/synth_flow| replace:: :file:`docs/source/code_examples/synth_flow`
+.. _code_examples/synth_flow: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/synth_flow
+
 .. figure:: /_images/code_examples/synth_flow/memory_01.*
    :class: width-helper
 
 .. literalinclude:: /code_examples/synth_flow/memory_01.ys
    :language: yoscrypt
-   :caption: ``docs/source/code_examples/synth_flow/memory_01.ys``
+   :caption: :file:`memory_01.ys`
 
 .. literalinclude:: /code_examples/synth_flow/memory_01.v
    :language: verilog
-   :caption: ``docs/source/code_examples/synth_flow/memory_01.v``
+   :caption: :file:`memory_01.v`
 
 .. figure:: /_images/code_examples/synth_flow/memory_02.*
    :class: width-helper
 
 .. literalinclude:: /code_examples/synth_flow/memory_02.v
    :language: verilog
-   :caption: ``docs/source/code_examples/synth_flow/memory_02.v``
+   :caption: :file:`memory_02.v`
 
 .. literalinclude:: /code_examples/synth_flow/memory_02.ys
    :language: yoscrypt
-   :caption: ``docs/source/code_examples/synth_flow/memory_02.ys``
+   :caption: :file:`memory_02.ys`
 
 .. _memory_map:
 
@@ -71,7 +76,7 @@ For example:
     memory_map
 
 :cmd:ref:`memory_libmap` attempts to convert memory cells (``$mem_v2`` etc) into
-hardware supported memory using a provided library (``my_memory_map.txt`` in the
+hardware supported memory using a provided library (:file:`my_memory_map.txt` in the
 example above).  Where necessary, emulation logic is added to ensure functional
 equivalence before and after this conversion. :yoscrypt:`techmap -map
 my_memory_map.v` then uses :cmd:ref:`techmap` to map to hardware primitives. Any

docs/source/using_yosys/synthesis/proc.rst

@@ -28,13 +28,18 @@ Example
 
 .. todo:: describe ``proc`` images
 
+|code_examples/synth_flow|_.
+
+.. |code_examples/synth_flow| replace:: :file:`docs/source/code_examples/synth_flow`
+.. _code_examples/synth_flow: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/synth_flow
+
 .. literalinclude:: /code_examples/synth_flow/proc_01.v
    :language: verilog
-   :caption: ``docs/source/code_examples/synth_flow/proc_01.v``
+   :caption: :file:`proc_01.v`
 
 .. literalinclude:: /code_examples/synth_flow/proc_01.ys
    :language: yoscrypt
-   :caption: ``docs/source/code_examples/synth_flow/proc_01.ys``
+   :caption: :file:`proc_01.ys`
 
 .. figure:: /_images/code_examples/synth_flow/proc_01.*
    :class: width-helper
@@ -44,19 +49,19 @@ Example
 
 .. literalinclude:: /code_examples/synth_flow/proc_02.v
    :language: verilog
-   :caption: ``docs/source/code_examples/synth_flow/proc_02.v``
+   :caption: :file:`proc_02.v`
 
 .. literalinclude:: /code_examples/synth_flow/proc_02.ys
    :language: yoscrypt
-   :caption: ``docs/source/code_examples/synth_flow/proc_02.ys``
+   :caption: :file:`proc_02.ys`
 
 .. figure:: /_images/code_examples/synth_flow/proc_03.*
    :class: width-helper
 
 .. literalinclude:: /code_examples/synth_flow/proc_03.ys
    :language: yoscrypt
-   :caption: ``docs/source/code_examples/synth_flow/proc_03.ys``
+   :caption: :file:`proc_03.ys`
 
 .. literalinclude:: /code_examples/synth_flow/proc_03.v
    :language: verilog
-   :caption: ``docs/source/code_examples/synth_flow/proc_03.v``
+   :caption: :file:`proc_03.v`

docs/source/yosys_internals/extending_yosys/abc_flow.rst

@@ -22,7 +22,7 @@ guide to the syntax:
 
 By convention, all delays in ``specify`` blocks are in integer picoseconds.
 Files containing ``specify`` blocks should be read with the ``-specify`` option
-to ``read_verilog`` so that they aren't skipped.
+to :cmd:ref:`read_verilog` so that they aren't skipped.
 
 LUTs
 ^^^^
@@ -41,9 +41,9 @@ DFFs
 
 DFFs should be annotated with an ``(* abc9_flop *)`` attribute, however ABC9 has
 some specific requirements for this to be valid: - the DFF must initialise to
-zero (consider using ``dfflegalize`` to ensure this). - the DFF cannot have any
+zero (consider using :cmd:ref:`dfflegalize` to ensure this). - the DFF cannot
-asynchronous resets/sets (see the simplification idiom and the Boxes section for
+have any asynchronous resets/sets (see the simplification idiom and the Boxes
-what to do here).
+section for what to do here).
 
 It is worth noting that in pure ``abc9`` mode, only the setup and arrival times
 are passed to ABC9 (specifically, they are modelled as buffers with the given
@@ -59,7 +59,7 @@ mapped back to the original flop. This is used in :cmd:ref:`synth_intel_alm` and
 :cmd:ref:`synth_quicklogic` for the PolarPro3.
 
 DFFs are usually specified to have setup constraints against the clock on the
-input signals, and an arrival time for the Q output.
+input signals, and an arrival time for the ``Q`` output.
 
 Boxes
 ^^^^^

docs/source/yosys_internals/extending_yosys/extensions.rst

@@ -6,7 +6,7 @@ Writing extensions
 
 .. todo:: check text is coherent
 
-.. todo:: update to use ``/code_examples/extensions/test*.log``
+.. todo:: update to use :file:`/code_examples/extensions/test*.log`
 
 This chapter contains some bits and pieces of information about programming
 yosys extensions. Don't be afraid to ask questions on the YosysHQ Slack.
@@ -21,7 +21,11 @@ Quick guide
 -----------
 
 Code examples from this section are included in the
-``docs/code_examples/extensions/`` directory of the Yosys source code.
+|code_examples/extensions|_ directory of the Yosys source code.
+
+.. |code_examples/extensions| replace:: :file:`docs/source/code_examples/extensions`
+.. _code_examples/extensions: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/extensions
+
 
 Program components and data formats
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -31,7 +35,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 :cmd:ref:`proc` and :cmd:ref:`memory` (or ``memory -nomap``):
+commands :cmd:ref:`proc` and :cmd:ref:`memory` (or :yoscrypt:`memory -nomap`):
 
 .. figure:: /_images/internals/simplified_rtlil.*
     :class: width-helper
@@ -41,6 +45,8 @@ commands :cmd:ref:`proc` and :cmd:ref:`memory` (or ``memory -nomap``):
 
 It is possible to only work on this simpler version:
 
+.. todo:: consider replacing inline code
+
 .. code:: c++
 
     for (RTLIL::Module *module : design->selected_modules() {
@@ -66,10 +72,10 @@ with, and lists off the current design's modules.
 .. literalinclude:: /code_examples/extensions/my_cmd.cc
    :language: c++
    :lines: 1, 4, 6, 7-20
-   :caption: Example command :yoscrypt:`my_cmd` from ``my_cmd.cc``
+   :caption: Example command :yoscrypt:`my_cmd` from :file:`my_cmd.cc`
    
 Note that we are making a global instance of a class derived from
-``Yosys::Pass``, which we get by including ``kernel/yosys.h``.
+``Yosys::Pass``, which we get by including :file:`kernel/yosys.h`.
 
 Compiling to a plugin
 ~~~~~~~~~~~~~~~~~~~~~
@@ -80,6 +86,8 @@ to create plugins.
 
 The following command compiles our example :yoscrypt:`my_cmd` to a Yosys plugin:
 
+.. todo:: replace inline code
+
 .. code:: shell
 
    yosys-config --exec --cxx --cxxflags --ldflags \
@@ -120,7 +128,7 @@ We'll do the same as before and format it as a a ``Yosys::Pass``.
 .. literalinclude:: /code_examples/extensions/my_cmd.cc
    :language: c++
    :lines: 23-47
-   :caption: :yoscrypt:`test1` - creating the absval module, from ``my_cmd.cc``
+   :caption: :yoscrypt:`test1` - creating the absval module, from :file:`my_cmd.cc`
 
 .. code:: shell-session
 
@@ -160,7 +168,7 @@ Consider the following module:
 
 .. literalinclude:: /code_examples/extensions/sigmap_test.v
    :language: Verilog
-   :caption: sigmap_test.v
+   :caption: :file:`sigmap_test.v`
 
 In this case ``a``, ``x``, and ``y`` are all different names for the same
 signal. However:
@@ -204,7 +212,10 @@ Use ``log_id()`` to create a C-string for an ``RTLIL::IdString``:
 
     log("Name of this module: %s\n", log_id(module->name));
 
-Use ``log_header()`` and ``log_push()``/``log_pop()`` to structure log messages:
+Use ``log_header()`` and ``log_push()``/\ ``log_pop()`` to structure log
+messages:
+
+.. todo:: replace inline code
 
 .. code:: C++
 
@@ -219,6 +230,8 @@ Error handling
 
 Use ``log_error()`` to report a non-recoverable error:
 
+.. todo:: replace inline code
+
 .. code:: C++
 
     if (design->modules.count(module->name) != 0)
@@ -238,20 +251,22 @@ The "stubnets" example module
 ------------------------------
 
 The following is the complete code of the "stubnets" example module. It is
-included in the Yosys source distribution as
+included in the Yosys source distribution under |code_examples/stubnets|_.
-``docs/source/code_examples/stubnets/stubnets.cc``.
+
+.. |code_examples/stubnets| replace:: :file:`docs/source/code_examples/stubnets`
+.. _code_examples/stubnets: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/stubnets
 
 .. literalinclude:: /code_examples/stubnets/stubnets.cc
     :language: c++
     :linenos:
-    :caption: docs/source/code_examples/stubnets/stubnets.cc
+    :caption: :file:`stubnets.cc`
 
 .. literalinclude:: /code_examples/stubnets/Makefile
     :language: makefile
     :linenos:
-    :caption: docs/source/code_examples/stubnets/Makefile
+    :caption: :file:`Makefile`
 
 .. literalinclude:: /code_examples/stubnets/test.v
     :language: verilog
     :linenos:
-    :caption: docs/source/code_examples/stubnets/test.v
+    :caption: :file:`test.v`

docs/source/yosys_internals/flow/index.rst

@@ -1,7 +1,6 @@
 Internal flow
 =============
 
-
 A (usually short) synthesis script controls Yosys.
 
 These scripts contain three types of commands:

docs/source/yosys_internals/flow/verilog_frontend.rst

@@ -23,8 +23,8 @@ representation that closely resembles the structure of the original Verilog
 code. The Verilog frontend consists of three components, the Preprocessor, the
 Lexer and the Parser.
 
-The source code to the Verilog frontend can be found in ``frontends/verilog/``
+The source code to the Verilog frontend can be found in
-in the Yosys source tree.
+:file:`frontends/verilog/` in the Yosys source tree.
 
 The Verilog preprocessor
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -37,20 +37,19 @@ It is implemented as a C++ function that is passed a file descriptor as input
 and returns the pre-processed Verilog code as a ``std::string``.
 
 The source code to the Verilog Preprocessor can be found in
-``frontends/verilog/preproc.cc`` in the Yosys source tree.
+:file:`frontends/verilog/preproc.cc` in the Yosys source tree.
 
 The Verilog lexer
 ~~~~~~~~~~~~~~~~~
 
-The Verilog Lexer is written using the lexer generator flex. Its source code
+The Verilog Lexer is written using the lexer generator flex. Its source code can
-can be found in ``frontends/verilog/verilog_lexer.l`` in the Yosys source tree.
+be found in :file:`frontends/verilog/verilog_lexer.l` in the Yosys source tree.
 The lexer does little more than identifying all keywords and literals recognised
 by the Yosys Verilog frontend.
 
-The lexer keeps track of the current location in the Verilog source code
+The lexer keeps track of the current location in the Verilog source code using
-using some global variables. These variables are used by the constructor
+some global variables. These variables are used by the constructor of AST nodes
-of AST nodes to annotate each node with the source code location it
+to annotate each node with the source code location it originated from.
-originated from.
 
 Finally the lexer identifies and handles special comments such as "``// synopsys
 translate_off``" and "``// synopsys full_case``". (It is recommended to use
@@ -62,10 +61,11 @@ The Verilog parser
 ~~~~~~~~~~~~~~~~~~
 
 The Verilog Parser is written using the parser generator bison. Its source code
-can be found in ``frontends/verilog/verilog_parser.y`` in the Yosys source tree.
+can be found in :file:`frontends/verilog/verilog_parser.y` in the Yosys source
+tree.
 
 It generates an AST using the ``AST::AstNode`` data structure defined in
-``frontends/ast/ast.h``. An ``AST::AstNode`` object has the following
+:file:`frontends/ast/ast.h`. An ``AST::AstNode`` object has the following
 properties:
 
 .. list-table:: AST node types with their corresponding Verilog constructs.
@@ -77,7 +77,8 @@ properties:
     * - AST_NONE
       - This Node type should never be used.
     * - AST_DESIGN
-      - This node type is used for the top node of the AST tree. It has no corresponding Verilog construct.
+      - This node type is used for the top node of the AST tree. It has no
+        corresponding Verilog construct.
     * - AST_MODULE, AST_TASK, AST_FUNCTION
       - ``module``, ``task`` and ``function``
     * - AST_WIRE
@@ -99,9 +100,11 @@ properties:
     * - AST_CELLTYPE
       - The type of cell in cell instantiation
     * - AST_IDENTIFIER
-      - An Identifier (signal name in expression or cell/task/etc. name in other contexts)
+      - An Identifier (signal name in expression or cell/task/etc. name in other
+        contexts)
     * - AST_PREFIX
-      - Construct an identifier in the form <prefix>[<index>].<suffix> (used only in advanced generate constructs)
+      - Construct an identifier in the form <prefix>[<index>].<suffix> (used
+        only in advanced generate constructs)
     * - AST_FCALL, AST_TCALL
       - Call to function or task
     * - AST_TO_SIGNED, AST_TO_UNSIGNED
@@ -113,7 +116,8 @@ properties:
     * - AST_REDUCE_AND, AST_REDUCE_OR, AST_REDUCE_XOR, AST_REDUCE_XNOR
       - The unary reduction operators ``~``, ``&``, ``|``, ``^`` and ``~^``
     * - AST_REDUCE_BOOL
-      - Conversion from multi-bit value to boolean value (equivalent to AST_REDUCE_OR)
+      - Conversion from multi-bit value to boolean value (equivalent to
+        AST_REDUCE_OR)
     * - AST_SHIFT_LEFT, AST_SHIFT_RIGHT, AST_SHIFT_SLEFT, AST_SHIFT_SRIGHT
       - The shift operators ``<<``, ``>>``, ``<<<`` and ``>>>``
     * - AST_LT, AST_LE, AST_EQ, AST_NE, AST_GE, AST_GT
@@ -127,7 +131,8 @@ properties:
     * - AST_TERNARY
       - The ternary ``?:``-operator
     * - AST_MEMRD AST_MEMWR
-      - Read and write memories. These nodes are generated by the AST simplifier for writes/reads to/from Verilog arrays.
+      - Read and write memories. These nodes are generated by the AST simplifier
+        for writes/reads to/from Verilog arrays.
     * - AST_ASSIGN
       - An ``assign`` statement
     * - AST_CELL
@@ -139,13 +144,16 @@ properties:
     * - AST_BLOCK
       - A ``begin``-``end``-block
     * - AST_ASSIGN_EQ. AST_ASSIGN_LE
-      - Blocking (``=``) and nonblocking (``<=``) assignments within an ``always``- or ``initial``-block
+      - Blocking (``=``) and nonblocking (``<=``) assignments within an
+        ``always``- or ``initial``-block
     * - AST_CASE. AST_COND, AST_DEFAULT
-      - The ``case`` (``if``) statements, conditions within a case and the default case respectively
+      - The ``case`` (``if``) statements, conditions within a case and the
+        default case respectively
     * - AST_FOR
       - A ``for``-loop with an ``always``- or ``initial``-block
     * - AST_GENVAR, AST_GENBLOCK, AST_GENFOR, AST_GENIF
-      - The ``genvar`` and ``generate`` keywords and ``for`` and ``if`` within a generate block.
+      - The ``genvar`` and ``generate`` keywords and ``for`` and ``if`` within a
+        generate block.
     * - AST_POSEDGE, AST_NEGEDGE, AST_EDGE
       - Event conditions for ``always`` blocks.
 
@@ -295,7 +303,7 @@ correct intermediate values whenever one of the previously assigned signals is
 used in an expression.
 
 Unfortunately the generation of a correct
-``RTLIL::CaseRule``/``RTLIL::SwitchRule`` tree for behavioural code is a
+``RTLIL::CaseRule``/\ ``RTLIL::SwitchRule`` tree for behavioural code is a
 non-trivial task. The AST frontend solves the problem using the approach
 described on the following pages. The following example illustrates what the
 algorithm is supposed to do. Consider the following Verilog code:
@@ -371,7 +379,7 @@ expressions after the initial assignment. The signal ``out2`` is assigned using
 nonblocking assignments and therefore is not substituted on the right-hand-side
 expressions.
 
-The ``RTLIL::CaseRule``/``RTLIL::SwitchRule`` tree must be interpreted the
+The ``RTLIL::CaseRule``/\ ``RTLIL::SwitchRule`` tree must be interpreted the
 following way:
 
 -  On each case level (the body of the process is the root case), first the
@@ -388,7 +396,7 @@ following way:
    objects within a ``RTLIL::CaseRule`` is preserved with respect to the
    original AST and Verilog code.
 
--  The whole ``RTLIL::CaseRule``/``RTLIL::SwitchRule`` tree describes an
+-  The whole ``RTLIL::CaseRule``/\ ``RTLIL::SwitchRule`` tree describes an
    asynchronous circuit. I.e. the decision tree formed by the switches can be
    seen independently for each assigned signal. Whenever one assigned signal
    changes, all signals that depend on the changed signals are to be updated.
@@ -403,11 +411,11 @@ the original Verilog code has been translated into the synchronization type
 (posedge) and signal (``\clock``) for the ``RTLIL::SyncRule`` object. In the
 case of this simple example the ``RTLIL::SyncRule`` object is later simply
 transformed into a set of d-type flip-flops and the
-``RTLIL::CaseRule``/``RTLIL::SwitchRule`` tree to a decision tree using
+``RTLIL::CaseRule``/\ ``RTLIL::SwitchRule`` tree to a decision tree using
 multiplexers.
 
 In more complex examples (e.g. asynchronous resets) the part of the
-``RTLIL::CaseRule``/``RTLIL::SwitchRule`` tree that describes the asynchronous
+``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_arst`` pass.
 
@@ -583,7 +591,7 @@ Note how this step always overrides a previous assignment to the old temporary
 variable. Other than nonblocking assignments, the old assignment could still
 have an effect somewhere in the design, as there have been calls to
 ``AST::AstNode::genRTLIL()`` with a
-``subst_rvalue_from``/ ``subst_rvalue_to``-tuple that contained the
+``subst_rvalue_from``/\ ``subst_rvalue_to``-tuple that contained the
 right-hand-side of the old assignment.
 
 The proc pass
@@ -609,17 +617,17 @@ from a behavioural model to an RTL representation is performed by the
      and the top-level ``RTLIL::SwitchRule`` has been removed.
 
 -  | :cmd:ref:`proc_mux` 
-   | This pass converts the ``RTLIL::CaseRule``/ ``RTLIL::SwitchRule``-tree to a
+   | 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.
 
 -  | :cmd:ref:`proc_dff`
-   | This pass replaces the ``RTLIL::SyncRule`` s to d-type flip-flops (with
+   | This pass replaces the ``RTLIL::SyncRule``\ s to d-type flip-flops (with
      asynchronous resets if necessary).
 
 -  | :cmd:ref:`proc_dff`
-   | This pass replaces the ``RTLIL::MemWriteAction`` s with ``$memwr`` cells.
+   | This pass replaces the ``RTLIL::MemWriteAction``\ s with ``$memwr`` cells.
 
 -  | :cmd:ref:`proc_clean`
    | A final call to :cmd:ref:`proc_clean` removes the now empty
@@ -636,18 +644,13 @@ Second it improves flexibility. This scheme can easily be extended to support
 other types of storage-elements, such as sr-latches or d-latches, without having
 to extend the actual Verilog frontend.
 
-Synthesizing Verilog arrays
+.. todo:: Synthesizing Verilog arrays
----------------------------
-
-.. todo:: 
 
   Add some information on the generation of ``$memrd`` and ``$memwr`` cells and
   how they are processed in the memory pass.
 
-Synthesizing parametric designs
--------------------------------
 
-.. todo::
+.. todo:: Synthesizing parametric designs
 
   Add some information on the ``RTLIL::Module::derive()`` method and how it is
   used to synthesize parametric modules via the hierarchy pass.

docs/source/yosys_internals/formats/cell_library.rst

@@ -9,8 +9,11 @@ Internal cell library
 .. todo:: less academic, also check formatting consistency
 
 Most of the passes in Yosys operate on netlists, i.e. they only care about the
-RTLIL::Wire and RTLIL::Cell objects in an RTLIL::Module. This chapter discusses
+``RTLIL::Wire`` and ``RTLIL::Cell`` objects in an ``RTLIL::Module``. This
-the cell types used by Yosys to represent a behavioural design internally.
+chapter discusses the cell types used by Yosys to represent a behavioural design
+internally.
+
+.. TODO:: is this chapter split preserved
 
 This chapter is split in two parts. In the first part the internal RTL cells are
 covered. These cells are used to represent the design on a coarse grain level.
@@ -33,7 +36,7 @@ parameters in sync with the size of the signals connected to the inputs and
 outputs.
 
 Simulation models for the RTL cells can be found in the file
-``techlibs/common/simlib.v`` in the Yosys source tree.
+:file:`techlibs/common/simlib.v` in the Yosys source tree.
 
 Unary operators
 ~~~~~~~~~~~~~~~
@@ -42,8 +45,8 @@ All unary RTL cells have one input port ``\A`` and one output port ``\Y``. They
 also have the following parameters:
 
 ``\A_SIGNED``
-	Set to a non-zero value if the input ``\A`` is signed and therefore
+	Set to a non-zero value if the input ``\A`` is signed and therefore should be
-	should be sign-extended when needed.
+	sign-extended when needed.
 
 ``\A_WIDTH``
 	The width of the input port ``\A``.
@@ -110,7 +113,7 @@ All binary RTL cells have two input ports ``\A`` and ``\B`` and one output port
 	:name: tab:CellLib_binary
 
 	======================= ============= ======================= =========
-	Verilog 	        Cell Type     Verilog                 Cell Type
+	Verilog                 Cell Type     Verilog                 Cell Type
 	======================= ============= ======================= =========
 	:verilog:`Y = A  & B`   $and          :verilog:`Y = A <  B`   $lt
 	:verilog:`Y = A  | B`   $or           :verilog:`Y = A <= B`   $le
@@ -124,7 +127,7 @@ All binary RTL cells have two input ports ``\A`` and ``\B`` and one output port
 	:verilog:`Y = A || B`   $logic_or     :verilog:`Y = A  / B`   $div
 	:verilog:`Y = A === B`  $eqx          :verilog:`Y = A  % B`   $mod
 	:verilog:`Y = A !== B`  $nex          ``N/A``                 $divfloor
-	:verilog:`Y = A ** B`   $pow          ``N/A``                 $modfoor
+	:verilog:`Y = A ** B`   $pow          ``N/A``                 $modfloor
 	======================= ============= ======================= =========
 
 The ``$shl`` and ``$shr`` cells implement logical shifts, whereas the ``$sshl``
@@ -141,7 +144,7 @@ positions are filled with undef (x) bits, and corresponds to the Verilog indexed
 part-select expression.
 
 For the binary cells that output a logical value (``$logic_and``, ``$logic_or``,
-``$eqx``, ``$nex``, ``$lt``, ``$le``, ``$eq``, ``$ne``, ``$ge``, ``$gt)``, when
+``$eqx``, ``$nex``, ``$lt``, ``$le``, ``$eq``, ``$ne``, ``$ge``, ``$gt``), when
 the ``\Y_WIDTH`` parameter is greater than 1, the output is zero-extended, and
 only the least significant bit varies.
 
@@ -334,11 +337,11 @@ cells.
 Memories
 ~~~~~~~~
 
-Memories are either represented using RTLIL::Memory objects, ``$memrd_v2``,
+Memories are either represented using ``RTLIL::Memory`` objects, ``$memrd_v2``,
 ``$memwr_v2``, and ``$meminit_v2`` cells, or by ``$mem_v2`` cells alone.
 
-In the first alternative the RTLIL::Memory objects hold the general metadata for
+In the first alternative the ``RTLIL::Memory`` objects hold the general metadata
-the memory (bit width, size in number of words, etc.) and for each port a
+for the memory (bit width, size in number of words, etc.) and for each port a
 ``$memrd_v2`` (read port) or ``$memwr_v2`` (write port) cell is created. Having
 individual cells for read and write ports has the advantage that they can be
 consolidated using resource sharing passes. In some cases this drastically
@@ -353,7 +356,7 @@ address input ``\ADDR``, a data output ``\DATA``, an asynchronous reset input
 parameters:
 
 ``\MEMID``
-	The name of the RTLIL::Memory object that is associated with this read
+	The name of the ``RTLIL::Memory`` object that is associated with this read
 	port.
 
 ``\ABITS``
@@ -413,7 +416,7 @@ The ``$memwr_v2`` cells have a clock input ``\CLK``, an enable input ``\EN``
 ``\DATA``. They also have the following parameters:
 
 ``\MEMID``
-	The name of the RTLIL::Memory object that is associated with this write
+	The name of the ``RTLIL::Memory`` object that is associated with this write
 	port.
 
 ``\ABITS``
@@ -452,7 +455,7 @@ to ``\WIDTH`` parameter. All three of the inputs must resolve to a constant for
 synthesis to succeed.
 
 ``\MEMID``
-	The name of the RTLIL::Memory object that is associated with this
+	The name of the ``RTLIL::Memory`` object that is associated with this
 	initialization cell.
 
 ``\ABITS``
@@ -468,9 +471,9 @@ synthesis to succeed.
 	The cell with the higher integer value in this parameter wins an
 	initialization conflict.
 
-The HDL frontend models a memory using RTLIL::Memory objects and asynchronous
+The HDL frontend models a memory using ``RTLIL::Memory`` objects and
-``$memrd_v2`` and ``$memwr_v2`` cells. The :cmd:ref:`memory` pass (i.e.~its
+asynchronous ``$memrd_v2`` and ``$memwr_v2`` cells. The :cmd:ref:`memory` pass
-various sub-passes) migrates ``$dff`` cells into the ``$memrd_v2`` and
+(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
@@ -480,7 +483,7 @@ is left in the design.
 The ``$mem_v2`` cell provides the following parameters:
 
 ``\MEMID``
-	The name of the original RTLIL::Memory object that became this
+	The name of the original ``RTLIL::Memory`` object that became this
 	``$mem_v2`` cell.
 
 ``\SIZE``
@@ -1145,8 +1148,8 @@ mapped to physical flip-flop cells from a Liberty file using the dfflibmap pass.
 The combinatorial logic cells can be mapped to physical cells from a Liberty
 file via ABC using the abc pass.
 
-Add information about ``$slice`` and ``$concat`` cells.
+.. todo:: Add information about ``$slice`` and ``$concat`` cells.
 
-Add information about ``$lut`` and ``$sop`` cells.
+.. todo:: Add information about ``$lut`` and ``$sop`` cells.
 
-Add information about ``$alu``, ``$macc``, ``$fa``, and ``$lcu`` cells.
+.. todo:: Add information about ``$alu``, ``$macc``, ``$fa``, and ``$lcu`` cells.

docs/source/yosys_internals/formats/index.rst

@@ -1,6 +1,8 @@
 Internal formats
 ================
 
+.. todo:: brief overview for the internal formats index
+
 .. toctree:: 
 	:maxdepth: 3
 

docs/source/yosys_internals/techmap.rst

@@ -12,6 +12,13 @@ Yosys' internal cell types (such as ``$or``) as well as user-defined cell types.
   file.
 - Generate blocks and recursion are powerful tools for writing map files.
 
+Code examples used in this document are included in the Yosys code base under
+|code_examples/techmap|_.
+
+.. |code_examples/techmap| replace:: :file:`docs/source/code_examples/techmap`
+.. _code_examples/techmap: https://github.com/YosysHQ/yosys/tree/krys/docs/docs/source/code_examples/techmap
+
+
 Mapping OR3X1
 ~~~~~~~~~~~~~
 
@@ -24,31 +31,32 @@ Mapping OR3X1
 
 .. literalinclude:: /code_examples/techmap/red_or3x1_map.v
    :language: verilog
-   :caption: ``docs/source/code_examples/techmap/red_or3x1_map.v``
+   :caption: :file:`red_or3x1_map.v`
 
 .. figure:: /_images/code_examples/techmap/red_or3x1.*
     :class: width-helper
 
 .. literalinclude:: /code_examples/techmap/red_or3x1_test.ys
    :language: yoscrypt
-   :caption: ``docs/source/code_examples/techmap/red_or3x1_test.ys``
+   :caption: :file:`red_or3x1_test.ys`
 
 .. literalinclude:: /code_examples/techmap/red_or3x1_test.v
    :language: verilog
-   :caption: ``docs/source/code_examples/techmap/red_or3x1_test.v``
+   :caption: :file:`red_or3x1_test.v`
 
 Conditional techmap
 ~~~~~~~~~~~~~~~~~~~
 
 - In some cases only cells with certain properties should be substituted.
-- The special wire ``_TECHMAP_FAIL_`` can be used to disable a module
+- The special wire ``_TECHMAP_FAIL_`` can be used to disable a module in the map
-  in the map file for a certain set of parameters.
+  file for a certain set of parameters.
-- The wire ``_TECHMAP_FAIL_`` must be set to a constant value. If it
+- The wire ``_TECHMAP_FAIL_`` must be set to a constant value. If it is non-zero
-  is non-zero then the module is disabled for this set of parameters.
+  then the module is disabled for this set of parameters.
 - Example use-cases:
 
     - coarse-grain cell types that only operate on certain bit widths
-    - memory resources for different memory geometries (width, depth, ports, etc.)
+    - memory resources for different memory geometries (width, depth, ports,
+      etc.)
 
 Example:
 
@@ -57,22 +65,22 @@ Example:
 
 .. literalinclude:: /code_examples/techmap/sym_mul_map.v
    :language: verilog
-   :caption: ``docs/source/code_examples/techmap/sym_mul_map.v``
+   :caption: :file:`sym_mul_map.v`
 
 .. literalinclude:: /code_examples/techmap/sym_mul_test.v
    :language: verilog
-   :caption: ``docs/source/code_examples/techmap/sym_mul_test.v``
+   :caption: :file:`sym_mul_test.v`
 
 .. literalinclude:: /code_examples/techmap/sym_mul_test.ys
    :language: yoscrypt
-   :caption: ``docs/source/code_examples/techmap/sym_mul_test.ys``
+   :caption: :file:`sym_mul_test.ys`
 
 
 Scripting in map modules
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-- The special wires ``_TECHMAP_DO_*`` can be used to run Yosys scripts
+- The special wires ``_TECHMAP_DO_*`` can be used to run Yosys scripts in the
-  in the context of the replacement module.
+  context of the replacement module.
 - The wire that comes first in alphabetical oder is interpreted as string (must
   be connected to constants) that is executed as script. Then the wire is
   removed. Repeat.
@@ -96,15 +104,15 @@ Example:
 
 .. literalinclude:: /code_examples/techmap/mymul_map.v
    :language: verilog
-   :caption: ``docs/source/code_examples/techmap/mymul_map.v``
+   :caption: :file:`mymul_map.v`
 
 .. literalinclude:: /code_examples/techmap/mymul_test.v
    :language: verilog
-   :caption: ``docs/source/code_examples/techmap/mymul_test.v``
+   :caption: :file:`mymul_test.v`
 
 .. literalinclude:: /code_examples/techmap/mymul_test.ys
    :language: yoscrypt
-   :caption: ``docs/source/code_examples/techmap/mymul_test.ys``
+   :caption: :file:`mymul_test.ys`
 
 Handling constant inputs
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -126,15 +134,15 @@ Example:
 
 .. literalinclude:: /code_examples/techmap/mulshift_map.v
    :language: verilog
-   :caption: ``docs/source/code_examples/techmap/mulshift_map.v``
+   :caption: :file:`mulshift_map.v`
 
 .. literalinclude:: /code_examples/techmap/mulshift_test.v
    :language: verilog
-   :caption: ``docs/source/code_examples/techmap/mulshift_test.v``
+   :caption: :file:`mulshift_test.v`
 
 .. literalinclude:: /code_examples/techmap/mulshift_test.ys
    :language: yoscrypt
-   :caption: ``docs/source/code_examples/techmap/mulshift_test.ys``
+   :caption: :file:`mulshift_test.ys`
 
 Handling shorted inputs
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -143,7 +151,8 @@ Handling shorted inputs
   ``_TECHMAP_CONNMAP_<port-name>_`` can be used to handle shorted inputs.
 - Each bit of the port correlates to an ``_TECHMAP_BITS_CONNMAP_`` bits wide
   number in ``_TECHMAP_CONNMAP_<port-name>_``.
-- Each unique signal bit is assigned its own number. Identical fields in the ``_TECHMAP_CONNMAP_<port-name>_`` parameters mean shorted signal bits.
+- Each unique signal bit is assigned its own number. Identical fields in the
+  ``_TECHMAP_CONNMAP_<port-name>_`` parameters mean shorted signal bits.
 - The numbers 0-3 are reserved for ``0``, ``1``, ``x``, and ``z`` respectively.
 - Example use-cases:
 
@@ -157,15 +166,15 @@ Example:
 
 .. literalinclude:: /code_examples/techmap/addshift_map.v
    :language: verilog
-   :caption: ``docs/source/code_examples/techmap/addshift_map.v``
+   :caption: :file:`addshift_map.v`
 
 .. literalinclude:: /code_examples/techmap/addshift_test.v
    :language: verilog
-   :caption: ``docs/source/code_examples/techmap/addshift_test.v``
+   :caption: :file:`addshift_test.v`
 
 .. literalinclude:: /code_examples/techmap/addshift_test.ys
    :language: yoscrypt
-   :caption: ``docs/source/code_examples/techmap/addshift_test.ys``
+   :caption: :file:`addshift_test.ys`
 
 Notes on using techmap
 ~~~~~~~~~~~~~~~~~~~~~~