Remove docs dependency on yosys repo (#3558)

* Copies guidelines files into docs/ for website

* Copying manual/CHAPTER_Prog for new docs

* Copying manual/APPNOTE_011... for new docs

Also adding faketime to list of packages for website build.

Co-authored-by: KrystalDelusion <krystinedawn@yosyshq.com>

39 files changed, 905 insertions, 18 deletions

diff --git a/Makefile b/Makefile
index e1c24c09a..25b1e378e 100644
--- a/Makefile
+++ b/Makefile
@@ -963,12 +963,17 @@ docs/source/cmd/abc.rst: $(TARGETS) $(EXTRA_TARGETS)
 	mkdir -p docs/source/cmd
 	./$(PROGRAM_PREFIX)yosys -p 'help -write-rst-command-reference-manual'
 
-PHONY: docs/gen_images
+PHONY: docs/gen_images docs/guidelines
 docs/gen_images:
 	$(Q) $(MAKE) -C docs/images all
 
+DOCS_GUIDELINE_FILES := GettingStarted CodingStyle
+docs/guidelines:
+	$(Q) mkdir -p docs/source/temp
+	$(Q) cp -f $(addprefix guidelines/,$(DOCS_GUIDELINE_FILES)) docs/source/temp
+
 DOC_TARGET ?= html
-docs: docs/source/cmd/abc.rst docs/gen_images
+docs: docs/source/cmd/abc.rst docs/gen_images docs/guidelines
 	$(Q) $(MAKE) -C docs $(DOC_TARGET)
 
 update-manual: $(TARGETS) $(EXTRA_TARGETS)
diff --git a/README.md b/README.md
index d0f46f244..df2f54930 100644
--- a/README.md
+++ b/README.md
@@ -634,7 +634,7 @@ and the website version of the documentation is not yet publicly available.
 In addition to those listed above for building Yosys from source, the following
 packages are used for building the website: 
 
-	$ sudo apt-get install pdf2svg
+	$ sudo apt-get install pdf2svg faketime
 
 PDFLaTeX, included with most LaTeX distributions, is also needed during the
 build process for the website.
diff --git a/docs/.gitignore b/docs/.gitignore
index 26645e4cb..e36f2309a 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -1,5 +1,6 @@
 /build/
 /source/cmd
+/source/temp
 /images/*.log
 /images/*.aux
 /images/*.pdf
diff --git a/docs/images/Makefile b/docs/images/Makefile
index 84e09615f..a7216ec90 100644
--- a/docs/images/Makefile
+++ b/docs/images/Makefile
@@ -1,7 +1,7 @@
 all: dots tex svg tidy
 
 TEX_SOURCE:= $(wildcard *.tex)
-DOT_LOC:= ../../manual/APPNOTE_011_Design_Investigation
+DOT_LOC:= ../source/APPNOTE_011_Design_Investigation
 DOT_SOURCE:= $(wildcard $(DOT_LOC)/*.dot)
 
 TEX_SOURCE+= 011/example_out.tex
diff --git a/docs/source/APPNOTE_011_Design_Investigation/cmos.v b/docs/source/APPNOTE_011_Design_Investigation/cmos.v
new file mode 100644
index 000000000..2912c760a
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/cmos.v
@@ -0,0 +1,3 @@
+module cmos_demo(input a, b, output [1:0] y);
+assign y = a + b;
+endmodule
diff --git a/docs/source/APPNOTE_011_Design_Investigation/cmos_00.dot b/docs/source/APPNOTE_011_Design_Investigation/cmos_00.dot
new file mode 100644
index 000000000..49c630080
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/cmos_00.dot
@@ -0,0 +1,34 @@
+digraph "cmos_demo" {
+rankdir="LR";
+remincross=true;
+n4 [ shape=octagon, label="a", color="black", fontcolor="black" ];
+n5 [ shape=octagon, label="b", color="black", fontcolor="black" ];
+n6 [ shape=octagon, label="y", color="black", fontcolor="black" ];
+c10 [ shape=record, label="{{<p7> A|<p8> B|<p9> Y}|$g0\nNOR|{}}" ];
+c11 [ shape=record, label="{{<p7> A|<p9> Y}|$g1\nNOT|{}}" ];
+c12 [ shape=record, label="{{<p7> A|<p9> Y}|$g2\nNOT|{}}" ];
+c13 [ shape=record, label="{{<p7> A|<p8> B|<p9> Y}|$g3\nNOR|{}}" ];
+x0 [ shape=record, style=rounded, label="<s0> 1:1 - 0:0 " ];
+x0:e -> c13:p9:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", label=""];
+c14 [ shape=record, label="{{<p7> A|<p8> B|<p9> Y}|$g4\nNOR|{}}" ];
+x1 [ shape=record, style=rounded, label="<s0> 1:1 - 0:0 " ];
+x1:e -> c14:p8:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", label=""];
+x2 [ shape=record, style=rounded, label="<s0> 0:0 - 0:0 " ];
+x2:e -> c14:p9:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", label=""];
+n1 [ shape=diamond, label="$n4" ];
+n1:e -> c10:p9:w [color="black", label=""];
+n1:e -> c14:p7:w [color="black", label=""];
+n2 [ shape=diamond, label="$n5" ];
+n2:e -> c11:p9:w [color="black", label=""];
+n2:e -> c13:p7:w [color="black", label=""];
+n3 [ shape=diamond, label="$n6_1" ];
+n3:e -> c12:p9:w [color="black", label=""];
+n3:e -> c13:p8:w [color="black", label=""];
+n4:e -> c10:p8:w [color="black", label=""];
+n4:e -> c12:p7:w [color="black", label=""];
+n5:e -> c10:p7:w [color="black", label=""];
+n5:e -> c11:p7:w [color="black", label=""];
+n6:e -> x0:s0:w [color="black", label=""];
+n6:e -> x1:s0:w [color="black", label=""];
+n6:e -> x2:s0:w [color="black", label=""];
+}
diff --git a/docs/source/APPNOTE_011_Design_Investigation/cmos_01.dot b/docs/source/APPNOTE_011_Design_Investigation/cmos_01.dot
new file mode 100644
index 000000000..ea6f4403c
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/cmos_01.dot
@@ -0,0 +1,23 @@
+digraph "cmos_demo" {
+rankdir="LR";
+remincross=true;
+n4 [ shape=octagon, label="a", color="black", fontcolor="black" ];
+n5 [ shape=octagon, label="b", color="black", fontcolor="black" ];
+n6 [ shape=octagon, label="y[0]", color="black", fontcolor="black" ];
+n7 [ shape=octagon, label="y[1]", color="black", fontcolor="black" ];
+c11 [ shape=record, label="{{<p8> A|<p9> B}|$g0\nNOR|{<p10> Y}}" ];
+c12 [ shape=record, label="{{<p8> A}|$g1\nNOT|{<p10> Y}}" ];
+c13 [ shape=record, label="{{<p8> A}|$g2\nNOT|{<p10> Y}}" ];
+c14 [ shape=record, label="{{<p8> A|<p9> B}|$g3\nNOR|{<p10> Y}}" ];
+c15 [ shape=record, label="{{<p8> A|<p9> B}|$g4\nNOR|{<p10> Y}}" ];
+c11:p10:e -> c15:p8:w [color="black", label=""];
+c12:p10:e -> c14:p8:w [color="black", label=""];
+c13:p10:e -> c14:p9:w [color="black", label=""];
+n4:e -> c11:p9:w [color="black", label=""];
+n4:e -> c13:p8:w [color="black", label=""];
+n5:e -> c11:p8:w [color="black", label=""];
+n5:e -> c12:p8:w [color="black", label=""];
+c15:p10:e -> n6:w [color="black", label=""];
+c14:p10:e -> n7:w [color="black", label=""];
+n7:e -> c15:p9:w [color="black", label=""];
+}
diff --git a/docs/source/APPNOTE_011_Design_Investigation/example.v b/docs/source/APPNOTE_011_Design_Investigation/example.v
new file mode 100644
index 000000000..8c71989b3
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/example.v
@@ -0,0 +1,6 @@
+module example(input clk, a, b, c,
+               output reg [1:0] y);
+    always @(posedge clk)
+        if (c)
+            y <= c ? a + b : 2'd0;
+endmodule
diff --git a/docs/source/APPNOTE_011_Design_Investigation/example.ys b/docs/source/APPNOTE_011_Design_Investigation/example.ys
new file mode 100644
index 000000000..b1e956088
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/example.ys
@@ -0,0 +1,11 @@
+read_verilog example.v
+show -format dot -prefix example_00
+proc
+show -format dot -prefix example_01
+opt
+show -format dot -prefix example_02
+
+cd example
+select t:$add
+show -format dot -prefix example_03
+
diff --git a/docs/source/APPNOTE_011_Design_Investigation/example_00.dot b/docs/source/APPNOTE_011_Design_Investigation/example_00.dot
new file mode 100644
index 000000000..1e23ed0ea
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/example_00.dot
@@ -0,0 +1,23 @@
+digraph "example" {
+rankdir="LR";
+remincross=true;
+n4 [ shape=octagon, label="a", color="black", fontcolor="black" ];
+n5 [ shape=octagon, label="b", color="black", fontcolor="black" ];
+n6 [ shape=octagon, label="c", color="black", fontcolor="black" ];
+n7 [ shape=octagon, label="clk", color="black", fontcolor="black" ];
+n8 [ shape=octagon, label="y", color="black", fontcolor="black" ];
+c12 [ shape=record, label="{{<p9> A|<p10> B}|$2\n$add|{<p11> Y}}" ];
+v0 [ label="2'00" ];
+c14 [ shape=record, label="{{<p9> A|<p10> B|<p13> S}|$3\n$mux|{<p11> Y}}" ];
+p1 [shape=box, style=rounded, label="PROC $1\nexample.v:3"];
+c12:p11:e -> c14:p10:w [color="black", style="setlinewidth(3)", label=""];
+c14:p11:e -> p1:w [color="black", style="setlinewidth(3)", label=""];
+n4:e -> c12:p9:w [color="black", label=""];
+n5:e -> c12:p10:w [color="black", label=""];
+n6:e -> c14:p13:w [color="black", label=""];
+n6:e -> p1:w [color="black", label=""];
+n7:e -> p1:w [color="black", label=""];
+p1:e -> n8:w [color="black", style="setlinewidth(3)", label=""];
+n8:e -> p1:w [color="black", style="setlinewidth(3)", label=""];
+v0:e -> c14:p9:w [color="black", style="setlinewidth(3)", label=""];
+}
diff --git a/docs/source/APPNOTE_011_Design_Investigation/example_01.dot b/docs/source/APPNOTE_011_Design_Investigation/example_01.dot
new file mode 100644
index 000000000..e89292b51
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/example_01.dot
@@ -0,0 +1,33 @@
+digraph "example" {
+rankdir="LR";
+remincross=true;
+n6 [ shape=octagon, label="a", color="black", fontcolor="black" ];
+n7 [ shape=octagon, label="b", color="black", fontcolor="black" ];
+n8 [ shape=octagon, label="c", color="black", fontcolor="black" ];
+n9 [ shape=octagon, label="clk", color="black", fontcolor="black" ];
+n10 [ shape=octagon, label="y", color="black", fontcolor="black" ];
+c14 [ shape=record, label="{{<p11> A|<p12> B}|$2\n$add|{<p13> Y}}" ];
+c18 [ shape=record, label="{{<p15> CLK|<p16> D}|$7\n$dff|{<p17> Q}}" ];
+c20 [ shape=record, label="{{<p11> A|<p12> B|<p19> S}|$5\n$mux|{<p13> Y}}" ];
+v0 [ label="2'00" ];
+c21 [ shape=record, label="{{<p11> A|<p12> B|<p19> S}|$3\n$mux|{<p13> Y}}" ];
+x1 [shape=box, style=rounded, label="BUF"];
+x2 [shape=box, style=rounded, label="BUF"];
+n1 [ shape=diamond, label="$0\\y[1:0]" ];
+x2:e:e -> n1:w [color="black", style="setlinewidth(3)", label=""];
+c18:p17:e -> n10:w [color="black", style="setlinewidth(3)", label=""];
+n10:e -> c20:p11:w [color="black", style="setlinewidth(3)", label=""];
+c14:p13:e -> c21:p12:w [color="black", style="setlinewidth(3)", label=""];
+n3 [ shape=point ];
+c20:p13:e -> n3:w [color="black", style="setlinewidth(3)", label=""];
+n3:e -> c18:p16:w [color="black", style="setlinewidth(3)", label=""];
+n3:e -> x2:w:w [color="black", style="setlinewidth(3)", label=""];
+x1:e:e -> c20:p19:w [color="black", label=""];
+c21:p13:e -> c20:p12:w [color="black", style="setlinewidth(3)", label=""];
+n6:e -> c14:p11:w [color="black", label=""];
+n7:e -> c14:p12:w [color="black", label=""];
+n8:e -> c21:p19:w [color="black", label=""];
+n8:e -> x1:w:w [color="black", label=""];
+n9:e -> c18:p15:w [color="black", label=""];
+v0:e -> c21:p11:w [color="black", style="setlinewidth(3)", label=""];
+}
diff --git a/docs/source/APPNOTE_011_Design_Investigation/example_02.dot b/docs/source/APPNOTE_011_Design_Investigation/example_02.dot
new file mode 100644
index 000000000..f950ed2ed
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/example_02.dot
@@ -0,0 +1,20 @@
+digraph "example" {
+rankdir="LR";
+remincross=true;
+n3 [ shape=octagon, label="a", color="black", fontcolor="black" ];
+n4 [ shape=octagon, label="b", color="black", fontcolor="black" ];
+n5 [ shape=octagon, label="c", color="black", fontcolor="black" ];
+n6 [ shape=octagon, label="clk", color="black", fontcolor="black" ];
+n7 [ shape=octagon, label="y", color="black", fontcolor="black" ];
+c11 [ shape=record, label="{{<p8> A|<p9> B}|$2\n$add|{<p10> Y}}" ];
+c15 [ shape=record, label="{{<p12> CLK|<p13> D}|$7\n$dff|{<p14> Q}}" ];
+c17 [ shape=record, label="{{<p8> A|<p9> B|<p16> S}|$5\n$mux|{<p10> Y}}" ];
+c17:p10:e -> c15:p13:w [color="black", style="setlinewidth(3)", label=""];
+c11:p10:e -> c17:p9:w [color="black", style="setlinewidth(3)", label=""];
+n3:e -> c11:p8:w [color="black", label=""];
+n4:e -> c11:p9:w [color="black", label=""];
+n5:e -> c17:p16:w [color="black", label=""];
+n6:e -> c15:p12:w [color="black", label=""];
+c15:p14:e -> n7:w [color="black", style="setlinewidth(3)", label=""];
+n7:e -> c17:p8:w [color="black", style="setlinewidth(3)", label=""];
+}
diff --git a/docs/source/APPNOTE_011_Design_Investigation/example_03.dot b/docs/source/APPNOTE_011_Design_Investigation/example_03.dot
new file mode 100644
index 000000000..e19d24af7
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/example_03.dot
@@ -0,0 +1,11 @@
+digraph "example" {
+rankdir="LR";
+remincross=true;
+v0 [ label="a" ];
+v1 [ label="b" ];
+v2 [ label="$2_Y" ];
+c4 [ shape=record, label="{{<p1> A|<p2> B}|$2\n$add|{<p3> Y}}" ];
+v0:e -> c4:p1:w [color="black", label=""];
+v1:e -> c4:p2:w [color="black", label=""];
+c4:p3:e -> v2:w [color="black", style="setlinewidth(3)", label=""];
+}
diff --git a/docs/source/APPNOTE_011_Design_Investigation/foobaraddsub.v b/docs/source/APPNOTE_011_Design_Investigation/foobaraddsub.v
new file mode 100644
index 000000000..0f277211d
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/foobaraddsub.v
@@ -0,0 +1,8 @@
+module foobaraddsub(a, b, c, d, fa, fs, ba, bs);
+  input [7:0] a, b, c, d;
+  output [7:0] fa, fs, ba, bs;
+  assign fa = a + (* foo *) b;
+  assign fs = a - (* foo *) b;
+  assign ba = c + (* bar *) d;
+  assign bs = c - (* bar *) d;
+endmodule
diff --git a/docs/source/APPNOTE_011_Design_Investigation/make.sh b/docs/source/APPNOTE_011_Design_Investigation/make.sh
new file mode 100644
index 000000000..3845dac6b
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/make.sh
@@ -0,0 +1,23 @@
+#!/bin/bash
+set -ex
+if false; then
+	rm -f *.dot
+	../../yosys example.ys
+	../../yosys -p 'proc; opt; show -format dot -prefix splice' splice.v
+	../../yosys -p 'techmap; abc -liberty ../../techlibs/cmos/cmos_cells.lib;; show -format dot -prefix cmos_00' cmos.v
+	../../yosys -p 'techmap; splitnets -ports; abc -liberty ../../techlibs/cmos/cmos_cells.lib;; show -lib ../../techlibs/cmos/cmos_cells.v -format dot -prefix cmos_01' cmos.v
+	../../yosys -p 'opt; cd sumprod; select a:sumstuff; show -format dot -prefix sumprod_00' sumprod.v
+	../../yosys -p 'opt; cd sumprod; select a:sumstuff %x; show -format dot -prefix sumprod_01' sumprod.v
+	../../yosys -p 'opt; cd sumprod; select prod; show -format dot -prefix sumprod_02' sumprod.v
+	../../yosys -p 'opt; cd sumprod; select prod %ci; show -format dot -prefix sumprod_03' sumprod.v
+	../../yosys -p 'opt; cd sumprod; select prod %ci2; show -format dot -prefix sumprod_04' sumprod.v
+	../../yosys -p 'opt; cd sumprod; select prod %ci3; show -format dot -prefix sumprod_05' sumprod.v
+	../../yosys -p 'proc; opt; memory; opt; cd memdemo; show -format dot -prefix memdemo_00' memdemo.v
+	../../yosys -p 'proc; opt; memory; opt; cd memdemo; show -format dot -prefix memdemo_01 y %ci2:+$dff[Q,D] %ci*:-$mux[S]:-$dff' memdemo.v
+	../../yosys submod.ys
+	sed -i '/^label=/ d;' *.dot
+fi
+for dot_file in *.dot; do
+	pdf_file=${dot_file%.dot}.pdf
+	dot -Tpdf -o $pdf_file $dot_file
+done
diff --git a/docs/source/APPNOTE_011_Design_Investigation/memdemo.v b/docs/source/APPNOTE_011_Design_Investigation/memdemo.v
new file mode 100644
index 000000000..b39564ddc
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/memdemo.v
@@ -0,0 +1,19 @@
+module memdemo(clk, d, y);
+
+input clk;
+input [3:0] d;
+output reg [3:0] y;
+
+integer i;
+reg [1:0] s1, s2;
+reg [3:0] mem [0:3];
+
+always @(posedge clk) begin
+    for (i = 0; i < 4; i = i+1)
+        mem[i] <= mem[(i+1) % 4] + mem[(i+2) % 4];
+    { s2, s1 } = d ? { s1, s2 } ^ d : 4'b0;
+    mem[s1] <= d;
+    y <= mem[s2];
+end
+
+endmodule
diff --git a/docs/source/APPNOTE_011_Design_Investigation/memdemo_00.dot b/docs/source/APPNOTE_011_Design_Investigation/memdemo_00.dot
new file mode 100644
index 000000000..0336a9aac
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/memdemo_00.dot
@@ -0,0 +1,138 @@
+digraph "memdemo" {
+rankdir="LR";
+remincross=true;
+n24 [ shape=octagon, label="clk", color="black", fontcolor="black" ];
+n25 [ shape=octagon, label="d", color="black", fontcolor="black" ];
+n26 [ shape=diamond, label="mem[0]", color="black", fontcolor="black" ];
+n27 [ shape=diamond, label="mem[1]", color="black", fontcolor="black" ];
+n28 [ shape=diamond, label="mem[2]", color="black", fontcolor="black" ];
+n29 [ shape=diamond, label="mem[3]", color="black", fontcolor="black" ];
+n30 [ shape=diamond, label="s1", color="black", fontcolor="black" ];
+n31 [ shape=diamond, label="s2", color="black", fontcolor="black" ];
+n32 [ shape=octagon, label="y", color="black", fontcolor="black" ];
+c36 [ shape=record, label="{{<p33> A|<p34> B}|$28\n$add|{<p35> Y}}" ];
+c37 [ shape=record, label="{{<p33> A|<p34> B}|$31\n$add|{<p35> Y}}" ];
+c38 [ shape=record, label="{{<p33> A|<p34> B}|$34\n$add|{<p35> Y}}" ];
+c39 [ shape=record, label="{{<p33> A|<p34> B}|$37\n$add|{<p35> Y}}" ];
+c41 [ shape=record, label="{{<p33> A|<p34> B|<p40> S}|$110\n$mux|{<p35> Y}}" ];
+x0 [ shape=record, style=rounded, label="<s0> 1:1 - 0:0 " ];
+x0:e -> c41:p40:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", label=""];
+c42 [ shape=record, label="{{<p33> A|<p34> B|<p40> S}|$113\n$mux|{<p35> Y}}" ];
+x1 [ shape=record, style=rounded, label="<s0> 0:0 - 0:0 " ];
+x1:e -> c42:p40:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", label=""];
+c43 [ shape=record, label="{{<p33> A|<p34> B|<p40> S}|$116\n$mux|{<p35> Y}}" ];
+x2 [ shape=record, style=rounded, label="<s0> 0:0 - 0:0 " ];
+x2:e -> c43:p40:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", label=""];
+v3 [ label="1'1" ];
+c44 [ shape=record, label="{{<p33> A|<p34> B}|$145\n$and|{<p35> Y}}" ];
+v4 [ label="1'1" ];
+c45 [ shape=record, label="{{<p33> A|<p34> B}|$175\n$and|{<p35> Y}}" ];
+v5 [ label="1'1" ];
+c46 [ shape=record, label="{{<p33> A|<p34> B}|$205\n$and|{<p35> Y}}" ];
+v6 [ label="1'1" ];
+c47 [ shape=record, label="{{<p33> A|<p34> B}|$235\n$and|{<p35> Y}}" ];
+v7 [ label="2'00" ];
+c48 [ shape=record, label="{{<p33> A|<p34> B}|$143\n$eq|{<p35> Y}}" ];
+v8 [ label="2'01" ];
+c49 [ shape=record, label="{{<p33> A|<p34> B}|$173\n$eq|{<p35> Y}}" ];
+v9 [ label="2'10" ];
+c50 [ shape=record, label="{{<p33> A|<p34> B}|$203\n$eq|{<p35> Y}}" ];
+v10 [ label="2'11" ];
+c51 [ shape=record, label="{{<p33> A|<p34> B}|$233\n$eq|{<p35> Y}}" ];
+c52 [ shape=record, label="{{<p33> A|<p34> B|<p40> S}|$147\n$mux|{<p35> Y}}" ];
+c53 [ shape=record, label="{{<p33> A|<p34> B|<p40> S}|$177\n$mux|{<p35> Y}}" ];
+c54 [ shape=record, label="{{<p33> A|<p34> B|<p40> S}|$207\n$mux|{<p35> Y}}" ];
+c55 [ shape=record, label="{{<p33> A|<p34> B|<p40> S}|$237\n$mux|{<p35> Y}}" ];
+c59 [ shape=record, label="{{<p56> CLK|<p57> D}|$66\n$dff|{<p58> Q}}" ];
+c60 [ shape=record, label="{{<p56> CLK|<p57> D}|$68\n$dff|{<p58> Q}}" ];
+c61 [ shape=record, label="{{<p56> CLK|<p57> D}|$70\n$dff|{<p58> Q}}" ];
+c62 [ shape=record, label="{{<p56> CLK|<p57> D}|$72\n$dff|{<p58> Q}}" ];
+c63 [ shape=record, label="{{<p56> CLK|<p57> D}|$59\n$dff|{<p58> Q}}" ];
+c64 [ shape=record, label="{{<p56> CLK|<p57> D}|$63\n$dff|{<p58> Q}}" ];
+c65 [ shape=record, label="{{<p56> CLK|<p57> D}|$64\n$dff|{<p58> Q}}" ];
+c66 [ shape=record, label="{{<p33> A}|$39\n$reduce_bool|{<p35> Y}}" ];
+v11 [ label="4'0000" ];
+c67 [ shape=record, label="{{<p33> A|<p34> B|<p40> S}|$40\n$mux|{<p35> Y}}" ];
+x12 [ shape=record, style=rounded, label="<s1> 3:2 - 1:0 |<s0> 1:0 - 1:0 " ];
+c67:p35:e -> x12:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", style="setlinewidth(3)", label=""];
+c68 [ shape=record, label="{{<p33> A|<p34> B}|$38\n$xor|{<p35> Y}}" ];
+x13 [ shape=record, style=rounded, label="<s1> 1:0 - 3:2 |<s0> 1:0 - 1:0 " ];
+x13:e -> c68:p33:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", style="setlinewidth(3)", label=""];
+c36:p35:e -> c52:p33:w [color="black", style="setlinewidth(3)", label=""];
+c44:p35:e -> c52:p40:w [color="black", label=""];
+c45:p35:e -> c53:p40:w [color="black", label=""];
+c46:p35:e -> c54:p40:w [color="black", label=""];
+c47:p35:e -> c55:p40:w [color="black", label=""];
+c48:p35:e -> c44:p33:w [color="black", label=""];
+c49:p35:e -> c45:p33:w [color="black", label=""];
+c50:p35:e -> c46:p33:w [color="black", label=""];
+c51:p35:e -> c47:p33:w [color="black", label=""];
+c52:p35:e -> c59:p57:w [color="black", style="setlinewidth(3)", label=""];
+c53:p35:e -> c60:p57:w [color="black", style="setlinewidth(3)", label=""];
+c37:p35:e -> c53:p33:w [color="black", style="setlinewidth(3)", label=""];
+c54:p35:e -> c61:p57:w [color="black", style="setlinewidth(3)", label=""];
+c55:p35:e -> c62:p57:w [color="black", style="setlinewidth(3)", label=""];
+c66:p35:e -> c67:p40:w [color="black", label=""];
+c68:p35:e -> c67:p34:w [color="black", style="setlinewidth(3)", label=""];
+n24:e -> c59:p56:w [color="black", label=""];
+n24:e -> c60:p56:w [color="black", label=""];
+n24:e -> c61:p56:w [color="black", label=""];
+n24:e -> c62:p56:w [color="black", label=""];
+n24:e -> c63:p56:w [color="black", label=""];
+n24:e -> c64:p56:w [color="black", label=""];
+n24:e -> c65:p56:w [color="black", label=""];
+n25:e -> c52:p34:w [color="black", style="setlinewidth(3)", label=""];
+n25:e -> c53:p34:w [color="black", style="setlinewidth(3)", label=""];
+n25:e -> c54:p34:w [color="black", style="setlinewidth(3)", label=""];
+n25:e -> c55:p34:w [color="black", style="setlinewidth(3)", label=""];
+n25:e -> c66:p33:w [color="black", style="setlinewidth(3)", label=""];
+n25:e -> c68:p34:w [color="black", style="setlinewidth(3)", label=""];
+c59:p58:e -> n26:w [color="black", style="setlinewidth(3)", label=""];
+n26:e -> c38:p34:w [color="black", style="setlinewidth(3)", label=""];
+n26:e -> c39:p33:w [color="black", style="setlinewidth(3)", label=""];
+n26:e -> c42:p33:w [color="black", style="setlinewidth(3)", label=""];
+c60:p58:e -> n27:w [color="black", style="setlinewidth(3)", label=""];
+n27:e -> c36:p33:w [color="black", style="setlinewidth(3)", label=""];
+n27:e -> c39:p34:w [color="black", style="setlinewidth(3)", label=""];
+n27:e -> c42:p34:w [color="black", style="setlinewidth(3)", label=""];
+c61:p58:e -> n28:w [color="black", style="setlinewidth(3)", label=""];
+n28:e -> c36:p34:w [color="black", style="setlinewidth(3)", label=""];
+n28:e -> c37:p33:w [color="black", style="setlinewidth(3)", label=""];
+n28:e -> c43:p33:w [color="black", style="setlinewidth(3)", label=""];
+c62:p58:e -> n29:w [color="black", style="setlinewidth(3)", label=""];
+n29:e -> c37:p34:w [color="black", style="setlinewidth(3)", label=""];
+n29:e -> c38:p33:w [color="black", style="setlinewidth(3)", label=""];
+n29:e -> c43:p34:w [color="black", style="setlinewidth(3)", label=""];
+c38:p35:e -> c54:p33:w [color="black", style="setlinewidth(3)", label=""];
+c63:p58:e -> n30:w [color="black", style="setlinewidth(3)", label=""];
+n30:e -> x13:s1:w [color="black", style="setlinewidth(3)", label=""];
+c64:p58:e -> n31:w [color="black", style="setlinewidth(3)", label=""];
+n31:e -> x13:s0:w [color="black", style="setlinewidth(3)", label=""];
+c65:p58:e -> n32:w [color="black", style="setlinewidth(3)", label=""];
+c39:p35:e -> c55:p33:w [color="black", style="setlinewidth(3)", label=""];
+n5 [ shape=point ];
+x12:s0:e -> n5:w [color="black", style="setlinewidth(3)", label=""];
+n5:e -> c48:p34:w [color="black", style="setlinewidth(3)", label=""];
+n5:e -> c49:p34:w [color="black", style="setlinewidth(3)", label=""];
+n5:e -> c50:p34:w [color="black", style="setlinewidth(3)", label=""];
+n5:e -> c51:p34:w [color="black", style="setlinewidth(3)", label=""];
+n5:e -> c63:p57:w [color="black", style="setlinewidth(3)", label=""];
+n6 [ shape=point ];
+x12:s1:e -> n6:w [color="black", style="setlinewidth(3)", label=""];
+n6:e -> c64:p57:w [color="black", style="setlinewidth(3)", label=""];
+n6:e -> x0:s0:w [color="black", style="setlinewidth(3)", label=""];
+n6:e -> x1:s0:w [color="black", style="setlinewidth(3)", label=""];
+n6:e -> x2:s0:w [color="black", style="setlinewidth(3)", label=""];
+c41:p35:e -> c65:p57:w [color="black", style="setlinewidth(3)", label=""];
+c42:p35:e -> c41:p33:w [color="black", style="setlinewidth(3)", label=""];
+c43:p35:e -> c41:p34:w [color="black", style="setlinewidth(3)", label=""];
+v10:e -> c51:p33:w [color="black", style="setlinewidth(3)", label=""];
+v11:e -> c67:p33:w [color="black", style="setlinewidth(3)", label=""];
+v3:e -> c44:p34:w [color="black", label=""];
+v4:e -> c45:p34:w [color="black", label=""];
+v5:e -> c46:p34:w [color="black", label=""];
+v6:e -> c47:p34:w [color="black", label=""];
+v7:e -> c48:p33:w [color="black", style="setlinewidth(3)", label=""];
+v8:e -> c49:p33:w [color="black", style="setlinewidth(3)", label=""];
+v9:e -> c50:p33:w [color="black", style="setlinewidth(3)", label=""];
+}
diff --git a/docs/source/APPNOTE_011_Design_Investigation/memdemo_01.dot b/docs/source/APPNOTE_011_Design_Investigation/memdemo_01.dot
new file mode 100644
index 000000000..2ad92c78b
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/memdemo_01.dot
@@ -0,0 +1,29 @@
+digraph "memdemo" {
+rankdir="LR";
+remincross=true;
+n4 [ shape=diamond, label="mem[0]", color="black", fontcolor="black" ];
+n5 [ shape=diamond, label="mem[1]", color="black", fontcolor="black" ];
+n6 [ shape=diamond, label="mem[2]", color="black", fontcolor="black" ];
+n7 [ shape=diamond, label="mem[3]", color="black", fontcolor="black" ];
+n8 [ shape=octagon, label="y", color="black", fontcolor="black" ];
+v0 [ label="$0\\s2[1:0] [1]" ];
+c13 [ shape=record, label="{{<p9> A|<p10> B|<p11> S}|$110\n$mux|{<p12> Y}}" ];
+v1 [ label="$0\\s2[1:0] [0]" ];
+c14 [ shape=record, label="{{<p9> A|<p10> B|<p11> S}|$113\n$mux|{<p12> Y}}" ];
+v2 [ label="$0\\s2[1:0] [0]" ];
+c15 [ shape=record, label="{{<p9> A|<p10> B|<p11> S}|$116\n$mux|{<p12> Y}}" ];
+v3 [ label="clk" ];
+c19 [ shape=record, label="{{<p16> CLK|<p17> D}|$64\n$dff|{<p18> Q}}" ];
+c13:p12:e -> c19:p17:w [color="black", style="setlinewidth(3)", label=""];
+c14:p12:e -> c13:p9:w [color="black", style="setlinewidth(3)", label=""];
+c15:p12:e -> c13:p10:w [color="black", style="setlinewidth(3)", label=""];
+n4:e -> c14:p9:w [color="black", style="setlinewidth(3)", label=""];
+n5:e -> c14:p10:w [color="black", style="setlinewidth(3)", label=""];
+n6:e -> c15:p9:w [color="black", style="setlinewidth(3)", label=""];
+n7:e -> c15:p10:w [color="black", style="setlinewidth(3)", label=""];
+c19:p18:e -> n8:w [color="black", style="setlinewidth(3)", label=""];
+v0:e -> c13:p11:w [color="black", label=""];
+v1:e -> c14:p11:w [color="black", label=""];
+v2:e -> c15:p11:w [color="black", label=""];
+v3:e -> c19:p16:w [color="black", label=""];
+}
diff --git a/docs/source/APPNOTE_011_Design_Investigation/primetest.v b/docs/source/APPNOTE_011_Design_Investigation/primetest.v
new file mode 100644
index 000000000..6cb766b73
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/primetest.v
@@ -0,0 +1,4 @@
+module primetest(p, a, b, ok);
+input [15:0] p, a, b;
+output ok = p != a*b || a == 1 || b == 1;
+endmodule
diff --git a/docs/source/APPNOTE_011_Design_Investigation/splice.dot b/docs/source/APPNOTE_011_Design_Investigation/splice.dot
new file mode 100644
index 000000000..4657feed1
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/splice.dot
@@ -0,0 +1,39 @@
+digraph "splice_demo" {
+rankdir="LR";
+remincross=true;
+n1 [ shape=octagon, label="a", color="black", fontcolor="black" ];
+n2 [ shape=octagon, label="b", color="black", fontcolor="black" ];
+n3 [ shape=octagon, label="c", color="black", fontcolor="black" ];
+n4 [ shape=octagon, label="d", color="black", fontcolor="black" ];
+n5 [ shape=octagon, label="e", color="black", fontcolor="black" ];
+n6 [ shape=octagon, label="f", color="black", fontcolor="black" ];
+n7 [ shape=octagon, label="x", color="black", fontcolor="black" ];
+n8 [ shape=octagon, label="y", color="black", fontcolor="black" ];
+c11 [ shape=record, label="{{<p9> A}|$2\n$neg|{<p10> Y}}" ];
+x0 [ shape=record, style=rounded, label="<s1> 1:0 - 3:2 |<s0> 1:0 - 1:0 " ];
+x0:e -> c11:p9:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", style="setlinewidth(3)", label=""];
+x1 [ shape=record, style=rounded, label="<s0> 3:0 - 7:4 " ];
+c11:p10:e -> x1:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", style="setlinewidth(3)", label=""];
+c12 [ shape=record, label="{{<p9> A}|$1\n$not|{<p10> Y}}" ];
+x2 [ shape=record, style=rounded, label="<s1> 1:0 - 3:2 |<s0> 1:0 - 1:0 " ];
+x2:e -> c12:p9:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", style="setlinewidth(3)", label=""];
+x3 [ shape=record, style=rounded, label="<s1> 3:2 - 1:0 |<s0> 1:0 - 3:2 " ];
+c12:p10:e -> x3:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", style="setlinewidth(3)", label=""];
+x4 [ shape=record, style=rounded, label="<s1> 0:0 - 1:1 |<s0> 1:1 - 0:0 " ];
+x5 [ shape=record, style=rounded, label="<s1> 1:0 - 3:2 |<s0> 1:0 - 1:0 " ];
+x6 [ shape=record, style=rounded, label="<s0> 3:0 - 11:8 " ];
+x5:e -> x6:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", style="setlinewidth(3)", label=""];
+n1:e -> x4:s0:w [color="black", style="setlinewidth(3)", label=""];
+n1:e -> x4:s1:w [color="black", style="setlinewidth(3)", label=""];
+n1:e -> x5:s1:w [color="black", style="setlinewidth(3)", label=""];
+n2:e -> x5:s0:w [color="black", style="setlinewidth(3)", label=""];
+n3:e -> x0:s1:w [color="black", style="setlinewidth(3)", label=""];
+n4:e -> x0:s0:w [color="black", style="setlinewidth(3)", label=""];
+n5:e -> x2:s1:w [color="black", style="setlinewidth(3)", label=""];
+n6:e -> x2:s0:w [color="black", style="setlinewidth(3)", label=""];
+x4:e -> n7:w [color="black", style="setlinewidth(3)", label=""];
+x1:s0:e -> n8:w [color="black", style="setlinewidth(3)", label=""];
+x3:s0:e -> n8:w [color="black", style="setlinewidth(3)", label=""];
+x3:s1:e -> n8:w [color="black", style="setlinewidth(3)", label=""];
+x6:s0:e -> n8:w [color="black", style="setlinewidth(3)", label=""];
+}
diff --git a/docs/source/APPNOTE_011_Design_Investigation/splice.v b/docs/source/APPNOTE_011_Design_Investigation/splice.v
new file mode 100644
index 000000000..1cf7274c0
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/splice.v
@@ -0,0 +1,10 @@
+module splice_demo(a, b, c, d, e, f, x, y);
+
+input [1:0] a, b, c, d, e, f;
+output [1:0] x = {a[0], a[1]};
+
+output [11:0] y;
+assign {y[11:4], y[1:0], y[3:2]} =
+                {a, b, -{c, d}, ~{e, f}};
+
+endmodule
diff --git a/docs/source/APPNOTE_011_Design_Investigation/submod.ys b/docs/source/APPNOTE_011_Design_Investigation/submod.ys
new file mode 100644
index 000000000..29ad61076
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/submod.ys
@@ -0,0 +1,16 @@
+read_verilog memdemo.v
+proc; opt; memory; opt
+
+cd memdemo
+select -set outstage y %ci2:+$dff[Q,D] %ci*:-$mux[S]:-$dff
+select -set selstage y %ci2:+$dff[Q,D] %ci*:-$dff @outstage %d
+select -set scramble mem* %ci2 %ci*:-$dff mem* %d @selstage %d
+submod -name scramble @scramble
+submod -name outstage @outstage
+submod -name selstage @selstage
+
+cd ..
+show -format dot -prefix submod_00 memdemo
+show -format dot -prefix submod_01 scramble
+show -format dot -prefix submod_02 outstage
+show -format dot -prefix submod_03 selstage
diff --git a/docs/source/APPNOTE_011_Design_Investigation/submod_00.dot b/docs/source/APPNOTE_011_Design_Investigation/submod_00.dot
new file mode 100644
index 000000000..2e55268ee
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/submod_00.dot
@@ -0,0 +1,45 @@
+digraph "memdemo" {
+rankdir="LR";
+remincross=true;
+n5 [ shape=octagon, label="clk", color="black", fontcolor="black" ];
+n6 [ shape=octagon, label="d", color="black", fontcolor="black" ];
+n7 [ shape=diamond, label="mem[0]", color="black", fontcolor="black" ];
+n8 [ shape=diamond, label="mem[1]", color="black", fontcolor="black" ];
+n9 [ shape=diamond, label="mem[2]", color="black", fontcolor="black" ];
+n10 [ shape=diamond, label="mem[3]", color="black", fontcolor="black" ];
+n11 [ shape=diamond, label="s1", color="black", fontcolor="black" ];
+n12 [ shape=diamond, label="s2", color="black", fontcolor="black" ];
+n13 [ shape=octagon, label="y", color="black", fontcolor="black" ];
+c17 [ shape=record, label="{{<p14> CLK|<p15> D}|$59\n$dff|{<p16> Q}}" ];
+c18 [ shape=record, label="{{<p14> CLK|<p15> D}|$63\n$dff|{<p16> Q}}" ];
+c20 [ shape=record, label="{{<p5> clk|<p7> mem[0]|<p8> mem[1]|<p9> mem[2]|<p10> mem[3]|<p19> n1}|outstage\noutstage|{<p13> y}}" ];
+c21 [ shape=record, label="{{<p5> clk|<p6> d|<p19> n1}|scramble\nscramble|{<p7> mem[0]|<p8> mem[1]|<p9> mem[2]|<p10> mem[3]}}" ];
+c23 [ shape=record, label="{{<p6> d|<p11> s1|<p12> s2}|selstage\nselstage|{<p19> n1|<p22> n2}}" ];
+n1 [ shape=point ];
+c23:p19:e -> n1:w [color="black", style="setlinewidth(3)", label=""];
+n1:e -> c17:p15:w [color="black", style="setlinewidth(3)", label=""];
+n1:e -> c21:p19:w [color="black", style="setlinewidth(3)", label=""];
+c21:p10:e -> n10:w [color="black", style="setlinewidth(3)", label=""];
+n10:e -> c20:p10:w [color="black", style="setlinewidth(3)", label=""];
+c17:p16:e -> n11:w [color="black", style="setlinewidth(3)", label=""];
+n11:e -> c23:p11:w [color="black", style="setlinewidth(3)", label=""];
+c18:p16:e -> n12:w [color="black", style="setlinewidth(3)", label=""];
+n12:e -> c23:p12:w [color="black", style="setlinewidth(3)", label=""];
+c20:p13:e -> n13:w [color="black", style="setlinewidth(3)", label=""];
+n2 [ shape=point ];
+c23:p22:e -> n2:w [color="black", style="setlinewidth(3)", label=""];
+n2:e -> c18:p15:w [color="black", style="setlinewidth(3)", label=""];
+n2:e -> c20:p19:w [color="black", style="setlinewidth(3)", label=""];
+n5:e -> c17:p14:w [color="black", label=""];
+n5:e -> c18:p14:w [color="black", label=""];
+n5:e -> c20:p5:w [color="black", label=""];
+n5:e -> c21:p5:w [color="black", label=""];
+n6:e -> c21:p6:w [color="black", style="setlinewidth(3)", label=""];
+n6:e -> c23:p6:w [color="black", style="setlinewidth(3)", label=""];
+c21:p7:e -> n7:w [color="black", style="setlinewidth(3)", label=""];
+n7:e -> c20:p7:w [color="black", style="setlinewidth(3)", label=""];
+c21:p8:e -> n8:w [color="black", style="setlinewidth(3)", label=""];
+n8:e -> c20:p8:w [color="black", style="setlinewidth(3)", label=""];
+c21:p9:e -> n9:w [color="black", style="setlinewidth(3)", label=""];
+n9:e -> c20:p9:w [color="black", style="setlinewidth(3)", label=""];
+}
diff --git a/docs/source/APPNOTE_011_Design_Investigation/submod_01.dot b/docs/source/APPNOTE_011_Design_Investigation/submod_01.dot
new file mode 100644
index 000000000..f8f8c008a
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/submod_01.dot
@@ -0,0 +1,87 @@
+digraph "scramble" {
+rankdir="LR";
+remincross=true;
+n17 [ shape=octagon, label="clk", color="black", fontcolor="black" ];
+n18 [ shape=octagon, label="d", color="black", fontcolor="black" ];
+n19 [ shape=octagon, label="mem[0]", color="black", fontcolor="black" ];
+n20 [ shape=octagon, label="mem[1]", color="black", fontcolor="black" ];
+n21 [ shape=octagon, label="mem[2]", color="black", fontcolor="black" ];
+n22 [ shape=octagon, label="mem[3]", color="black", fontcolor="black" ];
+n23 [ shape=octagon, label="n1", color="black", fontcolor="black" ];
+c27 [ shape=record, label="{{<p24> A|<p25> B}|$28\n$add|{<p26> Y}}" ];
+c28 [ shape=record, label="{{<p24> A|<p25> B}|$31\n$add|{<p26> Y}}" ];
+c29 [ shape=record, label="{{<p24> A|<p25> B}|$34\n$add|{<p26> Y}}" ];
+c30 [ shape=record, label="{{<p24> A|<p25> B}|$37\n$add|{<p26> Y}}" ];
+v0 [ label="1'1" ];
+c31 [ shape=record, label="{{<p24> A|<p25> B}|$145\n$and|{<p26> Y}}" ];
+v1 [ label="1'1" ];
+c32 [ shape=record, label="{{<p24> A|<p25> B}|$175\n$and|{<p26> Y}}" ];
+v2 [ label="1'1" ];
+c33 [ shape=record, label="{{<p24> A|<p25> B}|$205\n$and|{<p26> Y}}" ];
+v3 [ label="1'1" ];
+c34 [ shape=record, label="{{<p24> A|<p25> B}|$235\n$and|{<p26> Y}}" ];
+v4 [ label="2'00" ];
+c35 [ shape=record, label="{{<p24> A|<p25> B}|$143\n$eq|{<p26> Y}}" ];
+v5 [ label="2'01" ];
+c36 [ shape=record, label="{{<p24> A|<p25> B}|$173\n$eq|{<p26> Y}}" ];
+v6 [ label="2'10" ];
+c37 [ shape=record, label="{{<p24> A|<p25> B}|$203\n$eq|{<p26> Y}}" ];
+v7 [ label="2'11" ];
+c38 [ shape=record, label="{{<p24> A|<p25> B}|$233\n$eq|{<p26> Y}}" ];
+c40 [ shape=record, label="{{<p24> A|<p25> B|<p39> S}|$147\n$mux|{<p26> Y}}" ];
+c41 [ shape=record, label="{{<p24> A|<p25> B|<p39> S}|$177\n$mux|{<p26> Y}}" ];
+c42 [ shape=record, label="{{<p24> A|<p25> B|<p39> S}|$207\n$mux|{<p26> Y}}" ];
+c43 [ shape=record, label="{{<p24> A|<p25> B|<p39> S}|$237\n$mux|{<p26> Y}}" ];
+c47 [ shape=record, label="{{<p44> CLK|<p45> D}|$66\n$dff|{<p46> Q}}" ];
+c48 [ shape=record, label="{{<p44> CLK|<p45> D}|$68\n$dff|{<p46> Q}}" ];
+c49 [ shape=record, label="{{<p44> CLK|<p45> D}|$70\n$dff|{<p46> Q}}" ];
+c50 [ shape=record, label="{{<p44> CLK|<p45> D}|$72\n$dff|{<p46> Q}}" ];
+c27:p26:e -> c40:p24:w [color="black", style="setlinewidth(3)", label=""];
+c36:p26:e -> c32:p24:w [color="black", label=""];
+c37:p26:e -> c33:p24:w [color="black", label=""];
+c38:p26:e -> c34:p24:w [color="black", label=""];
+c40:p26:e -> c47:p45:w [color="black", style="setlinewidth(3)", label=""];
+c41:p26:e -> c48:p45:w [color="black", style="setlinewidth(3)", label=""];
+c42:p26:e -> c49:p45:w [color="black", style="setlinewidth(3)", label=""];
+c43:p26:e -> c50:p45:w [color="black", style="setlinewidth(3)", label=""];
+n17:e -> c47:p44:w [color="black", label=""];
+n17:e -> c48:p44:w [color="black", label=""];
+n17:e -> c49:p44:w [color="black", label=""];
+n17:e -> c50:p44:w [color="black", label=""];
+n18:e -> c40:p25:w [color="black", style="setlinewidth(3)", label=""];
+n18:e -> c41:p25:w [color="black", style="setlinewidth(3)", label=""];
+n18:e -> c42:p25:w [color="black", style="setlinewidth(3)", label=""];
+n18:e -> c43:p25:w [color="black", style="setlinewidth(3)", label=""];
+c47:p46:e -> n19:w [color="black", style="setlinewidth(3)", label=""];
+n19:e -> c29:p25:w [color="black", style="setlinewidth(3)", label=""];
+n19:e -> c30:p24:w [color="black", style="setlinewidth(3)", label=""];
+c28:p26:e -> c41:p24:w [color="black", style="setlinewidth(3)", label=""];
+c48:p46:e -> n20:w [color="black", style="setlinewidth(3)", label=""];
+n20:e -> c27:p24:w [color="black", style="setlinewidth(3)", label=""];
+n20:e -> c30:p25:w [color="black", style="setlinewidth(3)", label=""];
+c49:p46:e -> n21:w [color="black", style="setlinewidth(3)", label=""];
+n21:e -> c27:p25:w [color="black", style="setlinewidth(3)", label=""];
+n21:e -> c28:p24:w [color="black", style="setlinewidth(3)", label=""];
+c50:p46:e -> n22:w [color="black", style="setlinewidth(3)", label=""];
+n22:e -> c28:p25:w [color="black", style="setlinewidth(3)", label=""];
+n22:e -> c29:p24:w [color="black", style="setlinewidth(3)", label=""];
+n23:e -> c35:p25:w [color="black", style="setlinewidth(3)", label=""];
+n23:e -> c36:p25:w [color="black", style="setlinewidth(3)", label=""];
+n23:e -> c37:p25:w [color="black", style="setlinewidth(3)", label=""];
+n23:e -> c38:p25:w [color="black", style="setlinewidth(3)", label=""];
+c29:p26:e -> c42:p24:w [color="black", style="setlinewidth(3)", label=""];
+c30:p26:e -> c43:p24:w [color="black", style="setlinewidth(3)", label=""];
+c31:p26:e -> c40:p39:w [color="black", label=""];
+c32:p26:e -> c41:p39:w [color="black", label=""];
+c33:p26:e -> c42:p39:w [color="black", label=""];
+c34:p26:e -> c43:p39:w [color="black", label=""];
+c35:p26:e -> c31:p24:w [color="black", label=""];
+v0:e -> c31:p25:w [color="black", label=""];
+v1:e -> c32:p25:w [color="black", label=""];
+v2:e -> c33:p25:w [color="black", label=""];
+v3:e -> c34:p25:w [color="black", label=""];
+v4:e -> c35:p24:w [color="black", style="setlinewidth(3)", label=""];
+v5:e -> c36:p24:w [color="black", style="setlinewidth(3)", label=""];
+v6:e -> c37:p24:w [color="black", style="setlinewidth(3)", label=""];
+v7:e -> c38:p24:w [color="black", style="setlinewidth(3)", label=""];
+}
diff --git a/docs/source/APPNOTE_011_Design_Investigation/submod_02.dot b/docs/source/APPNOTE_011_Design_Investigation/submod_02.dot
new file mode 100644
index 000000000..1a672c484
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/submod_02.dot
@@ -0,0 +1,33 @@
+digraph "outstage" {
+rankdir="LR";
+remincross=true;
+n4 [ shape=octagon, label="clk", color="black", fontcolor="black" ];
+n5 [ shape=octagon, label="mem[0]", color="black", fontcolor="black" ];
+n6 [ shape=octagon, label="mem[1]", color="black", fontcolor="black" ];
+n7 [ shape=octagon, label="mem[2]", color="black", fontcolor="black" ];
+n8 [ shape=octagon, label="mem[3]", color="black", fontcolor="black" ];
+n9 [ shape=octagon, label="n1", color="black", fontcolor="black" ];
+n10 [ shape=octagon, label="y", color="black", fontcolor="black" ];
+c15 [ shape=record, label="{{<p11> A|<p12> B|<p13> S}|$110\n$mux|{<p14> Y}}" ];
+x0 [ shape=record, style=rounded, label="<s0> 1:1 - 0:0 " ];
+x0:e -> c15:p13:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", label=""];
+c16 [ shape=record, label="{{<p11> A|<p12> B|<p13> S}|$113\n$mux|{<p14> Y}}" ];
+x1 [ shape=record, style=rounded, label="<s0> 0:0 - 0:0 " ];
+x1:e -> c16:p13:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", label=""];
+c17 [ shape=record, label="{{<p11> A|<p12> B|<p13> S}|$116\n$mux|{<p14> Y}}" ];
+x2 [ shape=record, style=rounded, label="<s0> 0:0 - 0:0 " ];
+x2:e -> c17:p13:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", label=""];
+c21 [ shape=record, label="{{<p18> CLK|<p19> D}|$64\n$dff|{<p20> Q}}" ];
+c15:p14:e -> c21:p19:w [color="black", style="setlinewidth(3)", label=""];
+c21:p20:e -> n10:w [color="black", style="setlinewidth(3)", label=""];
+c16:p14:e -> c15:p11:w [color="black", style="setlinewidth(3)", label=""];
+c17:p14:e -> c15:p12:w [color="black", style="setlinewidth(3)", label=""];
+n4:e -> c21:p18:w [color="black", label=""];
+n5:e -> c16:p11:w [color="black", style="setlinewidth(3)", label=""];
+n6:e -> c16:p12:w [color="black", style="setlinewidth(3)", label=""];
+n7:e -> c17:p11:w [color="black", style="setlinewidth(3)", label=""];
+n8:e -> c17:p12:w [color="black", style="setlinewidth(3)", label=""];
+n9:e -> x0:s0:w [color="black", label=""];
+n9:e -> x1:s0:w [color="black", label=""];
+n9:e -> x2:s0:w [color="black", label=""];
+}
diff --git a/docs/source/APPNOTE_011_Design_Investigation/submod_03.dot b/docs/source/APPNOTE_011_Design_Investigation/submod_03.dot
new file mode 100644
index 000000000..0dbbe3baa
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/submod_03.dot
@@ -0,0 +1,26 @@
+digraph "selstage" {
+rankdir="LR";
+remincross=true;
+n3 [ shape=octagon, label="d", color="black", fontcolor="black" ];
+n4 [ shape=octagon, label="n1", color="black", fontcolor="black" ];
+n5 [ shape=octagon, label="n2", color="black", fontcolor="black" ];
+n6 [ shape=octagon, label="s1", color="black", fontcolor="black" ];
+n7 [ shape=octagon, label="s2", color="black", fontcolor="black" ];
+c10 [ shape=record, label="{{<p8> A}|$39\n$reduce_bool|{<p9> Y}}" ];
+v0 [ label="4'0000" ];
+c13 [ shape=record, label="{{<p8> A|<p11> B|<p12> S}|$40\n$mux|{<p9> Y}}" ];
+x1 [ shape=record, style=rounded, label="<s1> 3:2 - 1:0 |<s0> 1:0 - 1:0 " ];
+c13:p9:e -> x1:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", style="setlinewidth(3)", label=""];
+c14 [ shape=record, label="{{<p8> A|<p11> B}|$38\n$xor|{<p9> Y}}" ];
+x2 [ shape=record, style=rounded, label="<s1> 1:0 - 3:2 |<s0> 1:0 - 1:0 " ];
+x2:e -> c14:p8:w [arrowhead=odiamond, arrowtail=odiamond, dir=both, color="black", style="setlinewidth(3)", label=""];
+c10:p9:e -> c13:p12:w [color="black", label=""];
+c14:p9:e -> c13:p11:w [color="black", style="setlinewidth(3)", label=""];
+n3:e -> c10:p8:w [color="black", style="setlinewidth(3)", label=""];
+n3:e -> c14:p11:w [color="black", style="setlinewidth(3)", label=""];
+x1:s0:e -> n4:w [color="black", style="setlinewidth(3)", label=""];
+x1:s1:e -> n5:w [color="black", style="setlinewidth(3)", label=""];
+n6:e -> x2:s1:w [color="black", style="setlinewidth(3)", label=""];
+n7:e -> x2:s0:w [color="black", style="setlinewidth(3)", label=""];
+v0:e -> c13:p8:w [color="black", style="setlinewidth(3)", label=""];
+}
diff --git a/docs/source/APPNOTE_011_Design_Investigation/sumprod.v b/docs/source/APPNOTE_011_Design_Investigation/sumprod.v
new file mode 100644
index 000000000..4091bf0a1
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/sumprod.v
@@ -0,0 +1,12 @@
+module sumprod(a, b, c, sum, prod);
+
+  input [7:0] a, b, c;
+  output [7:0] sum, prod;
+
+  {* sumstuff *}
+  assign sum = a + b + c;
+  {* *}
+
+  assign prod = a * b * c;
+
+endmodule
diff --git a/docs/source/APPNOTE_011_Design_Investigation/sumprod_00.dot b/docs/source/APPNOTE_011_Design_Investigation/sumprod_00.dot
new file mode 100644
index 000000000..06522dcc9
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/sumprod_00.dot
@@ -0,0 +1,18 @@
+digraph "sumprod" {
+rankdir="LR";
+remincross=true;
+v0 [ label="a" ];
+v1 [ label="b" ];
+v2 [ label="$1_Y" ];
+c4 [ shape=record, label="{{<p1> A|<p2> B}|$1\n$add|{<p3> Y}}" ];
+v3 [ label="$1_Y" ];
+v4 [ label="c" ];
+v5 [ label="sum" ];
+c5 [ shape=record, label="{{<p1> A|<p2> B}|$2\n$add|{<p3> Y}}" ];
+v0:e -> c4:p1:w [color="black", style="setlinewidth(3)", label=""];
+v1:e -> c4:p2:w [color="black", style="setlinewidth(3)", label=""];
+c4:p3:e -> v2:w [color="black", style="setlinewidth(3)", label=""];
+v3:e -> c5:p1:w [color="black", style="setlinewidth(3)", label=""];
+v4:e -> c5:p2:w [color="black", style="setlinewidth(3)", label=""];
+c5:p3:e -> v5:w [color="black", style="setlinewidth(3)", label=""];
+}
diff --git a/docs/source/APPNOTE_011_Design_Investigation/sumprod_01.dot b/docs/source/APPNOTE_011_Design_Investigation/sumprod_01.dot
new file mode 100644
index 000000000..aefe7a6da
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/sumprod_01.dot
@@ -0,0 +1,15 @@
+digraph "sumprod" {
+rankdir="LR";
+remincross=true;
+n2 [ shape=octagon, label="a", color="black", fontcolor="black" ];
+n3 [ shape=octagon, label="b", color="black", fontcolor="black" ];
+n4 [ shape=octagon, label="c", color="black", fontcolor="black" ];
+n5 [ shape=octagon, label="sum", color="black", fontcolor="black" ];
+c9 [ shape=record, label="{{<p6> A|<p7> B}|$1\n$add|{<p8> Y}}" ];
+c10 [ shape=record, label="{{<p6> A|<p7> B}|$2\n$add|{<p8> Y}}" ];
+c9:p8:e -> c10:p6:w [color="black", style="setlinewidth(3)", label=""];
+n2:e -> c9:p6:w [color="black", style="setlinewidth(3)", label=""];
+n3:e -> c9:p7:w [color="black", style="setlinewidth(3)", label=""];
+n4:e -> c10:p7:w [color="black", style="setlinewidth(3)", label=""];
+c10:p8:e -> n5:w [color="black", style="setlinewidth(3)", label=""];
+}
diff --git a/docs/source/APPNOTE_011_Design_Investigation/sumprod_02.dot b/docs/source/APPNOTE_011_Design_Investigation/sumprod_02.dot
new file mode 100644
index 000000000..4646c9947
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/sumprod_02.dot
@@ -0,0 +1,5 @@
+digraph "sumprod" {
+rankdir="LR";
+remincross=true;
+n1 [ shape=octagon, label="prod", color="black", fontcolor="black" ];
+}
diff --git a/docs/source/APPNOTE_011_Design_Investigation/sumprod_03.dot b/docs/source/APPNOTE_011_Design_Investigation/sumprod_03.dot
new file mode 100644
index 000000000..dcfea2b56
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/sumprod_03.dot
@@ -0,0 +1,11 @@
+digraph "sumprod" {
+rankdir="LR";
+remincross=true;
+n1 [ shape=octagon, label="prod", color="black", fontcolor="black" ];
+v0 [ label="$3_Y" ];
+v1 [ label="c" ];
+c5 [ shape=record, label="{{<p2> A|<p3> B}|$4\n$mul|{<p4> Y}}" ];
+c5:p4:e -> n1:w [color="black", style="setlinewidth(3)", label=""];
+v0:e -> c5:p2:w [color="black", style="setlinewidth(3)", label=""];
+v1:e -> c5:p3:w [color="black", style="setlinewidth(3)", label=""];
+}
diff --git a/docs/source/APPNOTE_011_Design_Investigation/sumprod_04.dot b/docs/source/APPNOTE_011_Design_Investigation/sumprod_04.dot
new file mode 100644
index 000000000..e77c41aa2
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/sumprod_04.dot
@@ -0,0 +1,11 @@
+digraph "sumprod" {
+rankdir="LR";
+remincross=true;
+n2 [ shape=octagon, label="c", color="black", fontcolor="black" ];
+n3 [ shape=octagon, label="prod", color="black", fontcolor="black" ];
+c7 [ shape=record, label="{{<p4> A|<p5> B}|$4\n$mul|{<p6> Y}}" ];
+n1 [ shape=diamond, label="$3_Y" ];
+n1:e -> c7:p4:w [color="black", style="setlinewidth(3)", label=""];
+n2:e -> c7:p5:w [color="black", style="setlinewidth(3)", label=""];
+c7:p6:e -> n3:w [color="black", style="setlinewidth(3)", label=""];
+}
diff --git a/docs/source/APPNOTE_011_Design_Investigation/sumprod_05.dot b/docs/source/APPNOTE_011_Design_Investigation/sumprod_05.dot
new file mode 100644
index 000000000..b54441290
--- /dev/null
+++ b/docs/source/APPNOTE_011_Design_Investigation/sumprod_05.dot
@@ -0,0 +1,15 @@
+digraph "sumprod" {
+rankdir="LR";
+remincross=true;
+n2 [ shape=octagon, label="c", color="black", fontcolor="black" ];
+n3 [ shape=octagon, label="prod", color="black", fontcolor="black" ];
+v0 [ label="a" ];
+v1 [ label="b" ];
+c7 [ shape=record, label="{{<p4> A|<p5> B}|$3\n$mul|{<p6> Y}}" ];
+c8 [ shape=record, label="{{<p4> A|<p5> B}|$4\n$mul|{<p6> Y}}" ];
+c7:p6:e -> c8:p4:w [color="black", style="setlinewidth(3)", label=""];
+n2:e -> c8:p5:w [color="black", style="setlinewidth(3)", label=""];
+c8:p6:e -> n3:w [color="black", style="setlinewidth(3)", label=""];
+v0:e -> c7:p4:w [color="black", style="setlinewidth(3)", label=""];
+v1:e -> c7:p5:w [color="black", style="setlinewidth(3)", label=""];
+}
diff --git a/docs/source/CHAPTER_Prog.rst b/docs/source/CHAPTER_Prog.rst
index f706123aa..23aeed5a5 100644
--- a/docs/source/CHAPTER_Prog.rst
+++ b/docs/source/CHAPTER_Prog.rst
@@ -15,11 +15,11 @@ The guidelines directory contains notes on various aspects of Yosys
 development. The files GettingStarted and CodingStyle may be of
 particular interest, and are reproduced here.
 
-.. literalinclude:: ../../guidelines/GettingStarted
+.. literalinclude:: temp/GettingStarted
 	:language: none
 	:caption: guidelines/GettingStarted
 
-.. literalinclude:: ../../guidelines/CodingStyle
+.. literalinclude:: temp/CodingStyle
 	:language: none
 	:caption: guidelines/CodingStyle
 
@@ -28,19 +28,19 @@ The "stubsnets" example module
 
 The following is the complete code of the "stubsnets" example module. It
 is included in the Yosys source distribution as
-manual/CHAPTER_Prog/stubnets.cc.
+docs/source/CHAPTER_Prog/stubnets.cc.
 
-.. literalinclude:: ../../manual/CHAPTER_Prog/stubnets.cc
+.. literalinclude:: CHAPTER_Prog/stubnets.cc
 	:language: c++
 	:linenos:
-	:caption: manual/CHAPTER_Prog/stubnets.cc
+	:caption: docs/source/CHAPTER_Prog/stubnets.cc
 
-.. literalinclude:: ../../manual/CHAPTER_Prog/Makefile
+.. literalinclude:: CHAPTER_Prog/Makefile
 	:language: makefile
 	:linenos:
-	:caption: manual/CHAPTER_Prog/Makefile
+	:caption: docs/source/CHAPTER_Prog/Makefile
 
-.. literalinclude:: ../../manual/CHAPTER_Prog/test.v
+.. literalinclude:: CHAPTER_Prog/test.v
 	:language: verilog
 	:linenos:
-	:caption: manual/CHAPTER_Prog/test.v
+	:caption: docs/source/CHAPTER_Prog/test.v
diff --git a/docs/source/CHAPTER_Prog/.gitignore b/docs/source/CHAPTER_Prog/.gitignore
new file mode 100644
index 000000000..fa83c3212
--- /dev/null
+++ b/docs/source/CHAPTER_Prog/.gitignore
@@ -0,0 +1,3 @@
+stubnets.so
+stubnets.d
+*.log
diff --git a/docs/source/CHAPTER_Prog/Makefile b/docs/source/CHAPTER_Prog/Makefile
new file mode 100644
index 000000000..8e326bdc2
--- /dev/null
+++ b/docs/source/CHAPTER_Prog/Makefile
@@ -0,0 +1,12 @@
+test: stubnets.so
+	yosys -ql test1.log -m ./stubnets.so test.v -p "stubnets"
+	yosys -ql test2.log -m ./stubnets.so test.v -p "opt; stubnets"
+	yosys -ql test3.log -m ./stubnets.so test.v -p "techmap; opt; stubnets -report_bits"
+	tail test1.log test2.log test3.log
+
+stubnets.so: stubnets.cc
+	yosys-config --exec --cxx --cxxflags --ldflags -o $@ -shared $^ --ldlibs
+
+clean:
+	rm -f test1.log test2.log test3.log
+	rm -f stubnets.so stubnets.d
diff --git a/docs/source/CHAPTER_Prog/stubnets.cc b/docs/source/CHAPTER_Prog/stubnets.cc
new file mode 100644
index 000000000..566d24b18
--- /dev/null
+++ b/docs/source/CHAPTER_Prog/stubnets.cc
@@ -0,0 +1,130 @@
+// This is free and unencumbered software released into the public domain.
+//
+// Anyone is free to copy, modify, publish, use, compile, sell, or
+// distribute this software, either in source code form or as a compiled
+// binary, for any purpose, commercial or non-commercial, and by any
+// means.
+
+#include "kernel/yosys.h"
+#include "kernel/sigtools.h"
+
+#include <string>
+#include <map>
+#include <set>
+
+USING_YOSYS_NAMESPACE
+PRIVATE_NAMESPACE_BEGIN
+
+// this function is called for each module in the design
+static void find_stub_nets(RTLIL::Design *design, RTLIL::Module *module, bool report_bits)
+{
+	// use a SigMap to convert nets to a unique representation
+	SigMap sigmap(module);
+
+	// count how many times a single-bit signal is used
+	std::map<RTLIL::SigBit, int> bit_usage_count;
+
+	// count output lines for this module (needed only for summary output at the end)
+	int line_count = 0;
+
+	log("Looking for stub wires in module %s:\n", RTLIL::id2cstr(module->name));
+
+	// For all ports on all cells
+	for (auto &cell_iter : module->cells_)
+	for (auto &conn : cell_iter.second->connections())
+	{
+		// Get the signals on the port
+		// (use sigmap to get a uniqe signal name)
+		RTLIL::SigSpec sig = sigmap(conn.second);
+
+		// add each bit to bit_usage_count, unless it is a constant
+		for (auto &bit : sig)
+			if (bit.wire != NULL)
+				bit_usage_count[bit]++;
+	}
+
+	// for each wire in the module
+	for (auto &wire_iter : module->wires_)
+	{
+		RTLIL::Wire *wire = wire_iter.second;
+
+		// .. but only selected wires
+		if (!design->selected(module, wire))
+			continue;
+
+		// add +1 usage if this wire actually is a port
+		int usage_offset = wire->port_id > 0 ? 1 : 0;
+
+		// we will record which bits of the (possibly multi-bit) wire are stub signals
+		std::set<int> stub_bits;
+
+		// get a signal description for this wire and split it into separate bits
+		RTLIL::SigSpec sig = sigmap(wire);
+
+		// for each bit (unless it is a constant):
+		// check if it is used at least two times and add to stub_bits otherwise
+		for (int i = 0; i < GetSize(sig); i++)
+			if (sig[i].wire != NULL && (bit_usage_count[sig[i]] + usage_offset) < 2)
+				stub_bits.insert(i);
+
+		// continue if no stub bits found
+		if (stub_bits.size() == 0)
+			continue;
+
+		// report stub bits and/or stub wires, don't report single bits
+		// if called with report_bits set to false.
+		if (GetSize(stub_bits) == GetSize(sig)) {
+			log("  found stub wire: %s\n", RTLIL::id2cstr(wire->name));
+		} else {
+			if (!report_bits)
+				continue;
+			log("  found wire with stub bits: %s [", RTLIL::id2cstr(wire->name));
+			for (int bit : stub_bits)
+				log("%s%d", bit == *stub_bits.begin() ? "" : ", ", bit);
+			log("]\n");
+		}
+
+		// we have outputted a line, increment summary counter
+		line_count++;
+	}
+
+	// report summary
+	if (report_bits)
+		log("  found %d stub wires or wires with stub bits.\n", line_count);
+	else
+		log("  found %d stub wires.\n", line_count);
+}
+
+// each pass contains a singleton object that is derived from Pass
+struct StubnetsPass : public Pass {
+	StubnetsPass() : Pass("stubnets") { }
+	void execute(std::vector<std::string> args, RTLIL::Design *design) override
+	{
+		// variables to mirror information from passed options
+		bool report_bits = 0;
+
+		log_header(design, "Executing STUBNETS pass (find stub nets).\n");
+
+		// parse options
+		size_t argidx;
+		for (argidx = 1; argidx < args.size(); argidx++) {
+			std::string arg = args[argidx];
+			if (arg == "-report_bits") {
+				report_bits = true;
+				continue;
+			}
+			break;
+		}
+
+		// handle extra options (e.g. selection)
+		extra_args(args, argidx, design);
+
+		// call find_stub_nets() for each module that is either
+		// selected as a whole or contains selected objects.
+		for (auto &it : design->modules_)
+			if (design->selected_module(it.first))
+				find_stub_nets(design, it.second, report_bits);
+	}
+} StubnetsPass;
+
+PRIVATE_NAMESPACE_END
diff --git a/docs/source/CHAPTER_Prog/test.v b/docs/source/CHAPTER_Prog/test.v
new file mode 100644
index 000000000..201f75006
--- /dev/null
+++ b/docs/source/CHAPTER_Prog/test.v
@@ -0,0 +1,8 @@
+module uut(in1, in2, in3, out1, out2);
+
+input [8:0] in1, in2, in3;
+output [8:0] out1, out2;
+
+assign out1 = in1 + in2 + (in3 >> 4);
+
+endmodule
diff --git a/docs/source/appendix/APPNOTE_011_Design_Investigation.rst b/docs/source/appendix/APPNOTE_011_Design_Investigation.rst
index 004d3cb66..44819e283 100644
--- a/docs/source/appendix/APPNOTE_011_Design_Investigation.rst
+++ b/docs/source/appendix/APPNOTE_011_Design_Investigation.rst
@@ -140,7 +140,7 @@ behavior of the circuit.
 
    Output of ``yosys -p 'proc; opt; show' splice.v``
 
-.. literalinclude:: ../../../manual/APPNOTE_011_Design_Investigation/splice.v
+.. literalinclude:: ../APPNOTE_011_Design_Investigation/splice.v
    :caption: ``splice.v``
    :name: splice_src
 
@@ -355,7 +355,7 @@ Objects can not only be selected by their name but also by other properties. For
 example ``select t:$add`` will select all cells of type ``$add``. In this case
 this is also yields the diagram shown in :numref:`seladd`.
 
-.. literalinclude:: ../../../manual/APPNOTE_011_Design_Investigation/foobaraddsub.v
+.. literalinclude:: ../APPNOTE_011_Design_Investigation/foobaraddsub.v
    :caption: Test module for operations on selections
    :name: foobaraddsub
    :language: verilog
@@ -380,7 +380,7 @@ which is a complete selection of everything in the current module.
 Operations on selections
 ------------------------
 
-.. literalinclude:: ../../../manual/APPNOTE_011_Design_Investigation/sumprod.v
+.. literalinclude:: ../APPNOTE_011_Design_Investigation/sumprod.v
    :caption: Another test module for operations on selections
    :name: sumprod
    :language: verilog
@@ -487,7 +487,7 @@ features. We synthesize the circuit using ``proc; opt; memory; opt`` and change
 to the ``memdemo`` module with ``cd memdemo``. If we type ``show`` now we see
 the diagram shown in :numref:`memdemo_00`.
 
-.. literalinclude:: ../../../manual/APPNOTE_011_Design_Investigation/memdemo.v
+.. literalinclude:: ../APPNOTE_011_Design_Investigation/memdemo.v
    :caption: Demo circuit for demonstrating some advanced Yosys features
    :name: memdemo_src
    :language: verilog
@@ -685,7 +685,7 @@ commands can be applied.
 Solving combinatorial SAT problems
 ----------------------------------
 
-.. literalinclude:: ../../../manual/APPNOTE_011_Design_Investigation/primetest.v
+.. literalinclude:: ../APPNOTE_011_Design_Investigation/primetest.v
    :language: verilog
    :caption: A simple miter circuit for testing if a number is prime. But it has
              a problem (see main text and :numref:`primesat`).