From 8e07030feee20cfbee78a1bf15feca6021d0db72 Mon Sep 17 00:00:00 2001
From: Krystine Sherwin <93062060+KrystalDelusion@users.noreply.github.com>
Date: Wed, 1 Nov 2023 10:13:28 +1300
Subject: [PATCH] docs: update auxiliary programs

Now includes usage output, (hopefully) generated by the tool during the docs build process so it will always be up to date.
Included in makefile as `docs/usage` target.
Also some updates/additions to the description text, esp `yosys-filterlib` and `yosys-smtbmc`.
---
 Makefile                          | 11 ++++++++--
 docs/source/appendix/auxlibs.rst  |  4 ++--
 docs/source/appendix/auxprogs.rst | 34 ++++++++++++++++++++++++-------
 3 files changed, 38 insertions(+), 11 deletions(-)

diff --git a/Makefile b/Makefile
index da2e8e2dc..62485f150 100644
--- a/Makefile
+++ b/Makefile
@@ -969,7 +969,7 @@ 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 docs/guidelines
+PHONY: docs/gen_images docs/guidelines docs/usage
 docs/gen_images:
 	$(Q) $(MAKE) -C docs/source/_images all
 
@@ -978,8 +978,15 @@ docs/guidelines:
 	$(Q) mkdir -p docs/source/temp
 	$(Q) cp -f $(addprefix guidelines/,$(DOCS_GUIDELINE_FILES)) docs/source/temp
 
+# many of these will return an error which can be safely ignored, so we prefix
+# the command with a '-'
+DOCS_USAGE_PROGS := yosys-config yosys-filterlib yosys-abc yosys-smtbmc yosys-witness
+docs/usage: $(addprefix docs/source/temp/,$(DOCS_USAGE_PROGS))
+docs/source/temp/%: docs/guidelines
+	-$(Q) ./$(PROGRAM_PREFIX)$* --help > $@ 2>&1
+
 DOC_TARGET ?= html
-docs: docs/source/cmd/abc.rst docs/gen_images docs/guidelines
+docs: docs/source/cmd/abc.rst docs/gen_images docs/guidelines docs/usage
 	$(Q) $(MAKE) -C docs $(DOC_TARGET)
 
 clean:
diff --git a/docs/source/appendix/auxlibs.rst b/docs/source/appendix/auxlibs.rst
index 861634648..a77eb8b3f 100644
--- a/docs/source/appendix/auxlibs.rst
+++ b/docs/source/appendix/auxlibs.rst
@@ -1,8 +1,8 @@
 Auxiliary libraries
 ===================
 
-The Yosys source distribution contains some auxiliary libraries that are bundled
-with Yosys.
+The Yosys source distribution contains some auxiliary libraries that are
+compiled into Yosys and can be used in plugins.
 
 .. todo:: fill out the newer auxiliary libs
 
diff --git a/docs/source/appendix/auxprogs.rst b/docs/source/appendix/auxprogs.rst
index 41570b086..6b2d04d71 100644
--- a/docs/source/appendix/auxprogs.rst
+++ b/docs/source/appendix/auxprogs.rst
@@ -1,26 +1,32 @@
 Auxiliary programs
 ==================
 
-.. todo:: check this list is up to date and correct, esp yosys-smtbmc
-
 Besides the main yosys executable, the Yosys distribution contains a set of
 additional helper programs.
 
 yosys-config
 ------------
 
-The yosys-config tool (an auto-generated shell-script) can be used to query
+The ``yosys-config`` tool (an auto-generated shell-script) can be used to query
 compiler options and other information needed for building loadable modules for
 Yosys. See :doc:`/yosys_internals/extensions` for details.
 
+.. literalinclude:: /temp/yosys-config
+    :start-at: Usage
+
 .. _sec:filterlib:
 
 yosys-filterlib
 ---------------
 
-The yosys-filterlib tool is a small utility that can be used to strip or extract
-information from a Liberty file. See :ref:`sec:techmap_extern` for
-details.
+.. todo:: how does a filterlib rules-file work?  is this still supported?
+
+The ``yosys-filterlib`` tool is a small utility that can be used to strip or
+extract information from a Liberty file.  This can be useful for removing
+sensitive or proprietary information such as timing or other trade secrets.
+
+.. literalinclude:: /temp/yosys-filterlib
+    :start-at: Usage
 
 yosys-abc
 ---------
@@ -30,10 +36,24 @@ been accepted upstream. Not all versions of Yosys work with all versions of ABC.
 So Yosys comes with its own yosys-abc to avoid compatibility issues between the
 two.
 
+.. literalinclude:: /temp/yosys-abc
+    :start-at: usage
+    :end-before: UC Berkeley
+
 yosys-smtbmc
 ------------
 
+The ``yosys-smtbmc`` tool is a utility used by SBY for interacting with smt
+solvers.
+
+.. literalinclude:: /temp/yosys-smtbmc
+
 yosys-witness
 -------------
 
-yosys-witness is a new tool to inspect and convert yosys witness traces.
+``yosys-witness`` is a new tool to inspect and convert yosys witness traces.
+This is used in SBY and SCY for producing traces in a consistent format
+independent of the solver.
+
+.. literalinclude:: /temp/yosys-witness
+    :start-at: Usage