update doc (synth, overview, generics, etc.) (#1205)

* doc: extend info about setting generics through the CLI

* doc: rename 'Command Reference' to 'Additional Command Reference'

* doc: use '``' instead of ':samp:'

* doc: update info about synthesis

* doc: add references to sources in internals/Overview

* doc: add diagram to internals/Overview

4 files changed, 80 insertions, 34 deletions

diff --git a/doc/using/CommandReference.rst b/doc/using/CommandReference.rst
index 17ae4bc40..f66335d2c 100644
--- a/doc/using/CommandReference.rst
+++ b/doc/using/CommandReference.rst
@@ -1,8 +1,8 @@
 .. program:: ghdl
 .. _REF:Command:
 
-Command Reference
-#################
+Additional Command Reference
+############################
 
 .. HINT:: The most common commands and options are shown in section :ref:`USING:Invoking`. Here the advanced and experimental features are described.
 
diff --git a/doc/using/InvokingGHDL.rst b/doc/using/InvokingGHDL.rst
index e393892c2..1857fccfc 100644
--- a/doc/using/InvokingGHDL.rst
+++ b/doc/using/InvokingGHDL.rst
@@ -227,35 +227,6 @@ Theses rules can then be integrated in another Makefile.
 
 .. _GHDL:options:
 
-Synthesis command
-=================
-
-GHDL supports synthesis, but only as a front-end: it generates a
-generic netlist that is not optimized.
-
-.. index:: synthesis command
-
-.. _Synth:command:
-
-Synthesis [``--synth``]
------------------------
-
-.. option:: --synth <[options] [unit]>
-
-.. option:: --synth <[options] files -e [unit]>
-
-The first command elaborates for synthesis the design whose top unit
-is indicated by ``unit``.  All the units must have been analyzed.  The
-second form analyze only the files present on the command line and
-then elaborate them starting from the top ``unit``.  A generic netlist
-is then displayed using a very simple vhdl subset.
-
-The command line is the same as the ``ghdl`` command added to
-Yosys by the ghdl plugin except ``--synth`` is not present.  With this
-plugin, it is possible to optimize and map to a target the netlist.
-
-This command is useful for checking that a design could be synthesized.
-
 Options
 =======
 
diff --git a/doc/using/Simulation.rst b/doc/using/Simulation.rst
index e97212375..64e4f36c6 100644
--- a/doc/using/Simulation.rst
+++ b/doc/using/Simulation.rst
@@ -37,9 +37,17 @@ Here is the list of the most useful options. For further info, see :ref:`DEV:Deb
 
     $ ghdl -r --std=08 my_unit -gDEPTH=12
 
-  .. WARNING::
-     This is currently a run option; but in the future it will be deprecated to
-     become an elaboration option only.
+  .. NOTE::
+    This is currently a run option; but in the (not near) future it might be deprecated to
+    become an elaboration option only. As a result, now you can generate a single binary and
+    execute it multiple times with different arguments. That might not be possible in the future.
+
+    As explained in :option:`-e`, performing a complete elaboration in terms of the LRM requires
+    to get rid of the compile and link model. This is mostly because delaying certain elaboration
+    steps to the runtime prevents elaboration-time optimisions.
+
+  .. HINT::
+    Currently, GHDL has limited support for generic types in the CLI. It is suggested to use strings or integers. Nonetheless, project `JSON-for-VHDL <https://github.com/Paebbels/JSON-for-VHDL>`_ allows to encode a set of parameters as stringified JSON, and it provides VHDL functions to read specific values from it. It is valid for synthesis.
 
 .. option:: --assert-level=<LEVEL>
 
diff --git a/doc/using/Synthesis.rst b/doc/using/Synthesis.rst
new file mode 100644
index 000000000..c236152e6
--- /dev/null
+++ b/doc/using/Synthesis.rst
@@ -0,0 +1,67 @@
+.. program:: ghdl
+.. _USING:Synthesis:
+
+Synthesis
+#########
+
+.. WARNING::
+   This is experimental and work in progress! If you find crashes or unsupported features, please :ref:`report them <reporting_bugs>`!
+
+Since ``v0.37``, GHDL features a built-in (experimental) synthesis kernel with two backends: ``synth`` and ``yosys-plugin``. Currently, synthesis is supported as a front-end of other synthesis and technology mapping tools.
+Hence, the netlists generated by GHDL are not optimised.
+
+.. NOTE::
+   Due to GHDL's modular architecture (see :ref:`INT:Overview`), the synthesis kernel shares the VHDL parsing front-end with the simulation back-ends. Hence, available options for synthesis are the same as for analysis and/or simulation elaboration (see :ref:`GHDL:options`).
+
+.. index:: synthesis command
+
+.. _Synth:command:
+
+Synthesis [``--synth``]
+=======================
+
+.. HINT::
+   This command is useful for checking that a design can be synthesized, before actually running a complete synthesis
+   tool. In fact, because this is expected to be much faster, it can be used as a frequent check.
+
+.. TIP::
+   Since GHDL's front-end supports multiple versions of the standard, but the synthesised netlists are generated using
+   a subset of VHDL 1993, GHDL's synthesis features can be used as a preprocessor with tools that do support older
+   versions of the standard, but which don't provide the most recent features.
+
+.. option:: --synth <[options] primary_unit [secondary_unit]>
+
+Elaborates for synthesis the design whose top unit is indicated by ``primary_unit [secondary_unit]``.
+
+.. ATTENTION::
+   All the units must have been analyzed; that is, the artifacts of previously executed :option:`-a` calls must exist.
+
+.. option:: --synth <[options] files... -e primary_unit [secondary_unit]>
+
+Analyses and elaborates for synthesis the files present on the command line only.
+Elaboration starts from the top unit indicated by ``primary_unit [secondary_unit]``.
+
+Currently, the output is a generic netlist using a (very simple) subset of VHDL 1993.
+See :ghdlsharp:`1174` for on-going discussion about other output formats.
+
+.. TIP::
+   Files can be provided in any order.
+
+.. _Synth:plugin:
+
+Yosys plugin
+============
+
+`ghdl-yosys-plugin <https://github.com/ghdl/ghdl-yosys-plugin>`_ is a module to use GHDL as a VHDL front-end for `Yosys
+Open Synthesis Suite <http://www.clifford.at/yosys/>`_, a framework for optimised synthesis and technology mapping.
+Artifacts generated by Yosys can be used in multiple open source and vendor tools to achieve P&R, formal verification,
+etc. A relevant feature of combining GHDL and Yosys is that mixed-language (VHDL-Verilog) synthesis with open source
+tools is possible.
+
+The command line syntax for this plugin is the same as for :option:``--synth``, except that the command name (``--synth``)
+is neither required nor supported. Instead, ``yosys``, ``yosys -m ghdl`` or ``yosys -m path/to/ghdl.so`` need to be used,
+depending of how is the plugin built. See `README <https://github.com/ghdl/ghdl-yosys-plugin>`_ for building and installation
+guidelines.
+
+.. HINT::
+   ghdl-yosys-plugin is a thin layer that converts the internal representation of :option:`--synth` to Yosys' C API. Hence, it is suggested to check the designs with :option:`--synth` before running synthesis with Yosys.