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

                      Putting UTS Documents On-line

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

                            TABLE OF CONTENTS


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

2.    A Tour Through /usr/doc . . . . . . . . . . . . . . . . . . . .   1

3.    /usr/doc/src/enter  . . . . . . . . . . . . . . . . . . . . . .   2

4.    How to Add or Update a Document . . . . . . . . . . . . . . . .   2

5.    How to Create a doc-like Command  . . . . . . . . . . . . . . .   3

6.    References  . . . . . . . . . . . . . . . . . . . . . . . . . .   4


                                                            Last Page   4

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

1.    INTRODUCTION

The finddoc and  doc commands [1]  on UTS  allow users to  find and  view
documents about UTS on a  CRT terminal.  The purpose of this document  is
to describe how to update an on-line document or add a new one.  It  also
gives a  description of the  directories and  files used by  doc so  that
users interested in creating their own set of on-line documents can do so
easily.

The syntax of the doc command is

     doc [-f file] ... [title] ...

File and title are both file names.  The difference between them is  that
file may  be  any  file and  title  is the  name  of a  UTS  document  in
/usr/doc/out.  Throughout this document 'title'  (in bold) will mean  any
title  accepted  by  doc  and   consequently  the  name  of  a  file   in
/usr/doc/src, the name of a file in /usr/doc/out and the first word of  a
line in /usr/doc/Index.  Valid titles are displayed when no arguments are
given to doc.




2.    A TOUR THROUGH /USR/DOC

Document source,  formatted documents  and  a document  index  reside  in
/usr/doc.  It consists of two  directories -- src and out -- and a  file,
Index.

src    This directory contains document source  in save form for each  of
       the documents available to the doc command.  Some large  documents
       have  their  own   directory  named  title.    Also  included   in
       /usr/doc/src is a command called 'enter'.  It is described in Sec-
       tion 3.

out    This directory  contains the  formatted versions  of each  of  the
       documents available to doc.  When  doc prints valid titles, it  is
       dislaying an ls of this directory.

Index  This file is an index  of the documents found in  the src and  out
       directories.  Each document has a line in this file of the form

           Title~Document Name~Authors~Part Number~Date Released~Keywords

       where Title is the  title of  the document.  The  entries in  this
       file should be kept in alphabetical order by Title.  Feel  free to
       add Keywords  to this  file since  they are  now sparse.   Finddoc

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

       searches the entire file for the patterns given as arguments to it
       (using grep).

An important thing to note about /usr/doc is that for each document  with
the name title that is  available with doc there should be a file in  the
src directory named title+, a file named title in the out directory and a
line in the file Index whose Title is title.




3.    /USR/DOC/SRC/ENTER

The command /usr/doc/src/enter helps get documents from their source form
in /usr/doc/src to their  formatted form in /usr/doc/out.  The  following
discussion assumes that the source  for the document being entered  (non-
save format) is also  in /usr/doc/src/title or  /usr/doc/src/title/title.
Complete path names may be substituted if needed.

The syntax of the command is

     enter title

This takes title and runs it through ms,  tprf and awk before placing  it
in /usr/doc/out/title.  Ms and tprf format title using a special  charac-
ter table that will simulate  the Qume but still  make the document  look
acceptable on  both Memorex  and  COI terminals.   Awk uses  the  program
/lib/awk/sstodoc to reformat the output of ms so that it is more  attrac-
tive to look at on a CRT terminal.  This program and its effects are more
completely described in sstodoc [2].




4.    HOW TO ADD OR UPDATE A DOCUMENT

The steps involved in adding a  document or updating the on-line  version
of a document named  title are as  follows.  They assume that the  user's
current directory is /usr/doc/src.

 1.  Do a 'rest title+' unless it exists already.

 2.  Edit title until it is fixed.

 3.  Do an 'enter title'.

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

 4.  Do a save to create or update title+.

 5.  Make a new entry in /usr/doc/Index if the document is new or  update
     the existing entry if the document is being re-released.




5.    HOW TO CREATE A DOC-LIKE COMMAND

The doc command makes documents about UTS available for on-line  viewing.
The same commands and file  structure could display other types of  docu-
ments (documents  for a  particular  project for  instance)  with  little
change.  This section describes what is required to do this.

The files required for doc are:

          /bin/doc
          /bin/finddoc
          /usr/doc/Index
          /usr/doc/src/enter
          /usr/doc/src/*title*
          /usr/doc/out/title

To create a new doc system copies must be  made and new names chosen  for
/bin/doc, /bin/finddoc and /usr/doc.   For example, the new system  might
consist of

          /usr/td/bin/tddoc
          /usr/td/bin/findtddoc
          /usr/td/doc/src/enter
          /usr/td/doc/src/*title*
          /usr/td/doc/out/title

/usr/td/bin/tddoc, /usr/td/bin/findtddoc and /usr/td/doc/src/enter  would
be copies of /bin/doc, /bin/finddoc and /usr/doc/src/enter (all are shell
files) with  the  new file  names  substituted for  the  original  names.
/usr/td/doc/src and /usr/td/doc/out would contain the documents that  are
to be  available  with tddoc  and  follow  the same  rules  as  those  in
/usr/doc/src and /usr/doc/out.

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

6.    REFERENCES

 [1]  UTS Programmer's Manual, Volume 1.

 [2]  UTS Programmer's Manual, Volume 3.
