doc/changelog renamed to doc/appendix

Replace :samp: with

23 files changed, 336 insertions, 231 deletions

diff --git a/doc/changelog/2014/index.rst b/doc/appendix/2014/index.rst
index 5822e67e7..5822e67e7 100644
--- a/doc/changelog/2014/index.rst
+++ b/doc/appendix/2014/index.rst
diff --git a/doc/changelog/2014/v0.30.rst b/doc/appendix/2014/v0.30.rst
index 87ebef22f..87ebef22f 100644
--- a/doc/changelog/2014/v0.30.rst
+++ b/doc/appendix/2014/v0.30.rst
diff --git a/doc/changelog/2015/index.rst b/doc/appendix/2015/index.rst
index 3a3dc1ed5..3a3dc1ed5 100644
--- a/doc/changelog/2015/index.rst
+++ b/doc/appendix/2015/index.rst
diff --git a/doc/changelog/2015/v0.31.rst b/doc/appendix/2015/v0.31.rst
index 71bab8013..71bab8013 100644
--- a/doc/changelog/2015/v0.31.rst
+++ b/doc/appendix/2015/v0.31.rst
diff --git a/doc/changelog/2016/index.rst b/doc/appendix/2016/index.rst
index 340fb915d..340fb915d 100644
--- a/doc/changelog/2016/index.rst
+++ b/doc/appendix/2016/index.rst
diff --git a/doc/changelog/2016/v0.32.rst b/doc/appendix/2016/v0.32.rst
index ae6ff7a12..ae6ff7a12 100644
--- a/doc/changelog/2016/v0.32.rst
+++ b/doc/appendix/2016/v0.32.rst
diff --git a/doc/changelog/2016/v0.33.rst b/doc/appendix/2016/v0.33.rst
index 676390771..676390771 100644
--- a/doc/changelog/2016/v0.33.rst
+++ b/doc/appendix/2016/v0.33.rst
diff --git a/doc/changelog/2017/index.rst b/doc/appendix/2017/index.rst
index fa4ed0f1c..fa4ed0f1c 100644
--- a/doc/changelog/2017/index.rst
+++ b/doc/appendix/2017/index.rst
diff --git a/doc/changelog/2017/v0.34.rst b/doc/appendix/2017/v0.34.rst
index 874a36728..874a36728 100644
--- a/doc/changelog/2017/v0.34.rst
+++ b/doc/appendix/2017/v0.34.rst
diff --git a/doc/changelog/index.rst b/doc/appendix/Changelog.rst
index 43367c456..43367c456 100644
--- a/doc/changelog/index.rst
+++ b/doc/appendix/Changelog.rst
diff --git a/doc/appendix/Meta.rst b/doc/appendix/Meta.rst
new file mode 100644
index 000000000..19deb791a
--- /dev/null
+++ b/doc/appendix/Meta.rst
@@ -0,0 +1,110 @@
+.. _CHANGE:Roadmap:
+
+Meta
+####
+
+General guidelines to edit the documentation
+********************************************
+
+   1) It’s better for version control systems and diff tools to break lines at a sensible number of characters. Long lines appear as one diff. Also merging is more complex because merges are line based. Long unbreakable items may be longer (links, refs, …). We chose to use 160 chars.
+   2) Please indent all directive content by 3 spaces (not 2, and no tabs).
+   3) Please use ``*`` as an itemize character, since ``-`` and ``+`` are supported by docutils, but not officially supported by Sphinx`.
+   4) Please underline all headlines with at least as many characters as the headline is long. Following the Python pattern for headline the levels are:
+
+      .. code::
+	  
+         ############
+         ************ (sometimes skipped in small documents)
+         ============
+         -------------------
+         ‘’’’’’’’’’’’’’’’’’’’’’’’
+	  
+   5) It’s not required to write
+   
+      .. code::
+	    
+		 :samp:`code`
+	   
+      The default role for
+	   
+	  .. code::
+	   
+	     ``…``
+		  
+      is samp. ``:samp:`` is only required when you want to write italic text in code text.
+	  
+	  .. code::
+
+         :samp:`print 1+{variable}`
+
+      Now, variable becomes italic.
+
+      Please simplify all usages of :samp:`…`to ``…`` for readability. Here are the regular expressions for an editor like Notepad++:
+	  
+      - Search pattern:: :samp:`(.+?)`
+		 
+      - Replace pattern:: ``\1`` 
+
+   6) Each backend has one folder and each platform/compiler has one file. Please note that page headlines are different from ToC headline: 
+
+      .. code::   
+
+         .. toctree::
+            :hidden:
+
+            ToC entry <file1>
+            file2
+
+   7) A documentation should not use “you”, “we”, …, because it’s not an interactive conversation or informal letter. It’s like a thesis, everything is structured and formal. However, to make it more friendly to newcomers, we agree to allow informal language in section ':ref:`USING:QuickStart`'.
+
+   8) Please keep errors low.
+	  
+
+Guidelines to edit section 'Building'
+*************************************
+
+I prefer a text block, which explains how a compilation works, what I can configure for that backend, etc. After that, I prefer a code block with e.g. bash instructions on how to compile a backend. A list of instructions with embedded bash lines is not helpful. An experienced, as well as novice user, would like to copy a set of instructions into the shell. But it should be stated what these instructions will do. Complex flows like for GCC, can be split into multiple shell code blocks. Moreover, I find it essential, to demonstrate when and where to change directories.
+
+We would like to see a list like
+
+* gcc (Gnu Compiler Collection)
+* gcc-gnat (Ada compiler for GCC)
+* llvm-del (LLVM development package)
+* ...
+
+The goal is to also explain what a user is installing and what the few lines in the build description do. Now they know the name, can search for similar names if the have another package manager or distro or can ask Google/Wikipedia. We often find many build receipts with cryptic shell code and to execute this unknown stuff with sudo is not comfortable. We would like to know what it does before hiting enter.
+	  
+Documentation configuration
+***************************
+	  
+* Python snippet for Sphinx's `conf.py` to extract the current version number from Git (latest tag name). [:ghdlsharp:`200`, :ghdlsharp:`221`]
+
+* Reference ``genindex.html`` from the navigation bar. [:ghdlsharp:`200`]
+
+* Create "parts" (LaTeX terminology / chapter headlines) in navigation bar. [: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`
+
+CSS
+***
+
+* The indentation of the elements in the side menu have been modified. They are fixed por levels 1, 2 and 3 (`#294 <https://github.com/tgingold/ghdl/pull/294#issuecomment-281555760>`_) and 4 (later).
+
+* The RTD menu (bottom-left) has been modified (`#294 <https://github.com/tgingold/ghdl/pull/294#issuecomment-281513494>`_):
+
+   * No headlines are shown. It is not possible to remove only one of them with CSS only (JS would be required). However, because the content in most of the lines is self-explained, it is preferred not to show any.
+   * The Search box is removed.
+	
+Dist
+****
+		
+* Ubuntu uses `dash` instead of `bash` when a shell script is run. As a result, some functionalities, such as arrays like ``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/appendix/Roadmap.rst b/doc/appendix/Roadmap.rst
new file mode 100644
index 000000000..0d48c6c5c
--- /dev/null
+++ b/doc/appendix/Roadmap.rst
@@ -0,0 +1,46 @@
+.. _CHANGE:Roadmap:
+
+Roadmap | Future Improvements
+#############################
+
+I have several axes for `GHDL` improvements:
+
+* Documentation.
+* Better diagnostics messages (warning and error).
+* Full support of VHDL-2008.
+* Optimization (simulation speed).
+* Graphical tools (to see waves and to debug)
+* Style checks
+* VITAL acceleration
+
+TODOs
+=====
+
+* RTD builds fail if EPUB is activated.
+* Convert VendorPrimitives Markdown to RST
+* SVG images are not shown in the PDF. That's because LaTeX is used. Can any package be added to allow so?
+* Create a fancy Shield with a ZIP/TGZ icon, that points to the source code zip and tar.gz/tgz:
+
+   * https://github.com/tgingold/ghdl/archive/2017-03-01.zip
+   * https://github.com/tgingold/ghdl/archive/2017-03-01.tar.gz
+
+* The URL of some sections does not match the position in the hierarchy shown in the side menu. We have several options:
+
+   * Leave it as it is now.
+   * Create a new chapter in the side menu, named 'Building GHDL' and move 'Builing' and 'Precompile Vendor Primitives' there.
+   * Move 'Releases' to ch Introduction, renamed to 'Getting'. And keep 'Building', 'Vendor...' and 'Docker' in the same chapter, renamed to 'Building'.
+   
+   We are going to write more content first, and see how much we get. We'll reorder afterwards.
+   
+   [@Paebbels] I have no problem if a chapter has different URLs for sections. Users use either the web-gui / navigation bar or remember an url in the browser history, the will not see the discrepancy because the use only one access way.
+   
+Options shown in the command line help, but not found in the doc:
+
+* ``--syn-binding         use synthesis default binding rule``
+
+* VPI Commands
+
+	* ``--vpi=FILENAME        load VPI module``
+	* ``--vpi-trace[=FILE]    trace vpi calls to FILE``
+	
+.. todolist::
\ No newline at end of file
diff --git a/doc/building/Directories.rst b/doc/building/Directories.rst
index e7b054a7d..5a121ba55 100644
--- a/doc/building/Directories.rst
+++ b/doc/building/Directories.rst
@@ -3,9 +3,9 @@
 Directory Structure
 ###################
 
-* :samp:`src`: sources of GHDL, all of them in Ada.
+* ``src``: sources of GHDL, all of them in Ada.
 
-* :samp:`libraries`: mostly third party libraries such as, `ieee`, `mentor`,
+* ``libraries``: mostly third party libraries such as, `ieee`, `mentor`,
   `std`, `synopsys` and `vital`. Except a few shell and `Python` scripts, all
   the content is written in VHDL.
 
@@ -13,41 +13,41 @@ Directory Structure
     especially for FPGA primitives, soft and hard macros. These libraries can
     not be shipped with GHDL, but we offer prepared compile scripts to
     pre-compile the vendor libraries, if the vendor tool is present on the
-    computer. These are located in :samp:`libraries/vendor`.
+    computer. These are located in ``libraries/vendor``.
     See Vendor Primitives <VendorPrimitives.html> for information on how to
     use them.
 	
-* :samp:`dist`: scripts and auxiliar files to build GHDL in different
+* ``dist``: scripts and auxiliar files to build GHDL in different
   environments:
   
-  * :samp:`gcc`: header and configuration files to build GHDL with GCC (all the
+  * ``gcc``: header and configuration files to build GHDL with GCC (all the
     platforms).
-  * :samp:`linux`: build and test script written in shell, and other auxiliary
+  * ``linux``: build and test script written in shell, and other auxiliary
     files used to i) launch docker containers and ii) automate multiple builds
     in `Travis CI <https://travis-ci.org/>`_.
   
-  * :samp:`windows`:
+  * ``windows``:
     
-    * :samp:`mcode`:
-    * :samp:`appveyor`: 
+    * ``mcode``:
+    * ``appveyor``: 
   	
-* :samp:`doc`: `Markdown` and `reStructuredText` sources and auxiliary files to
+* ``doc``: `Markdown` and `reStructuredText` sources and auxiliary 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.
 
-* :samp:`testsuite`: see section :ref:`test_suites`.
+* ``testsuite``: see section :ref:`test_suites`.
 
-* `.yml` configuration files for CI environments (:samp:`readthedocs`,
-  :samp:`travis` and :samp:`appveyor`) and `ignore` files for source control
-  management tools (:samp:`git` and :samp:`.hg`).
+* `.yml` configuration files for CI environments (``readthedocs``,
+  ``travis`` and ``appveyor``) and `ignore` files for source control
+  management tools (``git`` and ``.hg``).
 
-* Files for building GHDL: :samp:`configure` and :samp:`Makefile.in`.
+* Files for building GHDL: ``configure`` and ``Makefile.in``.
 
-* Auxiliar files for development: :samp:`.gdbinit` and :samp:`ghdl.gpr.in`
+* Auxiliar files for development: ``.gdbinit`` and ``ghdl.gpr.in``
   (GNAT project file).
 
-* Text files: :samp:`COPYING.md`, :samp:`NEWS.md` and :samp:`README.md`.
+* Text files: ``COPYING.md``, ``NEWS.md`` and ``README.md``.
 
 
 .. TODO::
diff --git a/doc/building/TestSuites.rst b/doc/building/TestSuites.rst
index b4d8807a2..609e98755 100644
--- a/doc/building/TestSuites.rst
+++ b/doc/building/TestSuites.rst
@@ -6,6 +6,6 @@ Test Suites
 .. TODO::
 
    * @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`
+   	 * ``--expect-failure    invert exit status``
+   * ``--has-feature=X       test presence of feature X``
+   * ``--list-features       display the list of features``
diff --git a/doc/changelog/Meta.rst b/doc/changelog/Meta.rst
deleted file mode 100644
index b14927205..000000000
--- a/doc/changelog/Meta.rst
+++ /dev/null
@@ -1,31 +0,0 @@
-.. _CHANGE:Roadmap:
-
-Meta
-############
-
-* Python snippet for Sphinx's `conf.py` to extract the current version number from Git (latest tag name). 
-
-	* :ghdlsharp:`200`, :ghdlsharp:`221`
-
-* Reference :samp:`genindex.html` from the navigation bar.
-
-	* :ghdlsharp:`200`
-
-* Create "parts" (LaTeX terminology / chapter headlines) in navigation bar.
-
-	* :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
deleted file mode 100644
index 5358d3a57..000000000
--- a/doc/changelog/Roadmap.rst
+++ /dev/null
@@ -1,32 +0,0 @@
-.. _CHANGE:Roadmap:
-
-Roadmap | Future Improvements
-#############################
-
-I have several axes for `GHDL` improvements:
-
-* Documentation.
-* Better diagnostics messages (warning and error).
-* Full support of VHDL-2008.
-* Optimization (simulation speed).
-* Graphical tools (to see waves and to debug)
-* Style checks
-* VITAL acceleration
-
-TODOs
-=====
-
-- RTD builds fail if EPUB is activated.
-- Convert VendorPrimitives Markdown to RST
-- SVG images are not shown in the PDF. That's because LaTeX is used. Can any package be added to allow so?
-
-Options shown in the command line help, but not found in the doc:
-
-* :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 c04bb5b4e..3374b63e0 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -308,7 +308,6 @@ latex_documents = [
 # If false, no module index is generated.
 #latex_domain_indices = True
 
-
 # -- Options for manual page output ---------------------------------------
 
 # One entry per manual page. List of tuples
@@ -349,18 +348,18 @@ texinfo_documents = [
 # Sphinx.Ext.InterSphinx
 # ==============================================================================
 intersphinx_mapping = {
-	'python': ('https://docs.python.org/3.6/', None),
-	'poc': ('http://poc-library.readthedocs.io/en/release', None),
-#	'ghdl':   ('http://ghdl.readthedocs.io/en/latest', None)
+   'python': ('https://docs.python.org/3.6/', None),
+   'poc': ('http://poc-library.readthedocs.io/en/release', None),
+#   'ghdl':   ('http://ghdl.readthedocs.io/en/latest', None)
 }
 
 # ==============================================================================
 # Sphinx.Ext.ExtLinks
 # ==============================================================================
 extlinks = {
-  'ghdlsharp': ('https://github.com/tgingold/ghdl/issues/%s', '#'),
-	'ghdlissue': ('https://github.com/tgingold/ghdl/issues/%s', 'issue #'),
-	'ghdlpull':  ('https://github.com/tgingold/ghdl/pull/%s', 'pull request #'),
-	'ghdlsrc':   ('https://github.com/tgingold/ghdl/blob/master/src/%s', None),
-	'wikipedia': ('https://en.wikipedia.org/wiki/%s', None)
-}
+   'wikipedia': ('https://en.wikipedia.org/wiki/%s', None),
+   'ghdlsharp': ('https://github.com/tgingold/ghdl/issues/%s', '#'),
+   'ghdlissue': ('https://github.com/tgingold/ghdl/issues/%s', 'issue #'),
+   'ghdlpull':  ('https://github.com/tgingold/ghdl/pull/%s', 'pull request #'),
+   'ghdlsrc':   ('https://github.com/tgingold/ghdl/blob/master/src/%s', None)
+}
\ No newline at end of file
diff --git a/doc/getting/Releases.rst b/doc/getting/Releases.rst
index dc5e733ca..63284307a 100644
--- a/doc/getting/Releases.rst
+++ b/doc/getting/Releases.rst
@@ -158,12 +158,15 @@ protocol:
    git remote rename origin github
 
 
-
 ---------------------------------------------------------------------
 
 .. TODO::
  
-  - Naming:
-	- branch ghdl-X.Y
-	- tag vX.Y
-  - stable, development, nightly
\ No newline at end of file
+   * Naming:
+      * branch ghdl-X.Y
+      * tag vX.Y
+   * stable, development, nightly
+   * Regular: ubuntu-mcode and fedora-llvm (both latest default packages).
+   * Distro checking: three distros and three compilers, nine options total. Would you add Debian? Any other?
+   * Dependency version checking: single distro and specific compiler and version pairs. Which ones? LLVM 3.5? LLVM3.9? LLVM 4? GGC 4? GCC 5?
+   * Release: does it make any sense to realease multiple distro versions, if all of them are compiled with the same dependency version? A side observation is that Fedora's release is half the size of Ubuntu's, even though both are compiled with LLVM 3.8. Why?
\ No newline at end of file
diff --git a/doc/references/CommandReference.rst b/doc/references/CommandReference.rst
index 2d7dc491a..3816afe42 100644
--- a/doc/references/CommandReference.rst
+++ b/doc/references/CommandReference.rst
@@ -20,7 +20,7 @@ There are a few GHDL commands which are seldom useful.
 
 .. index:: cmd help
 
-Help [:samp:`-h`]
+Help [``-h``]
 -----------------
 
 .. option:: --help, -h
@@ -35,7 +35,7 @@ for this later command are displayed::
 
 .. index:: cmd display configuration
   
-Display config [:samp:`--disp-config`]
+Display config [``--disp-config``]
 --------------------------------------
 
 .. option:: --disp-config <[options]>
@@ -43,18 +43,18 @@ Display config [:samp:`--disp-config`]
 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`
+.. index:: display ``std.standard``
 
-Display standard [:samp:`--disp-standard`]
+Display standard [``--disp-standard``]
 ------------------------------------------
 
 .. option:: --disp-standard <[options]>
 
-Display the :samp:`std.standard` package.
+Display the ``std.standard`` package.
 
 .. index:: cmd version
 
-Version [:samp:`--version`]
+Version [``--version``]
 ---------------------------
 
 .. option:: --version, -v
@@ -69,7 +69,7 @@ The following commands act on one or several files. These are not analyzed, ther
 .. index:: cmd file pretty printing
 .. index:: vhdl to html
 
-Pretty print [:samp:`--pp-html`]
+Pretty print [``--pp-html``]
 --------------------------------
 
 .. option:: --pp-html <[options] file...>
@@ -83,7 +83,7 @@ The style of the html file can be modified with the :option:`--format=` option:
 
 .. index:: cmd file find
 
-Find [:samp:`-f`]
+Find [``-f``]
 -----------------
 
 .. option:: -f <file...>
@@ -92,7 +92,7 @@ The files are scanned, parsed and the names of design units are displayed. Desig
 
 .. index:: cmd file chop
 
-Chop [:samp:`--chop`]
+Chop [``--chop``]
 ---------------------
 
 .. option:: --chop <files...>
@@ -111,7 +111,7 @@ This command may be useful to split big files, if your computer has not enough m
 
 .. index:: cmd file lines
 
-Lines [:samp:`--lines`]
+Lines [``--lines``]
 -----------------------
 
 .. option:: --lines <files...>
@@ -123,7 +123,7 @@ GCC/LLVM only commands
 
 .. index:: cmd GCC/LLVM binding
 
-Bind [:samp:`--bind`]
+Bind [``--bind``]
 ---------------------
 
 .. option:: --bind <[options] primary_unit [secondary_unit]>
@@ -132,7 +132,7 @@ Performs only the first stage of the elaboration command; the list of objects fi
 
 .. index:: cmd GCC/LLVM linking
 
-Link [:samp:`--link`]
+Link [``--link``]
 ---------------------
 
 .. option:: --link <[options] primary_unit [secondary_unit]>
@@ -141,7 +141,7 @@ Performs only the second stage of the elaboration command: the executable is cre
 
 .. index:: cmd GCC/LLVM list link
 
-List link [:samp:`--list-link`]
+List link [``--list-link``]
 -------------------------------
 
 .. option:: --list-link <primary_unit [secondary_unit]>
@@ -167,15 +167,15 @@ This option is only useful during elaboration.
 
 .. 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 ``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 :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 ``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 :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 ``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
 =================================
diff --git a/doc/references/ImplementationOfVHDL.rst b/doc/references/ImplementationOfVHDL.rst
index 8eaa04a81..66246608d 100644
--- a/doc/references/ImplementationOfVHDL.rst
+++ b/doc/references/ImplementationOfVHDL.rst
@@ -72,7 +72,7 @@ The latest version is 2008.  Many features have been added, and GHDL
 doesn't implement all of them.
 
 You can select the VHDL standard expected by GHDL with the
-:samp:`--std=VER` option, where :samp:`VER` is one of the left column of the
+``--std=VER`` option, where ``VER`` is one of the left column of the
 table below:
 
 
@@ -176,7 +176,7 @@ Library database
 ================
 
 Each design unit analyzed is placed into a design library.  By default,
-the name of this design library is :samp:`work`; however, this can be
+the name of this design library is ``work``; however, this can be
 changed with the :option:`--work=NAME` option of GHDL.
 
 To keep the list of design units in a design library, GHDL creates
@@ -255,7 +255,7 @@ attribute.  In this example, the `sin` function is imported:
 
 A subprogram is made foreign if the `foreign` attribute decorates
 it.  This attribute is declared in the 1993 revision of the
-:samp:`std.standard` package.  Therefore, you cannot use this feature in
+``std.standard`` package.  Therefore, you cannot use this feature in
 VHDL 1987.
 
 The decoration is achieved through an attribute specification.  The
@@ -266,7 +266,7 @@ The value of the specification must be a locally static string.
 Even when a subprogram is foreign, its body must be present.  However, since
 it won't be called, you can made it empty or simply but an assertion.
 
-The value of the attribute must start with :samp:`VHPIDIRECT` (an
+The value of the attribute must start with ``VHPIDIRECT`` (an
 upper-case keyword followed by one or more blanks).  The linkage name of the
 subprogram follows.
 
@@ -340,7 +340,7 @@ Starting a simulation from a foreign program
 --------------------------------------------
 
 You may run your design from an external program.  You just have to call
-the :samp:`ghdl_main` function which can be defined:
+the ``ghdl_main`` function which can be defined:
 
 in C:
 
@@ -380,7 +380,7 @@ suppose there is only one design file, :file:`design.vhdl`.
   $ ghdl -a design.vhdl
 
 Then, bind your design.  In this example, we suppose the entity at the
-design apex is :samp:`design`.
+design apex is ``design``.
 
 ::
 
diff --git a/doc/using/InvokingGHDL.rst b/doc/using/InvokingGHDL.rst
index ceb25b1a6..0bfa2d969 100644
--- a/doc/using/InvokingGHDL.rst
+++ b/doc/using/InvokingGHDL.rst
@@ -4,23 +4,23 @@
 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 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.
 
 .. 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).
+   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::
    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):
+   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):
 
 	* 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 it corresponds to 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 ``HKLM\Software\Ghdl\Install_Dir`` registry entry on Windows.
 
 	You should use the :option:`--disp-config` command to display and debug installation problems.
 
@@ -32,19 +32,19 @@ The mostly used commands of GHDL are those to analyze and elaborate a design.
 
 .. index:: cmd analysis
 
-Analysis [:samp:`-a`]
+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).
 
-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`.
+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
 
-Elaboration [:samp:`-e`]
+Elaboration [``-e``]
 ------------------------
 
 .. option:: -e <[options...] primary_unit [secondary_unit]>
@@ -66,7 +66,7 @@ Name of the units must be a simple name, without any dot.  You can select the na
 
 .. index:: cmd run
  
-Run [:samp:`-r`]
+Run [``-r``]
 ----------------
 
 .. option:: -r <[options...] primary_unit [secondary_unit] [simulation_options...]>
@@ -87,7 +87,7 @@ See section ':ref:`USING:Simulation`', for details on options.
 
 .. index:: cmd elaborate and run
 
-Elaborate and run [:samp:`--elab-run`]
+Elaborate and run [``--elab-run``]
 --------------------------------------
 
 .. option:: --elab-run <[elab_options...] primary_unit [secondary_unit] [run_options...]>
@@ -97,7 +97,7 @@ Acts like the elaboration command (see :option:`-e`) followed by the run command
 
 .. index:: cmd checking syntax
 
-Check syntax [:samp:`-s`]
+Check syntax [``-s``]
 -------------------------
 
 .. option:: -s <[options] files>
@@ -107,7 +107,7 @@ Analyze files but do not generate code. This command may be used to check the sy
 
 .. index:: cmd analyze and elaborate
 
-Analyze and elaborate [:samp:`-c`]
+Analyze and elaborate [``-c``]
 ----------------------------------
 
 .. option:: -c <[options] file... -<e|r> primary_unit [secondary_unit]>
@@ -127,7 +127,7 @@ The advantages over the traditional approach (analyze and then elaborate) are:
 * 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.
+   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 ``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.
@@ -141,7 +141,7 @@ Analyzing and elaborating a design consisting in several files can be tricky, du
 
 .. index:: cmd importing files
 
-Import [:samp:`-i`]
+Import [``-i``]
 -------------------
 
 .. option:: -i <[options] file...>
@@ -158,12 +158,12 @@ See :option:`-m`, to actually build the design.
 
 .. index:: cmd make
 
-Make [:samp:`-m`]
+Make [``-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.
+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 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).
@@ -181,7 +181,7 @@ This is not perfect, since the default architecture (the most recently analyzed
 
 .. index:: cmd generate makefile
 
-Generate Makefile [:samp:`--gen-makefile`]
+Generate Makefile [``--gen-makefile``]
 ------------------------------------------
 
 .. option:: --gen-makefile <[options] primary [secondary]>
@@ -203,21 +203,21 @@ Options
 
 .. 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 ``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 :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 ``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 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 ``std`` library. Furthermore, you should not put units in the ``ieee`` library.
 
 .. 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 ``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` to specify where libraries other than :samp:`WORK` are placed.
+  Use option :option:`-P` to specify where libraries other than ``WORK`` are placed.
 
 .. 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 section ':ref:`VHDL_standards`'.
+  Specify the standard to use.  By default, the standard is ``93c``, which means VHDL-93 accepting VHDL-87 syntax.  For details on ``STD`` values see section ':ref:`VHDL_standards`'.
 
 .. option:: --ieee<=VER>
 
@@ -225,35 +225,35 @@ Options
   .. index:: synopsys library
   .. index:: mentor library
 
-  Select the :samp:`IEEE` library to use. :samp:`VER` must be one of:
+  Select the ``IEEE`` library to use. ``VER`` must be one of:
 
   none
-    Do not supply an `IEEE` library.  Any library clause with the :samp:`IEEE`
+    Do not supply an `IEEE` library.  Any library clause with the ``IEEE``
     identifier will fail, unless you have created by your own a library with
     the `IEEE` name.
 
   standard
     Supply an `IEEE` library containing only packages defined by
-    :samp:`ieee` standards.  Currently, there are the multivalue logic system
-    packages :samp:`std_logic_1164` defined by IEEE 1164, the synthesis
-    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
+    ``ieee`` standards.  Currently, there are the multivalue logic system
+    packages ``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
     Supply the former packages and the following additional packages:
-    :samp:`std_logic_arith`, :samp:`std_logic_signed`,
-    :samp:`std_logic_unsigned`, :samp:`std_logic_textio`.
+    ``std_logic_arith``, ``std_logic_signed``,
+    ``std_logic_unsigned``, ``std_logic_textio``.
 
     These 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 :samp:`ieee`.
+    library without the permission from the ``ieee``.
 
   mentor
     Supply the standard packages and the following additional package:
-    :samp:`std_logic_arith`.  The package is a slight variation of a definitely
+    ``std_logic_arith``.  The package is a slight variation of a definitely
     not standard but widely mis-used package.
 
   To avoid errors, you must use the same `IEEE` library for all units of
@@ -273,10 +273,10 @@ Options
 .. 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`
+  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 better fix your design and use the :samp:`numeric_std` package.
+.. 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 ``numeric_std`` package.
 
 .. option:: -frelaxed-rules
 
@@ -295,7 +295,7 @@ Options
 
   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 ``state1`` constant start at the `constant` word. Because the constant ``state1`` and the enumeration literal ``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.
 
@@ -308,13 +308,13 @@ Options
 
   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 ``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.
 
 .. option:: --PREFIX<=PATH>
 
-  Use :file:`PATH` as the prefix path to find commands and pre-installed (:samp:`std` and :samp:`ieee`) libraries.
+  Use :file:`PATH` as the prefix path to find commands and pre-installed (``std`` and ``ieee``) libraries.
 
 .. option:: -v
 
@@ -327,7 +327,7 @@ 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`.
+   You could disable a warning by using the ``--warn-no-XXX`` or ``-Wno-XX`` instead of ``--warn-XXX`` or ``-WXXX``.
 
 .. option:: --warn-reserved
 
@@ -376,7 +376,7 @@ Some constructions are not erroneous but dubious. Warnings are diagnostic messag
 
 .. option:: --warn-nested-comment
 
-  Emit a warning if a :samp:`/*` appears within a block comment (vhdl 2008).
+  Emit a warning if a ``/*`` appears within a block comment (vhdl 2008).
 
 .. option:: --warn-parenthesis
 
@@ -408,26 +408,26 @@ 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 new library is created implicitly, by compiling entities (packages etc.) into it: ``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` 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.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`]
+Directory [``--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`.
+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
 
-Clean [:samp:`--clean`]
+Clean [``--clean``]
 -----------------------
 
 .. option:: --clean <[options]>
@@ -437,7 +437,7 @@ Try to remove any object, executable or temporary file it could have created. So
 
 .. index:: cmd library remove
 
-Remove [:samp:`--remove`]
+Remove [``--remove``]
 -------------------------
 
 .. option:: --remove <[options]>
@@ -448,12 +448,12 @@ known anymore by GHDL.
 
 .. index:: cmd library copy
 
-Copy [:samp:`--copy`]
+Copy [``--copy``]
 ---------------------
 
 .. 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:
+Make a local copy of an existing library.  This is very useful if you want to add unit to the ``ieee`` library:
 
 .. code-block:: shell
 
@@ -470,7 +470,7 @@ command before its execution.
 
 .. index:: cmd VPI compile
 
-compile [:samp:`--vpi-compile`]
+compile [``--vpi-compile``]
 -------------------------------
 
 .. option:: --vpi-compile <command>
@@ -495,7 +495,7 @@ executes::
 
 .. index:: cmd VPI link
 
-link [:samp:`--vpi-link`]
+link [``--vpi-link``]
 -------------------------
 
 .. option:: --vpi-link <command>
@@ -521,7 +521,7 @@ executes::
 
 .. index:: cmd VPI cflags
 
-cflags [:samp:`--vpi-cflags`]
+cflags [``--vpi-cflags``]
 -----------------------------
 
 .. option:: --vpi-cflags
@@ -530,7 +530,7 @@ Display flags added by :option:`--vpi-compile`.
 
 .. index:: cmd VPI ldflags
 
-ldflags [:samp:`--vpi-ldflags`]
+ldflags [``--vpi-ldflags``]
 -------------------------------
 
 .. option:: --vpi-ldflags
@@ -539,7 +539,7 @@ Display flags added by :option:`--vpi-link`.
 
 .. index:: cmd VPI include dir
 
-include dir [:samp:`--vpi-include-dir`]
+include dir [``--vpi-include-dir``]
 ---------------------------------------
 
 .. option:: --vpi-include-dir
@@ -548,7 +548,7 @@ Display the include directory added by the compile flags.
 
 .. index:: cmd VPI library dir
 
-library dir [:samp:`--vpi-library-dir`]
+library dir [``--vpi-library-dir``]
 ---------------------------------------
 
 .. option:: --vpi-library-dir
@@ -561,7 +561,7 @@ Display the library directory added by the link flags.
 IEEE library pitfalls
 =====================
 
-When you use options :option:`--ieee=synopsys` or :option:`--ieee=mentor`, the :samp:`ieee` library contains non standard packages such as :samp:`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, their use has pitfalls. For example, this description has error during compilation:
+When you use options :option:`--ieee=synopsys` or :option:`--ieee=mentor`, 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, their use has pitfalls. For example, this description has error during compilation:
 
 .. code-block:: VHDL
 
@@ -677,4 +677,4 @@ 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.
+   The ``ieee`` math packages (``math_real`` and ``math_complex``) provided with `GHDL` are fully compliant with the `IEEE` standard.
diff --git a/doc/using/QuickStartGuide.rst b/doc/using/QuickStartGuide.rst
index f61a86d5d..b390b382e 100644
--- a/doc/using/QuickStartGuide.rst
+++ b/doc/using/QuickStartGuide.rst
@@ -33,12 +33,12 @@ To illustrate the large purpose of `VHDL`, here is a commented `'Hello world'` p
 
 .. TIP::
 
-   * Both :samp:`.vhdl` and :samp:`.vhd` extensions are used for VHDL source files, while :samp:`.v` is used for Verilog.
+   * Both ``.vhdl`` and ``.vhd`` extensions are used for VHDL source files, while ``.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:
+- First, you have to compile the file; this is called `analysis` of a design file in `VHDL` terms. Run ``ghdl -a hello.vhdl`` in the `shell`. This command creates or updates a file :file:`work-obj93.cf`, which describes the library ``work``.
+- Then, run ``ghdl -e hello_world`` in the `shell`. Option :option:`-e` means :dfn:`elaborate`, which is used to build a design, with the ``hello_world`` entity at the top of the hierarchy.
+- Last, you can directly launch the simulation running ``ghdl -r hello_world`` in the `shell`. The result of the simulation will be shown on screen:
 
 .. code-block:: shell
 
@@ -49,7 +49,7 @@ To illustrate the large purpose of `VHDL`, here is a commented `'Hello world'` p
 
    * `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.
+   * As a result, :option:`-r` is just a passthrough to the binary generated in the `elaboration`. Therefore, the executable can be run directly, ``./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.
 
@@ -96,7 +96,7 @@ VHDL is generally used for hardware design.  This example starts with a `full ad
       co <= (i0 and i1) or (i0 and ci) or (i1 and ci);
    end rtl;
 
-You can analyze this design file, :samp:`ghdl -a adder.vhdl`, and try to execute the `adder` design. But this is useless, since nothing externally visible will happen. In order to check this full adder, a :dfn:`testbench` has to be run. This testbench is very simple, since the adder is also simple: it checks exhaustively all inputs.  Note that only the behaviour is tested, timing constraints are not checked. A file named :file:`adder_tb.vhdl` contains the testbench for the adder:
+You can analyze this design file, ``ghdl -a adder.vhdl``, and try to execute the `adder` design. But this is useless, since nothing externally visible will happen. In order to check this full adder, a :dfn:`testbench` has to be run. This testbench is very simple, since the adder is also simple: it checks exhaustively all inputs.  Note that only the behaviour is tested, timing constraints are not checked. A file named :file:`adder_tb.vhdl` contains the testbench for the adder:
 
 .. code-block:: VHDL
 
@@ -159,18 +159,18 @@ You can analyze this design file, :samp:`ghdl -a adder.vhdl`, and try to execute
    end behav;
 
 
-As usual, you should analyze the design, :samp:`ghdl -a adder_tb.vhdl`.
+As usual, you should analyze the design, ``ghdl -a adder_tb.vhdl``.
 
 .. HINT::
-   Then, if required, elaborate the testbench: :samp:`ghdl -e adder_tb`. You do not need to specify which object files are required, since GHDL knows them and automatically adds them.
+   Then, if required, elaborate the testbench: ``ghdl -e adder_tb``. You do not need to specify which object files are required, since GHDL knows them and automatically adds them.
 
-Now, it is time to run the testbench, :samp:`ghdl -r adder_tb`, and check the result on screen::
+Now, it is time to run the testbench, ``ghdl -r adder_tb``, and check the result on screen::
 
   adder_tb.vhdl:52:7:(assertion note): end of test
 
 If your design is rather complex, you'd like to inspect signals. Signal values can be dumped using multiple formats (see section ':ref:`export_waves`' for more information). The resulting file can be read with a wave viewer such as `GtkWave <http://gtkwave.sourceforge.net/>`_.
 
-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`.
+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: ``ghdl -r adder_tb --vcd=adder.vcd``. Then, you can view the dump: ``gtkwave adder.vcd``.
 
 See section ':ref:`simulation_options`', for more details on other runtime options.
 
@@ -179,7 +179,7 @@ Starting with a design
 
 Unless you are only studying VHDL, you will work with larger designs than the ones of the previous examples. Let's see how to analyze and run a bigger design, such as the DLX model suite written by Peter Ashenden which is distributed under the terms of the GNU General Public License. A copy is kept on `ghdl.free.fr/dlx.tar.gz <http://ghdl.free.fr/dlx.tar.gz>`_ .
 
-- First, untar the sources: :samp:`tar zxvf dlx.tar.gz`.
+- First, untar the sources: ``tar zxvf dlx.tar.gz``.
 
 .. HINT:: In order not to pollute the sources with the library, it is a good idea to create a :file:`work/` subdirectory for the `WORK` library.  To any GHDL commands, we will add the :option:`--workdir=work` option, so that all files generated by the compiler (except the executable) will be placed in this directory.
 
@@ -188,20 +188,20 @@ Unless you are only studying VHDL, you will work with larger designs than the on
      $ cd dlx
      $ mkdir work
 
-* Then, we will run the :samp:`dlx_test_behaviour` design.  We need to analyze all the design units for the design hierarchy, in the correct order. GHDL provides an easy way to do this, by importing the sources, :samp:`ghdl -i --workdir=work *.vhdl`.
+* Then, we will run the ``dlx_test_behaviour`` design.  We need to analyze all the design units for the design hierarchy, in the correct order. GHDL provides an easy way to do this, by importing the sources, ``ghdl -i --workdir=work *.vhdl``.
 
-* GHDL knows all the design units of the DLX, but no one have been analyzed. Run the make option, :samp:`ghdl -m --workdir=work dlx_test_behaviour`, which analyzes and elaborates a design. This creates many files in the :file:`work/` directory, and (GCC/LLVM only) the :file:`dlx_test_behaviour` executable in the current directory.
+* GHDL knows all the design units of the DLX, but no one have been analyzed. Run the make option, ``ghdl -m --workdir=work dlx_test_behaviour``, which analyzes and elaborates a design. This creates many files in the :file:`work/` directory, and (GCC/LLVM only) the :file:`dlx_test_behaviour` executable in the current directory.
 
-.. HINT:: The simulation needs to have a DLX program contained in the file :file:`dlx.out`. This memory image will be loaded in the DLX memory. Just take one sample: :samp:`cp test_loop.out dlx.out`.
+.. HINT:: The simulation needs to have a DLX program contained in the file :file:`dlx.out`. This memory image will be loaded in the DLX memory. Just take one sample: ``cp test_loop.out dlx.out``.
 
-* Now, you can run the test suite: :samp:`ghdl -r --workdir=work dlx_test_behaviour`. The test bench monitors the bus and displays each instruction executed. It finishes with an assertion of severity level note:
+* Now, you can run the test suite: ``ghdl -r --workdir=work dlx_test_behaviour``. The test bench monitors the bus and displays each instruction executed. It finishes with an assertion of severity level note:
 
   .. code-block:: shell
 
      dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction
       encountered, execution halted
 
-* Last, since the clock is still running, you have to manually stop the program with the :kbd:`C-c` key sequence.  This behavior prevents you from running the test bench in batch mode. However, you may force the simulator to stop when an assertion above or equal a certain severity level occurs. To do so, call run with this option instead: :samp:`ghdl -r --workdir=work dlx_test_behaviour --assert-level=note``. With this option, the program stops just after the previous message:
+* Last, since the clock is still running, you have to manually stop the program with the :kbd:`C-c` key sequence.  This behavior prevents you from running the test bench in batch mode. However, you may force the simulator to stop when an assertion above or equal a certain severity level occurs. To do so, call run with this option instead: ``ghdl -r --workdir=work dlx_test_behaviour --assert-level=note```. With this option, the program stops just after the previous message:
 
   .. code-block:: shell
 
@@ -211,8 +211,18 @@ Unless you are only studying VHDL, you will work with larger designs than the on
 
 .. TIP:: If you want to make room on your hard drive, you can either:
 
-   * Clean the design library with the GHDL command :samp:`ghdl --clean --workdir=work`. This removes the executable and all the object files. If you want to rebuild the design at this point, just do the make command as shown above.
-   * Remove the design library with the GHDL command :samp:`ghdl --remove --workdir=work`. This removes the executable, all the object files and the library file. If you want to rebuild the design, you have to import the sources again, and to make the design.
-   * 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.
+   * Clean the design library with the GHDL command ``ghdl --clean --workdir=work``. This removes the executable and all the object files. If you want to rebuild the design at this point, just do the make command as shown above.
+   * Remove the design library with the GHDL command ``ghdl --remove --workdir=work``. This removes the executable, all the object files and the library file. If you want to rebuild the design, you have to import the sources again, and to make the design.
+   * Remove the :file:`work/` directory: ``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 section ':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 ``std_logic_unsigned`` package. GHDL supports this VHDL dialect through some options: ``--ieee=synopsys -fexplicit``. See section ':ref:`IEEE_library_pitfalls`', for more details.
+
+Further examples
+=======================
+
+.. TODO::
+
+  * Add references to examples/tutorials with GHDL.
+  * Shall `René Doß <https://mail.gna.org/public/ghdl-discuss/2017-01/msg00000.html>` want to contribute adapting his article to RST?
+  * https://github.com/Obijuan/open-fpga-verilog-tutorial/wiki
+>>>>>>> doc/changelog renamed to doc/appendix
diff --git a/doc/using/Simulation.rst b/doc/using/Simulation.rst
index 5945588df..968849ee7 100644
--- a/doc/using/Simulation.rst
+++ b/doc/using/Simulation.rst
@@ -20,8 +20,8 @@ could do it through the generics interfaces of the top entity.
 However, the GHDL runtime behaviour can be modified with some options; for
 example, it is possible to stop simulation after a certain time.
 
-The exit status of the simulation is :samp:`EXIT_SUCCESS` (0) if the
-simulation completes, or :samp:`EXIT_FAILURE` (1) in case of error
+The exit status of the simulation is ``EXIT_SUCCESS`` (0) if the
+simulation completes, or ``EXIT_FAILURE`` (1) in case of error
 (assertion failure, overflow or any constraint error).
 
 Here is the list of the most useful options.  Some debugging options are
@@ -33,14 +33,14 @@ all options available, including the debugging one.
   Select the assertion level at which an assertion violation stops the
   simulation.  `LEVEL` is the name from the `severity_level`
   enumerated type defined in the `standard` package or the
-  :samp:`none` name.
+  ``none`` name.
 
-  By default, only assertion violation of severity level :samp:`failure`
+  By default, only assertion violation of severity level ``failure``
   stops the simulation.
 
-  For example, if `LEVEL` was :samp:`warning`, any assertion violation
-  with severity level :samp:`warning`, :samp:`error` or :samp:`failure` would
-  stop simulation, but the assertion violation at the :samp:`note` severity
+  For example, if `LEVEL` was ``warning``, any assertion violation
+  with severity level ``warning``, ``error`` or ``failure`` would
+  stop simulation, but the assertion violation at the ``note`` severity
   level would only display a message.
 
   Option :option:`--assert-level=none` prevents any assertion violation to stop
@@ -48,17 +48,17 @@ all options available, including the debugging one.
 
 .. option:: --ieee-asserts<=POLICY>
 
-  Select how the assertions from :samp:`ieee` units are
-  handled. `POLICY` can be :samp:`enable` (the default),
-  :samp:`disable` which disables all assertion from :samp:`ieee` packages
-  and :samp:`disable-at-0` which disables only at start of simulation.
+  Select how the assertions from ``ieee`` units are
+  handled. `POLICY` can be ``enable`` (the default),
+  ``disable`` which disables all assertion from ``ieee`` packages
+  and ``disable-at-0`` which disables only at start of simulation.
 
   This option can be useful to avoid assertion message from
-  :samp:`ieee.numeric_std` (and other :samp:`ieee` packages).
+  ``ieee.numeric_std`` (and other ``ieee`` packages).
 
 .. option:: --stop-time<=TIME>
 
-  Stop the simulation after :samp:`TIME`.  :samp:`TIME` is expressed as a time
+  Stop the simulation after ``TIME``.  ``TIME`` is expressed as a time
   value, *without* any space.  The time is the simulation time, not
   the real clock time.
 
@@ -85,7 +85,7 @@ all options available, including the debugging one.
 
   Do VITAL annotation on `PATH` with SDF file :file:`FILENAME`.
 
-  `PATH` is a path of instances, separated with :samp:`.` or :samp:`/`.
+  `PATH` is a path of instances, separated with ``.`` or ``/``.
   Any separator can be used.  Instances are component instantiation labels,
   generate labels or block labels.  Currently, you cannot use an indexed name.
 
@@ -95,8 +95,8 @@ all options available, including the debugging one.
    --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,
+  If the option contains a type of delay, that is ``min=``,
+  ``typ=`` or ``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.
 
@@ -161,13 +161,13 @@ Export waveforms
   .. index:: dump of signals
 
   Option :option:`--vcd` dumps into the VCD file `FILENAME` the signal
-  values before each non-delta cycle.  If `FILENAME` is :samp:`-`,
+  values before each non-delta cycle.  If `FILENAME` is ``-``,
   then the standard output is used, otherwise a file is created or
   overwritten.
 
   The :option:`--vcdgz` option is the same as the *--vcd* option,
   but the output is compressed using the `zlib` (`gzip`
-  compression).  However, you can't use the :samp:`-` filename.
+  compression).  However, you can't use the ``-`` filename.
   Furthermore, only one VCD file can be written.
 
   :dfn:`VCD` (value change dump) is a file format defined
@@ -176,21 +176,21 @@ Export waveforms
   Since it comes from `verilog`, only a few VHDL types can be dumped.  GHDL
   dumps only signals whose base type is of the following:
 
-  * types defined in the :samp:`std.standard` package:
+  * types defined in the ``std.standard`` package:
 
-  * :samp:`bit`
+  * ``bit``
 
-  * :samp:`bit_vector`
+  * ``bit_vector``
 
-  * types defined in the :samp:`ieee.std_logic_1164` package:
+  * types defined in the ``ieee.std_logic_1164`` package:
 
-  * :samp:`std_ulogic`
+  * ``std_ulogic``
 
-  * :samp:`std_logic` (because it is a subtype of :samp:`std_ulogic`)
+  * ``std_logic`` (because it is a subtype of ``std_ulogic``)
 
-  * :samp:`std_ulogic_vector`
+  * ``std_ulogic_vector``
 
-  * :samp:`std_logic_vector`
+  * ``std_logic_vector``
 
   * any integer type
 
@@ -220,7 +220,7 @@ Export waveforms
   of signals to be dumped.
 
   The format of this file was defined by myself and is not yet completely fixed.
-  It may change slightly.  The :samp:`gtkwave` tool can read the GHW files.
+  It may change slightly.  The ``gtkwave`` tool can read the GHW files.
 
   Contrary to VCD files, any VHDL type can be dumped into a GHW file.
  
@@ -248,12 +248,12 @@ Export hierarchy and references
     Display entities, architectures, instances, blocks and generates statements.
 
   * proc
-    Like :samp:`inst` but also display processes.
+    Like ``inst`` but also display processes.
 
   * port
-    Like :samp:`proc` but display ports and signals too.
+    Like ``proc`` but display ports and signals too.
     If `KIND` is not specified, the hierarchy is displayed with the
-    :samp:`port` mode.
+    ``port`` mode.
 
 .. option:: --no-run
 
@@ -261,9 +261,9 @@ Export hierarchy and references
 
 .. 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.
+To easily navigate through your sources, you may generate cross-references. This command generates an html file for each ``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.
+The set of ``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.
 
@@ -336,7 +336,7 @@ Dump Run Time Information (RTI).
 
 .. option:: --bootstrap
 
-Allow :samp:`--work=std`
+Allow ``--work=std``
 
 GNU Debugger (GDB)
 ------------------
@@ -347,8 +347,8 @@ GNU Debugger (GDB)
 
 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 :samp:`__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 ``__ghdl_fatal`` procedure. Therefore, to catch runtime error, set a breakpoint like this::
 
   (gdb) break __ghdl_fatal
 
-When the breakpoint is hit, use the :samp:`where` or :samp:`bt` command to display the stack frames.
+When the breakpoint is hit, use the ``where`` or ``bt`` command to display the stack frames.