REF REFORMAT Diarmuid McIntyre April 1993
Revised D. McIntyre July 1993
COPYRIGHT University of Sussex 1993. All Rights Reserved.
/* THIS IS A DRAFT VERSION ONLY */
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< THE REFORMAT PACKAGE >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
This file briefly describes the procedures and variables used to implement the REFORMAT program, which can be used to automatically create hard copy LATEXed manuals from the on line REF files. For details of how to use the REFORMAT package and altering it for your own use, see HELP * REFORMAT.
Select headings to return to index
The REFORMAT program allows the user to create a hardcopy manual for Poplog using only the REF files as they exist now. For this purpose, the user can utilise the Poplog Manual master files which are located in the directory
$usepop/C.all/lib/lib/reformat
Alternatively the user can create their own master file using a file in from the above directory as a guide.
A master file simply specifies what REF files are to be included and in which order, along with some simple commands dealing with the table of contents and the sub division of the manual. The creation of a new master file from scratch is dealt with in HELP * REFORMAT.
The flexibility of the program allows the contents of a manual to be dynamically updated whenever a REF file has been changed. By using only the latest copy of REF files, the manual is always assured of being in date.
This REF file deals mainly with the syntax of the top level procedures which are accessible to the user. Included are some procedures which are used at a low level by the REFORMAT Library but which the user might find handy, when attempting to find errors in their input to the REFORMAT program.
This section gives a brief overview of the working of the program. It is given merely to aid understanding. The program itself is comprehensively documented and commented. Those wishing to modify the program in some way are directed to LIB * REFORMAT.
The REFORMAT program can be divided up into 4 distinct parts which are co-ordinated by the control procedures detailed in the main text below.
# The preparation stage
Where globals are declared and initialised, libraries which are needed are loaded, and various important VED variables (i.e. vedediting) given new values.
Each specified file, in its turn, is stripped of certain on-line features no longer necessary and occasional substitutions made.
# The formatting stage
This essentially goes from the top downwards of each specified file, placing the text in appropriate environments. The next section details what types of environments there are. Environments are generally one-dimensional. However due to the indented nature of the REF files, allowance has been made for recursive embedding of environments. When an embedded environment is entered into, the global indentation variables are saved and then restored when the embedding ends.
# The postformatting stage.
This deals with the small scale substitution of text and cross references. The substitutions are a mixture of cosmetic improvements, and changes necessary to the running of the LATEX program.
When a cross reference occurs, either to an identifier or to a file, the program insures that if the source is included in the manual then the appropriate chapter or page number is mentioned. Identifier references are then added to the index.
Dstrings are also dealt with at this stage. A VED attribute will cause a problem for the LATEX processor. Therefore all attributes are stripped and the text placed in a corresponding LATEX environment.
# The LATEXing stage
The files outputted by the above stages form a LATEX document. This has to be processed several times in order to resolve cross references and to include the "table of contents" and the "index" which will be generated. This is done by means of the makemanual shell script. The shell script is executed within the main control procedure makemanual. The processing is actually done within a specially created xterm which disappears when processing is complete.
The control procedures combine the first three of the above stages and apply them to whatever REF files are specified either individually or in a master file.
The REFORMAT program works by recognising certain features in a REF file and surrounding these features with LATEX commands so that they are represented properly. The recognition of the features is based upon the standards laid out in REF * REFFORM. Deviations from these standards will cause the feature to either be mistakenly identified or not to be recognised at all. In either case, error will follow.
The REFORMAT divides a REF file into the following components:
Component Recogniseable form
--------- ------------------
Program Code Marked by a \Sp character at the beginning of
each line of code. (including blank lines
between procedures).
Table Laid out like this, with underlined
headings above each column. Note also the right
justification of the various columns.
Bullet List Lists marked with a 'o' or '#' (\G#).
Enumerated List A list with each entry marked by a letter or
a number in the form '1)' '(A)' or 'B.'
Descriptive List A list with the descriptive text either one
line (at least two spaces right of the item)
or a left justified paragraph starting the line
immediately below the item (indented by 4
columns).
Diagrams These are simply marked as for program code.
However VED graphics characters will be
replaced appropriately.
Text Paragraphs As per normal. Any one line paragraphs shorter
than 72 characters should NOT have any double
spaces in them.
Identifier heading One or more lines dealing with the syntax form
of an identifier. The type of identifier is
named between square brackets on the far right
of the first line.
REF *REFFORM provides much more comprehensive details of how text structures should be formatted.
Also Recognised are Section (sub)Headings of both the old style and new style. Once again, see REF *REFFORM and REF *REFFORM_OLD for details of these.
The program proceeds by stripping each named REF file of unnecessary detail, such as the copyright notice, the contents listing (if there is an overview present), and the header arrows. The first heading is then dealt with. The style of the first heading determines how the rest of the file will be treated. The program then attempts to match the following text to one of the categories in the previous section. It then inserts the necessary formatting commands. This process continues until the end of the section which is marked by (at least) 3 consecutive blank lines.
The above process then repeats until the end of the file (marked by <termin>).
If an identifier entry heading is found then the following represented text is indented. At the end of an identifer entry, (2 blank lines) indentation returns to normal. Whilst in an identifier entry, the search continues for all component parts as before but section and identifier entry headings are excluded from the checklist. In general, text which is indented in the on-line REF file is kept indented.
Finally, a series of procedures are run which deals with the small scale substitution of text and cross references. All valid cross reference are added to the index.
The output of the above will be included as a chapter in a manual, processed by LATEX (several times in order to get the cross references right, and create the index. The LATEX processing is done in a specially created xterm so the user can monitor its progress.
makemanual(string) [procedure]
This is the main procedure. string is the name of a master file. It creates a list containing each of the REF files which is named in the master file (by a 'refinclude' statement) and then proceeds to prepare a LATEX version of each one. A copy of the master file is made and a preamble and ending tacked on. This copy is named:
string_rf.tex
It is this that provides the input to the makemanual shell-script. Make_manual uses this script to runs the LATEX command several times and prepare the index, leaving the output file in:
string_rf.dvi
ved_makemanual(string) [procedure]
This is simply an ENTER command version of the makemanual procedure. It uses vedargument to get the string. If vedargument is null then an error message is given.
all_reffiles_included -> bool [variable]
bool -> all_reffiles_included
If bool is true then each textual reference to a REF file will be followed by the phrase "(included in another Volume)". True should only be assigned to all_reffiles_included if a complete set of manuals is being generated. Its default value is false.
non_existent_identifiers [variable]
At the end of a run of the REFORMAT program on a REF file, this list holds the names of any cross references to identifiers which do not exist with within the Poplog system. It ascertains this by using a call to sys_search_doc_index with the identifier name and the appropriate REF directory as arguments. This will occur in the cases of a mis-spelling or a REF writer having named an identifier which has not yet been programmed, or is in library.
whole_file_action() [procedure]
This is the system control procedure for formatting individual files but it can be accessed to good effect by the user. It allow the user to process the file they are in without going through the rigmarole of the filepreview program.
Simply put, executing this procedure will cause LATEX formatting commands to be placed in the current file, and whatever preprocessing or substitutions needs to be done, are done. The end result is not a LATEX stand-alone document but it is a useful command both to see the process at work, and to find out which bit of a file causes problems.
IMPORTANT NOTE: Since this command works on the current file, it is best to run it on a copy rather than an original as the original will be lost.
ved_filepreview() [procedure]
This ENTER command allows to user to preview the current REF file which they are working on as a fully fledged chapter in the manual. It does this by creating a copy of the file, running the REFORMAT program on it, then placing this within a false manual shell. This is then run through the LATEX and xdvi UNIX programs. It leaves the user back in the original file which is unchanged. The user can then inspect the files created, to make any changes to the original as necessary.
The files created by the above command can (and should!) be removed using the:
ENTER latex clear
command. See HELP * VED_LATEX for more details of this.
--- C.all/ref/reformat --- Copyright University of Sussex 1993. All rights reserved.