Automatic creation of printable user documentation
--------------------------------------------------

The {english|french|portuguese|german} user manual is created automatically 
from

    - a free form portion in SGML code (tnx G0VGS, F6FGZ, PP5AQ and DK4VW))
    - the translated user help files (tnx to all of them too)

The advantages of this automatism:

    - There is only one place to keep up to date
    - It's easy to make different forms of user documentation available 
      (printout, book, HTML and on-line)

It has the disadvantage of a little bit of complexity and some rules
which have to be followed, but we are feeling it is well worth.




1. File Structure

The structure for the user manuals is like this:

~/box/info/help.{language} - The place for the translated user online
                             help files.

~/doc/user/{language}      - This is where the free form portion of the 
                             manual must be located. Also this is the place
                             where the Postscript output will be placed.
                             This is called "source" directory in this
                             context.

~/doc/user/{language}/html - This is where the HTML results will be stored.

If you are going to translate to a new language, please follow this
scheme so that your work may be easily included in a future release of CLX. 
Let's say, you are translating into Suaheli. 

    1. Make two new directories ~/doc/user/suaheli and 
       ~/box/info/help.suaheli.

    2. Copy ~/doc/user/english/g0vgs.sgml to 
       ~/doc/user/suaheli/yourcall.sgml and copy all the on-line help 
       files from ~/box/info/help.english to ~/box/info/help.suaheli. 

    3. Make a link from ~/doc/user/english/Makefile to ~/doc/user/suaheli 
       and copy ~/doc/user/english/Rules.make to ~/doc/user/suaheli and 
       change it accordingly (put in your callsign).

    4. Go to the ~/box/info/help.suaheli and translate all the files.

    5. Go to the ~/doc/user/suaheli and translate {yourcall}.sgml.

    6. Try running "make check".


2. Creation

The Makefile in the source-directory executes different commands, which
in turn generate a finalized HTML and PostScript file from the information
found. The first (free-form) part of the user manual and the reformatted 
user help files are merged in the process, additionally the help.overview
file from the help files directory is used to generate a command overview.
To make this work on your system, you need to have several packages 
installed, namely Perl, the SGML-Tools (I am currently using version 1.07)
and LaTeX.

To start the process, simply type

    $ make check 

and if all seems fine, do a

    $ make html

to get the HTML version, or

    $ make ps

to the the postscript version, or

    $ make txt

to get the ASCII version or

    $ make release

to get all.

The first portion of the user manual, the free-form file, is taken more or 
less "as is". However, to make authors' lives easier, special national
characters like the French e with an grave accent () or the German umlaut 
characters () are automatically replaced by an ed script. So you need not
use those strange characters &egrave; or &auml; directly - but you can.
Also, please keep the formatting SGML tags in place as these are needed 
for the translation process.

Reformatting of the on-line help files is done by the perl script "extract" 
in the ~/tools directory. "extract" tries to be intelligent recognizing 
the structure of the help file. Certain rules must be observed to have 
"extract" understand what it sees. So a help file must basically look 
as follows:

------------------------------------------------------------------------------
Command
Command variations (optional)

Free form text follows. This text will be reformatted, putting a boldface
font around each CAPITALIZED WORD found. This will make the text look nice
and have COMMANDS stand out of the text. Please put all CLX commands in
CAPITAL letters.

    Any indented text will be set in typewriter font and not
    reformatted. Here is your chance for tables, lists. These will
    not break as long as they are indented (should 4 blanks by default).

Additional text may follow, which is again being reformatted.

A key word is anything looking like "Ex[ae]mple*:". This will be printed in 
bold face letters too. So put the examples like this, and they will be
treated correctly:

Examples:

    COMMAND                 definition for the basic command
    COMMAND/EXTENSION       command extension explained here

------------------------------------------------------------------------------

The command overview, which comes last in the manual generated is produced
as follows: For every file in the help.{language} directory, the corresponding
line is taken from the file ~clx_us/info/help.{language}/help.overview. 
Commands not found in this file are specially marked with three question marks.
This way, you can easily keep this file up to date. 

Also there are a few rules for the help.overview file:

    1. There must be a file help.overview in the language directory.

    2. This file must consist of:

       a) a headline (optionally underlined with "---" characters)
       b) one introductory paragraph
       c) one paragraph explaining each command (optionally using follow-up
          lines which must start with 20 or more blank characters
       d) one or more closing paragraphs.

    3. Commands and their explanation must be separated by at least two
       space characters, to separate command arguments from the explaining 
       text. There may be leading space characters.

This describes all of the current rules. If you are planning to put work
into a new (language) project, please advise the CLX team as early as
possible in order to prevent duplicate work done by someone else.

DL6RAI, Fri Dec  4 18:28:12 GMT 1998
