Docs: Bugpoint fixups from JF

Also dropping the `autosectionlabel_maxdepth = 1` so that I can actually use the auto section labels.
Adds warning on bash substitution on scripting intro page when talking about `yosys -p`.

docs/source/conf.py

@@ -62,7 +62,6 @@ if os.getenv("READTHEDOCS"):
 
 # Ensure that autosectionlabel will produce unique names
 autosectionlabel_prefix_document = True
-autosectionlabel_maxdepth = 1
 
 # include todos for previews
 extensions.append('sphinx.ext.todo')

docs/source/getting_started/scripting_intro.rst

@@ -26,7 +26,7 @@ of the comment is a semicolon ``;`` or a new line.
 .. code-block::
    :caption: Using the ``-p`` option
 
-   $ yosys -p "read_verilog fifo.v; :this is a comment; prep"
+   $ yosys -p 'read_verilog fifo.v; :this is a comment; prep'
 
 .. warning::
 
@@ -42,6 +42,13 @@ will be raised by Yosys.  `exec` provides a much more flexible way of executing
 commands, allowing the output to be logged and more control over when to
 generate errors.
 
+.. warning::
+
+   Take care when using the ``yosys -p`` option.  Some shells such as bash will
+   perform substitution options inside of a double quoted string, such as ``!``
+   for history substitution and ``$`` for variable substitution; single quotes
+   should be used instead to pass the string to Yosys without substitution.
+
 The synthesis starter script
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/source/using_yosys/bugpoint.rst

@@ -44,14 +44,10 @@ Minimizing RTLIL designs with bugpoint
     * the ``-qq`` prevents Yosys from outputting non-error messages to the
       console, so this will either display the text ``test``, or an error
       message about ``Shell`` being unavailable
-    * be careful about using ``!`` in bash as it will perform a history
+    * check :ref:`getting_started/scripting_intro:script parsing` for more about
-      substitution if not escaped with single quotes (double quotes will not
+      the ``-p`` option and common pitfalls
-      escape it)
-    * ``!`` does not need to be escaped in *Yosys* scripts or when called within
-      the interactive Yosys shell, *only* when called on the command line with
-      ``-p``
 
-- single command (``yosys -p "<command>" design.il``)
+- single command (``yosys -p '<command>' design.il``)
 - *or* multiple commands in a separate script file
 
   + script shouldn't load the design
@@ -68,26 +64,30 @@ Minimizing RTLIL designs with bugpoint
 
 - follow `bugpoint` instructions
 
-   + output design after `bugpoint` with `write_rtlil`
+  + output design after `bugpoint` with `write_rtlil`
-   + use ``-grep "<string>"`` to only accept a minimized design that crashes
+  + use ``-grep "<string>"`` to only accept a minimized design that crashes
-     with the ``<string>`` in the log file
+    with the ``<string>`` in the log file
-   + ``-modules``, ``-ports``, ``-cells``, and ``-processes`` will enable those
+  + ``-modules``, ``-ports``, ``-cells``, and ``-processes`` will enable those
-     parts of the design to be removed
+    parts of the design to be removed
 
-     * use the ``bugpoint_keep`` attribute on objects you don't want to be
+    * use the ``bugpoint_keep`` attribute on objects you don't want to be
-       removed, usually because you already know they are related to the failure
+      removed, usually because you already know they are related to the failure
-     * ``(* bugpoint_keep *)`` in Verilog, ``attribute \bugpoint_keep 1`` in
+    * ``(* bugpoint_keep *)`` in Verilog, ``attribute \bugpoint_keep 1`` in
-       RTLIL, or ``setattr -set bugpoint_keep 1 [selection]`` from script
+      RTLIL, or ``setattr -set bugpoint_keep 1 [selection]`` from script
 
-   + ``-runner "<prefix>"`` can allow running ``yosys`` wrapped by another
+  + ``-runner "<prefix>"`` can allow running ``yosys`` wrapped by another
-     command
+    command
-   + can also use `setenv` before `bugpoint` to set environment variables for
+  + can also use `setenv` before `bugpoint` to set environment variables for
-     the spawned processes (e.g. ``setenv UBSAN_OPTIONS halt_on_error=1``)
+    the spawned processes (e.g. ``setenv UBSAN_OPTIONS halt_on_error=1``)
 
 .. note::
 
-   Using `setenv` in this way **does not affect the current process**.  Only
+   Using `setenv` in this way may not affect the current process as some
-   child processes will respect the assigned ``halt_on_error``.
+   environment variables are only read on start up.  For instance the
+   ``UBSAN_OPTIONS halt_on_error`` here only affects child processes, as does
+   the :doc:`Yosys environment variable</appendix/env_vars>` ``ABC``.  While
+   others such as ``YOSYS_NOVERIFIC`` and ``HOME`` are evaluated each time they
+   are used.
 
 
 .. _minimize your script:
@@ -187,15 +187,34 @@ Minimizing Verilog designs
 Creating an issue on GitHub
 ---------------------------
 
-- "Reproduction Steps" is ideally a single code-block (starting and ending with
+- "Reproduction Steps" is ideally a code-block (starting and ending with triple
-  triple backquotes), containing the minimized yosys script file, which includes
+  backquotes) containing the minimized design (Verilog or RTLIL), followed by a
-  the minimized design as a "here document" followed by the sequence of commands
+  code-block containing the minimized yosys script OR a command line call to
-  which reproduce the error
+  yosys with code-formatting (starting and ending with single backquotes)
 
-.. TODO:: https://tldp.org/LDP/abs/html/here-docs.html
+.. code-block:: markdown
 
-   Actually fill out :doc:`/using_yosys/more_scripting/load_design` with here
+   min.v
-   docs info and then link to it from here
+   ```verilog
+   // minimized Verilog design
+   ```
+
+   min.ys
+   ```
+   read_verilog min.v
+   # minimum sequence of commands to reproduce error
+   ```
+
+   OR
+
+   `yosys -p ': minimum sequence of commands;' min.v`
+
+
+- alternatively can provide a single code-block which includes the minimized
+  design as a "here document" followed by the sequence of commands which
+  reproduce the error
+
+  + see :doc:`/using_yosys/more_scripting/load_design` for more on heredocs.
 
 .. code-block:: markdown
 
@@ -203,7 +222,7 @@ Creating an issue on GitHub
    read_rtlil <<EOF
    # minimized RTLIL design
    EOF
-   # minimum sequence of commands to reproduce error
+   # minimum sequence of commands
    ```
 
 - any environment variables or command line options should also be mentioned in

docs/source/using_yosys/more_scripting/load_design.rst

@@ -32,8 +32,17 @@ The `read` command
   + ``-verific`` and ``-noverific`` options to enforce with/without Verific
   + check ``help read`` for more about the options available and the filetypes
     supported
+  + elaborate designs with ``verific -import [options] <top>`` (or use
+    `hierarchy`)
 
-- fallback to `read_verilog`
+- fallback to `read_verilog` with ``-defer`` option
+
+  + does not compile design until `hierarchy` command as discussed in
+    :doc:`/getting_started/example_synth`
+  + more similar to `verific` behaviour
+
+- ``read -define`` et al mapped to `verific` or `verilog_defines`
+- similarly, ``read -incdir`` et al mapped to `verific` or `verilog_defaults`
 
 .. note::
 
@@ -129,3 +138,10 @@ Externally maintained plugins
 - both plugins above are included in `OSS CAD Suite`_
 
 .. _OSS CAD Suite: https://github.com/YosysHQ/oss-cad-suite-build
+
+- `Synlig`_, which uses `Surelog`_ to provide SystemVerilog support
+
+  + also implemented as a '`Frontend`_'
+
+.. _Synlig: https://github.com/chipsalliance/synlig
+.. _Surelog: https://github.com/chipsalliance/Surelog