NAME

man − Ditroff macros for writing manual entries
 

INTRODUCTION

Manual entries in Sprite are formatted with the ditroff program using the -man macros.  This manual entry summarizes the features provided by the -man macros.  For more general information on how to write manual entries for Sprite, refer to The Sprite Engineering Manual.  Templates of manual entries for programs and library procedures are available in /sprite/lib/forms/cmd.man and /sprite/lib/forms/lib.man respectively. 

The Sprite -man macros are defined in two pieces.  The first piece is /sprite/lib/ditroff/tmac.an; this file is read whenever you specify -man on a ditroff command line.  The file tmac.an provides exactly the same set of macros that are available under UNIX (except that it defines the ]l variable as discussed below).  Extra macros just for Sprite (such as .AP and .BS) are provided by the file /sprite/lib/ditroff/tmac.sprite.  To include these macros, each Sprite manual entry should start with a line .so  \∗(]ltmac.sprite The variable ]l is defined by Sprite’s tmac.an to be equal to /sprite/lib/ditroff/.  To distribute a Sprite manual entry to a non-Sprite system, send both the manual entry and tmac.sprite.  In the other systems, the ]l variable is not defined, so the file tmac.sprite must be in the same directory as the manual entry being printed. 
 

MACROS

The -man macros are:

.AP type name inOut [indent]
Argument paragraph.  The type, name, and inOut arguments give information about this argument:  its type, its name, and a string indicating how the argument is used.  InOut must be either in (meaning the argument is used by the procedure but is not used to modify information in the caller’s memory), out (meaning the argument points to information in the caller’s memory which the procedure modifies without ever reading), or in/out (meaning the argument points to information in the caller’s memory which is both read and written by the procedure).  Text following the .AP line provides a short description of the argument: it will be indented to appear to the right of type, name, and inOut.  If indent is specified, it determines the indentation of the following text in ens;  however, this argument is normally omitted, in which case a reasonable default is picked.  In a sequence of argument descriptions, each with its own .AP call, the type, name, inOut, and description parts will be lined up in columns.  The .AS macro may be used to size the columns. 

.AS type name
Set argument sizes for .AP.  Type and name specify the largest such arguments that will be used in a following series of .AP calls;  tab stops are set for the following calls so that the type and name columns will line up with adequate spacing.  If this macro is never invoked, then default field widths will be chosen, which are valid for small arguments. 

.B [args]
Print in boldface.  If any args are given, then all of the arguments are printed in boldface (up to six of them).  Otherwise, everything on the next line of input is printed in boldface.  In either case, the font reverts to roman after the arguments or following line have been printed. 

.BE End boxed text.  Close off a box started previously with .BS. 

.BS Start boxed text.  Everything up to the matching .BE macro will be enclosed in a box.  This is used for the summary boxes at the tops of manual entries. 

.DE End a display:  cancel the effects of the previous .DS macro, returning to normal indentation and fill mode. 

.DS Start a display.  All lines up until the next .DE macro will be indented and output in no-fill mode. 

.DT Reset tabs to default spacings (every half-inch). 

.IP tag [indent]
This is identical to .IP in the -ms macros.  It starts an indented paragraph with tag (if given) as an outdented tag.  If indent is given, it specifies how much the paragraph will be indented, in ens. 

.HP Start a paragraph with a hanging indent (the first line will be outdented relative to the rest of the paragraph). 

.HS section [date [version]]
Header for Sprite.  This macro should be used in place of .TH for all Sprite manual entries.  It should be the first thing in the entry’s source file.  Section indicates which section of the manual this entry belongs to, and should be one of:

admin The manual entry describes an administrative program (i.e. one whose binary is under /sprite/admin).  Administrative programs are not used by normal users. 

cmds The manual entry describes a user-level application program.  This section is equivalent to section 1 of UNIX manuals. 

daemons The manual entry describes a daemon program.  Daemons are programs that run in background to provide various system services, such as inetd or lpd.  They are normally invoked automatically at boot-time or when needed, and aren’t usually visible to ordinary users. 

dev The manual entry describes the characteristics of a particular type of I/O device or pseudo-device, along with the I/O controls that may be applied to devices of that type.  This section is equivalent to section 4 of UNIX manuals. 

files The manual entry describes the format of a particular file or file type.  For example, the manual entry you are reading is in the files section.  This section is equivalent to section 5 of UNIX manuals. 

lib The manual entry describes one or more procedures in one of the standard C libraries.  This section is equivalent to the combination of sections 2 and 3 of UNIX manuals. 

tcl The manual entry describes one or more procedures from the Tcl command language library. 

The date argument to .HS is optional and specifies the date on which the entry (or its corresponding program) was last modified.  The version argument is optional and specifies the Sprite version number corresponding to this version of the manual entry.  The current default is “1.0”. 

.I [args]
Print in italics.  If any args are given, then all of the arguments are printed in italics (up to six of them).  Otherwise, everything on the next line of input is printed in italics.  In either case, the font reverts to roman after the arguments or following line have been printed. 

.LG [args]
Print in a larger font.  If any args are given, then all of the arguments are printed in a larger font (up to six of them).  Otherwise, everything on the next line of input is printed in a larger font.  In either case, the font reverts to normal size after the arguments or following line have been printed. 

.LP Start a new paragraph.  Same as .PP. 

.PD distance
Set the spacing between paragraphs to distance. 

.PP Start a new paragraph. 

.RE [level]
End right-shifted text, moving the indentation level back to its previous level.  Normally, each .RS moves the indentation back one level (in the case of nested .RS calls).  However, if level is specified, it gives the index of the nesting level from which to return.  For example, .RS 3 says to return from 3 levels of nesting to 2 levels (when this call is invoked, there better be at least three nested .RS calls in effect).  .RS 0 says to return from all nested .RS calls. 

.RS [indent]
Right shift. From now on, indent all future text (up to the matching .RE) by an additional amount equal to indent ens.  If indent isn’t specified, then use the current indentation (from the last .TP or .IP) as the amount of additional indentation.  Pairs of .RS and .RE calls may be nested.  The .SH macro cancels all active .RS calls. 

.SH name [moreName ...]
Start a new section named name.  The name may actually consist of up to six distinct arguments. 

.SS name [moreName ... ]
Start a new subsection named name.  The name may actually consist of up to six distinct arguments. 

.SM [args]
Print in a smaller font.  If any args are given, then all of the arguments are printed in a smaller font (up to six of them).  Otherwise, everything on the next line of input is printed in a smaller font.  In either case, the font reverts to normal size after the arguments or following line have been printed. 

.TH name section [date [version]]
Set title and heading. This macro is obsolete.  It is used for old UNIX manual pages only. For Sprite man pages, the .HS macro should be used instead.  Name gives the name of the manual page, which will appear in the upper-right and upper-left corners of each page.  Section gives the section number.  Date gives the last-modified-time for the program;  if not specified, it defaults to blank.  Version gives the operating system version that this manual entry corresponds to.  The default for version varies in time;  see the tmac.an source file for the current value. 

.TP [indent]
Start a tagged paragraph.  The following line contains a tag, and everything after that contains the contents of the paragraph.  The tag will be printed outdented to the normal left margin, and the paragraph will be indented relative to the tag.  If indent is specified, then the indent distance is changed to indent ens (the indent distance is sticky across calls to .TP and .IP but gets reset to a default value by .PP and .SH).  For example, each of the macro descriptions in this particular manual entry was formatted using the .TP macro. 

.VE End vertical sidebar.  Starting with the output line following the current one, do not print vertical sidebars. 

.VS Start vertical sidebar.  From now on, starting with the current output line, a vertical bar will appear at the right side of all output lines.  This will continue until the next .VE call.  Sidebars should be used to indicate recent changes in the manual entry. 
 

KEYWORDS

ditroff, format, macros, -man, manual entry

Sprite version 1.0  —  February 22, 1989