
Preface
-------

This file lists some hints for improving GAPDoc format books
that were originally written in the `gapmacro.tex' based format
and later --using some heuristic tools and some hand-editing--
were turned into GAPDoc format.

The main GAP manuals (Reference Manual, Tutorial, Programming in GAP,
Extending GAP) are the main targets for these hints,
but they might be also useful for the translation of package manuals
from the `gapmacro.tex' based format into GAPDoc format.


How to Proceed with the Reference Manual
----------------------------------------

- The idea is that you ``adopt'' some chapters of the Reference Manual,
  typically those belonging to the modules of GAP code which you have claimed
  (see the files `doc/tut/authors.xml', `dev/MAINTAINERS', `dev/MODULES').

- The file `dev/manualchapters' was created for collecting the information
  about the status of the manuals,
  so please edit this file according to the progress with ``your'' manual
  chapters.

- For your chapters, the first step is to compare the versions
  in the `gapmacro.tex' based format and in GAPDoc format,
  in the TeX/LaTeX version, in the HTML version, and in the text version
  used for the online help;
  check what got lost or looks worse in the GAPDoc manual than in the old one.

  (How to access the two manuals in question:
  The current GAPDoc format version is the one in the development version
  of GAP,
  which can be compiled by calling `make doc' in the GAP root directory.
  The latest version based on `gapmacro.tex' can be obtained as that
  of January 30th, 2007.
  Perhaps the easiest way is to compare the manual in the development version
  with the manual of the released version of GAP;
  then also changes for the forthcoming release can be listed,
  in the file `dev/NEWFEATURES'.)

- At the same time --once you are reading the text-- it would be desirable
  to list deficiencies of the *contents* of the chapter,
  which are not related to the manual format.
  So interesting questions are
  - what is missing in this chapter and
  - which statements look strange or are outdated or misleading
    or simply wrong, or will become problematic in the future?

- The second step is to look at the source code of your chapters
  in the current GAPDoc manual, that is,
  in the `doc/ref/*.xml' files and the affected pieces of text in `lib' files.
  You can either apply your corrections and improvements directly,
  or (if you are unsure about the appropriate solution) list the offending
  details under the ``Comments'' line for the chapter in question,
  in the file `dev/manualchapters'.

  Perhaps the function `PrintInfoAboutManualChapters' in the file
  `dev/manualutils.g' is useful, but clearly it tests just a few aspects.

  Here is a checklist what is likely to need changes by hand.

  - There are still many <C> elements (see ?<Code>)
    whose contents are documented GAP variables.
    Most of them should be changed into <Ref> elements (see ?<Ref>).
    (The ``duplications'' of the kind ``<C>var</C> (see <Ref Func="var"/>)''
    should have disappeared, but if you meet such a case then replace it by
    the <Ref> element only.)
    *Note* that *not all* such <C> elements really mean references:
    there are for example names of record components, names of menu entries
    for the Mac version of GAP, index entries etc. where the <C> element
    is the correct form.
    So here we cannot replace globally.
  - Those <C> elements whose contents are filenames should be turned into
    <F> elements (see ?<File>).
    (Again this cannot be done automatically.)
  - There are several ``multiply defined labels'', which arise from the fact
    that several declaration lines for the same function exist,
    which are not distinguished by `Label' attributes (see ?<ManSection>).
    This can be resolved in the following two ways:
    Where this is reasonable, the different variants of arguments should be
    combined in one declaration line, using the regular expression syntax
    for optional arguments.
    In the other cases, introducing meaningful labels is recommended.
    The former solution will require changes in the text that follows the
    declaration line.
    The latter solution will require changes in all cross-references to
    the variable in question (since the labels have to be added there).
    So this is ugly work.
  - In <ManSection> elements where several variables are introduced,
    it is likely that one wants to add a <Heading> element that yields a
    better subsection heading than the default (which is the first variable
    name that is introduced, see ?<ManSection>).
  - Mathematical formulae need to be cleaned up (see ?<Math> and ?<M>).
    Introducing whitepace is needed in many cases (look at the online help
    version, the LaTeX version does not care about this);
    and subscripts/superscripts may need to be changed.
  - Lists might be suboptimal.
    Where the <Mark> elements contain just numbers, switching from <List>
    to <Enum> yields nicer results (see ?<List> and the following subsections).
    <Mark> elements with the contents `--' should be simply removed.
  - <Index> elements should occur in the text at the place where they are
    intended to point.
    In the old manual, the index entries often occurred at the beginning of
    the section or somewhere behind the proper place
    (perhaps because one did not want to put them into the documentation part
    in the `lib' file?).
  - <Example> elements (see ?<Log>) typically belong to a subsection that
    introduces the GAP objects that are shown in the examples in question.
    Many of the manual examples have been moved already into ``their''
    <ManSection> element (and therefore were moved from the `.xml' file into
    a file in `lib'), but it is still likely that some examples are
    logically in wrong places, i.e., between the end of a (sub)section and
    the beginning of the next (sub)section.
  - Several chapters contain ``implicit subsections'' in the sense that
    the old manual did not support subsections but the text required
    somehow a subsection like structuring;
    In these cases, we find an emphasized ``subsection heading''
    (i.e., in an <E> element, see ?<Emph>), usually on a line of its own,
    followed by some text paragraphs.
    Here the subsection should be made explicit.
  - Citations (see ?<Cite>) can now use the `Where' attribute,
    which was not supported in the old manual format.


Heuristic Tools for the Translation to GAPDoc
---------------------------------------------

1. The GAP programs which I had used for translating the main GAP manuals
   (and the manuals for the packages AtlasRep, CTblLib, and Example)
   to GAPDoc format can be found in the file `dev/gapmacro2gapdoc.g'.
   Originally I had not planned to make them public,
   they are really very poor tools for the obvious mappings of structures,
   and they ignore structures that occurred rarely in the main manuals
   --I simply translated nontrivial pieces of syntax by hand instead of
   writing nontrivial GAP functions.
   However, I have been convinced to make these tools available,
   mainly for documentational purposes,
   and not as ``the official and recommended translation to GAPDoc''.

   For the further treatment of the main manuals,
   these tools are not interesting

   Detailed comments about the steps I took
   in the translation of the manual of the `Example' package
   are listed in the file `pkg/example/comments'.
   Perhaps the paragraph on ``Suggested changes of the *contents*''
   in this file can be used as a prototype for the ``Comments'' entries
   in the file `dev/manualchapters'.

2. Tools for checking certain properties of a manual chapter can be found
   in `dev/manualutils.g'.
   The functions in this file might be extended/improved in the future,
   since they could be interesting also for documents that were originally
   written in GAPDoc.


