HELP STANDARDS Mark Rubinstein and Ros Barrett May 1985
Revised Kathryn Seifert,A.Sloman Oct 1986
Revised A.Sloman June 1990
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
-- Documentation file headers
-- HELP file format
-- Examples of HELP file headings
-- Example of Prolog HELP file heading
-- General Format: vedlinemax 72, vednotabs true
-- Programming examples in TEACH or HELP files
-- Cross references: in text and at end
-- Naming keys and illustrating key strokes
-- Table of contents: ved_heading, ved_indexify, ved_g
-- PROGRAM LIBRARIES
-- Program library headers
-- System library headers
-- Use of sections
-- Settings for compiler flags: compile_mode
-- Use of lexical scoping
-- Preventing names in a package from clashing with user identifiers
-- Creating a sub-directory tree for a package
-- Efficiency issues
-- Variable naming conventions
-- Avoiding file name clashes on UNIX SystemV
-- Macros vs syntax words
-- New looping syntax in libraries
-- Use of SYSSTRING for buffers
-- Temporary files: SYSTMPFILE
-- Hard Wired Filenames
-- Conditional compilation: #_IF
-- Information about current system: SYSDEFS, POPHOST
-- Different files for different machines
-- NEWS files
-- Updating overview files
-- Automating the production and checking of documentation
-- RELATED DOCUMENTATION-- 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.
[
......
[ [^(hassubstring(%'/help/'%)) ^(hassubstring(%'/ref/'%))
^(hassubstring(%'/doc/'%)) ^(hassubstring(%'/teach/'%))
]
{vedlinemax 72} {vednotabs true}]
.....
] -> vedfiletypes;
See HELP *VEDVEDDEFAULTS, HELP * VEDFILETYPES
Right alignment of text files is a matter of taste. Most Poplog help
files are not right-aligned, partly in order to save space. Where
right-alignment is required use <ENTER> jj or <ENTER> jjp, to justify
and align marked range or current paragraph. Indentation can be
controlled using VEDLEFTMARGIN or <ENTER> lcol.
See HELP * FORMAT for more information on VED-based formatting
facilities.
-- Programming examples in TEACH or HELP files ------------------------
The following guidelines are recommended for examples of programs
and interactions.
- Use the normal Poplog case i.e. usually lower case. (Early help and
teach files used upper case to make programming examples stand out.)
- Do not include the prompts that the language subsystems provide.
Include system prompts only if they distinguish modes, for example the
? prompt when using READLINE.
- Include output as the program outputs it - if it is edited, say so.
The VED command
<ENTER> output .
is useful for getting sample output into a file. (See HELP *LMR)
- Start code and output by indenting it 4 spaces, with further
indentations in steps of 4 spaces, unless smaller steps are necessary
to keep examples in the visible window. (See HELP * VEDINDENTSTEP)
- Include a blank line above and below each example.
- When describing program formats, use lower case type-descriptions
in angle brackets when not illustrating with actual code.
For example:
forevery <list of patterns> do <actions> endforevery
- Use similar notation in text to refer back to the example. E.g.:
<actions> can include arbitrary Pop-11 instructions.
- Present code as you would write it, for example, do not put more
than one space between items in a list. Hence
[2 3 4 5] -> x;
as opposed to:
[ 2 3 4 5 ] -> x ;
- Language names should be written as described above (see 'Language
naming conventions'). Variable names should be written enclosed in
hyphens, which serves to clearly indicate their nature, and also to
stop small variable names from getting lost in the text. E.g.:
In Pop-11 conditionals are indicated by -if- or -unless-, and
-cucharout- is a user-assigned variable.
The procedure -foo- takes as its argument an integer -i-.
Note that this does not apply to the descriptions of procedures in REF
files, where arguments are conventionally written in upper case, e.g.:
sysread(DEV, BSUB, BYTESTRUCT, NBYTES) -> NREAD
-- Cross references: in text and at end -------------------------------
- Using asterisks to precede names of referenced files enables them to
be accessed using <ESC> n, <ESC> N and <ESC> h, as described in
HELP * HELPFILES, using the *VEDGETSYSFILE mechanism.
- To make a reference to documentation in the body of the text, put the
category of documentation in CAPITALS, and follow it with an asterisk,
(preferably but not necessarily) followed by a space then the name of
file in capitals. Make sure that the category name and the file name
appear on the same line. The word "HELP" may be omitted as the
searching mechanism defaults to HELP.
For example:
A process can be recognised with *ISPROCESS (further details in
REF *PROCESS)
- Other categories of files require the asterisk to be preceded by
the category name in upper case, e.g. TEACH *TEACHFILES
REF *SYNTAX, SHOWLIB *VED_SHOWLIB, LIB * VED_SHOWLIB,
PLOGHELP * PREDICATES.
- If there are several files of the same category, the category name
need occur only once on each line, as the cross reference mechanism
uses the last recognised category name preceding the file name, e.g.
REF * IDENT, * VMCODE, TEACH * VED, * VEDPOP, * TEACHFILES
- Cross references to Prolog HELP files should use the category
PLOGHELP. E.g.
see PLOGHELP *SYNTAX.
- PROGRAM LIBRARY files may use LIB or SHOWLIB as the category. These
will cause VED_SHOWLIB to be invoked to read the named file. INCLUDE
files may use INCLUDE as the category, which will cause
VED_SHOWINCLUDE to be used.
- To reference a particular part of a long file, follow the name of the
file with a "/" then a suitable search string, e.g.
HELP *VEDCOMMS/ved_cut REF * NUMBERS/biginteger
- End documentation files with a section headed RELATED DOCUMENTATION,
or See Also, providing a list of cross references to related files,
using asterisks to facilitate access. Each major cross reference should be
followed by a short description.
For example:
RELATED DOCUMENTATION
HELP *MATCHES - for more general information on matching
REF *SYSIO - for further information on I/O procedures
DOC *AAREAD.ME - the installation guide
-- Naming keys and illustrating key strokes ---------------------------
- If a key normally has a label printed on it refer to it by the name
in angle brackets, e.g. <ESC>, <ENTER>, <CTRL> etc. For example
To write the current file do:
press: <ENTER>
type: w
press: <RETURN>
- As in the above example use colons to separate instructions from
the 'arguments'.
- For key sequences use a space as separator, as in:
<CTRL> d <ESC> c
- For 'logical' names of keys and key-sequences use upper case without
angle brackets, e.g. SCREENUP and WORDLEFT. These are terminal
dependent keys and may not even exist as individual keys on all
keyboards.
- Wherever possible make documentation terminal independent. Refer to
both individual keys and sequences of keys by their logical names as
opposed to their numbers and positions on your keyboard. Derive the
logical names of VED keys from the names of the corresponding
procedures by omitting the prefix "ved" from the name. E.g. the
procedure VEDSCREENDOWN is invoked by the SCREENDOWN key.
See HELP *LOGICAL_KEYS for a list of standard logical names for keys.
- Occasionally a HELP or TEACH file may recommend assigning a VED
procedure to a key using *VEDSETKEY. It is best not to be too specific
about the key(s) to be used. E.g. rather than saying
redefine <CTRL> l to be VEDNEWPROCEDURE
say something like:
redefine a suitable key or key-sequence to be VEDNEWPROCEDURE
SINCE <CTRL> l may be a critical key sequence on some terminals, or
may have been preempted by user-tailoring of VED.
-- Table of contents: ved_heading, ved_indexify, ved_g ----------------
Begin long TEACH or HELP files with a "contents" section so that readers
can go quickly and easily to the part of the file wanted using <ENTER> g
as described in HELP *ENTER_G.
Facilities are provided for formatting headings and creating tables of
contents automatically, as was done for this file. After typing, or
modifying, a section heading line do:
<ENTER> heading
This will turn it into a heading in the standard format, with two
preceding hyphens and a trailing row of hyphens.
If there is no table of contents in the file then
<ENTER> indexify
will build one on the line immediately after the cursor. If there is one
already it will be rebuilt in the same place, to match the current state
of the section headings. See HELP * ENTER_G for details.
This mechanism can also be used to indexify program files, as long as
the headings are inserted between /* ... */ comments so that they
can start at the beginning of a line.
-- PROGRAM LIBRARIES ---------------------------------------------------- Program library headers --------------------------------------------
These should have the form of comments including the name of the file,
the author, date, summary of the purpose of the program, cross
references to relevant documentation and lists of related files.
Update information in reverse chronological order can go at the end of
the file.
-- System library headers ---------------------------------------------
At Sussex University, where Poplog is built, all the public Poplog files
are kept in one master directory network. Each file is in a directory
$usepop/master/C.???/... which is a mirror of the $usepop/pop/... tree,
and this is shown in the headers of library files. For an example see
SHOWLIB *VTURTLE
The C.??? component
specifies what kinds of machines the file is suitable for. Examples are:
C.unix - for any unix machine
C.gec - for any GEC Series 63 machine
C.vms - for any vms machine.
(Sussex users only: See *NEWLIB for details on installing files by the
same name in different parts of the master network.)
-- Use of sections ----------------------------------------------------
Pop-11 library programs should use either lexical scoping (see below) or
sections, or both, to prevent clashes between subroutine or variable
names used in a library and names used outside the library, either by
other libraries or by users.
See HELP * SECTIONS for an introduction to SECTIONS and REF * SECTIONS
for full details.
Even if no section is used, start the file with 'section;' and
end with 'endsection;'. This will ensure that if the file happens
to be compiled by another program in the middle of a section, the
library identifiers will be available in the top level section.
Identifiers that are to be available in all sections, or all sections
below the one in which they are made available need to be declared as
global, e.g.
global vars foo, procedure(proc1,proc2);
global constant myhomedir=popdirectory;
define global factorial(x);
See HELP * GLOBAL for more on this.
Many library utilities are in a section called $-library.
Many VED utilities are in the section called section $-ved.
A family of related library programs may go into their own section,
exporting only the identifiers that need to be globally accessible.
-- Settings for compiler flags: compile_mode --------------------------
Most libraries now produced for Poplog use the COMPILE_MODE syntax (see
HELP *COMPILE_MODE) to set various compiler flags to provide the
required degree of strictness during compilation.
It is recommended that the line
compile_mode:pop11 +strict;
be included at the top of library files.
-- Use of lexical scoping ---------------------------------------------
Lexical scoping of identifiers can be used for efficiency (see
HELP * EFFICIENCY). It also plays an important role in preventing
clashes of identifiers. Lexical scoping is achieved using
LVARS, LCONSTANT, DLVARS. See HELP *LEXICAL for a summary. Full
details are given in REF * VMCODE and REF * IDENT.
In Poplog lexically scoped identifiers can be used globally in a file,
in which case their scope is restricted to a call of the compiler on a
particular file (or stream). So a library file that declares global
procedures and variables using LVARS or LCONSTANT need not use sections
to prevent clashes with other library files. It is possible to merge
two files into one compilation stream by "including" one of them in the
other, as described in HELP * INCLUDE. A package of related files can
then share some "include" files which use lconstant to define macros
and other identifiers required only at compile time.
-- Preventing names in a package from clashing with user identifiers --
When creating a package that might be used in connection with other
programs it is usually a good idea to start all identifier names in the
package with a unique prefix, to reduce the risk of clashing with
software developed by others.
Sections and lexical scoping can remove the risk as far as identifiers
"private" to the package are concerned, but this leaves the risk of a
clash for any identifiers that are exported from the package. Selecting
a common prefix to use for all their names reduces the risk.
Unfortunately this convention was not followed from the beginning of
Poplog's life, so identifier names are somewhat chaotic, as with many
other widely used large systems.
-- Creating a sub-directory tree for a package ------------------------
If you add a package that includes a variety of sub-directories, e.g.
auto, lib, help, teach, ref, etc. then it is advisable to include ONE
file that adds the directories to appropriate search lists. For an
example see LIB * POPXLIB. This library extends various search lists to
include the X library and documentation directories.
As these search lists can shadow the general Poplog search lists, it is
a good idea to choose names that are unlikely to clash, e.g. using a
prefix as suggested above. Alternatively, instead of using the standard
commands for accessing such files (HELP, TEACH, etc) you can define new
categories of files with their own documentation, using the mechanism
described in HELP * VEDGETSYSFILE, * VEDSYSFILE. The "uses" mechanism
for ensuring that a file required has been compiled can be copied
by copying and modifying the libraries
LIB * LOADLIB, LIB * USESLIB, LIB * POPUSESLIST, LIB * USES,
-- Efficiency issues --------------------------------------------------
HELP * EFFICIENCY mentions some of the things to bear in mind. Do not
be tempted to make your programs fast at the cost of safety by using
'fast_' or 'fi_' procedures, unless you indicate that you have done
so by prefixing procedure names with 'fast_'.
Since one of the features of Pop-11 is the availability of dynamic lists
it is important that if user lists are operated on, HD TL and DEST should
be used rather than FRONT, BACK and DESTPAIR, so that users can employ
dynamic lists. (SEE HELP *PDTOLIST). Exceptions may be 'fast_'
procedures.
Judicious use of fast_ procedures can be used to speed up programs
quite safely, e.g.
if null(list) then ....
else
hd(list) .... tl(list) ....
can safely be replaced by
if null(list) then ...
else
fast_front(list) .... fast_back(list) ....
This is because 'null' will already have checked that list is a pair,
and if it is a dynamic list will have 'solidified' (or 'expanded') the
fist link of the list so that it is unnecessary to us 'hd' or 'tl'
repeat the check or ensure expansion. (See HELP * PDTOLIST)
-- Variable naming conventions ----------------------------------------
Pop-11 global variables that users can update tend to have names
starting with 'pop'. VED extensions should start with "ved_" if they
are to be used as <ENTER> commands, otherwise just use the prefix
"ved".
When in doubt about whether to separate syllables with an underscore, do
so, apart from avoiding spurious "ved_" prefixes. (This underscore
convention should have been done from the beginning in Pop-11, but
wasn't. For the convenience of users, we shall not change this until
there is a user-driven standardisation movement.)
Use meaningful names wherever possible, but beware of choosing
identifiers that are likely to clash with others. (See previous sections
on packages)
-- Avoiding file name clashes on UNIX SystemV -------------------------
For autoloadable libraries (See DOC *SYSSPEC) identifier names map onto
file names, followed by the suffix for the language in question, e.g.
'.p', '.pl', '.lsp' etc. So 'member' is defined in a file called
'member.p'.
HELP files use just the name of the identifier, e.g. 'member'.
On AT&T Unix systems there is a most unfortunate limit of 14 characters
per file name, including any suffixes. The "." in 'foo.p' is one of the
characters. This means that the file names may require the identifier
part to be truncated. The language suffix MUST be included, however. A
consequence is that if two identifier names differ only after the 14th
character then they cannot have different help files. Worse, if Pop-11
identifiers differ after the 12th character, or Prolog identifiers after
the 11th or Lisp identifiers after the 10th, then they cannot be
included in separate files program files. E.g. newanypropername and
newanypropersize would map into
newanyproper.p
newanyprope.pl
newanyprop.lsp
This will cause problems when the libraries are ported to UNIX SystemV
machines.
-- Macros vs syntax words ---------------------------------------------
It is generally preferable to define new syntactic forms as syntax words
rather than as macros. There are two reasons for this:
- Macros build new list structures to attach to proglist, causing extra
garbage collection time.
- Macros are expanded before the text stream is actually compiled. That
means that if a syntactic error occurs because a macro has been used
wrongly, the offending item will not be available to be indicated in
the error message. It also means that in some circumstances, actions
(other than simple textual replacement) done by macros can happen at
the wrong time.
Generally speaking, macros should only replace themselves with a stream
of items on proglist, and not cause any other side-effects; anything
that does otherwise should be a syntax word.
However it is often easier to use macros, and sometimes the task cannot
be done using syntax words since incomplete expressions have to be
read in and rearranged, as in LIB *SWITCHON.
When defining new syntax words, don't forget to define any closing
brackets as syntax words too (if there are any).
-- New looping syntax in libraries ------------------------------------
If you define a new looping format, don't forget to plant labels that
can be used by nextloop (nextif, nextunless) and quitloop (quitif,
quitunless). sysNEW_LABEL creates new labels, pop11_loop_start plants
the label for nextloop (etc) and pop11_loop_end plants the label for
quitloop (etc). See REF *POPCOMPILE.
For an example SHOWLIB * FOREACH-- Use of SYSSTRING for buffers ---------------------------------------
This is a global variable holding a long character string of length
SYSSTRINGLEN that can be used as argument for *SYSREAD in library
programs that need to read in files, provided that no other programs
likely to use SYSSTRING are invoked between the call of SYSREAD and
accessing its contents. Using SYSSTRING avoids the garbage collection
overhead of creating strings when needed, and the space overhead of
having a different string for each utility. For an example of its use
SHOWLIB *DISCAPPEND-- Temporary files: SYSTMPFILE ----------------------------------------
If a library program needs to create a temporary file use SYSTMPFILE.
See REF * SYSUTIL/systmpfile-- Hard Wired Filenames ------------------------------------------------
It is a bad idea to use "hard-wired" filenames in programs. If your
program needs to refer to a particular file, even if it's always going
to have exactly the same file specification (e.g. '/etc/passwd'), then
it is good practice to declare a constant at the top of the file and use
the name of the constant throughout the program.
This is particularly useful if the file has a different specification
on different operating systems. For example:
constant passwdfile = '/etc/passwd';
or
lconstant passwdfile = '/etc/passwd';
--- Operating System Specifics -----------------------------------------
Poplog programs often have to have slight differences to work on
different operating systems. For example file specifications may be
different. Sometimes it is possible to write code that will work
on different operating systems by using some of the tools provided such
as dir_>< which sticks a file name and directory name together in a form
appropriate for the machine it is on. The procedure SYSFILEOK should
also be used to ensure that a file specification is suitable for the
operating system (e.g. SYSFILEOK will truncate names if necessary).
sysfileok(<string>) -> <legal file name>
Sometimes, however, these procedures are not sufficient and you may need
an action that depends on the operating system of the computer that the
program is running on. For example the command to get the operating
system to list the files in a directory is different for VMS and UNIX.
In this case you can use the compile time conditional.
-- Conditional compilation: #_IF --------------------------------------
#_IF <condition>
<statement-set-1>
#_ELSE
<statement-set-2>
#_ENDIF
#_IF is read by the compiler and the attached condition is evaluated at
compile time. If it is not false then the <statement-set-1> is compiled
and <statement-set-2> is ignored by the compiler as if it were
commented, otherwise the second set of statements is compiled and the
first set is ignored.
As with "if" you can have #_IF ... #_ENDIF, #_IF ... #_ELSE ... #_ENDIF
or #_IF ... #_ELSEIF ... #_ELSE ... #_ENDIF with any number of #_ELSEIF
conditions being allowed. Unlike IF no THEN is required - the condition
is read until the end of the line, so the condition must all be on the
same line as the #_IF (or #_ELSEIF) and it must be the only thing on
that line (apart from comments). To make this unusual feature stand out
it is good practice not to indent any #_ statements.
#_IF is often used in conjunction with the -DEF- macro, which tests
whether a word is defined: see HELP * DEF.
-- Information about current system: SYSDEFS, POPHOST -----------------
Library programs can find out details of the host machine and operating
system by using the libraries LIB * SYSDEFS and LIB * POPHOST.
See HELP * SYSDEFS, * POPHOST.
For example, to define a Pop-11 macro LSC to print out a directory
listing in columns, which will work for both Unix and VMS systems:
uses sysdefs; ;;; for definition of VMS/UNIX flags
define macro lsc;
lvars filespec;
dlocal popnewline;
true -> popnewline;
rdstringto([; ^newline ^termin]) -> filespec;
false -> popnewline;
#_IF DEF UNIX
sysobey('ls -C ' >< filespec);
#_ELSEIF DEF VMS
sysobey('dir/versions=1 ' >< filespec);
#_ELSE
mishap('lsc not defined for this operating system',
sys_os_type);
#_ENDIF
enddefine;
-- Different files for different machines ------------------------------
Using compile time conditional is useful where the difference between
the program on one machine and another only amounts to a line or two, or
where one procedure is different, but if the program needs to be
radically different on different machines then it is possible to write
two separate files, though this will imply that when one is changed
it will be necessary to remember to change the other.
-- NEWS files ---------------------------------------------------------
All new items should be announced in HELP *NEWS, if in the public
library and in HELP *LOCALNEWS if in the local library. It is very
important to maintain this central chronological record of changes.
Additions to Prolog and Lisp can go into the help files *PLOGNEWS and
*LISPNEWS.
-- Updating overview files --------------------------------------------
It is important to enter new facilities in summary files even if they
have their own help files. In addition there are various categories of
overview files that describe a range of facilities then point to
particular help files in that range. For examples see HELP *CONTROL,
*CLASSES, *DATASTRUCTURES, *STRINGS and PLOGHELP *PREDICATES
[Sussex only]
Any new HELP files in the main pop/help directory should be entered into
the overview file HELP *CONTENTS. New TEACH *FILES in the main pop/teach
directory should go into TEACH *TEACHFILES. (Possibly these will be
renamed for consistency).
-- Automating the production and checking of documentation ------------
This possibility will be investigated. There are serious difficulties in
automating documentation for a system as complex and varied as Poplog,
especially as many of the files are overview files.
However, by adopting appropriate conventions in program files we may be
able to do something about automating part of the process.
-- RELATED DOCUMENTATION ----------------------------------------------
DOC * SYSSPEC - overview of Poplog file structure
HELP * ENTER_G - tools for formatting documentation files
HELP * LOGICAL_KEYS - logical names for VED key sequences
--- C.all/help/standards
--- Copyright University of Sussex 1991. All rights reserved. ----------