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

3 files changed, 20 insertions, 7 deletions

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