.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
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.
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.
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.
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.
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.
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.
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").
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.
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.
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.
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.
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.
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
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.
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.
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.
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
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).
"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.
.bl_ .oc_ label 4
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.
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.
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.