Open Watcom Documentation Guide
===============================

This document provides a brief overview of the Open Watcom documentation
system and lists most of the steps necessary for editing and producing
online or printed documents.

It is useful to note that the online documentation is almost, but not quite,
independent of the rest of the Open Watcom compilers and tools. The one
important exception is online help files for Open Watcom GUI tools. Formatting
online documentation generates include files containing #defines designating
help entries. These are used during building of the tools binaries. If the
binaries are not built with the right header files, the online help will
be out of sync and will not be all that helpful.


How to Set it up
================

A Win32 or OS/2 system can be used to produce most of the documentation.
OS/2 Warp is required for the final step in producing the OS/2 online help
files (unless you have an IPF compiler that runs under Win32) and Win32 system
is needed for producing Windows help files (unless you can run the required
help compilers under OS/2). DOS may work too but it is untested at this time.

The environment variable "doc_root" must point to the root of the doc
tree (the place where cmds, doc, gml, and Hlp directories are located).
If you're wondering where the Hlp directory is, run mkdocs.bat/mkdocs.cmd
located in the bat directory. But first you'll need to do something like

 set doc_root=d:\OpenWatcom\docs

Add %doc_root%\cmds to your PATH. Your PATH must also contain the Watcom C/C++
binary directories appropriate for your host platform (for wmake). This is
taken care of automatically by using setvars.cmd/setvars.bat.

Note that to produce Windows and/or OS/2 online documentation, you will need
the appropriate SDKs and Toolkits containing the platform specific online
help compilers.


How it is organized
===================

Under the main directory are number of sub-directories.

.\gml	It is main directory for GML SCRIPT. It contains all GML support files.

.\doc	Main documentation source directory.

.\cmds	It contains arbitrary files for creating on-line help version (help compilers etc.).

.\mif	Contains makefiles for the documentation building system.

.\dos .\os2 .\win .\nt Here on-line help version are created for each operating system.

.\ps	Here the post script documentation is created.

.\html	Html version of the documentation is there.



How to Build Postscript Versions of the Documentation
=====================================================

Here are the steps to formatting a book for printing on a Postscript
printer.

You can run command  

builder rel2 ps

from documentation main directory to build all books.

If you want only one or a few books then you must go into ps sub-directory and
run command

wmake hbook=<bn>

where <bn> is one of

        c_readme            C/C++ Read Me First
        cguide              C/C++ User's Guide
        cguideq             C/C++ User's Guide for QNX
        clib                C Library Reference (for all systems except QNX)
        clib_nec            C Library Reference Kanji Functions subset
        clib_nt             C Library Reference for Win32 (Power++)
        clib_qnx            C Library Reference for QNX (stale)
        clib_tst            C Library Reference (for testing a subset of doc)
        cpplib              C++ Class Library Reference (current)
        f77graph            F77 Graphics Library Reference
        f_readme            F77 Read Me First
        fpguide             F77 Programmer's Guide
        ftools              F77 Tools User's Guide
        fuguide             F77 User's Guide
        guitool             Graphical Tools User's Guide
        lguide              Linker User's Guide
        pguide              C/C++ Programmer's Guide
        rcerrs              Resource Compiler Diagnostic Messages (obsolete)
        tools               C/C++ Tools User's Guide
        wasaxp              AXP Assembler User's Guide (obsolete)
        wd                  Debugger User's Guide
        wlinkerr            Linker Error Messages (obsolete)

The output file is of type ".ps". You should be able to send this to
any PostScript printer or view in GhostScript or convert to PDF or
whatever it is you do with PostScript files.


How to Build Online Help Versions of the Documentation
======================================================

For Microsoft Help format (both old and new help formats):

    All help files can be created by command

    builder rel2 os_win (for old win16 format only)

    or by

    builder rel2 os_nt (for new win32 format only).



    If you can build only one book than you must change current directory to
    win or nt sub-directory and you can use command

    wmake hbook=<book>

    where <book> is book code.


    The Win16 format help files (*.hlp) are created in the
    %doc_root%\win directory. The Win32 format help files (*.hlp,
    *.cnt) are cerated in the %doc_root%\nt directory.

For Watcom Help format (for Watcom WHELP command):

    Run 

    builder rel2 os_dos

    to create all online help.


    The WHELP format help files (*.ihp) are copied to the
    %doc_root%\dos directory.

For OS/2 Help format:

    Run 

    builder rel2 os_os2

    to create all the IPF files for the OS/2 IPF compiler.

    Transfer the IPF files, bitmap files, etc. to an OS/2 system.

    Look at cpos2.bat for an example of what needs to be copied and what
    directories are set up.

    Under OS/2:
    Define the doc_root environment variable.

    Run doit.cmd under OS/2 to produce the INF and HLP files.

    Look at doit.cmd for a hint on how to do one document at a time.
    Or read on if you're lazy.

    Note: If, under OS/2, you get a "memory exhausted" (out of memory)
    message from the IPF compiler then, under Win32, erase the WHP and IPF
    file for the document in question and recreate it (I don't understand
    why but it just makes the problem go away).  This problem usually only
    shows up for the CMIX and FMIX (master index) files (which are huge).

    The OS/2 format help files (*.INF, *.HLP) should be moved to the
    %doc_root%\os2 directory on the Win32 platform.

    To format one document at a time, go to the appropriate directory
    (for instance docs\os2) and run wmake with argument
    hbook=<book_name> where <book_name> is one of the online books listed
    above.


How to Update the Documentation
===============================

All the documentation is stored in ASCII text files with the file
extension "GML". The files are annotated with a combination of Script
and GML (Generalized Markup Language) tags.

The Script tags are of the form ".tag" (i.e., they begin with a period
and are followed by two or more letters or digits). Script tags will
be most familiar to anyone who has ever used Waterloo Script or IBM
Script. The tagged format is also similar in idea to other tagged
formatting systems like RUNOFF or ROFF.

The GML tags are of the form ":TAG." (i.e., they begin with a colon,
followed by some letters and digits and end with a period). GML tags
will be most familiar to anyone who has ever used IBM GML or Waterloo
GML. This tag set is a variant of SGML. The most familiar SGML tag
format is "<TAG>". In Watcom GML, the "<" and ">" are replaced by the
":" and ".".

The tag set includes a base set of predefined tags. In addition to
this base set, you can define an extended tag set using the built-in
macro language. The base Script tag set employs two letters (e.g.,
.dm, .if, .se, .cp, .us). The user-defined (extended set) can employ
two, three, four or more letters (e.g. .chapter, .section, .beglevel).
For a good example of user-defined Script tags, see
%doc_root%\doc\gml\fmtmacro.gml. GML tags can also be defined. For a
good example of user-defined GML tags, see %doc_root%\doc\gml\cppextra.gml.

These tags are described here for you, not so that you can begin defining
your own tags, but so that you will recognize them in the ASCII text
that comprises the documentation. But of course no-one's stopping you
from defining your own tags if you feel so inclined.

Here's a snippet from one of the doc files.

    .np
    The recommended options for generating the fastest 16-bit Intel code
    are:
    .ix 'fastest 16-bit code'
    .begnote
    .note Pentium Pro
    &sw.oneatx &sw.oh &sw.oi+ &sw.ei &sw.zp8 &sw.6 &sw.fpi87 &sw.fp6
    .note Pentium
    &sw.oneatx &sw.oh &sw.oi+ &sw.ei &sw.zp8 &sw.5 &sw.fpi87 &sw.fp5
    .note 486
    &sw.oneatx &sw.oh &sw.oi+ &sw.ei &sw.zp8 &sw.4 &sw.fpi87 &sw.fp3
    .note 386
    &sw.oneatx &sw.oh &sw.oi+ &sw.ei &sw.zp8 &sw.3 &sw.fpi87 &sw.fp3
    .note 286
    &sw.oneatx &sw.oh &sw.oi+ &sw.ei &sw.zp8 &sw.2 &sw.fpi87 &sw.fp2
    .note 186
    &sw.oneatx &sw.oh &sw.oi+ &sw.ei &sw.zp8 &sw.1 &sw.fpi87
    .note 8086
    &sw.oneatx &sw.oh &sw.oi+ &sw.ei &sw.zp8 &sw.0 &sw.fpi87
    .endnote
    .np
    The recommended options for generating the fastest 32-bit Intel code
    are:

The ".np" is a user-defined tag for "start a new paragraph". The ".ix"
creates an index entry in the index. It doesn't appear with the text.
In on-line help, this index entry becomes a searchable item. The
".begnote", ".note", and ".endnote" user-defined tags are used to
create an unordered list. Every piece of text entered into the source
file is identified by tags like these.

The best way to understand what the tags do is to look at a printed
copy of the document and see what it looks like.

The WATCOM GML program (WGML) is a compiler/interpreter that reads the
document's source files to produce an output file. In our case, we
want PostScript for printing and we want another form for generation
of online help. This second form is a non-printable form that is
suitable for post-processing to turn it into IPF for the OS/2 IPF
compiler, RTF for the WinHelp tools, special Watcom-defined format
for use with a DOS-based help tool (WHELP) or the ever-popular HTML.

If you are a programmer, you'll be somewhat comfortable with the whole
process of turning ASCII text into documentation. WGML is a text
processor (compiler) that reads a source file (GML) which, in turn,
imbeds other source files, and produces an output file (the object
file). WGML is very fast. It was very fast in the old 20MHz 386 days
and is, of course, much faster with today's processors. The C Library
Reference comprising 1,241 pages takes 2 1/2 minutes to format into
Postscript on a 400 MHz Pentium-II.


Diagnostic Messages
===================

If you see ***WARNING*** messages issued by WGML, you can ignore them.
If you see ***ERROR*** messages, you cannot ignore them.

Good Luck!
