# GAP package GAPDoc

Authors: Frank Lübeck and Max Neunhöffer
Needs: GAP in version at least 4.3.
and for creating high quality output of GAPDoc documents a sufficiently new version of `LaTeX/pdfLaTeX` and certain `LaTeX` packages, `makeindex`.
Operating systems: Any, on which GAP and the programs mentioned above are running.
Current version: 0.9999
Status: This package is distributed with GAP 4.3 as a deposited package. Some other packages now use GAPDoc for their documentation. If you want to read such documentation you must install the GAPDoc package as well. We intend to submit the package for refereeing soon.
Contact: Frank.Luebeck@Math.RWTH-Aachen.De or Max.Neunhoeffer@Math.RWTH-Aachen.DE
Download: See below for archives in several formats.

## Description

This package (together with recent improvements of GAP's help mechanism) describes an alternative for writing GAP documentation.

The idea is to define a sufficiently abstract markup language for GAP documentation which can be (relatively easily) converted into different output formats. We used XML to define such a language.

This package provides:

- Utilities to use the documentation of other packages which is written in GAPDoc format. If you don't want to write your own (package) documentation you can skip the remaining points.
- The description of a markup language for GAP documentation (which is defined using the XML standard).
- Three example documents using this language: The GAPDoc documentation itself, a short example which demonstrates all constructs defined in the GAPDoc language, and a very short example explained in the introduction of the main documentation.
- A mechanism for distributing documentation among several files, including source code files.
- GAP programs (written by the first named author) which produce from documentation written in the GAPDoc language several document formats:
  - text format with color markup for onscreen browsing.
  - LaTeX format and from this PDF- and DVI-versions with hyperlinks.
  - HTML (4.01 strict) format for reading with a Web-browser.

## Installation

Just unpack one of the archives given below in the `pkg` subdirectory of your GAP installation.

Unpacking generates a subdirectory `gapdoc`.

[This becomes unnecessary from GAP 4.4 on.] To tell GAP about this package add the following line to the file '`ALLPKG`' in the `pkg` directory.

    GAPDoc     # meta package for preparing GAP (package) documentation

That's it! (Maybe you want to read the help section '`?SetHelpViewer`' in the GAP reference manual.)

Installation outside the GAP main directory: When you don't have access to the directory of your main GAP installation you can also install the package by unpacking inside a directory `MYGAPDIR/pkg`. (Don't forget to call `gap` with the `-l ";MYGAPDIR"` option.) The only drawback with this installation is that in the HTML version of the package documentation the links to the main GAP manuals don't work. You can correct this by recompiling the HTML version of the documentation: Say `cd gapdoc; gap makedoc.g`.

## Online Documentation

Here is the documentation of the GAPDoc package in several output formats. If you have installed the package as described above you can also access all of these documents from the GAP online help.

### Main GAPDoc documentation

- HTML-version
- `pdf`-version
- `dvi`-version
- postscript-version
- text-version with and without color markup (you can read the colored version with `less` on a terminal screen, if it looks like garbage, type `-r<CR>` or start with `less -r`)

There is also an example document which uses all constructs which are allowed in a GAPDoc document. Here you can compare directly the GAPDoc-XML-source code and how it looks like in each format.

### Example GAPDoc document

- HTML-version
- `pdf`-version
- `dvi`-version
- postscript-version
- text-version with and without color markup.

## Package Archives for Download

The GAPDoc package is availabe in several formats:

- `gapdoc-0.9999.zoo` (use the "unzoo" or "unzoo.exe" from the GAP homepage)
- `gapdoc-0.9999.tar.gz` (GNU `tar` archive, `gzip`'ed)
- `gapdoc-0.9999.tar.bz2` (GNU `tar` archive, `bzip2`'ed)
- `gapdoc-0.9999-win.zip` (with DOS/Windows style line breaks in text files)

Frank Lübeck / Last modified: Mon, 29 Mar 2004 13:49:00 +0200