Docs: changes from JF

`yosys-witness` prereq `click`.
Yosys environment vars & `yosys --help` output.
Removing Ubuntu/macOS version numbers/names.
Hide `troubleshooting` page.

Makefile

@@ -982,7 +982,7 @@ docs/guidelines:
 
 # 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_PROGS := yosys 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

docs/source/appendix/auxprogs.rst

@@ -57,3 +57,7 @@ independent of the solver.
 
 .. literalinclude:: /temp/yosys-witness
     :start-at: Usage
+
+.. note:: ``yosys-witness`` requires `click`_ Python package for use.
+
+.. _click: https://pypi.org/project/click/

docs/source/appendix/env_vars.rst

@@ -0,0 +1,31 @@
+Yosys environment variables
+===========================
+
+``HOME``
+   Yosys command history is stored in ``$HOME/.yosys_history``.  Graphics (from
+   :cmd:ref:`show` and :cmd:ref:`viz` commands) will output to this directory by
+   default.  This environment variable is also used in some cases for resolving
+   filenames with ``~``.
+
+``PATH``
+   May be used in OpenBSD builds for finding the location of Yosys executable.
+
+``TMPDIR``
+   Used for storing temporary files.
+
+``ABC``
+   When compiling Yosys with out-of-tree ABC using ``ABCEXTERNAL``, this
+   variable can be used to override the external ABC executable.
+
+``YOSYS_NOVERIFIC``
+   If Yosys was built with Verific, this environment variable can be used to
+   temporarily disable Verific support.
+
+``YOSYS_COVER_DIR`` and ``YOSYS_COVER_FILE``
+   When using code coverage, these environment variables control the output file
+   name/location.
+
+``YOSYS_ABORT_ON_LOG_ERROR``
+   Can be used for debugging Yosys internals.  Setting it to 1 causes abort() to
+   be called when Yosys terminates with an error message.
+

docs/source/cmd_ref.rst

@@ -3,9 +3,14 @@
 ================================================================================
 Command line reference
 ================================================================================
+
+.. literalinclude:: /temp/yosys
+    :start-at: Usage
+
 .. toctree::
 	:caption: Command reference
 	:maxdepth: 1
 	:glob:
 
+	/appendix/env_vars
 	/cmd/*

docs/source/test_suites.rst

@@ -6,15 +6,20 @@ Testing Yosys
 Automatic testing
 -----------------
 
-The `Yosys Git repo`_ has automatic testing of builds and running of the
-included test suite on the following platforms:
-
 .. only:: html
 
-   - Ubuntu 20.04 (Focal Fossa) |test-linux|
+   The `Yosys Git repo`_ has automatic testing of builds and running of the
-   - macOS 11 (Big Sur) |test-macos|
+   included test suite on the following platforms:
+
+   - Ubuntu |test-linux|
+   - macOS |test-macos|
 
 .. _Yosys Git repo: https://github.com/YosysHQ/yosys
 
 .. |test-linux| image:: https://github.com/YosysHQ/yosys/actions/workflows/test-linux.yml/badge.svg?branch=master
 .. |test-macos| image:: https://github.com/YosysHQ/yosys/actions/workflows/test-macos.yml/badge.svg?branch=master
+
+For up to date information, including OS versions, refer to `the git actions
+page`_.
+
+.. _the git actions page: https://github.com/YosysHQ/yosys/actions

docs/source/using_yosys/more_scripting/index.rst

@@ -9,4 +9,5 @@ More scripting
    load_design
    selections
    interactive_investigation
-   troubleshooting
+
+.. troubleshooting

docs/source/using_yosys/more_scripting/troubleshooting.rst

@@ -1,6 +1,6 @@
 Troubleshooting
 ~~~~~~~~~~~~~~~
 
-.. TODO:: more on troubleshooting
+.. todo:: troubleshooting document(?)
 
 See :doc:`/cmd/bugpoint`