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= where 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 wgmlref Watcom Script/GML Tutorial and Reference Manual 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= where 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= where 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 "". 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!