Docs: interactive investigation

More `literalinclude` and references to source.
Adding `example_show.ys` and `example_lscd.ys`.
Rename `example_00` et al to `example_first` et al.
Also some other minor tidying.

docs/source/code_examples/show/Makefile

@@ -2,13 +2,13 @@ PROGRAM_PREFIX :=
 
 YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
 
-EXAMPLE = example_00 example_01 example_02
+EXAMPLE = example_first example_second example_third
 EXAMPLE_DOTS := $(addsuffix .dot,$(EXAMPLE))
 
 CMOS = cmos_00 cmos_01
 CMOS_DOTS := $(addsuffix .dot,$(CMOS))
 
-dots: splice.dot $(EXAMPLE_DOTS) $(CMOS_DOTS)
+dots: splice.dot $(EXAMPLE_DOTS) $(CMOS_DOTS) example.out
 
 splice.dot: splice.v
 	$(YOSYS) -p 'prep -top splice_demo; show -format dot -prefix splice' splice.v
@@ -16,6 +16,9 @@ splice.dot: splice.v
 $(EXAMPLE_DOTS): example.v example.ys
 	$(YOSYS) example.ys
 
+example.out: example_lscd.ys example.v
+	$(YOSYS) $< -l $@ -Q -T
+
 $(CMOS_DOTS): cmos.v cmos.ys
 	$(YOSYS) cmos.ys
 

docs/source/code_examples/show/example.out

@@ -0,0 +1,54 @@
+
+-- Executing script file `example_lscd.ys' --
+
+1. Executing Verilog-2005 frontend: example.v
+Parsing Verilog input from `example.v' to AST representation.
+Generating RTLIL representation for module `\example'.
+Successfully finished Verilog frontend.
+echo on
+
+yosys> ls
+
+1 modules:
+  example
+
+yosys> cd example
+
+yosys [example]> ls
+
+8 wires:
+  $0\y[1:0]
+  $add$example.v:5$2_Y
+  $ternary$example.v:5$3_Y
+  a
+  b
+  c
+  clk
+  y
+
+2 cells:
+  $add$example.v:5$2
+  $ternary$example.v:5$3
+
+1 processes:
+  $proc$example.v:3$1
+
+yosys [example]> dump $2
+
+
+  attribute \src "example.v:5.22-5.27"
+  cell $add $add$example.v:5$2
+    parameter \Y_WIDTH 2
+    parameter \B_WIDTH 1
+    parameter \A_WIDTH 1
+    parameter \B_SIGNED 0
+    parameter \A_SIGNED 0
+    connect \Y $add$example.v:5$2_Y
+    connect \B \b
+    connect \A \a
+  end
+
+yosys [example]> cd ..
+
+yosys> echo off
+echo off

docs/source/code_examples/show/example.ys

@@ -1,6 +1,6 @@
 read_verilog example.v
-show -format dot -prefix example_00
+show -format dot -prefix example_first
 proc
-show -format dot -prefix example_01
+show -format dot -prefix example_second
 opt
-show -format dot -prefix example_02
+show -format dot -prefix example_third

docs/source/code_examples/show/example_lscd.ys

@@ -0,0 +1,8 @@
+read_verilog example.v
+echo on
+ls
+cd example
+ls
+dump $2
+cd ..
+echo off

docs/source/code_examples/show/example_show.ys

@@ -0,0 +1,6 @@
+read_verilog example.v
+show -pause # first
+proc
+show -pause # second
+opt
+show -pause # third

docs/source/using_yosys/more_scripting/interactive_investigation.rst

@@ -15,12 +15,16 @@ in the circuit diagrams generated by it.
 A simple circuit
 ^^^^^^^^^^^^^^^^
 
-:numref:`example_v` below provides the Verilog code for a simple circuit which
+:ref:`example_v` below provides the Verilog code for a simple circuit which we
-we will use to demonstrate the usage of :cmd:ref:`show` in a simple setting.
+will use to demonstrate the usage of :cmd:ref:`show` in a simple setting. The
+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: ``docs/source/code_examples/show/example.v``
+   :caption: ``example.v``
    :name: example_v
 
 The Yosys synthesis script we will be running is included as
@@ -30,22 +34,24 @@ Enter key. Using :yoscrypt:`show -pause` also allows the user to enter an
 interactive shell to further investigate the circuit before continuing
 synthesis.
 
-.. code-block:: yoscrypt
+.. literalinclude:: /code_examples/show/example_show.ys
-   :caption: ``docs/source/code_examples/show/example.ys``
+   :language: yoscrypt
+   :caption: ``example_show.ys``
    :name: example_ys
-   
-   read_verilog example.v
-   show -pause # first
-   proc
-   show -pause # second
-   opt
-   show -pause # third
 
 This script, when executed, will show the design after each of the three
 synthesis commands. We will now look at each of these diagrams and explain what
 is shown.
 
-.. figure:: /_images/code_examples/show/example_00.*
+.. note::
+
+   The images uses in this document are generated from the ``example.ys`` file,
+   rather than ``example_show.ys``.  ``example.ys`` outputs the schematics as
+   ``.dot`` files rather than displaying them directly.  You can view these
+   images yourself by running ``yosys example.ys`` and then ``xdot
+   example_first.dot`` etc.
+
+.. figure:: /_images/code_examples/show/example_first.*
    :class: width-helper
    
    Output of the first :cmd:ref:`show` command in :numref:`example_ys`
@@ -59,7 +65,7 @@ prefixed with a dollar sign. For more details on the internal cell library, see
 :doc:`/yosys_internals/formats/cell_library`.
 
 Constants are shown as ellipses with the constant value as label. The syntax
-``<bit_width>'<bits>`` is used for for constants that are not 32-bit wide and/or
+``<bit_width>'<bits>`` is used for constants that are not 32-bit wide and/or
 contain bits that are not 0 or 1 (i.e. ``x`` or ``z``). Ordinary 32-bit
 constants are written using decimal numbers.
 
@@ -77,7 +83,7 @@ original ``always``-block in the second line. Note how the multiplexer from the
 The :cmd:ref:`proc` command transforms the process from the first diagram into a
 multiplexer and a d-type flip-flop, which brings us to the second diagram:
 
-.. figure:: /_images/code_examples/show/example_01.*
+.. figure:: /_images/code_examples/show/example_second.*
    :class: width-helper
    
    Output of the second :cmd:ref:`show` command in :numref:`example_ys`
@@ -99,11 +105,11 @@ call :cmd:ref:`clean` before calling :cmd:ref:`show`.
 In this script we directly call :cmd:ref:`opt` as the next step, which finally
 leads us to the third diagram: 
 
-.. figure:: /_images/code_examples/show/example_02.*
+.. figure:: /_images/code_examples/show/example_third.*
    :class: width-helper
    :name: example_out
    
-   Output of the third :cmd:ref:`show` command in :numref:`example_ys`
+   Output of the third :cmd:ref:`show` command in :ref:`example_ys`
    
 Here we see that the :cmd:ref:`proc` command not only has removed the artifacts
 left behind by :cmd:ref:`proc`, but also determined correctly that it can remove
@@ -256,39 +262,16 @@ For most cases, the shell will start with the whole design selected (i.e. when
 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 `ls` command lists the objects within that module.
+switch back). Now the :cmd:ref:`ls` command lists the objects within that
-:numref:`lscd` below demonstrates this using the ``example.v`` from
+module. This is demonstrated below using ``example.v`` from `A simple circuit`_:
-`A simple circuit`_
 
-.. TODO:: update yosys output with $ternary$example.v$3
+.. literalinclude:: /code_examples/show/example.out
-
+   :language: doscon
-.. code-block:: none
+   :start-at: yosys> ls
-   :caption: Demonstration of :cmd:ref:`ls` and :cmd:ref:`cd` having run ``yosys example.v``
+   :end-before: yosys [example]> dump
+   :caption: Output of :cmd:ref:`ls` and :cmd:ref:`cd` after running ``yosys example.v``
    :name: lscd
 
-   yosys> ls
-
-   1 modules:
-     example
-
-   yosys> cd example
-
-   yosys [example]> ls
-
-   7 wires:
-     $0\y[1:0]
-     $add$example.v:5$2_Y
-     a
-     b
-     c
-     clk
-     y
-
-   3 cells:
-     $add$example.v:5$2
-     $procdff$7
-     $procmux$5
-
 When a module is selected using the :cmd:ref:`cd` command, all commands (with a
 few exceptions, such as the ``read_`` and ``write_`` commands) operate only on
 the selected module. This can also be useful for synthesis scripts where
@@ -308,25 +291,21 @@ Usually all interactive work is done with one module selected using the
 start with ``b`` from all modules whose names start with ``a``.
 
 The :cmd:ref:`dump` command can be used to print all information about an
-object. For example ``dump $2`` will print :numref:`dump2`. This can for example
+object. For example, calling :yoscrypt:`dump $2` after the :yoscrypt:`cd
-be useful to determine the names of nets connected to cells, as the net-names
+example` above:
-are usually suppressed in the circuit diagram if they are auto-generated.
 
-.. code-block:: RTLIL
+.. literalinclude:: /code_examples/show/example.out
-   :caption: Output of ``dump $2`` using ``example.v`` from `A simple circuit`_
+   :language: RTLIL
+   :start-after: yosys [example]> dump
+   :end-before: yosys [example]> cd
+   :dedent:
+   :caption: Output of :yoscrypt:`dump $2` after :numref:`lscd`
    :name: dump2
 
-     attribute \src "example.v:5"
+This can for example be useful to determine the names of nets connected to
-     cell $add $add$example.v:5$2
+cells, as the net-names are usually suppressed in the circuit diagram if they
-       parameter \A_SIGNED 0
+are auto-generated.  Note that the output is in the RTLIL representation,
-       parameter \A_WIDTH 1
+described in :doc:`/yosys_internals/formats/rtlil_rep`.
-       parameter \B_SIGNED 0
-       parameter \B_WIDTH 1
-       parameter \Y_WIDTH 2
-       connect \A \a
-       connect \B \b
-       connect \Y $add$example.v:5$2_Y
-     end
 
 Interactive Design Investigation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/source/using_yosys/more_scripting/selections.rst

@@ -141,10 +141,10 @@ See :doc:`/cmd/select` for the full list.
 Expanding selections
 ^^^^^^^^^^^^^^^^^^^^
 
-The listing in :numref:`sumprod` uses the Yosys non-standard ``{... *}`` syntax
+:numref:`sumprod` uses the Yosys non-standard ``{... *}`` syntax to set the
-to set the attribute ``sumstuff`` on all cells generated by the first assign
+attribute ``sumstuff`` on all cells generated by the first assign statement.
-statement. (This works on arbitrary large blocks of Verilog code an can be used
+(This works on arbitrary large blocks of Verilog code and can be used to mark
-to mark portions of code for analysis.)
+portions of code for analysis.)
 
 .. literalinclude:: /code_examples/selections/sumprod.v
    :caption: Another test module for operations on selections