Configuring the Manual Compiler

     MC is a powerful application you can use to create references for your
programs.  One of the bases for its power is its flexibility and how it can
adapt to almost any situation.  In this chapter, we deal with how to configure
the program for your specific task.

%SECTION%MANUAL.CFG: Controlling the result

     The one constant throughout a manual is its appearance and structure,
which is controlled through the MANUAL.CFG file.  Here is a sample MANUAL.CFG,
that was used to create an earlier version of this manual:

MANUAL.CFG:
 ; Manual Configuration

 ; Manual Name
 ManualName = MANUAL.DOC

 ; Spaces to indent each new TOC entry
 ContentsIndent = 3

 ; Lines after each TOC entry
 ContentsLines = 1

 ; Total lines per page (60 is best for 8.5" x 11")
 LinesPerPage = 60

 ; Paginate manual? 0/1 - No/Yes
 Paginate = 0

 ---
 ; End of manual configuration, do not remove the three dashes

 ; Format Configuration
 //ContentsMessage
 %CENTER%
 %CENTER%Table of Contents
 %CENTER%
 //ContentsTopic
 %CONTENTNUM% %CONTENTNAME%
 //Section
 %CENTER%
 %CENTER%%SECTIONNUM% - %SECTIONNAME%
 %CENTER%
 //Subtopic
  %SUBNUM% %SUBNAME%
 //PageHeader
 //PageFooter
 %CENTER%MC v1.00 - Page %PAGE%
 ---
 ; End of format configuration, do not remove the three dashes

     Note: the %CENTER% token can be used anywhere in the MANUAL.CFG file to
center a line of text.  The example here (as is the case with the other
examples containing replacable tokens) is set right one column to prevent the
program from parsing the tokens.

     As you can see, there are two basic parts to the file.  The first is a     
section that controls the mechanics of the creation of the manual.  Here is 
an explaination of the commands used in the first part:

ManualName: The name used for the final copy of the manual.  Defaults to
            MANUAL.DOC if none specified.

ContentsIdent: Controls how many spaces the subtopics are indented in 
               relation to the main topic.  With a ContentsIdent of 5, a 
               TOC may look like this:

1.0 Main Topic . . . . . . .
     1.1 Sub Topic 1 . . . . 
     1.2 Sub Topic 2 . . . .

LinesPerPage: Controls the amount of lines to place on each page during the
              pagination process.  Anywhere from 55-60 is a good amount for
              a regular 8" x 11" (letter format) sheet, depending on the
              length of the headers/footers.

Paginate: Controls whether or not the document is paginated.  If not, the
          pagination process is replaced by a drafting process (slightly, but
          not siginificantly faster), the page headers/footers are not added
          and the table of contents does not contain page numbers.  Good for
          manuals that won't be printed, but read from DOS instead.

     The second section of the file controls the aesthetic parts of the
manual.  Each section must be terminated by the start of another as shown in
the example.  Here is an explaination of the sections:

ContentsMessage: Controls the message that is placed at the top of the TOC 
                 page, after the header if no %NEWPAGE% token is found in the 
                 header.  It is usually a title saying "Table of Contents" in 
                 some way.  It contains no tokens.

ContentsTopic: Controls the format of a TOC entry.  The %CONTENTNUM% token
               is replaced by the section number of the entry and the 
               %CONTENTNAME% token is replaced by the topic.  If the entry is
               a subtopic, it is indented ContentsIndent spaces.

Section: Controls the format of a section heading.  The %SECTIONNUM% token is 
         replaced by the section number (ie: 1.0, 2.0) and the %SECTIONNAME% 
         token is replaced by the topic.  
                 
Subtopic: Controls the format of a subtopic.  The %SUBNUM% tokes is replaced
          by the subsection number (ie: 1.4, 2.3, 5.2) and the %SUBNAME% is
          replaced by the topic.

PageHeader: Controls the text placed at the top of each page.  If it contains
           a %PAGE% token, it is replaced with the current page number.

PageFooter: Controls the text placed at the bottom of each page.  If it
           contains a %PAGE% token, it is replaced with the current page
           number.

%SECTION%HEADER.CFG: Sending a message

     To customize the manual, you need to create a header which gives a sort
of "ad" to anyone reading it.  It usually contains such information as the
name of the program, your name, copyright info and maybe even a recent 
revision list.  If you don't want the header to be on the same page as the 
Table of Contents (more like a title page), just add a %NEWPAGE% token at the
bottom of the file.  This will place a page break after the header and start
the TOC at the top of the next page.  If you don't want a header for some 
reason, just create a blank file for HEADER.CFG, which will put the TOC on the
first page.

%SECTION%*.TXT: Writing the body of the manual

     To create a section of the manual, you must start up your text editor
and create an ascii file containing your information.  The format of a 
section entry is basically:  (the greater-than and less-than signs are not
required, they are used to encapsulate each part)

 <description>
 < text
   text
   text >  

     The first line of the file is used as the topic for the section header
and the entry in the TOC.  If you want to create subtopics in your section,
use the %SECTION% token like so:

 <description>
 < text
   text
   text >  
 %SECTION%<sectionname1>
 < text
   text
   text >  
 %SECTION%<sectionname2>
 < text
   text
   text >  

     This will create a section with two subsections.  It's TOC entry would
look something like this:

1.0 <description> . . . . . . 
 1.1 <sectionname1> . . . . .
 1.2 <sectionname2> . . . . .

     Another feature available to manual authors is the %CENTER% token,
which can be used to center a line of text in the manual.  To use it, just
place it at the beginning of the line like so:

 This text is right-justified
 %CENTER%This text is centered

     One of the more useful tokens is the %NEWSECTION% token.  It can be used
to place multiple sections inside a single file, effectively creating a
"package" of sections.  These sections can be moved around as if they were a
single unit.  Just place it one the last line of the previous section and it
will act as if the next line was the beginning of a new file, like so:

 This is section 1.0
 %SECTION%This is subsection 1.1
 %NEWSECTION
 And this is section 2.0

     Creating a TOC somewhat like this:

1.0 This is section 1.0 . . . . . . . .
 1.1 This is subsection 1.1 . . . . . .

2.0 And this is section 2.0 . . . . . .

     That's all there is to creating each section.  Read the section on 
"SECTIONS.CFG" and do a little bit of experimentation on your own if you want
to utilize your entries to the extent of the compiler's power.

%SECTION%SECTIONS.CFG: Tying it all together

     Once you've created all of your entries, you must create the file which
contains the order of the sections.  It looks something like this:

; Section Order
LEGAL.TXT
FORMAT.TXT
ENTRIES.TXT
SECTIONS.TXT

     This would assign a section number of 1.* to the LEGAL.TXT entry, a
section number of 2.* to the FORMAT.TXT entry and so on.  Changing the order
of this would change the order in the Table of Contents and in the final 
compilation of the manual.  Make sure that sections are not referenced by 
number in the text of your entries, since they are quite subject to change 
from this file.  

     The approach offered by the structure of the program's data files lends
itself to a sort of "plug and play" approach.  You can create one file for a
specific purpose (ie: a legal section or a "how to contact" section) and just
copy it from manual to manual with a simple edit of the SECTIONS.CFG file and
a single COPY command from DOS.
 
%SECTION%MACROS.CFG: Replacable Macros

     To save time in the creation of your manual, you should put some often
used information into a macro.  This will allow you to place it around the
document (header/footer, header file, body), where it will be replaced by
the compiler with its value.  Here is a sample MACROS.CFG file:

; Version Number
//VERSION
v1.03

; Copyright Years
//CYEARS
1995

     The macro definition begins with '//', followed by the name of the macro
that will be embedded in the document.  The next line is the data that the
compiler will replace it with.

Restrictions:
 - Each macro can only be one line
 - Only 10 macros are allowed
 - Tokens inside macros will *not* be parsed (with the exception of macros
   that occur _later_ in the file)

     Since the compiler will search for the macro name surrounded by two
percent signs (%VERSION%, %CYEARS%), this line:

Macro Compiler %VERSION% - Copyright %CYEARS% by Matthew Mastracci

     Will be replaced by:

Macro Compiler v1.03 - Copyright 1995 by Matthew Mastracci

     Nice, eh?