From b14a651142c1aaabdd8a6536c23923bc60c5ff22 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Tue, 5 Nov 2024 13:29:45 +1300
Subject: [PATCH 1/4] Docs: Mention verilator for linting

Link to verilator in the introduction.
Include `verilator --lint-only fifo.v` in the example synth doc.
Fix linter warnings in fifo.v.
---
 docs/source/code_examples/fifo/fifo.v         | 6 +++---
 docs/source/getting_started/example_synth.rst | 8 ++++++++
 docs/source/introduction.rst                  | 5 +++++
 3 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/docs/source/code_examples/fifo/fifo.v b/docs/source/code_examples/fifo/fifo.v
index 769dfafd4..86f292406 100644
--- a/docs/source/code_examples/fifo/fifo.v
+++ b/docs/source/code_examples/fifo/fifo.v
@@ -5,7 +5,7 @@ module addr_gen
 ) ( input en, clk, rst,
 	output reg [AWIDTH-1:0] addr
 );
-	initial addr <= 0;
+	initial addr = 0;
 
 	// async reset
 	// increment address when enabled
@@ -13,7 +13,7 @@ module addr_gen
 		if (rst)
 			addr <= 0;
 		else if (en) begin
-			if (addr == MAX_DATA-1)
+			if ({'0, addr} == MAX_DATA-1)
 				addr <= 0;
 			else
 				addr <= addr + 1;
@@ -57,7 +57,7 @@ module fifo
 	);
 
 	// status signals
-	initial count <= 0;
+	initial count = 0;
 
 	always @(posedge clk or posedge rst) begin
 		if (rst)
diff --git a/docs/source/getting_started/example_synth.rst b/docs/source/getting_started/example_synth.rst
index f8530b45b..189eaddfa 100644
--- a/docs/source/getting_started/example_synth.rst
+++ b/docs/source/getting_started/example_synth.rst
@@ -30,6 +30,14 @@ First, let's quickly look at the design we'll be synthesizing:
 
 .. todo:: fifo.v description
 
+While the open source `read_verilog` frontend generally does a pretty good job
+at processing valid Verilog input, it does not provide very good error handling
+or reporting.  Using an external tool such as `verilator`_ before running Yosys
+is highly recommended. We can quickly check the Verilog syntax of our design by
+calling ``verilator --lint-only fifo.v``.
+
+.. _verilator: https://www.veripool.org/verilator/
+
 Loading the design
 ~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst
index 7261d8edb..946a54563 100644
--- a/docs/source/introduction.rst
+++ b/docs/source/introduction.rst
@@ -69,9 +69,14 @@ Things you can't do
 
   - Check out `nextpnr`_ for that
 
+- Rely on built-in syntax checking
+
+   - Use an external tool like `verilator`_ instead
+
 .. todo:: nextpnr for FPGAs, consider mentioning openlane, vpr, coriolis
 
 .. _nextpnr: https://github.com/YosysHQ/nextpnr
+.. _verilator: https://www.veripool.org/verilator/
 
 The Yosys family
 ----------------

From f2517f75993fda5a7aee38dd3e26305f142d81af Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Tue, 5 Nov 2024 13:42:16 +1300
Subject: [PATCH 2/4] README: Add note on linting

---
 README.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/README.md b/README.md
index 3845d2502..16146da8a 100644
--- a/README.md
+++ b/README.md
@@ -260,6 +260,16 @@ The command ``prep`` provides a good default word-level synthesis script, as
 used in SMT-based formal verification.
 
 
+Additional information
+======================
+
+The ``read_verilog`` command, used by default when calling ``read`` with Verilog
+source input, does not perform any syntax checking.  You should instead lint
+your source with another tool such as
+[Verilator](https://www.veripool.org/verilator/) first, e.g. by calling
+``verilator --lint-only``.
+
+
 Unsupported Verilog-2005 Features
 =================================
 

From e4994554fd70e7a304963313763a8bf69cc7ce38 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Tue, 5 Nov 2024 13:48:48 +1300
Subject: [PATCH 3/4] Docs: Fix nested list

---
 docs/source/introduction.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst
index 946a54563..376c8043b 100644
--- a/docs/source/introduction.rst
+++ b/docs/source/introduction.rst
@@ -71,7 +71,7 @@ Things you can't do
 
 - Rely on built-in syntax checking
 
-   - Use an external tool like `verilator`_ instead
+  - Use an external tool like `verilator`_ instead
 
 .. todo:: nextpnr for FPGAs, consider mentioning openlane, vpr, coriolis
 

From d0e56777607a66777bc678399b54b013935e49f7 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Sat, 9 Nov 2024 04:30:06 +1300
Subject: [PATCH 4/4] Docs: Less exaggeration

---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 16146da8a..c0da4b3cc 100644
--- a/README.md
+++ b/README.md
@@ -264,8 +264,8 @@ Additional information
 ======================
 
 The ``read_verilog`` command, used by default when calling ``read`` with Verilog
-source input, does not perform any syntax checking.  You should instead lint
-your source with another tool such as
+source input, does not perform syntax checking.  You should instead lint your
+source with another tool such as
 [Verilator](https://www.veripool.org/verilator/) first, e.g. by calling
 ``verilator --lint-only``.