Docs: Formatting recent md -> rst converts

docs/source/yosys_internals/extending_yosys/contributing.rst

@@ -9,19 +9,19 @@ Formatting of code
 
 - Yosys code is using tabs for indentation. Tabs are 8 characters.
 
-- A continuation of a statement in the following line is indented by
+- A continuation of a statement in the following line is indented by two
-  two additional tabs.
+  additional tabs.
 
-- Lines are as long as you want them to be. A good rule of thumb is
+- Lines are as long as you want them to be. A good rule of thumb is to break
-  to break lines at about column 150.
+  lines at about column 150.
 
-- Opening braces can be put on the same or next line as the statement
+- Opening braces can be put on the same or next line as the statement opening
-  opening the block (if, switch, for, while, do). Put the opening brace
+  the block (if, switch, for, while, do). Put the opening brace on its own line
-  on its own line for larger blocks, especially blocks that contains
+  for larger blocks, especially blocks that contains blank lines.
-  blank lines.
 
-- Otherwise stick to the Linux Kernel Coding Style:
+- Otherwise stick to the `Linux Kernel Coding Style`_.
-    https://www.kernel.org/doc/Documentation/process/coding-style.rst
+
+.. _Linux Kernel Coding Style: https://www.kernel.org/doc/Documentation/process/coding-style.rst
 
 
 C++ Language
@@ -29,8 +29,8 @@ C++ Language
 
 Yosys is written in C++17.
 
-In general Yosys uses "int" instead of "size_t". To avoid compiler
+In general Yosys uses ``int`` instead of ``size_t``. To avoid compiler warnings
-warnings for implicit type casts, always use "GetSize(foobar)" instead
+for implicit type casts, always use ``GetSize(foobar)`` instead of
-of "foobar.size()". (GetSize() is defined in kernel/yosys.h)
+``foobar.size()``. (``GetSize()`` is defined in :file:`kernel/yosys.h`)
 
 Use range-based for loops whenever applicable.

docs/source/yosys_internals/extending_yosys/test_suites.rst

@@ -40,30 +40,31 @@ page`_.
    * Tests allow refactoring;
 
    With those advantages in mind, it was required to choose a framework which fits
-   well with C/C++ code.  Hence, it was chosen (google test)
+   well with C/C++ code.  Hence, `google test`_ was chosen, because it is widely
-   [https://github.com/google/googletest], because it is largely used and it is
+   used and it is relatively easy learn.
-   relatively easy learn.
+
+   .. _google test: https://github.com/google/googletest
 
    Install and configure google test (manually)
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-   In this section, you will see a brief description of how to install google
+   In this section, you will see a brief description of how to install google test.
-   test. However, it is strongly recommended that you take a look to the official
+   However, it is strongly recommended that you take a look to the official
-   repository (https://github.com/google/googletest) and refers to that if you
+   repository (https://github.com/google/googletest) and refers to that if you have
-   have any problem to install it. Follow the steps below:
+   any problem to install it. Follow the steps below:
 
    * Install: cmake and pthread
-   * Clone google test project from: https://github.com/google/googletest and
+   * Clone google test project from: https://github.com/google/googletest and enter
-   enter in the project directory
+   in the project directory
    * Inside project directory, type:
 
-   ```
+   .. code-block:: console
-   cmake -DBUILD_SHARED_LIBS=ON .
-   make
-   ```
 
-   * After compilation, copy all "*.so" inside directory "googlemock" and
+      cmake -DBUILD_SHARED_LIBS=ON .
-   "googlemock/gtest" to "/usr/lib/"
+      make
+
+   * After compilation, copy all ``*.so`` inside directory ``googlemock`` and
+   ``googlemock/gtest`` to ``/usr/lib/``
    * Done! Now you can compile your tests.
 
    If you have any problem, go to the official repository to find help.
@@ -76,23 +77,25 @@ page`_.
 
    If you want to add new unit tests for Yosys, just follow the steps below:
 
-   * Go to directory "yosys/test/unit/"
+   * Go to directory :file:`test/unit/`
    * In this directory you can find something similar Yosys's directory structure.
    To create your unit test file you have to follow this pattern:
-   fileNameToImplementUnitTest + Test.cc. E.g.: if you want to implement the
+   fileNameToImplementUnitTest + Test.cc. E.g.: if you want to implement the unit
-   unit test for kernel/celledges.cc, you will need to create a file like this:
+   test for ``kernel/celledges.cc``, you will need to create a file like this:
-   tests/unit/kernel/celledgesTest.cc;
+   ``tests/unit/kernel/celledgesTest.cc``;
    * Implement your unit test
 
    Run unit tests
    ~~~~~~~~~~~~~~
 
    To compile and run all unit tests, just go to yosys root directory and type:
-   ```
+
-   make unit-test
+   .. code-block:: console
-   ```
+
+      make unit-test
 
    If you want to remove all unit test files, type:
-   ```
+
-   make clean-unit-test
+   .. code-block:: console
-   ```
+
+      make clean-unit-test

docs/source/yosys_internals/verilog.rst

@@ -21,64 +21,63 @@ for them:
 Verilog Attributes and non-standard features
 --------------------------------------------
 
-- The ``full_case`` attribute on case statements is supported
+- The ``full_case`` attribute on case statements is supported (also the
-  (also the non-standard ``// synopsys full_case`` directive)
+  non-standard ``// synopsys full_case`` directive)
 
-- The ``parallel_case`` attribute on case statements is supported
+- The ``parallel_case`` attribute on case statements is supported (also the
-  (also the non-standard ``// synopsys parallel_case`` directive)
+  non-standard ``// synopsys parallel_case`` directive)
 
-- The ``// synopsys translate_off`` and ``// synopsys translate_on``
+- The ``// synopsys translate_off`` and ``// synopsys translate_on`` directives
-  directives are also supported (but the use of ``` `ifdef .. `endif ```
+  are also supported (but the use of ``` `ifdef .. `endif ``` is strongly
-  is strongly recommended instead).
+  recommended instead).
 
-- The ``nomem2reg`` attribute on modules or arrays prohibits the
+- The ``nomem2reg`` attribute on modules or arrays prohibits the automatic early
-  automatic early conversion of arrays to separate registers. This
+  conversion of arrays to separate registers. This is potentially dangerous.
-  is potentially dangerous. Usually the front-end has good reasons
+  Usually the front-end has good reasons for converting an array to a list of
-  for converting an array to a list of registers. Prohibiting this
+  registers. Prohibiting this step will likely result in incorrect synthesis
-  step will likely result in incorrect synthesis results.
+  results.
 
-- The ``mem2reg`` attribute on modules or arrays forces the early
+- The ``mem2reg`` attribute on modules or arrays forces the early conversion of
-  conversion of arrays to separate registers.
+  arrays to separate registers.
 
-- The ``nomeminit`` attribute on modules or arrays prohibits the
+- The ``nomeminit`` attribute on modules or arrays prohibits the creation of
-  creation of initialized memories. This effectively puts ``mem2reg``
+  initialized memories. This effectively puts ``mem2reg`` on all memories that
-  on all memories that are written to in an ``initial`` block and
+  are written to in an ``initial`` block and are not ROMs.
-  are not ROMs.
 
-- The ``nolatches`` attribute on modules or always-blocks
+- The ``nolatches`` attribute on modules or always-blocks prohibits the
-  prohibits the generation of logic-loops for latches. Instead
+  generation of logic-loops for latches. Instead all not explicitly assigned
-  all not explicitly assigned values default to x-bits. This does
+  values default to x-bits. This does not affect clocked storage elements such
-  not affect clocked storage elements such as flip-flops.
+  as flip-flops.
 
-- The ``nosync`` attribute on registers prohibits the generation of a
+- The ``nosync`` attribute on registers prohibits the generation of a storage
-  storage element. The register itself will always have all bits set
+  element. The register itself will always have all bits set to 'x' (undefined).
-  to 'x' (undefined). The variable may only be used as blocking assigned
+  The variable may only be used as blocking assigned temporary variable within
-  temporary variable within an always block. This is mostly used internally
+  an always block. This is mostly used internally by Yosys to synthesize Verilog
-  by Yosys to synthesize Verilog functions and access arrays.
+  functions and access arrays.
 
 - The ``nowrshmsk`` attribute on a register prohibits the generation of
   shift-and-mask type circuits for writing to bit slices of that register.
 
-- The ``onehot`` attribute on wires mark them as one-hot state register. This
+- The ``onehot`` attribute on wires mark them as one-hot state register. This is
-  is used for example for memory port sharing and set by the fsm_map pass.
+  used for example for memory port sharing and set by the fsm_map pass.
 
-- The ``blackbox`` attribute on modules is used to mark empty stub modules
+- The ``blackbox`` attribute on modules is used to mark empty stub modules that
-  that have the same ports as the real thing but do not contain information
+  have the same ports as the real thing but do not contain information on the
-  on the internal configuration. This modules are only used by the synthesis
+  internal configuration. This modules are only used by the synthesis passes to
-  passes to identify input and output ports of cells. The Verilog backend
+  identify input and output ports of cells. The Verilog backend also does not
-  also does not output blackbox modules on default. ``read_verilog``, unless
+  output blackbox modules on default. `read_verilog`, unless called with
-  called with ``-noblackbox`` will automatically set the blackbox attribute
+  ``-noblackbox`` will automatically set the blackbox attribute on any empty
-  on any empty module it reads.
+  module it reads.
 
-- The ``noblackbox`` attribute set on an empty module prevents ``read_verilog``
+- The ``noblackbox`` attribute set on an empty module prevents `read_verilog`
   from automatically setting the blackbox attribute on the module.
 
 - The ``whitebox`` attribute on modules triggers the same behavior as
-  ``blackbox``, but is for whitebox modules, i.e. library modules that
+  ``blackbox``, but is for whitebox modules, i.e. library modules that contain a
-  contain a behavioral model of the cell type.
+  behavioral model of the cell type.
 
-- The ``lib_whitebox`` attribute overwrites ``whitebox`` when ``read_verilog``
+- The ``lib_whitebox`` attribute overwrites ``whitebox`` when `read_verilog` is
-  is run in `-lib` mode. Otherwise it's automatically removed.
+  run in ``-lib`` mode. Otherwise it's automatically removed.
 
 - The ``dynports`` attribute is used by the Verilog front-end to mark modules
   that have ports with a width that depends on a parameter.
@@ -94,7 +93,7 @@ Verilog Attributes and non-standard features
   Setting the ``keep`` attribute on a module has the same effect as setting it
   on all instances of the module.
 
-- The ``keep_hierarchy`` attribute on cells and modules keeps the ``flatten``
+- The ``keep_hierarchy`` attribute on cells and modules keeps the `flatten`
   command from flattening the indicated cells and modules.
 
 - The `gate_cost_equivalent` attribute on a module can be used to specify
@@ -106,63 +105,62 @@ Verilog Attributes and non-standard features
   initialized "FPGA-style" with ``reg foo = val``. It can be used during
   synthesis to add the necessary reset logic.
 
-- The ``top`` attribute on a module marks this module as the top of the
+- The ``top`` attribute on a module marks this module as the top of the design
-  design hierarchy. The ``hierarchy`` command sets this attribute when called
+  hierarchy. The `hierarchy` command sets this attribute when called with
-  with ``-top``. Other commands, such as ``flatten`` and various backends
+  ``-top``. Other commands, such as `flatten` and various backends use this
-  use this attribute to determine the top module.
+  attribute to determine the top module.
 
 - The ``src`` attribute is set on cells and wires created by to the string
   ``<hdl-file-name>:<line-number>`` by the HDL front-end and is then carried
-  through the synthesis. When entities are combined, a new |-separated
+  through the synthesis. When entities are combined, a new \|-separated string
-  string is created that contains all the string from the original entities.
+  is created that contains all the strings from the original entities.
 
-- The ``defaultvalue`` attribute is used to store default values for
+- The ``defaultvalue`` attribute is used to store default values for module
-  module inputs. The attribute is attached to the input wire by the HDL
+  inputs. The attribute is attached to the input wire by the HDL front-end when
-  front-end when the input is declared with a default value.
+  the input is declared with a default value.
 
-- The ``parameter`` and ``localparam`` attributes are used to mark wires
+- The ``parameter`` and ``localparam`` attributes are used to mark wires that
-  that represent module parameters or localparams (when the HDL front-end
+  represent module parameters or localparams (when the HDL front-end is run in
-  is run in ``-pwires`` mode).
+  ``-pwires`` mode).
 
 - Wires marked with the ``hierconn`` attribute are connected to wires with the
   same name (format ``cell_name.identifier``) when they are imported from
-  sub-modules by ``flatten``.
+  sub-modules by `flatten`.
 
 - The ``clkbuf_driver`` attribute can be set on an output port of a blackbox
-  module to mark it as a clock buffer output, and thus prevent ``clkbufmap``
+  module to mark it as a clock buffer output, and thus prevent `clkbufmap` from
-  from inserting another clock buffer on a net driven by such output.
+  inserting another clock buffer on a net driven by such output.
 
 - The ``clkbuf_sink`` attribute can be set on an input port of a module to
-  request clock buffer insertion by the ``clkbufmap`` pass.
+  request clock buffer insertion by the `clkbufmap` pass.
 
-- The ``clkbuf_inv`` attribute can be set on an output port of a module
+- The ``clkbuf_inv`` attribute can be set on an output port of a module with the
-  with the value set to the name of an input port of that module.  When
+  value set to the name of an input port of that module.  When the `clkbufmap`
-  the ``clkbufmap`` would otherwise insert a clock buffer on this output,
+  would otherwise insert a clock buffer on this output, it will instead try
-  it will instead try inserting the clock buffer on the input port (this
+  inserting the clock buffer on the input port (this is used to implement clock
-  is used to implement clock inverter cells that clock buffer insertion
+  inverter cells that clock buffer insertion will "see through").
-  will "see through").
 
 - The ``clkbuf_inhibit`` is the default attribute to set on a wire to prevent
-  automatic clock buffer insertion by ``clkbufmap``. This behaviour can be
+  automatic clock buffer insertion by `clkbufmap`. This behaviour can be
-  overridden by providing a custom selection to ``clkbufmap``.
+  overridden by providing a custom selection to `clkbufmap`.
 
-- The ``invertible_pin`` attribute can be set on a port to mark it as
+- The ``invertible_pin`` attribute can be set on a port to mark it as invertible
-  invertible via a cell parameter.  The name of the inversion parameter
+  via a cell parameter.  The name of the inversion parameter is specified as the
-  is specified as the value of this attribute.  The value of the inversion
+  value of this attribute.  The value of the inversion parameter must be of the
-  parameter must be of the same width as the port, with 1 indicating
+  same width as the port, with 1 indicating an inverted bit and 0 indicating a
-  an inverted bit and 0 indicating a non-inverted bit.
+  non-inverted bit.
 
-- The ``iopad_external_pin`` attribute on a blackbox module's port marks
+- The ``iopad_external_pin`` attribute on a blackbox module's port marks it as
-  it as the external-facing pin of an I/O pad, and prevents ``iopadmap``
+  the external-facing pin of an I/O pad, and prevents `iopadmap` from inserting
-  from inserting another pad cell on it.
+  another pad cell on it.
 
-- The module attribute ``abc9_lut`` is an integer attribute indicating to
+- The module attribute ``abc9_lut`` is an integer attribute indicating to `abc9`
-  `abc9` that this module describes a LUT with an area cost of this value, and
+  that this module describes a LUT with an area cost of this value, and
-  propagation delays described using `specify` statements.
+  propagation delays described using ``specify`` statements.
 
 - The module attribute ``abc9_box`` is a boolean specifying a black/white-box
-  definition, with propagation delays described using `specify` statements, for
+  definition, with propagation delays described using ``specify`` statements,
-  use by `abc9`.
+  for use by `abc9`.
 
 - The port attribute ``abc9_carry`` marks the carry-in (if an input port) and
   carry-out (if output port) ports of a box. This information is necessary for
@@ -179,38 +177,41 @@ Verilog Attributes and non-standard features
   ``proc_dlatch``.
 
 - The cell attribute ``wildcard_port_conns`` represents wildcard port
-  connections (SystemVerilog ``.*``). These are resolved to concrete
+  connections (SystemVerilog ``.*``). These are resolved to concrete connections
-  connections to matching wires in ``hierarchy``.
+  to matching wires in `hierarchy`.
 
-- In addition to the ``(* ... *)`` attribute syntax, Yosys supports
+- In addition to the ``(* ... *)`` attribute syntax, Yosys supports the
-  the non-standard ``{* ... *}`` attribute syntax to set default attributes
+  non-standard ``{* ... *}`` attribute syntax to set default attributes for
-  for everything that comes after the ``{* ... *}`` statement. (Reset
+  everything that comes after the ``{* ... *}`` statement. (Reset by adding an
-  by adding an empty ``{* *}`` statement.)
+  empty ``{* *}`` statement.)
 
-- In module parameter and port declarations, and cell port and parameter
+- In module parameter and port declarations, and cell port and parameter lists,
-  lists, a trailing comma is ignored. This simplifies writing Verilog code
+  a trailing comma is ignored. This simplifies writing Verilog code generators a
-  generators a bit in some cases.
+  bit in some cases.
 
 - Modules can be declared with ``module mod_name(...);`` (with three dots
-  instead of a list of module ports). With this syntax it is sufficient
+  instead of a list of module ports). With this syntax it is sufficient to
-  to simply declare a module port as 'input' or 'output' in the module
+  simply declare a module port as 'input' or 'output' in the module body.
-  body.
 
-- When defining a macro with `define, all text between triple double quotes
+- When defining a macro with ``\`define``, all text between triple double quotes
   is interpreted as macro body, even if it contains unescaped newlines. The
   triple double quotes are removed from the macro body. For example:
 
+.. code-block:: verilog
+
       `define MY_MACRO(a, b) """
          assign a = 23;
          assign b = 42;
       """
 
 - The attribute ``via_celltype`` can be used to implement a Verilog task or
-  function by instantiating the specified cell type. The value is the name
+  function by instantiating the specified cell type. The value is the name of
-  of the cell type to use. For functions the name of the output port can
+  the cell type to use. For functions the name of the output port can be
-  be specified by appending it to the cell type separated by a whitespace.
+  specified by appending it to the cell type separated by a whitespace. The body
-  The body of the task or function is unused in this case and can be used
+  of the task or function is unused in this case and can be used to specify a
-  to specify a behavioral model of the cell type for simulation. For example:
+  behavioral model of the cell type for simulation. For example:
+
+.. code-block:: verilog
 
       module my_add3(A, B, C, Y);
         parameter WIDTH = 8;
@@ -235,24 +236,28 @@ Verilog Attributes and non-standard features
 - The ``wiretype`` attribute is added by the verilog parser for wires of a
   typedef'd type to indicate the type identifier.
 
-- Various ``enum_value_{value}`` attributes are added to wires of an enumerated type
+- Various ``enum_value_{value}`` attributes are added to wires of an enumerated
-  to give a map of possible enum items to their values.
+  type to give a map of possible enum items to their values.
 
-- The ``enum_base_type`` attribute is added to enum items to indicate which
+- The ``enum_base_type`` attribute is added to enum items to indicate which enum
-  enum they belong to (enums -- anonymous and otherwise -- are
+  they belong to (enums -- anonymous and otherwise -- are automatically named
-  automatically named with an auto-incrementing counter). Note that enums
+  with an auto-incrementing counter). Note that enums are currently not strongly
-  are currently not strongly typed.
+  typed.
 
-- A limited subset of DPI-C functions is supported. The plugin mechanism
+- A limited subset of DPI-C functions is supported. The plugin mechanism (see
-  (see ``help plugin``) can be used to load .so files with implementations
+  ``help plugin``) can be used to load .so files with implementations of DPI-C
-  of DPI-C routines. As a non-standard extension it is possible to specify
+  routines. As a non-standard extension it is possible to specify a plugin alias
-  a plugin alias using the ``<alias>:`` syntax. For example:
+  using the ``<alias>:`` syntax. For example:
+
+.. code-block:: verilog
 
       module dpitest;
         import "DPI-C" function foo:round = real my_round (real);
         parameter real r = my_round(12.345);
       endmodule
 
+.. code-block::
+
       $ yosys -p 'plugin -a foo -i /lib/libm.so; read_verilog dpitest.v'
 
 - Sized constants (the syntax ``<size>'s?[bodh]<value>``) support constant
@@ -261,17 +266,17 @@ Verilog Attributes and non-standard features
 
 - The system tasks ``$finish``, ``$stop`` and ``$display`` are supported in
   initial blocks in an unconditional context (only if/case statements on
-  expressions over parameters and constant values are allowed). The intended
+  expressions over parameters and constant values are allowed). The intended use
-  use for this is synthesis-time DRC.
+  for this is synthesis-time DRC.
 
 - There is limited support for converting ``specify`` .. ``endspecify``
   statements to special ``$specify2``, ``$specify3``, and ``$specrule`` cells,
-  for use in blackboxes and whiteboxes. Use ``read_verilog -specify`` to
+  for use in blackboxes and whiteboxes. Use ``read_verilog -specify`` to enable
-  enable this functionality. (By default these blocks are ignored.)
+  this functionality. (By default these blocks are ignored.)
 
 - The ``reprocess_after`` internal attribute is used by the Verilog frontend to
   mark cells with bindings which might depend on the specified instantiated
-  module. Modules with such cells will be reprocessed during the ``hierarchy``
+  module. Modules with such cells will be reprocessed during the `hierarchy`
   pass once the referenced module definition(s) become available.
 
 - The ``smtlib2_module`` attribute can be set on a blackbox module to specify a
@@ -279,6 +284,8 @@ Verilog Attributes and non-standard features
   ``smtlib2_comb_expr`` attribute can be used on output ports to define their
   value using an SMT-LIB 2 expression. For example:
 
+.. code-block:: verilog
+
       (* blackbox *)
       (* smtlib2_module *)
       module submod(a, b);
@@ -291,48 +298,49 @@ Non-standard or SystemVerilog features for formal verification
 --------------------------------------------------------------
 
 - Support for ``assert``, ``assume``, ``restrict``, and ``cover`` is enabled
-  when ``read_verilog`` is called with ``-formal``.
+  when `read_verilog` is called with ``-formal``.
 
-- The system task ``$initstate`` evaluates to 1 in the initial state and
+- The system task ``$initstate`` evaluates to 1 in the initial state and to 0
-  to 0 otherwise.
+  otherwise.
 
 - The system function ``$anyconst`` evaluates to any constant value. This is
-  equivalent to declaring a reg as ``rand const``, but also works outside
+  equivalent to declaring a reg as ``rand const``, but also works outside of
-  of checkers. (Yosys also supports ``rand const`` outside checkers.)
+  checkers. (Yosys also supports ``rand const`` outside checkers.)
 
 - The system function ``$anyseq`` evaluates to any value, possibly a different
-  value in each cycle. This is equivalent to declaring a reg as ``rand``,
+  value in each cycle. This is equivalent to declaring a reg as ``rand``, but
-  but also works outside of checkers. (Yosys also supports ``rand``
+  also works outside of checkers. (Yosys also supports ``rand`` variables
-  variables outside checkers.)
+  outside checkers.)
 
 - The system functions ``$allconst`` and ``$allseq`` can be used to construct
-  formal exist-forall problems. Assumptions only hold if the trace satisfies
+  formal exist-forall problems. Assumptions only hold if the trace satisfies the
-  the assumption for all ``$allconst/$allseq`` values. For assertions and cover
+  assumption for all ``$allconst/$allseq`` values. For assertions and cover
   statements it is sufficient if just one ``$allconst/$allseq`` value triggers
   the property (similar to ``$anyconst/$anyseq``).
 
-- Wires/registers declared using the ``anyconst/anyseq/allconst/allseq`` attribute
+- Wires/registers declared using the ``anyconst/anyseq/allconst/allseq``
-  (for example ``(* anyconst *) reg [7:0] foobar;``) will behave as if driven
+  attribute (for example ``(* anyconst *) reg [7:0] foobar;``) will behave as if
-  by a ``$anyconst/$anyseq/$allconst/$allseq`` function.
+  driven by a ``$anyconst/$anyseq/$allconst/$allseq`` function.
 
 - The SystemVerilog tasks ``$past``, ``$stable``, ``$rose`` and ``$fell`` are
   supported in any clocked block.
 
 - The syntax ``@($global_clock)`` can be used to create FFs that have no
   explicit clock input (``$ff`` cells). The same can be achieved by using
-  ``@(posedge <netname>)`` or ``@(negedge <netname>)`` when ``<netname>``
+  ``@(posedge <netname>)`` or ``@(negedge <netname>)`` when ``<netname>`` is
-  is marked with the ``(* gclk *)`` Verilog attribute.
+  marked with the ``(* gclk *)`` Verilog attribute.
 
 
 Supported features from SystemVerilog
 -------------------------------------
 
-When ``read_verilog`` is called with ``-sv``, it accepts some language features
+When `read_verilog` is called with ``-sv``, it accepts some language features
 from SystemVerilog:
 
 - The ``assert`` statement from SystemVerilog is supported in its most basic
   form. In module context: ``assert property (<expression>);`` and within an
-  always block: ``assert(<expression>);``. It is transformed to an ``$assert`` cell.
+  always block: ``assert(<expression>);``. It is transformed to an ``$assert``
+  cell.
 
 - The ``assume``, ``restrict``, and ``cover`` statements from SystemVerilog are
   also supported. The same limitations as with the ``assert`` statement apply.
@@ -345,9 +353,9 @@ from SystemVerilog:
 - Checkers without a port list that do not need to be instantiated (but instead
   behave like a named block) are supported.
 
-- SystemVerilog packages are supported. Once a SystemVerilog file is read
+- SystemVerilog packages are supported. Once a SystemVerilog file is read into a
-  into a design with ``read_verilog``, all its packages are available to
+  design with `read_verilog`, all its packages are available to SystemVerilog
-  SystemVerilog files being read into the same design afterwards.
+  files being read into the same design afterwards.
 
 - typedefs are supported (including inside packages)
 	- type casts are currently not supported