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

17 files changed, 134 insertions, 76 deletions

diff --git a/doc/_static/icons/.gitempty b/doc/_static/icons/.gitempty
deleted file mode 100644
index e69de29bb..000000000
--- a/doc/_static/icons/.gitempty
+++ /dev/null
diff --git a/doc/_static/images/.gitempty b/doc/_static/images/.gitempty
deleted file mode 100644
index e69de29bb..000000000
--- a/doc/_static/images/.gitempty
+++ /dev/null
diff --git a/doc/about.rst b/doc/about.rst
index 32915a05f..3e8ea0dd9 100644
--- a/doc/about.rst
+++ b/doc/about.rst
@@ -20,31 +20,28 @@ However, VHDL was not designed as a general purpose language but as an `HDL`. As
 
 Like a program written in any other language, a VHDL program can be executed. Since VHDL is used to model designs, the term :dfn:`simulation` is often used instead of `execution`, with the same meaning. At the same time, like a design written in another `HDL`, a set of VHDL sources can be transformed with a :dfn:`synthesis tool` into a netlist, that is, a detailed gate-level implementation.
 
-The development of VHDL started in 1983 and the standard is named `IEEE <https://www.ieee.org/>`_ `1076`. Four revisions exist: `1987 <http://ieeexplore.ieee.org/document/26487/>`_, `1993 <http://ieeexplore.ieee.org/document/392561/>`_, `2002 <http://ieeexplore.ieee.org/document/1003477/>`_ and `2008 <http://ieeexplore.ieee.org/document/4772740/>`_. The standardization is handled by the VHDL Analysis and Standardization Group (`VASG/P1076 <http://www.eda-twiki.org/vasg/>`_).
+The development of VHDL started in 1983 and the standard is named `IEEE <https://www.ieee.org/>`_ `1076`. Five revisions exist: `1987 <http://ieeexplore.ieee.org/document/26487/>`_, `1993 <http://ieeexplore.ieee.org/document/392561/>`_, `2002 <http://ieeexplore.ieee.org/document/1003477/>`_, `2008 <http://ieeexplore.ieee.org/document/4772740/>`_ and `2019 <https://ieeexplore.ieee.org/document/8938196>`_. The standardization is handled by the VHDL Analysis and Standardization Group (`VASG/P1076 <http://www.eda-twiki.org/vasg/>`_).
 
 .. _INTRO:GHDL:
 
 What is GHDL?
 =============
 
-`GHDL` is a shorthand for `G Hardware Design Language` (currently, `G` has no meaning). It is a VHDL analyzer, compiler and simulator that can execute (nearly) any VHDL program. GHDL is *not* a synthesis tool: you cannot create a netlist with GHDL (yet).
+`GHDL` is a shorthand for `G Hardware Design Language` (currently, `G` has no meaning). It is a VHDL analyzer, compiler, simulator and (experimental) synthesizer that can process (nearly) any VHDL design.
+
+.. NOTE::
+  For almost 20 years, GHDL was *not* a synthesis tool: you could not create a netlist. Hence, most of the content in this documentation corresponds to the usage of GHDL as a compiler/simulator. See :ref:`USING:Synthesis` for further details regarding synthesis.
 
 Unlike some other simulators, GHDL is a compiler: it directly translates a VHDL file to machine code, without using an intermediary language such as `C` or `C++`. Therefore, the compiled code should be faster and the analysis time should be shorter than with a compiler using an intermediary language.
 
-GHDL can use multiple back-ends, i.e. code generators, (`GCC <http://gcc.gnu.org/>`_, `LLVM <http://llvm.org/>`_ or :wikipedia:`x86 <X86-64>`/:wikipedia:`i386 <Intel_80386>` only, a built-in one) and runs on :wikipedia:`GNU/Linux <Linux_distribution>`, :wikipedia:`Windows <Microsoft_Windows>` |trade|  and :wikipedia:`macOS <MacOS>` |trade| , both on x86 and on x86_64.
+GHDL can use multiple back-ends, i.e. code generators, (`GCC <http://gcc.gnu.org/>`_, `LLVM <http://llvm.org/>`_ or :wikipedia:`x86 <X86-64>`/:wikipedia:`i386 <Intel_80386>` only, a built-in one named *mcode*) and runs on :wikipedia:`GNU/Linux <Linux_distribution>`, :wikipedia:`Windows <Microsoft_Windows>` |trade| and :wikipedia:`macOS <MacOS>` |trade|; on x86, x86_64, armv6/armv7/aarch32/aarch64, etc.
 
-The current version of GHDL does not contain any built-in graphical viewer: you cannot see signal waves. You can still check the behavior of your design with a test bench. Moreover, the current version can produce `GHW <http://ghdl.readthedocs.io/en/latest/using/Simulation.html?highlight=GHW#cmdoption-wave>`_, :wikipedia:`VCD <Value_change_dump>` or `FST` files which can be viewed with a :wikipedia:`waveform viewer <Waveform_viewer>`, such as `GtkWave <http://gtkwave.sourceforge.net/>`_.
+The current version of GHDL does not contain any built-in graphical viewer: you cannot see signal waves. You can still check the behavior of your design with a test bench. Moreover, `GHW <http://ghdl.readthedocs.io/en/latest/using/Simulation.html?highlight=GHW#cmdoption-wave>`_, :wikipedia:`VCD <Value_change_dump>` or `FST` files can be produced, which can be viewed with a :wikipedia:`waveform viewer <Waveform_viewer>`, such as `GtkWave <http://gtkwave.sourceforge.net/>`_.
 
-GHDL aims at implementing VHDL as defined by `IEEE 1076 <http://ieeexplore.ieee.org/document/4772740/>`_. It supports the `1987 <http://ieeexplore.ieee.org/document/26487/>`_, `1993 <http://ieeexplore.ieee.org/document/392561/>`_ and `2002 <http://ieeexplore.ieee.org/document/1003477/>`_ revisions and, partially, the latest, `2008 <http://ieeexplore.ieee.org/document/4772740/>`_. :wikipedia:`PSL <Property_Specification_Language>` is also partially supported.
+GHDL aims at implementing VHDL as defined by `IEEE 1076 <http://ieeexplore.ieee.org/document/4772740/>`_. It supports the `1987 <http://ieeexplore.ieee.org/document/26487/>`_, `1993 <http://ieeexplore.ieee.org/document/392561/>`_ and `2002 <http://ieeexplore.ieee.org/document/1003477/>`_ revisions and, partially, `2008 <http://ieeexplore.ieee.org/document/4772740/>`_. :wikipedia:`PSL <Property_Specification_Language>` is also partially supported.
 
 Several third party projects are supported: `VUnit <https://vunit.github.io/>`_, `OSVVM <http://osvvm.org/>`_, `cocotb <https://github.com/potentialventures/cocotb>`_ (through the `VPI interface <https://en.wikipedia.org/wiki/Verilog_Procedural_Interface>`_), ...
 
-
-.. HINT::
-
-   Although synthesis is not available yet, there is some experimental support. See :ref:`DEV:Synthesis` for further info.
-
-
 .. _INTRO:WHO:
 
 Who uses GHDL?
diff --git a/doc/contribute.rst b/doc/contribute.rst
index 8b7710190..aeb2b4290 100644
--- a/doc/contribute.rst
+++ b/doc/contribute.rst
@@ -1,3 +1,5 @@
+.. program:: ghdl
+
 .. only:: html
 
    .. exec::
@@ -38,9 +40,12 @@ Reporting bugs
 .. TIP::
    * If the compiler crashes, this is a bug. Reliable tools never crash.
    * If the compiler emits an error message for a perfectly valid input or does not emit an error message for an invalid input, this may be a bug.
-   * If the executable created from your VHDL sources crashes, this may be a bug at runtime or the code itself may be wrong. However, since VHDL has a notion of pointers, an erroneous VHDL program (using invalid pointers for example) may crash.
+   * If the executable created from your VHDL sources crashes, this may be a bug at runtime or the code itself may be wrong. Since VHDL has a notion of pointers, an erroneous VHDL program (using invalid pointers for example) may crash.
    * If a compiler message is not clear enough, please tell us. The error messages can be improved, but we do not have enough experience with them.
 
+.. TIP::
+   It is suggested to test synthesis features with :option:`--synth`, before processing the design with :ref:`Synth:plugin`.
+
 Please, report issues of this kind through |SHIELD:bug-report|, as this allows us to categorize issues into groups and
 to assign developers to them. You can track the issue’s state and see how it’s getting solved.
 
@@ -63,7 +68,7 @@ to assign developers to them. You can track the issue’s state and see how itâ€
      * Anything else that you think would be helpful.
 
 .. NOTE::
-   If you don't know the LRM, be aware that an issue claimed as a bug report may be rejected because there is no bug according to it. GHDL aims at implementing VHDL as defined in `IEEE 1076 <http://ieeexplore.ieee.org/document/4772740/>`_. However, some other tools allow constructs which do not fully follow the standard revisions. Therefore, comparisons with other VHDL is not a solid argument. Some of them are supported by GHDL (see :ref:`IEEE_library_pitfalls`), but any such enhancement will have very low priority.
+   If you don't know the LRM, be aware that an issue claimed as a bug report may be rejected because there is no bug according to it. GHDL aims at implementing VHDL as defined in `IEEE 1076 <http://ieeexplore.ieee.org/document/4772740/>`_. However, some other tools allow constructs which do not fully follow the standard revisions. Therefore, comparisons with other VHDL variants is not a solid argument. Some of them are supported by GHDL (see :ref:`IEEE_library_pitfalls`), but any such enhancement will have very low priority.
 
 .. _requesting_enhancements:
 
diff --git a/doc/development/Documentation.rst b/doc/development/Documentation.rst
index 2ae76ff5e..364986542 100644
--- a/doc/development/Documentation.rst
+++ b/doc/development/Documentation.rst
@@ -3,7 +3,7 @@
 Documentation
 #############
 
-* Development/Synthesis. Synthesis, ghdlsynth-beta, formal verification, etc. Copy the 'Usage' section from ghdlsynth's README (https://github.com/1138-4EB/ghdlsynth-beta#usage).
+* Using/Synthesis: formal verification, etc.
 * Development/libghdl. How to interact with GHDL through ``libghdl`` and/or ``libghdl-py``.
 * Development/Related Projects. Brief discussion about similarities/differences with other open source projects such as rust_hdl or pyVHDLParser.
 * Usage/Docker. Probably copy/convert :file:`README.md` and :file:`USE_CASES.md` in ghdl/docker :ghdlsharp:`166`.
diff --git a/doc/development/GSOC.rst b/doc/development/GSOC.rst
index 813a2aa64..723afb832 100644
--- a/doc/development/GSOC.rst
+++ b/doc/development/GSOC.rst
@@ -8,7 +8,7 @@ This page contains ideas for enhancing GHDL that can fit internship programs, su
 VHDL frontend for Yosys
 =======================
 
-`Yosys <https://github.com/YosysHQ/yosys>`_ is an open-source synthesis tool with built-in Verilog support and partial SystemVerilog support. `ghdlsynth-beta <https://github.com/tgingold/ghdlsynth-beta>`_ is an experimental plugin for Yosys that allows to use GHDL (precisely, `libghdl <https://github.com/ghdl/ghdl#project-structure>`_) as a frontend for Yosys. Although functional, :ref:`DEV:Synthesis` is work in progress: multiple features are not supported yet, and others need to be tested for bugs.
+`Yosys <https://github.com/YosysHQ/yosys>`_ is an open-source synthesis tool with built-in Verilog support and partial SystemVerilog support. :ref:`Synth:plugin` is an experimental plugin for Yosys that allows to use GHDL. Although functional, :ref:`USING:Synthesis` is work in progress: multiple features are not supported yet, and others need to be tested for bugs.
 
 .. NOTE::
     * `FOSSI GSOC 2019 | VHDL front-end for Yosys <https://fossi-foundation.org/gsoc19-ideas.html#vhdl-front-end--for-yosys>`_
diff --git a/doc/development/Synthesis.rst b/doc/development/Synthesis.rst
deleted file mode 100644
index bcd23ff70..000000000
--- a/doc/development/Synthesis.rst
+++ /dev/null
@@ -1,8 +0,0 @@
-.. _DEV:Synthesis:
-
-Synthesis
-#########
-
-There is an experimental command (``--synth``) to generate RTL netlists (the format, VHDL or EDIF, is yet to be defined) from synthesisable code. For command ``--synth`` to be available, GHDL must be configured/built with option ``--enable-synth`` (GCC 8.1>= required, due to some new GNAT features which are only available in recent releases). Since this is a proof-of-concept, the output is mostly a dump of an internal structure for now. Therefore, it is not very useful, except for debugging.
-
-Moreover, `ghdlsynth <https://github.com/tgingold/ghdlsynth-beta>`_ is a complementary repository that lets GHDL to be loaded by `yosys <http://www.clifford.at/yosys/>`_ as a frontend plugin module, in order to generate bitstreams for some FPGA devices.
diff --git a/doc/getting/index.rst b/doc/getting/index.rst
index f64e44caf..591c4d95e 100644
--- a/doc/getting/index.rst
+++ b/doc/getting/index.rst
@@ -10,13 +10,18 @@ GHDL can be downloaded as a `zip-file <https://github.com/ghdl/ghdl/archive/mast
 offers HTTPS and SSH as transfer protocols. See the :ref:`RELEASE:Sources`
 page for further details.
 
-.. IMPORTANT ::
+.. IMPORTANT::
    Since GHDL is written in `Ada`, independently of the code generator you use,
    the a compiler is required. Most GNU/Linux package managers provide a package
    named ``gcc-ada`` or ``gcc-gnat``. Alternatively, `GNU Ada compiler`, `GNAT GPL`,
    can be downloaded anonymously from `libre.adacore.com <http://libre.adacore.com/tools/gnat-gpl-edition/>`_ (2014, or later; for x86, 32 or 64 bits).
    Then, untar and run the doinstall script.
 
+.. ATTENTION::
+   Since ``v0.37``, GHDL's synthesis features require GCC >=8.1, due to some new GNAT features which
+   are not available in previous releases. Users with older versions (who don't need synthesis)
+   can configure GHDL with option ``--no-synth``.
+
 .. rubric :: Available back-ends
 
 GHDL currently supports three different back-ends (code generators):
diff --git a/doc/index.rst b/doc/index.rst
index 4a24216f5..c675383be 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -99,8 +99,9 @@
    examples/quick_start/README
    using/InvokingGHDL
    using/Simulation
-   using/Foreign
+   using/Synthesis
    using/CommandReference
+   using/Foreign
    using/ImplementationOfVHDL
    using/ImplementationOfVITAL
    examples/README
@@ -113,7 +114,6 @@
    :caption: Development
    :hidden:
 
-   development/Synthesis
    development/Debugging
    development/CodingStyle
    development/Roadmap
diff --git a/doc/internals/Frontend.rst b/doc/internals/Frontend.rst
index 6d5e1da5c..fd5abd4e6 100644
--- a/doc/internals/Frontend.rst
+++ b/doc/internals/Frontend.rst
@@ -3,7 +3,13 @@
 Front-end
 #########
 
-Input files (or source files) are read by `files_map.ad[sb]`.  Only regular files can be read, because they are read entirely before being scanned.  This simplifies the scanner, but this also allows to have a unique index for each character in any file.  Therefore the source location is a simple 32-bit integer whose type is `Location_Type`.  From the location, `files_map` can deduce the source file (type is `Source_File_Entry`) and then the offset in the source file.  There is a line table for each source file in order to speed-up the conversion from file offset to line number and column number.
+Input files (or source files) are read by `files_map.ad[sb]`. Only regular files can be
+read, because they are read entirely before being scanned. This simplifies the scanner,
+but this also allows to have a unique index for each character in any file.
+Therefore the source location is a simple 32-bit integer whose type is `Location_Type`.
+From the location, `files_map` can deduce the source file (type is `Source_File_Entry`)
+and then the offset in the source file.  There is a line table for each source file in
+order to speed-up the conversion from file offset to line number and column number.
 
 The scanner (file :file:`vhdl-scanner.ad[sb]`) reads the source files and creates token
 from them.  The tokens are defined in file :file:`vhdl-tokens.ads`.  Tokens are scanned
diff --git a/doc/internals/Overview.rst b/doc/internals/Overview.rst
index 3be8772b4..fd29f5832 100644
--- a/doc/internals/Overview.rst
+++ b/doc/internals/Overview.rst
@@ -3,16 +3,23 @@
 Overview
 ########
 
-`GHDL` is architectured like a traditionnal compiler.  It has:
+.. image:: img/internals.png
+   :width: 350px
+   :align: center
 
-* a driver (sources in :file:`src/ghdldrv`) to call the programs (compiler, assembler, linker) if needed.
+`GHDL` is architectured like a traditionnal compiler. It has:
 
-* a library (sources in :file:`src/grt`) to help execution at run-time.
+* a driver (sources in :ghdlsrc:`src/ghdldrv <ghdldrv>`) to call the programs (compiler, assembler, linker) if needed.
 
-* a front-end (sources in :file:`src/vhdl`) to parse and analyse VHDL.
+* a runtime library named GRT (sources in :ghdlsrc:`src/grt <grt>`) to help execution at run-time. This ensures that execution is cycle-accurate.
 
-* a back-end (in fact many, sources are in :file:`src/ortho`) to generate code.
+* a front-end (sources in :ghdlsrc:`src/vhdl <vhdl>`) to parse and analyse VHDL. See :ref:`INT:Frontend` and :ref:`INT:AST`.
 
-The architecture is modular.  For example, it is possible to use the front-end in the `libghdl` library for the language server or to do synthesis (sources in :file:`src/synth`) instead of code generation.
+* multiple back-ends to generate either code or netlists.
+
+  * Three for :ref:`simulation <USING:Simulation>` (sources are in :ghdlsrc:`src/ortho <ortho>`): mcode, LLVM and GCC. See :ref:`BUILD`.
+  * Two for :ref:`synthesis <USING:Synthesis>` (sources in :ghdlsrc:`src/synth <synth>`): :ref:`--synth <Synth:command>` and :ref:`Synth:plugin`.
+
+The architecture is modular. For example, the front-end in the ``libghdl`` library is used for the language server.
 
 The main work is performed by the front-end, which is documented in the next chapter.
diff --git a/doc/internals/img/internals.png b/doc/internals/img/internals.png
new file mode 100644
index 000000000..cc6714287
--- /dev/null
+++ b/doc/internals/img/internals.png
diff --git a/doc/licenses.rst b/doc/licenses.rst
index d979d7cc1..aa2a65087 100644
--- a/doc/licenses.rst
+++ b/doc/licenses.rst
@@ -3,24 +3,24 @@
 Copyrights | Licenses
 #####################
 
-- The GHDL front-end package :samp:`std.textio`, and the runtime library :samp:`grt` are given under :ref:`LIC:GPLv2`.
+- The GHDL front-end package ``std.textio``, and the runtime library ``GRT`` are given under :ref:`LIC:GPLv2`.
 - The documentation is given under :ref:`LIC:CC-BY-SA`.
 
 .. WARNING::
-	As a consequence of the runtime copyright, you are not allowed to distribute an executable produced by GHDL without the VHDL sources. To my mind, this is not a real restriction, since it is pointless to distribute VHDL executable. Please, send a comment (:ref:`requesting_enhancements`) if you don't like this policy.
+	As a consequence of the runtime copyright, you are not allowed to distribute an executable produced by GHDL without allowing access to the VHDL sources. Please, send a comment (:ref:`requesting_enhancements`) if you don't like this policy.
 
 - The following packages are copyrighted by third parties (see corresponding sources for more information):
 
-	- These from library :samp:`ieee` are copyrighted by `Institute of Electrical and Electronics Engineers (IEEE) <https://www.ieee.org>`_ :
+	- These from library ``ieee`` are copyrighted by `Institute of Electrical and Electronics Engineers (IEEE) <https://www.ieee.org>`_ :
 
-		- :samp:`numeric_bit` and :samp:`numeric_std`: the source files may be distributed without change, except as permitted by the standard; these may not be sold or distributed for profit. [see also `IEEE 1076.3 <http://ieeexplore.ieee.org/document/592543/>`_ ]
-		- :samp:`std_logic_1164`, :samp:`Math_Real` and :samp:`Math_Complex`
-		- :samp:`VITAL_Primitives`, :samp:`VITAL_Timing` and :samp:`VITAL_Memory` [see also `IEEE 1076.4 <http://ieeexplore.ieee.org/document/954750/>`_ ]
+		- ``numeric_bit`` and ``numeric_std``: the source files may be distributed without change, except as permitted by the standard; these may not be sold or distributed for profit. [see also `IEEE 1076.3 <http://ieeexplore.ieee.org/document/592543/>`_ ]
+		- ``std_logic_1164``, ``Math_Real`` and ``Math_Complex``
+		- ``VITAL_Primitives``, ``VITAL_Timing`` and ``VITAL_Memory`` [see also `IEEE 1076.4 <http://ieeexplore.ieee.org/document/954750/>`_ ]
 
 	- The following sources may be used and distributed without restriction, provided that the copyright statements are not removed from the files and that any derivative work contains the copyright notice.
 
-		- :samp:`synopsys` directory: :samp:`std_logic_arith`, :samp:`std_logic_signed`, :samp:`std_logic_unsigned` and :samp:`std_logic_textio` are copyrighted by `Synopsys, Inc. <https://www.synopsys.com/>`_
-		- :samp:`mentor` directory: :samp:`std_logic_arith` is copyrighted by `Mentor Graphics <https://www.mentor.com>`_
+		- ``synopsys`` directory: ``std_logic_arith``, ``std_logic_signed``, ``std_logic_unsigned`` and ``std_logic_textio`` are copyrighted by `Synopsys, Inc. <https://www.synopsys.com/>`_
+		- ``mentor`` directory: ``std_logic_arith`` is copyrighted by `Mentor Graphics <https://www.mentor.com>`_
 
 .. _LIC:GPLv2:
 
@@ -63,7 +63,7 @@ Jensen, Adam               FreeBSD builds
 Koch, Markus               vendor pre-compile script for Lattice (GNU/Linux)
 Koontz, David              Mac OSX builds, LRM compliance work, bugfix analyses
 Lehmann, Patrick           Windows compile scripts, vendor library pre-compile scripts (win+lin), building in MinGW, AppVeyor integration.
-Martinez-Corral, Unai      Docker builds, Travis-CI & Docker, adapt/fix RTD theme
+Martinez-Corral, Unai      Docker, CI, Docs
 van Rantwijk, Joris        Debian packaging
 =========================  ============================================================
 
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.