diff --git a/docs/source/code_examples/opt/Makefile b/docs/source/code_examples/opt/Makefile
new file mode 100644
index 000000000..e59130ecd
--- /dev/null
+++ b/docs/source/code_examples/opt/Makefile
@@ -0,0 +1,19 @@
+PROGRAM_PREFIX :=
+
+YOSYS ?= ../../../../$(PROGRAM_PREFIX)yosys
+
+DOT_NAMES = opt_share opt_muxtree opt_merge opt_expr
+
+DOTS := $(addsuffix .dot,$(DOT_NAMES))
+
+dots: $(DOTS)
+
+%_full.dot: %.ys
+	$(YOSYS) $<
+
+%.dot: %_full.dot
+	gvpack -u $*_full.dot -o $@
+
+.PHONY: clean
+clean:
+	rm -f *.dot
diff --git a/docs/source/code_examples/opt/opt_expr.ys b/docs/source/code_examples/opt/opt_expr.ys
new file mode 100644
index 000000000..e87da339e
--- /dev/null
+++ b/docs/source/code_examples/opt/opt_expr.ys
@@ -0,0 +1,17 @@
+read_verilog <<EOT
+
+module uut(
+    input a,
+    output y, z
+);  
+    assign y = a == a;
+    assign z = a != a;
+endmodule
+
+EOT
+
+copy uut after
+opt_expr after
+clean
+
+show -format dot -prefix opt_expr_full -notitle -color cornflowerblue uut
diff --git a/docs/source/code_examples/opt/opt_merge.ys b/docs/source/code_examples/opt/opt_merge.ys
new file mode 100644
index 000000000..38434ca3a
--- /dev/null
+++ b/docs/source/code_examples/opt/opt_merge.ys
@@ -0,0 +1,18 @@
+read_verilog <<EOT
+
+module uut(
+    input  [3:0] a, b,
+    output [3:0] y, z
+);
+    assign y = a + b;
+    assign z = b + a;
+endmodule
+
+EOT
+
+copy uut after
+opt_merge after
+clean
+
+show -format dot -prefix opt_merge_full -notitle -color cornflowerblue uut
+
diff --git a/docs/source/code_examples/opt/opt_muxtree.ys b/docs/source/code_examples/opt/opt_muxtree.ys
new file mode 100644
index 000000000..b9d394c08
--- /dev/null
+++ b/docs/source/code_examples/opt/opt_muxtree.ys
@@ -0,0 +1,17 @@
+read_verilog <<EOT
+
+module uut(
+    input a, b, c, d,
+    output y
+);  
+    assign y = a ? (a ? b : c) : d;
+endmodule
+
+EOT
+
+copy uut after
+opt_muxtree after
+clean
+
+show -format dot -prefix opt_muxtree_full -notitle -color cornflowerblue uut
+
diff --git a/docs/source/code_examples/opt/opt_share.ys b/docs/source/code_examples/opt/opt_share.ys
new file mode 100644
index 000000000..bcf638748
--- /dev/null
+++ b/docs/source/code_examples/opt/opt_share.ys
@@ -0,0 +1,17 @@
+read_verilog <<EOT
+
+module uut(
+    input  [15:0] a, b,
+    input         sel,
+    output [15:0] res,
+);
+    assign res = {sel ? a + b : a - b};
+endmodule
+
+EOT
+
+copy uut after
+opt_share after
+clean
+
+show -format dot -prefix opt_share_full -notitle -color cornflowerblue uut
diff --git a/docs/source/code_examples/synth_flow/Makefile b/docs/source/code_examples/synth_flow/Makefile
index b6c83f05d..af5d41493 100644
--- a/docs/source/code_examples/synth_flow/Makefile
+++ b/docs/source/code_examples/synth_flow/Makefile
@@ -1,6 +1,5 @@
 
 TARGETS += proc_01 proc_02 proc_03
-TARGETS += opt_01 opt_02 opt_03 opt_04
 TARGETS += memory_01 memory_02
 TARGETS += techmap_01
 
diff --git a/docs/source/code_examples/synth_flow/opt_01.v b/docs/source/code_examples/synth_flow/opt_01.v
deleted file mode 100644
index 5d3c1ea49..000000000
--- a/docs/source/code_examples/synth_flow/opt_01.v
+++ /dev/null
@@ -1,3 +0,0 @@
-module test(input A, B, output Y);
-assign Y = A ? A ? B : 1'b1 : B;
-endmodule
diff --git a/docs/source/code_examples/synth_flow/opt_01.ys b/docs/source/code_examples/synth_flow/opt_01.ys
deleted file mode 100644
index 34ed123be..000000000
--- a/docs/source/code_examples/synth_flow/opt_01.ys
+++ /dev/null
@@ -1,3 +0,0 @@
-read_verilog opt_01.v
-hierarchy -check -top test
-opt
diff --git a/docs/source/code_examples/synth_flow/opt_02.v b/docs/source/code_examples/synth_flow/opt_02.v
deleted file mode 100644
index 762fc1a89..000000000
--- a/docs/source/code_examples/synth_flow/opt_02.v
+++ /dev/null
@@ -1,3 +0,0 @@
-module test(input A, output Y, Z);
-assign Y = A == A, Z = A != A;
-endmodule
diff --git a/docs/source/code_examples/synth_flow/opt_02.ys b/docs/source/code_examples/synth_flow/opt_02.ys
deleted file mode 100644
index fc92a636e..000000000
--- a/docs/source/code_examples/synth_flow/opt_02.ys
+++ /dev/null
@@ -1,3 +0,0 @@
-read_verilog opt_02.v
-hierarchy -check -top test
-opt
diff --git a/docs/source/code_examples/synth_flow/opt_03.v b/docs/source/code_examples/synth_flow/opt_03.v
deleted file mode 100644
index 134161bb8..000000000
--- a/docs/source/code_examples/synth_flow/opt_03.v
+++ /dev/null
@@ -1,4 +0,0 @@
-module test(input  [3:0] A, B,
-            output [3:0] Y, Z);
-assign Y = A + B, Z = B + A;
-endmodule
diff --git a/docs/source/code_examples/synth_flow/opt_03.ys b/docs/source/code_examples/synth_flow/opt_03.ys
deleted file mode 100644
index 282f06dde..000000000
--- a/docs/source/code_examples/synth_flow/opt_03.ys
+++ /dev/null
@@ -1,3 +0,0 @@
-read_verilog opt_03.v
-hierarchy -check -top test
-opt
diff --git a/docs/source/code_examples/synth_flow/opt_04.v b/docs/source/code_examples/synth_flow/opt_04.v
deleted file mode 100644
index 2ed447639..000000000
--- a/docs/source/code_examples/synth_flow/opt_04.v
+++ /dev/null
@@ -1,19 +0,0 @@
-module test(input CLK, ARST,
-            output [7:0] Q1, Q2, Q3);
-
-wire NO_CLK = 0;
-
-always @(posedge CLK, posedge ARST)
-	if (ARST)
-		Q1 <= 42;
-
-always @(posedge NO_CLK, posedge ARST)
-	if (ARST)
-		Q2 <= 42;
-	else
-		Q2 <= 23;
-
-always @(posedge CLK)
-	Q3 <= 42;
-
-endmodule
diff --git a/docs/source/code_examples/synth_flow/opt_04.ys b/docs/source/code_examples/synth_flow/opt_04.ys
deleted file mode 100644
index f5ddae29f..000000000
--- a/docs/source/code_examples/synth_flow/opt_04.ys
+++ /dev/null
@@ -1,3 +0,0 @@
-read_verilog opt_04.v
-hierarchy -check -top test
-proc; opt
diff --git a/docs/source/using_yosys/more_scripting/interactive_investigation.rst b/docs/source/using_yosys/more_scripting/interactive_investigation.rst
index a5e91a5a1..7e01ff06d 100644
--- a/docs/source/using_yosys/more_scripting/interactive_investigation.rst
+++ b/docs/source/using_yosys/more_scripting/interactive_investigation.rst
@@ -437,7 +437,7 @@ sections: ``outstage``, ``selstage``, and ``scramble``.
    :language: yoscrypt
    :caption: Using :cmd:ref:`submod` to break up the circuit from ``memdemo.v``
    :start-after: cd memdemo
-   :end-at: @selstage
+   :end-before: cd ..
    :name: submod
 
 The ``-name`` option is used to specify the name of the new module and also the
diff --git a/docs/source/using_yosys/more_scripting/troubleshooting.rst b/docs/source/using_yosys/more_scripting/troubleshooting.rst
index ff87d63cd..8b7876607 100644
--- a/docs/source/using_yosys/more_scripting/troubleshooting.rst
+++ b/docs/source/using_yosys/more_scripting/troubleshooting.rst
@@ -1,4 +1,6 @@
 Troubleshooting
 ~~~~~~~~~~~~~~~
 
+.. TODO:: more on troubleshooting
+
 See :doc:`/cmd/bugpoint`
diff --git a/docs/source/using_yosys/synthesis/opt.rst b/docs/source/using_yosys/synthesis/opt.rst
index 2d543c0b5..fb75c9fa1 100644
--- a/docs/source/using_yosys/synthesis/opt.rst
+++ b/docs/source/using_yosys/synthesis/opt.rst
@@ -81,6 +81,17 @@ The :cmd:ref:`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.
 
+.. literalinclude:: /code_examples/opt/opt_expr.ys
+   :language: Verilog
+   :start-after: read_verilog <<EOT
+   :end-before: EOT
+   :caption: example verilog for demonstrating :cmd:ref:`opt_expr`
+
+.. figure:: /_images/code_examples/opt/opt_expr.*
+   :class: width-helper
+
+   Before and after :cmd:ref:`opt_expr`
+
 Merging identical cells - :cmd:ref:`opt_merge`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -93,23 +104,38 @@ 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
 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`
+
+.. figure:: /_images/code_examples/opt/opt_merge.*
+   :class: width-helper
+
+   Before and after :cmd:ref:`opt_merge`
+
 Removing never-active branches from multiplexer tree - :cmd:ref:`opt_muxtree`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This pass optimizes trees of multiplexer cells by analyzing the select inputs.
 Consider the following simple example:
 
-.. code:: verilog
+.. literalinclude:: /code_examples/opt/opt_muxtree.ys
+   :language: Verilog
+   :start-after: read_verilog <<EOT
+   :end-before: EOT
+   :caption: example verilog for demonstrating :cmd:ref:`opt_muxtree`
 
-   module uut(a, y); 
-      input a; 
-      output [1:0] y = a ? (a ? 1 : 2) : 3; 
-   endmodule
-
-The output can never be 2, as this would require ``a`` to be 1 for the outer
+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
 detects this contradiction and replaces the inner multiplexer with a constant 1,
-yielding the logic for ``y = a ? 1 : 3``.
+yielding the logic for ``y = a ? b : d``.
+
+.. figure:: /_images/code_examples/opt/opt_muxtree.*
+   :class: width-helper
+
+   Before and after :cmd:ref:`opt_muxtree`
 
 Simplifying large MUXes and AND/OR gates - :cmd:ref:`opt_reduce`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -139,8 +165,19 @@ This pass identifies mutually exclusive cells of the same type that:
 allowing the cell to be merged and the multiplexer to be moved from
 multiplexing its output to multiplexing the non-shared input signals.
 
-.. todo:: more detailed description of :cmd:ref:`opt_share` (esp. why)
-   so that it's not just a copy-paste of the help output
+.. literalinclude:: /code_examples/opt/opt_share.ys
+   :language: Verilog
+   :start-after: read_verilog <<EOT
+   :end-before: EOT
+   :caption: example verilog for demonstrating :cmd:ref:`opt_share`
+
+.. figure:: /_images/code_examples/opt/opt_share.*
+   :class: width-helper
+
+   Before and after :cmd:ref:`opt_share`
+
+When running :cmd:ref:`opt` in full, the original ``$mux`` (labeled ``$3``) is
+optimized away by :cmd:ref:`opt_expr`.
 
 Performing DFF optimizations - :cmd:ref:`opt_dff`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -160,58 +197,6 @@ 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.
 
-Example
-~~~~~~~
-
-.. todo:: describe ``opt`` images
-   
-   and/or replace with an example image showing before/after of each ``opt_*``
-   command
-
-.. figure:: /_images/code_examples/synth_flow/opt_01.*
-   :class: width-helper
-
-.. literalinclude:: /code_examples/synth_flow/opt_01.ys
-   :language: yoscrypt
-   :caption: ``docs/source/code_examples/synth_flow/opt_01.ys``
-
-.. literalinclude:: /code_examples/synth_flow/opt_01.v
-   :language: verilog
-   :caption: ``docs/source/code_examples/synth_flow/opt_01.v``
-
-.. figure:: /_images/code_examples/synth_flow/opt_02.*
-   :class: width-helper
-
-.. literalinclude:: /code_examples/synth_flow/opt_02.ys
-   :language: yoscrypt
-   :caption: ``docs/source/code_examples/synth_flow/opt_02.ys``
-
-.. literalinclude:: /code_examples/synth_flow/opt_02.v
-   :language: verilog
-   :caption: ``docs/source/code_examples/synth_flow/opt_02.v``
-
-.. figure:: /_images/code_examples/synth_flow/opt_03.*
-   :class: width-helper
-
-.. literalinclude:: /code_examples/synth_flow/opt_03.ys
-   :language: yoscrypt
-   :caption: ``docs/source/code_examples/synth_flow/opt_03.ys``
-
-.. literalinclude:: /code_examples/synth_flow/opt_03.v
-   :language: verilog
-   :caption: ``docs/source/code_examples/synth_flow/opt_03.v``
-
-.. figure:: /_images/code_examples/synth_flow/opt_04.*
-   :class: width-helper
-
-.. literalinclude:: /code_examples/synth_flow/opt_04.v
-   :language: verilog
-   :caption: ``docs/source/code_examples/synth_flow/opt_04.v``
-
-.. literalinclude:: /code_examples/synth_flow/opt_04.ys
-   :language: yoscrypt
-   :caption: ``docs/source/code_examples/synth_flow/opt_04.ys``
-
 When to use :cmd:ref:`opt` or :cmd:ref:`clean`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/source/yosys_internals/flow/overview.rst b/docs/source/yosys_internals/flow/overview.rst
index 08ead2570..ae07e6f1f 100644
--- a/docs/source/yosys_internals/flow/overview.rst
+++ b/docs/source/yosys_internals/flow/overview.rst
@@ -18,6 +18,8 @@ The AST Frontend then compiles the AST to Yosys's main internal data format, the
 RTL Intermediate Language (RTLIL). A more detailed description of this format is
 given in the next section.
 
+.. TODO:: what next section
+
 There is also a text representation of the RTLIL data structure that can be
 parsed using the RTLIL Frontend.