What is HDoc?
=============

HDoc generates documentation in HTML format for Haskell modules.
The generated documents are cross linked and include summaries and
detailed descriptions for the documented functions, data types, type
classes and instance declarations.

To put it in other words: HDoc is very much like Javadoc.

For a quick start, see the file INSTALL and the section "Running the
included example" in this document (and KNOWN_PROBLEMS to find out
what does not yet work as it should).


Thanks for trying HDoc,

   Armin Groesslinger.

Please send your feedback/ideas and bug reports to
<groessli@fmi.uni-passau.de>.



License:
========

HDoc uses Andy Gill's HTML library. It is located in htmllibs/,
see htmllibs/License for details on that.

The subdir hsparser/ contains some parts from HsParser, the "100% pure
Haskell parser" by Sven Panne, Simon Marlow, and Noel Winstanley.  I

The subdir alex/ contains the runtime parts of Chris Dornan's scanner
generator Alex.

HDoc itself (the files in the toplevel directory (except GetOpt.hs
which is Sven Panne's Haskell port of GNU's getopt library) and under
examples/) is distributed under the GNU GPL, see COPYING for details.



Running the included example
============================

After compiling/installing (see file INSTALL), you can run the included
"simple example" with

$ cd examples/simple
$ ../../hdoc *.hs         

after compiling, or

$ cd examples/simple
$ ../../hdoc-hugs.sh *.hs

if you want to use the interpreted version.

You'll see some output like

reading BFS.hs  
reading BTree.hs  
reading Countable.hs  
sending output to ./
generating BFS.html
generating BTree.html
generating Countable.html
generating module index.
generating index of functions.
generating index of types.
generating index of classes.
generating index of instances.
generating index.html.
generating default stylesheet file ./hdoc.css.
finished.


Start your web browser and open examples/simple/index.html (it'a short
example; perhaps I'll write a better one some time).



Running HDoc:
=============

hdoc         [OPTIONS] files/modules ...           (for GHC/NHC98)

hdoc-hugs.sh [OPTIONS] files/modules ...           (for Hugs)

The given files are read, parsed and then the HTML documents are
constructed (in the current directory, when no -d DESTDIR is present).

"files" can be Haskell scripts (".hs"), literate Haskell script
(".lhs", LaTeX style or " > ..." style) or Green Card files (".gc").
When the file name does not contain a ".", then it is considered to be
a module name and the corresponding module is looked for on the search
path (see below).


Usage: ../../hdoc [OPTION...] file/module...
  -d DIR            --destdir=DIR      Send output to directory DIR    
  -e                --exports          Document exported objects only  
                    --line-numbers     Output line numbers             
  -t TITLE          --title=TITLE      Set the document title          
  -i PATH, -I PATH                     Search PATH for modules         
                    --stylesheet=FILE  Set the stylesheet to use       
                    --show-symbols     Show all supported named symbols
  -V                --version          Print HDoc's version number     
  -h                --help             Print this (short) help


Per default HDoc emits documentation for all top level functions,
all data types, classes and instances.
With --exports only objects appering in the export list of the modules
are included in the output. 
If you don't set the document title, HDoc will use a default title.

When HDoc runs, it will try to load modules imported from the files
given on the command line. For example, if you have a file A.hs with
contents

  module A where

  import B

  ...

then "hdoc A.hs" (or "hdoc A") will cause HDoc to look for module
B. It will try to find it in the files B.gc, B.lhs, B.hs in that
order. You can use the -I or -i switches to set the search path for
modules (the current directory is always searched), e.g.

hdoc -I /the/path/to/moduleB -I ../othermodules A.hs

As of verseion 0.8.2, HDoc supports hierarchical modules names,
i.e. the module name A.B.C will be translated to A/B/C.{gc,lhs,hs}.

HDoc will not generate output for modules not listed on the command
line, but for things re-exported from these modules. In addition it
will use them to derive type signatures for instance declarations
etc. HDoc knows about the type classes defined in the standard prelude
and in the standard libraries, so the type signatures for instances of
Eq, Enum etc. can be calculated by HDoc.


More documentation for the command line parameters and for HDoc's
input format can be found in the docs/ subdirectory.