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

@@ -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:

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
 

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