How to make your own manual, WWW pages, etc. (DOSELF)

Introduction.

The menu DOSELF holds some routines that we use to do program maintenance. You are not supposed to even know that this menu exists. However, feel free to abuse WHAT IF to make your own hypertext documentation, etc.

Put text for placeholders in a WHAT IF source module (DOCUWI)

WHAT IF has almost no flat text in its source code. Most text strings are replaced by a placeholder (that starts with a questionmark) that is replaced by the real text upon writing to the output device. The real texts can be found in the file MESSAGES.TXT in the dbdata directory. To make the source code somewhat readable again, the real text can be inserted in the source code as a comment above the line where it ocurrs. This can be done tediously manual, or automaticlly with the DOCUWI option. All inserted comments start with a C followed by a question mark. This is done to allow for easy removal by a script.

Fortran pretty printer (PRETTY)

FORTRAN source code is not always equally nicely readable. The command PRETTY can be used to make a very nicely readable listing of WHAT IF source code modules.

This pretty printer relies heavily on our coding conventions, and can not be used as a general FORTRAN pretty printer. We stick, among others, to the following rules:

Subroutine and function definitions start in column 7.

Do not use TABs, but always type out the blanks.

Function names are explicitly declared.

Module headers start with a C and three forward slashes, and are terminated with three back slashes.

Comments start with a C.

Include files are included using the INCLUDE statement.

Subroutine names are followed by a blank and an opening bracket, function names are followed directly by the bracket.

Copyright notices start with C.---

Probably we stick to several more conventions that were not realy designed, but historically grew. With projects the size of WHAT IF one has to stick to many conventions rather rigurously, otherwise after a couple of years it becomes unreadable spaghetti.

The output is in postscript format. Comments are in bold. Copyright notices are removed. Placeholder comments are in Italics. There are 120 lines per page.

Count types of statements (COUNTR)

The command COUNTR will prompt you for a list of module names. If the source code adheres to the (very highh) WHAT IF coding standards, the following will be counted per module:
Total lines     
Comment lines   
Copyright lines 
Compiler directives
Executable source lines    
Empty lines     
GVS tools calls (GVS subroutines and functions are guaranteed bug free)
Modules         
Subroutines     
Functions       
Output calls without textstring placeholders
Output calls with textstring placeholders
Implicit none statements  
Format statements without placeholders         
Characters non-blank
Characters blank

RUNOFF emulator

The WHAT IF documentation is written in the very old Digital RUNOFF format. This seems rather clumsy, but the advantage is that these are very easy to parse flat text files. WHAT IF has several facilities to make more useful files out of these files. :

RUNOFF emulation (RUNOFF)

The command RUNOFF will prompt you for the name of an input runoff file, an output mem file (human readable, and nicely formatted), and a postscript file.

RUNOFF emulation (RUNALL)

The command RUNALL prompts you for a file with runoff format file names. It will automatically (without futher prompting) run the RUNOFF option on all the runoff files. The file 'tex.list' in the writeup direction provides an example of such a file of files.

This option is used to convert the documentation into WHAT IF help files.

Create the writeup (TEXALL)

The writeup can be converted into a Latex document with the command TEXALL. The same 'tex.list' input file is needed as for RUNALL. Make sure that any files 'manual.*' are deleted from the directory before you run this option. After the TEXALL option you HAVE to terminate the program with the FULLSTOP option.

You have to type:

latex manual.tex
makeindex manual
latex manual
Thereafter you run 'xdvi manual.dvi' to preview (or dvips manual.dvi and ghostview manual.ps, or any other conversion). We use dvips to get a postscript file that gets printed.

The latex output can be converted to completey index and cross referenced HTML with the script xxx.

Translate the source code into other languages (CHKMES)

WHAT IF can run in Dutch after typing the command DUTCH. In order for this to work, all textstrings in the MESSAGES.TXT file need to be present in Dutch. The command CHKMES (combined with the file TRANSL.FIL in the writeup directory) was used to do large parts of this translation.

The RUNOFF format

The best way of figuring out which RUNOFF command subset we use, is to look in the .rno files in the writeup directory. A brief summary follows:

RUNOFF files are flat files of textlines no longer than 132 characters, but preferably shorter than 80 characters. RUNOFF directives can be put inbetween the text. Directives start with a period as the first character on the line. The next two till four positions are used for the actual directive (.NMCH .CH .HL .X .BR .LT or .EL). No other directives are supported. There can only be one directive per line. Directives can be followed by a directive textstring or a number. the following directives can be used:

 .NMCH xx    (where xx is the chapter number)
 .CH   xx    (where xx is the chapter title)
 .HL   xx    (where xx is a header level 1 for a paragraph,
              2 for a sub-paragraph, 3 for a sub-sub-paragraph,
              etc.)
 .LT         (To start literal text, this will not be justified
              etc. during the conversion)
 .EL         (To indicate the end of literal text)
 .BR         (To start on a new line)
 .X    xx    (Where xx is a text string to make an entry in
              the index table).
The .HL lines can be closed by a word in brackets. If this word is found anywhere in the text in capitals, a cross reference is create in the WWW page.