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