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.


         CONTENTS - (Use <ENTER> g to access required sections)

  1   Introduction

  2   The Workings of the Program

  3   How a REF file is broken down

  4   How the Program Proceeds

  5   Program Identifiers




---------------
1  Introduction
---------------

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.



------------------------------
2  The Workings of the 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.



--------------------------------
3  How a REF file is broken down
--------------------------------
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.



---------------------------
4  How the Program Proceeds
---------------------------
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.



----------------------
5  Program Identifiers
----------------------

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.
