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>

4 files changed, 47 insertions, 62 deletions

diff --git a/doc/intro/Contributing.rst b/doc/intro/Contributing.rst
index 6919d4496..66b5675bd 100644
--- a/doc/intro/Contributing.rst
+++ b/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.
\ No newline at end of file
+	
\ No newline at end of file
diff --git a/doc/intro/Copyrights.rst b/doc/intro/Copyrights.rst
index 07c1780b3..a178bcd55 100644
--- a/doc/intro/Copyrights.rst
+++ b/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/
\ No newline at end of file
+	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
\ No newline at end of file
diff --git a/doc/intro/WhatIsGHDL.rst b/doc/intro/WhatIsGHDL.rst
index 449ef5d01..5733c6869 100644
--- a/doc/intro/WhatIsGHDL.rst
+++ b/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>`_), ...
diff --git a/doc/intro/WhatIsVHDL.rst b/doc/intro/WhatIsVHDL.rst
index 4d40e0c59..06696d75d 100644
--- a/doc/intro/WhatIsVHDL.rst
+++ b/doc/intro/WhatIsVHDL.rst
@@ -3,31 +3,12 @@
 What is `VHDL`?
 ###############
 
-`VHDL` is an acronym for Very High Speed Integrated Circuit Hardware Description
-Language which is a programming language used to describe a logic circuit by
-function, data flow behavior, or structure.
+`VHDL <https://en.wikipedia.org/wiki/VHDL>`_ is an acronym for Very High Speed Integrated Circuit (`VHSIC <https://en.wikipedia.org/wiki/VHSIC>`_) `Hardware Description Language <https://en.wikipedia.org/wiki/Hardware_description_language>`_ which is a programming language used to describe a logic circuit by function, data flow behavior, or structure.
 
-`VHDL` *is* a programming language: although `VHDL` was not designed for writing
-general purpose programs, you can write any algorithm with the `VHDL` language.
-If you are able to write programs, you will find in `VHDL` features similar to
-those found in procedural languages such as `C`, `Python`, or `Ada`. `VHDL`
-derives most of its syntax and semantics from `Ada`. Knowing `Ada` is an
-advantage for learning `VHDL` (it is an advantage in general as well).
+Although `VHDL` was not designed for writing general purpose programs, `VHDL` *is* a programming language, and you can write any algorithm with it. If you are able to write programs, you will find in `VHDL` features similar to those found in procedural languages such as `C`, `Python`, or `Ada`. Indeed, `VHDL` derives most of its syntax and semantics from `Ada`. Knowing `Ada` is an advantage for learning `VHDL` (it is an advantage in general as well).
 
-However, `VHDL` was not designed as a general purpose language but as an `HDL`
-(hardware description language). As the name implies, `VHDL` aims at modeling or
-documenting electronics systems. Due to the nature of hardware components which
-are always running, `VHDL` is a highly concurrent language, built upon an
-event-based timing model.
+However, `VHDL` was not designed as a general purpose language but as an `HDL`. As the name implies, `VHDL` aims at modeling or documenting electronics systems. Due to the nature of hardware components which are always running, `VHDL` is a highly concurrent language, built upon an event-based timing model.
 
-Like a program written in any other language, a `VHDL` program can be executed.
-Since `VHDL` is used to model designs, the term :dfn:`simulation` is often used
-instead of `execution`, with the same meaning.
+Like a program written in any other language, a `VHDL` program can be executed. Since `VHDL` is used to model designs, the term :dfn:`simulation` is often used instead of `execution`, with the same meaning. At the same time, like a design written in another `HDL`, a set of `VHDL` sources can be transformed with a :dfn:`synthesis tool` into a netlist, that is, a detailed gate-level implementation.
 
-Like a program written in another hardware description language, a `VHDL`
-program can be transformed with a :dfn:`synthesis tool` into a netlist, that is,
-a detailed gate-level implementation.
-
-.. TODO::
-
-  very very briefly explain that there are four major verions: 87, 93, 02 and 08
\ No newline at end of file
+The development of `VHDL` started in 1983 and the standard is named `IEEE <https://www.ieee.org/>`_ `1076`. Four revisions exist: `1987 <http://ieeexplore.ieee.org/document/26487/>`_, `1993 <http://ieeexplore.ieee.org/document/392561/>`_, `2002 <http://ieeexplore.ieee.org/document/1003477/>`_ and `2008 <http://ieeexplore.ieee.org/document/4772740/>`_. The standarization is handled by the VHDL Analysis and Standardization Group (`VASG/P1076 <http://www.eda-twiki.org/vasg/>`_).