------------------------------- Page    i -------------------------------

                        Formatting Entries in the

                         UTS Programmer's Manual

------------------------------- Page   ii -------------------------------

                            TABLE OF CONTENTS


Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . . . .   1

1.    Text Formatting Commands  . . . . . . . . . . . . . . . . . . .   1

1.1      Main Section Headings  . . . . . . . . . . . . . . . . . . .   1
1.2      Paragraphs . . . . . . . . . . . . . . . . . . . . . . . . .   2
1.3      Lists  . . . . . . . . . . . . . . . . . . . . . . . . . . .   2
1.4      Tables . . . . . . . . . . . . . . . . . . . . . . . . . . .   2
1.5      Displays . . . . . . . . . . . . . . . . . . . . . . . . . .   2
1.6      Examples . . . . . . . . . . . . . . . . . . . . . . . . . .   3
1.7      Page Skip  . . . . . . . . . . . . . . . . . . . . . . . . .   3
1.8      Other Commands . . . . . . . . . . . . . . . . . . . . . . .   3

2.    Format Standards  . . . . . . . . . . . . . . . . . . . . . . .   3

2.1      The NAME Section . . . . . . . . . . . . . . . . . . . . . .   4
2.2      The SYNOPSIS Section . . . . . . . . . . . . . . . . . . . .   4

2.2.1       Commands  . . . . . . . . . . . . . . . . . . . . . . . .   5
2.2.2       Functions . . . . . . . . . . . . . . . . . . . . . . . .   5
2.2.3       Special Files . . . . . . . . . . . . . . . . . . . . . .   5

2.3      The DESCRIPTION Section  . . . . . . . . . . . . . . . . . .   6
2.4      The EXAMPLES Section . . . . . . . . . . . . . . . . . . . .   6
2.5      The FILES Section  . . . . . . . . . . . . . . . . . . . . .   7
2.6      The SEE ALSO Section . . . . . . . . . . . . . . . . . . . .   7
2.7      The DIAGNOSTICS Section  . . . . . . . . . . . . . . . . . .   7
2.8      The BUGS Section . . . . . . . . . . . . . . . . . . . . . .   8
2.9      Miscellaneous Sections . . . . . . . . . . . . . . . . . . .   8

References  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   8

Appendix A.    Command Summary  . . . . . . . . . . . . . . . . . . .   9


                                                            Last Page   9

-------------------------------- Page  1 --------------------------------

INTRODUCTION

This document describes the  text formatting commands  and standards  for
producing entries in the UTS  Programmer's Manual [3].  An input file  is
created containing text and the  commands described in this document  and
in the ms user's guide (see [1]).  This file is then formatted by the man
command, for display on the terminals or printers.

Most of the commands in the man text formatting system are identical  (or
similar) to those in the  ms system.  Descriptions of these commands  are
found in the ms user's guide.




1.    TEXT FORMATTING COMMANDS

Many commands that format text in  ms, including lists and displays,  are
also available for formatting  manual entries.  Appendix  A is a  command
summary that lists all manual entry formatting commands.

Full descriptions  of man  commands and  features that  are identical  to
those in ms can  be found in [1].   In addition, there are several  nroff
commands that may be used  directly, which are  described in [2].   Fami-
liarity with  ms  is assumed  in  this document.   The  discussion  below
describes the man formatting system.


1.1      MAIN SECTION HEADINGS

     .NA command [section]
     .SY
     .DE
     .EX
     .FI
     .SE
     .DI
     .BU
     .MI heading

These commands  begin the  various section  headings.  The  'MI'  command
allows any miscellaneous  heading to  be started, having  up to 8  words.
Each section is begun in fill mode.  A skeleton manual entry having these
commands  already  entered  in   the  proper  order   may  be  found   in
/usr/man/man0/entry.

-------------------------------- Page  2 --------------------------------

1.2      PARAGRAPHS

     .pp

This command begins a paragraph.  It is  not needed following any of  the
above section heading commands.  Its effect is to skip a line, and insure
that the paragraph will not start on the last line of a page.


1.3      LISTS

     .al [type] [no_spaces]
     .bl [no_spaces]
     .dl [no_spaces]
     .vl [indent_size] [no_spaces]
     .le [label]
     .lx [no_space]

Lists work just  as they  do in ms  [1].  A  list initialization  command
(.al, .bl, .dl,  .vl) is  used, followed by  several list entry  commands
(.le), and ended by a list exit command (.lx).


1.4      TABLES

     .ts
     .t&
     .te

Tables work just as they  do in ms [1].   Table specifications are  begun
with the table  start command  (.ts), and terminated  with the table  end
command (.te).  Table continuation commands  (.t&) may be used inside  as
needed.


1.5      DISPLAYS

     .dp
     one or more lines of text and commands
     .ed

There are no options to  the '.dp' command as there  is in ms.   Displays
are processed in  no fill mode, unless  a '.fi' command  is used.  A  new
page is started if the display is too big to fit on the current page.

-------------------------------- Page  3 --------------------------------

1.6      EXAMPLES

     .ep one line example
     .ep begin
     larger example
     containing
     several lines
     .ep end

The '.ep' command provides a simple means of included brief examples into
a manual page.  For example,

     one line example

is how such  an example  might appear.  The  example is  indented, and  a
blank line is generated before and after it.  As a second example,

     larger example
     containing
     several lines

uses the 'begin' and 'end' options.


1.7      PAGE SKIP

     .sk

This command ends the current page, and begins a new one.  When possible,
'.ne' or '.dp'/'.ed' are preferred for controlling pages.


1.8      OTHER COMMANDS

The fonts(3) preprocessor is used by the man command to make font changes
simpler to specify, after using  the .fo command.  Also, most nroff  com-
mands are also available to be used.  In particular, .br, .sp, .fi,  .nf,
.in, .ti, .ne, .de, .so, and .ta are frequently useful.   Descriptions of
these commands may be found in the ms user's guide [1].




2.    FORMAT STANDARDS

Previously, manual entries were produced with wanton disregard for  regu-
lation.  A massive effort was undertaken to bring the score  of different

-------------------------------- Page  4 --------------------------------

styles under a set of  rules that would make  the entries more  readable,
maintainable, and consistent.  These are not to be considered guidelines.
All entries must conform to the format standards.


2.1      THE NAME SECTION

The first argument to the .NA macro is the entry title.  For a command or
function, it is the command  or function name; For a special file, it  is
the file name with any '.h'  removed.  Occasionally it is appropriate  to
put more than one command or function on a single manual entry.  Then the
common part of the names should be used as the entry title.

The second argument denotes a  group of related  entries.  Only Volume  2
has such groups.


                ________________________________________
               |___________Groups_For_Volume_2_________|
               | <none>   Most functions               |
               |   sys    System calls                 |
               |   dbm    Data base routines           |
               |    m     Math library routines        |
               |____s_____Standard_I/O_library_routines|


The line following the .NA consists of one or more function, command,  or
file names that relate to the entry title, separated by ', ', followed by
a hyphen and a one line summary of the entry.

An example might be the system maintenance command 'destroy', which would
appear in volume three.

     .NA destroy c
     destroy - remove all life from the face of a planet

Nothing in this section can be in special fonts, as this is not supported
by the permuted index generator.


2.2      THE SYNOPSIS SECTION

This section contains the  definition of how  this command, function,  or
special file is used.  This is probably the single most important part of
the manual entry.  This section should consist of as few lines as  possi-
ble.

-------------------------------- Page  5 --------------------------------

2.2.1       COMMANDS

The syntax for the command is given.  If  the command does not reside  in
'/bin', then the full  path name must  be given.  The following  notation
describes the arguments.


             Notation    Meaning

                [X]      X is optional
                ...      The preceding item may be repeated
             Bold Type   The item in Bold Type is literal.


For the destroy command we could get:

     @/etc/destroy@ [@-t@] planet ...

Here the -t flag is optional, while one or more planets are required.

One line  is normally  enough for  commands, however  multiple lines  are
acceptable.


2.2.2       FUNCTIONS

The synopsis for a function is a copy  of its definition and the  defini-
tion of its  arguments, preceded by  any '#include' statements  necessary
for its use, all in bold font.  Integer arguments may be omitted, as that
is the C language default.

A good example is the entry for the ptrace system call, which is

     #include <sys/pstate.h>

     ptrace(pid, flag, buf)
     struct pstate *buf;


2.2.3       SPECIAL FILES

If the special file  resides in '/usr/include'  then this section  should
contain a '#include' line, in bold font, like that which would be used in
a C program to obtain the file.  If not, this section should be omitted.

The 'types' entry of Volume 3 provides an example.

     #include <sys/types.h>

-------------------------------- Page  6 --------------------------------

2.3      THE DESCRIPTION SECTION

This section contains the details  that separate this command,  function,
or special file from  the rest.  A list  of the arguments and their  pur-
poses must be included.  If any special formats, syntaxes, or  conditions
are required, the entry must either describe them or point  the reader to
where they are described.

All text in this section must appear in the roman (normal) font, with the
following exceptions.   Examples are  from  the aforementioned  'destroy'
entry.


  |_____________________________|________|___________________________|
  | Exception                   |  font  |  Example                  |
  |_____________________________|________|___________________________|
  | Command Names               |  Italic|  destroy                  |
  | Function Names              |  Italic|  abort                    |
  | Special File Names          |  Italic|  passwd                   |
  | Other Entry Names           |  Italic|  mv(1)                    |
  | Literal command arguments   |  Bold  |  -t                       |
  | Nonliteral command arguments|  Italic|  planet                   |
  |_Any_literals________________|__Bold__|__The_character_@_is_magic.|


For other entry names only the name itself is in italic font.  The source
to produce a reference to mv(1) would be ...

     _mv_(1)

The 'destroy' entry shows an example of the fonts usage.


        -t   Destroy is to pulverize the body  as well as clearing it  of
             life.

        The character @ is magic.  If planet  begins with @, all life  is
        to be moved to the Gobi desert (see mv(1)) for  inspection before
        it is destroyed.


2.4      THE EXAMPLES SECTION

Typical uses of  the command  are expected.   A description  of what  the
example would do is desired,  although not required.  Everything in  this
section is to  be in  the roman font.   Examples for  our 'destroy'  page
could be:

     /etc/destroy Uranus

-------------------------------- Page  7 --------------------------------

     /etc/destroy -t Mars Venus
             To annihilate Earth's nearest neighbors


2.5      THE FILES SECTION

Special files pertinent to the  entry are listed here,  one per line,  in
roman font.  A short explanation  of what the file is for may follow  the
name of the file.  In the explanation the same font rules as apply in the
description section are used.

The files section for the 'destroy' entry might be:

     /usr/Hermes       for Mercury
     /lib/carnage.*    files of damages

Note the use of the * character to  match any number of characters.   Any
of the shell's magic characters may be used to specify a group of files.


2.6      THE SEE ALSO SECTION

This section contains references to other entries, followed by references
to other documents.  The references should all be on one  line, separated
by ', '.   The documents  should each  be on  a separate  line, with  the
titles in italics.  The 'destroy' entry might have

     vmpunch(1), kill(1), kill(2)
     A Dcon Tutorial.


2.7      THE DIAGNOSTICS SECTION

For functions, values returned should be given.  For commands, error mes-
sages that require special  consideration should be explained here.   The
messages should be shown as they appear, separated by a blank line.   The
description of the messages must conform to the fonts regulations  of the
description section.  For the 'destroy' entry, then,

     Po yields Pb and Ar: cannot fuse
             Bad fuel element mixture for -t option.
             Retry using alternate data source.

     Exit code of 2 means that planet could not be found.

-------------------------------- Page  8 --------------------------------

2.8      THE BUGS SECTION

Shortcomings or dangers are confessed to  here, using the same font  con-
ventions as the description section.  For example,

     The -t option has not been tested for the planet Earth.


2.9      MISCELLANEOUS SECTIONS

These sections have no defined  format, although the description  section
fonts conventions are to be used.




REFERENCES

 [1]  "Formatting Documents on UTS, the ms user's guide".

 [2]  "Nroff User's Guide"

 [3]  "The  UTS  Programmer's  Manual",  see  man(1),  nroff(1),   ms(1),
      fonts(3).

-------------------------------- Page  9 --------------------------------

APPENDIX A.    COMMAND SUMMARY

Section   Command Syntax               Description

1.1       .BU                          BUGS section
1.1       .DE                          DESCRIPTION section
1.1       .DI                          DIAGNOSTICS section
1.1       .EX                          EXAMPLES section
1.1       .FI                          FILES section
1.1       .MI heading                  other miscellaneous sections
1.1       .NA command [section]        NAME section
1.1       .SE                          SEE ALSO section
1.1       .SY                          SYNOPSIS section
1.3       .al [type] [no_spaces]       begin automatically numbered list
1.3       .bl [no_spaces]              begin bullet list
1.8       .br                          break line
1.8       .de XX                       define macro
1.3       .dl [no_spaces]              begin dash list
1.5       .dp [type]                   begin display
1.5       .ed                          end display
1.6       .ep [begin] [end] [example]  example
1.8       .fi                          fill mode
1.8       .fo [bi]                     specify font change characters
1.8       .in [+n]                     indent
1.3       .le [label]                  list entry
1.3       .lx [no_space]               list exit
1.8       .ne n                        need lines
1.8       .nf                          no fill mode
1.2       .pp                          begin paragraph
1.7       .sk [n]                      skip pages
1.8       .so file                     include source file
1.8       .sp [n]                      space lines
1.8       .ta position ...             tab setting
1.4       .t&                          table continuation
1.4       .te                          table end
1.4       .ts                          table start
1.8       .ti +n                       temporary indent
1.3       .vl [indent] [no_spaces]     begin variably labeled list
