Search Top Index
REF REFFORM John Gibson, Jun 1987 Revised: A.Sloman, Jan 1990 Revised: A.Howard, Jul 1990 Revised: D.McIntyre, May 1993 COPYRIGHT University of Sussex 1993. All Rights Reserved. >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< THE FORMAT OF REF FILES >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< This file specifies the format for REF files which Sussex uses and recommends, listing various procedures to help adhere to these standards. Note that from Version 14.22 of Poplog onwards, the system REF files have taken on a new look. This file details the new standards that accompany that look. When it comes to writing your own REF files, you can of course stick to the old style. Details of the old style are now in REF * REFFORM_OLD. CONTENTS - (Use <ENTER> g to access required sections) 1 Introduction 2 The REFORMAT Program 3 Format of REF Files 3.1 Example Template REF File 3.2 The Header 3.3 The Title 3.4 The Overview 3.5 The Contents 3.6 Sections and Section-Header Formats 4 Table Format 5 Paragraph Format 6 Verbatim Text 7 Program Code 8 Lists 8.1 Enumerated Lists 8.2 Bullet Lists 8.3 Descriptive Lists 9 The Use of VED Character Attributes 10 Quoting Things 11 Identifier Entries 11.1 Example identifier entries 11.2 Standard Type Names for Arguments/Results ... Basic Types (Excluding Numbers) ... Numbers ... Other types ... Prolog types 12 Useful utility procedures 13 Further Documentation --------------- 1 Introduction --------------- This file sets out the standard format for Poplog REF files. This format is used by the library program LIB * MKREFINDEX (which builds an index of the identifiers documented by a set of REF files.) For more general information on formatting online documentation, HELP and TEACH files, libraries, etc. see HELP * STANDARDS. ----------------------- 2 The REFORMAT Program ----------------------- After Poplog 14.22 there will a program in existence called REFORMAT. The purpose of this program is to enable the user to automatically create a hard copy manual from the REF files. This is done dynamically using the most current edition of a REF file. The programs uses the various standards laid out in this file to divide a given REF file into text blocks which it then wraps in LaTeX code. More details of the workings of the program are given in REF * REFORMAT and HELP * REFORMAT. It is crucial to the workings of this program that each REF file be acceptable input to the program. There has been no changes in the standards but there has been a tightening up. For LIB * REFORMAT to work then the standards specified in this file must be rigorously adhered too. The Sussex REF files will already have been prepared for LIB * REFORMAT. However if you locally change a Sussex REF file you should make sure that the changes are compatible with the REFORMAT program. A special previewer has been written to enable you to see a REF file as a potential chapter in a manual. To preview a file using LIB * REFORMAT do <ENTER> lib reformat then <ENTER> filepreview Depending on the length of the file, after 2-10 minutes a dvi version of the file will appear on your screen using xdvi. See HELP * REFORMAT for more details. If this previewer does not work on your newly changed REF file, then you have either discovered a bug in the program or your changes have slipped up in their adherence to standards set out in this file. REMEMBER: Small errors which you can get away with on-line become really obvious when nicely printed out. ---------------------- 3 Format of REF Files ---------------------- The overall format (exemplified by this file) is: <header> <title> <overview> <contents> <section 1> <identifier entry> <identifier entry> ... <section 2> <identifier entry> <identifier entry> ... ... <footer> Where no lines extend over 72 characters, and all descriptive text is right-justified using * ved_jrefmr, * ved_jj or * ved_jjp. 3.1 Example Template REF File ------------------------------ NOTE: the numbers of blank lines between different kinds of entries are important --- they will be used by libraries like LIB * MKREFINDEX. REF EXAMPLE John Sloman, Jan 1990 Revised: Joan Doe, Feb 1993 COPYRIGHT University of Sussex 1993. All Rights Reserved. >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< AN EXAMPLE TITLE >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxx overview xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx CONTENTS - (Use <ENTER> g to access required sections) 1 First Section ... ---------------- 1 First Section ---------------- xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxx text xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxx more text xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx table/program code/list xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxx more text xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx table/program code/list xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxx more text xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx <identifier entry 1> <identifier entry 2> <identifier entry 3> <identifier entry 4> ----------------- 2 Second section ----------------- xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxx text xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxx more text xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx <identifier entry 1> <identifier entry 2> <identifier entry 3> <identifier entry 4> --- C.all/ref/example --- Copyright University of Sussex 1993. All rights reserved. 3.2 The Header --------------- The header should specify the name of the REF file, and it's author(s) as shown in the template given in the previous section. 3.3 The Title -------------- The title should be enclosed in a box made from `>` and `<` characters as shown in the template. Please make sure that the title is: # Meaningful # All in upper case Please ensure that the width of the box used to enclose the title is the same as that used in the template (this is used by LIB * REFORMAT.) More than three lines can be used for long titles. 3.4 The Overview ----------------- This should act as a very brief synopsis of the contents of the REF file. There should be no blank lines between paragraphs. See the template for an example. 3.5 The Contents ----------------- The contents are an (optional) index of the REF file as produced by * ved_newindex. Sussex REF files are produced using the "sp" style of index. See * ved_newindex for details. 3.6 Sections and Section-Header Formats ---------------------------------------- The main text of the REF file should be divided into sections and sub-sections to aid comprehension. # Each (sub)section should have a heading. # There should be 2 or more empty lines preceding a sub-sub-heading, 3 preceding a sub-heading, and 4 preceding a main heading. # There should be one blank line after main headings, and no blank lines after other headings. Headings should be produced with * ved_newheading to conform to the format used by * ved_newindex. The three heading types used are: ------- 1 Bold (Main Heading) ------- 1.1 Non-Bold (Sub Heading) ------------- ... Non-Bold (Sub Sub Heading) ------------- Note that: # Underlining and overlining is the same length as the heading text # Headings should start at column 1 # Underlining is made of `\G-` characters # There are two spaces after the section number (or '...') See REF * REFFORM_OLD for details of the old heading and section formats. --------------- 4 Table Format --------------- Tables are recognised by each column having an underlined heading. The underlining must be the SAME LENGTH as the heading. The underlining can be made up of ordinary hyphens or `\G-` characters. There should be a blank line before and after the table. Each column should be left justified (ie. aligned with the first column of the heading.) If there are going to be columns where entries will be omitted, make sure a row containing an entry for each column is the first row. Without this LIB * REFORMAT will not work properly. If this is impossible place a hyphen (`-`) in the non-filled columns to indicate a blank entry. ------------------- 5 Paragraph Format ------------------- These follow the form of the template. Two rules should always be followed: # Make sure that all regular paragraphs are right justified. # Single line paragraphs should not have more than two contiguous spaces to prevent them being interpreted by LIB * REFORMAT as an itemised list." ---------------- 6 Verbatim Text ---------------- Text that should be reproduced verbatim by * REFORMAT should have the VED format-control space character `\Sf` placed at the beginning of every line. For example: Col:1 4 8 12 | | | | X This text X should be X reproduced X verbatim (where `X` represents `\Sf`.) There should be a blank line before and after the verbatim section. The command * ved_ifsp can be used to insert format spaces, and the command * ved_dssp can be used to view them. --------------- 7 Program Code --------------- For compilable sections of code the ved prompt-marker space `\Sp` should be placed at the start of every line. For example: Col:1 4 8 12 16 20 24 28 | | | | | | | | X vedcurrent.sys_fname_nam=> (where `X` represents `\Sp`.) As with all other text groups there should be a blank line on either side. `\Sp` should only be used for program code that is actually compilable, i.e. not just 'outline' or 'meta' examples. If in doubt treat as verbatim text and use `\Sf`. As for verbatim text, * ved_ifsp and * ved_dssp can be used to insert and view prompt-marker spaces. NOTE: The LIB * REFORMAT program has to use some character to mark the beginning and end of program code. The `?` character was selected for this purpose. Therefore, try not to use the `?` character in code or if you have to, please try to put it on the end of a line. -------- 8 Lists -------- There are three types of lists. # Enumerated # Descriptive # Itemised (bullet) Lists can be embedded in each other. If this is the case then it is best to indent the sublist. Although you are able to have non-indented lists, the LIB * REFORMAT program performs better if they are indented. 8.1 Enumerated Lists --------------------- These take the form: N text text text text text text text text text text text text text N text text text text text text text where N is a number bullet in the form of one of: 1. (1) (a) a) a. 8.2 Bullet Lists ----------------- These take the form: B text text text text text text text text text text text text text B text text text text text text text B is one of `#` (`\G#`), `o`, or `*`. The use of `*` is not recommended as it can lead to confusion with cross references. 8.3 Descriptive Lists ---------------------- These take two forms. For short snappy lists do:: ITEM text text text text text text text ITEM text text text text text text text For longer, more informative lists do: ITEM text text text text text text text text text text text text text text example of code/table text text text text text text text text text text text text text text text text text text text text text ITEM text text text text text text text text text text text text text text text text text text text text text text text text text text text text ITEM text text text text text text text text text text text text text text example of code/table text text text text text text text text text text text text text text (ITEM can be in lower or upper case.) Sometimes when you are making a list, it can look better as a table. If this is the case then please convert it. The hard copy version produced by LIB * REFORMAT will definitely look better. -------------------------------------- 9 The Use of VED Character Attributes -------------------------------------- The use of the VED character attributes in REF files is perfectly acceptable. You can use them to emphasize pieces of the text. The following general rules are used in Sussex REF files: # Identifier names are placed in bold text (eg popmemlim.) # Variables are placed in italics and are usually lower case (eg item.) # Descriptive list items are placed in italics. # Cross references to other on-line documentation should be italicised too i.e. REF * REFFORM, except when they are to identifiers (eg REF * ved_chat) when the identifier should be bold. The `*` is not attributed. You can use ved_chat to change the attributes of a word. See * ved_chat for more information on VED character attributes. ------------------ 10 Quoting Things ------------------ Just some simple rules which should be observed as a matter of course. # Use the (") character to quote words. Do NOT use a character quote to begin the word and a string quote to end it. # Use the character quote (`) to quote characters # Use the string character (') to quote strings. # If you are referring to a named section, enclose the reference in double quotes ("). # Make sure that if you open a double quote on a word then you end it. i.e do not write "ref'. It is okay to have single " in verbatim code however or enclosed in character quotes or brackets. ---------------------- 11 Identifier Entries ---------------------- The important things are: 1. No entry should contain MORE than 1 consecutive blank line, and each entry must have ONLY 2 blank lines before and after it. 2. An entry begins with one (or more) "synopsis" lines, each starting at column 1, and the first of which for each new identifier has that identifier's identprops enclosed in square brackets at the end of the line (right justified to column 72.) To save space, "constant" is omitted in combination with anything else, and the only type that should be given is "procedure" for a procedure identifier (Poplog doesn't have any typed variables other than procedure-type, so this part shouldn't imply otherwise.) These lines can be inserted with * ved_idprops. The main text of the idprops should be in bold-italics, with the square brackets in normal text. Examples are: [procedure] (= procedure constant) [procedure variable] [constant] [variable] [operator N] [syntax] [syntax N] [macro] [macro variable] For a variable, it should also say if protected, e.g. [protected procedure variable] [library] is also used to flag the name of a library that must be explicitly loaded. 3. Synopsis lines represent the following items: # An outline use for syntax words. # An outline call for procedures (and their updaters) with arguments and results. # Example assignments to and from items for ordinary variables. # Example assignments to items for protected variables and constants. # Just the name for anything else If a synopsis lines extends over more than 1 line, the continuation lines must be indented by any number of columns (OTHER THAN 8 columns to distinguish them from the body of the text.) Note that the [identprops] part must still be on the first line of that synopsis.) See examples below. 4. As implied above, each entry can contain multiple synopsis lines, either for different call forms of the same identifier, or for several identifiers, but [identprops] at the end of the line must mark the first one for each new identifier introduced. 5. Formal parameter names in synopsis lines should only be made up of italicised lower case alphanumeric characters and underscores. 6. The first line of the following text for the entry must start at column 8; the rest of lines must be indented by at least 8 columns (and mustn't contain 2 or more consecutive blank lines.) 7. As a general room everything on the synopsis line should be bold, with two exceptions: # Variables which should be in italics. # Text which is not typed used to indicate option arguments (which should be in normal text.) See the example identifier entries in the next section. 11.1 Example identifier entries -------------------------------- (In the examples that follow, the entries have been indented by one character to prevent confusion with actual entries in REF files.) col 8 col 72 | | newanyproperty(assoc_list, tab_size, expand_pow, thresh, [procedure] hash_p, equal_p, gc_type, default, active_default) -> prop This is for constructing more complex properties. It returns a new property prop, where the arguments are: subscrs(n, string) -> char [procedure] char -> subscrs(n, string) Returns or updates the n-th character char of the string string. num_1 + num_2 -> num_3 [operator 5] num_1 - num_2 -> num_3 [operator 5] num_1 * num_2 -> num_3 [operator 4] num_1 / num_2 -> num_3 [operator 4] These operators respectively add, subtract, multiply and divide their arguments, which may be any numbers. The type of the result depends on the rules of floating-point and complex contagion (etc, etc.) popradians -> bool [variable] bool -> popradians This boolean-valued variable specifies whether the angle arguments or results for trigonometric procedures are in radians (true) or degrees (false.) Note that the default is false, implying angles in degrees. pi -> float [constant] This constant is the best ddecimal approximation to "pi". popexecute -> bool [protected variable] This boolean variable is true when the current invocation of the VM through sysCOMPILE is at execute level, and false when code is being planted inside a procedure or a non-executing lblock. 11.2 Standard Type Names for Arguments/Results ----------------------------------------------- The following names can be used for arguments and results of the appropriate type: they are not meant to be compulsory, only for cases where the use of more descriptive "semantic" names isn't warranted (or, they can be used in combination with the latter.) They are also not meant to be rigorous in the sense that a given argument or result can only take the implied value, but show that this is its "principal" value (any exceptions being clearly described in the text.) Where more than one is used, add integer subscripts at the end, i.e. item_1, item_2, etc. Alternatively if there are different type characterisations add prefixes separated by underscores, e.g. s_vec and d_vec for start vector and destination vector in REF * move_subvector See REF * DATA for information on the data types built in to Poplog. ... Basic Types (Excluding Numbers) ----------------------------------- array [datatype] An array. See REF * ARRAYS. bool [datatype] Boolean: true or false. Note that any non-false value is treated as being true in most circumstances. char [datatype] Character: an integer between 0 and 255. Note that Poplog uses the ASCII standard. clos [datatype] Closure: procedure built by partial application. See REF * PROCEDURE/Closures. dev [datatype] Device: structure used for file and terminal I/O. See REF * SYSIO. external_p [datatype] External procedure: created by external_load. fvec [datatype] Standard full vector. ident [datatype] Identifier. See REF * IDENT. intvec [datatype] A vector of 32-bit signed integers. item [datatype] Any Poplog object at all. key [datatype] Class-descriptor. See REF * KEYS. list [datatype] A list of items (or the empty list, nil.) See REF * LISTS. p [datatype] Procedure. pair [datatype] A pair: two-element record structure used, among other things, for building lists. proc [datatype] A process: a data structure created (e.g.) by consproc recording the state of execution of a procedure. See REF * PROCESS. prop [datatype] Property: a hashed data structure associating item/value pairs. See REF * PROPS. propent [datatype] Property entry: records a single item/value association. See REF * PROPS ref [datatype] Reference: a one-element record type object. See REF * RECORDS/References. sect [datatype] Section: a mapping between words and idents. See REF * SECTIONS. string [datatype] A vector of characters. See REF * STRINGS. struct [datatype] Compound object (anything except integers & decimals.) See REF * DATA. undef [datatype] An undef record: the value of an uninitialised permanent identifier. See REF * IDENT/Undef. vec [datatype] Vector: any vector type object. word [datatype] Word. See REF * WORDS. ... Numbers ----------- See REF * NUMBERS for full information on types of numbers available. n [datatype] m [datatype] A simple integer. int [datatype] Integral: simple or big integer. float [datatype] A floating point number (decimal or ddecimal.) rat [datatype] Rational: ratio or integral. ratio [datatype] A ratio (fraction.) real [datatype] A non-complex number (integer, biginteger, ratio, decimal or ddecimal.) complex [datatype] A complex number. num [datatype] Any number at all. ... Other types --------------- bytestruct [datatype] A 'byte accessible' data structure. See REF * DATA/Byte. char_cons [datatype] A character consumer procedure. See REF * CHARIO. char_rep [datatype] A character repeater procedure. See REF * CHARIO. dir [datatype] Directory: a string naming a disk directory. field_spec [datatype] A record or vector field type descriptor (as used by conskey.) See REF * KEYS. file [datatype] A string or word naming a disc file, or a device record corresponding to a disc file or pipe or mailbox, suitable for reading or writing. filename [datatype] String or word naming a disc file. idprops [datatype] An identifier status descriptor (as used by sysSYNTAX.) item_rep [datatype] An item repeater procedure, producing a Poplog item each time it is called, and termin when there are no more items. See REF * ITEMISE. lib_name [datatype] Name of a library file. Normally a string, but can sometimes be a word. See REF * LIBRARY. search_list [datatype] List of directories in which to search for library programs and documentation. See REF * LIBRARY and HELP * SEARCH_LISTS. spec [datatype] Field specification as used for conskey See REF * KEYS/SPEC. spec_list [datatype] List of field specifications as required for record classes. See REF * conskey. string_rep [datatype] An string repeater procedure, producing a string each time it is called, or termin when finished. strword [datatype] word or string. vedfile [datatype] A string that is a filename suitable for VED, or a VED file structure such as is found in vedbufferlist (i.e. a vector of strings.) wident [datatype] word or ident. ... Prolog types ---------------- prologterm [datatype] A complex Prolog term. See REF * PROLOG. prologvar [datatype] A Prolog variable. See REF * PROLOG. ----------------------------- 12 Useful utility procedures ----------------------------- The following procedures may be found useful when editing REF files: # * ved_jrefmr is used for formatting REF file identifier entries. # * ved_slrhs can be used to automatically create the updater entries for REF file synopsis lines. # * ved_idprops is used to insert [identprops] entries in REF file synopsis lines. # * ved_dssp is used to see the special formatting spaces used by VED. # * ved_ifsp is used to insert and remove the special formatting spaces used by VED. # * ved_newheading is used to create REF file section headings. # * ved_newindex is used to create a contents page for a REF file. The normal VED formatting procedures can also be of great use. See "Formatting Commands" in REF * VEDCOMMS for more information. Also see: HELP * VEDBLOCKS Information on moving blocks of text in VED. HELP * FORMAT Commands to aid on-screen formatting of text in VED. ------------------------- 13 Further Documentation ------------------------- HELP * VEDFILETYPES Setting the defaults for different types of files. HELP * MKREFINDEX Creating an index of REF files that can be used by the * ved_? and * ved_?? commands HELP * STANDARDS Other documentation and library standards for Poplog. REF * DOCUMENTATION Implementation of the Poplog on-line documentation system. --- C.all/ref/refform --- Copyright University of Sussex 1993. All rights reserved.