doc: add/rename '[library.]top_unit [arch]', style (849a25e0)

3 files changed, 371 insertions, 299 deletions

diff --git a/doc/using/CommandReference.rst b/doc/using/CommandReference.rst
index d3a263c54..e6ffe33a5 100644
--- a/doc/using/CommandReference.rst
+++ b/doc/using/CommandReference.rst
@@ -4,7 +4,9 @@
 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.
+.. HINT::
+  The most common commands and options are shown in section :ref:`USING:Invoking`.
+  Here the advanced and experimental features are described.
 
 Environment variables
 =====================
@@ -23,9 +25,8 @@ Help [``-h``]
 
 .. option:: --help, -h
 
-Display (on the standard output) a short description of the all the commands
-available. If the help switch is followed by a command switch, then options
-for that second command are displayed::
+Display (on the standard output) a short description of the all the commands available.
+If the help switch is followed by a command switch, then options for that second command are displayed::
 
   ghdl --help
   ghdl -h
@@ -62,7 +63,8 @@ Display the GHDL version.
 File commands
 =============
 
-The following commands act on one or several files. These are not analyzed, therefore, they work even if a file has semantic errors.
+The following commands act on one or several files.
+These are not analyzed, therefore, they work even if a file has semantic errors.
 
 .. index:: cmd file format
 
@@ -81,9 +83,9 @@ Pretty print [``--pp-html``]
 
 .. option:: --pp-html <[options] file...>
 
-The files are just scanned and an html file with syntax highlighting is generated on standard output. Since the files
-are not even parsed, erroneous files or incomplete designs can be pretty printed. The style of the html file can be
-modified with the :option:`--format` option.
+The files are just scanned and an html file with syntax highlighting is generated on standard output.
+Since the files are not even parsed, erroneous files or incomplete designs can be pretty printed.
+The style of the html file can be modified with the :option:`--format` option.
 
 .. index:: cmd file find
 
@@ -92,7 +94,8 @@ Find [``-f``]
 
 .. option:: -f <file...>
 
-The files are scanned, parsed and the names of design units are displayed. Design units marked with two stars are candidates to be at the apex of a design hierarchy.
+The files are scanned, parsed and the names of design units are displayed.
+Design units marked with two stars are candidates to be at the apex of a design hierarchy.
 
 .. index:: cmd file chop
 
@@ -101,17 +104,21 @@ Chop [``--chop``]
 
 .. option:: --chop <files...>
 
-The provided files are read, and a file is written in the current directory for every design unit. Each filename is built according to the type:
+The provided files are read, and a file is written in the current directory for every design unit.
+Each filename is built according to the type:
 
-* For an entity declaration, a package declaration, or a configuration the file name is :file:`NAME.vhdl`, where `NAME` is the name of the design unit.
+* For an entity declaration, a package declaration, or a configuration the file name is :file:`NAME.vhdl`, where `NAME`
+  is the name of the design unit.
 * For a package body, the filename is :file:`NAME-body.vhdl`.
 * Finally, for an architecture `ARCH` of an entity `ENTITY`, the filename is :file:`ENTITY-ARCH.vhdl`.
 
-Since the input files are parsed, this command aborts in case of syntax error. The command aborts too if a file to be written already exists.
+Since the input files are parsed, this command aborts in case of syntax error.
+The command aborts too if a file to be written already exists.
 
 Comments between design units are stored into the most adequate files.
 
-This command may be useful to split big files, if your computer doesn't have enough memory to compile such files. The size of the executable is reduced too.
+This command may be useful to split big files, if your computer doesn't have enough memory to compile such files.
+The size of the executable is reduced too.
 
 .. index:: cmd file lines
 
@@ -129,10 +136,14 @@ XML tree generation [``--file-to-xml``]
 
 .. option:: --file-to-xml
 
-  Outputs an XML representation of the decorated syntax tree for the input file and its dependencies. It can be used for VHDL tooling using semantic information, like style checkers, documentation extraction, complexity estimation, etc.
+  Outputs an XML representation of the decorated syntax tree for the input file and its dependencies.
+  It can be used for VHDL tooling using semantic information, like style checkers, documentation extraction, complexity
+  estimation, etc.
 
 .. WARNING::
-   * The AST slightly changes from time to time (particularly when new nodes are added for new language features), so be liberal in what is allowed by your tool. Also, the XML can be quite large so consider it only during prototyping.
+   * The AST slightly changes from time to time (particularly when new nodes are added for new language features), so be
+     liberal in what is allowed by your tool.
+     Also, the XML can be quite large so consider it only during prototyping.
    * Note that at this time there is no XML dump of the elaborated design.
 
 .. _gccllvm-only-programs:
@@ -145,33 +156,50 @@ GCC/LLVM only commands
 Bind [``--bind``]
 ---------------------
 
-.. option:: --bind <[options] primary_unit [secondary_unit]>
+.. option:: --bind <[options] [library.]top_unit [arch]>
 
-Performs only the first stage of the elaboration command; the list of object files is created but the executable is not built. This command should be used only when the main entry point is not GHDL.
+Performs only the first stage of the elaboration command; the list of object files is created but the executable is not
+built.
+This command should be used only when the main entry point is not GHDL.
 
 .. HINT::
-   Currently, the objects generated by :option:`--bind` are created in the working directory. This behaviour is different from other object files generated with :option:`-a`, which are always placed in the same directory as the `WORK` library. It is possible to provide an output path with ``ghdl --bind -o path/primary_unit primary_unit``. However, ``ghdl --list-link`` will only search in the current path.
+   Currently, the objects generated by :option:`--bind` are created in the working directory.
+   This behaviour is different from other object files generated with :option:`-a`, which are always placed in the same
+   directory as the `WORK` library.
+   It is possible to provide an output path with ``ghdl --bind -o path/top_unit [library.]top_unit [arch]``.
+   However, ``ghdl --list-link`` will only search in the current path.
 
 .. index:: cmd GCC/LLVM linking
 
 Link [``--link``]
 ---------------------
 
-.. option:: --link <[options] primary_unit [secondary_unit]>
+.. option:: --link <[options] [library.]top_unit [arch]>
 
-Performs only the second stage of the elaboration command: the executable is created by linking the files of the object files list. This command is available only for completeness. The elaboration command is equivalent to the bind command followed by the link command.
+Performs only the second stage of the elaboration command: the executable is created by linking the files of the object
+files list.
+This command is available only for completeness.
+The elaboration command is equivalent to the bind command followed by the link command.
 
 .. index:: cmd GCC/LLVM list link
 
 List link [``--list-link``]
 ---------------------------
 
-.. option:: --list-link <primary_unit [secondary_unit]>
+.. option:: --list-link <[library.]top_unit [arch]>
 
-This command may be used only after a bind command. GHDL displays all the files which will be linked to create an executable and additional arguments for the linker. This command is intended to add object files in a link of a foreign program. This command should be used only after ``ghdl --bind``, as some files generated by it are looked for in the current path.
+This command may be used only after a bind command.
+GHDL displays all the files which will be linked to create an executable and additional arguments for the linker.
+This command is intended to add object files in a link of a foreign program.
+This command should be used only after ``ghdl --bind``, as some files generated by it are looked for in the current path.
 
 .. HINT::
-   One of the arguments returned by ``--list-link`` is ``-Wl,--version-script=PREFIX/lib/ghdl/grt.ver``, where `PREFIX` is the installation path of GHDL. This will hide most of the symbols when the target executable binary is built. In some contexts, where the binary is to be loaded dynamically, the user might want additional symbols to be accessible. There are two possible approaches to have it done:
+   One of the arguments returned by ``--list-link`` is ``-Wl,--version-script=PREFIX/lib/ghdl/grt.ver``, where `PREFIX`
+   is the installation path of GHDL.
+   This will hide most of the symbols when the target executable binary is built.
+   In some contexts, where the binary is to be loaded dynamically, the user might want additional symbols to be
+   accessible.
+   There are two possible approaches to have it done:
 
    * Filter the output of ``--list-link`` with e.g. ``sed``.
    * Provide an additional non-anonymous version script: ``-Wl,-Wl,--version-script=file.ver``.
@@ -181,15 +209,20 @@ Options
 
 .. option:: --GHDL1<=COMMAND>
 
-Use ``COMMAND`` as the command name for the compiler. If ``COMMAND`` is not a path, then it is searched in the path.
+Use ``COMMAND`` as the command name for the compiler.
+If ``COMMAND`` is not a path, then it is searched in the path.
 
 .. option:: --AS<=COMMAND>
 
-Use ``COMMAND`` as the command name for the assembler. If ``COMMAND`` is not a path, then it is searched in the path. The default is ``as``.
+Use ``COMMAND`` as the command name for the assembler.
+If ``COMMAND`` is not a path, then it is searched in the path.
+The default is ``as``.
 
 .. option:: --LINK<=COMMAND>
 
-Use ``COMMAND`` as the linker driver. If ``COMMAND`` is not a path, then it is searched in the path. The default is ``gcc``.
+Use ``COMMAND`` as the linker driver.
+If ``COMMAND`` is not a path, then it is searched in the path.
+The default is ``gcc``.
 
 .. _passing-options-to-other-programs:
 
@@ -198,9 +231,11 @@ Passing options to other programs
 
 .. WARNING:: These options are only available with GCC/LLVM.
 
-For many commands, GHDL acts as a driver: it invokes programs to perform the command. You can pass arbitrary options to these programs.
+For many commands, GHDL acts as a driver: it invokes programs to perform the command.
+You can pass arbitrary options to these programs.
 
-Both the compiler and the linker are in fact GCC programs. See the GCC manual for details on GCC options.
+Both the compiler and the linker are in fact GCC programs.
+See the GCC manual for details on GCC options.
 
 .. option:: -Wc,<OPTION>
 
diff --git a/doc/using/InvokingGHDL.rst b/doc/using/InvokingGHDL.rst
index 29f5e1681..1b0805591 100644
--- a/doc/using/InvokingGHDL.rst
+++ b/doc/using/InvokingGHDL.rst
@@ -4,15 +4,17 @@
 Invoking GHDL
 #############
 
-The form of the :program:`ghdl` command is ``ghdl command [options...]``. There are multiple available commands, but these
-general rules apply:
+The form of the :program:`ghdl` command is ``ghdl command [options...]``.
+There are multiple available commands, but these general rules apply:
 
-* The first argument selects the command. The options are used to slightly modify the action.
-* No option is allowed before the command. Except for the run command, no option is allowed after a filename or a unit name.
+* The first argument selects the command.
+  The options are used to slightly modify the action.
+* No option is allowed before the command.
+  Except for the run command, no option is allowed after a filename or a unit name.
 
 .. HINT::
-  If the number of options is large and the command line length is beyond the system limit, you can use a response file. An
-  argument that starts with a ``@`` is considered as a response file; it is replaced by arguments read from the file
+  If the number of options is large and the command line length is beyond the system limit, you can use a response file.
+  An argument that starts with a ``@`` is considered as a response file; it is replaced by arguments read from the file
   (separated by blanks and end of line).
 
 .. HINT::
@@ -20,8 +22,8 @@ general rules apply:
   :ref:`REF:Command`.
 
 .. WARNING::
-  During analysis and elaboration GHDL may read the ``std`` and ``ieee`` files. The location of these files is based on the
-  prefix, which is (in order of priority):
+  During analysis and elaboration GHDL may read the ``std`` and ``ieee`` files.
+  The location of these files is based on the prefix, which is (in order of priority):
 
   * the :option:`--PREFIX` command line option
   * the :envvar:`GHDL_PREFIX` environment variable
@@ -45,12 +47,14 @@ Analysis [``-a``]
 
 .. option:: -a <[options...] file...>
 
-Analyzes/compiles one or more files, and creates an object file for each source file. Any argument starting with a
-dash is an option, the others are filenames. No options are allowed after a filename argument. GHDL analyzes each
-filename in the given order, and stops the analysis in case of error (remaining files are not analyzed).
+Analyzes/compiles one or more files, and creates an object file for each source file.
+Any argument starting with a dash is an option, the others are filenames.
+No options are allowed after a filename argument.
+GHDL analyzes each filename in the given order, and stops the analysis in case of error (remaining files are not
+analyzed).
 
-See :ref:`GHDL:options`, for details on the GHDL options. For example, to produce debugging information such as line
-numbers, use: ``ghdl -a -g my_design.vhdl``.
+See :ref:`GHDL:options`, for details on the GHDL options.
+For example, to produce debugging information such as line numbers, use: ``ghdl -a -g my_design.vhdl``.
 
 
 .. index:: cmd elaboration
@@ -60,35 +64,44 @@ numbers, use: ``ghdl -a -g my_design.vhdl``.
 Elaboration [``-e``]
 --------------------
 
-.. option:: -e <[options...] primary_unit [secondary_unit]>
+.. option:: -e <[options...] [library.]top_unit [arch]>
 
 Re-analyzes all the configurations, entities, architectures and package declarations, and creates the default
-configurations and the default binding indications according to the LRM rules. It also generates the list of object
-files required for the executable. Then, it links all these files with the runtime library.
+configurations and the default binding indications according to the LRM rules.
+It also generates the list of object files required for the executable.
+Then, it links all these files with the runtime library (GRT).
 
-* The elaboration command, :option:`-e`, must be followed by a name of either:
+The elaboration command, :option:`-e`, must be followed by a ``top_unit`` name denoting either of:
 
   * a configuration unit
   * an entity unit
-  * an entity unit followed by a name of an architecture unit
+  * an entity unit followed by a secondary unit (the name of an architecture unit)
 
-  Name of the units must be a simple name, without any dot. You can select the name of the `WORK` library with the
-  :option:`--work=NAME <--work>` option, as described in :ref:`GHDL:options`. See section :ref:`Top_entity`, for the
-  restrictions on the root design of a hierarchy.
+* Name of the top units can be either a simple name (without dots), or the name of a logical library followed by a dot
+  and a simple name.
+  The latter is equivalent to using :option:`--work=NAME <--work>` described in :ref:`GHDL:options`:
+  ``-e <[options...] --work=library top_unit [arch]>``.
+  It selects the name of the library to be used as ``WORK``.
+  See section :ref:`Top_entity`, for the restrictions on the root/top unit of a hierarchy.
+*  Name of the secondary units must be a simple name; they cannot contain any dot.
+
+With regard to the artifacts:
 
 * If the GCC/LLVM backend was enabled during the compilation of GHDL, the elaboration command creates an executable
-  containing the code of the VHDL sources, the elaboration code and simulation code to execute a design hierarchy. The
-  executable is created in the current directory and the the filename is the name of the primary unit, or for the latter
-  case, the concatenation of the name of the primary unit, a dash, and the name of the secondary unit (or architecture).
+  containing the code of the VHDL sources, the elaboration code and simulation code for executing a design hierarchy.
+  The executable is created in the current directory and the the filename is the name of the primary unit, or for the
+  latter case, the concatenation of the name of the primary unit, a dash, and the name of the secondary unit.
   Option ``-o`` followed by a filename can override the default executable filename.
 
-* If mcode is used, this command elaborates the design but does not generate anything. Since the run command also
-  elaborates the design, this can be skipped.
+* If mcode is used, this command elaborates the design but does not generate anything.
+  Since the run command also elaborates the design, this can be skipped.
 
-  .. WARNING::
-    This elaboration command is not a complete elaboration in terms of the VHDL standard. The actual elaboration is
-    performed at runtime. Therefore, in order to get a complete VHDL elaboration without running the simulation,
-    ``ghdl --elab-run --no-run`` is required. See :option:`--no-run`.
+.. WARNING::
+  This elaboration command is not a complete elaboration in terms of the VHDL standard.
+  The actual elaboration is performed at runtime.
+  Therefore, in order to get a complete VHDL elaboration without running the simulation, ``ghdl --elab-run --no-run``
+  is required.
+  See :option:`--no-run`.
 
 
 .. index:: cmd run
@@ -98,22 +111,25 @@ files required for the executable. Then, it links all these files with the runti
 Run [``-r``]
 ------------
 
-.. option:: -r <[options...] primary_unit [secondary_unit] [simulation_options...]>
+.. option:: -r <[options...] [library.]top_unit [arch] [simulation_options...]>
 
-Runs/simulates a design. Two sets of options are accepted, both of them being separated by ``primary_unit [secondary_unit]``.
-For the first set, ``options...``, arguments are the same as for the :ref:`elaboration command <Elaboration:command>`. For
-the second set, ``simulation_options...``, arguments are defined in :ref:`USING:Simulation`.
+Runs/simulates a design.
+Two sets of options are accepted, both of them being separated by ``[library.]top_unit [arch]``.
+For the first set, ``options...``, arguments are the same as for the :ref:`elaboration command <Elaboration:command>`.
+For the second set, ``simulation_options...``, arguments are defined in :ref:`USING:Simulation`.
 
-* GGC/LLVM: the filename of the executable is determined and it is executed. Elaboration options are ignored. You may also
-  directly execute the program. The executable must be in the current directory.
-* mcode: the design is elaborated and the simulation is launched. As a consequence, you must use the same options used during
-  analysis.
+* GGC/LLVM: the filename of the executable is determined and it is executed.
+  Elaboration options are ignored.
+  You may also directly execute the program.
+  The executable must be in the current directory.
+* mcode: the design is elaborated and the simulation is launched.
+  As a consequence, you must use the same options used during analysis.
 
 This command exists for three reasons:
 
+* It works with mcode implementation, where the executable code is generated in memory.
 * You are using GCC/LLVM, but you don't need to create the executable program name.
 * It is coherent with the :option:`-a` and :option:`-e` commands.
-* It works with mcode implementation, where the executable code is generated in memory.
 
 
 .. index:: cmd elaborate and run
@@ -123,10 +139,11 @@ This command exists for three reasons:
 Elaborate and run [``--elab-run``]
 ----------------------------------
 
-.. option:: --elab-run <[options...] primary_unit [secondary_unit] [simulation_options...]>
+.. option:: --elab-run <[options...] [library.]top_unit [arch] [simulation_options...]>
 
-Acts like the elaboration command followed by the run command. Note that this command accepts two sets of options. See
-:option:`-e`, :option:`-r` and :ref:`USING:Simulation`.
+Acts like the elaboration command followed by the run command.
+Note that this command accepts two sets of options.
+See :option:`-e`, :option:`-r` and :ref:`USING:Simulation`.
 
 
 .. index:: cmd checking syntax
@@ -136,8 +153,9 @@ Check syntax [``-s``]
 
 .. option:: -s <[options] files>
 
-Analyze files but do not generate code. This command may be used to check the syntax of files. It does not update the
-library.
+Analyze files but do not generate code.
+This command may be used to check the syntax of files.
+It does not update the library.
 
 
 .. index:: cmd analyze and elaborate
@@ -145,16 +163,18 @@ library.
 Analyze and elaborate [``-c``]
 ------------------------------
 
-.. option:: -c <[options] file... -<e|r> primary_unit [secondary_unit]>
+.. option:: -c <[options] file... -<e|r> top_unit [arch]>
 
 .. HINT::
   With GCC/LLVM, :option:`-e` should be used, and :option:`-r` with mcode.
 
-The files are first parsed, and then a elaboration is performed, which drives an analysis. Effectively, analysis and
-elaboration are combined, but there is no explicit call to :option:`-a`. With GCC/LLVM, code is generated during the
-elaboration. With mcode, the simulation is launched after the elaboration.
+The files are first parsed, and then a elaboration is performed, which drives an analysis.
+Effectively, analysis and elaboration are combined, but there is no explicit call to :option:`-a`.
+With GCC/LLVM, code is generated during the elaboration.
+With mcode, the simulation is launched after the elaboration.
 
-All the units of the files are put into the `work` library. But, the work library is neither read from disk nor saved.
+All the units of the files are put into the `work` library.
+But, the work library is neither read from disk nor saved.
 Therefore, you must give all the files of the `work` library your design needs.
 
 The advantages over the traditional approach (analyze and then elaborate) are:
@@ -166,8 +186,9 @@ The advantages over the traditional approach (analyze and then elaborate) are:
 
 .. HINT::
   However, you should know that most of the time is spent in code generation and the analyze and elaborate command
-  generates code for all units needed, even units of ``std`` and ``ieee`` libraries. Therefore, according to the design,
-  the time for this command may be higher than the time for the analyze command followed by the elaborate command.
+  generates code for all units needed, even units of ``std`` and ``ieee`` libraries.
+  Therefore, according to the design, the time for this command may be higher than the time for the analyze command
+  followed by the elaborate command.
 
 .. WARNING::
   This command is still under development. In case of problems, you should go back to the traditional way.
@@ -176,8 +197,8 @@ The advantages over the traditional approach (analyze and then elaborate) are:
 Design rebuilding commands
 ==========================
 
-Analyzing and elaborating a design consisting of several files can be tricky, due to dependencies. GHDL has a few commands
-to rebuild a design.
+Analyzing and elaborating a design consisting of several files can be tricky, due to dependencies.
+GHDL has a few commands for rebuilding a design.
 
 
 .. index:: cmd importing files
@@ -189,15 +210,16 @@ Import [``-i``]
 
 .. option:: -i <[options] file...>
 
-All the files specified in the command line are scanned, parsed and added into the libraries but as not yet analyzed. No
-object files are created. Its purpose is to localize design units in the design files. The make command will then be able to
-recursively build a hierarchy from an entity name or a configuration name.
+All the files specified in the command line are scanned, parsed and added into the libraries but as not yet analyzed.
+No object files are created.
+Its purpose is to localize design units in the design files.
+The make command will then be able to recursively build a hierarchy from an entity name or a configuration name.
 
 .. HINT::
-  * Note that all the files are added to the work library. If you have many libraries, you must use the command for each
-    library.
-  * Since the files are parsed, there must be correct files. However, since they are not analyzed, many errors are tolerated
-    by this command.
+  * Note that all the files are added to the work library.
+    If you have many libraries, you must use the command for each library.
+  * Since the files are parsed, there must be correct files.
+    However, since they are not analyzed, many errors are tolerated by this command.
 
 See :option:`-m`, to actually build the design.
 
@@ -209,36 +231,44 @@ See :option:`-m`, to actually build the design.
 Make [``-m``]
 -------------
 
-.. option:: -m <[options] primary [secondary]>
+.. option:: -m <[options] [library.]top_unit [arch]>
 
-Analyze automatically outdated files and elaborate a design. The primary unit denoted by the ``primary`` argument must already
-be known by the system, either because you have already analyzed it (even if you have modified it) or because you have imported
-it. A file may be outdated because it has been modified (e.g. you have just edited it), or because a design unit contained in
-the file depends on a unit which is outdated. This rule is of course recursive.
+Analyze automatically outdated files and elaborate a design.
+The primary unit denoted by the ``[library.]top_unit`` argument must already be known by the system, either because you
+have already analyzed it (even if you have modified it) or because you have imported it.
+A file may be outdated because it has been modified (e.g. you have just edited it), or because a design unit contained
+in the file depends on a unit which is outdated.
+This rule is recursive.
 
-* With option ``--bind``, GHDL will stop before the final linking step. This is useful when the main entry point is not GHDL
-  and you're linking GHDL object files into a foreign program.
-* With option ``-f`` (force), GHDL analyzes all the units of the work library needed to create the design hierarchy. Outdated
-  units are recompiled. This is useful if you want to compile a design hierarchy with new compilation flags (for example, to
-  add the ``-g`` debugging option).
+* With option ``--bind``, GHDL will stop before the final linking step.
+  This is useful when the main entry point is not GHDL and you're linking GHDL object files into a foreign program.
+* With option ``-f`` (force), GHDL analyzes all the units of the work library needed to create the design hierarchy.
+  Outdated units are recompiled.
+  This is useful if you want to compile a design hierarchy with new compilation flags (for example, to add the ``-g``
+  debugging option).
 
-The make command will only re-analyze design units in the work library. GHDL fails if it has to analyze an outdated unit from
-another library.
+.. IMPORTANT::
+  The make command will only re-analyze design units in the work library.
+  GHDL fails if it has to analyze an outdated unit from another library.
 
-The purpose of this command is to be able to compile a design without prior knowledge of file order. In the VHDL model, some
-units must be analyzed before others (e.g. an entity before its architecture). It might be a nightmare to analyze a full
-design of several files if you don't have the ordered list of files. This command computes an analysis order.
+The purpose of this command is to be able to compile a design without prior knowledge of file order.
+In the VHDL model, some units must be analyzed before others (e.g. an entity before its architecture).
+It might be a nightmare to analyze a full design of several files if you don't have the ordered list of files.
+This command computes an analysis order.
 
-The make command fails when a unit was not previously parsed. For example, if you split a file containing several design
-units into several files, you must either import these new files or analyze them so that GHDL knows in which file these
-units are.
+The make command fails when a unit was not previously parsed.
+For example, if you split a file containing several design units into several files, you must either import these new
+files or analyze them so that GHDL knows in which file these units are.
 
-The make command imports files which have been modified. Then, a design hierarchy is internally built as if no units are
-outdated. Then, all outdated design units, using the dependencies of the design hierarchy, are analyzed. If necessary, the
-design hierarchy is elaborated.
+The make command imports files which have been modified.
+Then, a design hierarchy is internally built as if no units are outdated.
+Then, all outdated design units, using the dependencies of the design hierarchy, are analyzed.
+If necessary, the design hierarchy is elaborated.
 
-This is not perfect, since the default architecture (the most recently analyzed one) may change while outdated design files
-are analyzed. In such a case, re-run the make command of GHDL.
+.. HINT::
+  This is not perfect, since the default architecture (the most recently analyzed one) may change while outdated design
+  files are analyzed.
+  In such a case, re-run the make command of GHDL.
 
 
 .. index:: cmd generate makefile
@@ -246,7 +276,7 @@ are analyzed. In such a case, re-run the make command of GHDL.
 Generate Makefile [``--gen-makefile``]
 --------------------------------------
 
-.. option:: --gen-makefile <[options] primary [secondary]>
+.. option:: --gen-makefile <[options] [library.]top_unit [arch]>
 
 This command works like the make command (see :option:`-m`), but only a makefile is generated on the standard output.
 
@@ -255,7 +285,7 @@ This command works like the make command (see :option:`-m`), but only a makefile
 Generate dependency file command [``--gen-depends``]
 ----------------------------------------------------
 
-.. option:: --gen-depends <[options] primary [secondary]>
+.. option:: --gen-depends <[options] [library.]top_unit [arch]>
 
 Generate a Makefile containing only dependencies to build a design unit.
 
@@ -277,42 +307,47 @@ Options
 
 .. option:: --work=<LIB_NAME>
 
-  Specify the name of the ``WORK`` library. Analyzed units are always placed in the library logically named ``WORK``. With
-  this option, you can set its name. By default, the name is ``work``.
+  Specify the name of the ``WORK`` library. Analyzed units are always placed in the library logically named ``WORK``.
+  With this option, you can set its name.
+  By default, the name is ``work``.
 
-  `GHDL` checks whether ``WORK`` is a valid identifier. Although being more or less supported, the ``WORK`` identifier
-  should not be an extended identifier, since the filesystem may prevent it from working correctly (due to case sensitivity
-  or forbidden characters in filenames).
+  `GHDL` checks whether ``WORK`` is a valid identifier.
+  Although being more or less supported, the ``WORK`` identifier should not be an extended identifier, since the
+  filesystem may prevent it from working correctly (due to case sensitivity or forbidden characters in filenames).
 
-  `VHDL` rules forbid you from adding units to the ``std`` library. Furthermore, you should not put units in the ``ieee`` library.
+  .. ATTENTION::
+    `VHDL` rules forbid you from adding units to the ``std`` library.
+    Furthermore, you should not put units in the ``ieee`` library.
+
+  .. HINT::
+    Since `849a25e0 <https://github.com/ghdl/ghdl/commit/849a25e02cfb359e3d9313060156b0643495548b>`__, this option can
+    be alternatively provided to several commands by prepending the library name to the top unit name.
+    See, for instance, :option:`-e`.
 
 .. option:: --workdir=<DIR>
 
-  Specify the directory where the ``WORK`` library is located. When this option is not present, the ``WORK`` library is in
-  the current directory. The object files created by the compiler are always placed in the same directory as the ``WORK`` library.
+  Specify the directory where the ``WORK`` library is located.
+  When this option is not present, the ``WORK`` library is in the current directory.
+  The object files created by the compiler are always placed in the same directory as the ``WORK`` library.
 
   Use option :option:`-P <-P>` to specify where libraries other than ``WORK`` are placed.
 
 .. option:: --std=<STANDARD>
 
-  Specify the standard to use. By default, the standard is ``93c``,
-  which means VHDL-93 with relaxed rules. For details on ``STANDARD``
-  values see section :ref:`VHDL_standards`.
+  Specify the standard to use. By default, the standard is ``93c``, which means VHDL-93 with relaxed rules.
+  For details on ``STANDARD`` values see section :ref:`VHDL_standards`.
 
-  .. IMPORTANT:: This option resets the effect of :option:`-frelaxed`, so it should
-    be the first option.
+  .. IMPORTANT:: This option resets the effect of :option:`-frelaxed`, so it should be the first option.
 
 .. option:: -fsynopsys
 
-  Allow the use of synopsys non-standard packages
-  (``std_logic_arith``, ``std_logic_signed``, ``std_logic_unsigned``,
-  ``std_logic_textio``).  These packages are
-  present in the ieee library but without this option it's an error to
-  use them.
+  Allow the use of synopsys non-standard packages (``std_logic_arith``, ``std_logic_signed``, ``std_logic_unsigned``,
+  ``std_logic_textio``).
+  These packages are present in the ieee library but without this option it's an error to use them.
 
-  The synopsys packages were created by some companies, and are popular. However
-  they are not standard packages, and have been placed in the `IEEE`
-  library without the permission from the ``ieee``.
+  The synopsys packages were created by some companies, and are popular.
+  However they are not standard packages, and have been placed in the `IEEE` library without the permission from the
+  ``ieee``.
 
 .. option:: --ieee=<IEEE_VAR>
 
@@ -322,63 +357,58 @@ Options
   Select the ``IEEE`` library to use. ``IEEE_VAR`` must be one of:
 
   none
-    Do not supply an `IEEE` library. Any library clause with the ``IEEE``
-    identifier will fail, unless you have created your own library with
-    the `IEEE` name.
+    Do not supply an `IEEE` library. Any library clause with the ``IEEE`` identifier will fail, unless you have created
+    your own library with the `IEEE` name.
 
   standard
-    Supply an `IEEE` library containing only packages defined by
-    ``ieee`` standards. Currently, there are the multivalue logic system
-    package ``std_logic_1164`` defined by IEEE 1164, the synthesis
-    packages ``numeric_bit`` and ``numeric_std`` defined by IEEE
-    1076.3, and the ``vital`` packages ``vital_timing`` and
-    ``vital_primitives``, defined by IEEE 1076.4. The version of these
-    packages is defined by the VHDL standard used. See section :ref:`VITAL_packages`,
-    for more details.
+    Supply an `IEEE` library containing only packages defined by ``ieee`` standards.
+    Currently, there are the multivalue logic system package ``std_logic_1164`` defined by IEEE 1164, the synthesis
+    packages ``numeric_bit`` and ``numeric_std`` defined by IEEE 1076.3, and the ``vital`` packages ``vital_timing`` and
+    ``vital_primitives``, defined by IEEE 1076.4.
+    The version of these packages is defined by the VHDL standard used.
+    See section :ref:`VITAL_packages`, for more details.
 
   synopsys
-    This option is now deprecated.  It is equivalent to
-    ``--ieee=standard`` and ``-fsynopsys``.
+    This option is now deprecated.
+    It is equivalent to ``--ieee=standard`` and ``-fsynopsys``.
 
-  To avoid errors, you must use the same `IEEE` library for all units of
-  your design, and during elaboration.
+  To avoid errors, you must use the same `IEEE` library for all units of your design, and during elaboration.
 
 .. option:: -P<DIRECTORY>
 
-  Add `DIRECTORY` to the end of the list of directories to be searched for
-  library files. A library is searched in `DIRECTORY` and also in
-  `DIRECTORY/LIB/vVV` (where `LIB` is the name of the library and `VV`
+  Add `DIRECTORY` to the end of the list of directories to be searched for library files.
+  A library is searched in `DIRECTORY` and also in `DIRECTORY/LIB/vVV` (where `LIB` is the name of the library and `VV`
   the vhdl standard).
 
-  The `WORK` library is always searched in the path specified by the
-  :option:`--workdir` option, or in the current directory if the latter
-  option is not specified.
+  The `WORK` library is always searched in the path specified by the :option:`--workdir` option, or in the current
+  directory if the latter option is not specified.
 
 .. option:: -fexplicit
 
   When two operators are overloaded, give preference to the explicit declaration.
-  This may be used to avoid the most common pitfall of the ``std_logic_arith``
-  package. See section :ref:`IEEE_library_pitfalls`, for an example.
+  This may be used to avoid the most common pitfall of the ``std_logic_arith`` package.
+  See section :ref:`IEEE_library_pitfalls`, for an example.
 
-.. WARNING:: This option is not set by default. I don't think this option is a good feature, because it breaks the
-  encapsulation rule. When set, an operator can be silently overridden in another package. You'd do better to fix your
-  design and use the ``numeric_std`` package.
+.. WARNING::
+  This option is not set by default.
+  We don't think this option is a good feature, because it breaks the encapsulation rule.
+  When set, an operator can be silently overridden in another package.
+  You'd do better to fix your design and use the ``numeric_std`` package.
 
 .. option:: -frelaxed
 .. option:: -frelaxed-rules
 
   .. IMPORTANT:: The effects of this option are reset by :option:`--std`, so it should be placed *after* that option.
 
-  Slightly relax some rules to be compatible with various other
-  simulators or synthesizers:
+  Slightly relax some rules to be compatible with various other simulators or synthesizers:
 
   * VHDL-87 file declarations are accepted;
 
-  * Default binding indication rules of VHDL-02 are used. Default binding rules
-    are often used, but they are particularly obscure before VHDL-02.
+  * Default binding indication rules of VHDL-02 are used. Default binding rules are often used, but they are
+    particularly obscure before VHDL-02.
 
-  * Within an object declaration, allow references to the name (which references the hidden declaration). This ignores the
-    error in the following code:
+  * Within an object declaration, allow references to the name (which references the hidden declaration).
+    This ignores the error in the following code:
 
     .. code-block:: VHDL
 
@@ -393,39 +423,37 @@ Options
 
     Some code (such as Xilinx packages) have such constructs, which are invalid.
 
-    (The scope of the ``state1`` constant starts at the `constant`
-    keyword. Because the constant ``state1`` and the enumeration
-    literal ``state1`` are homographs, the enumeration literal is
+    (The scope of the ``state1`` constant starts at the `constant` keyword.
+    Because the constant ``state1`` and the enumeration literal ``state1`` are homographs, the enumeration literal is
     hidden in the immediate scope of the constant).
 
-  This option also relaxes the rules about pure functions. Violations result in warnings instead of errors.
+  This option also relaxes the rules about pure functions.
+  Violations result in warnings instead of errors.
 
 .. option:: -fpsl
 
-  Enable parsing of PSL assertions within comments. See section :ref:`PSL_implementation` for more details.
+  Enable parsing of PSL assertions within comments.
+  See section :ref:`PSL_implementation` for more details.
 
 .. option:: --mb-comments, -C
 
   Allow UTF8 or multi-bytes chars in a comment.
 
-  According to the VHDL standards before 2002, the only characters
-  allowed in a source file (and that includes the comments) are the
-  graphical characters of the ISO 8859-1 character set.  This is
-  incompatible with comments using UTF-8 or some other encoding.  This
-  option lift this restriction.
+  According to the VHDL standards before 2002, the only characters allowed in a source file (and that includes the
+  comments) are the graphical characters of the ISO 8859-1 character set.
+  This is incompatible with comments using UTF-8 or some other encoding.
+  This option lift this restriction.
 
 .. option:: --syn-binding
 
-  Use synthesizer rules for component binding. During elaboration, if
-  a component is not bound to an entity using VHDL LRM rules, try to
-  find in any known library an entity whose name is the same as the
-  component name.
+  Use synthesizer rules for component binding.
+  During elaboration, if a component is not bound to an entity using VHDL LRM rules, try to find in any known library an
+  entity whose name is the same as the component name.
 
   This rule is known as the synthesizer rule.
 
-  There are two key points: normal VHDL LRM rules are tried first and
-  entities are searched only in known libraries. A known library is a
-  library which has been named in your design.
+  There are two key points: normal VHDL LRM rules are tried first and entities are searched only in known libraries.
+  A known library is a library which has been named in your design.
 
   This option is only useful during elaboration.
 
@@ -433,23 +461,26 @@ Options
 
   Define the output format of some options, such as :option:`--pp-html` or :option:`--xref-html`.
 
-  * By default or when :option:`--format=html2 <--format>` is specified, generated files follow the HTML 2.0 standard, and
-    colours are specified with `<FONT>` tags. However, colours are hard-coded.
+  * By default or when :option:`--format=html2 <--format>` is specified, generated files follow the HTML 2.0 standard,
+    and colours are specified with `<FONT>` tags.
+    However, colours are hard-coded.
 
-  * If :option:`--format=css <--format>` is specified, generated files follow the HTML 4.0 standard, and use the CSS-1 file
-    :file:`ghdl.css` to specify colours. This file is generated only if it does not already exist (it is never overwritten)
-    and can be customized by the user to change colours or appearance. Refer to a generated file and its comments for more
-    information.
+  * If :option:`--format=css <--format>` is specified, generated files follow the HTML 4.0 standard, and use the CSS-1
+    file :file:`ghdl.css` to specify colours.
+    This file is generated only if it does not already exist (it is never overwritten) and can be customized by the user
+    to change colours or appearance.
+    Refer to a generated file and its comments for more information.
 
 .. option:: --no-vital-checks
 .. option:: --vital-checks
 
   Disable or enable checks of restriction on VITAL units. Checks are enabled by default.
 
-  Checks are performed only when a design unit is decorated by a VITAL attribute. The VITAL attributes are ``VITAL_Level0``
-  and ``VITAL_Level1``, both declared in the ``ieee.VITAL_Timing`` package.
+  Checks are performed only when a design unit is decorated by a VITAL attribute.
+  The VITAL attributes are ``VITAL_Level0`` and ``VITAL_Level1``, both declared in the ``ieee.VITAL_Timing`` package.
 
-  Currently, VITAL checks are only partially implemented. See section :ref:`VHDL_restrictions_for_VITAL` for more details.
+  Currently, VITAL checks are only partially implemented.
+  See section :ref:`VHDL_restrictions_for_VITAL` for more details.
 
 .. option:: --PREFIX=<PATH>
 
@@ -461,37 +492,38 @@ Options
 
 .. option:: -o=<FNAME>
 
-  All the commands that perform a link (:option:`-e`, :option:`--elab-run`, :option:`--link`, :option:`-c`, :option:`-m`,
-  etc.) support overriding the location and name of the generated artifact.
+  All the commands that perform a link (:option:`-e`, :option:`--elab-run`, :option:`--link`, :option:`-c`,
+  :option:`-m`, etc.) support overriding the location and name of the generated artifact.
 
 .. option:: --time-resolution=<UNIT>
 
   .. ATTENTION::
-    This feature is supported with *mcode* backend only. It is not possible to support it with either LLVM or GCC backends,
-    because it needs to apply globally.
+    This feature is supported with *mcode* backend only.
+    It is not possible to support it with either LLVM or GCC backends, because it needs to apply globally.
 
-  Set the base time resolution of the simulation. This option is supported in commands :option:`-a` and :option:`-r` only.
-  Allowed values are ``auto`` (default), ``fs``, ``ps``, ``ns``, ``us``, ``ms`` or ``sec``. With LLVM/GCC, the value is fixed
-  to ``fs``.
+  Set the base time resolution of the simulation.
+  This option is supported in commands :option:`-a` and :option:`-r` only.
+  Allowed values are ``auto`` (default), ``fs``, ``ps``, ``ns``, ``us``, ``ms`` or ``sec``.
+  With LLVM/GCC, the value is fixed to ``fs``.
 
   .. HINT::
-    When overriding the time resolution, all the time units that are used in the design must be larger. Using units below
-    the resolution will produce a failure.
+    When overriding the time resolution, all the time units that are used in the design must be larger.
+    Using units below the resolution will produce a failure.
 
 
 Warnings
 ========
 
-Some constructions are not erroneous but dubious. Warnings are diagnostic messages that report such constructions. Some
-warnings are reported only during analysis, others during elaboration.
+Some constructions are not erroneous but dubious.
+Warnings are diagnostic messages that report such constructions.
+Some warnings are reported only during analysis, others during elaboration.
 
 .. HINT::
   You could disable a warning by using the ``--warn-no-XXX`` or ``-Wno-XXX`` instead of ``--warn-XXX`` or ``-WXXX``.
 
 .. HINT::
-  The warnings ``-Wbinding``, ``-Wlibrary``, ``-Wshared``,
-  ``-Wpure``, ``-Wspecs``, ``-Whide``, ``-Wport`` are enabled by
-  default.
+  The warnings ``-Wbinding``, ``-Wlibrary``, ``-Wshared``, ``-Wpure``, ``-Wspecs``, ``-Whide``, ``-Wport`` are enabled
+  by default.
 
 .. option:: --warn-library
 
@@ -499,19 +531,20 @@ warnings are reported only during analysis, others during elaboration.
 
 .. option:: --warn-default-binding
 
-  During analyze, warns if a component instantiation has neither configuration specification nor default binding. This may
-  be useful if you want to detect during analyze possibly unbound components if you don't use configuration. See section
-  :ref:`VHDL_standards` for more details about default binding rules.
+  During analyze, warns if a component instantiation has neither configuration specification nor default binding.
+  This may be useful if you want to detect during analyze possibly unbound components if you don't use configuration.
+  See section :ref:`VHDL_standards` for more details about default binding rules.
 
 .. option:: --warn-binding
 
-  During elaboration, warns if a component instantiation is not bound (and not explicitly left unbound). Also warns if a
-  port of an entity is not bound in a configuration specification or in a component configuration. This warning is enabled
-  by default, since default binding rules are somewhat complex and an unbound component is most often unexpected.
+  During elaboration, warns if a component instantiation is not bound (and not explicitly left unbound).
+  Also warns if a port of an entity is not bound in a configuration specification or in a component configuration.
+  This warning is enabled by default, since default binding rules are somewhat complex and an unbound component is most
+  often unexpected.
 
-  However, warnings are still emitted if a component instantiation is inside a generate statement. As a consequence, if you
-  use the conditional generate statement to select a component according to the implementation, you will certainly get
-  warnings.
+  However, warnings are still emitted if a component instantiation is inside a generate statement.
+  As a consequence, if you use the conditional generate statement to select a component according to the implementation,
+  you will certainly get warnings.
 
 .. option:: --warn-reserved
 
@@ -532,11 +565,12 @@ warnings are reported only during analysis, others during elaboration.
 
 .. option:: --warn-delayed-checks
 
-  Warns for checks that cannot be done during analysis time and are postponed to elaboration time. This is because not all
-  procedure bodies are available during analysis (either because a package body has not yet been analysed or because `GHDL`
-  doesn't read not required package bodies).
+  Warns for checks that cannot be done during analysis time and are postponed to elaboration time.
+  This is because not all procedure bodies are available during analysis (either because a package body has not yet been
+  analysed or because `GHDL` doesn't read not required package bodies).
 
-  These are checks for no wait statements in a procedure called in a sensitized process and checks for pure rules of a function.
+  These are checks for no wait statements in a procedure called in a sensitized process and checks for pure rules of a
+  function.
 
 .. option:: --warn-body
 
@@ -549,13 +583,11 @@ warnings are reported only during analysis, others during elaboration.
 
 .. option:: --warn-runtime-error
 
-  Emit a warning in case of runtime error that is detected during
-  analysis.
+  Emit a warning in case of runtime error that is detected during analysis.
 
 .. option:: --warn-shared
 
-  Emit a warning when a shared variable is declared and its type it
-  not a protected type.
+  Emit a warning when a shared variable is declared and its type it not a protected type.
 
 .. option:: --warn-hide
 
@@ -567,18 +599,15 @@ warnings are reported only during analysis, others during elaboration.
 
 .. option:: --warn-others
 
-  Emit a warning is an `others` choice is not required because all the
-  choices have been explicitly covered.
+  Emit a warning is an `others` choice is not required because all the choices have been explicitly covered.
 
 .. option:: --warn-pure
 
-  Emit a warning when a pure rules is violated (like declaring a pure
-  function with access parameters).
+  Emit a warning when a pure rules is violated (like declaring a pure function with access parameters).
 
 .. option:: --warn-static
 
-  Emit a warning when a non-static expression is used at a place where
-  the standard requires a static expression.
+  Emit a warning when a non-static expression is used at a place where the standard requires a static expression.
 
 .. option:: --warn-error
 
@@ -596,14 +625,13 @@ Diagnostics Control
 .. option:: -fdiagnostics-show-option
 .. option:: -fno-diagnostics-show-option
 
-  Control whether the warning option is displayed at the end of warning messages, so that the user can easily know how to
-  disable it.
+  Control whether the warning option is displayed at the end of warning messages, so that the user can easily know how
+  to disable it.
 
 .. option:: -fcaret-diagnostics
 .. option:: -fno-caret-diagnostics
 
-  Control whether the source line of the error is displayed with a
-  caret indicating the column of the error.
+  Control whether the source line of the error is displayed with a caret indicating the column of the error.
 
 
 Library commands
@@ -612,11 +640,13 @@ Library commands
 .. _Create_a_Library:
 .. index:: create your own library
 
-A new library is created implicitly, by compiling entities (packages etc.) into it: ``ghdl -a --work=my_custom_lib my_file.vhdl``.
+A new library is created implicitly, by compiling entities (packages etc.) into it:
+``ghdl -a --work=my_custom_lib my_file.vhdl``.
 
-A library's source code is usually stored and compiled into its own directory, that you specify with the :option:`--workdir`
-option: ``ghdl -a --work=my_custom_lib --workdir=my_custom_libdir my_custom_lib_srcdir/my_file.vhdl``. See also the
-:option:`-P <-P>` command line option.
+A library's source code is usually stored and compiled into its own directory, that you specify with the
+:option:`--workdir` option:
+``ghdl -a --work=my_custom_lib --workdir=my_custom_libdir my_custom_lib_srcdir/my_file.vhdl``.
+See also the :option:`-P <-P>` command line option.
 
 Furthermore, GHDL provides a few commands which act on a library:
 
@@ -625,8 +655,8 @@ Furthermore, GHDL provides a few commands which act on a library:
 
 .. option:: --dir <[options] [libs]>
 
-Displays the content of the design libraries (by default the ``work`` library). All options are allowed, but only a few are
-meaningful: :option:`--work`, :option:`--workdir` and :option:`--std`.
+Displays the content of the design libraries (by default the ``work`` library).
+All options are allowed, but only a few are meaningful: :option:`--work`, :option:`--workdir` and :option:`--std`.
 
 
 .. index:: cmd library clean
@@ -635,7 +665,9 @@ meaningful: :option:`--work`, :option:`--workdir` and :option:`--std`.
 
 .. option:: --clean <[options]>
 
-Try to remove any object, executable or temporary file it could have created. Source files are not removed. The library is kept.
+Try to remove any object, executable or temporary file it could have created.
+Source files are not removed.
+The library is kept.
 
 
 .. index:: cmd library remove
@@ -644,15 +676,16 @@ Try to remove any object, executable or temporary file it could have created. So
 
 .. option:: --remove <[options]>
 
-Acts like the clean command but removes the library too. Note that after removing a design library, the files are not
-known anymore by GHDL.
+Acts like the clean command but removes the library too.
+Note that after removing a design library, the files are not known anymore by GHDL.
 
 
 .. index:: cmd library copy
 
 .. option:: --copy <--work=name [options]>
 
-Make a local copy of an existing library. This is very useful if you want to add units to the ``ieee`` library:
+Make a local copy of an existing library.
+This is very useful if you want to add units to the ``ieee`` library:
 
 .. code-block:: shell
 
@@ -664,10 +697,10 @@ Make a local copy of an existing library. This is very useful if you want to add
 VPI/VHPI build commands
 =======================
 
-These commands simplify the compile and the link of a user VPI or VHPI module. They are all wrappers: the arguments are in fact a
-whole command line that is executed with additional switches. Currently a unix-like compiler (like `cc`, `gcc` or `clang`)
-is expected: the additional switches use their syntax. The only option is `-v` which displays the command before its
-execution.
+These commands simplify the compile and the link of a user VPI or VHPI module.
+They are all wrappers: the arguments are in fact a whole command line that is executed with additional switches.
+Currently a unix-like compiler (like `cc`, `gcc` or `clang`) is expected: the additional switches use their syntax.
+The only option is `-v` which displays the command before its execution.
 
 
 .. index:: cmd VPI compile
@@ -740,15 +773,14 @@ Display the library directory added by the link flags, forcing UNIX syntax.
 IEEE library pitfalls
 =====================
 
-When you use options :option:`--ieee=synopsys <--ieee>`, the ``ieee``
-library contains non standard packages such as
-``std_logic_arith``. These packages are not standard because there are
-not described by an IEEE standard, even if they have been put in the
-`IEEE` library. Furthermore, they are not really de-facto standard,
-because there are slight differences between the packages of Mentor
-and those of Synopsys. Furthermore, since they are not well thought
-out, their use has pitfalls. For example, this description has an
-error during compilation:
+When you use options :option:`--ieee=synopsys <--ieee>`, the ``ieee`` library contains non standard packages such as
+``std_logic_arith``.
+These packages are not standard because there are not described by an IEEE standard, even if they have been put in the
+`IEEE` library.
+Furthermore, they are not really de-facto standard, because there are slight differences between the packages of Mentor
+and those of Synopsys.
+Furthermore, since they are not well thought out, their use has pitfalls.
+For example, this description has an error during compilation:
 
 .. code-block:: VHDL
 
@@ -799,15 +831,17 @@ When you analyze this design, GHDL does not accept it (two long lines have been
       [std_logic_vector, std_logic_vector return boolean]
   ../translate/ghdldrv/ghdl: compilation error
 
-Indeed, the `"="` operator is defined in both packages, and both are visible at the place it is used. The first declaration
-is an implicit one, which occurs when the `std_logic_vector` type is declared and is an element to element comparison. The
-second one is an explicit declared function, with the semantics of an unsigned comparison.
+Indeed, the `"="` operator is defined in both packages, and both are visible at the place it is used.
+The first declaration is an implicit one, which occurs when the `std_logic_vector` type is declared and is an element to
+element comparison.
+The second one is an explicit declared function, with the semantics of an unsigned comparison.
 
-With some analysers, the explicit declaration has priority over the implicit declaration, and this design can be analyzed
-without error. However, this is not the rule given by the VHDL LRM, and since GHDL follows these rules, it emits an error.
+With some analysers, the explicit declaration has priority over the implicit declaration, and this design can be
+analyzed without error.
+However, this is not the rule given by the VHDL LRM, and since GHDL follows these rules, it emits an error.
 
-You can force GHDL to use this rule with the *-fexplicit* option (see :ref:`GHDL:options` for further details). However it
-is easy to fix this error, by using a selected name:
+You can force GHDL to use this rule with the *-fexplicit* option (see :ref:`GHDL:options` for further details).
+However it is easy to fix this error, by using a selected name:
 
 .. code-block:: VHDL
 
@@ -866,5 +900,5 @@ It is better to only use the standard packages defined by IEEE, which provide th
 .. index:: Math_Complex
 
 .. HINT::
-  The ``ieee`` math packages (``math_real`` and ``math_complex``) provided with `GHDL` are fully compliant with the `IEEE`
-  standard.
+  The ``ieee`` math packages (``math_real`` and ``math_complex``) provided with `GHDL` are fully compliant with the
+  `IEEE` standard.
diff --git a/doc/using/Synthesis.rst b/doc/using/Synthesis.rst
index f7dac2abf..fccfad9c6 100644
--- a/doc/using/Synthesis.rst
+++ b/doc/using/Synthesis.rst
@@ -5,7 +5,8 @@ Synthesis
 #########
 
 .. WARNING::
-  This is experimental and work in progress! If you find crashes or unsupported features, please :ref:`report them <reporting_bugs>`!
+  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.
@@ -18,29 +19,27 @@ Hence, the netlists generated by GHDL are not optimised.
 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.
+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.
+Moreover, 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.
+
+Currently, the default output is a generic netlist using a (very simple) subset of VHDL 1993.
+See :option:`--out` and :ghdlsharp:`1174` for on-going discussion about other output formats.
 
-.. option:: --synth <[options] primary_unit [secondary_unit]>
+.. option:: --synth <[options] [library.]top_unit [arch]>
 
-Elaborates for synthesis the design whose top unit is indicated by ``primary_unit [secondary_unit]``.
+Elaborates for synthesis the design whose top unit is indicated by ``[library.]top_unit [arch]``.
 
 .. 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]>
+.. option:: --synth <[options] files... -e top_unit [arch]>
 
 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 default output is a generic netlist using a (very simple) subset of VHDL 1993.
-See :option:`--out` and :ghdlsharp:`1174` for on-going discussion about other output formats.
+Elaboration starts from the top unit indicated by ``top_unit [arch]``.
 
 .. TIP::
   Files can be provided in any order.
@@ -61,30 +60,34 @@ Synthesis options
   * ``-- synthesis translate_on``
   * ``-- synopsys synthesis_off``
 
-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`). In addition to those options, there are some synthesis specific options.
+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`).
+In addition to those options, there are some synthesis specific options.
 
 .. TIP::
-  Furthermore there are lot of debug options available. Beware: these debug options should only used
-  for debugging purposes as they aren't guaranteed to be stable during development of GHDL's synthesis feature.
+  Furthermore there are lot of debug options available.
+  Beware: these debug options should only used for debugging purposes as they aren't guaranteed to be stable during
+  development of GHDL's synthesis feature.
   You can find them in the file :ghdlsrc:`ghdlsynth.adb <ghdldrv/ghdlsynth.adb>` in the procedure ``Decode_Option()``.
 
 .. option:: -gNAME=VALUE
 
-  Override top unit generic `NAME` with value `VALUE`. Similar to the run-time option :option:`-gGENERIC`.
+  Override top unit generic `NAME` with value `VALUE`.
+  Similar to the run-time option :option:`-gGENERIC`.
 
   Example::
 
-    $ ghdl --synth --std=08 -gDEPTH=12 my_unit
+    $ ghdl --synth --std=08 -gDEPTH=12 [library.]top_unit [arch]
 
 .. option:: --out=<vhdl|raw-vhdl|dot|none|raw|dump>
 
   * **vhdl** *(default)*: equivalent to ``raw-vhdl``, but the original top-level unit is preserved unmodified, so the
     synthesized design can be simulated with the same testbench.
 
-  * **raw-vhdl**: all statements are converted to a simple VHDL 1993 netlist, for allowing instantiation in other synthesis
-    tools without modern VHDL support.
+  * **raw-vhdl**: all statements are converted to a simple VHDL 1993 netlist, for allowing instantiation in other
+    synthesis tools without modern VHDL support.
 
   * **dot**: generate a graphviz dot diagram of the netlist AST.
 
@@ -100,7 +103,7 @@ simulation back-ends. Hence, available options for synthesis are the same as for
 
   Example::
 
-    $ ghdl --synth --std=08 --vendor-library=vendorlib my_unit
+    $ ghdl --synth --std=08 --vendor-library=vendorlib [library.]top_unit [arch]
 
 Assertions, PSL and formal verification
 =======================================
@@ -111,7 +114,7 @@ Assertions, PSL and formal verification
 
   Example::
 
-    $ ghdl --synth --std=08 --no-formal my_unit
+    $ ghdl --synth --std=08 --no-formal [library.]top_unit [arch]
 
 .. option:: --no-assert-cover
 
@@ -120,7 +123,7 @@ Assertions, PSL and formal verification
 
   Example::
 
-    $ ghdl --synth --std=08 --no-assert-cover my_unit
+    $ ghdl --synth --std=08 --no-assert-cover [library.]top_unit [arch]
 
 .. option:: --assert-assumes
 
@@ -130,7 +133,7 @@ Assertions, PSL and formal verification
 
   Example::
 
-    $ ghdl --synth --std=08 --assert-assumes my_unit
+    $ ghdl --synth --std=08 --assert-assumes [library.]top_unit [arch]
 
   As all PSL asserts are treated like PSL assumes, no `cover` directives are automatically generated for them,
   regardless of using the :option:`--no-assert-cover` or not.
@@ -144,7 +147,7 @@ Assertions, PSL and formal verification
 
   Example::
 
-    $ ghdl --synth --std=08 --assume-asserts my_unit
+    $ ghdl --synth --std=08 --assume-asserts [library.]top_unit [arch]
 
   `cover` directives are automatically generated for the resulting asserts (with an implication operator)
   if :option:`--no-assert-cover` isn't used.
@@ -183,35 +186,35 @@ To Verilog
 
 .. code-block:: shell
 
-    yosys -m ghdl -p 'ghdl filename.vhdl -e unit_name; write_verilog filename.v'
+    yosys -m ghdl -p 'ghdl filename.vhdl -e top_unit [arch]; write_verilog filename.v'
 
 To EDIF
 -------
 
 .. code-block:: shell
 
-    yosys -m ghdl -p 'ghdl filename.vhdl -e unit_name; write_edif filename.edif'
+    yosys -m ghdl -p 'ghdl filename.vhdl -e top_unit [arch]; write_edif filename.edif'
 
 To SMT
 ------
 
 .. code-block:: shell
 
-    yosys -m ghdl -p 'ghdl filename.vhdl -e unit_name; write_smt2 filename.smt2'
+    yosys -m ghdl -p 'ghdl filename.vhdl -e top_unit [arch]; write_smt2 filename.smt2'
 
 To BTOR2
 --------
 
 .. code-block:: shell
 
-    yosys -m ghdl -p 'ghdl filename.vhdl -e unit_name; write_btor filename.btor'
+    yosys -m ghdl -p 'ghdl filename.vhdl -e top_unit [arch]; write_btor filename.btor'
 
 To FIRRTL
 ---------
 
 .. code-block:: shell
 
-    yosys -m ghdl -p 'ghdl filename.vhdl -e unit_name; write_firrtl filename.firrtl'
+    yosys -m ghdl -p 'ghdl filename.vhdl -e top_unit [arch]; write_firrtl filename.firrtl'
 
 To VHDL
 -------