Search Top Index
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. ----------