diff --git a/docs/source/test_suites.rst b/docs/source/test_suites.rst
index b37263144..3e016400e 100644
--- a/docs/source/test_suites.rst
+++ b/docs/source/test_suites.rst
@@ -1,5 +1,5 @@
-Test suites
-===========
+Testing Yosys
+=============
 
 .. todo:: more about the included test suite
 
diff --git a/docs/source/using_yosys/synthesis/opt.rst b/docs/source/using_yosys/synthesis/opt.rst
index 407308a29..d60e17a48 100644
--- a/docs/source/using_yosys/synthesis/opt.rst
+++ b/docs/source/using_yosys/synthesis/opt.rst
@@ -1,43 +1,28 @@
 Optimization passes
 ===================
 
-.. todo:: check text context, also check the optimization passes still do what they say
-
 Yosys employs a number of optimizations to generate better and cleaner results.
 This chapter outlines these optimizations.
 
-The :cmd:ref:`opt` pass
---------------------------
+.. todo:: "outlines these optimizations" or "outlines *some*.."?
+
+The :cmd:ref:`opt` macro command
+--------------------------------
 
 The Yosys pass :cmd:ref:`opt` runs a number of simple optimizations. This
 includes removing unused signals and cells and const folding. It is recommended
-to run this pass after each major step in the synthesis script. At the time of
-this writing the :cmd:ref:`opt` pass executes the following passes that each
-perform a simple optimization:
+to run this pass after each major step in the synthesis script.  As listed in
+:doc:`/cmd/opt`, this macro command calls the following ``opt_*`` commands:
 
-.. code-block:: yoscrypt
+.. literalinclude:: /cmd/opt.rst
+   :language: yoscrypt
+   :start-after: following order:
+   :end-at: while <changed design>
+   :dedent:
+   :caption: Passes called by :cmd:ref:`opt`
 
-    opt_expr                # const folding and simple expression rewriting
-    opt_merge -nomux        # merging identical cells
-
-    do
-        opt_muxtree         # remove never-active branches from multiplexer tree
-        opt_reduce          # consolidate trees of boolean ops to reduce functions
-        opt_merge           # merging identical cells
-        opt_rmdff           # remove/simplify registers with constant inputs
-        opt_clean           # remove unused objects (cells, wires) from design
-        opt_expr            # const folding and simple expression rewriting
-    while [changed design]
-
-The command :cmd:ref:`clean` can be used as alias for :cmd:ref:`opt_clean`. And
-``;;`` can be used as shortcut for :cmd:ref:`clean`. For example:
-
-.. code-block:: yoscrypt
-
-    hierarchy; proc; opt; memory; opt_expr;; fsm;;
-
-The :cmd:ref:`opt_expr` pass
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Const folding and simple expression rewriting - :cmd:ref:`opt_expr`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This pass performs const folding on the internal combinational cell types
 described in :doc:`/yosys_internals/formats/cell_library`. This means a cell
@@ -90,8 +75,20 @@ The :cmd:ref:`opt_expr` pass is very conservative regarding optimizing ``$mux``
 cells, as these cells are often used to model decision-trees and breaking these
 trees can interfere with other optimizations.
 
-The :cmd:ref:`opt_muxtree` pass
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Merging identical cells - :cmd:ref:`opt_merge`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This pass performs trivial resource sharing. This means that this pass
+identifies cells with identical inputs and replaces them with a single instance
+of the cell.
+
+The option ``-nomux`` can be used to disable resource sharing for multiplexer
+cells (``$mux`` and ``$pmux``.) This can be useful as it prevents multiplexer
+trees to be merged, which might prevent :cmd:ref:`opt_muxtree` to identify
+possible optimizations.
+
+Removing never-active branches from multiplexer tree - :cmd:ref:`opt_muxtree`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This pass optimizes trees of multiplexer cells by analyzing the select inputs.
 Consider the following simple example:
@@ -108,8 +105,8 @@ multiplexer and 0 for the inner multiplexer. The :cmd:ref:`opt_muxtree` pass
 detects this contradiction and replaces the inner multiplexer with a constant 1,
 yielding the logic for ``y = a ? 1 : 3``.
 
-The :cmd:ref:`opt_reduce` pass
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Simplifying large MUXes and AND/OR gates - :cmd:ref:`opt_reduce`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This is a simple optimization pass that identifies and consolidates identical
 input bits to ``$reduce_and`` and ``$reduce_or`` cells. It also sorts the input
@@ -126,38 +123,36 @@ Lastly this pass consolidates trees of ``$reduce_and`` cells and trees of
 These three simple optimizations are performed in a loop until a stable result
 is produced.
 
-The ``opt_rmdff`` pass
-~~~~~~~~~~~~~~~~~~~~~~
+Merging mutually exclusive cells with shared inputs - :cmd:ref:`opt_share`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. TODO:: Update to ``opt_dff``
+.. TODO:: ``opt_share``
+
+Performing DFF optimizations - :cmd:ref:`opt_dff`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This pass identifies single-bit d-type flip-flops (``$_DFF_``, ``$dff``, and
 ``$adff`` cells) with a constant data input and replaces them with a constant
-driver.
+driver.  It can also merge clock enables and synchronous reset multiplexers,
+removing unused control inputs.
 
-The :cmd:ref:`opt_clean` pass
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Called with ``-nodffe`` and ``-nosdff``, this pass is used to prepare a design
+for :doc:`/using_yosys/synthesis/fsm`.
+
+Removing unused cells and wires - :cmd:ref:`opt_clean` pass
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 This pass identifies unused signals and cells and removes them from the design.
 It also creates an ``\unused_bits`` attribute on wires with unused bits. This
 attribute can be used for debugging or by other optimization passes.
 
-The :cmd:ref:`opt_merge` pass
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This pass performs trivial resource sharing. This means that this pass
-identifies cells with identical inputs and replaces them with a single instance
-of the cell.
-
-The option ``-nomux`` can be used to disable resource sharing for multiplexer
-cells (``$mux`` and ``$pmux``.) This can be useful as it prevents multiplexer
-trees to be merged, which might prevent :cmd:ref:`opt_muxtree` to identify
-possible optimizations.
-
 Example
 ~~~~~~~
 
 .. todo:: describe ``opt`` images
+   
+   and/or replace with an example image showing before/after of each ``opt_*``
+   command
 
 .. figure:: /_images/code_examples/synth_flow/opt_01.*
    :class: width-helper
@@ -214,11 +209,16 @@ It is generally a good idea to call :cmd:ref:`opt` before inherently expensive
 commands such as :cmd:ref:`sat` or :cmd:ref:`freduce`, as the possible gain is
 much higher in these cases as the possible loss.
 
-The :cmd:ref:`clean` command on the other hand is very fast and many commands
-leave a mess (dangling signal wires, etc). For example, most commands do not
-remove any wires or cells. They just change the connections and depend on a
-later call to clean to get rid of the now unused objects. So the occasional
-``;;`` is a good idea in every synthesis script.
+The :cmd:ref:`clean` command, which is an alias for :cmd:ref:`opt_clean` with
+fewer outputs, on the other hand is very fast and many commands leave a mess
+(dangling signal wires, etc). For example, most commands do not remove any wires
+or cells. They just change the connections and depend on a later call to clean
+to get rid of the now unused objects. So the occasional ``;;``, which itself is
+an alias for :cmd:ref:`clean`, is a good idea in every synthesis script, e.g:
+
+.. code-block:: yoscrypt
+
+   hierarchy; proc; opt; memory; opt_expr;; fsm;;
 
 Other optimizations
 -------------------