4 files changed, 196 insertions, 0 deletions
diff --git a/doc/intro/Contributing.rst b/doc/intro/Contributing.rst
new file mode 100644
index 000000000..8a0ba30bc
--- /dev/null
+++ b/doc/intro/Contributing.rst
@@ -0,0 +1,77 @@
+.. _INTRO:Contributing:
+
+Contributing
+############
+
+Despite all the testing and already reported `issues <https://github.com/tgingold/ghdl/issues>`_, you can find bugs
+or propose enhancements.
+
+  .. _reporting_bugs:
+
+Asking for enhancements
+==============
+  
+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 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
+has a notion of pointers, an erroneous VHDL program (using invalid
+pointers for example) may crash.
+
+If the compiler emits an error message for a perfectly valid input or
+does not emit an error message for an invalid input, this may be a bug.
+Please send the input file and what you expected.  If you know the LRM
+well enough, please specify the paragraph which has not been well
+implemented.  If you don't know the LRM, maybe your bug report will be
+rejected simply because there is no bug.  In the latter case, it may be
+difficult to discuss the issue; and comparisons with other VHDL tools
+is not a very strong argument.
+
+If a compiler message is not clear enough for you, please tell me.  The
+error messages can be improved, but I have not enough experience with
+them.
+
+If you send a `VHDL` file producing a bug, it is a good idea to try
+to make it as short as possible.  It is also a good idea to make it
+looking like a test: write a comment which explains whether the file
+should compile, and if yes, whether or not it should run successfully.
+In the latter case, an assert statement should finish the test; the
+severity level note indicates success, while a severity level failure
+indicates failure.
+
+For bug reports, please include enough information for the maintainers to
+reproduce the problem. This includes:
+
+* the version of `GHDL` (you can get it with :samp:`ghdl --version`).
+* the operating system
+* whether you have built `GHDL` from sources or used the binary
+  distribution.
+* the content of the input files
+* a description of the problem and samples of any erroneous input
+* anything else that you think would be helpful.
+
+Documentation
+==============
+
+If you have found a mistake in the manual, please send a comment.  If
+you have not understood some parts of this manual, please tell me.
+English is not my mother tongue, so this manual may not be well-written.
+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)
+	- [1138: check chapter 2 -> building -> GHDL -> directory structure]
+	- [1138: beware that some commit messages can `automatically close <https://help.github.com/articles/closing-issues-via-commit-messages/>`_ PRs]
+\ No newline at end of file
diff --git a/doc/intro/Copyrights.rst b/doc/intro/Copyrights.rst
new file mode 100644
index 000000000..06cc7e4a9
--- /dev/null
+++ b/doc/intro/Copyrights.rst
@@ -0,0 +1,55 @@
+.. _INTRO:Copyrights:
+
+Copyrights | License
+############
+
+The GHDL front-end, the :samp:`std.textio` package and the runtime
+library (:samp:`grt`) are copyrighted Tristan Gingold, come with **absolutely
+no warranty**, and are distributed under the conditions of the General
+Public License.
+
+The :samp:`ieee.numeric_bit` and :samp:`ieee.numeric_std` packages are
+copyrighted by the IEEE.  The source files may be distributed without
+change, except as permitted by the standard.
+
+This source file may not be
+sold or distributed for profit.  See the source file and the IEEE 1076.3
+standard for more information.
+
+The :samp:`ieee.std_logic_1164`, :samp:`ieee.Math_Real` and
+:samp:`ieee.Math_Complex` packages are copyrighted by the IEEE.  See
+source files for more information.
+
+The :samp:`ieee.VITAL_Primitives`, :samp:`ieee.VITAL_Timing` and
+:samp:`ieee.VITAL_Memory` packages are copyrighted by IEEE.  See source
+file and the IEEE 1076.4 standards for more information.
+
+The packages :samp:`std_logic_arith`, 
+:samp:`std_logic_signed`, :samp:`std_logic_unsigned` and
+:samp:`std_logic_textio` contained in the :samp:`synopsys` directory are
+copyrighted by Synopsys, Inc.  The source files may be used and
+distributed without restriction provided that the copyright statements
+are not removed from the files and that any derivative work contains the
+copyright notice.  See the source files for more information.
+
+The package :samp:`std_logic_arith` contained in the :samp:`mentor`
+directory is copyrighted by Mentor Graphics.  The source files may be
+distributed in whole without restriction provided that the copyright
+statement is not removed from the file and that any derivative work
+contains this copyright notice.  See the source files for more information.
+
+As a consequence of the runtime copyright, you may not be allowed to
+distribute an executable produced by `GHDL` without the VHDL
+sources.  To my mind, this is not a real restriction, since there is no
+points in distributing VHDL executable.  Please, send a comment
+(:ref:`Reporting_bugs`) if you don't like this policy.
+
+----------------
+
+.. TODO: topic
+
+  https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
+  
+  Available in the following formats: plain text, Texinfo, LaTeX, standalone HTML, Docbook, Markdown, ODF, RT
+
+  See `#280 <https://github.com/tgingold/ghdl/issues/280#issuecomment-279595802>`_
+\ No newline at end of file
diff --git a/doc/intro/WhatIsGHDL.rst b/doc/intro/WhatIsGHDL.rst
new file mode 100644
index 000000000..449ef5d01
--- /dev/null
+++ b/doc/intro/WhatIsGHDL.rst
@@ -0,0 +1,29 @@
+.. include:: <isonum.txt>
+
+.. _INTRO:GHDL:
+
+What is `GHDL`?
+###############
+
+`GHDL` is a shorthand for G Hardware Design Language. Currently, `G` has no
+meaning.
+
+`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, 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.
+
+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 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. It supports most of
+the 1987 standard and most features added by the 1993 standard.
diff --git a/doc/intro/WhatIsVHDL.rst b/doc/intro/WhatIsVHDL.rst
new file mode 100644
index 000000000..b70b3a723
--- /dev/null
+++ b/doc/intro/WhatIsVHDL.rst
@@ -0,0 +1,35 @@
+.. _INTRO:VHDL:
+
+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` *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).
+
+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.
+
+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 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: topic
+
+  @1138 very very briefly explain that there are four major verions: 87, 93, 02 and 08
+\ No newline at end of file