STYLE - explain file style and file structure guide.

Summary of macro calls:

.bl_ [indent]            -- fill on, space 1, indent 0
.bt_                     -- .bl_, .tp_
.bu_                     -- Bugs section
.ca_ 'string' [indent]   -- subcase of option case
.cp_ ['line']            -- Copyright
.de_                     -- Description section
.ex_                     -- Examples section
.fu_                     -- Files used section
.hb_                     -- .bl_, .hi_
.hd_ 'title string'      -- you-name-it section
.hi_ li ri 'title'       -- hanging indent
.it_ 'a string'          -- italicize
.lf_ nn                  -- nn lines follow
.no_                     -- Notes section
.oc_ 'string' [indent]   -- option case
.op_ ['title']           -- start section of .oc_'s
.pv_ 'string'            -- Privileges section
.sa_                     -- "See Also" section
.sy_                     -- syntax for command
.tl_                     -- line following is title
.tn_ [indent]            -- fill on, indent 0, space 1
.to_ [indent]            -- fill off, indent 10, space 1
.tp_ [indent]            -- start paragraph, indent 5
.us_                     -- subroutine calling sequence
.wh_                     -- subroutine arguments

Description:

This explain file describes the recommended procedures for writing TSS explain files and the structure of the catalog in which they are stored. It is particularly oriented towards the writing of explain files for TSS commands or library subroutines.

Using macros:

The TF source for every explain file should begin with

.so expl/../macro.t

This defines the standard TF set-up for explain files. It also defines a number of macros, described below. The macros are intended to supply at least 90 per cent of the text formatting functions you need to write almost any explain file. Try not to use other macros or TF requests if you can get away with it.

Style:

An explain file consists of several blocks of text. Each block is preceded by a blank line and then a heading. The heading usually ends in a colon.

Keep your sections short to make the text more readable. A reader's eyes get bored with long unbroken text.

Heading lines are generated by various special-purpose macros. In addition, the ".hd_" macro can generate user-supplied headings.

Before we get into how the macros are used, you should be aware of how the most common types of explain file are constructed.

Title line:

The first line should contain the name of the command or subsystem, in upper case, followed by a space-dash-space, followed by a brief description of the explain file in lower case on the remainder of the line, followed by a dot. For example,

L - list any file in any format (almost).

is the title line for the explanation of the L command. If a file explains a sub-topic of a larger topic, the sub-topic should be the first thing on the command line. For example,

HINTS - useful facts about Fortran in TSS.

is the title line for "expl fortran hints". This makes it easy to generate an index of sub-topics under a topic, just by obtaining the title line of each of the sub-topic files.

The title line is introduced by the title macro ".tl_", as in

.tl_
FRED - the friendly editor.

Lines to follow section:

If an explain file is more than 20 lines long (i.e. more than will fill an average CRT screen), the line after the title is frequently

.lf_ nn

where "nn" is the number of lines to follow (give or take 10 per cent). Since pagination has been built into the operating system, this feature has become less important.

Syntax/Use section:

After the title, explanations of commands and subroutines should show how the command/subroutine is used. For obscure historical reasons, this section is titled "Syntax" for TSS commands and "Use" for functions and subroutines.

The "Syntax" section for commands begins with the ".sy_" (syntax) macro. The line immediately following the macro gives a representation of how the command usually looks when typed from the terminal. For example,

.sy_
len filename

shows how someone would use the LEN command.

If the command only takes a few options, the option names are listed as part of the command line representation, as in

bye [+Clear] [-Verbose]

Note that options are enclosed in square brackets to indicate that they ARE optional. Putting a "*" after the square brackets indicates that there may be zero or more instances of the bracketed item. For example,

release file [file]*

implies that you can write

release file file file file ...

If there are many options, they should be listed immediately after the representative command line. The ".to_" macro is used to begin the list and ".tn_" to end it. As an example, this is how the syntax section of the ASM command is set up.

.sy_
ASM sourcefile[+sourcefile]* [option]*
.to_
.ta 25 L
.tc :
**=filename:Entry=name
+Clear:Hstar=filename (.h)
(+|-)ListIng (-):Library=filename
(+|-)LstOu (-):LoaderMemory=nn
(+|-)Gmac (+):LowLoad=nn
(+|-)Load (+):Map=filename
(+|-)SysLib (+):Object=filename
(+|-)Oldalt (-):Name=name
(+|-)Setup (-):ProgramMem=nn
+Zdebug:Update=filename
Alters=filename:StrangerOpts=name[,name]*
CompilerMemory=nn:USe=name[,name]*
SaveFile=filename:ComDeck=filename
.tn_

Note that options which may be either "+" or "-" (e.g. +Load, -Load) have this indicated by putting a "(+|-)" before the option keyword. Also note that the default setting for such options is usually noted in parentheses after the option keyword, e.g.

(+|-)Load (+)

All option defaults should be specified in this way, if possible; for example,

Hstar=filename (.h)

indicates that the default Hstar file name is ".h".

Option keywords in the Syntax section (and throughout the explain file) should have their minimal abbreviations indicated by putting the letters in upper case. For example, the minimal abbreviation for "CompilerMemory" is "cm". Letters in lower case may be omitted. If no abbreviations are permitted, option keywords should be written completely in upper case.

It is not necessary for the Syntax section to describe what an option does. This should be evident by the keyword used; in any case, the Syntax section is only intended to be a speedy reference for someone who has previously read the explain file.

For subroutines, you use the ".us_" (Use) macro instead of the ".sy_" macro. The ".us_" section should show the calling sequence of the subroutine or function being documented. If the subroutine or function requires arguments of a particular type, the Use section should include sample type declarations for the arguments. Optional arguments or groups of arguments should be enclosed in square brackets and the brackets may be nested. For example, here is a sample of a Use section for a B function featuring nested optional arguments.

.us_
ret = trtest( string, pos, table [, count [, type] ] );

If the list of optional arguments is extremely lengthy, you can cheat and just enclose the optional arguments in one set of square brackets. The classic example is "expl b lib dump".

Here is what a Use section for a Pascal function might look like.

.us_
var
    c : char;
    fd : integer;
function
    getch( var ch: char; fd: integer ) : char;
        extern;
    ...
    getch( c, fd )

Note that for Pascal routines not known to the compiler, it is necessary to show how the function must be declared in the calling program.

Examples section:

Immediately after the Syntax section comes a section of examples that show how to use the command and its more common options. Without such examples, the user may have difficulty understanding the syntax.

The section is introduced by using the ".ex_" (examples) macro, which sets an indent and turns filling off. Here is how the examples for the FTN explain are set up.

.ex_
ftn *
ftn srcpart1 srcpart2 01</myfile 02>02 10<
ftn /subra ul=tlib +clear

Examples are more or less compulsory for new TSS commands. Explanations of functions and subroutines frequently benefit from examples too, especially if the routines make use of options (e.g. "expl b lib open").

Where/Options section:

After the examples comes a section describing command options or subroutine arguments. This section is entitled "Options" for TSS commands and "Where" for functions and subroutines. The Options section for a command is introduced with the ".op_" macro. The Where section for a subroutine or function is introduced with the ".wh_" macro.

".op_" and ".wh_" simply create the section heading. Individual options or arguments begin with the ".oc_" (option case) macro. For example,

.op_
.oc_ +Clear
ruthlessly removes files from the AFT
before signing you off.
.oc_ -Verbose
causes only the total cost of the TSS
session to be printed.

constitutes the Options section for the BYE command.

For a TSS command, options should be shown in alphabetical order according to keyword. Each keyword should have the letters required for the minimal abbreviation capitalized. Subroutine arguments should be described in the order they appear in the calling sequence from left to right. If an option or argument contains blanks or tabs, you should enclose it in single quotes for the ".oc_" macro, e.g.

.oc_ 'PageLength=<page length>'

The text of a ".oc_" sub-section should be written as properly capitalized and punctuated sentences.

In some cases, you may want to describe several alternatives for a particular option or procedure argument. To set up such subcases, use the ".ca_" macro. For example, the description of the "action" argument of the B library function OPEN might use the ".ca_" macro in the following manner.

.oc_ action
is an optional ASCII string of characters
chosen from the following list:
.ca_ a
Append.
The unit is to be opened for writing,
and anything that is written to the unit
should be appended to the end of the file.
.ca_ b
random Block.
The file is to be accessed for random I/O,
presumably via the functions READ or WRITE.
   ... and so on ...
.oc_ media

Again, you should make every attempt to write the text of subcases as proper sentences.

Both ".oc_" and ".ca_" let you supply an optional numeric second argument which is used to alter the default indentation for the text which follows.

Description section:

The Description section begins with a ".de_" macro. In it, you should supply a brief description of how the command works and what function it is intended to perform. This should not be very long. If things get too long, begin with a brief outline and put more detailed information under sub-headings.

In the Description section, fill is on. Paragraphs should begin with the ".tp_" (thtart paragraph) macro, e.g.

.tp_
A paragraph starts here.
.tp_
This is a new paragraph.

If you want a blank line before the paragraph begins, use ".bt_". This can make your text much more easy on the eye, especially if your paragraphs tend to be long.

The ".de_" macro automatically includes a ".tp_", so you don't need a ".tp_" in front of the first paragraph in the section.

The ".to_" (turn-off) macro turns off filling, leaves a blank line, and sets the indent over 10 spaces. It is handy for providing the text of some system response or for showing sample JCL, among other things. It is also used to begin an unfilled list of items and to set off examples within the text.

For example, this was done with
.to_
For example, this was done with
.tn_

The ".tn_" (turn-on) macro restores the initial indentation and filling, then leaves a blank line. It is used to undo the effects of ".to_" and return to normal text. Note that you must not nest a ".to_/tn_" sequence inside another.

All of ".tp_", ".to_", and ".tn_" can accept an optional argument which is used to alter the indentation that is used. For example,

.tp_ 7

sets the standard indentation to seven spaces and then begins a paragraph by indenting five spaces beyond that. Similarly,

.to_ 5

dictates an indentation of five spaces for the list that follows; usually, ".to_" causes an indentation of 10.

User-supplied section headings:

If the text of your description section threatens to become overly long, break it up into several sections and introduce additional sections by using the ".hd_" macro with an argument. For example, the above heading was set up with

.hd_ 'User-supplied section headings'

Note that the macro file defines the single quote (') as the TF "quote character". This means you should avoid using the single quote inside arguments to these TF macros.

The ".hd_" automatically includes a ".tp_", so the first paragraph of the section doesn't need ".tp_".

The ".oc_" macro may be used in conjunction with the ".hd_" macro if you want to construct a list of things which are neither options nor subroutine arguments. For example, to construct a list of error messages and their descriptions, you might say

.hd_ 'Error messages'
.oc_ 'Error message 1'
Description of first error.
.oc_ 'Error message 2'
Description of second error.

Hanging indents:

There is a ".hi_" (hanging indent) macro that makes it possible for you to set up filled text of the form

title 1        xxxxxxxxxxxxxxxxxxxxx
               xxxxxxxxxxxxxxxxxxxxx
               xxxxxxx.
title 2        yyyyyyyyyyyyyyyyyyyyy
               yyyyyyyyyyyyyyyyyyyyy
               yyyyyyyyyyy.

This would be done with the following.

.hi_ 0 20 'Title 1'
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxxxxx.
.sp
.hi_ 0 20 'Title 2'
yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
yyyyyyyyyyyyyyyyyyyyyyyy.

The first argument is the indent of the title, the second is the indent of the body of the text, and the third is the title string.

The ".hb_" macro works in exactly the same way except that it automatically generates a blank line before the hanging indent text.

Files used section:

When documenting a TSS command, you must always make sure to include a section in which you name any files used by the command apart from those specified on the command line. This is done by invoking the ".fu_" macro and then entering the names, possibly followed by a comment on the usage of the file. For example,

.fu_
b* -- temp file to contain object decks for loader
.h -- default location to place load module
fc**lb -- main library (b/6/blib)
fc**bl -- batch library (b/6/batl)

You should specify the files used so that the user has some idea of how the use of the command may effect what is in his AFT.

See Also section:

In some cases, it is necessary to reference another explain file. This should only be done if there is a definite dependence on information in the other explain file, not just because it is vaguely related. The macro to create a header for the "See Also" section is ".sa_", as in

.sa_
expl b lib acc.fil
.tp_
expl b lib fildes

Bugs section:

This section is started by the ".bu_" macro, but is otherwise set up with the same conventions as the ".de_" macro. Under the heading of bugs you should include not only those things that the command or subroutine does not handle correctly, but also things that don't work in the way a user might expect.

Copyright:

All MFCF explain files must contain a copyright notice; we have had trouble in the past with unauthorized reproduction of our documentation and because copyright notices were omitted we had no legal recourse.

The ".cp_" macro creates a copyright notice of the appropriate form. If an argument is supplied to ".cp_", the macro prints that argument as the copyright notice, e.g.

.cp_ 'Copyright (c) 1996, Thinkage Ltd.'

This is useful in instances where you wish the copyright notice to appear on both the explain file and its TF source. The ".cp_" macro also adds a time stamp on the bottom of the file to tell when the file was formatted. If you want to suppress this time stamp, give ".cp_" a non-null second argument. For example,

.cp_ '' X

has a null first argument (so the default copyright notice will be used) but a non-null second argument so the time stamp will be suppressed.

Style Notes:

Here are a few items that have become standard style for explain files.

When referring to the name of a TSS command or a library subroutine, the name should be in upper case, e.g. ACC.FIL, FTN.

When referring to the name of an argument of a library subroutine, the name should be in lower case and enclosed in double quotes, e.g. "string", "fd".

When referring to an explain file in filled text, the name should be in lower case and enclosed in double quotes, e.g. "expl b lib incrun". Our standard convention is to say "expl" instead of "explain", but everything else should be spelled out in full.

Explain system catalog and file names should normally be truncated to four characters, but explain files for library subroutines should be truncated at six characters.

If a programming language construct or fragment appears in filled text, it should be surrounded by double quotes. The same goes for system error messages and the like. Capitalization should conform to the requirements of the situation. If the text is long, it is usually better to set it off inside a ".to_/.tn_" section.

If you refer to a keyword option in filled text, you should spell the keyword out in full (unless it is a particularly obnoxious one) and you should capitalize those letters required for the minimal abbreviation. Also, you should include the "+", "-" or "=", and enclose the whole thing in double quotes, e.g. the "+ListIn" option, the "Hstar=" option.

Do not underline anything in an explain file intended to be displayed on the terminal. There are still terminals around that treat an underscore as a back arrow and we get complaints from owners of such terminals. Also, it is almost impossible to find an underlined word in an explain file when using LOCATE or FRED for searching. If emphasis is ABSOLUTELY NECESSARY, capitalize the words. (Underlining IS allowed in manuals which are intended to be run off on the line printer.)

In general, when putting things inside quotes you usually use double quotes. The exception is in explain files for APL where double quotes may be mistaken for ASCII escape sequences.

Occasionally inside some section in which text is not filled, you might want to add some comment at the end as filled text. The ".bl_" macro turns on filling, leaves a blank line, and sets the indentation to zero. If you want a non-zero indent use ".bl_ nn", where "nn" is the desired indent.

Do not put null lines in the TF source of an explain file. Use ".sp" instead.

The line width for explain files is 60 characters. It is your responsibility to make sure unfilled lines are no longer than 60 characters.

When entering numbers in filled text, spell out the numbers from zero through nine and use digits for the rest, e.g. one, two, 10, 1000.

When commenting on examples in the text, use "--" to begin the comment, as in

stty +p       -- turns on pagination

Please try to use macros as much as possible and avoid the direct use of TF commands. This makes it much easier to read and maintain the TF source.

Spelling and Capitalization style:

The following items illustrate what is considered correct spelling and capitalization style for MFCF explain files.

AFT
ANSI
ASCII
BCD
catalog
Cobol
file name (not filename)
Fortran
new-line
non-zero
obsolete
PASCAL (the command)
Pascal (the language)
program
removeable
run-time
status
statuses
TSS
zeroes

Catalog structure of explain:

The source for all explain files should be kept under

expl/..

This catalog should be an exact parallel to the explain catalog containing the formatted versions; for example, the source for

expl/b/coro/expl

is found in

expl/../b/coro/expl.t

Note the use of the ".t" suffix to indicate that TF is to be used to format the file. Other suffixes are ".ty" for TYPE and ".b" for the occasional B program source (used to create explain files that submit manuals to the printer).

Manual Macros:

"expl/../manmac.t" contains versions of the standard explain macros for use in the preparation of manuals. These are identical to the versions used in explain files for the terminal except that they include TF requests to avoid widows and orphans, and are also slightly more liberal in using blank lines before blocks of text. All manuals written in the future should use these manual macros, in the interests of standardization.

In addition to the standard explain macros described above, the manual macros in "expl/../macro.t" contain several other macros.

.s1 title
creates a numbered heading for a main chapter, as well as an index entry which is sent to the standard diversion using ".di". "title" is the heading to be used for the chapter. It is often useful to have the title one long name with tildes in place of blanks in order to make tables of contents come out right.
.s2 title
creates a numbered heading for a section, as well as an index entry which is sent to the standard diversion using ".di". "title" is the heading used for the section.
.s3 title
creates a numbered heading for a subsection, as well as an index entry which is sent to the standard diversion using ".di". "title" is the heading used for the subsection.
.occ label
is equivalent to
.bl_
.oc_ label 4
.ni_ 4
creates a "nice" gap between sections, several blank lines long. If there is not a lot of space left on the current manual page, ".ni_" starts the next section on a new page.

All these macros are also found in "expl/../macro.t" for compatibility. The ".s1", ".s2", and ".s3" macros turn into normal ".hd_" macros. The ".occ" macro is the same in both macro files. The ".ni_" macro in "expl/../macro.t" is null.

Catalogs for Manuals:

Where manuals are kept under the explain catalog, the following points should be observed.

A manual (e.g. the TF manual) should have its source under the catalog

expl/../TOPIC/manu

e.g. "expl/../tf/manu/", "expl/../b/coro/manu/". If there are both manuals and tutorials, there may be several such catalogs, e.g.

expl/../b/manu
expl/../b/tuto
  ...etc...

When the manual is part of a subsection of an explain catalog, the same sort of catalogs should be used, e.g.

expl/../b/envi/manu
expl/../b/coro/manu

In other words, the source for each manual should be in a catalog all to itself. This permits "expl b coro" (for example) to give a brief summary of the things that "expl b coro manu" gives in detail.

If in the course of formatting the manual an index or intermediate output file is produced which also needs formatting, this should be put in the source catalog for the manual, e.g. "expl/../b/envi/manu/index.t". Again, the suffix indicates the type of formatting required.

The formatted but not Media7 sections of a manual should be stored in the main explain catalog under

expl/TOPIC/manu/

The entire manual should be formatted into one output file named

expl/TOPIC/manu/..media6

e.g. "expl/tf/manu/..media6". If file space is a problem, this file may be deleted or archived after creating the printer-ready Media7 version of the manual.

The KLISTed, printer-ready, Media7 version of a manual should be stored as

expl/TOPIC/manu/..media7

e.g. "expl/tf/manu/..media7", "expl/b/coro/manu/..media7". This is the version that can be copied and sent directly to the printer with a minimum of processing.

A load module must be created under

expl/TOPIC/manu/expl

to find the Media7 manual and send it to the printer. "expl/../manu.b" is the basic program to use; it requires three external strings: "banner", "descrip", and "filename". "expl/../manu.lib" contains the above program already compiled; you only need supply the three external strings and compile your file with "Library=expl/../manu.lib". Normally, "filename" will be of the form "expl/TOPIC/manu/..media7", as outlined above. The banner and description strings depend on the type of manual. See "expl/../tf/manu/expl.b" for an example. The source for the load module in

expl/TOPIC/manu/expl

will of course be kept in

expl/../TOPIC/manu/expl.b

"Make" files for each manual should be stored in the parallel (source) catalog as well. The principal "make" file should be a CRUN command file called ".makman.". If there are many such "make" files, make a catalog to hold them, e.g.

expl/../TOPIC/manu/.makman./

See "expl/../tf/manu/.makman." for an example.

The net result of this parallel structuring is an overall structure which makes it easy to find the source for any explain file or manual.

Multi-machine Explanations:

Some UW products are available on more machines than the DPS-8, and products for different machines often need different explanations. For convenience, we store the TF or TYPE source for these explanation files under "expl/.." along with the source for the DPS-8 explanations. This gives us the problem of distinguishing the source for the different explain files.

To make this distinction, the source file name should contain an indication of the machine that the file corresponds to. This is given at the lowest possible level -- the actual file name (if possible) instead of a catalog name. For example, the source for the explanation of the C library function "fopen", as it runs on the Bull HN DPS-7 is stored in

expl/../c/lib/fopen/_dps7.t

The "_dps7" indicates the machine to which the explanation applies.

The following descriptors are currently in use for this purpose.

_l66     -- DPS-8 (formerly, Level 66)
_dps7    -- DPS-7
_lev6    -- DPS-6 (formerly, Level 6)
_port    -- PORT operating system
_markiii -- Mark III operating system
_cp6     -- CP6 operating system
_i8086   -- Intel 8086 chip

Also in use is "_default". This indicates the source for machines that do not have a specifically named explanation. For example, suppose the DPS-6 and DPS-7 are the only machines to have a non-standard "error" function in the C library. Then we would have files

expl/../c/lib/error/_dps7.t
expl/../c/lib/error/_lev6.t
expl/../c/lib/error/_default.t

The "_default" source applies to all other machines.

Note that we only store the SOURCE for the various explanations. We do not format the actual explanations under EXPL. Otherwise, users would have difficulty finding the correct explanations for the machine they were using.

Copyright © 1996, Thinkage Ltd.