Contents

Select headings to return to index

ONLINE DOCUMENTATION AND LIBRARY STANDARDS for Poplog

Keywords: standards, documentation, library, format

This HELP file includes:

(a) General rules for online Poplog documentation files, apart from REF files, which use their own conventions (described in REF * REFFORM) and (b) some minimal conventions and guidelines for Poplog library programs.

These conventions have not been followed in all Poplog library files, as many were written before the standards emerged. The libraries are gradually being updated. This standards file will be enlarged from time to time as new conventions emerge.

It may be useful to study the information in DOC * SYSSPEC about the structure of the Poplog system, and the organisation of its libraries.

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

DOCUMENTATION LIBRARIES

Language naming conventions

The name of the system should be written as "Poplog". The names of the constituent languages should be written as follows: "Pop-11", "Lisp" (or "CLisp"), "Prolog", "SML".

Documentation file headers

Headers of online documentation files should have the format:

<CATEGORY OF FILE> <FILENAME> <author> <date>

If the file has been updated, the new <author> date information may be added on following lines. See the heading of this file for illustration.

There should be a blank line after the header.

Categories include: HELP DOC TEACH REF PLOGHELP. New categories may be introduced, using the mechanisms described in HELP * VEDGETSYSFILE.

HELP file format

HELP files should all follow a standard format consisting of the following sections separated by blank lines:

  1. Name of the file, who wrote it and when (as above),
  2. A short (one line if possible) description of the contents of the file,
  3. If it is a help file for a procedure, a variable, a syntactic form, or a Prolog predicate, then a sample call of the procedure, or form, Prolog predicate, etc. If a procedure has an updater include a sample call of the updater. If it is just a variable indicate the types of possible values.
  4. A list of keywords that may aid automated accessing mechanisms.
  5. If the file is long, then there should also be a list of the contents of the file, produced by VED_INDEXIFY. (See below)
  6. the main text, with section headers produced using VED_HEADING.
  7. a section headed RELATED DOCUMENTATION, providing a list of documentation files relevant to the current topic.

The sample call should show how the procedure (and its updater if appropriate) are invoked, so that readers can see at a glance how many arguments it takes, what they are, what kinds of results are produced, etc. The summary pattern should be followed by a blank line, then explanatory text.

If the HELP file does not describe a procedure, the header line should be followed by a title and brief description, then, if the file is long enough a table of contents produced by <ENTER> indexify (described below). For example see the top of this file.

Some HELP files are overview files rather than descriptions of particular facilities. They can start with a brief summary, or a table of contents, after the header. E.g. see HELP *CONTENTS, HELP *CLASSES

Examples of HELP file headings

An example of a Pop-11 HELP file heading.

HELP SUBSTRING <name> <date>
Accessing or updating a substring of a string or word.
substring(<index>,<length>,<string|word>) -> <string> <string> -> substring(<index>,<length>,<string|word>)
Keywords: string, substring, word
This procedure takes two numbers and a string or word, and ....

If the procedure takes optional arguments, specify these by putting a slash or vertical bar between them.

If the sample call takes up more than a line, break the line at the bracket boundaries as follows:

        newanyarray(<boundslist>,
                    <initialiser>,
                    <vector-type-spec|structure>,
                    <access procedure|offset>,
                    <mapping boolean>) -> <array>;

Put the output of a procedure call in angle brackets. If the number or types of results can vary, put slashes or vertical bars between the options.

If there are several different possible formats, list them separately, as in HELP *FOR.

Example of Prolog HELP file heading

PLOGHELP ARG Kathryn Seifert July 1986

Predicate which determines the Nth argument of a given term

?- arg(N, Term, Arg).

Keywords: term, arguments, structure

Pop-11 help files referenced in Prolog HELP files should be flagged by HELP as in HELP * DATABASE.

General Format: vedlinemax 72, vednotabs true

Restrict documentation files to 72 characters across. This looks better than 80 columns when files are printed and is more readable online.

<ENTER> rcol 72

to set VEDLINEMAX to 72 (see HELP *VEDCOMMS/ved_rcol)

Set VEDNOTABS true, so that there are no spurious tabs in the file. (See HELP * VEDNOTABS, HELP *VEDCOMMS/ved_tabs)

If you are frequently writing documentation, then you can define VEDVEDDEFAULTS in your vedinit.p to include something like:

    if issubstring('/help/',vedpathname)
    or issubstring('HELP ',subscrv(1,vedbuffer))
    or issubstring('/teach/',vedpathname)
    or issubstring('TEACH',subscrv(1,vedbuffer))
    then
        72 -> vedlinemax; true -> vednotabs
    endif;

Alternatively you can use -vedfiletypes-, e.g.