Fixed encoding problem. Replaced :samp: by ``.

4 files changed, 78 insertions, 53 deletions

diff --git a/doc/building/Building.rst b/doc/building/Building.rst
index e46b9c0b7..16d087342 100644
--- a/doc/building/Building.rst
+++ b/doc/building/Building.rst
@@ -1,49 +1,47 @@
 .. _BUILD:
 
-Building GHDL
-#############
+Building GHDL from Sources
+##########################
 
-GHDL currently supports three supported different backends (code generators): `mcode` (built-in), `GCC <http://gcc.gnu.org/>`_ and `LLVM <http://llvm.org/>`_ . Here is a short comparison, so that you can choose the one you want to use:
+.. rubric:: Download
 
-+------------------------+------------------------------------------------------------------------------------------+---------------------------------------------------------+
-|                        | pros                                                                                     | cons                                                    |
-+========================+==========================================================================================+=========================================================+
-| `mcode`                | - very easy to build                                                                     | - :samp:`x86_64`/:samp:`i386` only                      |
-|                        | - very quick analysis                                                                    | - simulation is slower                                  |
-|                        | - can handle very large designs                                                          |                                                         |
-+------------------------+------------------------------------------------------------------------------------------+---------------------------------------------------------+
-| GCC                    | - generated code is faster (particularly with :samp:`-O` or :samp:`-O2`)                 | - analysis can take time (particularly for large units) |
-|                        | - generated code can be debugged (with :samp:`-g`)                                       | - build is more complex                                 |
-|                        | - ported to many platforms (:samp:`x86`, :samp:`x86_64`, :samp:`powerpc`, :samp:`sparc`) |                                                         |
-+------------------------+------------------------------------------------------------------------------------------+---------------------------------------------------------+
-| LLVM                   | - Same as GCC                                                                            | Coverage, :samp:`gcov`, is unique to GCC                |
-|                        | - Easier to build than GCC                                                               |                                                         |
-+------------------------+------------------------------------------------------------------------------------------+---------------------------------------------------------+
+GHDL can be downloaded as a `zip-file <https://github.com/tgingold/ghdl/archive/master.zip>`_
+(latest 'master' branch) or cloned with ``git clone`` from GitHub. GitHub
+offers HTTPS and SSH as transfer protocols. See the :ref:`Download <GETTING:Download>`
+page for further details. The installation directory is referred to as ``GHDLRoot``.
 
-.. HINT:: The output of both GCC and LLVM is an executable file, but `mcode` does not generate any. Therefore, if using GCC/LLVM, the call with argument :samp:`-r` can be replaced with direct execution of the binary. See section :ref:`USING:QuickStart`.
++----------+-----------------------------------------------------------+
+| Protocol | Git Clone Command                                         |
++==========+===========================================================+
+| HTTPS    | ``git clone https://github.com/tgingold/ghdl.git ghdl``   |
++----------+-----------------------------------------------------------+
+| SSH      | ``git clone ssh://git@github.com:tgingold/ghdl.git ghdl`` |
++----------+-----------------------------------------------------------+
 
-After making your choice, you can jump to the corresponding section below. However, we suggest you to read :ref:`BUILD:dir_structure` before, so that you know where the content is placed and which temporal files are expected to be created.
+.. rubric:: Available back-ends
 
-.. HINT:: Since GHDL is written in `Ada`, independently of the code generator you use, the `GNU Ada compiler`, `GNAT GPL`, is required, 2014 (or later) for :samp:`x86` (32 or 64 bits). `GNAT GPL` can be downloaded anonymously from `libre.adacore.com <http://libre.adacore.com/tools/gnat-gpl-edition/>`_. Then, untar and run the doinstall script. Alternatively, most GNU/Linux provide a package named :samp:`gcc-ada` or :samp:`gcc-gnat`.
+GHDL currently supports three supported different back-ends (code generators):
+* `mcode` (built-in),
+* `GCC <http://gcc.gnu.org/>`_, and
+* `LLVM <http://llvm.org/>`_ .
 
-.. TODO::
+Here is a short comparison, so that you can choose the one you want to use:
 
-   * @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.
++----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+
+| Back-end                   | Pros                                                                       | Cons                                                    |
++============================+============================================================================+=========================================================+
+| :ref:`mcode <BUILD:mcode>` | * Very easy to build                                                       | * ``x86_64``/``i386`` only                              |
+|                            | * Very quick analysis                                                      | * Simulation is slower                                  |
+|                            | * Can handle very large designs                                            |                                                         |
++----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+
+| :ref:`GCC <BUILD:gcc>`     | * Generated code is faster (particularly with ``-O`` or ``-O2``)           | * Analysis can take time (particularly for large units) |
+|                            | * Generated code can be debugged (with ``-g``)                             | * Build is more complex                                 |
+|                            | * Ported to many platforms (``x86``, ``x86_64``, ``powerpc``, ``sparc``)   | * Code coverage collection (``gcov``) is unique to GCC  |
++----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+
+| :ref:`LLVM <BUILD:llvm>`   | * Same as GCC                                                              |                                                         |
+|                            | * Easier to build than GCC                                                 |                                                         |
++----------------------------+----------------------------------------------------------------------------+---------------------------------------------------------+
   
-
-GHDL can be build with three different back-ends: mcode, LLVM or GCC.
-
-* :ref:`mcode <BUILD:mcode>`
-* :ref:`LLVM <BUILD:llvm>`
-* :ref:`GCC <BUILD:gcc>`
-
 .. toctree::
    :hidden:
    
@@ -52,3 +50,31 @@ GHDL can be build with three different back-ends: mcode, LLVM or GCC.
    With LLVM Backend <llvm/index>
    With GCC Backend <gcc/index>
    TestSuites
+
+.. HINT::
+   The output of both GCC and LLVM is an executable file, but `mcode` does not
+   generate any. Therefore, if using GCC/LLVM, the call with argument ``-r`` can
+   be replaced with direct execution of the binary. See section :ref:`USING:QuickStart`.
+
+After making your choice, you can jump to the corresponding section.
+However, we suggest you to read :ref:`BUILD:dir_structure` before, so that you
+know where the content is placed and which temporal files are expected to be
+created.
+
+.. HINT::
+   Since GHDL is written in `Ada`, independently of the code generator you use,
+   the `GNU Ada compiler`, `GNAT GPL`, is required, 2014 (or later) for ``x86``
+   (32 or 64 bits). `GNAT GPL` can be downloaded anonymously from `libre.adacore.com <http://libre.adacore.com/tools/gnat-gpl-edition/>`_.
+   Then, untar and run the doinstall script. Alternatively, most GNU/Linux
+   provide a package named ``gcc-ada`` or ``gcc-gnat``.
+
+.. TODO::
+
+   * @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.
diff --git a/doc/conf.py b/doc/conf.py
index a42f29e6e..c04bb5b4e 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -153,8 +153,7 @@ try:
 	with open(prologPath, "r") as prologFile:
 		rst_prolog = prologFile.read()
 except Exception as ex:
-	print("CWD: " + str(os.getcwd()))
-	print("[ERROR:] File '{0!s}' not found.".format(prologPath))
+	print("[ERROR:] While reading '{0!s}'.".format(prologPath))
 	print(ex)
 	rst_prolog = ""
 
diff --git a/doc/index.rst b/doc/index.rst
index 6d86f79b1..17b95dc2e 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -36,10 +36,10 @@ Lorem ipsum dolor sit amet...
    :caption: Introduction
    :hidden:
 
-   0_Intro/WhatIsVHDL
-   0_Intro/WhatIsGHDL
-   0_Intro/Contributing
-   0_Intro/Copyrights
+   intro/WhatIsVHDL
+   intro/WhatIsGHDL
+   intro/Contributing
+   intro/Copyrights
    License/gpl-2.0
 
 .. raw:: latex
@@ -50,9 +50,9 @@ Lorem ipsum dolor sit amet...
    :caption: GHDL usage
    :hidden:
 
-   1_Using/QuickStartGuide
-   1_Using/InvokingGHDL
-   1_Using/Simulation
+   using/QuickStartGuide
+   using/InvokingGHDL
+   using/Simulation
 
 .. raw:: latex
 
@@ -62,9 +62,9 @@ Lorem ipsum dolor sit amet...
    :caption: Getting GHDL
    :hidden:
 
-   2_Getting/Releases
-   3_Building/Building
-   3_Building/VendorPrimitives
+   getting/Releases
+   Building GHDL building/building>
+   building/PrecompileVendorPrimitives
 
 .. raw:: latex
 
@@ -74,10 +74,10 @@ Lorem ipsum dolor sit amet...
    :caption: Implementation References
    :hidden:
 
-   4_References/CommandReference
-   4_References/CodingStyle
-   4_References/ImplementationOfVHDL
-   4_References/ImplementationOfVITAL
+   references/CommandReference
+   references/CodingStyle
+   references/ImplementationOfVHDL
+   references/ImplementationOfVITAL
 
 .. raw:: latex
 
diff --git a/doc/prolog.inc b/doc/prolog.inc
index 94490f67c..a0c1f3bf8 100644
--- a/doc/prolog.inc
+++ b/doc/prolog.inc
@@ -1,4 +1,4 @@
-.. # preload commonly known graphical characters like ©
+.. # preload commonly known graphical characters like ©
 .. include:: <isonum.txt>
 
 .. # define a hard kine break for HTML