* ABOUT REFGEN ****

REFGEN enables GO to format PenPoint SDK header files into pages for
printing in the PenPoint API Reference.  We were able to write
REFGEN because all PenPoint header files conform to the header file
coding standard.  REFGEN takes advantage of the coding standard to
understand some of the text elements in the file, and then makes
assumptions, based on indentation and other formatting of the
comments to do the rest of its formatting.

Thus, REFGEN serves two purposes:

o  It formats header files for printing, but in doing so...

o  It checks the compliance of the header file to the coding
   standard.

The first part of this document describes how to run REFGEN.  The
PenPoint header files in \PENPOINT\SDK\INC follow the header file
coding standard (however, the header files for the WATCOM and ANSI C
libraries do not).  In addition to the header files, you can view the
header file template in \PENPOINT\SDK\SAMPLE\TEMPLATE.H.

The second part of this document describes the specific header file
formats that REFGEN looks for when it processes header file comments.

The third part of this document describes the parts of the REFGEN
style files.

* RUNNING REFGEN ****

To generate a document file from a header file, use the program
REFGEN.  If you copy REFGEN to your machine, you need three
files:

   REFGEN.EXE
   REF1.EXE
   REF2.EXE

REFGEN uses your current directory and then your PATH to find and run
the modules REF1 and REF2.  REF1 parses the header file and creates a
REFGEN intermediate file.  REF2 reads the intermediate file and
formats the text.

The syntax for REFGEN is relatively simple:

   REFGEN header-file rtf-file [-t table-file] [-i intermediate-file] /
          [-s style-file]

The header-file is the header file that you want to process and the
rtf-file is the name of an output RTF file.  Usually you will want to
use the same file name and change the extension.  If the rtf-file
exists already, REFGEN will overwrite it.  

The -t flag allows you to specify a separate file that will contain a
summary of the classes and messages defined in the header file.  If
you specify a table-file, the output RTF file is optional.  

The -i flag allows you to specify that you want to keep the
intermediate file and allows you to specify the name for that file.
Normally the intermediate file is deleted at the end of processing 
(normally you shouldn't need to use this flag).

The -s flag allows you to specify a separate style file.  By default, 
REFGEN produces an RTF file that uses three standard LaserWriter and
PenPoint fonts: Times, Helvetica, and Courier. However, you can
create a separate file that specifies how to format each of the text
elements.  This style file is described later in this document. 

In this example, the user creates an RTF file for SCRIBBLE.H

   D:\>refgen \penpoint\sdk\inc\scribble.h scribble.rtf

In this example, the user creates a message table for SCRIBBLE.H:

   D:\>refgen \penpoint\sdk\inc\scribble.h -t scribble.tbl


REVIEWING YOUR OUTPUT

When you run REFGEN, we recommend that you direct the output to an
error file.  For example:

   D:\>refgen scribble.h scribble.rtf >scribble.err

The most important thing to pay attention to are the messages
generated by REF1 (the first phase of processing).

 Fatal:  indicates that REF1 encountered a problem beyond which it 
   couldn't cope.  Fatal errors usually originate from file operations.

 Error:  indicates a deviation from the header file standard where 
   there is no way to second guess what you intended.  Chances are 
   that REF1 will not correctly process the lines immediately 
   following an error.

 Warning:  indicates a place where REF1 suspects that you didn't 
   conform to the header file standard.

 Fix up:  indicates a deviation from the header file standard for 
   which REF1 can assume the correct behavior.  In the future, 
   REF1 might be able to prompt you to fix up these errors.

Finally, if you see an Internal error, please report it to GO.

You should also print your document and make sure that it looks
reasonable on paper.  If something doesn't look right, take another
look at the header file standard.  

PRINTING YOUR DOCUMENT

Once you have the RTF file, you can run Word, Word for Windows, or
any other RTF-literate word processor to convert the RTF into
printable text.  You do not need to attach a style sheet to the
document (although Word will prompt you for one).  

RUNNING REFGEN IN PARTS

The program REFGEN is just a shell that invokes the two programs REF1
and REF2.  REF1 reads the header file and determines the purpose or
intent of each line.  REF1 produces an intermediate file in which
each line contains a label, a separator, and text, which can be
separated by more separator characters.  REF1 can also produce a
table that lists each of the messages defined in the header file.

REF2 reads the intermediate file and determines what formatting to
apply to each of the lines.  REF2 also does one or two other things. 
Each time REF2 finds a typedef, an Enum16, or an Enum32, it adds the
structure to a list.  Later, when a particular message says that it
takes a structure, REF2 looks in the list for the structure.  If the
structure is in the list, REF2 outputs the structure in the correct
place for the message description.  You can direct REF2 to print
these structures to a separate file when it is done.  Also REF2 can
create an index entry whenever a message, function, structure, or
macro is defined in the file.

The syntax for REF1 is:

	REF1 header-file intermediate-file [M n] [T table-file]

The M switch allows you to specify what level of warnings and errors
you receive from REF1.  M 1 (the default) directs REF1 to report all
messages; M 5 directs REF1 to report only internal errors.

The T switch allows you to specify a file to which REF1 will write a
table of all messages and functions defined in the header file.  

The syntax for REF2 is:

REF2 inter-file output-file [F format-file] [R "running-text"] /
     [T typedef-file]

The F switch allows you to specify a particular format file.  The
format file is described at the end of this document.

The R switch allows you to specify text that is used in a running
head or running foot (depending on the style file).

The T switch allows you to specify the name of the file that will
receive an ordered list of the typedefs and Enum16/32s found in the
file.  To reduce the number of errors generated by standard PenPoint
typedefs (such as OBJECT, U32, BOOLEAN, NULL, and so on), REF2
preloads these typedefs and assigns them null definitions.  You will
see these in the typedef file.


* HEADER FILE FORMATS ****

This section describes the specific formats that REFGEN looks for and
the resulting format that REFGEN gives the text.  Again, look at the
template header file, TEMPLATE.H for examples.

HEADS

REFGEN allows you to include two-levels of heads in your document. 
You specify a first-level head by creating a box such as the one
shown here.  The text in the box is used as the first-level head. 
 
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 *					Common #defines and typedefs						   *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

To create a second-level head, create a line such as the one shown
here.  The text in the line is used as the second-level head.

/****  Info Style  ****/

PLAIN TEXT

REFGEN attempts to format all text in comments.  A series of lines in
comments that are indented by one space are grouped and formatted as
a single paragraph.  You indicate paragraph breaks by adding a blank
line between paragraphs.

If you want text to be gathered into a single paragraph, but you want
the line breaks to occur exactly where you specify, indent the text
by four spaces.

In this example, the first two paragraphs ("Note the..." and "Here's
the...) are grouped into separate paragraphs. The lines "the
sender..." and "the receiver..." appear as separate lines, as the
user intended.

/*
 (Note the use of "Passes back" instead of "Returns the current style values."
 The msgXxx line says "returns STATUS": don't contradict this in the 
 brief description.  Note also how this long paragraph (which will appear
 under "Comments" in the datasheet) has one space in front.  Also note how
 the brief description is in active voice.

 Here's the rule:
     the sender "specifies"       (In: parameters, the default)
     the receiver "passes back"   (Out: parameters)
 */

LISTS

You can create three types of lists in REFGEN. The first form simply
uses the indented lines (as shown above), which format as a
paragraph with forced line breaks.  Use this form for listing terms
or keywords without definitions.

/*
 The colors are :
    red
    white
    blue
 */

The second form is a bulleted list.  To create a bulleted list,
indent the first line by four spaces and begin the text with a
hyphen, colon, and one or more spaces ("-: ").  If the text runs to
additional lines, align the beginning of the following lines with the
beginning of the text (not the hyphen).

/*  
 There are three types of lists:
    -: Simple lists which are a variation of the forced line breaking
       paragraphs.
    -: Bulleted lists.
    -: Term definition lists.
 */

The third form is a term definition list.  To create a term
definition list, indent the first line by four spaces and type in the
term.  End the term with a colon and one or more spaces (similar to a
bulleted list).  If the text runs to additional lines, align the
beginning of the following lines with the beginning of the text (not
the term).

/*
 The fields you commonly set are:
    pArgs->win.bounds.size:  Size of thing if you don't lay it out.
    pArgs->thing.pString:    Name for thing. The name can be in  
                             upper- or lowercase characters.
 */

CODE EXAMPLES

If you have examples in your text that you want to format as a code
example (which uses a mono-spaced font) rather than as plain text,
begin the code example with "//{", beginning in column one on a line
by itself.  End the code example with "//}", again beginning on
column one on a line by itself.

/*
 Zeroes out pArgs->thing and sets
//{
	pArgs->border.style.edge        = bsEdgeAll;
	pArgs->control.style.previewing = true;
	pArgs->control.client           = OSThisApp;
	pArgs->thing.style.scaleUnits   = lsScaleLayoutUnits;
	pArgs->thing.scale              = lsScaleNormal;
//}
 Sets pArgs->thing.font to the default system font.
 */

PRIVATE TEXT

If you have text that you don't want to appear in the printed
document, bracket the text or code with "//REFGEN BEGINIGNORE" and
"//REFGEN ENDIGNORE".  This text should be on a line by itself and
should begin in column one.

//REFGEN BEGINIGNORE
/*
 These are private messages that only knowlegeable users should send
   ...
 */
//REFGEN ENDIGNORE

* STYLE FILES ****

This section describes the REFGEN style files and how to use them. 
The two style files made available with REFGEN, API.STL and
GENRTF.STL depict common RTF usage.  

  * NOTE * Style files are relatively new to REFGEN.  
           The style files and the definitions provided here 
           may change somewhat in the future.

The style files have a required set of text formats that must be
defined.  If these formats are not all defined, REF2 will terminate
operation (with an indication of the formats that were not defined).

The style file consists of a series of text lines.  A line that
begins with a colon (:) (while not in a definition) marks the
beginning of a definition.  The definition is ended with a line
containing :END.  While in a definition, all text is taken literally,
including spaces and blank lines.  Spaces at the end of a line can be
significant and are therefore left alone.

However, outside of a definition, blank lines and lines that begin
with an exclamation point (!) are ignored.

TWO KEYWORDS

The style file must set two keys.  The first. :STYLE, simply specifies
the formatter for which output is destined.  The second,
:INDEXPOSITION, specifies whether index entries must be added before
paragraph descriptions or after.  RTF output uses AFTER; Ventura
Publisher, the other main destination of REF2 output requires BEFORE.

:STYLE = RTF
:INDEXPOSITION = AFTER 

CHARACTER REPLACEMENT

Most formatters have escape characters that it uses to denote the
start of a command.  Of course, when this character appears in text,
you must double it, or provide some other form of escape or keyword. 
Other formatters have keywords that specify particular non-ASCII
characters, such as em-dashes and so on.
Some formatters are sensitive to the first character only,
others take an escape character anywhere in the line.  

The style file allows you to define two sets of replacement
characters: first characters and all characters.  The definition
begins with either the identifier :FIRSTCHARS or :CHARACTERS.  The
identifer line also contains a character, which defines a separator
character.  The following lines, up to the next :END specify the
character to replace, the separator specified with :FIRSTCHARS or
:CHARACTERS, and the text to replace the character with.  

:FIRSTCHARS is needed by Ventura Publisher, because an at sign at the
beginning of a line must be doubled:  For Ventura Publisher,
:FIRSTCHARS would be:

:FIRSTCHARS |
@|@@
:END

This :CHARACTERS describes the replacement characters used
by RTF:

:CHARACTERS | 
{|\{
}|\}
(a tab)|\tab 
\|\\
-|\_
|\line
:END

THE DEFINITIONS

The following sections describe the rest of the definition sections
in the style file.  The definition is followed by the replaceable
values used in the string.  See the GENRTF.STL file for usage
details.

:INITFILE 
%d %d %d %d %d %d
Describes information used to initialize the output document.  When
output, this text specifies the revision time (month, day, year)
and creation time (month, day, year).

:DEFINITIONS
Contains the style sheet for the document. 

:H2
%s
Defines the format for a level-2 head.  The replaceable value is the 
head text.

:H3
%s
Defines the format for a level-3 head.  The replaceable value is the 
head text.

:RUNHEADINIT 
Defines the fixed portion of the running head or foot.  


:RUNNINGHEAD
%s
Defines the variable portion of the running head or foot.  The
replaceable text is the running text.  This text is passed in to REF2
with the R flag.

:RF 
Defines the format for the reference headers (used to format
"Message Arguments" and "Comments").

:CP
Defines the format to use for code paragraphs.

:INDEXPARA
%s
Defines the formats used to output an index entry.  The replaceable
text is the actual index entry.

:LINE
%s
Defines the formats used to output a line of text followed by a
forced new-line.  The replaceable text contains the text to be
displayed before the line.  This is the same as :TEXTLINE.
:END

:INITTEXT
Defines the formats used for body text.

:LISTITEM
Defines the formats used for a descriptive list of items.

:INDENTLIST
Defines the formats used for a bulleted list.

:CODESPACE
Defines the formats for an empty code line.  This allows you to save
text space by making reducing the size of blank lines in text.

:GOCODEBEGIN
Defines the character formatting used to begin a GO code entry
(class, message, status, or function name). 

:GOCODEEND
Defines the character formatting used to end a GO code entry.

:GOTYPEBEGIN
Defines the character formatting used to begin a GO type entry (all
cap structure names).

:GOTYPEEND
Defines the character formatting used to end a GO type entry.

:FNAMEBEGIN
Defines the character formatting used to begin a file name.

:FNAMEEND
Defines the character formatting used to end a file name.

:ENDOFFILE
Defines the formats used to end a file.

:ENDOFLINE
Defines the formats used to end a paragraph.

:NEWLINE
Defines the formats used to force a new line.

:TEXTPARA
%s
Defines the formats used to output a line of text followed by a
new paragraph.  The replaceable text contains the text to be
displayed before the new paragraph.

:TEXTLINE
%s
Defines the formats used to output a line of text followed by a
forced new-line.  The replaceable text contains the text to be
displayed before the line.  This is the same as :LINE.
:END

:EMSPACE
Defines the characters used to output an em-space.

:SEPARATOR 
Defines the characters used to separate a descriptive list
item from its text.  Usually this is two spaces, an em-space, or a
space, a dash, and a space.

:BULLET
Defines the characters used to create a bullet in a bulleted list.

..........................end of document.....................

