===============
Getting Started                                                         [TOC]
===============

At the bottom of every page generated by *doctool* you see a link labeled
`View document source`.  Click it and you see the source file from which the
HTML code was generated.

On the top right you see a link labeled `Browse Files` that leads you to a
file-tree style browser containing all C++ or doc-files within this folder.

It uses some __reStructuredText__ dialect for writing documents.


Installation
============
As *doctool* was developed for private use this is the hard part:

- First get *dcotool* from __gitHub__:

  *--[BOX]------------------------------------------------------------------*
  |                                                                         |
  |  git clone git://github.com/michael-lehn/DocTool.git                    |
  |                                                                         |
  *-------------------------------------------------------------------------*

- Adapt some shell variables in `DocTool/Configuration/doctool.config`.  Idealy
  you only have to change two variables:
   - `VIMRUNTIME`
   - `CXXFLAGS`

- Adapt your `.profile`, such that *doctool* is in the `PATH` and can find
  itself, e.g.

  *--[CODE(type=txt)]-------------------------------------------------------*
  |                                                                         |
  | # ...                                                                   |
  | export DOCTOOL=${HOME}/DocTool/                                         |
  | export PATH=$PATH:${DOCTOOL}/Executables                                |
  | # ...                                                                   |
  |                                                                         |
  *-------------------------------------------------------------------------*

- I justed started to use __libclang__ (from the __clang__ compiler project)
  for creating cross references in the HTML-formated C++ source code and for
  generating API documentation.  If you want to use these features you have to
  adapt the `Makefile` in `DocTool/CxxTools`.  Please understand that this part
  is even more experimental than the rest.


Test Your Installation
======================
Change to `DocTool/Examples` and run `doctool --convertSourcefiles`.

- The option `--convertSourcefiles` will convert the C++ codes to HTML and
  applies the cross referencing it get from __libclang__.
- If you only run `doctool` without further options it only will process `*.doc`
  files the current directory or any subdirectory.
- If you run `doctool` in a directory that contains a `doctool.preconfig`
  file, it will evaluate it before parsing any 'doc' file.


Examples
========
- __Example 1__: Writing a simple tutorial for the _Hello world!_ programm.
- __Example 2__: Class API Documentation.
- __Example 3__: Literate Programming.


More Examples
=============
Originally the sole purpose of *doctool* was the creation of documentation and
tutorials for __FLENS__.  So you can see more examples there:

 - Tables and other formatting: __FLENS-LAPACK__
 - Class API: __GeMatrix__, __DenseVector__
 - Numerical routines: __trs__, __sv__
 - Small examples: __lapack-gelsy__
 - C++ Source Code Listings with Cross References: __mv__, __gesv__ (linked
   keyword are underlined with dots).
 - ...


Final Note
==========
Make sure your editor expands tabs to spaces.  Otherwise you will go nuts.


:links: reStructuredText  ->  http://en.wikipedia.org/wiki/ReStructuredText
        gitHub            ->  https://github.com/michael-lehn/DocTool
        libclang          ->  http://clang.llvm.org/doxygen/group__CINDEX.html
        clang             ->  http://clang.llvm.org
        Example (\d*)     ->  doc:tutorial/example$1
        FLENS             ->  http://www.mathematik.uni-ulm.de/~lehn/FLENS
        FLENS-LAPACK      ->  http://www.mathematik.uni-ulm.de/~lehn/FLENS/flens/lapack/lapack.html
        GeMatrix          ->  http://www.mathematik.uni-ulm.de/~lehn/FLENS/flens/matrixtypes/general/impl/gematrix.html
        DenseVector       ->  http://www.mathematik.uni-ulm.de/~lehn/FLENS/flens/vectortypes/impl/densevector.html
        trs               ->  http://www.mathematik.uni-ulm.de/~lehn/FLENS/flens/lapack/impl/trs.html
        sv                ->  http://www.mathematik.uni-ulm.de/~lehn/FLENS/flens/lapack/impl/sv.html
        lapack-gelsy      ->  http://www.mathematik.uni-ulm.de/~lehn/FLENS/flens/examples/lapack-gelsy.html
        mv                ->  http://www.mathematik.uni-ulm.de/~lehn/FLENS/flens/examples/tut02-page03-example.cc.html
        gesv              ->  http://www.mathematik.uni-ulm.de/~lehn/FLENS/flens/examples/lapack-gesv.cc.html