






        1.  BBuuiillddiinngg tthhee DDTTEE


             The Documentation Tools Environment package, or DTE,
             includes source code files from which the various tools
             are built, and source files from which the DTE
             documentation is built.  The DTE can be used to build
             and rebuild all OSF the documentation.  This documents
             contains requirements and instructions for building the
             DTE so that it can be used on your system.

             Depending on the manner in which you obtained the DTE
             package, its location on your system may vary. In the
             discussions that follow, _d_t_e-_d_i_r represents the base
             pathname at which the DTE tree has been loaded on your
             system.  (_d_t_e-_d_i_r can represent any number of actual
             directory levels.)  On a DTE distribution tape, the
             highest-level directory is DDTTEE; thus _d_t_e-_d_i_r//DDTTEE would
             represent the pathname of the DTE package once it has
             been loaded onto your system, and this designation has
             been used throughout this document.  If you have
             installed the DTE from some other source, however, the
             pathname may be different; if you received the DTE as
             part of an OSF/1 release tape, for example, the highest
             directory level would be:

             //_o_s_f-_b_u_i_l_d-_d_i_r/oossff11//VV11..11//ddoocc

             where //_o_s_f-_b_u_i_l_d-_d_i_r is the directory at which the
             distribution tape was loaded onto your system.  In the
             following pages, substitute the appropriate pathname on
             your system for _d_t_e-_d_i_r//DDTTEE.

             The _D_T_E _U_s_e_r'_s _G_u_i_d_e, located in _d_t_e-_d_i_r/DDTTEE//ddttee..ggdd in
             the DTE distribution tree (and elsewhere on the various
             OSF offering distributions), is not built when the DTE
             is installed; however, PostScript output versions of
             these documents are included in the tree.  You may
             rebuild these documents with the DTE tools after you
             have built the tools.  For further information, see
             BBuuiillddiinngg tthhee DDTTEE UUsseerr''ss GGuuiiddee below.

             NNoottee::  For a description of changes made to this
                    version of the DTE which are not
                    documented in the _D_T_E _U_s_e_r'_s _G_u_i_d_e, see
                    the section 1.6, LLaatteesstt CChhaannggeess iinn tthhee
                    DDTTEE.





                                   - 1 -











        1.1  RReeqquuiirreemmeennttss ffoorr BBuuiillddiinngg

             To build the documentation, you must have unloaded the
             DTE tree from your tape.  Approximately 3.5 megabytes
             of free local storage are required to transfer the DTE
             source and output files from the tape and to build the
             DTE tools.

             The DTE requires the UNIX system commands provided by
             the DOCUMENTOR'S WORKBENCH package (Version 2.0 or
             later), including eeppss (the device-independent ttrrooffff
             Postscript filter supplied with Elan's DWB package) or
             equivalent (the name may be different).  You must also
             have available the mmmm and mmaann maco packages, which are
             used by the DTE in conjunction with OSF's own
             customized macros, found in /_o_s_f-_b_u_i_l_d-
             _d_i_r/oossff11//VV11..11//ddoocc//ttoooollss//ssrrcc//mmaaccrrooss.

             NNoottee::  IIff yyoouu aarree iinnssttaalllliinngg aa nneeww vveerrssiioonn ooff
                    tthhee DDTTEE oovveerr aann oollddeerr vveerrssiioonn,, pplleeaassee
                    rreeaadd tthhee sseeccttiioonn bbeellooww eennttiittlleedd ""RRee--
                    rruunnnniinngg mmaakkee""..


        1.2  BBuuiillddiinngg tthhee DDTTEE

             NNoottee::  In order for you to build PostScript(TM)
                    versions of the documentation, your
                    system must have the appropriate
                    PostScript(TM) text-processing utilities.

             In the discussions that follow, it is assumed that the
             DTE tree has been loaded at the pathname _d_t_e-_d_i_r on
             your system, and that the highest level in the DTE tree
             is called DDTTEE, as on the DTE distribution tape.
             However, this directory may be different on your
             system.

               1.  The following directory should have been loaded
                   from the tape:

                   _d_t_e-_d_i_r/DDTTEE

                   and the DDTTEE directory contains the following
                   files and directories:

                   _d_t_e-_d_i_r/DDTTEE//RREEAADDMMEE
                   _d_t_e-_d_i_r/DDTTEE//ttoooollss (The DTE tree)
                   _d_t_e-_d_i_r/DDTTEE//ddttee..ggdd (_D_T_E _U_s_e_r'_s _G_u_i_d_e))





                                   - 2 -











                   where _d_t_e-_d_i_r is the directory where the DTE
                   image has been loaded.

               2.  Before installing the DTE, please read the
                   PPoossssiibbllee PPrroobblleemmss section to see if you need to
                   modify any files to accommodate your particular
                   system.

               3.  To perform the actual installation, type the
                   following command lines:

                   ccdd _d_t_e-_d_i_r/DDTTEE//ttoooollss//ssrrcc
                   mmaakkee TTOOPP==_d_t_e-_d_i_r//DDTTEE//ttoooollss MMAACCHHIINNEE==``mmaacchhiinnee`` iinnssttaallll

                   The rest of the line should be typed exactly as
                   it appears above.  The output from mmaacchhiinnee, which
                   is substituted into the command line by the
                   backquotes, enables mmaakkee to find out what your
                   machine-dependent subdirectory in _d_t_e-
                   _d_i_r/DDTTEE//ttoooollss//bbiinn is called; this is where the
                   machine-dependent executable files will be
                   installed.

                   If your system does not have the mmaacchhiinnee command
                   (you can test this by simply typing mmaacchhiinnee in
                   the shell), then replace ``mmaacchhiinnee`` with a
                   constant such as mmbbiinn.

                   There should be no errors reported by mmaakkee as it
                   does the install.

               4.  To use the tools, you must set the DDTTEE__LLIIBBDDIIRR
                   environment variable to:

                   _d_t_e-_d_i_r//DDTTEE//ttoooollss//lliibbddaattaa

                   and add the following directory to your search
                   path:

                   The directory that must be added is:

                   _d_t_e-_d_i_r/DDTTEE//ttoooollss//bbiinn//``mmaacchhiinnee``

                   Again, if you do not have the mmaacchhiinnee command on
                   your system, use the appropriate constant as
                   described above.

               5.  To make sure that the directory has been added to
                   your search path, you can now type the following:

                   bbooookk--ffoorrmmaatt --hheellpp



                                   - 3 -











                   which should display a summary of bbooookk--ffoorrmmaatt
                   usage.

                   To make sure that the DDTTEE__LLIIBBDDIIRR environment
                   variable has been correctly set, type:

                   eecchhoo $$DDTTEE__LLIIBBDDIIRR

               6.  You can now use the DTE tools.  For example, to
                   try bbooookk--ffoorrmmaatt, just ccdd to the directory
                   containing the Description file for the book you
                   want to process:

                   ccdd _b_o_o_k__d_i_r_e_c_t_o_r_y

                   where _b_o_o_k__d_i_r_e_c_t_o_r_y is the name of the directory
                   containing the Description file of the book you
                   want to build.  For example, you could try
                   building part of the _D_T_E _U_s_e_r'_s _G_u_i_d_e which is
                   included as part of the DTE package at _d_t_e-
                   _d_i_r/DDTTEE//ddttee..ggdd.  For further information on how
                   to do this, see the BBuuiillddiinngg tthhee DDTTEE UUsseerr''ss GGuuiiddee
                   section below.

               7.  Then, to test bbooookk--ffoorrmmaatt, type the following:

                   bbooookk--ffoorrmmaatt --tt aallll

                   You should get the following messages from bbooookk--
                   ffoorrmmaatt::

                   DDooiinngg ddrraafftt ffoorrmmaattttiinngg iinnttoo PPoossttSSccrriipptt

                   ffoorrmmaattttiinngg bbooddyy _c_h_a_p_t_e_r__f_i_l_e (_m_m) _f_o_r _p_s;  _p_a_r_t _n_n_n _o_f _m_m_m

                   If you get an error like the following:

                   DDooiinngg ddrraafftt ffoorrmmaattttiinngg iinnttoo PPoossttSSccrriipptt

                   ccaann''tt ffiinndd ffiillee ..//mmaaccrrooss//ssyynncc--pprree..mmmm

                   then you have not set the DDTTEE__LLIIBBDDIIRR environment
                   variable correctly; refer to step 4 above.


        1.2.1  EExxaammppllee

             Suppose the unbuilt DTE (that is, the DDTTEE tree) has
             been loaded onto your system at the pathname:

             _d_t_e-_d_i_r//DDTTEE



                                   - 4 -











             Now go to the _d_t_e-_d_i_r/DDTTEE//ttoooollss//ssrrcc directory and run
             mmaakkee to install the DTE by typing:

             ccdd _d_t_e-_d_i_r//DDTTEE//ttoooollss//ssrrcc
             mmaakkee TTOOPP==_d_t_e-_d_i_r//DDTTEE//ttoooollss MMAACCHHIINNEE==``mmaacchhiinnee`` iinnssttaallll

             Note again that if your system does not have the
             mmaacchhiinnee command, you should replace ``mmaacchhiinnee`` with a
             constant such as mmbbiinn; see step 3 above.

             After the installation, you should define the
             DDTTEE__LLIIBBDDIIRR environment variable and update your search
             path so that you can use the newly-built tools:

             sseetteennvv DDTTEE__LLIIBBDDIIRR _d_t_e-_d_i_r//DDTTEE//ttoooollss//lliibbddaattaa
             sseett ppaatthh==((_d_t_e-_d_i_r//DDTTEE//ttoooollss//bbiinn//``mmaacchhiinnee`` $$ppaatthh))


        1.2.2  PPoossssiibbllee PPrroobblleemmss

             This section contains information to help you avoid
             difficulties that may occur in installing the DTE.


        1.2.2.1  EEnnvviirroonnmmeenntt VVaarriiaabblleess

             The DTE tools use a set of environment variables to
             refer to various programs which they call to perform
             pre- and postprocessing tasks.  These programs can have
             different names on different systems; for example,
             ttrrooffff might be called ddiittrrooffff.

             If your system's versions of these programs have names
             different from the ones that the DTE tools expect them
             to have, you will have to change the value(s) of the
             environment variable(s).

             You should also add any changes that you make to these
             variables to your appropriate startup shell profile
             file, in order to make these directories a permanent
             part of your search path.

             Following is a list of the environment variables you
             may have to change.

             EEQQNN            Refers to the ttrrooffff version of the
                            mathematical expression preprocessor
                            used on your system.

             NNEEQQNN           Refers to the nnrrooffff version of the
                            mathematical expression preprocessor



                                   - 5 -











                            used on your system.

             TTRROOFFFF          Refers to the ttrrooffff used on your system.

             DDTTEE__OOUUTTFFIILLTTEERR  Refers to the PostScript postprocessor
                            used on your system.

             TTYYPPEESSEETTTTEERR     Refers to the PostScript typesetter used
                            on your system.


        1.3  LLooccaattiioonn ooff MMaakkeeffiilleess

             The following list tells where to find the MMaakkeeffiilleess
             and within the _d_t_e-_d_i_r//DDTTEE//ttoooollss tree.

                +o _d_t_e-_d_i_r//DDTTEE//ttoooollss//ssrrcc

                +o _d_t_e-_d_i_r//DDTTEE//ttoooollss//ssrrcc//ddttee

                +o _d_t_e-_d_i_r//DDTTEE//ttoooollss//ssrrcc//gglloossssaarryy

                +o _d_t_e-_d_i_r//DDTTEE//ttoooollss//ssrrcc//iinnssttaallllrreeff

                +o _d_t_e-_d_i_r//DDTTEE//ttoooollss//ssrrcc//mmaaccrrooss

                +o _d_t_e-_d_i_r//DDTTEE//ttoooollss//ssrrcc//ssmmll


        1.4  BBuuiillddiinngg tthhee DDTTEE UUsseerr''ss GGuuiiddee

             Printable PostScript versions of the _D_T_E _U_s_e_r'_s _G_u_i_d_e
             chapters can be found in _d_t_e-
             _d_i_r/DDTTEE//ddttee..ggdd//OOuuttppuutt//ddrraafftt//ppss; ASCII versions of these
             files are in _d_t_e-_d_i_r/DDTTEE//ddttee..ggdd//OOuuttppuutt//ddrraafftt//aasscciiii.

             Further information can be found in the _D_T_E _U_s_e_r'_s
             _G_u_i_d_e itself, and in the reference page for bbooookk--
             ffoorrmmaatt, which is located in _d_t_e-_d_i_r/DDTTEE//ttoooollss//mmaann//mmaann11
             (once you have built the DTE).


        1.4.1  TToo RReebbuuiilldd tthhee EEnnttiirree BBooookk iinn PPoossttSSccrriipptt

             To rebuild the book, follow these steps:

             ccdd _d_t_e-_d_i_r/DDTTEE//ddttee..ggdd

             and then:

             bbooookk--ffoorrmmaatt --tt aallll



                                   - 6 -











             to rebuild the PostScript output version, or:

             bbooookk--ffoorrmmaatt --nn aallll

             to rebuild the ASCII version.


        1.4.2  TToo RReemmoovvee tthhee OOlldd OOuuttppuutt FFiilleess

             You should do this only if you want to replace the
             output (i.e., PostScript or ASCII) files with rebuilt
             versions.  The following commands will remove _a_l_l the
             output files:

             ccdd _d_t_e-_d_i_r/DDTTEE//ddttee..ggdd
             rrmm --rr OOuuttppuutt
             rrmm --rr SSyynncc

             Note that the SSyynncc directory contains intermediate
             information used by bbooookk--ffoorrmmaatt to track individual
             pieces of the book as they are built separately, so you
             should not delete SSyynncc unless you plan to replace it
             immediately by invoking bbooookk--ffoorrmmaatt aallll.


        1.4.3  TToo RReebbuuiilldd aa PPaarrtt ooff tthhee BBooookk

             To rebuild only a part of the _D_T_E _U_s_e_r'_s _G_u_i_d_e, follow
             these steps:

             ccdd _d_t_e-_d_i_r/DDTTEE//ddttee..ggdd
             bbooookk--ffoorrmmaatt _p_a_r_t__o_f__b_o_o_k

             where _p_a_r_t__o_f__b_o_o_k is the part of the book you want to
             rebuild; the names of the book's parts come from the
             left-hand column of the book's Description file (they
             are _n_o_t necessarily the names of the source files).
             For further information, see the _D_T_E _U_s_e_r'_s _G_u_i_d_e.

             If the SSyynncc directory or any of its contents have been
             removed since the last bbooookk--ffoorrmmaatt --aallll, a single book
             part may not format properly.


        1.5  CCoonnttiinnuuoouuss WWiiddtthh FFoonntt SSppeecciiffiieerr

             Different versions of the Documenter's Workbench may
             require the constant width (i.e., typewriter) font to
             be specified in different ways.  The Elan package used
             at Open Software Foundation expects a \\ff((CCWW specifier;
             other software has been observed to expect \\ffCC.



                                   - 7 -











             Things being as they are, constant width font is
             requested in source in more than one way.  In books'
             front matter, which is coded in non-SML, the primitive
             codes \\ff((CCWW and \\ffCC occur.  The SML versions of these,
             \\**CC and \\**((CCWW, may also be present.  The other parts of
             the books should use SML codes only.  These consist of
             the primitives (again, \\**CC or \\**((CCWW), as well as those
             SML macros which implicitly request constant width
             font- the ..ooSS//..ooEE pair, for example.

             If your system expects a constant width specifier
             different from the one used in a book's source, you
             will quickly find out: bbooookk--ffoorrmmaatt will display an
             error message when it encounters the specifier and,
             under some circumstances, a core dump may occur.  If
             this happens with a book you are trying to format, do
             the following:

             Change primitives in source Change all instances of the
                                      incorrect ttrrooffff primitive to
                                      the form that is correct for
                                      your Documenter's Workbench
                                      software.  As mentioned above,
                                      these instances will probably
                                      all be in the book's front
                                      matter source files.

             Edit the hheeaaddeerr..aallll macro To correct places where
                                      constant width is requested by
                                      the SML macros, you should
                                      edit the hheeaaddeerr..aallll macro
                                      file, as described below.

             The file _d_t_e-_d_i_r/DDTTEE//ttoooollss//mmaaccrrooss//hheeaaddeerr..aallll contains
             the following:

             ...\"
             ...\" Copyright (c) 1991, OPEN SOFTWARE FOUNDATION, INC.
             ...\" ALL RIGHTS RESERVED
             ...\"
             ...\"
             ...\" header.all  --  header information for ALL formatting
             ...\"
             ...\"
             ...\" this file contains definitions of a very general nature.
             ...\" The intention is to define items that might get redefined
             ...\" under a different DWB, or provide global definitions.
             ...\"
             ...\"
             ...\"
             ...\" define the constant width font.  Instead of asking explicitly



                                   - 8 -











             ...\" for C or CW, everyone (in the macro packages) should use the
             ...\" string !) instead.
             ...\"
             .ds !) CW
             .ds !] (CW

             The two lines beginning ..ddss make \\**((CCWW the DTE's
             expected specifier for continuous-width font.  If you
             wish to change this to something else to suit the font
             name on your system, substitute your specifier for the
             CCWW.  For example, to make \\**CC the specifier, change the
             lines so that they read:

             .ds !) C
             .ds !] C

             Note especially the change in the second definition:
             the open parenthesis should be deleted if it is
             followed by a one-character specifier.


        1.6  LLaatteesstt CChhaannggeess ttoo tthhee DDTTEE

             This section consists of brief descriptions of
             important changes in this version of the DTE which were
             completed too late to be documented in the _D_T_E _U_s_e_r'_s
             _G_u_i_d_e.

                +o Changes to the Note Start and End macros (..nnSS and
                  ..nnEE)

                  These macros are now available in RSML as well as
                  in GPSML.

                  The ..nnSS macro continues to take a keyword that
                  describes the kind of note (supported keywords are
                  wwaarrnniinngg, ccaauuttiioonn, and rreevviieewwnnoottee).  If the
                  argument to the .nS macro is _n_o_t one of the known
                  keywords, then the argument will be used as a
                  banner for this note, allowing author creation of
                  new note types.

                +o Checks for termination of lists.

                  The RSML macros now check whether lists have been
                  terminated by the time a new section (..TTHH, ..SSHH, or
                  ..SSSS) begins.  If not, the lists are automatically
                  terminated (as before) during formatting, but a
                  new warning message is printed.





                                   - 9 -











                +o Index grouping of symbol characters

                  Index items that start with non-alphabetic
                  characters are now grouped together at the front
                  of the index under a SSyymmbboollss banner.

                +o Page running header and footer styles

                  All pages of a book, including the glossary and
                  index, now get a consistent page header and footer
                  style.  Left and right pages are now symmetrical,
                  providing a more balanced appearance, particularly
                  in books with parts (the ..ppAA macro).

                +o The table of contents

                  The glossary and index now appear in the table of
                  contents.

                +o The ddmmmm and ddmmaann commands

                  These commands now produce an appearance that is
                  more consistent with formatting outside of a book
                  context.  For example, page numbering style is not
                  _s_e_c_t_i_o_n-_p_a_g_e, but plain _p_a_g_e.

                  ddmmaann is still suitable for use when doing
                  production work (ie, the page and line lengths,
                  fonts, and point sizes are still consistent with
                  bbooookk--ffoorrmmaatt).

                +o Line spacing in RSML

                  A bug was fixed in RSML that sometimes caused too
                  little vertical white space between different
                  document elements (eg, between a list and a
                  paragraph).

                +o Outdenting of output regions

                  The ..ooSS macro now takes an optional argument that,
                  if present (any text at all -- it doesn't look at
                  the content of the argument, just for its
                  presence), will cause the output region to be
                  placed at the leftmost margin, eliminating the
                  need for an author to set the indent explicitly.

                +o The constant width font

                  The constant width font (eg, used by the ..ooSS
                  macro) has been made a little more compact by



                                   - 10 -











                  reducing the kerning.  This also allows a little
                  more constant width text to fit between the
                  margins of a document (viz, 72 characters from the
                  standard indent to the right margin, and 78
                  characters from the leftmost margin to the right
                  margin).


        1.6.1  PPaarrtt DDiivviissiioonnss ffoorr FFoorrmmaatttteedd BBooookkss

             Books can now be formatted into separate parts.  Parts
             can be realized in either of two different ways, each
             of which is described below.


        1.6.1.1  PPaarrttss WWiitthh CChhaapptteerrss

             You can specify part divisions (in addition to
             chapters) for any DTE-formatted book.  The parts are
             shown in the Table of Contents for the formatted book.
             In addition, the part title is shown at the top of
             every left-hand page; the book's title then appears at
             the bottom of every right-hand page.  The book's
             chapters become subordinate to the part in which they
             appear.

             There are two parts (as it were) to specifying this
             kind of formatting for a book:

                - Source code markup

                  At the spot in the book's source code where you
                  want the part to begin, the following line should
                  appear:

                  ..ppAA ""_p_a_r_t _n_u_m_b_e_r"" ""_P_a_r_t _T_i_t_l_e""

                  This line can be anywhere in the source files that
                  precedes the first chapter of the new part, and
                  follows the last chapter of the last (if any)
                  part.  We recommend that a separate file be
                  created to contain only this line; this makes it
                  easy to insert a new first chapter into the part,
                  if necessary.  Note that the ..ppAA command does _n_o_t
                  generate a part page.  If you want such a page,
                  you must write the source code for it yourself.
                  This code and the ..ppAA line could then be contained
                  together in a separate part page source file.

                - Description file keyword




                                   - 11 -











                  Besides coding the ..ppAA command in your book's
                  source, you must also put the following line
                  somewhere in the book's Description file:

                  ## PARTS

                  This line can appear anywhere in the Description
                  file; the convention
                   at OSF is to place it (with other options lines)
                  at the end.


        1.6.1.2  PPaarrttss IInnsstteeaadd ooff CChhaapptteerrss

             For books such as reference manuals, where chapter
             division is not desired, but parts are, an option is
             available to replace the chapters with parts in the
             formatted book.  The result is that what would
             ordinarily appear as chapters in the book's formatted
             Table of Contents are now called "Parts" there.

             To activate this option, you must put the following
             line somewhere in the book's Description file:

             ## CHAPTERPARTS

             This line can appear anywhere in the Description file;
             the standard practice at OSF is to place it (with other
             options lines) at the end.

             This option allows you to format a book _w_i_t_h parts, but
             _w_i_t_h_o_u_t separate part pages: in this case, the source
             files for the book can be identical to the chapter
             files for an "ordinary" book, and no special coding
             will be required.  However, if separate part pages are
             used, then some special coding is required to make sure
             that headers and footers do not appear on the formatted
             page and that pagination is correct.  As always,
             separate part pages have to be explicitly coded in the
             SML source.

             For example, suppose you want to divide a reference
             manual into parts, with separate part pages to mark the
             divisions within the book.  The Description file for
             such a manual, divided into four parts, would look
             something like the following, where pp11..ggppssmmll, pp22..ggppssmmll,
             etc., are the source files for the part pages:

             title   gpsml   FRONT frontmatter/title.gpsml
             copy    gpsml   FRONT frontmatter/copyright.gpsml
             pref    gpsml   PREFACE frontmatter/preface.gpsml



                                   - 12 -











             part1   gpsml   FRONT p1.gpsml
             p1.a    rsml    man1/a.rsml
             p1.b    rsml    man1/b.rsml
             part2   gpsml   FRONT p2.gpsml
             p2.d    rsml    man2/d.rsml
             p2.e    rsml    man2/e.rsml
             part3   gpsml   FRONT p3.gpsml
             p3.m    rsml    man3/m.rsml
             p3.n    rsml    man3/n.rsml
             part4   gpsml   FRONT p4.gpsml
             p4.x    rsml    man4/x.rsml
             p4.y    rsml    man4/y.rsml
             ## NO GLOSSARY
             ## CHAPTERPARTS
             ## OSFHEADS

             The important thing to note is the FFRROONNTT keyword in
             front of each part page source file.  FFRROONNTT is
             necessary to prevent headers and footers.  A typical
             part page (source, of course) might look like the
             following:

             ...\" Copyright 1991, Open Software Foundation, Inc.  ALL RIGHTS RESERVED.
             ...\"*********************************************************************
             .ad l   \"*** Sets left justification
             .PH ""  \"*** Prevent page header
             .PF ""  \"*** Prevents page footer
             ...\"*********************************************************************
             ...\"          Enter the title of the book:
             ...\"*********************************************************************
             .S 20
             .SP 1.5i
             .H 1 "Some RPC Commands"
             ...\"*********************************************************************
             ...\"          Enter the book's revision number
             .ad b   \"*** Resets justification


        1.6.2  OOSSFF MMaannppaaggee HHeeaaddeerrss

             The DTE's default behavior in formatting reference
             manuals is to construct the reference page header from
             the current chapter title. As an alternative, you can
             specify that the header should _a_l_w_a_y_s be the string
             OOppeenn SSooffttwwaarree FFoouunnddaattiioonn, or OOSSFF if the reference page
             name is too long to allow the full header string to be
             accommodated.  Use of this option is recommended only
             if you have _v_e_r_y long reference page names, or
             extremely long chapter titles.





                                   - 13 -











             To activate this option you must put the following line
             somewhere in the book's Description file:

             ## OSFHEADS

             This line can appear anywhere in the Description file;
             the standard practice at OSF is to place it (with other
             options lines) at the end.


        1.6.3  IInnddeennttiinngg ooff NNootteess

             The ..nnSS//..nnEE macro pair will now format the note text
             with both a left and a right margin equal to the width
             of the note label.  The label itself is flush with the
             current left margin.


        1.6.4  DDeeffaauulltt SSeettttiinnggss iinn DDiissppllaayy RReeggiioonnss

             The current default page widths (the, number of
             characters on a line in PostScript output) for ..ooSS//..ooEE
             regions are:

             Draft, text area: 66 characters (from the scanning
                       column indent)

             Draft, live area: 72 characters (from the left margin)

             Publish, text area: 56 characters

             Publish, live area: 66 characters

             Tab stops in ..ooSS//..ooEE and ..iiSS//..iiEE are now 8 columns
             apart.


        1.6.5  IInnddeexx GGeenneerraattiioonn

             Various changes have been made to Index generation:

             _S_e_e and _S_e_e _A_l_s_o now appear in the italic font

             Non-alphabetics now sort to the top of the index

             Indent positions for wrapping (long) items have been
                       changed

             Non-hyphenating dashes are now used for page numbers (a
                       change which has been implemented throughout
                       the macro packages)



                                   - 14 -











        1.6.6  MMiisscceellllaanneeoouuss CChhaannggeess

             The ..LLEE macro now resets the indent to the proper place
                       to allow following text to line up with the
                       previous indent.

             The ..VVLL macro in GPSML now has a default argument (11ii),
                       to match the ..VVLL default in RSML.

             The definition of the ..ggLL macro has been removed from
                       the ssmmll macro file (because it is already
                       defined elsewhere).  Other unneeded
                       definitions have been removed from
                       gglloossssaarryy..mmmm (iX, etc).

             UNNUMBERED sections now generate the "Chapter #" prefix
                       in the TOC.  Indentations of sections in
                       UNNUMBERED TOCs are now every 1/2 inch,
                       rather than the width of the maximum prefix.


        1.7  TThhee pprreeppeenndd--ssoo UUttiilliittyy

             NNoottee::  If you have used the iinnssttaallllrreeff utility
                    to install the OSF/1 reference pages on
                    your system, you do not need to use
                    pprreeppeenndd--ssoo as described below.

                    The presence of SML code, which requires
                    the presence of OSF's RSML macros in
                    order to be formatted, will prevent
                    reference page files being usable with a
                    standard mmaann command.

                    However, a small utility called pprreeppeenndd--
                    ssoo, which is included as part of the DTE,
                    will insert an ..ssoo request at the top of
                    specified reference page files, of the
                    form:

                    ..ssoo //ppaatthh//ttoo//mmaaccrroo//ffiilleess//rrssmmll


                    Whenever a reference page is formatted by
                    mmaann, the macro definitions are read into
                    the input stream, and all necessary
                    macros are present.  In the installed
                    DTE, these macro definitions are found in
                    the files:

                    _d_t_e-_d_i_r/_D_T_E/_t_o_o_l_s/_l_i_b_d_a_t_a/_m_a_c_r_o_s/_s_m_l



                                   - 15 -











                    and

                    _d_t_e-_d_i_r/_D_T_E/_t_o_o_l_s/_l_i_b_d_a_t_a/_m_a_c_r_o_s/_r_s_m_l


                    Once the reference page files have been
                    processed in this way, the macro
                    directories themselves cannot be moved.
                    OSF recommends putting a copy of the
                    appropriate SML/RSML macros in a place
                    like

                    /usr/share/lib/macros


                    or

                    /usr/lib/macros


                    which will ensure that they are in the
                    same filesystem as the reference pages
                    themselves (which should be in
                    //uussrr//sshhaarree//mmaann or //uussrr//mmaann), and so will
                    remain in the same location relative to
                    them.  pprreeppeenndd--ssoo checks for the
                    existence of pathnames specified with --
                    ssoo; non-existence of a pathname is a
                    fatal error.

                    Note that the pprreeppeenndd--ssoo utility is
                    _a_u_t_o_m_a_t_i_c_a_l_l_y _e_x_e_c_u_t_e_d _b_y _t_h_e iinnssttaallll--rreeff
                    _s_c_r_i_p_t, _p_r_o_v_i_d_e_d _w_i_t_h _O_S_F/_1 _s_n_a_p_s_h_o_t_s _a_n_d
                    _r_e_l_e_a_s_e_s.  (See Chapter 4 of the _O_S_F/_1
                    _S_n_a_p_s_h_o_t _a_n_d _R_e_l_e_a_s_e _N_o_t_e_s for
                    information about iinnssttaallll--rreeffppaaggeess).  Use
                    the following instructions only if you
                    have determined that pprreeppeenndd--ssoo has not
                    already been run on your system by
                    _i_n_s_t_a_l_l-_r_e_f_p_a_g_e_s.


        1.7.1  UUssiinngg ``pprreeppeenndd--ssoo''


             The pprreeppeenndd--ssoo utility can be used, if the DTE
             is installed, by simply typing its name followed
             by various flags and arguments.  The pathname of
             the RSML macros is one of the arguments you
             provide.  pprreeppeenndd--ssoo will process files whose
             names are given on the command line, or it will



                                   - 16 -











             process the input stream (ssttddiinn), sending output
             to ssttddoouutt.  Following is an explanation of the
             flags and arguments.


             pprreeppeenndd--ssoo  [[--ssoo  _m_a_c_f_i_l_e]] ...... [[_f_i_l_e]] ......



             --ssoo  <_m_a_c_f_i_l_e>      Pathname of file to ..ssoo at
                                 top of man files.  More than
                                 one --ssoo <<_m_a_c_f_i_l_e>> may be
                                 specified; multiple
                                 arguments should be
                                 specified in the order you
                                 want them included.

             [_f_i_l_e]              Man page file(s) to process.
                                 Wildcards can be used; see
                                 EExxaammpplleess below.

             --vv                  Verbose mode: show filenames
                                 of files as they are
                                 processed.

             --hheellpp               Display a help message.


        1.7.2  EExxaammppllee

             pprreeppeenndd--ssoo  --ssoo  //llooccaall//mmaaccrrooss//ffiillee11  --ssoo  //llooccaall//mmaaccrrooss//ffiillee22 << pprroogg..mmaann >> pprroogg..11


             Reads in the file pprroogg..mmaann, inserts the
             following lines at its top:

             .so /local/macros/file1
             .so /local/macros/file2

             and writes the resulting new file to pprroogg..11.


        1.7.3  EExxaammppllee

             pprreeppeenndd--ssoo  --ssoo  //llooccaall//mmaaccrrooss//ffiillee11  pprrooggAA..11  pprrooggBB..11


             Reads in the files pprrooggAA..11 and pprrooggBB..11
             successively, and inserts the following line at
             the top of each:




                                   - 17 -











             .so /local/macros/file1





















































                                   - 18 -






