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

                         How to Create or Update

                       the UTS Programmer's Manual

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

                            TABLE OF CONTENTS


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

1.1      A tour of /usr/man . . . . . . . . . . . . . . . . . . . . .   1
1.2      The contents of /usr/man/man0  . . . . . . . . . . . . . . .   1

2.    Creating the Manual . . . . . . . . . . . . . . . . . . . . . .   1

2.1      The prman Command  . . . . . . . . . . . . . . . . . . . . .   2
2.2      Proof Reading  . . . . . . . . . . . . . . . . . . . . . . .   2
2.3      Printing on the Qume . . . . . . . . . . . . . . . . . . . .   2
2.4      Final Checks . . . . . . . . . . . . . . . . . . . . . . . .   2

3.    Updating the Manual . . . . . . . . . . . . . . . . . . . . . .   3

References  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   3


                                                            Last Page   3

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

1.    INTRODUCTION

The UTS Programmer's Manual [1] is  the primary source of information  on
the use of  the UTS Time-Sharing system.   As such it  is expected to  be
consistent, accurate, and current.  This  document describes the  process
of producing the manual, and  makes no attempt to advise on its  content.
See [2] for information on creating and formatting individual entries  in
the manual.


1.1      A TOUR OF /USR/MAN

This directory contains the source for the manual entries for each of the
three volumes of the manual  in man1/*.3, man2/*.2, and man3/*.3.   Files
also exist having  '.i' suffixes,  which are indirect  references to  the
actual source files.  The formatted output of each entry resides in vol1,
vol2, and vol3.  The  man0 directory contains  files used in  maintaining
and printing this manual.


1.2      THE CONTENTS OF /USR/MAN/MAN0

Makefile        for make'ing findman/[123] and ptx/[123]
findman/[123]   findman command data base
script0         used to make findman/[123]
ptx/[123]       permuted index for each volume
macs            macro package for the permuted index
synop/[123]     synopsis lines for entries in each volume
script2         used to make synop/[123]
prman           command that prints entire volumes of the manual
cover           source for the 3 cover sheets generated by prman
entry           skeleton manual entry




2.    CREATING THE MANUAL

The project herein described is not  trivial.  Several of the UTS  utili-
ties are used in the creation of some part of the manual.  The prman com-
mand in /usr/man/man0 was written in the hope that the person creating  a
new release would  not have to see  these in action.   It is possible  to
create a new  manual using  only the  prman command.   The next  sections
describe how this is done.

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

2.1      THE PRMAN COMMAND

The prman command formats one or more entire volumes of [1], for  viewing
on several different output devices.   It always formats in Qume  simula-
tion to mimic  the intended  final copy as  well as  possible.  The  '-Q'
option (the default) is used  for viewing the volume on a CRT.  The  '-e'
and '-p' options  send the  output directly to  the E1  or CCS  printers,
respectively.  The '-q'  option is  used for the  final (or  preliminary)
copy on the Qume.  This  command invokes make on  /usr/man/man0/Makefile,
and does  everything  else needed  to  produce an  entire volume  of  the
manual.  This  outputs a  cover sheet,  permuted index,  and all  entries
(including an introduction).


2.2      PROOF READING

Hard copy proof reading is the only way most errors can be found.   Three
complete readings, each by a  different person, of a line printer  output
is recommended.   Unfortunately, the  line printers  don't do  everything
that a Qume will.  Another complete copy for proofreading must be made on
the Qume.  Any pages that do not meet the standard or that are just  ugly
need to be  fixed and  reprinted until they  are acceptable.  Only  after
every page has been properly produced should the final copy be printed.


2.3      PRINTING ON THE QUME

Get a good supply of  ribbons and paper on hand.   The Qume will  produce
about one page per minute.  Plan to spend three nights  per copy watching
the machine.   A ribbon  will  last about  an  hour and  a  half.   Start
qprf'ing the file containing the  'prman -q' output.  If it is  necessary
to restart, such as to replace a ribbon,  edit this file to delete  those
pages already printed, and  then qprf it  again.  This will assure  left-
right page  consistency, and  guard  against any  changes to  the  manual
directories during the print process.  The original file should be  saved
in case it is necessary to go back and reprint some part.


2.4      FINAL CHECKS

By the time you get this far it is probably late at night or early in the
morning and the last  thing you want to do  is read the whole thing  over
again.  After putting as much  time on this project as  you have by  now,
you know the manual very well.  If there is a  mistake, you have probably
seen it enough times  that it looks  right.  The final  checks should  be
done by someone else who is familiar with what you've been doing, but who
hasn't been doing the work.  The  checker should look for print  quality,
missing entries  or pages,  or  inconsistencies such  as improper  fonts.
After the checker finishes, you should again look over the manual.

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

3.    UPDATING THE MANUAL

The simplest way to update the  manual is to periodically regenerate  it.
If you have a fast output device this is fairly feasible.  Alternatively,
you may wish to produce incremental updates.  The easiest way to do  this
is to eliminate page  numbers.  The philosophy  is that over a period  of
time some entries in the  manual will become  outdated, that new  entries
will need to be  added, and that it will  be better to release an  update
consisting only of the changes than to release an entire new manual.  The
format of a manual  entry must conform  to that of the previous  release.
See [2] for this information.  The things to include with an  incremental
update are:

New Pages       Be sure to start the page on the correct side.  Reproduce
                as many of the surrounding pages as necessary to maintain
                the left-right alternation.   It may not  be possible  to
                avoid using blank pages, but do try.

Blank Pages     Use blank pages  to maintain the  left-right paging,  but
                only if needed.

Permuted Index  Regenerate it.




REFERENCES

 [1]  UTS Programmer's  Manual, Volumes  1,  2 and  3.   See  findman(1),
      man(1), man(3), prman(3).

 [2]  "Formatting Manual Entries on UTS".
