HELP REFORMAT Diarmuid McIntyre, May 1993
This helpfile explains the use of the REFORMAT program. This program
automatically produces a hard copy manual, LaTeX formatted, from a set
of specified on-line REF files. Individual REF files can also be
formatted and displayed automatically.
/* THIS IS A DRAFT VERSION ONLY */
CONTENTS - (Use <ENTER> g to access required sections)
-- Introduction
-- Prerequisites
-- Running the Complete Program
-- Executing the REFORMAT Program
-- ... From the Pop-11 prompt
-- ... From VED
-- Previewing an Individual REF File.
-- Changing the Manuals Contents
-- Making more than one Manual
-- Adjusting the linking text
-- Making Your Own Manual
-- ... The Preamble and the Ending
-- ... The Title Page
-- ... The Table of Contents
-- ... Including a REF file
-- ... Subdividing your manual (grouping the chapters)
-- ... Further Subdividing your manual
-- How the Program works
-- Problems?
-- After Running the Program
-- A Note on Non-Existent References
-- Final Note - The Index and the Table of Contents-- Introduction -------------------------------------------------------
The REFORMAT program allows the user to creating a hard copy LATEXed
manual using only the REF files as they exist now, along with some bare
essential linking text.
The program allows the contents of the manual to be dynamically
updated whenever a REF file has been changed. By using only the latest
copy of a REF file, the manual is always assured of being in date.
-- Prerequisites ------------------------------------------------------
You must have the LATEX package available and be running Poplog with an
Xwindow system. Your systems installation should also include the
`xdvi' previewer. If it doesn't you should adapt the shell script
'makemanual' to use whatever LATEX previewer you have available. You
must also be on a SUN-4 or higher.
-- Running the Complete Program ---------------------------------------
In order to produce the manual the following actions must be carried
out.
¤ prepare a master file if one is not prepared already.
¤ run any REF files you are unsure about through the previewer.
¤ Run the program using one of the two methods outlined below.
These actions are explained below.
With both methods of running the REFORMAT program, wait while the
program is running. This can take anything from 2 minutes to several
hours depending on how large the master is and how fast the machine it
is being run on is. With each file included in the master, messages will
be echoed to the command line. These will give you feedback on which
stage the processing is at. If there are typing errors in the names of
the REF files to be used, then you will get a mishap.
Your current window will be frozen (except for the messages) while
the files are being formatted. When the master file is ready to be
LATEXed, an xterm will appear on you screen. This allows you both to
free your window and also to monitor the progress of the processing. As
long as LATEX only gives warnings things are fine.
The completed manual i.e ready to be printed, will be left in the
file MASTER_FILENAME_rf.dvi . A message will appear on screen informing
you of this when the manual preparation is complete.
Hopefully everything should run smoothly. Any REF files which you
decide to include should already have been checked using the ENTER
filepreview command by their writers or adjusters, to ensure that they
are in a fit state to be processed. If you are unsure about a REF file
then please run the relevant file through the previewer to save yourself
a lot of time and trouble. It can be quite frustrating for the last file
of a 500 page manual to cause trouble.
-- Executing the REFORMAT Program -------------------------------------
The following commands ask you to specify the full path name of the
relevant master file. This is not necessary if you are actually in the
directory containing the Master file.
NOTE: Due to the fact that the running of the program (or even the
previewer on exceptionally large files) requires a LOT(!) of memory, it
is advisable that you either extend your quota greatly or take on the
account of someone who has (i.e. a superuser). Making a manual which
includes the entire REF system takes approximately 10 megabytes.
-- ... From the Pop-11 prompt -----------------------------------------
The REFORMAT program is written in Pop-11. To run it from the Pop-11
prompt do
: lib reformat
: make_manual(FILENAME);
where FILENAME is the full pathname of a master file (enclosed in
quotes). The master files for the four Poplog reference manuals are in
$popmaster/C.all/lib/lib/reformat
They are named:
onemaster.tex
two_part1master.tex
two_part2master.tex
threemaster.tex
-- ... From VED -------------------------------------------------------
The REFORMAT program can also be run on a master file using an ENTER
command. This takes the form:
ENTER lib reformat
and then
ENTER makemanual FILENAME
where FILENAME is the full pathname of a master file.
-- Previewing an Individual REF File. ---------------------------------
If you have not already done so, you must make the REFORMAT program
available by doing:
ENTER lib reformat
If you are making an alteration to a REF file then you will have to
rename the file using
ENTER name <new_name>
before running the previewer program.
The previewing itself is done by giving the following command:
ENTER filepreview
This takes the current file, makes a copy of it and proceeds to prepare
and preview the file. Messages will appear on the command line to show
you what stage formatting is at. Once the file has been formatted, your
window will become unfrozen and an xterm will appear in which the
formatted version of the file will be processed by latex. You may
iconise this Xterm if you wish. It will disappear when you click on the
"QUIT" button of xdvi. The xterm is to allow you to monitor your files
progress.
The whole process should not take more than 10-15 minutes for the
largest of files. Of course once again the speed of the machine you are
using does come into play. However a short REF file (of say 100 lines)
should be able to be previewed in about two minutes. However, due to the
fact that the screen you are using will temporarily freeze up (during
the formatting stage), you should ensure that you have another window
available to you to continue working in. (or alternatively a nearby
kettle:-)).
A message on the status line when all is complete will tell you the
location of the processed version of your file the latex commands have
been inserted so that you can see what has happened to your text. The
command:
ENTER latex clear
will rid your current directory of any files created by this program.
-- Changing the Manuals Contents --------------------------------------
In order to change what REF files the manual contains, you must add or
delete a line saying:
\refinclude{filename}
where filename is an unquoted "vedprocs", "chario" etc. More details of
this are given below in the section on creating your own manual from
scratch. The example master file contains informative comments on what
to do as well.
If you wish to include a file from the LISP subsystem then you should
preface the filename with "lisp_'. This is necessary due to there being
some REF files whose names are duplicated across subsystems. Therefore
to include the file REF *ARRAYS from the LISP subsystem, do:
\refinclude{lisp_arrays}
As long as you preface like this then there is no problem including
files from different subsystems in the same manual.
SUSSEX NOTE: to include a VMS version of a REF file, preface the
filename with "vms_" i.e. "vms_sysutil". Once again you can pick and mix
files to be included.
It is good practice before making an addition of a REF file to ensure
that it adheres to the standards laid out in REF *REFORM and can thus be
recognised and represented properly by the REFORMAT program. This can be
done by previewing the file as detailed in the previous section.
-- Making more than one Manual ----------------------------------------
The LATEX capacity for labels restricts manuals to be under 500 pages.
This is also about the maximum size a manual can be easily handled.
However, the contents of the REF directorys currently amount to 1800
pages. Hence the Poplog reference manuals had to be divided up into 4.
Unfortunately this restriction means that cross-referencing is not
always possible. If a file is not included in the same manual as the
file being processed, then rerences to it and the identifiers defined in
it are not possible. A partial solution to this is available if you are
making a complete set of manuals. Executing the line:
:true -> all_reffiles_included;
causes the phrase "(included in another volume)" to be placed after
references to all REF files. Of course, if a REF file is included in the
same manual then a reference to "REF *ARRAYS" will be replaced by
"Chapter N".
-- Adjusting the linking text -----------------------------------------
The linking text is kept to a bare minimum. It is all contained within
the master file. The formatting in this is also kept minimal. You can
rewrite any of the text as long as you make sure that and surrounding
formatting instructions are not breached. Of course, if you are familiar
with Latex then feel free to play around.
It is a good idea, if you are adjusting the linking text, to temporarily
comment out each refinclude statement using '%'. This will prevent the
REF files being included and thus save you a lot on processing time. In
essence this will provide you with the manual "shell".
-- Making Your Own Manual ---------------------------------------------
It is possible for you to create your own manuals. All that this
requires is the creation of a master file. Currently the only files that
can be REFORMATed are REF files but this might change with further
releases. So it might be possible one day to includes a mixture of REF
TEACH and HELP files in a manual. This section takes you through the
hand creation of a masterfile for a manual. It tries to provide as many
templates as possible so that those who are unfamiliar with LaTeX can do
this easily.
-- ... The Preamble and the Ending -------------------------------------
These are read in for you. Nothing to be done here although latex
experts might wish to adjust them. The preamble is located in
$popmaster/C.all/lib/lib/reformat/rf.start.tex
and the ending in
$popmaster/C.all/lib/lib/reformat/rf.end.tex
These files include commands into your master file, dealing with page
size, latex options and the definition of new commands. The latter tells
where the manual input ends and at which point in the text (i.e. the
end) to include the input.
-- ... The Title Page -------------------------------------------------
Here is a sample, quite simple title page.
\begin{titlepage}
\vspace{4in}
\begin{center}
\LARGE
\bf
\vspace{2in}
{\Huge\bf POPLOG REFERENCE MANUAL}\\
Volume 1 \\
\vspace{1cm}
{\LARGE\bf Prepared and Formatted by Diarmuid McIntyre}\\
\vspace{0.6cm}
\date \\
\vspace{10cm}
{\large Based on the On-Line REF files \\}
\end{center}
unless you are a Latex expert, the simplest thing to do is to adjust the
text according to your needs. If you wish to design your own one, you
could always leave this out completely and insert one from another
source.
-- ... The Table of Contents ------------------------------------------
Directly after the titlepage (or on the second line if there is none)
add:
\tableofcontents
That's it really.
-- ... Including a REF file -------------------------------------------
for each REF file you want included have a line like:
\refinclude{FILENAME}
where FILENAME is the system name of the REF file. For example to
include REF *SYSIO do:
\refinclude{sysio}
This will appear in the manual as a chapter. The order you place these
'refinclude' statements in, determines the order of the chapters. Note
that if you refinclude REF *VEDPROCS, the chapter title will not be
"VEDPROCS" but "VED SYSTEM PROCEDURES" which is the on-line title of the
document. Don't forget to prefix LISP files (see above).
Well thats it really for creating the basic Manual. The next subsection
describes a way of dividing your Manual up into more meaningful chunks.
-- ... Subdividing your manual (grouping the chapters) ----------------
You might wish to divide your manual into distinct groupings of chapters
each dealing with a particular area. This is easily done. Just before
the first 'refinclude' statement in any grouping insert the line:
\part{NAME OF PART}
i.e.
\part{ASPECTS OF POPLOG}
If you do this, you will have to make sure that each REF file
belongs in a specific group. This is because the end of a "part" is
recognised by either the end of the file or a new "\part".
If you wish to include files which do not easily fall into any
category, a handy solution is to have a "part" at the end called
MISCELLAENEOUS.
-- ... Further Subdividing your manual --------------------------------
If your wish to sub group further, things get a wee bit more
complicated. Insert at the beginning of each subsubgroup, the following
two lines.
\part*{SUBSUBGROUPNAME}
i.e.
\part*{Data Structures}
Note the `*'. This is very important as otherwise the number of \parts
gets incremented by one. The same ideas as subgrouping apply here, The
end of a Subsubgroup is either an end of the file, a new "\part" or a
new "\part*".
It is recommended that you have \part names in UPPERCASE and \part*
names in LOWERCASE with a capital for the start of each word.
You might desire some text at the beginning of each template. Maybe
explaining the further subdivision. To do this, insert the following
template, just after the main \part.
\chapter*{}
\begin{flushright}
{\parbox{5.2in}{
This part of the manual is divided into 3 sections:
\begin{itemize}
\item The name of a subsubgroup i.e. see the next two
\item Syntax and Compilation
\item Mishaps
\end{itemize}
}}
This text here might explain the reason for doing this.
The {itemize} section produces a neat looking bullet list. You can, of
course modify this to suit your needs. i.e. dumping the list and having
more text.
Well thats it for creating your own master. See the section on "Creating
More than One Volume", if you wish to achieve this with your master
file.
-- How the Program works ----------------------------------------------
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 program 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 identifier 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.
For further details of the workings of the program, see REF *REFORMAT.
-- Problems? ----------------------------------------------------------
As mentioned above, deviation from the standards set out in the master
version of REF *REFFORM will cause errors.
You might wish to ask yourself the following questions before you run
the reformat command to preview the file or after you have encountered a
problem.
¤ Are you being consistent in your style of section headings?
¤ Are all the identifier types in square brackets, right justified
i.e.
[procedure]
¤ Are all your paragraphs (except those of one line paragraphs)
right-justified to column 72?
¤ Do your lists and tables conform to the standards laid out in the
master version of REF *REFFORM?
All the master versions REF files incorporated in the manual before now
have been tested to see that they work with the previewer. If the
REFORMAT command does not work i.e. it gets hung up, this is probably
due to an unpreviewed file being incorporated.
DO however remember to give the program time to work before using
CTRL-C. Dealing with VED attributed strings can take quite a while
(especially on big files).
If the formatting part of the program hangs up, then when you do CTRL-C
you will be put in a file test.tex in your current directory. The same
will happen if an error occurs. By examining the file and where Latex
substitutions stop, you should be able to work out the nature of the
error. If the error is not caused by a deviation from standards try
fiddling with the text a little. However, this should not be necessary.
If you find that the latex processor is stumbling over a
cross-referenced string then the simplest course of action is to remove
the bolding from the problem string.
-- After Running the Program ------------------------------------------
You now have a ready-to-be-printed manual. This is stored in
masterfilename_rf.dvi.
You can use any LATEX printing command i.e. dvips to print it out. Due
to its size the job might be too large for the printer. If this is the
case then you should consult your system support staff for how to print
it out in batches. One method using dvips is:
dvips -p=N -l=M -Pprintername masterfilename_rf
where N equal the first page to be printed and M, the last.
-- A Note on Non-Existent References ----------------------------------
After you have run the previewer or the REFORMAT program. You might want
to check the value of the Global variable:
non_existent_identifiers
This, as the name suggests, lists any references to identifiers which
the program thinks don't exist. This can occasionally happen if
documentation is written about a program one of whose component parts is
still in the programmers eye.
-- Final Note - The Index and the Table of Contents -------------------
Due to the fact that the manual is created completely automatically, the
Index only deals with identifiers. It is the table of contents that
should be referenced when searching for a subject topic. The table of
contents is generated from section and subsection headings in the REF
files as well as the titles of the REF files (which form the chapter
titles). The index is added to each time an identifier name appears.
In the index, the bolded page number after an entry is that on which
the identifier is actually defined as opposed to being mentioned in
conjunction with something else.
--- C.all/help/reformat
--- Copyright University of Sussex 1993. All rights reserved. ----------