README.md, index, WhatIsVHDL, WhatIsGHDL ready for review.

Add shortcuts for shields in a single file and include it where used.
Create base64 GitHub and Travis-CI logos with b64.io and add them to self-created shields. Replace gitter with shield.io's variant.
Start rewriting <Contributing>

README.md

@@ -1,6 +1,5 @@
-[![Documentation Status](https://readthedocs.org/projects/ghdl/badge/?version=latest)](http://ghdl.readthedocs.io/en/latest/?badge=latest) [![Join the chat at https://gitter.im/ghdl1/Lobby](https://badges.gitter.im/ghdl1/Lobby.svg)](https://gitter.im/ghdl1/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
-
-[![Linux containers at Travis-CI](https://travis-ci.org/tgingold/ghdl.svg?branch=master)](https://travis-ci.org/tgingold/ghdl) [![Windows VMs at AppVeyor](https://ci.appveyor.com/api/projects/status/rsq60m5wcly3og8j?svg=true)](https://ci.appveyor.com/project/tgingold/ghdl) ![Latest tag](https://img.shields.io/github/tag/tgingold/ghdl.svg?style=flat) [![Latest release](https://img.shields.io/github/release/tgingold/ghdl.svg?style=flat)](https://github.com/tgingold/ghdl/releases)
+[![Documentation Status](https://readthedocs.org/projects/ghdl/badge/?version=latest)](http://ghdl.readthedocs.io/en/latest/?badge=latest) [![Join the chat at https://gitter.im/ghdl1/Lobby](https://img.shields.io/gitter/room/ghdl1/Lobby.svg?colorB=4cb696)](https://gitter.im/ghdl1/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![GNU General Public License 2](https://img.shields.io/badge/code%20license-GPLv2-bd0000.svg?style=flat)](https://github.com/tgingold/ghdl/blob/master/COPYING.md) [![Creative Commons Attribution-ShareAlike](https://img.shields.io/badge/doc%20license-CC--BY--SA-aab2ab.svg?style=flat)](https://github.com/tgingold/ghdl/blob/master/COPYING.md)  
+[![Linux containers at Travis-CI](https://img.shields.io/travis/tgingold/ghdl/master.svg?style=flat&logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAIP0lEQVR42qVXaUyUWRaFycyP%2BTVLemaSSfrPJN3JZJKOPyY6uBLTQgGlUMVeFHuxFaioKGpcAFFQUaOigAsmo7ghikZtxZVFCCKgqOi4ICoqqLjghqjcOeem%2B5sQFZnuL3l5VV%2B9d%2B9595577iuX%2F%2FcZNWrUX7y8vMyJiYmbpk6d2pKamto5bdq0LnxuT05OPhgUFOQcOXLkP35a7%2Bvr6%2FKLnmXLlun87t27X02YMKFkzpw5va2trXL37l158OCBPHz4UEdXV5fcu3dPbt26Jdu3b%2B%2Fz8%2FNrM5vNf%2BNeAPxlIHAi06xZs7rOnj0rL168kPb2dnn8%2BLE8evToo0EgHPfv35e1a9cKQOT9LKc2m03nyMhIv%2FXr18uzZ8%2F0pDU1NXLz5k0xTzSLycs0cHibBClhBOTJkycKqKmpSZCyGkTv10N27unpqfPw4cNDSkpK5OrVqzSmAHbu3CnXr1%2BXhIQECQkNkeCQYHEkxAPQRHEmJ0taWposWbJEOjs7dX1bW5s0NjYyEtW0OXny5KGBMJlMf1ixYsUHOqYRGmPYi4qK5PLly5KUlCSLFi0S5FqCAaSutk6io6MlMzNTtmzZIkwX9zASdXV10tLSQhALaRtEHdy5iLhYrdbbP53gxo0baqy7u1tWrlxJAErA7sfdYrFYNBINZxv0XUdHh5SXl8uhQ4eMPbW1tfqZqQwODv7rF0%2F%2FPZ6GhoZ%2B5v3AgQNKqqdPnyoBly9fztMxJeSFAeDcuXN8p9Wxf%2F9%2BBfH8%2BXMFcP78eSMlWN%2F8SafDhg0zPqOmG2%2Ffvi137tzRkF%2B6dEny8vLE399fUA1y%2BvRpGtMT%2B1n8JMQWKhUVFQTKiKlzkE7XHjlyRJqbm7lWI3n06NG%2B0aNHfzvAOVDq7Obm9mcIzIbS0lK5cuWKVFVVyerVq2Xv3r2aw5kzZ0pubq6cOnWKNa8njYyKlKRkpyBlPL2yPiUlhfzQVJ04cUI2bdrE1CmI%2Bvp6Wbp06bkRI0ZYBoAA4u9JIIAxGL9jxw5GgeRjCjT8GzdulM2bN2s5btu2TcJsNgmz2yU8IkIBHz58WIm4atUq6enpoS21iagyJbTL1BEYQe8zALi7u%2BdiAxcYg8iZd4a2srJST%2B9wOMTb25tk0gqYiPLjmDRpkkYhJCRE4uPjBeUmBw8e1JJ9%2Ffo108GDGLYJJjw8XAwAY8eOzedLIuZCkoY1Tzbv2rVLEV%2B4cIE5NpSOPCHrORh%2BpoX7GDVqx5kzZ2Tfvn2yZ88eVUVKOG1zMAoRiJoBADnJpEHmiMTh5prqaimHgeLiYs2p0%2BkkETUCXt5eUD8dVDod0A7OjIhGYcGCBVJQUCBlZWVMD21yZjQ1Aj4%2BPv8DMGbMmDCemDJKR%2BPGjRNfhNgeES7hkREML0tIAfiYzWK3h6kA2TBjPUNMkPjdKgmJiRIHdXTEIV0%2B3poWdEqBrGvYs7Oz5dixY0zhfwwAULGvwsLCVMvt4XaJdcRKQlIinahTdEE60FxDyQDOl1Whsrt48WI1Ghpqkxjso3OSkpGaN2%2Be5OfnGwNiRBUlSQnMNqAScEpvi9UiMbGxgj4uqFcl2ty5c2XGjBn6vbCwkGlibbM0WWpaEdAurX0eonhLMbmjJM7JyWFZ0h4JrLYCAwM%2FIJpRsOPqAlTqHPX%2FDXKHU4T2BAYFfsAirQA%2B1HNupNo1NTeR1RzqnJrBCGVkZGiX5MO%2BsBm86evrE9wjpL%2B%2Fn6%2B1R0yfPp0cqfxICRGuDoweEKkxJiaGZaSsfvnypTK8EyLCfK4tLEClPKQ9rqFCsu45U%2FO19gODgmXm7NkQsDICpQ0dGzZsoLBRP%2FrHjx%2F%2Fb5gwnFeDkeunTJnye7J0zZo1zB1DrBtfvXql9ezp4SFubv8Ci09rmeGmQxAsNQWB2xMdajpGurmRI4Zz2KBdKiJ1gNVyLC4uztUFOR6NcJsJBMz%2FHUrwPRWQqnfy5EluplHKL0nIk%2FIdDWl%2Bjx8%2FLu%2Ffv9eajgV33rx5w9Qoy69du8Zy43qt%2B6ysLA7VDcj%2BVj09yuMbzgDBLvhb3AHuV1ZWybp168h8CpPm8O3bt4IOSSlWIwsXLmQFkB%2FMNVlNpSQXWBX8TcO9detW2b17t8yfP5%2BVwshSrlnmjoEXTwWT4moyeda0tl6mkGhIESYC4elY6zCcg%2Fe5MDhPAJZEZYSUgLORd4Cjc%2B4FoBxGjaCQogyWMEVIbYP0f%2FzMXWD8KKvV8i4gIOA8ygcLEzhQQrEwvBgdsBzt%2BSLCeJcRYYulLCvDS3eXwvFSSO4lKF4l0lCB0%2B9CNPORqgpwIq3Fw8PDirT%2F8xOuSUbTgO%2FZ2Yva6uvr0GIb0UrvoSM%2B0ZGenk6RgSL6yAQQc5y7u5ghq%2F4BARJqs1ELlAe9vb1IUTd7B%2FZ3Qaq9nHDugVI3D3YdcwWzv0Y5uqI%2FpOMKTgYbTKYexMXHSaIz6bOD94OJCDfTwT7CywrbMWz24MLbi1R8DdJ%2B5NsQJSxIxeIqCExAVFRU%2B8WLF6WosEiNhIbZ6GRIIzo2WiIiI9gvMEeqPCMFJS6DPUQGyfwNkHZAlhnmtww3DTlTkj%2FliNrPvvHFqFihmC5DfXDyP1nQAZO%2BfFIoXxDb82cdE3gwOiLELuPHxje4c%2Bi1ziZPUzxuPjTyScMcDvCBf1IKCwpBQn90UYfEo2qiYqKVjAGBAc%2B9fXxqQdL0H1V3aBFAGeqMlpnKjmgQD62UTtiy%2FSwWtmYqm5IUXKFeMM%2FsomV2u%2F3vtAEuufysByfgRJX8DshTPU2mPPy7yQBBYzGWgC%2FVkOSXWVmZZHwnSPoD%2FlOmodXSsWFjsOe%2FCAcrQqMD2awAAAAASUVORK5CYII%3D)](https://travis-ci.org/tgingold/ghdl) [![Windows VMs at AppVeyor](https://ci.appveyor.com/api/projects/status/rsq60m5wcly3og8j?svg=true)](https://ci.appveyor.com/project/tgingold/ghdl) ![Latest tag](https://img.shields.io/github/tag/tgingold/ghdl.svg?label=latest%20tag&style=flat) [![Latest release](https://img.shields.io/github/release/tgingold/ghdl.svg?label=latest%20release&style=flat)](https://github.com/tgingold/ghdl/releases)
 
 # GHDL
 
@@ -22,17 +21,31 @@ Supported third party projects: [VUnit](https://vunit.github.io), [OSVVM](http:/
 
 GHDL is free software:
 
-- [![GNU General Public License 2](https://img.shields.io/github/license/tgingold/ghdl.svg?style=flat)](https://github.com/tgingold/ghdl/blob/master/COPYING.md)
-- Doc is available on [ghdl.readthedocs.org](https://ghdl.readthedocs.org/en/latest/index.html).
+- [![GNU General Public License 2](https://img.shields.io/github/license/tgingold/ghdl.svg?&colorB=bd0000&style=flat)](https://github.com/tgingold/ghdl/blob/master/COPYING.md)
+- [![Creative Commons Attribution-ShareAlike](https://img.shields.io/badge/doc%20license-Creative%20Commons%20Attribution--ShareAlike-aab2ab.svg?style=flat)](https://github.com/tgingold/ghdl/blob/master/COPYING.md) available at [![ghdl.readthedocs.org](https://img.shields.io/badge/readthedocs-ghdl-aab2ab.svg?style=flat)](https://ghdl.readthedocs.org) 
 - Some of the runtime libraries, are under different terms; see the individual source files for details.
 
 ## Getting GHDL
 
-@1138-4EB: releases, docker, build it yourself
+Periodically (not regularly), several binary distributions are made available through the [releases](https://github.com/tgingold/ghdl/releases) tab. If you can't find the one matching the platform and versions you need, you can build it yourself!
+
+### Docker containers
+
+If you don't want to install the dependencies in your own filesystem, [Docker](https://www.docker.com/) containers can be used. You can have the latest version compiled and automatically placed in your current path with:
+
+```
+wget "https://raw.githubusercontent.com/tgingold/ghdl/master/dist/linux/docker-buildtest.sh"
+chmod +x docker-buildtest.sh
+./docker-buildtest.sh -i "ghdl/ghdl-tools:fedora-llvm-cmp" -b "mcode" -f "ghdl-mcode.tgz" -g
+```
+
+See '[Docker](http://ghdl.readthedocs.io/en/latest/getting/Docker.html)' for a list of available images and compiler options. You will also find images with GHDL installed already, so that you can directly start using it without caring about the platform!
+
+*If you are new to docker, keep in mind that it's not significantly different from the traditional way. Exactly the same commands are executed, but it's done in a box similar to a virtual machine.*
 
 ### Building GHDL
 
-You need the GNU Ada compiler, GNAT GPL, 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.
+In order to follow the traditional way to `configure` and `make`, you need the GNU Ada compiler, GNAT GPL, 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.
 
 *Depending on the OS and distribution you are using, you will also need to install some toolchain dependencies, such as `zlib`. See '[Building](http://ghdl.readthedocs.io/en/latest/building/index.html)' for specific package names.*
 

doc/changelog/Roadmap.rst

@@ -1,4 +1,4 @@
-.. _INTRO:Contributing:
+.. _CHANGE:Roadmap:
 
 Roadmap | Future improvements
 ############

doc/changelog/index.rst

@@ -11,9 +11,7 @@ Change Log
       2016/index
       2015/index
       2014/index
-
-
-
+
 .. only:: latex
 
    .. toctree::
@@ -22,9 +20,3 @@ Change Log
       2015/index
       2016/index
       2017/index
-
-------------------------
-
-.. TODO::
-
-	- `./NEWS <https://github.com/tgingold/ghdl/blob/master/NEWS>`_

doc/index.rst

@@ -1,42 +1,14 @@
-This manual is the user and reference manual for GHDL. It does not contain an introduction to VHDL. Thus, the reader should have at least a basic knowledge of VHDL. A good knowledge of VHDL language reference manual (usually called LRM) is a plus.
+.. include:: shields.txt
 
-.. only:: html
+|SHIELD:gh-logo| |SHIELD:gitter| |SHIELD:code-lic| |SHIELD:doc-lic| |br| |SHIELD:travis-ci| |SHIELD:appveyor| |SHIELD:tag| |SHIELD:release|
 
-   .. raw:: html
-
-      <hr />
-
-   .. image:: /_static/logos/GitHub-Mark-32px.png
-      :scale: 60
-      :target: https://www.github.com/tgingold/ghdl
-      :alt: Source Code on GitHub
-   .. image:: https://badges.gitter.im/ghdl/ghdl1.svg
-      :target: https://gitter.im/ghdl/ghdl1
-      :alt: Join
+------------------------------------ 
 
-   .. raw:: html
-
-      <br />
+GHDL Documentation
+########
+
+This manual is the user and reference manual for GHDL. It does not contain an introduction to VHDL. Thus, the reader should have at least a basic knowledge of VHDL. A good knowledge of VHDL language reference manual (usually called LRM) is a plus.
 
-   .. image:: https://travis-ci.org/tgingold/ghdl.svg?branch=master
-      :target: https://travis-ci.org/tgingold/ghdl
-      :alt: Build status by Travis-CI
-   .. image:: https://ci.appveyor.com/api/projects/status/r5dtv6amsppigpsp/branch/release?svg=true
-      :target: https://ci.appveyor.com/project/Paebbels/poc/branch/release
-      :alt: Build status by AppVeyor      
-   .. image:: https://img.shields.io/github/tag/tgingold/ghdl.svg?style=flat
-      :alt: Latest tag
-   .. image:: https://img.shields.io/github/release/tgingold/ghdl.svg?style=flat
-      :target: https://github.com/tgingold/ghdl/releases
-      :alt: Latest release
-   .. image:: https://img.shields.io/github/license/tgingold/ghdl.svg?style=flat
-      :target: intro/Copyrights.html
-      :alt: GNU General Public License 2
-
-   .. raw:: html
-
-      <hr />
-
 .. only:: html
 
    News
@@ -61,10 +33,10 @@ sanctus est Lorem ipsum dolor sit amet
 .. TODO:
 
   - http://ghdl.free.fr
-  - In `doc/conf.py` add a command to copy `./COPYING.md` to `doc/License.md`
- 
-------------------------------------
+  - In `doc/conf.py` add a command to copy `./COPYING.md` to `doc/License.md`, and `NEWS.md` to `doc/changelog/index.md`.
 
+------------------------------------
+
 .. |docdate| date:: %b %d, %Y - %H:%M
 
 .. only:: html

doc/intro/Contributing.rst

@@ -3,22 +3,46 @@
 Contributing
 ############
 
-Despite all the testing and already reported `issues <https://github.com/tgingold/ghdl/issues>`_, you can find bugs
-or propose enhancements.
+.. include:: ../shields.txt
 
-  .. _reporting_bugs:
+The first step might be to use GHDL and explore it's possibilities in an own project. If you are new to VHDL, see the :ref:`Quick Start Guide <USING:QuickStart>` for an introduction. Furthermore, we encourage you to read :ref:`Invoking GHDL <USING:Invoking>`, where the most commonly used options are explained. You can also check the complete :ref:`Command Reference <REF:Command>`.
+
+If you are more familiar with GHDL, you might start asking yourself how it works internally. Then, you migh find :ref:`Implementation of VHDL <REF:ImplVHDL>` and :ref:`Implementation of VITAL <REF:ImplVITAL>` interesting. 
+
+While using GHDL, you might find flaws, such as bugs, missing features, typos in the documentation or topics which are still not covered. In order to improve GHDL, we welcome bugs report and suggestions for any aspect of GHDL. So, please report them so that we are aware!
+
+Either if it's a bug or an enhancement, have a look at the |SHIELD:issues-open| and |SHIELD:issues-closed| to see if someone already told us about it. You might find a solution there. To get a broader view, you can also check the :ref:`Roadmap <CHANGE>`. Then, you can reach us through various ways:
+
+- |SHIELD:gitter|
+- Open a |SHIELD:issues-new|
+- Fork, modify and create a Pull Request on |SHIELD:issues-pr| |SHIELD:issues-pr-closed|
+- Suscribe to the mailing-list |SHIELD:mailing|
+
+The indications below shall help you choose which one to take.
+
+improve doc
+examples
+
+
+If you have an interresting project, please send us feedback or get listed on our :doc:`Who uses GHDL?` page.
 
+
+Related interesting projects
+==============
+
 Asking for enhancements
 ==============
+
+  .. _reporting_bugs:
 
 Reporting bugs
 ==============
 
-In order to improve GHDL, we welcome bugs report and suggestions for
-any aspect of GHDL.  Please create an issue on
-https://github.com/tgingold/ghdl/issues
+	If you cannot compile, please report the gcc version, GNAT version and gcc source version.
+	- Minimum-(non)-Working-Example (MWE)
+`How To Ask Questions The Smart Way <www.catb.org/~esr/faqs/smart-questions.html>`_
 
-If the compiler crashes, this is a bug.  Reliable tools never crash.
+If the compiler crashes, this is a bug. Reliable tools never crash.
 
 If your compiled VHDL executable crashes, this may be a bug at
 runtime or the code produced may be wrong.  However, since VHDL
@@ -67,14 +91,7 @@ Again, rewriting part of it is a good way to improve it.
 
 .. TODO::
 
-  - Reporting bugs
-	- [1138: Issues, search first]
-	- Minimum-(non)-Working-Example (MWE)
   - Pull Requests (PRs)
 	- Check Building -> GHDL -> Directory Structure]
 	- Beware that some commit messages can `automatically close <https://help.github.com/articles/closing-issues-via-commit-messages/>`_ PRs]
-
-	There is a mailing list for any questions.  You can subscribe via: https://mail.gna.org/listinfo/ghdl-discuss/
-	Please report bugs on https://github.com/tgingold/ghdl/issues
-
-	If you cannot compile, please report the gcc version, GNAT version and gcc source version.
+

doc/intro/Copyrights.rst

@@ -67,9 +67,7 @@ points in distributing VHDL executable.  Please, send a comment
 	- Adam Jensen        (FreeBSD builds)
 	- Felix Bertram      (VPI interface)
 
-with apologies to anyone who ought to be on this list but isn't.
-Thanks also to all those who have reported bugs and support issues,
-and often patches and testcases to either:
-https://gna.org/bugs/?group=ghdl
-or
-https://sourceforge.net/p/ghdl-updates/tickets/
+	with apologies to anyone who ought to be on this list but isn't. Thanks also to all those who have reported bugs and support issues, and often patches and testcases to either: https://gna.org/bugs/?group=ghdl or https://sourceforge.net/p/ghdl-updates/tickets/
+
+	https://en.wikipedia.org/wiki/Wikipedia:Copyrights#Reusers.27_rights_and_obligations
+	https://en.wikipedia.org/wiki/Wikipedia:General_disclaimer

doc/intro/WhatIsGHDL.rst

@@ -5,25 +5,14 @@
 What is `GHDL`?
 ###############
 
-`GHDL` is a shorthand for G Hardware Design Language. Currently, `G` has no
-meaning.
+`GHDL` is a shorthand for `G Hardware Design Language` (currently, `G` has no meaning). It is a `VHDL` compiler that can execute (nearly) any `VHDL` program. `GHDL` is *not* a synthesis tool: you cannot create a netlist with `GHDL` (yet).
 
-`GHDL` is a `VHDL` compiler that can execute (nearly) any `VHDL` program. `GHDL`
-is *not* a synthesis tool: you cannot create a netlist with `GHDL`.
+Unlike some other simulators, `GHDL` is a compiler: it directly translates a `VHDL` file to machine code, without using an intermediary language such as `C` or `C++`. Therefore, the compiled code should be faster and the analysis time should be shorter than with a compiler using an intermediary language.
 
-Unlike some other simulators, `GHDL` is a compiler: it directly translates a
-`VHDL` file to machine code, using the `GCC` or `LLVM` back-end and without
-using an intermediary language such as `C` or `C++`. Therefore, the compiled
-code should be faster and the analysis time should be shorter than with a
-compiler using an intermediary language.
+`GHDL` can use multiple back-ends, i.e. code generators, (`GCC <http://gcc.gnu.org/>`_, `LLVM <http://llvm.org/>`_ or `x86 <https://en.wikipedia.org/wiki/X86-64>`_/`i386 <https://en.wikipedia.org/wiki/Intel_80386>`_ only, a built-in one) and runs on `GNU/Linux <http://en.wikipedia.org/wiki/Linux_distribution>`_, `Windows <http://en.wikipedia.org/wiki/Microsoft_Windows>`_ |trade|  and `macOS <http://en.wikipedia.org/wiki/MacOS>`_ |trade| , both on `x86` and on `x86_64`.
 
-The Windows\ |trade| version of `GHDL` is not based on `GCC` but on an internal
-code generator.
+The current version of `GHDL` does not contain any graphical viewer: you cannot see signal waves. You can still check the behaviour of your design with a test bench. Moreover, the current version can produce a `GHW <http://ghdl.readthedocs.io/en/latest/using/Simulation.html?highlight=GHW#cmdoption-wave>`_, `VCD <https://en.wikipedia.org/wiki/Value_change_dump>`_ or `FST` files which can be viewed with a `waveform viewer <https://en.wikipedia.org/wiki/Waveform_viewer>`_, such as `GtkWave <http://gtkwave.sourceforge.net/>`_.
 
-The current version of `GHDL` does not contain any graphical viewer: you cannot
-see signal waves. You can still check with a test bench. The current version can
-produce a `VCD` file which can be viewed with a wave viewer, as well as `ghw`
-files to be viewed by `gtkwave`.
+`GHDL` aims at implementing `VHDL` as defined by `IEEE 1076 <http://ieeexplore.ieee.org/document/4772740/>`_. It supports the `1987 <http://ieeexplore.ieee.org/document/26487/>`_, `1993 <http://ieeexplore.ieee.org/document/392561/>`_ and `2002 <http://ieeexplore.ieee.org/document/1003477/>`_ revisions and, partially, the latest, `2008 <http://ieeexplore.ieee.org/document/4772740/>`_. `PSL <https://en.wikipedia.org/wiki/Property_Specification_Language>`_ is also partially supported.
 
-`GHDL` aims at implementing `VHDL` as defined by IEEE 1076. It supports most of
-the 1987 standard and most features added by the 1993 standard.
+Several third party projects are supported: `VUnit <https://vunit.github.io/>`_, `OSVVM <http://osvvm.org/>`_, `cocotb <https://github.com/potentialventures/cocotb>`_ (through the `VPI interface <https://en.wikipedia.org/wiki/Verilog_Procedural_Interface>`_), ...