Fixed typos, indentation and headline underlining.

1 files changed, 63 insertions, 37 deletions

diff --git a/doc/using/InvokingGHDL.rst b/doc/using/InvokingGHDL.rst
index bf7619b7b..ceb25b1a6 100644
--- a/doc/using/InvokingGHDL.rst
+++ b/doc/using/InvokingGHDL.rst
@@ -1,20 +1,22 @@
 .. program:: ghdl
 .. _USING:Invoking:
 
-*************
 Invoking GHDL
-*************
+#############
 
 The form of the :program:`ghdl` command is :samp:`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.
 
-.. 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 :samp:`@` is considered as a response file; it is replaced by arguments read from the file (separated by blanks and end of line).
+.. 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 :samp:`@` is considered as a response file; it is replaced by arguments read from the file (separated by blanks and end of line).
 
-.. HINT:: Only the most common commands and options are shown here. For most advanced and experimental features see section :ref:`REF:Command`.
+.. 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 :samp:`std` and :samp:`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 :envvar:`GHDL_PREFIX` environment variable
@@ -23,14 +25,15 @@ The form of the :program:`ghdl` command is :samp:`ghdl command [options...]`. Th
 	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`]
-----------------
+---------------------
 
 .. option:: -a <[options...] file...>
 
@@ -38,10 +41,11 @@ Analyzes/compiles one or more files, and creates an object file for each source
 
 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`.
 
+
 .. index:: cmd elaboration
 
 Elaboration [:samp:`-e`]
--------------------
+------------------------
 
 .. option:: -e <[options...] primary_unit [secondary_unit]>
 
@@ -59,10 +63,11 @@ Name of the units must be a simple name, without any dot.  You can select the na
 
 * 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.
 
+
 .. index:: cmd run
  
 Run [:samp:`-r`]
------------
+----------------
 
 .. option:: -r <[options...] primary_unit [secondary_unit] [simulation_options...]>
 
@@ -79,32 +84,36 @@ This command exists for three reasons:
 
 See section ':ref:`USING:Simulation`', for details on options.
 
+
 .. index:: cmd elaborate and run
 
 Elaborate and run [:samp:`--elab-run`]
--------------------------
+--------------------------------------
 
 .. option:: --elab-run <[elab_options...] primary_unit [secondary_unit] [run_options...]>
 
 Acts like the elaboration command (see :option:`-e`) followed by the run command (see :option:`-r`).
 
+
 .. index:: cmd checking syntax
 
 Check syntax [:samp:`-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.
 
+
 .. index:: cmd analyze and elaborate
 
 Analyze and elaborate [:samp:`-c`]
------------------------------
+----------------------------------
 
 .. option:: -c <[options] file... -<e|r> primary_unit [secondary_unit]>
 
-.. HINT:: With GCC/LLVM, :option:`-e` should be used, and :option:`-r` with mcode.
+.. 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.
 
@@ -117,19 +126,23 @@ The advantages over the traditional approach (analyze and then elaborate) are:
 * You don't need to know an analysis order.
 * This command produces smaller executable, since unused units and subprograms do not generate code.
 
-.. HINT:: However, you should know that currently most of the time is spent in code generation and the analyze and elaborate command generate code for all units needed, even units of :samp:`std` and :samp:`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.
+.. HINT::
+   However, you should know that currently most of the time is spent in code generation and the analyze and elaborate command generate code for all units needed, even units of :samp:`std` and :samp:`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.
 
-.. WARNING:: This command is still under development. In case of problems, you should go back to the traditional way.
 
 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.
 
+
 .. index:: cmd importing files
 
 Import [:samp:`-i`]
---------------
+-------------------
 
 .. option:: -i <[options] file...>
 
@@ -138,22 +151,21 @@ All the files specified in the command line are scanned, parsed and added in the
 .. 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.
 
 See :option:`-m`, to actually build the design.
 
+
 .. index:: cmd make
 
 Make [:samp:`-m`]
-------------
+-----------------
 
 .. 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:`--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).
 
 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.
@@ -166,17 +178,19 @@ The make command imports files which have been modified. Then, a design hierarch
 
 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`]
--------------------------
+------------------------------------------
 
 .. option:: --gen-makefile <[options] primary [secondary]>
 
 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
@@ -306,12 +320,14 @@ Options
 
   Be verbose. For example, for analysis, elaboration and make commands, GHDL displays the commands executed.
 
+
 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.
 
-.. HINT:: You could disable a warning by using the :samp:`--warn-no-XXX` or :samp:`-Wno-XX` instead of :samp:`--warn-XXX` or :samp:`-WXXX`.
+.. HINT::
+   You could disable a warning by using the :samp:`--warn-no-XXX` or :samp:`-Wno-XX` instead of :samp:`--warn-XXX` or :samp:`-WXXX`.
 
 .. option:: --warn-reserved
 
@@ -371,8 +387,9 @@ Some constructions are not erroneous but dubious. Warnings are diagnostic messag
   Emit a warning in case of runtime error that is detected during
   analysis.
 
+
 Diagnostics Control
-========================
+===================
 
 .. option:: -fcolor-diagnostics
 .. option:: -fno-color-diagnostics
@@ -383,7 +400,8 @@ Diagnostics Control
 .. option:: -fno-diagnostics-show-option
 
   Control whether the warning option is displayed at the end of warning messages, so that user can easily know how to disable it.
-  
+
+
 Library commands
 ================
 
@@ -396,38 +414,42 @@ A library's source code is usually stored and compiled into its own directory, t
 
 Furthermore, GHDL provides a few commands which act on a library:
 
+
 .. index:: cmd library directory
 
 Directory [:samp:`--dir`]
------------------
+-------------------------
 
 .. option:: --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`.
 
+
 .. index:: cmd library clean
 
 Clean [:samp:`--clean`]
--------------
+-----------------------
 
 .. 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.
 
+
 .. index:: cmd library remove
 
 Remove [:samp:`--remove`]
---------------
+-------------------------
 
 .. 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.
 
+
 .. index:: cmd library copy
 
 Copy [:samp:`--copy`]
-------------
+---------------------
 
 .. option:: --copy <--work=name [options]>
 
@@ -438,16 +460,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
 
+
 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.
 
+
 .. index:: cmd VPI compile
 
 compile [:samp:`--vpi-compile`]
--------------------
+-------------------------------
 
 .. option:: --vpi-compile <command>
 
@@ -472,7 +496,7 @@ executes::
 .. index:: cmd VPI link
 
 link [:samp:`--vpi-link`]
-----------------
+-------------------------
 
 .. option:: --vpi-link <command>
 
@@ -498,7 +522,7 @@ executes::
 .. index:: cmd VPI cflags
 
 cflags [:samp:`--vpi-cflags`]
-------------------
+-----------------------------
 
 .. option:: --vpi-cflags
 
@@ -507,7 +531,7 @@ Display flags added by :option:`--vpi-compile`.
 .. index:: cmd VPI ldflags
 
 ldflags [:samp:`--vpi-ldflags`]
--------------------
+-------------------------------
 
 .. option:: --vpi-ldflags
 
@@ -516,7 +540,7 @@ Display flags added by :option:`--vpi-link`.
 .. index:: cmd VPI include dir
 
 include dir [:samp:`--vpi-include-dir`]
------------------------
+---------------------------------------
 
 .. option:: --vpi-include-dir
 
@@ -525,12 +549,13 @@ Display the include directory added by the compile flags.
 .. index:: cmd VPI library dir
 
 library dir [:samp:`--vpi-library-dir`]
------------------------
+---------------------------------------
 
 .. option:: --vpi-library-dir
 
 Display the library directory added by the link flags.
 
+
 .. _ieee_library_pitfalls:
 
 IEEE library pitfalls
@@ -651,4 +676,5 @@ It is better to only use the standard packages defined by IEEE, which provides t
 
 .. index:: Math_Complex
 
-.. HINT:: The :samp:`ieee` math packages (:samp:`math_real` and :samp:`math_complex`) provided with `GHDL` are fully compliant with the `IEEE` standard.
+.. HINT::
+   The :samp:`ieee` math packages (:samp:`math_real` and :samp:`math_complex`) provided with `GHDL` are fully compliant with the `IEEE` standard.