docs: Fix and test for AsciiDoc breaks (#3728)

docs/guide/connecting.rst

@@ -51,8 +51,8 @@ also the instance of the top level instance in the design hierarchy (what
 you would refer to with :code:`$root` in SystemVerilog).  This meant that
 all internal variables that were implemented by Verilator in the root scope
 were accessible as members of the model class itself.  Note there were often
-many such variable due to module inlining, including :code:`/* verilator
+many such variable due to module inlining, including
-public_flat */` items.
+:code:`/* verilator public_flat */` items.
 
 This means that user code that accesses internal signals in the model
 (likely including :code:`/* verilator public_flat */` signals, as they are

docs/guide/example_cc.rst

@@ -58,13 +58,13 @@ Breaking this command down:
    own compile rules, and run make yourself as we show in :ref:`Example
    SystemC Execution`.)
 
-#. :vlopt:`-j` `0' to Verilate using use as many CPU threads as the machine
+#. :vlopt:`-j 0 <-j>` to Verilate using use as many CPU threads as the
-   has.
+   machine has.
 
 #. :vlopt:`-Wall` so Verilator has stronger lint warnings
    enabled.
 
-#. An finally, :command:`our.v` which is our SystemVerilog design file.
+#. And finally, :command:`our.v` which is our SystemVerilog design file.
 
 Once Verilator completes we can see the generated C++ code under the
 :file:`obj_dir` directory.

docs/guide/example_dist.rst

@@ -7,7 +7,7 @@ Examples in the Distribution
 ============================
 
 See the ``examples/`` directory that is part of the distribution, and
-is installed (in a OS-specific place, often in e.g.
+is installed (in an OS-specific place, often in e.g.
 ``/usr/local/share/verilator/examples``).  These examples include:
 
 examples/make_hello_binary

docs/guide/exe_sim.rst

@@ -82,10 +82,10 @@ Summary:
 
 .. option:: +verilator+rand+reset+<value>
 
-   When a model was Verilated using :vlopt:`--x-initial unique
+   When a model was Verilated using
-   <--x-initial>`, sets the simulation runtime initialization technique.  0
+   :vlopt:`--x-initial unique <--x-initial>`, sets the simulation runtime
-   = Reset to zeros. 1 = Reset to all-ones.  2 = Randomize.  See
+   initialization technique.  0 = Reset to zeros. 1 = Reset to all-ones.  2
-   :ref:`Unknown States`.
+   = Randomize.  See :ref:`Unknown States`.
 
 .. option:: +verilator+seed+<value>
 

docs/guide/exe_verilator.rst

@@ -29,10 +29,10 @@ Summary:
 .. option:: <file.a/.o/.so>
 
    Specifies optional object or library files to be linked in with the
-   Verilog code, as a shorthand for :vlopt:`-LDFLAGS \<file\>`. The file
+   Verilog code, as a shorthand for
-   path should either be absolute, or relative to where the make will be
+   :vlopt:`-LDFLAGS \<file\> <-LDFLAGS>`. The file path should either be
-   executed from, or add to your makefile's VPATH the appropriate directory
+   absolute, or relative to where the make will be executed from, or add to
-   to find the file.
+   your makefile's VPATH the appropriate directory to find the file.
 
    If any files are specified in this way, Verilator will include a make
    rule that uses these files when linking the module's executable.  This
@@ -257,10 +257,11 @@ Summary:
 
 .. option:: -D<var>=<value>
 
-   Defines the given preprocessor symbol.  Similar to :vlopt:`+define
+   Defines the given preprocessor symbol.  Similar to
-   <+define+<var>>`, but does not allow multiple definitions with a single
+   :vlopt:`+define <+define+<var>>`, but does not allow multiple
-   option using plus signs. "+define" is fairly standard across Verilog
+   definitions with a single option using plus signs. "+define" is fairly
-   tools while "-D" is similar to :command:`gcc -D`.
+   standard across Verilog tools while "-D" is similar to
+   :command:`gcc -D`.
 
 .. option:: --debug
 
@@ -270,10 +271,10 @@ Summary:
      generally is a less-optimized binary with symbols present (so GDB can be used on it).
    * Enable debugging messages (equivalent to :vlopt:`--debugi 3 <--debugi>`).
    * Enable internal assertions (equivalent to :vlopt:`--debug-check`).
-   * Enable intermediate form dump files (equivalent to :vlopt:`--dumpi-tree 3
+   * Enable intermediate form dump files (equivalent to
-     <--dumpi-tree>`).
+     :vlopt:`--dumpi-tree 3 <--dumpi-tree>`).
-   * Leak to make node numbers unique (equivalent to :vlopt:`--debug-leak
+   * Leak to make node numbers unique (equivalent to
-     <--no-debug-leak>`.
+     :vlopt:`--debug-leak <--no-debug-leak>`.
    * Call abort() instead of exit() if there are any errors (so GDB can see
      the program state).
 
@@ -304,9 +305,10 @@ Summary:
 .. option:: --debugi-<srcfile> <level>
 
    Rarely needed - for developer use.  Set the specified Verilator source
-   file to the specified level (e.g. :vlopt:`--debugi-V3Width 9
+   file to the specified level (e.g.
-   <--debugi>`). Higher levels produce more detailed messages.  See
+   :vlopt:`--debugi-V3Width 9 <--debugi>`). Higher levels produce more
-   :vlopt:`--debug` for other implications of enabling debug.
+   detailed messages.  See :vlopt:`--debug` for other implications of
+   enabling debug.
 
 .. option:: --no-decoration
 
@@ -378,9 +380,9 @@ Summary:
    Rarely needed.  Enable dumping Ast .tree debug files with dumping level 3,
    which dumps the standard critical stages.  For details on the format see
    the Verilator Internals manual.  :vlopt:`--dump-tree` is enabled
-   automatically with :vlopt:`--debug`, so :vlopt:`--debug --no-dump-tree
+   automatically with :vlopt:`--debug`, so
-   <--dump-tree>` may be useful if the dump files are large and not
+   :vlopt:`--debug --no-dump-tree <--dump-tree>` may be useful if the dump
-   desired.
+   files are large and not desired.
 
 .. option:: --dump-tree-dot
 
@@ -392,7 +394,7 @@ Summary:
 
    Rarely needed - for developer use.  Replace AST node addresses with
    short identifiers in tree dumps to enhance readability.  Each unique
-   pointer value is mapped to a unique identifier, but note that this is
+   pointer value is mapped to an unique identifier, but note that this is
    not necessarily unique per node instance as an address might get reused
    by a newly allocated node after a node with the same address has been
    dumped then freed.
@@ -570,7 +572,7 @@ Summary:
 
    Rarely needed.  Suppress an unknown Verilator option for an option that
    takes no additional arguments.  This is used to allow scripts written
-   with pragmas for a later version of Verilator to run under a older
+   with pragmas for a later version of Verilator to run under an older
    version.  e.g. :code:`-future0 option --option` would on older versions
    that do not understand :code:`--option` or :code:`+option` suppress what
    would otherwise be an invalid option error, and on newer versions that
@@ -582,13 +584,14 @@ Summary:
 
    Rarely needed.  Suppress an unknown Verilator option for an option that
    takes an additional argument.  This is used to allow scripts written
-   with pragmas for a later version of Verilator to run under a older
+   with pragmas for a later version of Verilator to run under an older
    version.  e.g. :code:`-future1 option --option arg` would on older
-   versions that do not understand :code:`--option arg` or :code:`+option
+   versions that do not understand :code:`--option arg` or
-   arg` suppress what would otherwise be an invalid option error, and on
+   :code:`+option arg` suppress what would otherwise be an invalid option
-   newer versions that implement :code:`--option arg`, :code:`-future1
+   error, and on newer versions that implement :code:`--option arg`,
-   option --option arg` would have the :code:`-future1 option` ignored and
+   :code:`-future1 option --option arg` would have the
-   the :code:`--option arg` would function appropriately.
+   :code:`-future1 option` ignored and the :code:`--option arg` would function
+   appropriately.
 
 .. option:: -G<name>=<value>
 
@@ -711,9 +714,9 @@ Summary:
    methodologies. Default is an l2-name matching the top module. The
    default before Verilator 3.884 was ``--l2-name v``.
 
-   For example, the program :code:`module t; initial $display("%m");
+   For example, the program
-   endmodule` will show by default "t". With ``--l2-name v`` it will print
+   :code:`module t; initial $display("%m"); endmodule` will show by default
-   "v".
+   "t". With ``--l2-name v`` it will print "v".
 
 .. option:: --language <value>
 
@@ -855,8 +858,8 @@ Summary:
    Enables slow optimizations for the code Verilator itself generates (as
    opposed to :vlopt:`-CFLAGS -O3 <-CFLAGS>` which effects the C compiler's
    optimization.  :vlopt:`-O3` may improve simulation performance at the
-   cost of compile time.  This currently sets :vlopt:`--inline-mult -1
+   cost of compile time.  This currently sets
-   <--inline-mult>`.
+   :vlopt:`--inline-mult -1 <--inline-mult>`.
 
 .. option:: -O<optimization-letter>
 
@@ -1096,18 +1099,18 @@ Summary:
 .. option:: --public-flat-rw
 
    Declares all variables, ports and wires public as if they had
-   :code:`/*verilator public_flat_rw @
+   :code:`/*verilator public_flat_rw @ (<variable's_source_process_edge>)*/`
-   (<variable's_source_process_edge>)*/` metacomments.  This will make them
+   metacomments.  This will make them VPI accessible by their flat name,
-   VPI accessible by their flat name, but not turn off module inlining.
+   but not turn off module inlining.  This is particularly useful in
-   This is particularly useful in combination with :vlopt:`--vpi`. This may
+   combination with :vlopt:`--vpi`. This may also in some rare cases result
-   also in some rare cases result in mis-simulation of generated clocks.
+   in mis-simulation of generated clocks.  Instead of this global option,
-   Instead of this global option, marking only those signals that need
+   marking only those signals that need public_flat_rw is typically
-   public_flat_rw is typically significantly better performing.
+   significantly better performing.
 
 .. option:: -pvalue+<name>=<value>
 
-   Overwrites the given parameter(s) of the toplevel module. See :vlopt:`-G
+   Overwrites the given parameter(s) of the toplevel module. See
-   <-G<name>>` for a detailed description.
+   :vlopt:`-G <-G<name>>` for a detailed description.
 
 .. option:: --quiet-exit
 
@@ -1465,7 +1468,7 @@ Summary:
 
    Rarely needed.  Suppress unknown Verilator comments or warning messages
    with the given message code.  This is used to allow code written with
-   pragmas for a later version of Verilator to run under a older version;
+   pragmas for a later version of Verilator to run under an older version;
    add "-Wfuture-" arguments for each message code or comment that the new
    version supports which the older version does not support.
 
@@ -1753,15 +1756,16 @@ The grammar of configuration commands is as follows:
 
 .. option:: parallel_case -file "<filename>" -lines <lineno>
 
-   Same as :code:`//synopsys full_case` and :code:`//synopsys
+   Same as :code:`//synopsys full_case` and
-   parallel_case`. When these synthesis directives are discovered,
+   :code:`//synopsys parallel_case`. When these synthesis directives are
-   Verilator will either formally prove the directive to be true, or
+   discovered, Verilator will either formally prove the directive to be
-   failing that, will insert the appropriate code to detect failing cases
+   true, or failing that, will insert the appropriate code to detect
-   at simulation runtime and print an "Assertion failed" error message.
+   failing cases at simulation runtime and print an "Assertion failed"
+   error message.
 
 .. option:: hier_block -module "<modulename>"
 
-   Specifies that the module is a unit of hierarchical Verilation.  Note
+   Specifies that the module is an unit of hierarchical Verilation.  Note
    that the setting is ignored unless the :vlopt:`--hierarchical` option is
    specified.  See :ref:`Hierarchical Verilation`.
 

docs/guide/extensions.rst

@@ -57,10 +57,10 @@ or "`ifdef`"'s may break other tools.
    Verilator does not use any text inside the quotes for
    ordering/scheduling.  If you need the $c to be called at a specific
    time, e.g. when a variable changes, then the $c must be under an
-   appropriate sensitivity statement, e.g. :code:`always @(posedge clk)
+   appropriate sensitivity statement, e.g.
-   $c("func()")` to call it on every edge, or e.g. :code:`always @*
+   :code:`always @(posedge clk) $c("func()")` to call it on every edge, or
-   c("func(",a,")")` to call it when :code:`a` changes (the latter working
+   e.g. :code:`always @* c("func(",a,")")` to call it when :code:`a`
-   because :code:`a` is outside the quotes).
+   changes (the latter working because :code:`a` is outside the quotes).
 
    If you will be reading or writing any Verilog variables inside the C++
    functions, the Verilog signals must be declared with
@@ -251,7 +251,7 @@ or "`ifdef`"'s may break other tools.
 
 .. option:: /*verilator&32;hier_block*/
 
-   Specifies that the module is a unit of hierarchical Verilation.  This
+   Specifies that the module is an unit of hierarchical Verilation.  This
    metacomment must be between :code:`module module_name(...);` and
    :code:`endmodule`.  The module will not be inlined nor uniquified for
    each instance in hierarchical Verilation.  Note that the metacomment is

docs/guide/languages.rst

@@ -80,10 +80,11 @@ string, and wreal.
 Synthesis Directive Assertion Support
 -------------------------------------
 
-With the :vlopt:`--assert` option, Verilator reads any :code:`//synopsys
+With the :vlopt:`--assert` option, Verilator reads any
-full_case` or :code:`//synopsys parallel_case` directives.  The same
+
-applies to any :code:`//ambit synthesis`, :code:`//cadence` or
+:code:`//synopsys full_case` or :code:`//synopsys parallel_case`
-:code:`//pragma` directives of the same form.
+directives.  The same applies to any :code:`//ambit synthesis`,
+:code:`//cadence` or :code:`//pragma` directives of the same form.
 
 When these synthesis directives are discovered, Verilator will either
 formally prove the directive to be true, or failing that, will insert the
@@ -369,7 +370,7 @@ and the address.  For non-power-of-2-sizes arrays, index 0 will be written.
 
 Reading a memory element that is outside the bounds specified for the array
 will give a width warning and wrap around the power-of-2 size.  For
-non-power-of-2 sizes, it will return a unspecified constant of the
+non-power-of-2 sizes, it will return an unspecified constant of the
 appropriate width.
 
 

docs/guide/simulating.rst

@@ -18,12 +18,14 @@ Benchmarking & Optimization
 ===========================
 
 For best performance, run Verilator with the :vlopt:`-O3`
-:vlopt:`--x-assign fast <--x-assign>` :vlopt:`--x-initial fast
+:vlopt:`--x-assign fast <--x-assign>`
-<--x-initial>` :vlopt:`--noassert <--assert>` options.  The :vlopt:`-O3`
+:vlopt:`--x-initial fast <--x-initial>`
-option will require longer time to run Verilator, and :vlopt:`--x-assign
+:vlopt:`--noassert <--assert>` options.  The :vlopt:`-O3`
-fast <--x-assign>` :vlopt:`--x-initial fast <--x-assign>` may increase the
+option will require longer time to run Verilator, and
-risk of reset bugs in trade for performance; see the above documentation
+:vlopt:`--x-assign fast <--x-assign>`
-for these options.
+:vlopt:`--x-initial fast <--x-assign>`
+may increase the risk of reset bugs in trade for performance; see the above
+documentation for these options.
 
 If using Verilated multithreaded, use ``numactl`` to ensure you are using
 non-conflicting hardware resources. See :ref:`Multithreading`. Also
@@ -162,7 +164,7 @@ Line Coverage
 
 With :vlopt:`--coverage` or :vlopt:`--coverage-line`, Verilator will
 automatically add coverage analysis at each code flow change point (e.g. at
-branches).  At each such branch a unique counter is incremented.  At the
+branches).  At each such branch an unique counter is incremented.  At the
 end of a test, the counters along with the filename and line number
 corresponding to each counter are written into the coverage file.
 

docs/guide/verilating.rst

@@ -239,17 +239,17 @@ physical core. For best performance use the :command:`numactl` program to
 (when the threading count fits) select unique physical cores on the same
 socket. The same applies for :vlopt:`--trace-threads` as well.
 
-As an example, if a model was Verilated with :vlopt:`--threads 4
+As an example, if a model was Verilated with
-<--threads>`, we consult:
+:vlopt:`--threads 4 <--threads>`, we consult:
 
 .. code-block:: bash
 
     egrep 'processor|physical id|core id' /proc/cpuinfo
 
 To select cores 0, 1, 2, and 3 that are all located on the same socket (0)
-but different physical cores.  (Also useful is :command:`numactl
+but different physical cores.  (Also useful is
---hardware`, or :command:`lscpu` but those doesn't show Hyperthreading
+:command:`numactl --hardware`, or :command:`lscpu` but those doesn't show
-cores.) Then we execute:
+hyperthreading cores.)  Then we execute:
 
 .. code-block:: bash
 

docs/guide/warnings.rst

@@ -150,11 +150,11 @@ List Of Warnings
    practice. Verilator reports this as an error, because ignoring this
    warning may make Verilator simulations differ from other simulators.
 
-   It is generally safe to disable this error (with a :code:`// verilator
+   It is generally safe to disable this error (with a
-   lint_off BLKANDNBLK` metacomment or the :code:`-Wno-BLKANDNBLK` option)
+   :code:`// verilator lint_off BLKANDNBLK` metacomment or the
-   when one of the assignments is inside a public task, or when the
+   :code:`-Wno-BLKANDNBLK` option) when one of the assignments is inside a
-   blocking and non-blocking assignments have non-overlapping bits and
+   public task, or when the blocking and non-blocking assignments have
-   structure members.
+   non-overlapping bits and structure members.
 
    Generally, this is caused by a register driven by both combo logic and a
    flop:
@@ -383,8 +383,10 @@ List Of Warnings
    Verilog, but not SystemVerilog, a wire must be used as the target of
    continuous assignments.
 
-   This error is only reported when :vlopt:`--language 1364-1995
+   This error is only reported when
-   <--language>`, :vlopt:`--language 1364-2001 <--language>`, or
+
+   :vlopt:`--language 1364-1995 <--language>`,
+   :vlopt:`--language 1364-2001 <--language>`, or
    :vlopt:`--language 1364-2005 <--language>` is used.
 
    Ignoring this error will only suppress the lint check, it will simulate
@@ -483,7 +485,7 @@ List Of Warnings
    Error at simulation runtime when model did not properly settle.
 
    Verilator sometimes has to evaluate combinatorial logic multiple times,
-   usually around code where a UNOPTFLAT warning was issued, but disabled.
+   usually around code where an UNOPTFLAT warning was issued, but disabled.
 
    Faulty example:
 
@@ -499,12 +501,13 @@ List Of Warnings
 
    To debug this, first review any UNOPTFLAT warnings that were
    ignored.  Though typically it is safe to ignore UNOPTFLAT (at a
-   performance cost), at the time of issuing a UNOPTFLAT Verilator did not
+   performance cost), at the time of issuing an UNOPTFLAT Verilator did not
    know if the logic would eventually converge and assumed it would.
 
-   Next, run Verilator with :vlopt:`--prof-cfuncs -CFLAGS -DVL_DEBUG
+   Next, run Verilator with
-   <--prof-cfuncs>`.  Rerun the test.  Now just before the convergence
+   :vlopt:`--prof-cfuncs -CFLAGS -DVL_DEBUG <--prof-cfuncs>`.  Rerun the
-   error you should see additional output similar to this:
+   test.  Now just before the convergence error you should see additional
+   output similar to this:
 
    .. include:: ../../docs/gen/ex_DIDNOTCONVERGE_msg.rst
 
@@ -983,7 +986,7 @@ List Of Warnings
 
    Warns that a module has a pin which is not mentioned in an instance.  If
    a pin is not missing it should still be specified on the instance
-   declaration with a empty connection, using :code:`(.pin_name())`.
+   declaration with an empty connection, using :code:`(.pin_name())`.
 
    Ignoring this warning will only suppress the lint check, it will
    simulate correctly.
@@ -1161,7 +1164,7 @@ List Of Warnings
                               example.v:1:20: ... Location of previous definition, with value: 'def2'
 
    The best solution is to use a different name for the second macro.  If
-   this is not possible, add a undef to indicate the code is overriding the
+   this is not possible, add an undef to indicate the code is overriding the
    value. This will express the intent and should avoid future warnings on
    any linting tool:
 
@@ -1555,7 +1558,7 @@ List Of Warnings
 
    .. TODO better example
 
-   Warns that the code is comparing a unsigned value in a way that implies
+   Warns that the code is comparing an unsigned value in a way that implies
    it is signed, for example "X < 0" will always be false when X is
    unsigned.
 
@@ -1716,7 +1719,7 @@ List Of Warnings
 
    .. include:: ../../docs/gen/ex_VARHIDDEN_msg.rst
 
-   To resolve, rename the variable to a unique name.
+   To resolve, rename the variable to an unique name.
 
 
 .. option:: WAITCONST

test_regress/t/t_dist_docs_style.pl

@@ -23,7 +23,7 @@ foreach my $file (sort keys %files) {
     my $contents = file_contents($filename);
 
     checkPattern($filename, $contents,
-                 qr/.*(?<!ref):\`[^`]+\n/,
+                 qr/.*[a-z](?<!:ref):\`[^`]+\n/,
                  "tag:`...` should not be split between lines");
 }