Describe commands as options. Fix internal refs to options. Apply

suggestions about ch 2. Add options given by the executable but not
documented earlier.

8 files changed, 310 insertions, 363 deletions

diff --git a/doc/changelog/Meta.rst b/doc/changelog/Meta.rst
index 4b86d7d32..b14927205 100644
--- a/doc/changelog/Meta.rst
+++ b/doc/changelog/Meta.rst
@@ -5,7 +5,7 @@ Meta
 
 * Python snippet for Sphinx's `conf.py` to extract the current version number from Git (latest tag name). 
 
-	* :ghdlsharp:`200`
+	* :ghdlsharp:`200`, :ghdlsharp:`221`
 
 * Reference :samp:`genindex.html` from the navigation bar.
 
@@ -15,4 +15,17 @@ Meta
 
 	* :ghdlsharp:`200`
 	
+* Intersphinx files
+
+	* :ghdlsharp:`200`
+	* To decompress the inventory file: `curl -s http://ghdl.readthedocs.io/en/latest/objects.inv | tail -n+5 | openssl zlib -d`. From `how-to-uncompress-zlib-data-in-unix <http://unix.stackexchange.com/questions/22834/how-to-uncompress-zlib-data-in-unix>`_.
+	* External ref and link to section::
+	
+		:ref:`GHDL Roadmap <ghdl:CHANGE:Roadmap>`
+		
+	* External ref to option (no link)::
+	
+		:ghdl:option:`--ieee`
+		:option:`ghdl:--ieee`
+	
 * Ubuntu uses `dash` instead of `bash` when a shell script is run. As a result, some functionalities, such as arrays like :samp:`array[1]`, are not supported. Therefore, build scripts in `dist/linux` should not use those functionalities unless they are sourced in a `bash` shell. That is, :file:`tavis-ci.sh` uses arrays, since it is sourced in the Travis CI machine. But :file:`docker-buildtest.sh` and :file:`buildtest.sh` do not use any. The same applies to the scripts in `testsuite`.
\ No newline at end of file
diff --git a/doc/changelog/Roadmap.rst b/doc/changelog/Roadmap.rst
index 5dfba58b1..93589170e 100644
--- a/doc/changelog/Roadmap.rst
+++ b/doc/changelog/Roadmap.rst
@@ -22,27 +22,11 @@ TODOs
 
 Options shown in the command line help, but not found in the doc:
 
-* :samp:`--expect-failure      invert exit status`
-* :samp:`--has-feature=X       test presence of feature X`
-* :samp:`--list-features       display the list of features`
-* :samp:`--vpi=FILENAME        load VPI module`
-* :samp:`--vpi-trace[=FILE]    trace vpi calls to FILE`
-* :samp:`--dump-rti            dump Run Time Information`
-* :samp:`--trace-signals       disp signals after each cycle`
-* :samp:`--trace-processes     disp process name before each cycle`
-* :samp:`--stats               display run-time statistics`
-* :samp:`--disp-order          disp signals order`
-* :samp:`--disp-sources        disp sources while displaying signals`
-* :samp:`--disp-sig-types      disp signal types`
-* :samp:`--disp-signals-map    disp map bw declared sigs and internal sigs`
-* :samp:`--disp-signals-table  disp internal signals`
-* :samp:`--checks              do internal checks after each process run`
-* :samp:`--activity=LEVEL      watch activity of LEVEL signals: LEVEL is all, min (default) or none (unsafe)`
-* :samp:`-C  --mb-comments     allow multi-bytes chars in a comment`
-
-	* https://github.com/tgingold/ghdl/issues/132
-	
-* :samp:`--bootstrap           allow --work=std`
 * :samp:`--syn-binding         use synthesis default binding rule`
 
+* VPI Commands
+
+	* :samp:`--vpi=FILENAME        load VPI module`
+	* :samp:`--vpi-trace[=FILE]    trace vpi calls to FILE`
+	
 .. todolist::
\ No newline at end of file
diff --git a/doc/conf.py b/doc/conf.py
index 516275077..a4eee999f 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -348,7 +348,8 @@ texinfo_documents = [
 # Sphinx.Ext.InterSphinx
 # ==============================================================================
 intersphinx_mapping = {
-	'python': ('https://docs.python.org/3.5/', None)
+	'python': ('https://docs.python.org/3.5/', None),
+	'poc': ('http://poc-library.readthedocs.io/en/release', None),
 #	'ghdl':   ('http://ghdl.readthedocs.io/en/latest', None)
 }
 
diff --git a/doc/getting/Building.rst b/doc/getting/Building.rst
index 64e72bccb..9df115f3c 100644
--- a/doc/getting/Building.rst
+++ b/doc/getting/Building.rst
@@ -31,6 +31,11 @@ After making your choice, you can jump to the corresponding section below. Howev
   - @1138 Backtraces optional -patchable-
   - Very briefly, why is mcode faster for analysis and GCC/LLVM for simulation?
   - The only other dependency is zlib (On ubuntu/debian, install zlib1g-dev).
+  - From :ghdlsharp:`279`:
+	- GCC: GHDL generates an intermediate representation for GCC, which creates an executable. So GHDL acts a a new language frontend like C for the GCC and uses the existing backend to generated e.g. x86(-64) binary code.
+	- LLVM: GHDL generates instructions for the LLVM abstract register machine, which then generates x86(-64) instructions for the host system.
+	- mcode: GHDL generates the x86(-64) instructions in memory and executes the model.
+    - gcc is currently only supported on Linux, because you need to compile a complete GCC from zero and add GHDL as a frontend into the GCC. Compiling the complete GCC suite plus GHDL takes a lot of time. I think it's not possible to finish the compile task in the bounds of a Travis-CI run.
   
 .. _BUILD:dir_structure:
   
@@ -53,7 +58,7 @@ Directory structure
 	
 		* :samp:`mcode`:
 		
-		* :samp:`appveyor`:
+		* :samp:`appveyor`: 
 		
 * :samp:`doc`: `Markdown` and `reStructuredText` sources and auxiliar files to build the documentation with `Sphinx <http://www.sphinx-doc.org>`_. Indeed, `Read the docs <http://readthedocs.org>`_ (RTD) is used to automatically build and deploy this site and/or PDF you are reading.
 
@@ -71,8 +76,10 @@ Directory structure
 
 	- [@1138-4EB|@Paebbels] Replace link to VendorPrimitives, when the file is translated from md to rst.
 	
-	- [@Paebbels] Add brief description of how the content in dist/windows is ordered.
-  
+	- [@Paebbels] Add brief description of how the content in dist/windows is ordered. From :ghdlsharp:`279`:
+		- The content in dist/appveyor is for the AppVeyor flow. AppVeyor is a continuous integration service like Travis-CI, but is offers a Windows Server 2012 R2 machine. The AppVeyor flow has more scripts than the Travis-CI flow, so we put them into a separate directory.
+		- The code in dist/windows/mcode is special code needed to build mcode in windows. mcode is supported on Linux (32/64-bit) and Windows (32-bit).
+
 Mcode backend
 =================
 
@@ -196,4 +203,7 @@ Test suites
 
 .. TODO::
 
-  @1138 explain that there are two (maybe three with vhdl08 tests)
\ No newline at end of file
+	* @1138 explain that there are two (maybe three with vhdl08 tests)
+  	* :samp:`--expect-failure      invert exit status`
+	* :samp:`--has-feature=X       test presence of feature X`
+	* :samp:`--list-features       display the list of features`
\ No newline at end of file
diff --git a/doc/references/CommandReference.rst b/doc/references/CommandReference.rst
index 771d2386e..4adb2dd36 100644
--- a/doc/references/CommandReference.rst
+++ b/doc/references/CommandReference.rst
@@ -1,3 +1,4 @@
+.. program:: ghdl
 .. _REF:Command:
 
 Command Reference
@@ -5,19 +6,24 @@ Command Reference
 
 .. HINT:: The most common commands and options are shown in section :ref:`USING:Invoking`. Here the advanced and experimental features are described.
 
+Environment variables
+=============
+
+.. envvar:: GHDL_PREFIX
+
+	.. TODO:: Add short description to :option:`GHDL_PREFIX`
+
 Misc commands
 =============
 
 There are a few GHDL commands which are seldom useful.
 
-.. _Help_command:
+.. index:: cmd help
 
 Help [:samp:`-h`]
 ------------
 
-.. index:: -h command
-
-.. index:: --help command
+.. 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
@@ -27,57 +33,46 @@ for this later command are displayed::
   ghdl -h
   ghdl -h command
 
-
-.. _Disp_config_command:
-
+.. index:: cmd display configuration
+  
 Display config [:samp:`--disp-config`]
 -------------------
 
-.. index:: --disp-config command
-
-.. index:: display configuration
-
-:samp:`ghdl --disp-config [options]`
+.. option:: --disp-config <[options]>
 
 Display the program paths and options used by GHDL. This may be useful to track installation errors.
 
+.. index:: cmd display standard
+.. index:: display :samp:`std.standard`
+
 Display standard [:samp:`--disp-standard`]
 ---------------------
 
-.. index:: --disp-standard command
-
-.. index:: display :samp:`std.standard`
-
-:samp:`ghdl --disp-standard [options]`
+.. option:: --disp-standard <[options]>
 
 Display the :samp:`std.standard` package.
 
+.. index:: cmd version
+
 Version [:samp:`--version`]
 ---------------
 
-.. index:: --version command
-
-.. index:: version
+.. option:: --version, -v
 
-:samp:`ghdl --version`
-
-Display the `GHDL` version and exit.
+Display the GHDL version and exit.
 
 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.
 
+.. index:: cmd file pretty printing
+.. index:: vhdl to html
+
 Pretty print [:samp:`--pp-html`]
 --------------------
 
-.. index:: --pp-html command
-
-.. index:: pretty printing
-
-.. index:: vhdl to html
-
-:samp:`ghdl --pp-html [options] file...`
+.. 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.
 
@@ -86,21 +81,21 @@ The style of the html file can be modified with the :option:`--format=` option:
 * By default or when the :option:`--format=html2` option is specified, the output is an HTML 2.0 file, with colours set through `<FONT>` tags.
 * When the :option:`--format=css` option is specified, the output is an HTML 4.0 file, with colours set through a CSS file, whose name is :file:`ghdl.css`. See :ref:`Cross-reference_command`, for more details about this CSS file.
 
+.. index:: cmd file find
+
 Find [:samp:`-f`]
 ------------
 
-.. index:: -f command
-
-:samp:`ghdl -f file...`
+.. option:: -f <file...>
 
 The files are scanned, parsed and the names of design units are displayed. Design units marked with two stars are candidate to be at the apex of a design hierarchy.
 
+.. index:: cmd file chop
+
 Chop [:samp:`--chop`]
 ------------
 
-.. index:: --chop command
-
-:samp:`ghdl --chop files`
+.. option:: --chop <files...>
 
 The provided files are read, and a file is written in the current directory for every design unit. Each filename is build according to the type:
 
@@ -114,87 +109,73 @@ Comments between design units are stored into the most adequate files.
 
 This command may be useful to split big files, if your computer has not enough memory to compile such files. The size of the executable is reduced too.
 
+.. index:: cmd file lines
+
 Lines [:samp:`--lines`]
 -------------
 
-.. index:: --lines command
-
-:samp:`ghdl --lines files`
+.. option:: --lines <files...>
 
 Display on the standard output lines of files preceded by line number.
 
 GCC/LLVM only commands
 =================
 
-.. _Bind_command:
+.. index:: cmd GCC/LLVM binding
 
 Bind [:samp:`--bind`]
 ------------
 
-.. index:: binding
-
-.. index:: --bind command
-
-:samp:`ghdl --bind [options] primary_unit [secondary_unit]`
+.. option:: --bind <[options] primary_unit [secondary_unit]>
 
 Performs only the first stage of the elaboration command; the list of objects files is created but the executable is not built.  This command should be used only when the main entry point is not GHDL.
 
-.. _Link_command:
+.. index:: cmd GCC/LLVM linking
 
 Link [:samp:`--link`]
 ------------
 
-.. index:: linking
-
-.. index:: --link command
-
-:samp:`ghdl --link [options] primary_unit [secondary_unit]`
+.. option:: --link <[options] primary_unit [secondary_unit]>
   
 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.
 
-.. _List_link_command:
+.. index:: cmd GCC/LLVM list link
 
 List link [:samp:`--list-link`]
 -----------------
 
-.. index:: --list-link command
-
-:samp:`ghdl --list-link primary_unit [secondary_unit]`
+.. option:: --list-link <primary_unit [secondary_unit]>
 
 This command may be used only after a bind command. GHDL displays all the files which will be linked to create an executable. This command is intended to add object files in a link of a foreign program.
 
-GHDL options
+Options
 =================
 
+.. option:: --mb-comments, -C
+
+Allow multi-bytes chars in a comment
+
 .. 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 synthesizer rule.
+This rule is known as synthesizer rule.
 
-  There are two key points: normal VHDL LRM rules are tried first and
-  entities are searched only in known library.  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 library.  A known library is a library which has been named in your design.
 
-  This option is only useful during elaboration.
+This option is only useful during elaboration.
 
-.. option:: --GHDL1=<COMMAND>
+.. option:: --GHDL1<=COMMAND>
 
-  Use :samp:`COMMAND` as the command name for the compiler.  If :samp:`COMMAND` is
-  not a path, then it is searched in the path.
+Use :samp:`COMMAND` as the command name for the compiler.  If :samp:`COMMAND` is not a path, then it is searched in the path.
 
-.. option:: --AS=<COMMAND>
+.. option:: --AS<=COMMAND>
 
-  Use :samp:`COMMAND` as the command name for the assembler.  If :samp:`COMMAND` is
-  not a path, then it is searched in the path.  The default is :samp:`as`.
+Use :samp:`COMMAND` as the command name for the assembler.  If :samp:`COMMAND` is not a path, then it is searched in the path.  The default is :samp:`as`.
 
-.. option:: --LINK=<COMMAND>
+.. option:: --LINK<=COMMAND>
 
-  Use :samp:`COMMAND` as the linker driver.  If :samp:`COMMAND` is
-  not a path, then it is searched in the path.  The default is :samp:`gcc`.
+Use :samp:`COMMAND` as the linker driver.  If :samp:`COMMAND` is not a path, then it is searched in the path.  The default is :samp:`gcc`.
   
 Passing options to other programs
 =================================
@@ -207,12 +188,12 @@ Both the compiler and the linker are in fact GCC programs. See the GCC manual fo
 
 .. option:: -Wc,<OPTION>
 
-  Pass `OPTION` as an option to the compiler.
+Pass `OPTION` as an option to the compiler.
 
 .. option:: -Wa,<OPTION>
 
-  Pass `OPTION` as an option to the assembler.
+Pass `OPTION` as an option to the assembler.
 
 .. option:: -Wl,<OPTION>
 
-  Pass `OPTION` as an option to the linker.
+Pass `OPTION` as an option to the linker.
diff --git a/doc/using/InvokingGHDL.rst b/doc/using/InvokingGHDL.rst
index 73c821b92..bf7619b7b 100644
--- a/doc/using/InvokingGHDL.rst
+++ b/doc/using/InvokingGHDL.rst
@@ -1,5 +1,5 @@
-.. _USING:Invoking:
 .. program:: ghdl
+.. _USING:Invoking:
 
 *************
 Invoking GHDL
@@ -14,42 +14,36 @@ The form of the :program:`ghdl` command is :samp:`ghdl command [options...]`. Th
 
 .. HINT:: Only the most common commands and options are shown here. For most advanced and experimental features see section :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 priority order):
+.. WARNING:: During analysis and elaboration GHDL may read the :samp:`std` and :samp:`ieee` files. The location of these files is based on the prefix, which is (in priority order):
 
-	* the :option:`--PREFIX=` command line option
+	* the :option:`--PREFIX` command line option
 	* the :envvar:`GHDL_PREFIX` environment variable
-	* a built-in default path. It is a hard-coded path on GNU/Linux and the value of the :samp:`HKLM\Software\Ghdl\Install_Dir` registry entry on Windows.
+	* a built-in default path. It is a hard-coded path on GNU/Linux, and it corresponds to the value of the :samp:`HKLM\Software\Ghdl\Install_Dir` registry entry on Windows.
 
-	You should use the :option:`--disp-config` command (:ref:`--disp-config <Disp_config_command>` for details) to disp and debug installation problems.
+	You should use the :option:`--disp-config` command to display and debug installation problems.
 
 Design building commands
 =================
 
 The mostly used commands of GHDL are those to analyze and elaborate a design.
 
+.. index:: cmd analysis
+
 Analysis [:samp:`-a`]
 ----------------
 
-.. index:: analysis
-
-.. index:: -a command
-
-:samp:`ghdl -a [options...] file...`
+.. 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).
 
 See :ref:`GHDL_options`, for details on the GHDL options. For example, to produce debugging information such as line numbers, use: :samp:`ghdl -a -g my_design.vhdl`.
 
-.. _Elaboration_command:
+.. index:: cmd elaboration
 
 Elaboration [:samp:`-e`]
 -------------------
 
-.. index:: elaboration
-
-.. index:: -e command
-
-:samp:`ghdl -e [options..] primary_unit [secondary_unit]`
+.. option:: -e <[options...] primary_unit [secondary_unit]>
 
 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 objects files required for the executable. Then, it links all these files with the runtime library. The actual elaboration is performed at runtime.
 
@@ -59,22 +53,18 @@ Re-analyzes all the configurations, entities, architectures and package declarat
 	* an entity unit
 	* an entity unit followed by a 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` option, as described in :ref:`GHDL_options`. See :ref:`Top_entity`, for the restrictions on the root design of a hierarchy.
+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` option, as described in :ref:`GHDL_options`. See section ':ref:`Top_entity`', for the restrictions on the root design of a hierarchy.
 		
 * 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 later case, the concatenation of the name of the primary unit, a dash, and the name of the secondary unit (or architecture). Option :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 con be skipped.
 
-.. _Run_command:
-
+.. index:: cmd run
+ 
 Run [:samp:`-r`]
 -----------
 
-.. index:: run
-
-.. index:: -r command
-
-:samp:`ghdl -r [options...] primary_unit [secondary_unit] [simulation_options...]`.
+.. option:: -r <[options...] primary_unit [secondary_unit] [simulation_options...]>
 
 Runs/simulates a design. The options and arguments are the same as for the :ref:`elaboration command <Elaboration_command>`.
 
@@ -87,45 +77,34 @@ This command exists for three reasons:
 * It is coherent with the :option:`-a` and :option:`-e` commands.
 * It works with mcode implementation, where the executable code is generated in memory.
 
-See :ref:`Simulation_and_runtime`, for details on options.
+See section ':ref:`USING:Simulation`', for details on options.
+
+.. index:: cmd elaborate and run
 
 Elaborate and run [:samp:`--elab-run`]
 -------------------------
 
-.. index:: elaborate and run
-
-.. index:: --elab-run command
-
-:samp:`ghdl --elab-run [elab_options...] primary_unit [secondary_unit] [run_options...]`
+.. option:: --elab-run <[elab_options...] primary_unit [secondary_unit] [run_options...]>
 
-Acts like the elaboration command (see :ref:`elaboration command <Elaboration_command>`) followed by the run command (see :ref:`run command <Run_command>`).
+Acts like the elaboration command (see :option:`-e`) followed by the run command (see :option:`-r`).
 
-.. _Check_syntax_command:
+.. index:: cmd checking syntax
 
 Check syntax [:samp:`-s`]
 --------------------
 
-.. index:: checking syntax
+.. option:: -s <[options] files>
 
-.. index:: -s command
+Analyze files but do not generate code. This command may be used to check the syntax of files. It does not update the library.
 
-:samp:`ghdl -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_and_elaborate_command:
+.. index:: cmd analyze and elaborate
 
 Analyze and elaborate [:samp:`-c`]
 -----------------------------
 
-.. index:: Analyze and elaborate command
-
-.. index:: -c command
-
-GCC/LLVM: :samp:`ghdl -c [options] file... -e primary_unit [secondary_unit]`
+.. option:: -c <[options] file... -<e|r> primary_unit [secondary_unit]>
 
-mcode: :samp:`ghdl -c [options] file... -r primary_unit [secondary_unit]`
+.. 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.
 
@@ -145,17 +124,14 @@ The advantages over the traditional approach (analyze and then elaborate) are:
 Design rebuilding commands
 ===================
 
-Analyzing and elaborating a design consisting in several files can be tricky,
-due to dependencies.  GHDL has a few commands to rebuild a design.
+Analyzing and elaborating a design consisting in several files can be tricky, due to dependencies. GHDL has a few commands to rebuild a design.
+
+.. index:: cmd importing files
 
 Import [:samp:`-i`]
 --------------
 
-.. index:: importing files
-
-.. index:: -i command
-
-:samp:`ghdl -i [options] file...`
+.. option:: -i <[options] file...>
 
 All the files specified in the command line are scanned, parsed and added in the libraries but as not yet analyzed. No object files are created. It's 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.
 
@@ -165,22 +141,18 @@ All the files specified in the command line are scanned, parsed and added in the
 
 	* Since the files are parsed, there must be correct files. However, since they are not analyzed, many errors are tolerated by this command.
 
-See see :ref:`-m <Make_command>`, to actually build the design.
+See :option:`-m`, to actually build the design.
 
-.. _Make_command:
+.. index:: cmd make
 
 Make [:samp:`-m`]
 ------------
 
-.. index:: make
-
-.. index:: -m command
-
-:samp:`ghdl -m [options] primary [secondary]`
+.. option:: -m <[options] primary [secondary]>
 
 Analyze automatically outdated files and elaborate a design. The primary unit denoted by the :samp:`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 just have edited it), or because a design unit contained in the file depends on a unit which is outdated. This rule is of course recursive.
 
-* With option :option:`-b` (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 :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 :option:`-f` (force), GHDL analyzes all the units of the work library needed to create the design hierarchy. Not 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).
 
@@ -190,68 +162,50 @@ The purpose of this command is to be able to compile a design without prior know
 
 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.
 
+.. index:: cmd generate makefile
+
 Generate Makefile [:samp:`--gen-makefile`]
 -------------------------
 
-.. index:: --gen-makefile command
+.. option:: --gen-makefile <[options] primary [secondary]>
 
-:samp:`ghdl --gen-makefile [options] primary [secondary]`
-
-This command works like the make command (see :ref:`-m <Make_command>`), but only a makefile is generated on the standard output.
-
-.. _GHDL_Options:
+This command works like the make command (see :option:`-m`), but only a makefile is generated on the standard output.
 
 Options
 ============
 
 .. index:: IEEE 1164
-
 .. index:: 1164
-
 .. index:: IEEE 1076.3
-
 .. index:: 1076.3
 
 .. HINT:: Besides the options described below, `GHDL` passes any debugging options (those that begin with :option:`-g`) and optimizations options (those that begin with :option:`-O` or :option:`-f`) to `GCC`.  Refer to the `GCC` manual for details.
 
 .. index:: WORK library
 
-.. option:: --work=<NAME>
+.. option:: --work<=NAME>
 
-  Specify the name of the :samp:`WORK` library.  Analyzed units are always
-  placed in the library logically named :samp:`WORK`.  With this option,
-  you can set its name.  By default, the name is :samp:`work`.
+  Specify the name of the :samp:`WORK` library.  Analyzed units are always placed in the library logically named :samp:`WORK`.  With this option, you can set its name.  By default, the name is :samp:`work`.
 
-  `GHDL` checks whether :samp:`WORK` is a valid identifier.  Although being
-  more or less supported, the :samp:`WORK` identifier should not be an
-  extended identifier, since the filesystem may prevent it from correctly
-  working (due to case sensitivity or forbidden characters in filenames).
+  `GHDL` checks whether :samp:`WORK` is a valid identifier. Although being more or less supported, the :samp:`WORK` identifier should not be an extended identifier, since the filesystem may prevent it from correctly working (due to case sensitivity or forbidden characters in filenames).
 
-  `VHDL` rules forbid you to add units to the :samp:`std` library.
-  Furthermore, you should not put units in the :samp:`ieee` library.
+  `VHDL` rules forbid you to add units to the :samp:`std` library. Furthermore, you should not put units in the :samp:`ieee` library.
 
-.. option:: --workdir=<DIR>
+.. option:: --workdir<=DIR>
 
-  Specify the directory where the :samp:`WORK` library is located.  When this
-  option is not present, the :samp:`WORK` library is in the current
-  directory.  The object files created by the compiler are always placed
-  in the same directory as the :samp:`WORK` library.
+  Specify the directory where the :samp:`WORK` library is located. When this option is not present, the :samp:`WORK` library is in the current directory.  The object files created by the compiler are always placed in the same directory as the :samp:`WORK` library.
 
-  Use option :option:`-P` to specify where libraries other than :samp:`WORK`
-  are placed.
+  Use option :option:`-P` to specify where libraries other than :samp:`WORK` are placed.
 
-.. option:: --std=<STD>
+.. option:: --std<=STD>
 
-  Specify the standard to use.  By default, the standard is :samp:`93c`, which
-  means VHDL-93 accepting VHDL-87 syntax.  For details on :samp:`STD` values see
-  :ref:`VHDL_standards`.
+  Specify the standard to use.  By default, the standard is :samp:`93c`, which means VHDL-93 accepting VHDL-87 syntax.  For details on :samp:`STD` values see section ':ref:`VHDL_standards`'.
 
-.. option:: --ieee=<VER>
+.. option:: --ieee<=VER>
 
   .. index:: ieee library
   .. index:: synopsys library
@@ -271,7 +225,7 @@ Options
     packages , :samp:`numeric_bit` and :samp:`numeric_std` defined by IEEE
     1076.3, and the :samp:`vital` packages :samp:`vital_timing` and
     :samp:`vital_primitives`, defined by IEEE 1076.4.  The version of these
-    packages is defined by the VHDL standard used.  See :ref:`VITAL_packages`,
+    packages is defined by the VHDL standard used.  See section ':ref:`VITAL_packages`',
     for more details.
 
   synopsys
@@ -299,22 +253,20 @@ Options
   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:`--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 :samp:`std_logic_arith`
-  package.  See :ref:`IEEE_library_pitfalls`, for an example.
+  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 better fix your design and use the :samp:`numeric_std` package.
 
 .. option:: -frelaxed-rules
 
-  Within an object declaration, allow to reference the name (which
-  references the hidden declaration).  This ignores the error in the
-  following code:
+  Within an object declaration, allow to reference the name (which references the hidden declaration).  This ignores the error in the following code:
 
   .. code-block:: VHDL
 
@@ -327,44 +279,32 @@ Options
      constant state1 : state := state1;
     end pkg2;
 
-  Some code (such as Xilinx packages) have such constructs, which
-  are valid.
+  Some code (such as Xilinx packages) have such constructs, which are valid.
 
-  (The scope of the :samp:`state1` constant start at the `constant`
-  word. Because the constant :samp:`state1` and the enumeration literal
-  :samp:`state1` are homograph, the enumeration literal is hidden in the
-  immediate scope of the constant).
+  (The scope of the :samp:`state1` constant start at the `constant` word. Because the constant :samp:`state1` and the enumeration literal :samp:`state1` are homograph, 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 :ref:`PSL_implementation`,
-  for more details.
+  Enable parsing of PSL assertions within comments.  See section ':ref:`PSL_implementation`' for more details.
 
 .. option:: --no-vital-checks
 .. option:: --vital-checks
 
-  Disable or enable checks of restriction on VITAL units.  Checks are enabled
-  by default.
+  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 :samp:`VITAL_Level0` and :samp:`VITAL_Level1`, both
-  declared in the :samp:`ieee.VITAL_Timing` package.
+  Checks are performed only when a design unit is decorated by a VITAL attribute. The VITAL attributes are :samp:`VITAL_Level0` and :samp:`VITAL_Level1`, both declared in the :samp:`ieee.VITAL_Timing` package.
 
-  Currently, VITAL checks are only partially implemented.  See
-  :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>
+.. option:: --PREFIX<=PATH>
 
-  Use :file:`PATH` as the prefix path to find commands and pre-installed (std and
-  ieee) libraries.
+  Use :file:`PATH` as the prefix path to find commands and pre-installed (:samp:`std` and :samp:`ieee`) libraries.
 
 .. option:: -v
 
-  Be verbose.  For example, for analysis, elaboration and make commands, GHDL
-  displays the commands executed.
+  Be verbose. For example, for analysis, elaboration and make commands, GHDL displays the commands executed.
 
 Warnings
 =============
@@ -379,31 +319,18 @@ Some constructions are not erroneous but dubious. Warnings are diagnostic messag
 
 .. 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 component if you don't use
-  configuration.  :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 component 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 even 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 even 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-library
 
   Warns if a design unit replaces another design unit with the same name.
 
-
 .. option:: --warn-vital-generic
 
   Warns if a generic name of a vital entity is not a vital generic name.  This
@@ -411,20 +338,13 @@ Some constructions are not erroneous but dubious. Warnings are diagnostic messag
 
 .. 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 statement in a procedure called in a
-  sensitized process and checks for pure rules of a function.
+  These are checks for no wait statement in a procedure called in a sensitized process and checks for pure rules of a function.
 
 .. option:: --warn-body
 
-  Emit a warning if a package body which is not required is analyzed.  If a
-  package does not declare a subprogram or a deferred constant, the package
-  does not require a body.
+  Emit a warning if a package body which is not required is analyzed.  If a package does not declare a subprogram or a deferred constant, the package does not require a body.
 
 .. option:: --warn-specs
 
@@ -468,62 +388,48 @@ Library commands
 ================
 
 .. _Create_a_Library:
-
 .. index:: create your own library
 
 A new library is created implicitly, by compiling entities (packages etc.) into it: :samp:`ghdl -a --work=my_custom_lib my_file.vhd`.
 
-A library's source code is usually stored and compiled into its own directory, that you specify with the :option:`--workdir` option: :samp:`ghdl -a --work=my_custom_lib --workdir=my_custom_libdir my_custom_lib_srcdir/my_file.vhd`. See also the :option:`-P<DIRECTORY>` 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: :samp:`ghdl -a --work=my_custom_lib --workdir=my_custom_libdir my_custom_lib_srcdir/my_file.vhd`. See also the :option:`-P` command line option.
 
 Furthermore, GHDL provides a few commands which act on a library:
 
+.. index:: cmd library directory
+
 Directory [:samp:`--dir`]
 -----------------
 
-.. index:: displaying library
-
-.. index:: --dir command
-.. option::--dir
+.. option:: --dir <[options] [libs]>
 
-:samp:`ghdl --dir [options] [libs]`
+Displays the content of the design libraries (by default the :samp:`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 :samp:`work` library). All options are allowed, but only a few are meaningful: :option:`--work=NAME`, :option:`--workdir=PATH` and :option:`--std=VER`.
+.. index:: cmd library clean
 
 Clean [:samp:`--clean`]
 -------------
 
-.. index:: cleaning
-
-.. index:: --clean command
-
-:samp:`ghdl --clean [options]`
+.. 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.
 
-.. _Remove_command:
+.. index:: cmd library remove
 
 Remove [:samp:`--remove`]
 --------------
 
-.. index:: cleaning all
-
-.. index:: --remove command
-
-:samp:`ghdl --remove [options]`
+.. option:: --remove <[options]>
 
 Do like the clean command but remove the library too. Note that after removing a design library, the files are not
 known anymore by GHDL.
 
-.. _Copy_command:
+.. index:: cmd library copy
 
 Copy [:samp:`--copy`]
 ------------
 
-.. index:: copying library
-
-.. index:: --copy command
-
-:samp:`ghdl --copy --work=name [options]`
+.. option:: --copy <--work=name [options]>
 
 Make a local copy of an existing library.  This is very useful if you want to add unit to the :samp:`ieee` library:
 
@@ -532,35 +438,18 @@ Make a local copy of an existing library.  This is very useful if you want to ad
   ghdl --copy --work=ieee --ieee=synopsys
   ghdl -a --work=ieee numeric_unsigned.vhd
 
-.. _Cross-reference_command:
-
-Cross-reference [:samp:`--xref-html`]
-=======================
-
-To easily navigate through your sources, you may generate cross-references::
-
-:samp:`ghdl --xref-html [options] file...`
-
-This command generates an html file for each :samp:`file` given in the command line, with syntax highlighting and full cross-reference: every identifier is a link to its declaration. Besides, an index of the files is created too.
-
-The set of :samp:`file` are analyzed, and then, if the analysis is successful, html files are generated in the directory specified by the :option:`-o dir` option, or :file:`html/` directory by default.
-
-* If the option :option:`--format=html2` is specified, then the generated html files follow the HTML 2.0 standard, and colours are specified with `<FONT>` tags. However, colours are hard-coded.
-
-* If the option :option:`--format=css` is specified, then the generated html 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.
-
 VPI build commands
 ==================
 
 These commands simplify the compile and the link of a user vpi module. They are all wrapper: 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.
 
-.. _VPI_compile_command:
+.. index:: cmd VPI compile
 
 compile [:samp:`--vpi-compile`]
 -------------------
 
-.. index:: --vpi-compile command
+.. option:: --vpi-compile <command>
 
 Add include path to the command and execute it::
 
@@ -580,10 +469,12 @@ executes::
 
 .. _VPI_link_command:
 
+.. index:: cmd VPI link
+
 link [:samp:`--vpi-link`]
 ----------------
 
-.. index:: --vpi-link command
+.. option:: --vpi-link <command>
 
 Add library path and name to the command and execute it::
 
@@ -604,45 +495,39 @@ executes::
 
 .. _VPI_cflags_command:
 
+.. index:: cmd VPI cflags
+
 cflags [:samp:`--vpi-cflags`]
 ------------------
 
-.. index:: --vpi-cflags command
-
-:samp:`ghdl --vpi-cflags`
+.. option:: --vpi-cflags
 
 Display flags added by :option:`--vpi-compile`.
 
-.. _VPI_ldflags_command:
+.. index:: cmd VPI ldflags
 
 ldflags [:samp:`--vpi-ldflags`]
 -------------------
 
-.. index:: --vpi-ldflags command
-
-:samp:`ghdl --vpi-ldflags`
+.. option:: --vpi-ldflags
 
 Display flags added by :option:`--vpi-link`.
 
-.. _VPI_include_dir_command:
+.. index:: cmd VPI include dir
 
 include dir [:samp:`--vpi-include-dir`]
 -----------------------
 
-.. index:: --vpi-include-dir command
-
-:samp:`ghdl --vpi-include-dir`
+.. option:: --vpi-include-dir
 
 Display the include directory added by the compile flags.
 
-.. _VPI_library_dir_command:
+.. index:: cmd VPI library dir
 
 library dir [:samp:`--vpi-library-dir`]
 -----------------------
 
-.. index:: --vpi-library-dir command
-
-:samp:`ghdl --vpi-library-dir`
+.. option:: --vpi-library-dir
 
 Display the library directory added by the link flags.
 
diff --git a/doc/using/QuickStartGuide.rst b/doc/using/QuickStartGuide.rst
index 3173a6c61..baf6c6a52 100644
--- a/doc/using/QuickStartGuide.rst
+++ b/doc/using/QuickStartGuide.rst
@@ -1,3 +1,4 @@
+.. program:: ghdl
 .. _USING:QuickStart:
 
 ******************
@@ -31,23 +32,26 @@ To illustrate the large purpose of `VHDL`, here is a commented `'Hello world'` p
      end process;
   end behaviour;
 
-.. TIP:: Both :samp:`.vhdl` and :samp:`.vhd` extensions are used for VHDL source files, while :samp:`.v` is used for Verilog. 
+.. TIP::
 
-.. TODO:: Unless you use especial characters, either `UTF-8` or `ISO-8859-1` encodings can be used. However, if you do, the latter should be used. The IEEE 1076-2008 Standard defines ASCII (7-bit encoding) or ISO Latin-1 (ISO-8859-1) as default. GHDL has a relaxing rule :samp:`--mb` (multi byte) to allow UTF-8 or other encodings in comments. Please see the MB description for details.
+	* Both :samp:`.vhdl` and :samp:`.vhd` extensions are used for VHDL source files, while :samp:`.v` is used for Verilog. 
+	* Unless you use especial characters, either `UTF-8` or `ISO-8859-1` encodings can be used. However, if you do, the latter should be used. The standard defines ASCII (7-bit encoding) or ISO Latin-1 (ISO-8859-1) as default. However, GHDL has a relaxing option, :option:`--mb-comments` (multi byte), to allow UTF-8 or other encodings in comments.
 
 - First, you have to compile the file; this is called `analysis` of a design file in `VHDL` terms. Run :samp:`ghdl -a hello.vhdl` in the `shell`. This command creates or updates a file :file:`work-obj93.cf`, which describes the library :samp:`work`.
+- Then, run :samp:`ghdl -e hello_world` in the `shell`. Option :option:`-e` means :dfn:`elaborate`, which is used to build a design, with the :samp:`hello_world` entity at the top of the hierarchy.
+- Last, you can directly launch the simulation running :samp:`ghdl -r hello_world` in the `shell`. The result of the simulation will be shown on screen:
 
-.. WARNING:: If a GCC/LLVM variant of `GHDL` is used:
+.. code-block:: shell
 
-  * `Analysis` generates a file, :file:`hello.o`, which is the object file corresponding to your `VHDL` program.  This is not created on Windows.
-  * An aditional step is required; run :samp:`ghdl -e hello_world` in the `shell`. Option :option:`-e` means :dfn:`elaborate`, which is used to build a design, with the :samp:`hello_world` entity at the top of the hierarchy. This wil generate an executable binary named :file:`hello_world`.
-  * :option:`-e` can be bypassed with mcode, but you can still use it to check for some elaboration problems.
-  
-- Last, launch the simulation running :samp:`ghdl -r hello_world` in the `shell`. The result of the simulation will be shown on the screen::
+	Hello world!  
 
-  Hello world!  
-  
-.. TIP:: If a GCC/LLVM variant of `GHDL` is used, :option:`-r` is just a passthrough to the binary generated in the `elaboration`. Therefore, the executable can be run directly, :samp:`./hello_world`. See :ref:`Run_command` for more informartion.
+.. HINT:: If a GCC/LLVM variant of `GHDL` is used:
+
+  * `Analysis` generates a file, :file:`hello.o`, which is the object file corresponding to your `VHDL` program.  This is not created with mcode.
+  * The elaboration step is compulsory after the analysis and prior to launching the simulation; This wil generate an executable binary named :file:`hello_world`.
+  * As a result, :option:`-r` is just a passthrough to the binary generated in the `elaboration`. Therefore, the executable can be run directly, :samp:`./hello_world`. See :option:`-r` for more informartion.
+ 
+.. HINT:: :option:`-e` can be bypassed with mcode, since :option:`-r` actually elaborates the design and saves it on memory before running the simulation. But you can still use it to check for some elaboration problems.
   
 A full adder
 ============
@@ -146,7 +150,7 @@ If your design is rather complex, you'd like to inspect signals. Signal values c
 
 As explained in the `manual <http://gtkwave.sourceforge.net/gtkwave.pdf>`_, GtkWave *'relies on a post-mortem approach through the use of dumpfiles'*. Therefore, you should first simulate your design and dump a waveform file, say VCD: :samp:`ghdl -r adder_tb --vcd=adder.vcd`. Then, you can view the dump: :samp:`gtkwave adder.vcd`.
 
-See :ref:`simulation_options`, for more details on other runtime options.
+See section ':ref:`simulation_options`', for more details on other runtime options.
 
 Starting with a design
 ======================
@@ -192,7 +196,7 @@ Unless you are only studying VHDL, you will work with larger designs than the on
   
   * Remove the :file:`work/` directory: :samp:`rm -rf work`. Only the executable is kept. If you want to rebuild the design, create the :file:`work/` directory, import the sources, and make the design.
 
-.. WARNING:: Sometimes, a design does not fully follow the VHDL standards. For example it uses the badly engineered :samp:`std_logic_unsigned` package. GHDL supports this VHDL dialect through some options: :samp:`--ieee=synopsys -fexplicit`. See :ref:`IEEE_library_pitfalls`, for more details.
+.. WARNING:: Sometimes, a design does not fully follow the VHDL standards. For example it uses the badly engineered :samp:`std_logic_unsigned` package. GHDL supports this VHDL dialect through some options: :samp:`--ieee=synopsys -fexplicit`. See section ':ref:`IEEE_library_pitfalls`', for more details.
 
 Further examples
 =======================
diff --git a/doc/using/Simulation.rst b/doc/using/Simulation.rst
index 11ace067c..d3aa6f9a5 100644
--- a/doc/using/Simulation.rst
+++ b/doc/using/Simulation.rst
@@ -1,3 +1,4 @@
+.. program:: ghdl
 .. _USING:Simulation:
 
 Simulation and runtime
@@ -27,7 +28,7 @@ Here is the list of the most useful options.  Some debugging options are
 also available, but not described here.  The :option:`--help` options lists
 all options available, including the debugging one.
 
-.. option:: --assert-level=<LEVEL>
+.. option:: --assert-level<=LEVEL>
 
   Select the assertion level at which an assertion violation stops the
   simulation.  `LEVEL` is the name from the `severity_level`
@@ -45,7 +46,7 @@ all options available, including the debugging one.
   Option :option:`--assert-level=none` prevents any assertion violation to stop
   simulation.
 
-.. option:: --ieee-asserts=<POLICY>
+.. option:: --ieee-asserts<=POLICY>
 
   Select how the assertions from :samp:`ieee` units are
   handled. `POLICY` can be :samp:`enable` (the default),
@@ -55,7 +56,7 @@ all options available, including the debugging one.
   This option can be useful to avoid assertion message from
   :samp:`ieee.numeric_std` (and other :samp:`ieee` packages).
 
-.. option:: --stop-time=<TIME>
+.. option:: --stop-time<=TIME>
 
   Stop the simulation after :samp:`TIME`.  :samp:`TIME` is expressed as a time
   value, *without* any space.  The time is the simulation time, not
@@ -66,7 +67,7 @@ all options available, including the debugging one.
     $ ./my_design --stop-time=10ns
     $ ./my_design --stop-time=ps
 
-.. option:: --stop-delta=<N>
+.. option:: --stop-delta<=N>
 
   Stop the simulation after `N` delta cycles in the same current time.
 
@@ -80,13 +81,13 @@ all options available, including the debugging one.
 
   Disable buffering on stdout, stderr and files opened in write or append mode (TEXTIO).
 
-.. option:: --psl-report=<FILENAME>
+.. option:: --psl-report<=FILENAME>
 
   Write a report for PSL assertions and coverage at the end of
   simulation.  The file is written using the JSON format, but still
   being human readable.
 
-.. option:: --sdf=<PATH>=<FILENAME>
+.. option:: --sdf<=PATH=FILENAME>
 
   Do VITAL annotation on `PATH` with SDF file :file:`FILENAME`.
 
@@ -96,16 +97,16 @@ all options available, including the debugging one.
 
   Specifying a delay::
 
-   --sdf=min=<PATH>=<FILENAME>
-   --sdf=typ=<PATH>=<FILENAME>
-   --sdf=max=<PATH>=<FILENAME>
+   --sdf=min=PATH=FILENAME
+   --sdf=typ=PATH=FILENAME
+   --sdf=max=PATH=FILENAME
 
   If the option contains a type of delay, that is :samp:`min=`,
   :samp:`typ=` or :samp:`max=`, the annotator use respectively minimum,
   typical or maximum values.  If the option does not contain a type of delay,
   the annotator use the typical delay.
 
-  See :ref:`Backannotation`, for more details.
+  See section ':ref:`Backannotation`', for more details.
 
 .. option:: --help
 
@@ -116,7 +117,7 @@ all options available, including the debugging one.
 Export waveforms
 ============
 
-.. option:: --read-opt-file=<FILENAME>
+.. option:: --read-opt-file<=FILENAME>
 
   Filter signals to be dumped to the wave file according to the wave option
   file provided.
@@ -149,15 +150,15 @@ Export waveforms
      # those of sub3)
      /**/sub3/*/*
 
-.. option:: --write-opt-file=<FILENAME>
+.. option:: --write-opt-file<=FILENAME>
 
   If the wave option file doesn't exist, creates it with all the signals of
   the design. Otherwise throws an error, because it won't erase an existing
   file.
 
-.. option:: --vcd=<FILENAME>
+.. option:: --vcd<=FILENAME>
 
-.. option:: --vcdgz=<FILENAME>
+.. option:: --vcdgz<=FILENAME>
 
   .. index:: vcd
 
@@ -208,13 +209,17 @@ Export waveforms
   format supporting VHDL types.  If you are aware of such a free format,
   please mail me (:ref:`Reporting_bugs`).
 
-.. option:: --fst=<FILENAME>
+.. option:: --vcd-nodate
+
+  Do not write date in VCD file
+  
+.. option:: --fst<=FILENAME>
 
   Write the waveforms into a `fst`, that can be displayed by
   `gtkwave`. The `fst` files are much smaller than VCD or
   `GHW` files, but it handles only the same signals as the VCD format.
 
-.. option:: --wave=<FILENAME>
+.. option:: --wave<=FILENAME>
 
   Write the waveforms into a `ghw` (GHdl Waveform) file.  Currently, all
   the signals are dumped into the waveform file, you cannot select a hierarchy
@@ -224,17 +229,17 @@ Export waveforms
   It may change slightly.  The :samp:`gtkwave` tool can read the GHW files.
 
   Contrary to VCD files, any VHDL type can be dumped into a GHW file.
-
+ 
 .. TODO::
 
-  - :samp:` --vcd-nodate       do not write date in VCD file`
-  - Is interactive simulation only possible with VCD? Can't it be done with either FST or GHW?
+  - Brief explanation on why these three formats where chosen only. Explain why other formats add no functionality.
+  - Interactive simulation (GtkWave) is only possible with VCD.
   - `Source code annotation is currently not available for VHDL, however all of GTKWave's other debug features are readily accessible. VHDL support is planned for a future release`. That's something that could be added in the future, but I have no plan for it.
   
-Export design hierarchy
+Export hierarchy and references
 ============
   
-.. option:: --disp-tree[=<KIND>]
+.. option:: --disp-tree<[=KIND]>
 
   .. index:: display design hierarchy
 
@@ -259,32 +264,96 @@ Export design hierarchy
 .. option:: --no-run
 
   Stop the simulation before the first cycle. This may be used with :option:`--disp-tree` to display the tree without simulating the whole design. This option actually elaborates the design, so it will catch any bound error in port maps. 
+
+.. option:: --xref-html <[options] file...>
+
+To easily navigate through your sources, you may generate cross-references. This command generates an html file for each :samp:`file` given in the command line, with syntax highlighting and full cross-reference: every identifier is a link to its declaration. Besides, an index of the files is created too.
+
+The set of :samp:`file` are analyzed, and then, if the analysis is successful, html files are generated in the directory specified by the :option:`-o <dir>` option, or :file:`html/` directory by default.
+
+* If the option :option:`--format=html2` is specified, then the generated html files follow the HTML 2.0 standard, and colours are specified with `<FONT>` tags. However, colours are hard-coded.
+
+* If the option :option:`--format=css` is specified, then the generated html 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:: --psl-report<=FILE>
+
+Generate a JSON file at the end of the simulation reporting, for each PSL cover and assert statements, the name, source location and whether it passed or failed.
  
 .. TODO::
-  * The json format is not documented, except it should be self-documented. Maybe worth adding a small example ?
-  * The XML format (for --file-to-xml) is not documented and it may change as it shows internal stuff. :samp:`--file-to-xml FILEs  Dump AST in XML`
-   
-Debugging VHDL programs
-============
+  * Maybe worth adding a small example of how to generate a JSON file?
+ 
+.. 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...
+
+.. 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.
+	* Note that at this time there is no XML dump of the elaborated design.
 
 .. index:: debugging
+	
+Debugging
+============
+
+.. option:: --trace-signals
+
+Display signals after each cycle.
+
+.. option:: --trace-processes
+
+Display process name before each cycle.
+
+.. option:: --stats
+
+Display run-time statistics.
+
+.. option:: --disp-order
+
+Display signals order.
+
+.. option:: --disp-sources
+
+Display sources while displaying signals.
+
+.. option:: --disp-sig-types
+
+Display signal types.
+
+.. option:: --disp-signals-map
+
+Display map bw declared signals and internal signals.
+
+.. option:: --disp-signals-table
+
+Display internal signals.
+
+.. option:: --checks
+
+Do internal checks after each process run.
+
+.. option:: --activity<=LEVEL>
+
+Watch activity of LEVEL signals: LEVEL is all, min (default) or none (unsafe).
+
+.. option:: --dump-rti
+
+Dump Run Time Information (RTI).
+
+.. option:: --bootstrap
+
+Allow :samp:`--work=std`
+
+GNU Debugger (GDB)
+-------------------
 
 .. index:: `__ghdl_fatal`
 
-Debugging VHDL programs using `GDB` is possible only on GNU/Linux systems.
+.. WARNING:: Debugging VHDL programs using `GDB` is possible only with GCC/LLVM.
 
-`GDB` is a general purpose debugger for programs compiled by `GCC`.
-Currently, there is no VHDL support for `GDB`.  It may be difficult
-to inspect variables or signals in `GDB`, however, `GDB` is
-still able to display the stack frame in case of error or to set a breakpoint
-at a specified line.
+GDB is a general purpose debugger for programs compiled by GCC. Currently, there is no VHDL support for GDB. It may be difficult to inspect variables or signals in GDB. However, it is still able to display the stack frame in case of error or to set a breakpoint at a specified line.
 
-`GDB` can be useful to precisely catch a runtime error, such as indexing
-an array beyond its bounds.  All error check subprograms call the
-`__ghdl_fatal` procedure.  Therefore, to catch runtime error, set
-a breakpoint like this:
+GDB can be useful to precisely catch a runtime error, such as indexing an array beyond its bounds. All error check subprograms call the :samp:`__ghdl_fatal` procedure. Therefore, to catch runtime error, set a breakpoint like this::
 
   (gdb) break __ghdl_fatal
 
-When the breakpoint is hit, use the `where` or `bt` command to
-display the stack frames.
+When the breakpoint is hit, use the :samp:`where` or :samp:`bt` command to display the stack frames.