Merge remote-tracking branch 'origin/master' into ghc-head

1 files changed, 164 insertions, 0 deletions

diff --git a/doc/intro.rst b/doc/intro.rst
new file mode 100644
index 00000000..fcdc67f1
--- /dev/null
+++ b/doc/intro.rst
@@ -0,0 +1,164 @@
+Introduction
+============
+
+This is Haddock, a tool for automatically generating documentation from
+annotated Haskell source code. Haddock was designed with several goals
+in mind:
+
+-  When documenting APIs, it is desirable to keep the documentation
+   close to the actual interface or implementation of the API,
+   preferably in the same file, to reduce the risk that the two become
+   out of sync. Haddock therefore lets you write the documentation for
+   an entity (function, type, or class) next to the definition of the
+   entity in the source code.
+
+-  There is a tremendous amount of useful API documentation that can be
+   extracted from just the bare source code, including types of exported
+   functions, definitions of data types and classes, and so on. Haddock
+   can therefore generate documentation from a set of straight Haskell
+   98 modules, and the documentation will contain precisely the
+   interface that is available to a programmer using those modules.
+
+-  Documentation annotations in the source code should be easy on the
+   eye when editing the source code itself, so as not to obscure the
+   code and to make reading and writing documentation annotations easy.
+   The easier it is to write documentation, the more likely the
+   programmer is to do it. Haddock therefore uses lightweight markup in
+   its annotations, taking several ideas from
+   `IDoc <http://www.cse.unsw.edu.au/~chak/haskell/idoc/>`__. In fact,
+   Haddock can understand IDoc-annotated source code.
+
+-  The documentation should not expose any of the structure of the
+   implementation, or to put it another way, the implementer of the API
+   should be free to structure the implementation however he or she
+   wishes, without exposing any of that structure to the consumer. In
+   practical terms, this means that while an API may internally consist
+   of several Haskell modules, we often only want to expose a single
+   module to the user of the interface, where this single module just
+   re-exports the relevant parts of the implementation modules.
+
+   Haddock therefore understands the Haskell module system and can
+   generate documentation which hides not only non-exported entities
+   from the interface, but also the internal module structure of the
+   interface. A documentation annotation can still be placed next to the
+   implementation, and it will be propagated to the external module in
+   the generated documentation.
+
+-  Being able to move around the documentation by following hyperlinks
+   is essential. Documentation generated by Haddock is therefore
+   littered with hyperlinks: every type and class name is a link to the
+   corresponding definition, and user-written documentation annotations
+   can contain identifiers which are linked automatically when the
+   documentation is generated.
+
+-  We might want documentation in multiple formats - online and printed,
+   for example. Haddock comes with HTML, LaTeX, and Hoogle backends, and
+   it is structured in such a way that adding new backends is
+   straightforward.
+
+Obtaining Haddock
+-----------------
+
+Distributions (source & binary) of Haddock can be obtained from its `web
+site <http://www.haskell.org/haddock/>`__.
+
+Up-to-date sources can also be obtained from our public darcs
+repository. The Haddock sources are at
+``http://code.haskell.org/haddock``. See
+`darcs.net <http://www.darcs.net/>`__ for more information on the darcs
+version control utility.
+
+License
+-------
+
+The following license covers this documentation, and the Haddock source
+code, except where otherwise indicated.
+
+    Copyright 2002-2010, Simon Marlow. All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions
+    are met:
+
+    -  Redistributions of source code must retain the above copyright
+       notice, this list of conditions and the following disclaimer.
+
+    -  Redistributions in binary form must reproduce the above copyright
+       notice, this list of conditions and the following disclaimer in
+       the documentation and/or other materials provided with the
+       distribution.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS "AS IS" AND ANY
+    EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+    PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE
+    LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+    CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+    SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+    BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Contributors
+------------
+
+Haddock was originally written by Simon Marlow. Since it is an open
+source project, many people have contributed to its development over the
+years. Below is a list of contributors in alphabetical order that we
+hope is somewhat complete. If you think you are missing from this list,
+please contact us.
+
+-  Ashley Yakeley
+-  Benjamin Franksen
+-  Brett Letner
+-  Clemens Fruhwirth
+-  Conal Elliott
+-  David Waern
+-  Duncan Coutts
+-  George Pollard
+-  George Russel
+-  Hal Daume
+-  Ian Lynagh
+-  Isaac Dupree
+-  Joachim Breitner
+-  Krasimir Angelov
+-  Lennart Augustsson
+-  Luke Plant
+-  Malcolm Wallace
+-  Manuel Chakravarty
+-  Mark Lentczner
+-  Mark Shields
+-  Mateusz Kowalczyk
+-  Mike Thomas
+-  Neil Mitchell
+-  Oliver Brown
+-  Roman Cheplyaka
+-  Ross Paterson
+-  Sigbjorn Finne
+-  Simon Hengel
+-  Simon Marlow
+-  Simon Peyton-Jones
+-  Stefan O'Rear
+-  Sven Panne
+-  Thomas Schilling
+-  Wolfgang Jeltsch
+-  Yitzchak Gale
+
+Acknowledgements
+----------------
+
+Several documentation systems provided the inspiration for Haddock, most
+notably:
+
+-  `IDoc <http://www.cse.unsw.edu.au/~chak/haskell/idoc/>`__
+
+-  `HDoc <http://www.fmi.uni-passau.de/~groessli/hdoc/>`__
+
+-  `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`__
+
+and probably several others I've forgotten.
+
+Thanks to the the members of haskelldoc@haskell.org,
+haddock@projects.haskell.org and everyone who contributed to the many
+libraries that Haddock makes use of.