                   <                                    Digital Internal Use Only                                          DOCTOR #                        User's Guide       "                        Don't Panic  N                        This document describes the functionality of the DOCTORO                        utility that allows manipulation of several VAX DOCUMENT I                        related input or output files as well as (minimal) 3                        conformant PostScript files.   M                        Although its size has grown over the years, it is easy P                        reading and you may only need to read a single chapter ifL                        you're only interested in a single feature of DOCTOR.        @                        Revision/Update Information:  DOCTOR V3.3  L                        Document release date          3-JAN-1994 17:37:26.09  G                                  DOCTOR is proprietary Digital software                                   <                                    Digital Internal Use Only                   /                        ________________________ #                        January 1994   !                        __________ L                        The information in this document is subject to changeF                        without notice and should not be construed as aK                        commitment by Digital Equipment Corporation. Digital N                        Equipment Corporation assumes no responsibility for any?                        errors that may appear in this document.   K                        The software described in this document is furnished H                        under a license and may be used or copied only inA                        accordance with the terms of such license.   N                        No responsibility is assumed for the use or reliabilityO                        of software on equipment that is not supplied by Digital I                        Equipment Corporation or its affiliated companies.   P                        Restricted Rights: Use, duplication, or disclosure by theN                        U.S. Government is subject to restrictions as set forthM                        in subparagraph (c)(1)(ii)  of the Rights in Technical O                        Data and Computer Software clause at DFARS 252.227-7013.   !                        __________ ;                         Digital Equipment B.V. 1990, 1994.   +                        All Rights Reserved. 3                        Processed in the Netherlands   !                        __________   H                        The following are trademarks of Digital Equipment#                        Corporation:   7                        DEC           DIBOL       UNIBUS 4                        DEC/CMS       EduSystem   VAX;                        DEC/MMS       IAS         VAXcluster 4                        DECnet        MASSBUS     VMS3                        DECsystem-10  PDP         VT (                        DECSYSTEM-20  PDT)                        DECUS         RSTS 8                        DECwriter     RSX         DIGITAL                    <                                    Digital Internal Use Only                                             Contents     U                         PREFACE                                                   vii   U                    CHAPTER 1  DOCTOR AT A GLANCE - QUICK OVERVIEW                 1-1   U                         1.1  QUESTIONS                                            1-1   U                         1.2  ANSWERS                                              1-3 U                              1.2.1  Add blank pages to a PostScript file          1-3 U                              1.2.2  Extract page range from PostScript file       1-4 I                              1.2.3  Adding diagonal wording to PostScript U                                     pages                                         1-4 U                              1.2.4  Adding footers to PostScript pages            1-5 K                              1.2.5  Adding headers to pages of a PostScript U                                     document                                      1-5 E                              1.2.6  Extract figures from a PostScript U                                     document                                      1-5 F                              1.2.7  Re-arrange pages for saddle-stitchU                                     printing                                      1-6 U                              1.2.8  List of an SDML document composition          1-6 U                              1.2.9  Automate document generation using MMS        1-6 U                              1.2.10 Prepare SDML file for Bookreader              1-7 U                              1.2.11 Produce a list of all <X> index entries       1-7 U                              1.2.12 Produce a list of all symbols defined         1-8 U                              1.2.13 Cross referencing between documents           1-8 U                              1.2.14 Sort a Glossary section                       1-9 U                              1.2.15 Count all tags used                           1-9 J                              1.2.16 Create SDML <MESSAGE_SECTION> from VMSU                                     Message source                               1-10 U                              1.2.17 Define dummy symbols                         1-10   U                    CHAPTER 2  DOCTOR'S COMPONENTS                                 2-1   U                    CHAPTER 3  DOCTORING SDML FILES: SORTING GLOSSARY ENTRIES      3-1   U                         3.1  OVERVIEW                                             3-1   U                         3.2  SORTING PROCESS                                      3-2   U                         3.3  SORT ORDER                                           3-3   U                         3.4  OPTIONS                                              3-4             U                                                                                   iii   A                                         Digital Internal Use Only                          Contents           Q                CHAPTER 4  DOCTORING VMS MESSAGE SOURCE FILES                  4-1   Q                     4.1  OVERVIEW                                             4-1   Q                     4.2  COMMENTING REQUIREMENTS FOR A MESSAGE FILE           4-2   Q                     4.3  INCLUDE RESULT IN DOCUMENTATION                      4-6   Q                     4.4  DOCTOR/MESSAGE FEATURES ON MESSAGE FILES             4-6   Q                CHAPTER 5  DOCTORING SDML FILES FOR BOOKREADER OUTPUT          5-1   Q                     5.1  OVERVIEW                                             5-1   Q                     5.2  EXAMPLE OF ONLINE CONVERSION                         5-2   Q                     5.3  INCLUDING PREDEFINED SYMBOLS                         5-5   Q                     5.4  GENERATING ADDITIONAL SYMBOLS                        5-5   Q                     5.5  THINGS TO REMEMBER                                   5-7 Q                          5.5.1  Using /OUTPUT                                 5-7 Q                          5.5.2  Using /VERSION_1                              5-7   Q                     5.6  ADDING SYMBOLS                                       5-8   Q                     5.7  ADDING REFERENCES                                    5-8   Q                     5.8  ADDING FIGURE FILES                                  5-8   Q                     5.9  WHAT MUST YOU DO?                                    5-9   Q                     5.10 REMOVING OR RENEWING ADDED SYMBOLS                   5-9   Q                CHAPTER 6  DOCTORING POSTSCRIPT FILES                          6-1   Q                     6.1  OVERVIEW                                             6-1   Q                     6.2  ADDING BLANK PAGES                                   6-2   Q                     6.3  REPLACING THE PROLOG                                 6-5   Q                     6.4  EXTRACTING RANGES                                    6-8   Q                     6.5  REMOVING OR RE-USING FIGURES                        6-10 Q                          6.5.1  Removing figures                             6-11 Q                          6.5.2  Extracting figures                           6-11   Q                     6.6  SADDLE STICH PRINTING                               6-12 Q                          6.6.1  Using an LPS40 to print the file             6-15 Q                          6.6.2  Using an LPS20 to print the file             6-16   Q                     6.7  MINIMAL CONFORMANT FILES                            6-16                   iv   <                                    Digital Internal Use Only         Q                                                                          Contents           K                CHAPTER 7  DOCTORING SDML FILES: HIERARCHY OF FILES WITHIN A Q                           BOOK                                                7-1   Q                     7.1  OVERVIEW                                             7-1   Q                     7.2  LISTING ALL INCLUDED FILES                           7-2   Q                     7.3  PRODUCING MMS REBUILD FILES                          7-4   Q                     7.4  USING THE MMS DESCRIPTION FILE                      7-11 Q                          7.4.1  What file to build?                          7-11 Q                          7.4.2  Another doctype than specified               7-12 Q                          7.4.3  Another destination than specified           7-12 Q                          7.4.4  Using DOCUMENT/GRAPHICS (Rags)               7-13   Q                     7.5  RETRIEVE ALL INDEX ENTRIES                          7-14   Q                CHAPTER 8  DOCTORING SDML FILES: COUNTING TAGS USED            8-1   Q                     8.1  OVERVIEW                                             8-1   Q                     8.2  OPTIONS                                              8-1   Q                     8.3  OUTPUT FORMAT                                        8-2   Q                     8.4  USAGE                                                8-2   Q                CHAPTER 9  DOCTORING XREF FILES                                9-1   Q                     9.1  OVERVIEW                                             9-1   Q                     9.2  BUILD SYMBOL LISTINGS                                9-2   Q                     9.3  BUILD CROSS REFERENCE SYMBOL FILE                    9-3   Q                     9.4  EXAMPLE OUTPUT                                       9-4 Q                          9.4.1  Symbol file output                            9-4 Q                          9.4.2  List file output                              9-5 Q                          9.4.3  Sorted list file output                       9-6                   COMMAND SECTIONQ                                 DOCTOR/GLOSSARY                                11 Q                                 DOCTOR/MESSAGE                                 14 Q                                 DOCTOR/ONLINE                                  16 Q                                 DOCTOR/PS                                      20 Q                                 DOCTOR/SDML                                    28 Q                                 DOCTOR/TAG_COUNT                               33 Q                                 DOCTOR/XREF                                    35   Q                                                                                 v   <                                    Digital Internal Use Only                         Contents           Q                APPENDIX A  ERROR MESSAGES                                     A-1   Q                     A.1  DOCMSG MESSAGES                                      A-1   Q                     A.2  DOCTOR MESSAGES                                      A-1   Q                     A.3  DTAGCOUNT MESSAGES                                   A-2   Q                     A.4  GLOSSARY MESSAGES                                    A-3   Q                     A.5  MARFIN MESSAGES                                      A-5   Q                     A.6  ONLINE MESSAGES                                      A-8   Q                     A.7  PSSCAN MESSAGES                                      A-9   Q                     A.8  SADDLE MESSAGES                                     A-16   Q                     A.9  XREF MESSAGES                                       A-20                   INDEX                  EXAMPLES   Q                     3-1  Glossary entry for DOCTOR/GLOSSARY                   3-2   Q                     4-1  Sample Message source file                           4-3   Q                     4-2  Sample DOCTOR/MESSAGE output                         4-4   Q                     5-1  Original file                                        5-2   Q                     5-2  Modified file                                        5-3   Q                     6-1  Conformant PostScript skeleton                      6-19   Q                     7-1  Hierarchy list produced by DOCTOR/SDML               7-5   Q                     7-2  Example DEC/MMS description file                     7-8   Q                     7-3  Output of DOCTOR/SDML/INDEX                         7-14   Q                     8-1  Sample DOCTOR/TAG_COUNT output file                  8-2   Q                     9-1  Sample .SDML_XREF output                             9-5                   FIGURES  Q                     6-1  Saddle stiched printing                             6-13                   TABLES   Q                     6-1  FONT keyword values                                  6-7   Q                     6-2  Extracting or removing figures                      6-10   Q                     7-1  Tags that cause other files to be included           7-2   Q                     7-2  DOCTOR/SDML qualifiers for DEC/MMS                   7-7   Q                     9-1  Alphabetic list of symbols                           9-6   Q                     9-2  Chapter symbols - in alphabetical order              9-7                   vi   <                                    Digital Internal Use Only         Q                                                                          Contents           Q                     9-3  Chapter symbols - in numerical order                 9-7                                                                                                 Q                                                                               vii   <                                    Digital Internal Use Only                   Q                __________________________________________________________________                   Preface  0                        Location and installation  I                        The DOCTOR utility can be found in and copied from   >                         NSIC00::PSQ:[PUBLIC.SOURCES.DOCTOR]*.*  G                        This includes the .EXE executable image and some O                        documentation for a variety of output devices, including N                        bookreader format. This document is also located there.@                        DOCTOR requires VAX/VMS V5.4-2 or higher.  P                        From V3.3-24 onwards, DOCTOR.EXE will work on all VAX/VMSO                        systems whether or not DEC/CMS is installed as a version I                        management product. Before this release, a special M                        version DOCTOR_NOCMS.EXE is required for sites that do 2                        not have DEC/CMS available.  F                        To use DOCTOR properly, it must be invoked as aM                        foreign command. This is achieved by defining a symbol K                        (preferably in your login command procedure so it is B                        always defined when you start a session) as  :                         $ DOCTOR :== $disk:[dir]DOCTOR.EXE  P                        The disk:[dir] part must be the location where you copiedN                        the program file into. If many people use this utility,M                        it is advisable to copy the program into the directory B                        pointed to by logical name DOC$LOCAL_TOOLS.  K                        If this is all done, you're ready to use the DOCTOR.u  9                                                 Important H                        Because DOCTOR is a collection of tools under oneL                        umbrella, it is important that each invocation startsL                        with the qualifier that indicates which tool you wantN                        to use: either DOCTOR/GLOSSARY, DOCTOR/PS, DOCTOR/SDML,P                        DOCTOR/ONLINE, DOCTOR/MESSAGE, DOCTOR/TAG_COUNT or DOCTOR                        /XREF.i  O                        A quick overview on how to use DOCTOR and what it can do4N                        for you, is provided in Chapter 1, DOCTOR at a glance -&                        Quick Overview.        Q                                                                               vii   <                                    Digital Internal Use Only    n                    Preface          M                        For problems, QAR's, and questions, please send a mailtK                        to Theo de Klerk via either NSIC00::KLERK or Theo desM                        Klerk @UTO. After mid-December 1993 the E-mail address L                        will be NSIC00::KLERK. Because DOCTOR is an unfunded,N                        free-time product, no support is guaranteed or implied.M                        However, the author will try to keep DOCTOR up to date P                        whenever possible. An additional platform for discussionsP                        on DOCTOR is its conference notes file on IJSAPL::DOCTOR.  -                        Availability of DOCTOR   M                        This utility is a product of DS/Country Program Office L                        in the Netherlands. It is developed to be used withinJ                        Digital Equipment Co. As of January 1st, 1993 it isO                        allowed to use this tool on customer sites, provided therN                        following conditions are explicitly communicated to the                         customer:  L                        1  DOCTOR is Digital proprietary software. It may notO                           be further duplicated, distributed or sold other than 3                           through Digital channels.   Q                        2  DOCTOR is an unsupported product. Although bug reports, L                           enhancement requests are welcomed, no guarantee isP                           given or implied that any modification will be made to!                           DOCTOR.   '                        Acknowledgements   F                        DOCTOR came into existence initially after someP                        discussions with Mark Devries on the topic of blank pages%                        in PostScript.   J                        The underlay features to include "draft" diagonallyH                        across the page was initally written in 1988 as aP                        PostScript routine by Lance McNulty, and later re-createdN                        for more general use by Chris Mackay, who also providedO                        the current PostScript code for the /PS/CHANGE function.   H                        Will Kohlbrenner provided much of the informationE                        required to interpret the XREF files for crossE#                        referencing.   P                        The /ONLINE code in VAX SCAN finally accepted nested tagsL                        after vital help from Barry Rogoff in showing how theM                        TRIGGER EXPOSE and NOTANY had to be combined. Mary UttaN                        provided test files and functioned as tester of /ONLINEA                        while V2.0 was still in engineering phase.4                  viiit  <                                    Digital Internal Use Only d  g    Q                                                                           Preface           N                        Others who were vital in providing me with some crucialL                        answers to questions raised during the development ofM                        DOCTOR are Sheila Huston, Sheila Lawner, David and Toms!                        Parmenter.   P                        Unfortunately, several of these people no longer work forM                        Digital and continued their career outside the company N                        - by choice or due to Digital's restructuring. It was a3                        privilege to work with them.f                                                                                Q                                                                                ixr  <                                    Digital Internal Use Only                         Preface          (                        Technical Changes  P                        Unfortunately, there is a non-upwards compatibility issueO                        for users of DOCTOR V3.0 or earlier and those using V3.1 !                        or higher.a  N                        You may need to modify command procedures using DOCTOR,P                        if they use the DOCTOR/SDML/MMS utility to produce an MMSN                        file to rebuild the document. All qualifiers related toP                        the specification of a doctype or destination name neededJ                        to be reworked, as DCL could not always distinguishO                        between them as more than the first four characters were !                        identical.G  L                        Removed are the qualifiers /LN03, /POSTSCRIPT, /LINE_M                        PRINTER, /MAIL, /BOOKREADER. The same functionality is N                        now made available in a single qualifier with keywords:  b                          /DESTINATION=(LN03= , POSTSCRIPT= , LINE_PRINTER= , MAIL= , BOOKREADER= )  L                        Default settings when not mentioned remained the sameD                        (LN03, PS, LINE, MAIL and BOOK respectively).  L                        Also removed are the qualifiers /DOCTYPE and /ONLINE_M                        DOCTYPE. They have been replaced with a similar singleE!                        qualifier:L  A                          /DOCTYPE=(PAPER= , ONLINE= , MANPAGE=  )N  L                        From V3.3-22 onwards, there is an incompatibility forN                        the /ONLINE/DUMMY_SYMBOL qualifier. Before V3.3-22 thisN                        qualifier would accept a file specification. From V3.3-M                        22 onwards, it takes two keywords: OUTPUT= which stillEP                        takes the output file spec and TEXT="string" to allow theP                        user to specify a text string as value for each undefinedL                        symbol. By default, /DUMMY_SYMBOL is equal to /DUMMY_O                        SYMBOL= (OUTPUT=infile.SDML_DUMMY_SYMBOLS), which is the 5                        same behaviour of pre-V3.3-22.   K                        From V3.3-24 onwards, there is no need for a special P                        version of DOCTOR that does not depend on DEC/CMS. By notN                        calling the CMS routines directly but through LIB$FIND_O                        IMAGE_SYMBOL, DOCTOR will discover itself whether or not 4                        DEC/CMS is available for use.                          x  <                                    Digital Internal Use Only 0  M                Q                __________________________________________________________________C  2        1       DOCTOR at a glance - Quick Overview      L                        This chapter will give a short overview to the DOCTORN                        utility and allows you to find the information requiredN                        quickly through a set of questions to be answered. ThisL                        chapter may be the only one you need to read as a new&                        user of DOCTOR.  Q                __________________________________________________________________1          1.1     Questions  ?                        1. What file needs to be used by DOCTOR?g  O                        o  A .PS PostScript file. Goto 3. What modification mustR9                           be made to the PostScript file?   P                        o  A .SDML VAX DOCUMENT source file. Goto 4. What must be2                           done with the SDML file?  N                        o  A .XREF cross reference file produced by a bookbuildO                           run of VAX DOCUMENT. Goto 5. What do you want to knowg.                           from the XREF file?.  M                        o  A .MSG VAX Message source file. See Section 1.2.16.   O                        o  Don't know but I know what I want to do. Goto 2. What 1                           is it you want to do? .   4                        2. What is it you want to do?  O                        o  Convert a VAX Message source file into a VAX DOCUMENTLL                           source file describing the messages in a <MESSAGE_#                           SECTION>.   K                        o  Get an overview of all symbols used in a documentNG                           written for VAX DOCUMENT. See Section 1.2.12.l  K                        o  Get an overview of all source files, figure filestO                           and other files used and referenced by a VAX DOCUMENTn>                           written document. See Section 1.2.8.  J                        o  MMS must automate the building of a VAX DOCUMENT>                           written document. See Section 1.2.9.  O                        o  Be able to refer to sections in one book from another K                           book, when both books are written in VAX DOCUMENT :                           source code. See Section 1.2.13.  Q                                                                               1-1O  <                                    Digital Internal Use Only         2                DOCTOR at a glance - Quick Overview          N                        o  Sort a VAX DOCUMENT glossary alphabetically althoughN                           the items are currently unsorted. See Section 1.2.14  O                        o  List all tags used in a VAX DOCUMENT written document D                           and their usage count. See Section 1.2.15.  L                        o  Add symbols to all VAX DOCUMENT tags in a documentL                           to allow the document to process correctly for theE                           BOOKREADER destination. See Section 1.2.10.   J                        o  Produce a VAX DOCUMENT source file that containsG                           <DEFINE_SYMBOL> tags for all symbols that are L                           referenced but not actually assigned to a specificG                           section, table or figure. See Section 1.2.17.   O                        o  Add blank pages to an unbalanced PostScript file. See (                           Section 1.2.1.  G                        o  Extract a section from a PostScript file. See (                           Section 1.2.2.  J                        o  Add a diagonal faint grey text on all pages of aA                           PostScript document. See Section 1.2.3.   G                        o  Add a footer to all pages. See Section 1.2.4.   G                        o  Add a header to all pages. See Section 1.2.5.   I                        o  Extract figures from a PostScript document. See (                           Section 1.2.6.  N                        o  Re-arrange pages in a PostScript file so I can printM                           them as a signature booklet (saddle stitching). See (                           Section 1.2.7.  P                        o  Number pages of an unnumbered PostScript document. See(                           Section 1.2.4.  P                        3. What modification must be made to the PostScript file?  O                        o  Add blank pages to an unbalanced PostScript file. See (                           Section 1.2.1.  G                        o  Extract a section from a PostScript file. See (                           Section 1.2.2.  J                        o  Add a diagonal faint grey text on all pages of aA                           PostScript document. See Section 1.2.3.   G                        o  Add a footer to all pages. See Section 1.2.4.   G                        o  Add a header to all pages. See Section 1.2.5.O  I                        o  Extract figures from a PostScript document. Seee(                           Section 1.2.6.                  1-2  <                                    Digital Internal Use Only         Q                                               DOCTOR at a glance - Quick Overview           N                        o  Re-arrange pages in a PostScript file so I can printM                           them as a signature booklet (saddle stitching). See (                           Section 1.2.7.  P                        o  Number pages of an unnumbered PostScript document. See(                           Section 1.2.4.  ?                        4. What must be done with the SDML file?   M                        o  A list must be produced of all files that make up a 6                           document. See Section 1.2.8.  N                        o  An MMS description file must be made to automate theE                           rebuild of the document. See Section 1.2.9.   Q                        o  The document must have symbols added to enable it to be M                           processed to a Bookreader file. See Section 1.2.10.i  J                        o  A list must be produced of all symbols used in a7                           document. See Section 1.2.12.   I                        o  A list of all index entries <X> and <Y> must be 7                           produced. See Section 1.2.11.   Q                        o  The glossary entries must be sorted alphabetically. Seer(                           Section 1.2.14  P                        o  A list of all tags used in the document must be given,E                           with their usage count. See Section 1.2.15.t  F                        5. What do you want to know from the XREF file?  H                        o  A list of all symbols defined in the book. See(                           Section 1.2.12  O                        o  A file defining all symbols of one book as symbols to O                           be used in another book for cross referencing between 4                           books. See Section 1.2.13.  Q                __________________________________________________________________   *        1.2     Answers____________________  3        1.2.1   Add blank pages to a PostScript fileo  P                        To be used only on documents that for some reason omittedI                        to include blank even (lefthand side) pages when a 3                        chapter ends on an odd page.s  O                         DOCTOR/PS /BLANK inputfile.PS [ /OUTPUT=outputfile.PS ]e  Q                                                                               1-3   <                                    Digital Internal Use Only X  S    2                DOCTOR at a glance - Quick Overview          M                        If you have a default blank page defined as PostScripteO                        file (e.g. with texts like "Left Blank") you can specifyeN                        such a blank page file with the /BLANK=blankpagefile.PS!                        qualifier.                           Example:   I                          DOCTOR/PS file.PS /OUTPUT=twosidedfile.ps /BLANK   4                        For details, see Section 6.2.  *                ___________________________  6        1.2.2   Extract page range from PostScript file  G                        Any page range or ranges can be extracted from a M                        PostScript file, provided you specify the correct pagefP                        values. These are mentioned inside the PostScript file onL                        the lines that start with %%Page:. With a DCL command  7                         $ SEARCH  inputfile.PS  %%Page:   M                        you will see all valid page values specified following (                        the %%Page: word.  6                        To extract a range then specify  G                          DOCTOR/PS inputfile.PS /OUTPUT=outputfile.PS - F                                /EXTRACT=(START=startpage, END=endpage)  O                        Or, when a number of pages must be printed following theT%                        starting page:/  G                          DOCTOR/PS inputfile.PS /OUTPUT=outputfile.PS -/N                                /EXTRACT=(START=startpage, NUMBER=integervalue)                          Example:f  K                          DOCTOR/PS completefile.PS /OUTPUT=partialfile.PS -Q<                              /EXTRACT=(START=4-6, END=5-2) -<                              /EXTRACT=(START=8-1,NUMBER=6) -B                              /EXTRACT=(START=INDEX-1, END=INDEX-9)  4                        For details, see Section 6.4.  *                ___________________________  :        1.2.3   Adding diagonal wording to PostScript pages  P                        To add a faint diagonal text to all pages of a PostScript$                        file, specify  e                         DOCTOR/PS inputfile.PS /CHANGE=(DIAGONAL="text string") /OUTPUT=outputfile.PSo  4                        For details, see Section 6.3.                  1-4  <                                    Digital Internal Use Only s  e    Q                                               DOCTOR at a glance - Quick Overviewr        *                ___________________________  1        1.2.4   Adding footers to PostScript pages   M                        To add a footer on all pages of a PostScript document, &                        use the command  c                         DOCTOR/PS inputfile.PS /CHANGE=(BOTTOM="text string") /OUTPUT=outputfile.PS   O                        To add a counter value on each page footer starting on a O                        certain positive integer value that increments with each $                        page, specify  ^                         DOCTOR/PS inputfile.PS /CHANGE=(COUNTER=integer) /OUTPUT=outputfile.PS  O                        The BOTTOM= and COUNTER= arguments can be combined. TheniK                        the number is appended to the specified footer text.                           Example:   \                          DOCTOR/PS inputfile.PS /CHANGE=(BOTTOM="text string", COUNTER=50) -5                                /OUTPUT=outfilefile.PS   4                        For details, see Section 6.3.  *                ___________________________  ?        1.2.5   Adding headers to pages of a PostScript document   L                        To add a text string at the top of each page, use the                        command  b                          DOCTOR/PS inputfile.PS /CHANGE=(TOP="text string") /OUTPUT=outfilefile.PS  4                        For details, see Section 6.3.  *                ___________________________  9        1.2.6   Extract figures from a PostScript documents  J                        When figures in a document are made as encapsulatedD                        PostScript files and included in the completeN                        document, you can extract those figures into individualP                        encapsulated PostScript files again by using the command:  @                          DOCTOR/PS inputfile.PS /FIGURES=EXTRACT  K                        Each figure will get the name it had originally whengN                        included into the document. If you want their filenamesK                        changed to reflect the page number on which they are >                        found in the complete document, specify  O                          DOCTOR/PS inputfile.PS /FIGURES=(EXTRACT, PAGE_NUMBER)l  N                        Whether a document has included encapsulated PostScriptK                        figures can be determined by searching for the lines H                        %%BeginDocument inside the input PostScript file.  4                        For details, see Section 6.5.  Q                                                                               1-5   <                                    Digital Internal Use Only e       2                DOCTOR at a glance - Quick Overview        *                ___________________________  :        1.2.7   Re-arrange pages for saddle-stitch printing  N                        To re-order the page order inside a PostScript documentO                        to allow for printing four pages at half size on the two O                        sides of a single sheet of paper so that the booklet can M                        be folded as a magazine, you must first ensure whether K                        the document has a balanced set of pages (containing P                        blank pages where needed - see Section 1.2.1 to do this).F                        Then, you can reorder the pages by the command:  L                          DOCTOR/PS/SADDLE inputfile.PS /OUTPUT=outputfile.PS  J                        Then the booklet is printed on an LPS20 double side6                        PostScript laser printer using:  b                          PRINT/QUEUE=lps20_PSqueue/PARAMETER=(SIDE=TUMBLE, NUMBER=2) outputfile.PS  4                        For details, see Section 6.6.  *                ___________________________  3        1.2.8   List of an SDML document compositiont  O                        A list of all files (figures, tables, elements etc) usedGI                        in one document can be produced using the command:L  M                          DOCTOR/SDML mainfile.SDML  [/OUTPUT=outputfile.SDML]i  K                        This results in a new version of the main file wheredN                        the structure of the document is written in a <COMMENT>N                        header at the start of that file. The main file must beN                        the file that is specified on the DOCUMENT command lineL                        for processing (i.e. the profile file in bookbuilds).  4                        For details, see Section 7.2.  *                ___________________________  5        1.2.9   Automate document generation using MMS   N                        To generate an MMS description file that can be used toN                        automate the processing of a VAX DOCUMENT document, use"                        the command  G                          DOCTOR /SDML mainfile.SDML /MMS  [/OUTPUT=NL:]r  K                        This results in a mainfile.MMS description. You mustcN                        specify /OUTPUT=NL: if you don't want to generate a newL                        mainfile.SDML that contains a listing of the documentA                        structure (as described in Section 1.2.8).Y                  1-6  <                                    Digital Internal Use Only S  w    Q                                               DOCTOR at a glance - Quick Overview           E                        You can also specify a specific doctype and/or J                        destination if you don't like the defaults (REPORT,K                        SOFTWARE.ONLINE, MANPAGE and LN03, LINE_PRINTER, PS, <                        MAIL, BOOKREADER, ROFF). For example:  9                          DOCTOR/SDML mainfile.SDML /MMS - O                              /DOCTYPE=(PAPER=MANUAL,  ONLINE=MANUAL.ONLINE, ) - X                              /DESTINATION=(POSTSCRIPT=POST, LN03=MY_OWN_LN03, MAIL=TEXT)  4                        For details, see Section 7.3.  *                ___________________________  /        1.2.10  Prepare SDML file for Bookreader   N                        A document must have symbols attached to all sectioningP                        tags, tables, examples and figures and these must also beP                        referenced using the <REFERENCE>. DOCTOR can add all thisP                        where it is not provided by the author using the command:  O                          DOCTOR/ONLINE mainfile.SDML [/SUPERSEDE] /OUTPUT=.SDML   M                        This will result in new versions of all files of which L                        the document consists with \BK_ADDED_nn symbols addedL                        where needed. When a document is modified or has beenH                        processed by DOCTOR/ONLINE before, the /SUPERSEDEL                        qualifier will remove all old symbols that were added;                        before adding new ones where needed.   K                        When many symbols are predefined in a special symbolrH                        file, these can be made known to DOCTOR too using  X                          DOCTOR/ONLINE mainfile.SDML /SYMBOL_FILE=filespec /OUTPUT=.SDML  2                        For details, see Chapter 5.  *                ___________________________  6        1.2.11  Produce a list of all <X> index entries  O                        To produce a text file in which all <X> and <Y> tags arerO                        listed, together with their origin (source file and line>>                        number) can be produced by the command:  J                          DOCTOR/SDML main_file.SDML /INDEX=outputfile_spec  N                        This output file can be used to check for typing errorsN                        where index entries should be identical and are not. By/                        sorting the output file:   4                          SORT index_file  index_file  M                        all <X> entries are sorted alphabetically and mistypedtP                        entries are easily discovered and can be corrected in the-                        original source files.   Q                                                                               1-7   <                                    Digital Internal Use Only         2                DOCTOR at a glance - Quick Overview          4                        For details, see Section 7.5.  *                ___________________________  4        1.2.12  Produce a list of all symbols defined  K                        When a bookbuild is performed on a profile file, VAX M                        DOCUMENT also produces a cross reference file with theiO                        name of the profile file and file type .XREF. This crossnK                        reference file can be inspected by DOCTOR and it canbO                        generate several tabular lists that describe all symbolseN                        and their translation when used with a <REFERENCE> tag.N                        These lists are produced in VAX DOCUMENT source format,N                        so the resulting files from DOCTOR must be processed by@                        VAX DOCUMENT (e.g. using REPORT doctype).  N                        To produce a list of all symbols in alphabetical order,                        use  C                         DOCTOR/XREF profilefile.XREF /LIST  [/FULL]   M                        When the /FULL is omitted, the tables only contain the M                        text that would be shown when <REFERENCE>(value) wouldo&                        have been used.  N                        To produce a list of all symbols sorted in alphabeticalJ                        order, but divided by their type (chapter, section,.                        figure, table etc), use  D                          DOCTOR/XREF profilefile.XREF /SORT  [/FULL]  K                        To produce a list of all symbols sorted in numerical I                        order (1.1, 1.2, 1.2.1 etc) and by their type, usei  M                          DOCTOR/XREF profilefile.XREF /SORT /NUMERIC  [/FULL]   4                        For details, see Section 9.2.  *                ___________________________  2        1.2.13  Cross referencing between documents  N                        When DOCUMENT performs a bookbuild, it produces a crossL                        reference file with the same name as the profile fileO                        and with file type .XREF. This file contains all symbolseN                        defined in the document and their value. It is possibleJ                        for DOCTOR to inspect this cross reference file andJ                        produce another SDML file with <DEFINE_SYMBOL> tagsK                        for each symbol in the file. This way, the resulting M                        SDML file can be included into another book (using theeJ                        <INCLUDE> or /SYMBOL= qualifier) and the symbols ofJ                        the first book be used in the second to allow cross1                        referencing between books.                   1-8  <                                    Digital Internal Use Only         Q                                               DOCTOR at a glance - Quick Overviewn          O                        To generate a symbol file from a book after VAX DOCUMENT L                        has produced the required .XREF file, use the command  ?                          DOCTOR/XREF profilefile.XREF /SYMBOL -d/                                /PREFIX=string -.?                                /BOOKTITLE="title of the book" - 8                                [/FULL | /VALUE | /TEXT ]  N                        A prefix can be added to all symbols to avoid collisionK                        with symbols defined in the second book. A booktitleoP                        should be specified to allow it to be named in the secondO                        book (e.g. "See 'European Tales', Chapter 5"). DependingbL                        on the use of /FULL, /VALUE or /TEXT the symbols willK                        contain only those parts that would be seen when the P                        <REFERENCE> was used with either the argument FULL, VALUE@                        or TEXT. When omitted, /VALUE is assumed.  4                        For details, see Section 9.3.  *                ___________________________  &        1.2.14  Sort a Glossary section  L                        When a VAX DOCUMENT source file contains a <GLOSSARY>M                        section, the defined terms can be written in any orderaP                        and DOCTOR can sort them alphabetically using the <GTERM>N                        tags for sorting. The rest of the document, outside theM                        glossary, remains untouched. To sort the glossary, use "                        the command  7                         DOCTOR/GLOSSARY  inputfile.SDMLu  O                        When a specific ordering is wanted, you can additionally.M                        specify the /SORT qualifier which has the same options_I                        as the /INDEX qualifier of the DOCUMENT command to P                        ensure that both glossary and index are sorted in similar                        fashion:r  R                          /SORT=( [LETTER|WORD] [,NONALPHA={AFTER|BEFORE|IGNORE}] )  2                        For details, see Chapter 3.  *                ___________________________  "        1.2.15  Count all tags used  O                        To obtain a list of all tags used and their usage count, .                        you specify the command  M                         DOCTOR/TAG_COUNT mainfile.SDML /OUTPUT=outputfile.TXTc  P                        This produces a plain text file where all tags are listedP                        alphabetically with the number of times the tag was used.  Q                                                                               1-9p  <                                    Digital Internal Use Only         2                DOCTOR at a glance - Quick Overview          O                        The main file specified is searched as well as any other 3                        file that is included by it.1  2                        For details, see Chapter 8.  *                ___________________________  D        1.2.16  Create SDML <MESSAGE_SECTION> from VMS Message source  M                        To convert a VAX/VMS message utility source file (filedP                        type .MSG into documentation for VAX DOCUMENT processing,P                        the message source file needs to be written in a specificP                        format, where each message is followed by a comment block%                        structured as::  6                         FNF <File !AS not found>/FAO=1                         !+,                         ! Explanation:  text,                         ! User Action:  text                         !-  P                        The comment block must start with !+ and end with !-. AnyP                        comment outside the block is ignored. The explanation andP                        user action text can span multiple lines. When a colon isD                        needed in the text, the <COLON> must be used.  L                        Message source files formatted as described above canL                        be converted into a VAX DOCUMENT .SDML file using the                        command  Q                          DOCTOR/MESSAGE vmsmessage.MSG [/OUTPUT=outputfile.SDML ])  2                        For details, see Chapter 4.  *                ___________________________  #        1.2.17  Define dummy symbolsr  P                        When a VAX DOCUMENT source references symbols that do notK                        (yet/anymore) exist, but the document should process I                        properly without aborting on warnings of undefined=M                        symbols, an SDML file can be produced that defines all P                        missing symbols with value "<REFERENCE>(missing_symbol)".N                        This file can then be either included with <INCLUDE> orA                        by the DOCUMENT command qualifier /SYMBOL.   P                        To produce such a file with <DEFINE_SYMBOL> tags, use the                        command:p  N                          DOCTOR/ONLINE mainfile.SDML /OUTPUT=NL:/DUMMY_SYMBOLS                  1-10H  <                                    Digital Internal Use Only         Q                                               DOCTOR at a glance - Quick Overviewc          O                        or, when many symbols are predefined in a special symboli                        file:  d                          DOCTOR/ONLINE mainfile.SDML /SYMBOL=symbolfilespec/OUTPUT=NL:/DUMMY_SYMBOLS  M                        This will keep track of conditions set and skip blocksmN                        that do not match the currently active condition. UsingL                        /CONDITION= allows you to specify such a condition toK                        DOCTOR, similar to the way you would specify this to >                        DOCUMENT. For details, see Section 5.4.                                                                              Q                                                                              1-11p  <                                    Digital Internal Use Only                     Q                __________________________________________________________________   "        2       DOCTOR's components      O                        The utility consists of several more or less independent O                        parts, each working on some sort of file produced by theaL                        VAX DOCUMENT typesetting software. Only the part thatK                        works on PostScript files can also be used for othertL                        PostScript files, as long as they adhere to the AdobeK                        specified minimal conformant file structure. This isEN                        defined in Appendix C of the "Red Book", the PostScriptO                        Language Reference Manual, published by Addison & WesleynO                        for Adobe Inc. DOCTOR supports both the Adobe structured K                        comments versions V2 (used by VAX DOCUMENT V1.2B and D                        V2.0-1) and V3 (used by VAX DOCUMENT V2.1-1).  P                        The types of files that can be handled by the DOCTOR are:  *                        o  PostScript files  D                        o  XREF cross reference files of VAX DOCUMENT  ;                        o  SDML source files of VAX DOCUMENTd  Q                        o  MSG message files of the VMS Message utility to produce $                           SDML files  D                        These will be discussed in the next chapters.                                      Q                                                                               2-1g  <                                    Digital Internal Use Only o  r                Q                __________________________________________________________________e  =        3       DOCTORing SDML files: Sorting glossary entriesg      Q                __________________________________________________________________e          3.1     Overviewt  F                        Using the DOCTOR/GLOSSARY qualifier invokes theK                        glossary item sort utility. It will accept the input J                        of any properly coded SDML source file with <GTERM>N                        entries and sorts these in ASCIIbetical order with someK                        small corrections on its collating sequence. Under auO                        properly coded file, it is understood that only a single K                        <GLOSSARY> - <ENDGLOSSARY> block exists in the .SDMLfM                        file. Multiple glossaries inside a single file are not +                        supported by DOCTOR.   L                        The glossary does not need to be the only part of theO                        file: it may be embedded in a larger SDML file. Only thetO                        glossary part is sorted. Text preceding or following thef:                        glossary section remains untouched.  7                                                   Note: F                             An informational header is produced in theE                             output file. This header is recognized by G                             *GL* markers. When new entries are added toCJ                             a previously sorted file, DOCTOR/GLOSSARY willH                             remove the original header and replace it byJ                             a new one. This can only be done if the headerI                             remains untouched. (It can always be manually 0                             removed, of course).  (                        Known limitations  7                        The following limitations apply:   I                        1  Only a single <GLOSSARY> block can exist in the M                           input file. Multiple glossaries in one file are not $                           supported.  Q                        2  DOCTOR/GLOSSARY ignores any <COMMENT> or <LITERAL> tagstM                           inside the glossary. This may lead to wrong resultsiN                           if a comment block includes all or part of a <GTERM>L                           / <GDEF> tag. It may then also cause <COMMENT> andM                           <ENDCOMMENT> to be sorted to different parts of theuK                           file. Comment blocks within the range of a singleiP                           glossary term are no problem. Comment blocks belongingK                           to a glossary term should follow its <GTERM>, notE  Q                                                                               3-1   <                                    Digital Internal Use Only .  I    =                DOCTORing SDML files: Sorting glossary entriesT          L                           preceed it. Comment blocks should also not span or/                           include <GTERM> tags.   Q                __________________________________________________________________u          3.2     Sorting process  L                        DOCUMENT/GLOSSARY sorts the input file by looking forK                        the first line that contains a <GTERM> tag. AnythingaJ                        preceding this tag will be copied verbatim into the#                        output file.   E                        All text between the first <GTERM> tag and the H                        tag <ENDGLOSSARY> will be sorted according to theK                        textual argument of the <GTERM> tag. A glossary termdI                        is considered to be all text from the start of theeN                        corresponding <GTERM> tag upto the position of the nextO                        <GTERM> (or the final <ENDGLOSSARY>). This means that it N                        is possible to insert other code such as <COMMENT>, <X>P                        or <Y> within this text block - either inside the <GTERM>P                        and associated <GDEF> tag argument, or as a separate tag,K                        not nested within an argument, as Example 3-1 shows.   F                        Example 3-1  Glossary entry for DOCTOR/GLOSSARYQ                        __________________________________________________________   *                        <GTERM>(Call frame)&                        <X>(call frame)                         <COMMENT>P                          Next definition is taken from Digital Press publication.                          "Digital Dictionary".#                        <ENDCOMMENT> [                        <GDEF>(Standard data structure built on the stack during a procedure Z                        or function call, starting from the location addressed by the frameW                        pointer (FP) register, to lower addresses. Same as stack frame.)   N                        <COMMENT>(This comment belongs to the Call Frame entry)  '                        <gterm>(Channel)dK                        <COMMENT>(This comment belongs to the Channel entry) *                        <x>(I/O<xs>channel)#                        <x>(channel)-^                        <gdef>(Logical path connecting user process with a physical device unit<                         to allow communication to the unit.)  Q                        __________________________________________________________                       3-2  <                                    Digital Internal Use Only l  s    Q                                    DOCTORing SDML files: Sorting glossary entriess        Q                __________________________________________________________________X          3.3     Sort order   M                        The <GTERM> tags can be coded in upper or lowercase or J                        mixed. The glossary entries are all sorted by theirL                        uppercase equivalent. However, the output retains the/                        original representation.C  N                        The sorting mechanism has been implemented similarly toL                        the /INDEX keywords of DOCUMENT. If you don't specifyM                        anything there, you don't specify anything with DOCTORaH                        /GLOSSARY to keep consistent sorting in index andN                        glossary. The following options are possible, which areM                        invoked by specifying keywords to the /SORT qualifier:   Q                        __________________________________________________________ Q                        /SORT=_________Description________________________________   N                        WORD           Sorts a term letter by letter (also non-N                                       alphabetical characters in the middle ofM                                       words) and treats spaces and hyphens aslO                                       significant. Mutual exclusive with LETTER   N                        LETTER         Sorts a term letter by letter (also non-N                                       alphabetical characters in the middle ofO                                       words), ignoring spaces and hyphens. ThisnP                                       is the default. Mutual exclusive with WORD  N                        NONALPHA=AFTER Place terms starting with non-alphabeticK                                       characters at the end of the glossaryl5                                       (following "Z")e  N                        NONALPHA=BEFOREPlace terms starting with non-alphabeticM                                       characters at the start of the glossaryw5                                       (preceding "A")c  K                        NONALPHA=IGNOREIgnore nonalphabetic characters. E.g.eO                                       "69WAYS" is sorted as "WAYS". This is theoQ                        _______________default.___________________________________u  O                        The default /INDEX=(LETTER,NONALPHA=IGNORE) is identical /                        to the DOCUMENT default.   F                        Some attempt is made to translate multinationalH                        characters back into "english characters" without#                        punctuation:o  H                        Any occurrence in the first string (match string)H                        is replaced by the character in the second string,                        (translation string):  6                        ''6                        'AAAAAAACEEEEIIIINOOOOOOOUUUUY'  Q                                                                               3-3a  <                                    Digital Internal Use Only    t    =                DOCTORing SDML files: Sorting glossary entries         Q                __________________________________________________________________o          3.4     Options  P                        There are few options available on the sorting mechanism.M                        The qualifier /OUTPUT allows to specify another outputuL                        file. By default the next higher version of the inputM                        file is created. A warning that a purge may delete thei<                        original file is issued in that case.                                                                                                  3-4  <                                    Digital Internal Use Only R                   Q                __________________________________________________________________   1        4       DOCTORing VMS Message source files<      Q                __________________________________________________________________           4.1     Overviewr  P                        When a software product is coded and one uses the VAX/VMSI                        error message utility to produce error messages on M                        SYS$ERROR when the software detects an error (like the O                        %DOCTOR messages you get from DOCTOR), the best place to N                        describe the reason of the error message occurring, andO                        what the user could possibly do to prevent it next time, P                        is to write this information immediately when the messageM                        is defined. That's when you know best which message is N                        added, why it was added and what you could do about it.  N                        The DOCTOR/MESSAGE utility will format a properly codedP                        source file with VAX/VMS message definitions and embeddedO                        comments in such a way that the comments of the file arerN                        reformatted into a <MESSAGE_SECTION> section, ready forN                        inclusion into the User's Guide message appendix of theO                        documentation that describes the software to which these -                        error messages belong.   7                                                   Note: C                             If you use DOCTOR/MESSAGE/HELP then the A                             produced .SDML file is compatible for H                             processing with the HELP.MESSAGE doctype andI                             the MDFI destination, that is currently underOF                             development by CUIP. This will result in aF                             .MDFI help file for the Alpha VMS and OpenF                             VMS utility HELP/MESSAGE that gives onlineI                             access to the message explanation of any base H                             or layered product running on that platform.J                             See note 6.* in the SQM::BLADE_INFO notes file=                             for more details on this utility.   J                        The produced SDML file can be <INCLUDE>d into a VAXP                        DOCUMENT source that is processed for the SOFTWARE family                        doctype.   P                        The error messages found in Appendix A are made by DOCTORP                        /MESSAGE from the message file that belongs to the DOCTORN                        utility sources, and is included into this User's Guide                        bye  Q                                                                               4-1M  <                                    Digital Internal Use Only         1                DOCTORing VMS Message source filesS          :                        <APPENDIX>(Error messages\apperror)1                        <include>(DOCTOR_MSG.SDML)1$                        <ENDAPPENDIX>  K                        You can look there to get an impression on the final                         output.  Q                __________________________________________________________________g  9        4.2     Commenting requirements for a message filen  K                        The VAX Message file must conform to the VAX MessagemP                        Utility standard. This means that each message definitionN                        is one line and upto 255 characters in length. AnythingG                        following an exclamation mark ("!") on a line ishL                        considered comment or (if part of the message text) a%                        FAO directive.E  I                        DOCTOR/MESSAGE will use comment lines to allow the O                        programmer to describe the reasons for the error message O                        to be signalled to the user and possible user actions to O                        avoid this situation from happening again. These comment L                        lines must adhere to a certain structure that will be&                        explained next.  C                        DOCTOR/MESSAGE will start by reading all theeE                        facility definition lines (.FACILITY) and sorttH                        them alphabetically. Each facility will produce aI                        <HEAD1>(facility name) section in the output file.h  L                        Next, it will read all the symbolic message names and5                        also sort them alphabetically.   P                        Finally, it will scan through the comment lines followingL                        a message line and reformat it into VAX DOCUMENT. TheM                        comments following a message line are considered to be_K                        describing that message. They are only recognized by'N                        DOCTOR/MESSAGE when they are written in a comment block@                        that starts with "!+" and ends with "!-".  M                        A small example of the message file source code to thetM                        DOCTOR utility and the resulting message code for thislL                        User's Guide is shown in Example 4-1 and Example 4-2.                            4-2  <                                    Digital Internal Use Only    s    Q                                                DOCTORing VMS Message source files         >                        Example 4-1  Sample Message source fileQ                        __________________________________________________________u  (                        .TITLE doctor_msg$                        .IDENT 'V1.0'B                        .FACILITY doctor,1/PREFIX=doc_            1(                        .SEVERITY SUCCESS                        .BASE 1  B                        .SEVERITY INFORMATIONAL                   2                         .BASE 100B                        IDENT    <This is !AS version !AS>/FAO=2  3                          !+ e                          !4Explanation: Indicates the current version of the utility that is invoked. d                          !   This is important when bugs and wishes are expressed to the development"                          !   team.                          !V                          !5User Action: Specify number when submitting SPR's or QAR's.                          !- M                        NOTIMPL  <Functionality !AS not yet implemented>/FAO=1_                          !+ `                          ! Explanation: The specified functionality is not yet implemented, evenM                          !   though the command interface is already present.                           !P                          ! User Action: Wait till the next release or inquire at=                          !       NSIC00<colon><colon>KLERK. 6                           !-lX                        SENDQAR    <Internal error. Please send QAR. Error ID: !AS>/FAO=1                          !+s_                          ! Explanation: You managed to give a set of input data that caused the ^                          !   utility program to go to "catch all" statements that should never(                          !   be reached.                          !^                          ! User Action: Please notify the developers by SPR or QAR, describing[                          !   the error and specifying the version of the software used, thea^                          !   error messages displayed and possibly a sample of the input files`                          !   that caused the error to occur, together with the specified command'                          !   statement.                           !                          !-l  Q                        __________________________________________________________e  P                        Some comments to the original message source file and the+                        produced .SDML file:s  M                        1  The .FACILITY is used to compose a <HEAD1>(facility J                           title\MSG_facility) section tag. They are sorted)                           alphabetically.   N                        2  The severity level will be printed with each messageG                           description as a <MSG_TEXT>(Severity:) entry.   M                        3  The message ident and string is used to compose the1<                           message entry using the <MSG> tag.  Q                                                                               4-3   <                                    Digital Internal Use Only g  e    1                DOCTORing VMS Message source files         @                        Example 4-2  Sample DOCTOR/MESSAGE outputQ                        __________________________________________________________   @                        <HEAD1>(DOCTOR Messages\MSG_DOCTOR)     1(                        <MESSAGE_SECTION>3                        <DEFINE>(COLON\:\0\0\\\:)  7 Z                        <MSG>(IDENT\This is <EMPHASIS>(string) version <EMPHASIS>(string))3!                        <X>(IDENT)l.                        <MSG_TEXT>(Severity)  2$                        INFORMATIONAL4                        <MSG_TEXT>(Explanation)     4T                        Indicates the current version of the utility that is invoked.^                        This is important when bugs and wishes are expressed to the development                        team.1                        <MSG_TEXT>(User Action)  5 E                        Specify number when submitting SPR's or QAR's._  Z                        <MSG>(NOTIMPL\Functionality <EMPHASIS>(string) not yet implemented)#                        <X>(NOTIMPL)S+                        <MSG_TEXT>(Severity) $                        INFORMATIONAL.                        <MSG_TEXT>(Explanation)O                        The specified functionality is not yet implemented, even G                        though the command interface is already present.G.                        <MSG_TEXT>(User Action)?                        Wait till the next release or inquire at 3                        NSIC00<colon><colon>KLERK. 6r  c                        <MSG>(SENDQAR\Internal error. Please send QAR. Error ID: <EMPHASIS>(string))c#                        <X>(SENDQAR)i+                        <MSG_TEXT>(Severity)R$                        INFORMATIONAL.                        <MSG_TEXT>(Explanation)N                        You managed to give a set of input data that caused theX                        utility program to go to "catch all" statements that should never"                        be reached..                        <MSG_TEXT>(User Action)M                        Please notify the developers by SPR or QAR, describingaU                        the error and specifying the version of the software used, the_X                        error messages displayed and possibly a sample of the input filesZ                        that caused the error to occur, together with the specified command!                        statement.b  *                        <UNDEFINE>(COLON) 8+                        <ENDMESSAGE_SECTION>T  Q                        __________________________________________________________   L                        4  The comment block following the message definitionO                           is split in comment entries. Each entry starts with adN                           short header. DOCTOR/MESSAGE interprets each commentP                           line. If a colon is encountered, the first part of theP                           line is made into a <MSG_TEXT> entry, the remainder ofQ                           the line (plus possible subsequent lines) form the body ;                           of the message entry description.                   4-4  <                                    Digital Internal Use Only         Q                                                DOCTORing VMS Message source files           P                        5  Same as previous entry. Following the Digital standardL                           for message descriptions, two entries are made perJ                           message: an Explanation and User Action section.  N                        6  If you want to use the colon (:) as part of the textN                           without DOCTOR/MESSAGE interpreting this as an entryQ                           heading, use the tag <COLON> which is defined by DOCTORuM                           /MESSAGE at the start of the message section outputsQ                           and undefined at the end of it (so it is not a standardi)                           DOCUMENT tag!).   /                        7  Definition of <COLON>   -                        8  Undefine of <COLON>a  N                        The following lines are required by both DOCTOR/MESSAGEI                        and the VAX Message utility to work properly. NotesN                        that you should not run DOCTOR/MESSAGE on a source fileN                        without having been able to properly compile the sourceM                        by the MESSAGE command. DOCTOR/MESSAGE does not do the_N                        same intensive checking as MESSAGE and partly relies on&                        correct syntax.  M                        .FACILITY      Once for each set of facility messages. M                                       The facility name is used to create the O                                       <HEAD1> heading for that message section. M                                       Abbreviated forms of the word .FACILITY 2                                       are allowed.  N                        .SEVERITY      Required to specify the type of severityM                                       of the message described. It is used byeN                                       DOCTOR/MESSAGE to write this informationO                                       in the Severity: part of the output. Each L                                       message can also have its own severityL                                       indicated using the /WARNING, /SUCCESSM                                       etc. qualifiers attached to the message O                                       definition line. Abbreviated forms of theN@                                       word .SEVERITY are allowed                      Q                                                                               4-5_  <                                    Digital Internal Use Only         1                DOCTORing VMS Message source filesa          2                        message line   Formatted as  H                                         messagename  < text >/qualifiersH                                         messagename  " text "/qualifiers  J                                       where the text message is surroundedH                                       by either quotation marks or angleM                                       brackets. This line is output literally J                                       into the DOCTOR/MESSAGE output file,L                                       sorted alphabetically on message name.H                                       By default, the FAO directives areM                                       replaced by generic strings like stringrO                                       or number, depending on the FAO directive_K                                       encountered. Also UIC, time, date and P                                       other directives are properly substituted.K                                       If this is not wanted, specify DOCTOR G                                       /MESSAGE/FAO on the command line.   Q                __________________________________________________________________   .        4.3     Include result in documentation  O                        The resulting message document file can be included into N                        appendices of the user publications or made part of theL                        Detailed Design Specification. Both will then have an(                        identical format.  J                        As such, the following use of the message output is!                        suggested:_  4                           <APPENDIX>(Error messages)5                           <INCLUDE>(messagefile.SDML)s                               : 4                             additional message files                               :R'                           <ENDAPPENDIX>k  Q                __________________________________________________________________t  7        4.4     DOCTOR/MESSAGE Features on Message Files   J                        The comments related to a message are recognized byO                        DOCTOR/MESSAGE only if they are written within a specialm2                        comment block, formatted as                            !+ 8                          !  header text: additional text                          !                          !-   G                        This comment block should follow the VMS message .                        definition immediately.                  4-6  <                                    Digital Internal Use Only t  f    Q                                                DOCTORing VMS Message source filesa          K                        The header text is output as a boldly written set of O                        words, followed by one or more lines of additional text. P                        The separation between header text and the remaining textN                        is made by the colon (":"). As such the additional textN                        should not use this character. If the colon is requiredL                        as part of the explanatory text, then use the <COLON>                        tag.h  L                        To conform to the Digital standard way of documentingF                        error messages, the following use is suggested:  G                          message_name  <error message text> /qualifierst                             !+1                             ! Explanation:   text                              ! 1                             ! User Action:   text                              !-O                             !  additional comments not meant for DOCTOR/MESSAGE                              !u  L                        Note that any comment written outside a comment blockN                        delimited by the "+" and "-" will not be seen by DOCTORO                        /MESSAGE. In addition, the entire message can be omittedsO                        from the SDML output if the message line itself containsmN                        a comment trailer that contains either !* or !*Skip* as                        text:  P                          message_name  <error message text> /qualifiers  !*SKIP*                             !+1                             ! Explanation:   textD                             ! 1                             ! User Action:   texti                             !-]                             !  Despite the !+ and !- marked comment block, the entire message a                             !  is not copied into the SDML output file due to the !*SKIP* commenti3                             !  on the message line.                              !_                        Q                                                                               4-7l  <                                    Digital Internal Use Only h  A                Q                __________________________________________________________________   9        5       DOCTORing SDML files for Bookreader outputh      Q                __________________________________________________________________           5.1     Overviewe  N                        VAX DOCUMENT can be used to build books for printing onO                        paper, but also for using them as online books using the E                        DECwindows Bookreader on either VMS or ULTRIX.   K                        Unfortunately, the Bookreader product imposes a moreaM                        strict use of some of the tags, available in DOCUMENT,hO                        due to its unique features of "pop up" elements (tables,tN                        figures, examples) that appear when you click on a "hot                        spot".   J                        Because any part of the document must be accessibleL                        from the table of contents, a symbol must be attachedN                        to them so an implicit reference is made from the table=                        of contents to the section pointed at.e  L                        DOCTOR/ONLINE will go through your SDML files and addL                        symbols where there are none, and also add referencesM                        to pop up elements, where none is written in the text. O                        If you specify a profile file, all elements will also be P                        searched, as will any file referenced in a <INCLUDE> tag.N                        Specifying /LOG will show you which files are accessed.  H                        The following tags are modified by DOCTOR/ONLINE:  J                        o  <HEAD>, <CHEAD>, <HEADN>, <CHAPTER>, <GLOSSARY>,P                           <PART>, <APPENDIX>, <FRONT_MATTER> - a symbol is added(                           if not present  N                        o  <SUBHEADN>, <PREFACE>, <PREFACE_SECTION>, <COMMAND>,N                           <ROUTINE>, <SDML_TAG>, <STATEMENT>, <SUBCOMMAND> - aI                           symbol is added unless /VERSION_1 is specified.E  Q                        o  formal <EXAMPLE>, <TABLE>, <FIGURE> - a symbol is added_J                           if not present, a <REFERENCE> to them is created  J                        o  <FIGURE_FILE>(book\..\..) is added to supplementB                           existing figures for other destinations.  D                        The following tags are used by DOCTOR/ONLINE:  O                        o  <ELEMENT>, <INCLUDES_FILE>, <INCLUDE> - to read these =                           files as well during the processing   Q                                                                               5-1e  <                                    Digital Internal Use Only    i    9                DOCTORing SDML files for Bookreader outputp          N                        o  <FIGURE_FILE> - to create a similar one for the BOOK&                           destination.  M                        o  <REFERENCE> to track down all references to symbolsN  O                        o  <DEFINE_SYMBOL> which defines additional symbols that ;                           may be referenced by <REFERENCE>.i  N                        o  <DEFINE_BOOK_NAME> which defines a symbol for a user.                           specified book title  I                        o  <SET_CONDITION>, <CONDITION> and <ENDCONDITION>lJ                           tags. During Pass 1, when all symbol informationL                           is collected, DOCTOR will skip any conditionalizedO                           text block whose condition does not match the current P                           conditional setting. It will however, generate symbolsN                           for all tags that need one, regardless of condition.  N                        To prepare files for use with DOCUMENT V1.2B you shouldK                        specify /VERSION_1. No harm done if you forgot: justeK                        reprocess those files with /VERSION_1 and any symboldL                        added on tags that should not have a symbol for V1.2B-                        will be removed again.l  Q                __________________________________________________________________g  +        5.2     Example of ONLINE conversion   K                        An example of original input versus converted output I                        file can be seen in Example 5-1, Original file and_2                        Example 5-2, Modified file.  1                        Example 5-1  Original file Q                        __________________________________________________________s  ,                        <chapter>(unsymboled)2                        <head1>(section head1\s1_1)                          <p>]                        Test for V1.2B and V2 differences: it should not add symbols for V1.2B .                        <subhead1>(A subheader)  :                        It should not add one if it had oneH                        <subhead1>(A subheader with symbol\subheadsymbol)  M                        Test for informal figures - should add figurefile only                         <figure> 2                        <figure_file>(ps\fig.ps\10)"                        <endfigure>  Q                        __________________________________________________________ ;                        Example 5-1 (continued on next page)                   5-2  <                                    Digital Internal Use Only    <    Q                                        DOCTORing SDML files for Bookreader output         9                        Example 5-1 (Cont.)  Original file Q                        __________________________________________________________   O                        Test for symbol adding, reference adding and file adding /                        <figure>(figure caption) 9                        <figure_file>(ln03\ln03fig.six\10)c"                        <endfigure>  9                        Test for same, no reference addingt(                        <reference>(f1_1)4                        <figure>(figure caption\f1_1)9                        <figure_file>(ln03\ln03fig.six\10) "                        <endfigure>  I                        Test for same, no reference adding, no file addingS(                        <reference>(f1_2)4                        <figure>(figure caption\f1_2)9                        <figure_file>(ln03\ln03fig.six\10) 9                        <figure_file>(book\bookfig.fse\10) "                        <endfigure>  ;                        Test for same, reference adding only 4                        <figure>(figure caption\f1_3)9                        <figure_file>(ln03\ln03fig.six\10) 9                        <figure_file>(book\bookfig.fse\10) "                        <endfigure>  A                        Test for same, reference adding only againQ4                        <figure>(figure caption\f1_4)4                        <FIGURE_SPACE>(42\left blank)"                        <endfigure>  A                        Test for same, reference adding only again 4                        <figure>(figure caption\f1_5)!                        <line_art> #                           somethinga$                        <endline_art>"                        <endfigure>  9                        Add symbol and reference to table. +                        <table>(small table)A*                        <table_setup>(2\10)5                        <table_row>( 1 \ the only row)h!                        <endtable>s  2                        <head1>(section head1\s1_2)  -                        <head1>(section head1)t  Q                        __________________________________________________________   1                        Example 5-2  Modified file Q                        ___________________________________________________________  Q                        __________________________________________________________l;                        Example 5-2 (continued on next page)l  Q                                                                               5-3d  <                                    Digital Internal Use Only    i    9                DOCTORing SDML files for Bookreader output         9                        Example 5-2 (Cont.)  Modified file Q                        __________________________________________________________d  7                        <chapter>(unsymboled\BK_ADDED_1)i2                        <head1>(section head1\S1_1)                          <p>]                        Test for V1.2B and V2 differences: it should not add symbols for V1.2Bc9                        <subhead1>(A subheader\BK_ADDED_2)o  :                        It should not add one if it had oneH                        <subhead1>(A subheader with symbol\SUBHEADSYMBOL)  M                        Test for informal figures - should add figurefile only                         <figure>n2                        <figure_file>(ps\fig.ps\10)5                        <FIGURE_FILE>(BOOK\FIG.fse\10) "                        <endfigure>  O                        Test for symbol adding, reference adding and file adding :                        <figure>(figure caption\BK_ADDED_3)9                        <figure_file>(ln03\ln03fig.six\10)d9                        <FIGURE_FILE>(BOOK\LN03FIG.fse\10) "                        <endfigure>  7                        <CP><REFERENCE>(BK_ADDED_3\FULL)   9                        Test for same, no reference adding (                        <reference>(f1_1)4                        <figure>(figure caption\F1_1)9                        <figure_file>(ln03\ln03fig.six\10)n9                        <FIGURE_FILE>(BOOK\LN03FIG.fse\10)a"                        <endfigure>  I                        Test for same, no reference adding, no file adding_(                        <reference>(f1_2)4                        <figure>(figure caption\F1_2)9                        <figure_file>(ln03\ln03fig.six\10)Y9                        <figure_file>(book\bookfig.fse\10) "                        <endfigure>  ;                        Test for same, reference adding only 4                        <figure>(figure caption\F1_3)9                        <figure_file>(ln03\ln03fig.six\10)w9                        <figure_file>(book\bookfig.fse\10)l"                        <endfigure>  1                        <CP><REFERENCE>(F1_3\FULL)   A                        Test for same, reference adding only again 4                        <figure>(figure caption\F1_4)4                        <FIGURE_SPACE>(42\left blank)"                        <endfigure>  1                        <CP><REFERENCE>(F1_4\FULL)   Q                        __________________________________________________________ ;                        Example 5-2 (continued on next page)                   5-4  <                                    Digital Internal Use Only         Q                                        DOCTORing SDML files for Bookreader output         9                        Example 5-2 (Cont.)  Modified file Q                        __________________________________________________________   A                        Test for same, reference adding only again 4                        <figure>(figure caption\F1_5)!                        <line_art>o#                           something $                        <endline_art>"                        <endfigure>  1                        <CP><REFERENCE>(F1_5\FULL)   9                        Add symbol and reference to table. 6                        <table>(small table\BK_ADDED_4)*                        <table_setup>(2\10)5                        <table_row>( 1 \ the only row)i!                        <endtable>   7                        <CP><REFERENCE>(BK_ADDED_4\FULL)   2                        <head1>(section head1\S1_2)  8                        <head1>(section head1\BK_ADDED_5)  Q                        __________________________________________________________   Q                __________________________________________________________________h  +        5.3     Including predefined symbols   J                        In many cases, a book also uses a set of predefinedK                        symbols, that are made known to DOCUMENT through the J                        DOCUMENT/SYMBOL=symbolfile command qualifier. TheseO                        symbols will also be taken into account by DOCTOR if the_P                        /SYMBOL_FILE qualifier is also used on the DOCTOR command                        line:  K                          DOCTOR/ONLINE/SYMBOL=symbolfilespec inputfile.SDML   O                        This way it is avoided that those predefined symbols are M                        listed as unknown in the list file that is produced if /                        /LIST is also specified.   I                        See also Section 5.4 for additional information on M                        the combination of predefined symbols and additionally &                        generated ones.  Q                __________________________________________________________________s  ,        5.4     Generating additional symbols  K                        Apart from providing all necessary section tags with_L                        symbols where the author did not specify these, it isO                        also possible that a number of <REFERENCE> tags are usedsM                        that refer to undefined sections. Either because therewN                        was a typing error, or because a section was removed orA                        because the section has yet to be written.x  Q                                                                               5-5   <                                    Digital Internal Use Only         9                DOCTORing SDML files for Bookreader output6          J                        When DOCUMENT processes a source file that containsN                        more than 30 undefined references (or any other warningI                        message), it will abort after the 30th message. TosM                        avoid this, you can instruct DOCTOR/ONLINE to generateaL                        an additional file that produces values for all theseN                        undefined symbols: specify the /DUMMY_SYMBOL qualifier.  H                        It then produces a file with <DEFINE_SYMBOL> tagsJ                        where the value of each symbol is simply set to theK                        value <TAG>(reference) tag. When the source document J                        is now processed with DOCUMENT, the final text willM                        print "<REFERENCE>(undefined_symbol)". If this text isaN                        unwanted, you may define your own undefined_symbol textG                        using the /DUMMY_SYMBOL=(TEXT="string") keyword.   M                        The processing of the entire document is now possible, M                        despite the undefined symbol references by the command/                         sequence:  `                           DOCTOR/ONLINE/DUMMY_SYMBOL=(OUTPUT=dummy_symbol_file, TEXT="string") -.                                 inputfile.SDML^                           DOCUMENT/SYMBOL=dummy_symbol_file inputfile.SDML doctype destination  L                        To generate such a symbol file, the qualifier /DUMMY_F                        SYMBOLS is required. When no keyword OUTPUT= isL                        specified, it defaults to input_file_name.SDML_DUMMY_                        SYMBOLS.a  L                        During the collection of defined symbols (in Pass 1),I                        DOCTOR obeys the setting of conditional tags. If a O                        conditionalized block of text does not match the current O                        condition, it is ignored and all symbols defined in that O                        block are also not seen, i.e. remain undefined and hencePM                        will be output to the dummy symbol file. You can set a L                        specific condition through either the <SET_CONDITION>I                        inside the SDML file or through the DOCTOR /ONLINE -                        /CONDITION= qualifier.   P                        When the /SYMBOL qualifier is also specified, the symbolsP                        defined in that symbol file are not copied into the dummyN                        symbol file. If you want to include a <INCLUDE>(symbol_L                        file_spec) into the generated dummy symbol file to beO                        sure you include both, then the keyword /DUMMY=(INCLUDE_gJ                        SYMBOLS) is required. This is useful if you want toK                        process the final document using both the predefinedkK                        symbols and the generated dummy ones. Because only atL                        single /SYMBOLS= qualifier is allowed on the DOCUMENTO                        command line, you can specify the generated dummy symbolhN                        file, which now automatically references the predefined7                        symbols through a <INCLUDE> tag.e                  5-6  <                                    Digital Internal Use Only         Q                                        DOCTORing SDML files for Bookreader output         Q                __________________________________________________________________   *        5.5     Things_to_remember_________          5.5.1   Using /OUTPUT  L                        Using the /OUTPUT= qualifier allows you to let DOCTORL                        create modified output files with a different name orK                        extension than the orginals. This allows you to keepiO                        the original files untouched. One of three approaches isG!                        suggested:s  M                        1  Specify /OUTPUT=disk:[dir] only. This will move all N                           modified output files into a separate directory. YouP                           can attempt to build the online books from there. OnceP                           they are coded the way you want it, you can delete the>                           originals. This is the prefered way.  N                        2  Specify /OUTPUT=.filetype only. This will create theL                           modified files in the same directory, but they allP                           have a different file extension, e.g. .SDML_BOOK. OnceL                           all files are coded to your liking, you can simplyL                           RENAME them into normal SDML files. Processing allO                           files with modified file types may cause problems, astQ                           the <INCLUDE> and <ELEMENT> tags inside the files stillL6                           refer to the original files.  N                        3  Specify /OUTPUT=[]. This will create new versions ofP                           the files in your current directory with the same nameO                           and file extension as the originals. If originals arekO                           also in your default directory then obviously the newi?                           created ones supersede the originals.   P                           If you specify /OUTPUT=.SDML the output will always beN                           in the original directory of the sources and the new?                           versions will supersede the old ones.   7                                                   Note:sG                             When no /OUTPUT is specified, DOCTOR/ONLINE K                             will use the file type .SDML_ONLINE, to prevent K                             unintentional loss of the originals by a purge.   *                ___________________________          5.5.2   Using /VERSION_1   K                        There is a distinct difference in processing between N                        VAX DOCUMENT V1.2B and V2.0 or higher. The V2+ allows aN                        symbol on the <SUBHEAD*>, <PREFACE>, <PREFACE_SECTION>,H                        <COMMAND>, <ROUTINE>, <SDML_TAG>, <STATEMENT> andP                        <SUBCOMMAND> tags, whereas V1.2B does not. If you specifyK                        /VERSION_1, no symbols are added. In fact, if any is O                        encountered, it is removed and placed inside a <COMMENT>   Q                                                                               5-7_  <                                    Digital Internal Use Only N  E    9                DOCTORing SDML files for Bookreader outputn          M                        tag. Therefore, if by accident you processed files forgP                        V2 (the default) any symbols that should not be added forN                        V1.2B can be removed by reprocessing the same file with"                        /VERSION_1.  Q                __________________________________________________________________>          5.6     Adding symbols   P                        Each section tag such as the <HEAD*>(header) tag, withoutK                        a symbol will be given one. This is done by adding a J                        unique symbol BK_ADDED_nnn where nnn is a generatedN                        number. Also files processed before can be re-processedK                        as DOCTOR/ONLINE first looks for the presence of any L                        of those tags, and will generate new ones which startM                        from the highest found number nnn+1. These symbols are_M                        generated for all tags that require one, regardless of L                        whether they are embedded in a conditional text block2                        whose condition is not met.  Q                __________________________________________________________________            5.7     Adding references  P                        While the DOCTOR searches through the files, it registersI                        all symbols found and tries to match them with thedH                        occurence of at least one <REFERENCE> tag. If theG                        document is not ready for Bookreader destination K                        processing, DOCTOR will have found some symbols thatnL                        have no references. If this is the case with either aP                        formal table, example or figure, these elements cannot beP                        "popped up" by clicking on a hotspot, as these only exist3                        when a <REFERENCE> is coded.   N                        To resolve this, DOCTOR will add a <REFERENCE> to theseM                        pop up elements immediately following the <ENDFIGURE>,uO                        <ENDEXAMPLE> or <ENDTABLE>. It will not attempt to embed M                        this reference in a sentence: you may still want to doeL                        this by yourself. The list file that can be generatedM                        contains the instructions of where manual intervention '                        may be required.   Q                __________________________________________________________________u  "        5.8     Adding figure files  P                        Because figures may have been specified for known printerN                        destinations, but not for online books, the DOCTOR willK                        also add a <FIGURE_FILE> within a figure block if no K                        figure for the BOOK destination is found. Obviously, O                        DOCTOR will not generate such a figure. You will need to O                        create it yourself or try to convert the existing figureuO                        into the FSE format required by the Bookreader. RAGS and                   5-8  <                                    Digital Internal Use Only         Q                                        DOCTORing SDML files for Bookreader output_          N                        UTOX are two tools that can assist you in this process.O                        RAGS can make figures for all valid destination types of O                        VAX DOCUMENT, UTOX can convert several figure file types M                        into others. However, if a sixel of PostScript file is P                        all you got of a figure, you will have to re-draw it. Use                        RAGS.  Q                __________________________________________________________________u           5.9     What must you do?  K                        If you specify the /LIST qualifier to DOCTOR/ONLINE,_M                        you will get a list file that contains all the actionsmK                        you still must perform after the documents have been !                        converted.   Q                __________________________________________________________________   1        5.10    Removing or renewing added symbols2  O                        Occassionally it will happen that you want to remove all L                        automatically generated symbols. This may be the caseN                        when an existing piece of text needs to be incorporatedH                        in another document. Or when a book is created ofO                        individual elements which at some point in time were all>M                        processed individually. In both cases chances are thatdP                        the document elements contain identical symbols that were!                        generated.i  O                        DOCTOR allows you two options to correct this situation:   O                        1  DOCTOR/ONLINE/REMOVE removes all symbols generated by O                           any previous processing of a file with DOCTOR/ONLINE.<M                           It removes the symbols during Pass 1 processing and %                           then stops.i  L                        2  DOCTOR/ONLINE/SUPERSEDE also removes all generatedL                           symbols during Pass 1 but continues with Pass 2 toK                           generate new ones, that are consistent throughout O                           the document. In this process files without generated>L                           symbols are created during Pass 1 in the specifiedP                           output directory (/OUTPUT=) and these are then used toN                           scan for adding new symbols during Pass 2. ThereforeO                           you will end up with two new versions of the original<P                           files: the newest with new symbols, the one but newest8                           without any generated symbols.  9                                                     Note: F                                Due to the fact that VAX SCAN is unableD                                to retrieve the specific file versionF                                it creates it was decided not to deleteE                                this intermediate file without symbols L                                automatically as DOCTOR can never be deadsure  Q                                                                               5-9   :                                  Digital Internal Use Only t       9                DOCTORing SDML files for Bookreader outputf          L                                it deletes the right version always. And we'd9                                rather be safe than sorry.o                                                                                                              5-10   <                                    Digital Internal Use Only                     Q                __________________________________________________________________   )        6       DOCTORing PostScript files       Q                __________________________________________________________________2          6.1     Overview   I                        PostScript files are produced by a wide variety of L                        products, such as VAX DOCUMENT, DECwrite, DECpaint orJ                        MS-Word. With the arrival of laser printers lots ofM                        documentation is produced in the PostScript format and_@                        printed. Several problems can then occur:  O                        o  A file print is halfway ready when the system crashes M                           or the job gets aborted for all the right and wrong "                           reasons.  O                        o  Only a section of a document is interesting to print.m  P                        o  Some products, like VAX DOCUMENT, do not produce blankO                           pages when a section ends on an odd page. This causesaL                           double sided printers to skip a page and print theP                           following section on the wrong side of the page (recto?                           pages on verso pages and vice versa).   Q                        o  The same file is needed, but one would like a different P                           standard page layout (e.g. with DRAFT written over theP                           page) as defined in the prolog of the PostScript file.  Q                        o  The PostScript file contains figures that were inserted Q                           as encapsulated PostScript and you would like to remove Q                           those from the file or to create them as separate filesd2                           to re-use those figures.  L                        o  A PostScript document should be re-ordered in pageM                           output to allow for saddle stiching of double sided M                           printed sheets (4 pages/sheet, like a magazine with 6                           pages folded in the middle).  J                        The DOCTOR utility allows to do all this in an easyH                        manner, provided the PostScript file that must beM                        inspected adheres to Adobe's minimal conformant coding M                        style, as described in Section 6.7. This is assumed to P                        be true if the first line of the PostScript file containsI                        %!PS-Adobe, possible followed by a version number.   Q                                                                               6-1   =                                     Digital Internal Use Only          )                DOCTORing PostScript files           L                        DOCTOR also adheres to the coding standard itself. ItK                        prefixes the file output with the following standardYG                        banner, that follows the %!PS-Adobe header line:l                  %!PS-Adobe-2.0 E                %%Creator:   VAX DOCUMENT V2.0 modified by DOCTOR V3.0                 %%c6                %%CreationDate: 20-JUL-1992 13:21:58.92                %%FB                %% Command issued: DOCTOR/PS DOCTOR.PS/OUT=[]/BLANKH                %% File used:      PSQ:[PUBLIC.SOURCES.DOCTOR]DOCTOR.PS;4D                %% QAR's to:       Theo de Klerk @UTO,  NSIC00::KLERK                %%o7                %%     *** Digital Internal Use Only ***                 %%i  M                        Because this header preceeds any header that is copiedcO                        from the original input file, the above entries overruleiI                        identical header entries. The original header line N                        indicating its creator has been kept, but appended withP                        the DOCTOR version. This is to allow other tools to stillK                        retrieve from this line the origin of the PostScripts                        code.  9                                                Important: C                             It is advised always to use the /OUTPUTo@                             qualifier to specify the output fileF                             specification. If omitted, the DOCTOR willK                             make the next higher version of the input file.nF                             This is potentially dangerous as one mightK                             accidentially delete this original file through $                             purging.  Q                __________________________________________________________________r  !        6.2     Adding blank pages   J                        Using the /BLANK qualifier will allow you to insertO                        additional pages into the PostScript file to balance the M                        number of odd/even pages. This is especially importantiN                        for VAX DOCUMENT files that, by default, do not includeH                        any blank pages if a chapter ends on an odd page.  I                        This will make sure that the output document, when J                        printed on a double sided printing device will haveG                        all recto and verso pages printed in the correcttI                        orientation. This is also important on single sidesO                        printing devices, where the final output will be stackedMK                        into a double sided printing photocopier machine fornM                        further duplication. The inserted blank page is indeediP                        blank: no page numbers or anything is output to the page,O                        as DOCTOR does not know how the page layout is composed.                   6-2  :                                  Digital Internal Use Only g  M    Q                                                        DOCTORing PostScript files_          C                                       Restriction for update pages:_I                             DOCTOR/BLANK inspects the %%Page: comments inTG                             the PostScript file and determines from theiJ                             last numeric part of the folio number (such asI                             "Glossary-10") whether or not a page needs toiG                             be inserted. It can only make this decisionsE                             properly for normally formatted books. If.I                             the book is built using update pages, the endaJ                             result may be incorrect, as DOCTOR cannot makeI                             the right decision on page jumps like 4-3, 4-eK                             3.1 or 4-3.1, 4-4. The last digits are all odd,iG                             assuming that a blank even page needs to betJ                             inserted. Depending on your own feelings, this6                             may or may not be desired.  L                        If you plan to print the PostScript file in a reducedO                        format (with two pages on one side of a sheet of paper), H                        you should also use the /LEADING_BLANK qualifier.M                        This inserts a blank page before the first page of the O                        document output, to ensure that the positioning of recto J                        and verso pages is not changed: the first page of aO                        document is a right hand side page, but would occupy the M                        left half of the page when /LEADING_BLANK had not beene                        used.  O                        When the /LOG qualifier is also enabled, the DOCTOR williE                        tell you when a page is inserted. For example:i  \                        $ DOCTOR/PS DOW.PS/BLANK/EXTRACT=(START=7-1,NUMBER=4)/OUT=TEMP.PS/LOGC                        %DOCTOR-I-IDENT, This is DOCTOR version V3.0tS                        %DOCTOR-I-CONFORM, File assumed to conform to %!PS-Adobe-3.0 =                        %DOCTOR-I-INSERTED, Page 7-2  inserted =                        %DOCTOR-I-INSERTED, Page 8-2  inserted =                        %DOCTOR-I-INSERTED, Page A-2  insertedr=                        %DOCTOR-I-INSERTED, Page B-2  insertedrG                        %DOCTOR-S-CREATED, Created PSQ:[DOCTOR]TEMP.PS;1   M                        where the chapters 7 and 8 only had a single page (7-1eC                        and 8-1), as had the two appendices A and B.   P                        Each inserted blank page only results in the insertion ofO                        the following PostScript code for VAX DOCUMENT generatedD/                        files (Adobe V3 output):<            Q                                                                               6-3   <                                    Digital Internal Use Only u  r    )                DOCTORing PostScript files                                   %% R                        %%Page: (7-2) 2   (the added folio page and ordinal number)1                        %%     INSERTED BLANK PAGE +                        %%PageFonts: (atend)u3                        %%PageProcessColors: (atend)i2                        %%PageCustomColors: (atend)7                        PaperHeight PaperWidth PM 0 0 XYe                        EP PP$                        %%PageTrailer2                        %%PageFonts: Helvetica-Bold+                        %%PageProcessColors:_2                        %%PageCustomColors: (BLACK)                        %  N                        The same file, made with Adobe V2 standards by DOCUMENT1                        V2.0 or before, results in   P                        %%Page: 7-2 2   (the added folio page and ordinal number)1                        %%     INSERTED BLANK PAGEe'                        %%BeginPageSetupp%                        %%EndPageSetupT+                        %%PageFonts: (atend) 2                        %%PageCustomColors: (atend)?                        1000 BP PaperHeight PaperWidth PM 0 0 XYs2                        %%BeginCustomColor: 0_BLACK*                        %%EndCustomColor: 0                        6 PP EP$                        %%PageTrailer2                        %%PageFonts: Helvetica-Bold2                        %%PageCustomColors: 0_BLACK                        %  N                        whereas any other PostScript file produced by a product=                        other than VAX DOCUMENT will result ins  $                        %%Page: 7-2 21                        %%     INSERTED BLANK PAGE                         showpageo                        %  7                                                   Note:fF                             The Adobe comment standard also allows forK                             pages to be marked as %%Page: text 5 where textIJ                             can be any string with no white space. It needK                             not have a numeric part therefore. In this case K                             obviously DOCTOR is not able to determine whereFJ                             a new blank page is needed or not, since thereF                             is no page number information available to@                             determine whether a page is skipped.                  6-4  <                                    Digital Internal Use Only n  s    Q                                                        DOCTORing PostScript filesi          1                        User specified blank pages   I                        The /BLANK qualifier allows the specification of auJ                        separate file specification, that can contain user-P                        specified instructions to create an additional page. ThisP                        would overrule the default blank page output as specified/                        in the previous section.   L                        The user specified file must contain all the relevantJ                        PostScript instructions to create the blank page toM                        be inserted. This could include instructions to typseteO                        This page has been left blank intentionally or somethingfL                        similar. The instructions should contain the showpageL                        command to output the page during printing. It shouldN                        not contain a page header in the form of %%Page: as theM                        internal page folio numbering and ordinal numbering isw6                        performed by the DOCTOR itself.  M                        When a part of a document is extracted, the /BLANK may M                        result in an extra blank page preceeding the extracted N                        section (if it starts on an even page) or one following>                        the section if it ended on an odd page.  P                        The only time this may cause two blank pages is where twoM                        consecutive extracted ranges both have a page appended I                        and preceeded respectively. This ensures different_G                        sections are always on different physical pages.c  N                        Note that the /LEADING_BLANK page will not use the userK                        specified file for blank pages, as this leading page_K                        is not considered part of the document, but rather ar7                        placeholder before the document.n  Q                __________________________________________________________________y  #        6.3     Replacing the prologe  O                        The prolog of each PostScript file is supposed to follow P                        the initial header section and either starts at the firstP                        line that does not start with %! or %% or after the firstK                        line that contains %%EndComments. It continues until O                        there is an explicit %%EndProlog line. This line must be ?                        present, even if no prolog is specified.s  I                        The prolog contains definitions and a general pageTL                        layout applicable to all pages. Hence, you can add orK                        replace certain features to give the printed pages a M                        different look, without modifying any of the text that N                        is part of the document itself. You can create your ownL                        prolog, either based on the original one, or entirelyM                        homewritten, to replace the prolog that comes with thee  Q                                                                               6-5   <                                    Digital Internal Use Only s       )                DOCTORing PostScript filesp          N                        input file. This way you can produce effects as writingL                        "DRAFT" diagonally across all pages, or print a faintG                        logo on each page or border the text in a frame.i  G                        The user specified prolog file must end with the -                        %%EndProlog statement.   P                        To allow some simple modification, the qualifier /CHANGE_O                        PROLOG has been implemented. You can specify three itemst$                        on each page:  P                        o  A bold printed text at the top of each page (a header)  K                        o  A bold printed text at the bottom of each page (aaM                           footer), with or without an additional (page)number                            added   Q                        o  A faintly grey printed text diagonally across the page. =                           The grey scale can be set manually.f  P                        These three text items do not interfere with the originalK                        text in the PostScript file. You could imagine it as M                        printing this file on pre-printed paper that had those O                        three items on it already. The text on the diagonal line N                        is dynamically adjusted in size so that the entire textM                        fits on a single line running from the bottom lefthand :                        corner to the top righthand corner.  L                        The /CHANGE_PROLOG comes with twelve keywords, all ofN                        which are optional, but at least one must be specified:  4                        /CHANGE_PROLOG=(TOP="text", -H                                        BOTTOM="text", COUNTER=integer, -9                                        DIAGONAL="text", -t0                                        BORDER, -W                                        FONT=font_type, SIZE=number, GRAYSCALE=number, -e:                                        OUTPUT=file_spec, -I                                        HSIZE=pointsize, VSIZE=pointsize - :                                        PAGESIZE=papertype)  O                        The first four arguments specify the text to be used forAM                        the header, footer or diagonal line. If a space occursnL                        in this text, the entire text must be enclosed withinL                        quotation marks. The specified texts are used for the<                        prolog in the output PostScript file.  L                        The COUNTER argument allows you to specify an integerO                        value that will be printed on the bottom line, followingaL                        the specified BOTTOM text. The counter will incrementO                        with each page. It allows you to number pages that would O                        otherwise be unnumbered and you can specify the starting <                        value of the page numbering sequence.                  6-6  <                                    Digital Internal Use Only         Q                                                        DOCTORing PostScript filesn          H                        The GRAYSCALE allows to specify how dark the greyP                        diagonal text must be. It defaults to 95%, which is lightP                        grey. A value of 00 would make it ink-black and 99 almostO                        invisibly white. The diagonal text will auto-size to fit M                        the entire length of the diagonal. By default the text K                        is printed in Helvetica-Bold, and the top and bottom M                        lines are sized to 15 points. However, you may specify M                        a different font using the FONT= keyword and the SIZE= O                        keyword. Although any size (in point units) is accepted, O                        values above 20 points seem (no pun intended) pointless. O                        The fonts that can be specified are listed in Table 6-1.   Q                        Table_6-1__FONT_keyword_values____________________________t  N                            Note that all PostScript font specification hyphensL                              are replaced by underscores for the DCL keyword  &                        -   Times_Roman  %                        -   Times_Boldr  +                        -   Times_BoldItalic   '                        -   Times_Italico  1                        -   NewCenturySchlbk_Roman   0                        -   NewCenturySchlbk_Bold  6                        -   NewCenturySchlbk_BoldItalic  2                        -   NewCenturySchlbk_Italic  $                        -   Helvetica  )                        -   Helvetica_Bold   0                        -   Helvetica_BoldOblique  ,                        -   Helvetica_Oblique  "                        -   Courier  '                        -   Courier_Boldi  .                        -   Courier_BoldOblique  *                        -   Courier_Oblique  *                        -   AvantGarde_Book  *                        -   AvantGarde_Demi  1                        -   AvantGarde_DemiObliquei  1                        -   AvantGarde_BookOblique   ,                        -   LubalinGraph_Book  ,                        -   LubalinGraph_Demi  Q                                                                               6-7t  <                                    Digital Internal Use Only    l    )                DOCTORing PostScript files           Q                        Table_6-1_(Cont.)__FONT_keyword_values____________________e  3                        -   LubalinGraph_DemiOblique   3                        -   LubalinGraph_BookObliquet  )                        -   Souvenir_Lighte  (                        -   Souvenir_Demi  .                        -   Souvenir_DemiItalic  Q                        -___Souvenir_LightItalic__________________________________n  M                        A border may be printed around the page specifying theuP                        BORDER keyword. By default, no such rectangular border isP                        drawn (Note that PostScript printers can produce the sameM                        if with printing the command PRINT /PARA=(NUMBER=1) ist"                        specified).  L                        The OUTPUT keyword allows the specification of a fileN                        specification. In that case, in addition to using thoseK                        header, footer and diagonal line texts in the outputdI                        PostScript file, a separate prolog file is createdhO                        containing those same definitions for header, footer andeP                        diagonal. This created prolog file can later be used withP                        the /PROLOG qualifier to replace the standard prolog with.                        this newly created one.  J                        The two keywords HSIZE and VSIZE are only needed ifK                        the prolog must be made to fit a specific page size. M                        By default A4 size is used. Any other dimension can be 0                        specified in point units.  K                        Alternatively, you can use the keyword PAGESIZE that P                        will recognizethe following standard paper sizes: LETTER,P                        LEDGE R, LEGAL, EXECUTIVE, 7X9, 35MM, A5, A4, A3, B5, B4,P                        C6, C5, C4. The keyword PAGESIZE is mutually exclusive to,                        both HSIZE and VSIZE.  Q                __________________________________________________________________s           6.4     Extracting ranges  L                        Using the /EXTRACT  qualifier you can specify to copyI                        only a range of pages from the input file into the J                        output file. The first page to copy is indicated byL                        the START=folio keyword, the last page either throughK                        END=folio keyword or the NUMBER=integer keyword. The I                        specified folio numbers must exist in the file, as C                        otherwise DOCTOR cannot synchronize on them.                   6-8  <                                    Digital Internal Use Only n       Q                                                        DOCTORing PostScript filesn          P                        Specifying an invalid start page means the entire sectionK                        is skipped, specifying an invalid end page means theiL                        remainder of the document is included while DOCTOR isN                        looking for the end page to match the invalid specifiedO                        folio number. When both the END and NUMBER are specifiedwN                        and they indicate a different range, the first match isN                        used, resulting in the shortest range between the first>                        and last page of the extracted section.  K                        You can specify several /EXTRACT qualifiers to allow K                        for several ranges to be included in the same output L                        file. The ranges should not overlap. In its search toM                        end one range, the DOCTOR will read past the beginning O                        of the next section and thereby will never encounter the J                        starting page again of the section that overlapped.  M                        The /LOG qualifier will indicate when a range is found G                        and whether in the end some ranges were skipped.]  L                        The valid entries for START= and END= can be found by                        doing a  5                          $ SEARCH filespec.PS %%Page:   J                        command at DCL level. This will reveal all the pageP                        header lines of the available pages within the PostScriptI                        document. For Adobe V3 comment standards, the page J                        numbers are enclosed within parentheses. You do notP                        specify these parentheses in the START= and END= keywords1                        of the /EXTRACT qualifier.   9                                                Important:hH                             Many documents consist of text and graphics,B                             made by different products and somehowE                             combined into the final document. As each J                             product produces its own %%Page: entries, someH                             entries may seem out of order from the usualF                             incremental numbering of the page sequenceK                             number (ordinal). When this is the case, DOCTORLI                             ignores those page comments and assumes it iseJ                             some sort of included graphic and not really aJ                             page. Therefore you cannot select one of thoseD                             page numbers to select a range boundary.  7                                                   Note: F                             The Adobe comment standard also allows forK                             pages to be marked as %%Page: text 5 where text0I                             does not contain a numeric part. In this casemJ                             obviously DOCTOR is not able to determine whatA                             page ranges are available to extract.   Q                                                                               6-9A  <                                    Digital Internal Use Only o  r    )                DOCTORing PostScript files         Q                __________________________________________________________________2  +        6.5     Removing or re-using figuresK  L                        A PostScript file contains text and possibly figures.L                        Those figures are very often made separately (using aO                        drawing package) and then inserted into the text body by O                        the text formatting tool such as VAX DOCUMENT's <FIGURE_nH                        FILE> tag or DECwrite's "LINK TO PICTURE" option.  I                        Occassionally there is a need to either remove theTO                        figures from the PostScript file (to allow the remainderiK                        to be converted back to plain ASCII text file) or ton?                        re-use those figures in other documents.t  K                        The extracting or removal of figures is based on the M                        assumption that the input PostScript file contains the                         lines  8                        %%BeginDocument:  figure_filespecJ                         ... code of the encapsulated PostScript figure ...$                        %%EndDocument  N                        to mark the begin and end of each included encapsulated                        figure.  M                        In Table 6-2 all possible combinations are summarized.   Q                        Table_6-2__Extracting_or_removing_figures_________________   Q                        Qualifier___________________Result________________________   J                        /FIGURE                     Default. Leaves figures<                                                    untouched  P                        /FIGURE=EXTRACT             Extract figures into separateQ                                                    files by their original names. O                                                    Figures also remain in input ;                                                    documents  P                        /FIGURE=(EXTRACT,PAGE_      Extract figures into separateN                        NUMBER)                     files. These files have theN                                                    same name as the input fileN                                                    spec, but appended to it isO                                                    the page number on which the C                                                    figure occurred.e  Q                        /NOFIGURE                   Removes figures from the inputu8                                                    file.  K                        /NOFIGURE=EXTRACT           Removes figures from the N                                                    input file. Extract figuresO                                                    into separate files by their B                                                    original names.                  6-10o  <                                    Digital Internal Use Only    a    Q                                                        DOCTORing PostScript files_          Q                        Table_6-2_(Cont.)__Extracting_or_removing_figures_________   Q                        Qualifier___________________Result________________________e  Q                        /NOFIGURE=(EXTRACT,PAGE_    Removes figures from the inputhM                        NUMBER)                     file. Extract figures into N                                                    separate files. These filesL                                                    have the same name as theP                                                    input file spec, but appendedN                                                    to it is the page number onQ                        ____________________________which_the_figure_occurred.____o  *                ___________________________          6.5.1   Removing figuresi  O                        For some time now several tools are available to convertuM                        a PostScript file back into its plain ASCII text file.aH                        This can come handy if the sources to produce theM                        PostScript file are lost or part of the document could /                        be used in another file.   N                        Within Digital there is a PS2TEXT utility to enable youL                        to do this on several PostScript files, amongst whichI                        VAX DOCUMENT. However, if such a document containscM                        figures made by some graphics package, these should beoN                        removed from the PostScript file before a conversion isN                        attempted. Again DOCTOR comes to the rescue by allowingM                        the /NOFIGURES qualifier that will remove all <FIGURE_ .                        FILE> included figures.  K                        When the /LOG qualifier is specified, it outputs the J                        names of the figure files that are removed from the#                        output file.d  *                ___________________________  !        6.5.2   Extracting figurest  L                        When you want to extract figures from a document intoL                        individual figure files, you can also use the /FIGUREL                        qualifier. In this case, you need to add a keyword toK                        it: EXTRACT. This will result in DOCTOR scanning the J                        PostScript source file and to extract each includedP                        figure to become a separate .EPS file. This file can thenC                        be used in other documents or presentations.       Q                                                                              6-11   <                                    Digital Internal Use Only         )                DOCTORing PostScript filesd          H                        There are two ways to specify a file name for the)                        extracted figures:o  I                        o  They get their original name back. This name isOO                           specified in the PostScript input file on the comment=/                           lines that start with   8                                %%BeginDocument: filespec  K                           The extracted figure files will be created in the Q                           current default directory, or the one that is indicated Q                           by the /OUTPUT qualifier. This manner may be useful for N                           the original author of the document who has lost the0                           original figure files.  B                           This behaviour is obtained by specifying+                           /FIGURES=EXTRACT.t  P                        o  They all get the name of the original input PostScriptN                           file, but appended to it is the page number on whichN                           the figure occurs. This makes it easy for those thatM                           want to use the original document as a reference tob6                           where the figure is printed.  B                           This behaviour is obtained by specifying7                           /PAGES=(EXTRACT,PAGE_NUMBER).   O                        If /LOG is also specified, the created figure file names !                        are shown.a  I                        When the /EXTRACT qualifier is also used, only the N                        figures in the selected page ranges are extracted. WhenN                        the /NOFIGURE qualifier is used in combination with theK                        keywords EXTRACT and/or PAGE_NUMBER, the figures areaM                        extracted into their individual files, and at the sameg<                        time removed from the input document.  Q                __________________________________________________________________   $        6.6     Saddle stich printing  O                        When one wants to use a printer that allows for printing,P                        on both sides of a sheet of paper, it may be advantageousL                        to print the pages on half format (allowing two pagesM                        on a single sheet side) and then fold the pages in the N                        middle to make a signature (like a magazine), ready for'                        saddle stiching.   P                        When the book is very thick, one may decide to divide theP                        book into several of these signatures and then stich them                         together.                  6-12a  <                                    Digital Internal Use Only r  f    Q                                                        DOCTORing PostScript files-          P                        In both cases this requires the output order of the pagesM                        in the PostScript file to be modified. Rather than the N                        usual sequential order of page 1, 2, 3 etc, we now needK                        the first and the last page to be printed after each M                        other (and on the same sheet side if printing is setup M                        for two pages/sheet). And then page 2 and the one-but-->                        last page on the backside of the sheet.  M                        As a small example: suppose 8 pages A4 must be printedOM                        in reduced format and folded as a brochure of size A5.-J                        This results in 2 sheets of paper as illustrated in"                        Figure 6-1.  1                Figure 6-1 Saddle stiched printingbQ                __________________________________________________________________   i                  +--------+--------+    +--------+--------+    +--------+--------+    +--------+--------+ i                  |        |        |    |        |        |    |        |        |    |        |        | i                  |        |        |    |        |        |    |        |        |    |        |        | i                  |        |        |    |        |        |    |        |        |    |        |        | i                  |        |        |    |        |        |    |        |        |    |        |        | i                  |        |        |    |        |        |    |        |        |    |        |        |_i                  |8       |       1|    |2       |       7|    |6       |       3|    |4       |       5| i                  +--------+--------+    +--------+--------+    +--------+--------+    +--------+--------+t  g                ___front_sheet_1____________back_sheet_1___________front_sheet_2__          back sheet 2E  O                        To rearrange the order of the pages in a PostScript fileeA                        the command DOCTOR/PS/SADDLE must be used.e  7                                                   Note: K                             It is important to note that the two qualifiers H                             /PS/SADDLE must be specified together and in'                             that order.d  C                             The /SADDLE qualifier cannot be used iniH                             combination with any of the other PostScriptK                             manipulation qualifiers (like /EXTRACT, /CHANGEt"                             etc.).  F                             Finally, /SADDLE only works for printing 4I                             pages on a sheet (two on each side). There is G                             no support for 4 or more pages printed on a <                             single side of a sheet of paper.  F                        You must indicate how many pages will compose aM                        signature. Obviously this must always be a multiple of L                        4. It doesn't matter if your PostScript document pageN                        number is not an exact multiple of this signature size:O                        DOCTOR will append the necessary final pages to complete_  Q                                                                              6-13s  <                                    Digital Internal Use Only e  y    )                DOCTORing PostScript filesf          M                        the final signature. If the document only has 7 pages,tO                        DOCTOR will create a blank 8th page to team up with pagep+                        1 on the same sheet.DJ                        The number of pages to gather for each signature isJ                        specified with /GATHER=. If you do not specify thisK                        qualifier, the entire book is considered to become a L                        single signature. This will be convenient for typicalJ                        books of less than 32 pages (8 sheets). If the bookM                        is thicker, you should specify a gather value yourselfsM                        to allow for saddle stiching the individual signatures N                        later. Alternatively, if /GATHER is not specified for aM                        thick book, the entire book will be a single signatureiM                        that can be used if the pages are cut in the middle tofP                        produce two stacks of the half-sized sheets that are thenL                        glued together in a perfect bind (or by thermoglue or'                        spiral binding).e  G                        Additional qualifiers that can be specified are:l  K                        o  /LOG for additional information during processing   N                        o  /OUTPUT= to specify an output file specification. ByN                           default the next higher version of the input file isL                           created (and a warning is issued that purging will/                           delete the original).   J                        o  /2UP. This will cause DOCTOR to process the fileN                           produced with /SADDLE once more and modify some pageJ                           output PostScript code to allow you to print theO                           resulting file on A3 sheets with two A4 pages printeddN                           on a side (rather than reducing each page to fit twoM                           pages on an A4 sheet). Because the code inserted is P                           very specific PostScript for VAX DOCUMENT V2.1 output,N                           this qualifier is ignored if specified for any otherN                           PostScript document and a warning message is issued.  P                        Although it is possible, it usually adds to the confusionN                        and frustration to try and reorganize a PostScript fileN                        that was reorganized before. It also shows common senseP                        to first manipulate the PostScript file in all other waysM                        (like adding blank pages, modifying prolog etc) before N                        trying to re-order the pages. The re-ordering should beP                        the last thing you do on a PostScript file before sending'                        it to a printer.   7                                                   Note:eA                             Because several products that produceeF                             PostScript code redefine the definition ofI                             the showpage command, which is used by DOCTOR K                             to insert additional blank pages, the resultingt                  6-14   :                                  Digital Internal Use Only         Q                                                        DOCTORing PostScript filesa          J                             output file may print as a set of blank pages.E                             Currently the following PostScript outputuG                             has shown to print correctly (or DOCTOR haseD                             special features built in to produce theI                             desired result): VAX DOCUMENT V1.2 or higher, J                             DECwrite V2.0 and higher, DECpresent V1.0, AllK                             MS-Windows V3 PostScript files produced through_F                             the MS-Windows "Windows PSCRIPT" converter:                             (e.g. MS-Powerpoint, MS-Word).  *                ___________________________  /        6.6.1   Using an LPS40 to print the file   O                        The LPS40 is only capable of single sided printing. ThisoO                        means that you will get two pages on a sheet and a blankIM                        back side. Those pages can serve as master copy before.N                        using them in copying machines for further duplication.  -                        The command to give ist  _                          PRINT/QUEUE=lps40_queue file.PS /PARAMETER=(DATA=POSTSCRIPT, NUMBER=2)e  F                        By default all pages are bordered. If you don'tE                        want this, you need to make sure that the filedG                        LPS$NOBORDERNUP.LUP exists in a system directoryeL                        that is pointed to by logical name LPS$LAYUP. In thisK                        directory the Printserver software will look for anytN                        layup information to position the output on the printed                        pages.e  M                        The contents of the file LPS$LAYUP:LPS$NOBORDERNUP.LUP :                        should contain the following lines:  ,                        ! LPS$NOBORDERNUP.LUPW                        ! specifies a variation for n-up printing.  A larger left margin_`                        ! is specified to allow for hole punching.  This file is for single sidedL                        ! printing. It does not draw borders around the pages  !                        no bordersE/                        margins = 19, 19, 60, 19   F                        It is then activated through the print command:  9                         PRINT/QUEUE=LPS40_queue file.PS -F[                               /PARAMETER=(DATA=POSTSCRIPT, NUMBER=2, LAYUP=LPS$NOBORDERNUP)       Q                                                                              6-15   <                                    Digital Internal Use Only t       )                DOCTORing PostScript files         *                ___________________________  /        6.6.2   Using an LPS20 to print the fileo  O                        If single side printing is required, the same operations N                        are applicable as for the LPS40 printing as outlined in,                        the previous section.  H                        If double sided printing is required to produce aN                        ready to use booklet or double sided master for furtherG                        reproduction, the following command is required:t  2                 PRINT/QUEUE=LPS20_queue  file.PS -F                    /PARAMETER=(DATA=POSTSCRIPT, NUMBER=2, SIDE=TUMBLE)  O                        The TUMBLE keyword ensures that all pages are printed in N                        the right orientation and not upside down, which is theP                        default for double sided printing (to allow easy flipping9                        through, but that's unwanted now).g  L                        When no borders are wanted around the pages, the sameJ                        LAYUP keyword can be specified as described for the                        LPS40.u  Q                __________________________________________________________________   '        6.7     Minimal conformant files   M                        Adobe Inc. defined a "Document Structuring Conventions N                        Specification" for PostScript files that utilities suchO                        as VAX DOCUMENT and DECwrite should adhere to. Only then M                        other utilities such as DOCTOR can inspect those files_N                        and manipulate them. DOCTOR's output is also conformantP                        to these styles, so one could use DOCTOR on its own files#                        recursively.   L                        A complete description of the conformant rules can beL                        found in the PostScript Reference Manual, 2nd editionO                        written by Adobe Inc. and published by Addison & Wesley.   <                                             Electronic copy:I                             An electronic copy of this part of the manual D                             can be obtained via the mail file serverE                             of Adobe System Inc. This is a three step F                             approach, where in each case a simple MAILD                             message is sent (no headers etc - just aC                             plain message the way VAXmail works) totJ                             DECWRL::"adobe!ps-file-server" with no subject%                             title[1].   H                             0  Initially you may send a simple mail withJ                                only the word "help". In response, the mail  !                __________________t  A             [1] Thanks to Kevin Manderson to point this out to me_                  6-16   :                                  Digital Internal Use Only    t    Q                                                        DOCTORing PostScript filess          L                                server will send you instructions on what are4                                valid requests to it.  E                             1  The first request consists of only theSH                                word "index". This results in an index ofJ                                categories of documents that are available.  K                             2  The second request is asking for the list of J                                files available within such a category. ForH                                example: "index Documents". This producesJ                                a list of files available from the category2                                (folder) Documents.  L                             3  The final request, based on the previous listI                                of information, is asking for the files toSJ                                be sent over. Sometimes a single file is soH                                large, that mail gateways will refuse it.K                                So you can ask it in parts, and will need to J                                edit them together afterwards (removing allL                                heading and trailing information added by theK                                mail gateways). Each part must be a separateaK                                mail request (otherwise the combined request I                                still exceeds the maximum byte size of the 2                                allowed mail size).G                                The request is made by sending the words K                                send category filename. For example, for the 7                                structuring conventions:   :                                    send Documents DSC.ps.A  I                                and send additional messages for the parts.H                                .B, .C, .D, .E and .F (as was the case in/                                September 1992).E  M                        It is also known informally as the Red Book because of N                        its cover colour. Appendix C of that book describes theM                        style. There are two important aspects to conformancy:   E                        1  The comment blocks have a particular formatI  O                        2  The prolog contains all definitions, font setups etc,RN                           so that each page description depends only on itself<                           and the definitions in the prolog.  N                        Currently there are two versions of structured commentsN                        defined by Adobe, known as PS-Adobe-V2 and PS-Adobe-V3.K                        Although both have much in common, there are certainrK                        incompatibilities. DOCTOR attempts to interpret bothb!                        correctly.   Q                                                                              6-17   <                                    Digital Internal Use Only         )                DOCTORing PostScript files,          O                        In a conformant file, the descriptions of the individualkM                        pages are self-contained. They do not depend on what'ssN                        written on other pages. For this reason, any definitionI                        of customized PostScript commands are not embeddedrL                        inside the description of a single page, but they areM                        all collected at the front of the document, the prologtP                        part. Hence VAX DOCUMENT PostScript files allows printingP                        of some pages, as long as the extracted file contains theO                        prolog, the selected page descriptions, and the trailer.lL                        The prolog can also be enhanced (add certain featuresI                        applicable to all pages), as long as no definitions2                        already present is removed.  K                        For DOCTOR, the only important aspects are that eachAK                        PostScript file contains at least the parts shown in K                        Example 6-1. It needs to be able to find the end and I                        start of the header, prolog, main body and trailer M                        section of the document. Within the main body, it must P                        find all the page headers in case an extract is required.M                        Each conformant file needs to start with %!PS-Adobe on L                        the first line of the file. DOCTOR will check on thisN                        and aborts if it did not find that line. If the line isP                        found, it assumes the remainder of the file also conforms/                        to the coding standards.   *                        You can always do a  8                        $ SEARCH  PostScript_file %%Page:  J                        to see what page folio numbers are available withinJ                        the PostScript file if you want to use the /EXTRACTO                        qualifier option. When these page numbers are surrounded P                        by parentheses (as done with Adobe V3 comment standards),<                        you do not specify these parentheses.  P                        It is important to realize that many PostScript documentsM                        consist of contributions made by different packages: aeM                        type setting system such as VAX DOCUMENT and graphicalLP                        packages such as MacDraw or RAGS or single page documentsN                        from DECwrite or DECpresent. Each of these create theirN                        own PostScript files that are somehow combined into theO                        final complete document file. A scan for all the %%Page: K                        entries will then quickly reveal deviations from thetP                        ordinary page numbering. An example list of this from oneP                        of the VAX DOCUMENT documentation files on using graphics$                        reveals this:                      6-18   <                                    Digital Internal Use Only         Q                                                        DOCTORing PostScript filess        B                        Example 6-1  Conformant PostScript skeletonQ                        __________________________________________________________s  !                        %!PS-Adobe                         %%f,                        %%CreationDate:  date                        %%x6                        %%  ...other header comments...                        %% M                        %%EndComments   (or a line not starting with %% or %!)                           %% 0                        %%  ...prolog commands...                        %%e"                        %%EndProlog  /                        %%Page: folionr  ordinalt  1                           ...main body of text...t  /                        %%Page: folionr  ordinal   1                           ...etc for all pages...   2                        %%BeginDocument: (filespec)O                           ...encapsulated PostScript code of included figure...t$                        %%EndDocument                           %%Trailer  Q                        __________________________________________________________T  (                        %%Page: (2-12) 33(                        %%Page: (2-13) 34(                        %%Page: (2-14) 35H                        %%Page: 1 1                  <--  included figure(                        %%Page: (2-15) 36H                        %%Page: "Only" 1             <--  included figure(                        %%Page: (2-16) 37(                        %%Page: (2-17) 38(                        %%Page: (2-18) 39  K                        The DOCTOR recognizes this as a sudden disruption of H                        the incremental change of the ordinal page numberM                        that indicates the number of the page sheet within the N                        document. If such a distruption occurs, DOCTOR does notL                        consider the disrupting %%Page: entry a real page and5                        treats it as an ordinary line.     Q                                                                              6-19e  <                                    Digital Internal Use Only                     Q                __________________________________________________________________i  E        7       DOCTORing SDML files: hierarchy of files within a books      Q                __________________________________________________________________e          7.1     Overview   M                        A complex document written for VAX DOCUMENT processingtH                        can consist of many elements. The text may all beP                        written in a single source file, or distributed over manyO                        others, that are all <INCLUDE>d into the final printableeL                        document. Besides text, other tools and utilities canP                        have provided additional graphical or tabular data. OftenM                        a complex document is built using a profile file whereAO                        this profile specifies the names of the other SDML filesa>                        that are part of the complete document.  O                        When several people work on such a compound document, it M                        is easy to loose track of the number of files that are G                        referenced from the main, the root, source file.   J                        Here, the DOCTOR/SDML utility, also known as MARFINN                        (MARkup Files INcluded), can assist you in the process.I                        Given any top level root file that is coded in VAX C                        DOCUMENT, it will produce one or several of:   K                        o  An organizational hierachy of how the document iseP                           composed of individual elements (that in turn may also;                           be composed of smaller elements).a  G                        o  A DEC/MMS description file that lists all the Q                           dependencies between the individual components in order O                           to rebuild the final printable document in any of the O                           supported destinations: LN03, PostScript, Bookreader,u/                           Line_printer or Mail.   K                        o  A list of all occurrences of the <X> and <Y> tags N                           that are written in those VAX DOCUMENT source files,M                           annotated with the exact line number of the file in 0                           which they were found.  F                        The following sections show you how to use that#                        information.W      Q                                                                               7-1o  <                                    Digital Internal Use Only    i    E                DOCTORing SDML files: hierarchy of files within a bookc        Q                __________________________________________________________________p  )        7.2     Listing all included files   L                        When a document is processed to the final output, theO                        VAX DOCUMENT command line indicates the top level source L                        SDML file to be processed. When one of VAX DOCUMENT'sK                        three components (Tag Translator, Text Processor and L                        Device Converter) encounter any of the tags (or theirL                        equivalents) as specified in Table 7-1, the specifiedG                        files will be opened and included into the finali(                        printable output.  M                        The tags available in VAX DOCUMENT to include material A                        into the document are listed in Table 7-1.e  Q                        Table_7-1__Tags_that_cause_other_files_to_be_included_____e  Q                        tag_____________________________description_______________w  P                        <ELEMENT>(filespec)[1]          An SDML file specified inE                                                        a profile file   M                        <INCLUDE>(filespec)[1]          An SDML file specifiedgP                                                        inside another SDML file.  I                        <INCLUDES_FILE>(logical-        A reference in the1J                        name\file-spec)[1]              profile that one ofJ                                                        the <ELEMENT> filesK                                                        contains a <INCLUDE>SO                                                        with a logical name that N                                                        must be translated intoO                                                        the specified file spec.   P                        <TABLE_FILE>(file-spec)[1]      Within a table, inserts a=                                                        table.   I                        <FIGURE_FILE>(target-           Specified within apL                        device\file-or-space\vertical-  <FIGURE> environment,M                        size)[3]                        and specifies a binary K                                                        graphical file to be P                                                        included in the document.  M                        <INCLUDE_TEX_FILE>(file-        Specifies that the TagTO                        spec)[2]                        Translator should inserttN                                                        the specified file withO                                                        TeX macros at this spot.iP                                                        It is a .TEX file, not anB                                                        .SDML file.  Q                        __________________________________________________________f7                        [1]Tag Translator does inclusion_  7                        [2]Text Processor does inclusion_  9                        [3]Device Converter does inclusion                   7-2  <                                    Digital Internal Use Only         Q                            DOCTORing SDML files: hierarchy of files within a book           K                        Table 7-1 (Cont.)  Tags that cause other files to beiQ                        ___________________included_______________________________h  Q                        tag_____________________________description_______________e  L                        <ICON_FILE>(target-             As a figure file, butP                        device\file-spec\vertical-      within an <ICON> context.                        size)[3]c  O                        <EXAMPLE_FILE>(file-spec)[1]    Allows a text file to bedM                                                        inserted as part of an A                                                        <EXAMPLE>.   O                        <MEMO_FILE>(dvi-file-spec)[3]   Allows another .DVI_destfM                                                        file to be included byeK                                                        the Device Converter N                                                        at this position in theC                                                        output file. Q                        __________________________________________________________ 7                        [1]Tag Translator does inclusioni  9                        [3]Device Converter does inclusion Q                        ___________________________________________________________  K                        By specifying the DOCTOR/SDML for an .SDML file, the N                        DOCTOR will open that file and follow every lead if oneN                        of the above tags is encountered. Only when those filesK                        are VAX DOCUMENT source files themselves, the DOCTORoL                        opens those files and recursively inspects those too.M                        It will ignore any of these included file tags if they N                        are coded inside a <LITERAL> and/or <COMMENT> block. IfN                        you do want to take into account these blocks, you mustI                        specify the /IGNORE=(COMMENTS,LITERALS) qualifier.   O                        The final result is a new version of the specified file, L                        but with a comment header that illustrates the nestedP                        composition of the parts the document is build of. RatherO                        than the next higher version, you can specify the outputeJ                        file yourself through /OUTPUT, or if you don't wantO                        another version of the source file, /OUTPUT=NL: producessO                        no output. This is useful only when some other output ise?                        required, e.g. the MMS description file.t  M                        It is also highlighted which files were supposed to besO                        there, but could not be found. By specifying DOCTOR/SDMLdO                        /CMS you instruct the DOCTOR also to inspect any DEC/CMSpO                        libraries that are currently defined through the CMS SETsO                        LIBRARY command. Normally it will simply look in the CMS L                        library and inspect any of the highest generations ofO                        the CMS elements. However, by specifying /CMS=generation L                        only elements are looked up that are a member of that-                        particular generation.   Q                                                                               7-3n  <                                    Digital Internal Use Only .  .    E                DOCTORing SDML files: hierarchy of files within a book)          A                        An example output is given in Example 7-1.u  P                        This example illustrates that the header that is producedN                        always starts with *MF*. You should not remove this, ifM                        you wish to run DOCTOR/SDML over the same source again O                        later. These *MF* are recognized by the utility as being L                        an older hierarchy list and it would replace it by anM                        updated one, if the same SDML file is scanned a second                         time.  >                        The annotations in the example indicate  O                        1  The version of the utility that produced the listing.oP                           This is important if bug fixes are communicated to the%                           developers.   M                        2  The utility was invoked as DOCTOR/SDML/CMS to allow P                           searching though the active DEC/CMS libraries that are&                           listed here.  P                        3  This file is not found in either the current directory2                           or any other CMS library  L                        4  This file was found only as element in the DEC/CMS!                           librarya  N                        5  The remainder of the file is unmodified and an exactN                           copy of the specified input file. In the example, weN                           used a profile file that includes many elements thatQ                           in turn reference several graphical figures (.PS, .EPS,cM                           .SIX) as well as program examples in Pascal (.PAS).e  N                        Using the DOCTOR/SDML utility provides you with an easyP                        tool to make sure all elements that are needed to rebuild=                        your document are present (or not...).a  Q                __________________________________________________________________e  *        7.3     Producing MMS rebuild files  O                        Because once the hierarchy list is made, the DOCTOR alsonM                        knows which files depend on which other ones, it is an O                        easy task to produce a description file that can be read P                        by DEC/MMS to rebuild the document if one of the elements#                        is modified.                         7-4  <                                    Digital Internal Use Only o  r    Q                            DOCTORing SDML files: hierarchy of files within a bookt        J                        Example 7-1  Hierarchy list produced by DOCTOR/SDMLQ                        __________________________________________________________d  $                        <COMMENT>*MF*S                        *MF*    Created by DOCTOR V3.0 at 20-JUL-1992 13:51:10.98  1                         *MF*AS                        *MF*    Command issued: DOCTOR/SDML PASCAL_DECPRESS.SDML/CMS R                        *MF*    QAR's to:        Theo de Klerk @UTO,  NSIC00::KLERK                        *MF* E                        *MF*         *** Digital Internal Use Only ***                         *MF*eA                        *MF*    CMS library = PSQ:[EXAMPLE.CMSLIB]                         *MF*eT                        *MF*    The following files are referenced by this SDML file:                        *MF* *                        *MF*     FRONT.SDML(                        *MF*     VMS.SDML/                        *MF*          PROCESS.PSL.                        *MF*          PSPACE.PSI                        *MF*          PSPACE.SIX --- file not found ---  2 0                        *MF*          SCHEDULE.PSH                        *MF*          SCHEDULE.SIX --- file not found ---3                        *MF*     IMAGEACTIVATOR.SDMLa2                        *MF*          SOURCEFILE.PS3                        *MF*     PASCAL_ENHANCE.SDML I                        *MF*          VARYING.PAS  (CMS library)         3eE                        *MF*          STRING_SCHEMA.PAS  (CMS library)n3                        *MF*          CONFORMANT.PAS ?                        *MF*     ENVIRONMENT.SDML  (CMS library)t,                        *MF*     STARLET.SDML1                        *MF*          DESCFIG1.EPSg,                        *MF*     STORAGE.SDML3                        *MF*          VAL_VAR_CAL.PS 2                        *MF*          NOPICTURE.TXT/                        *MF*          FOREIGN.PS 8                        *MF*     CASE.SDML  (CMS library)@                        *MF*     BIBLIOGRAPHY.SDML  (CMS library)-                        *MF*     GLOSSARY.SDML.'                        *MF*<ENDCOMMENT>                            <PROFILE>I                            <ELEMENT>(FRONT.SDML)                        4 .                            <ELEMENT>(VMS.SDML)9                            <ELEMENT>(IMAGEACTIVATOR.SDML) 9                            <ELEMENT>(PASCAL_ENHANCE.SDML) 6                            <ELEMENT>(ENVIRONMENT.SDML)2                            <ELEMENT>(STARLET.SDML)2                            <ELEMENT>(STORAGE.SDML)/                            <ELEMENT>(CASE.SDML) 7                            <ELEMENT>(BIBLIOGRAPHY.SDML) 3                            <ELEMENT>(GLOSSARY.SDML) '                            <INDEX_FILE> #                        <ENDPROFILE>_  Q                        __________________________________________________________   Q                                                                               7-5   <                                    Digital Internal Use Only         E                DOCTORing SDML files: hierarchy of files within a book           L                        Because DEC/MMS does not know how to build an LN03 orM                        PostScript file from a SDML file, the DOCTOR/SDML also O                        inserts all the required MMS rules and suffixes to allow P                        DEC/MMS to retrieve the sources from a CMS library and toF                        rebuild it using a proper VAX DOCUMENT command.  N                        In order to produce such a description file for DEC/MMSL                        you must specify the /MMS qualifier. If you specify aN                        filespec to it, that filename will be used. Otherwise aM                        description file is produced with the same filename as P                        the input SDML file, but with file extention .MMS. If youN                        don't want to replace the header of the original sourceL                        file also, specify /OUTPUT=NL: to ensure only an .MMS?                        file is produced, and no new .SDML file._  G                        The DOCTOR/SDML will generate an MMS description I                        file that has build instructions for the following J                        destinations. If nothing is specified explicitly byM                        the user, a default choice is made for the name of ther3                        doctype and the destination:   J                        o  BOOKREADER (default: SOFTWARE.ONLINE BOOKREADER)  5                        o  LN03 (default: REPORT LN03)r  A                        o  POSTSCRIPT (default: REPORT POSTSCRIPT)g  =                        o  LINE_PRINTER (default: REPORT LINE)f  5                        o  MAIL (default: REPORT MAIL)   L                        It is possible to specify a different doctype name orM                        destination, if your local site does not use the abovey=                        (default DOCUMENT installation) names:   P                        o  Use the /DOCTYPE to specify another doctype for either7                           paper or online destinations:   A                                /DOCTYPE=(PAPER=name, ONLINE=name)c  M                        o  Use the /DESTINATION to specify another destination H                           name for one or several of the possible output'                           destinations:   C                                /DESTINATION=(LN03=LN03_destination, O                                              POSTSCRIPT=PostScript_destination, S                                              LINE_PRINTER=LINE_PRINTER_destination,iC                                              MAIL=MAIL_destination,vN                                              BOOKREADER=BOOKREADER_destination-                                             )                   7-6  <                                    Digital Internal Use Only    e    Q                            DOCTORing SDML files: hierarchy of files within a bookd          M                        It is possible to order DOCTOR to only inspect element,J                        generations that belong to a specific CMS class. InM                        that case, the /CMS=generation must be specified. This I                        also results in an additional MMS macro, CMSFLAGS=fM                        /GEN=generation to be specified in the MMS description                         file.  P                        Finally, some sites use special logical names, additionalL                        DEC/MMS rules etc. To allow for this, you can specifyH                        the /INCLUDE= qualifier. It specifies a file thatM                        contains valid DEC/MMS instructions. Its result on theeJ                        produced description file by the DOCTOR/SDML/MMS isN                        that an .INCLUDE filespec directive is written into theL                        description file. This included file can contain yourP                        own set of suffix definitions, action rules and MMS macro                        symbols.r  N                        Normally DOCTOR/SDML/MMS provides a set of suffixes andM                        action rules to retrieve files from DEC/CMS libraries. N                        If you use an .INCLUDE file, you may want to define allM                        your own suffixes and rules and not use those providedeK                        by DOCTOR. In that case, you should specify the /MMSaL                        /NORULES. This qualifier will still produce a minimumO                        set of rules that enable MMS to rebuild the final targetf9                        files from the .SDML source files.   I                        The valid qualifiers for DOCTOR/SDML are listed in !                        Table 7-2.   Q                        Table_7-2__DOCTOR/SDML_qualifiers_for_DEC/MMS_____________s  Q                        /MMS file                   Produces a new version of SDMLfQ                                                    and a standard MMS description 8                                                    file.  N                        /MMS=descfile file          As above, but with descfileO                                                    used for the MMS output file   L                        /MMS=descfile/NORULES       As above, but without theL                        file                        generation of default MMSE                                                    rules and suffixese  K                        /MMS                        produces an MMS file for H                        /DOCTYPE=(PAPER=MANUAL)     making a MANUAL styleK                        /DESTINATION=(POST=MY_      based document for paperlN                        QUEUE)                      destinations, and using theO                                                    MY_QUEUE name for PostScriptg@                                                    destinations.  Q                                                                               7-7e  <                                    Digital Internal Use Only         E                DOCTORing SDML files: hierarchy of files within a book           Q                        Table_7-2_(Cont.)__DOCTOR/SDML_qualifiers_for_DEC/MMS_____   N                        /MMS /CMS=generation        produces an MMS descriptionJ                                                    file that contains onlyK                                                    the relations to rebuild_M                                                    the document consisting ofeL                                                    elements that are part ofO                                                    the specified CMS generation Q                        ____________________________(class).______________________   M                        Because the doctype and destination as well as the VAX L                        DOCUMENT commmand are defined as MMS symbols, you canO                        at any time overrule them by specifying the same symbols_M                        as DCL command symbols and invoke the description file_8                        through the command MMS/OVERRULE.  E                        Specific additional DOCUMENT qualifiers may beeJ                        specified using /DOCQUALIFIERS= where the string ofH                        DOCUMENT qualifiers are specified between quotes,L                        e.g. /DOCQUALIFIERS= ("/CONTENTS/INDEX"). By default,H                        /CONTENTS /INDEX /BATCH=(NOPRINT,NOTIFY) is used.  A                        An example output is given in Example 7-2.n  ;                Example 7-2 Example DEC/MMS description file Q                __________________________________________________________________                   !I                !  Created by DOCTOR V3.1 at 24-SEP-1992 13:53:23.58     1t                !O                !  Command issued: /SDML PASCAL_DECPRESS.SDML/OUT=NL: /MMS=X.MMS D                !  QAR's to:       Theo de Klerk @UTO,  NSIC00::KLERK                !7                !      *** Digital Internal Use Only ***                 !                .SUFFIXES   2V                .SUFFIXES  .DECW$BOOK .PS .LN03 .LINE .TXT  .FDL .CLD .MSG .FOR .PAS  -Z                   .PSART .EPS .FSE .SIX .SDML .GRA .DECW$BOOK~ .PS~ .LN03~ .LINE~ .TXT~  -L                   .FDL~ .CLD~ .MSG~ .FOR~ .PAS~ .PSART~ .EPS~ .FSE~ .SIX~  -                   .SDML~ .GRA~  %                DOCUMENT=DOCUMENT    3                 DOCTYPE=REPORTf-                ONLINE_DOCTYPE=SOFTWARE.ONLINE                 LINE_DEST=LINEr                MAIL_DEST=MAIL )                POSTSCRIPT_DEST=POSTSCRIPTe                LN03_DEST=LN03 %                ONLINE_DEST=BOOKREADER C                DOCQUALIFIERS=/CONTENTS/INDEX/BATCH=(NOTIFY,NOPRINT)   Q                __________________________________________________________________/3                Example 7-2 (continued on next page)                   7-8  <                                    Digital Internal Use Only    b    Q                            DOCTORing SDML files: hierarchy of files within a bookn        C                Example 7-2 (Cont.) Example DEC/MMS description filehQ                __________________________________________________________________r  (                .DECW$BOOK~.DECW$BOOK : 4`                    IF "$(MMS$CMS_LIBRARY)" .NES. "" THEN  DEFINE/USER CMS$LIB $(MMS$CMS_LIBRARY)q                    $(CMS) FETCH $(MMS$CMS_ELEMENT) /OUTPUT=$(MMS$TARGET_NAME).DECW$BOOK $(CMSFLAGS) $(CMSCOMMENT)c                  .PS~.PS :`                    IF "$(MMS$CMS_LIBRARY)" .NES. "" THEN  DEFINE/USER CMS$LIB $(MMS$CMS_LIBRARY)j                    $(CMS) FETCH $(MMS$CMS_ELEMENT) /OUTPUT=$(MMS$TARGET_NAME).PS $(CMSFLAGS) $(CMSCOMMENT)  #                    ... etcetera ...                   .SIX~.SIX :`                    IF "$(MMS$CMS_LIBRARY)" .NES. "" THEN  DEFINE/USER CMS$LIB $(MMS$CMS_LIBRARY)k                    $(CMS) FETCH $(MMS$CMS_ELEMENT) /OUTPUT=$(MMS$TARGET_NAME).SIX $(CMSFLAGS) $(CMSCOMMENT)   #                    ... etcetera ...r                  .SDML~.SDML :`                    IF "$(MMS$CMS_LIBRARY)" .NES. "" THEN  DEFINE/USER CMS$LIB $(MMS$CMS_LIBRARY)l                    $(CMS) FETCH $(MMS$CMS_ELEMENT) /OUTPUT=$(MMS$TARGET_NAME).SDML $(CMSFLAGS) $(CMSCOMMENT)                   .SDML.DECW$BOOK :c                    $(DOCUMENT) $(MMS$TARGET_NAME) $(ONLINE_DOCTYPE) $(ONLINE_DEST) $(DOCQUALIFIERS)                   .SDML.PS : `                    $(DOCUMENT) $(MMS$TARGET_NAME) $(DOCTYPE) $(POSTSCRIPT_DEST) $(DOCQUALIFIERS)                  .SDML.LN03 : `                    $(DOCUMENT) $(MMS$TARGET_NAME) $(DOCTYPE) $(LN03_DEST)       $(DOCQUALIFIERS)                  .SDML.LINE : `                    $(DOCUMENT) $(MMS$TARGET_NAME) $(DOCTYPE) $(LINE_DEST)       $(DOCQUALIFIERS)                  .SDML.TXT :`                    $(DOCUMENT) $(MMS$TARGET_NAME) $(DOCTYPE) $(MAIL_DEST)       $(DOCQUALIFIERS)                  .GRA.SDML :G                    $(DOCUMENT)/GRAPHICS=RENDER $(MMS$TARGET_NAME).GRA - a                         /TYPE=(PS,BRF,MONOSIX)/OUTPUT=$(MMS$TARGET_NAME)/NOBACKGROUND/SDML=FIGUREe                  .DEFAULT :  50                    ! No action for $(MMS$TARGET)  <                PROFILE.DECW$BOOK DEPENDS_ON  PROFILE.SDML, --                        BOOKREADER_FIX.SDML, -t$                        FRONT.SDML, -%                        PART10.SDML, -r"                        VMS.SDML, -%                        PROCESS.FSE, - $                        PSPACE.FSE, -  "                    ... etcetera...  Q                __________________________________________________________________ 3                Example 7-2 (continued on next page)   Q                                                                               7-9e  <                                    Digital Internal Use Only         E                DOCTORing SDML files: hierarchy of files within a book         C                Example 7-2 (Cont.) Example DEC/MMS description file Q                __________________________________________________________________   9                PROFILE.LN03 DEPENDS_ON  PROFILE.SDML, - 6 -                        BOOKREADER_FIX.SDML, -u$                        FRONT.SDML, -%                        PART10.SDML, -l"                        VMS.SDML, -%                        PROCESS.SIX, -a$                        PSPACE.SIX, -  "                    ... etcetera...  5                PROFILE.PS DEPENDS_ON  PROFILE.SDML, -u-                        BOOKREADER_FIX.SDML, - $                        FRONT.SDML, -%                        PART10.SDML, - "                        VMS.SDML, -$                        PROCESS.PS, -#                        PSPACE.PS, -c  6                   ...etcetera for all other targets...  P                ! If the next dependency is used, one should not submit the finalN                ! DOCUMENT jobs in batch mode as they are not allowed to run inK                ! parallel. The MMS macro DOCQUALIFIERS should be defined asi.                ! DOCQUALIFIERS=/CONTENTS/INDEXA                ALL_DOCUMENTS DEPENDS_ON PROFILE.DECW$BOOK, -    7O3                         PROFILE.PS, PROFILE.LN03, -_1                         PROFILE.LINE, PROFILE.TXT Q                ______!_All_are_up_to_date________________________________________2  N                        Some notes by the MMS description file as shown in this                        example:L  I                        1  The version number of the utility is once againh$                           mentioned.  P                        2  The order in which file types depend on one another isN                           redefined. It includes all the file types the DOCTORM                           encountered while building the hierarchy list. This K                           list will be suppressed if /NORULES is specified.   F                        3  The DOCUMENT command as well as the doctype,O                           destination and qualifiers are all defined as symbols O                           to allow overrule through DCL symbols or a MMS/MACRO= "                           command.  M                        4  For each of the file types found, rules are made toFO                           allow MMS to fetch them from a DEC/CMS library. TheseMP                           are suppressed if the qualifier /NORULES is specified.  P                        5  When no update can be made for a certain file element,H                           by default it notifies the user and continues.                  7-10l  <                                    Digital Internal Use Only         Q                            DOCTORing SDML files: hierarchy of files within a book           K                        6  The first target to build is the entire document. N                           Dependency lines for all supported output file types7                           are created in a similar way.   P                        7  If you want all destinations to be processed one afterO                           the other, you must invoke MMS in this example, using)%                           the commandA  H                                MMS/DESCRIPTION=PROFILE.MMS ALL_DOCUMENTS  P                           It will then execute this annotated line which in turnN                           will invoke each of the DOCUMENT commands to produceL                           the Bookreader, PostScript, LN03, Line_printer andN                           Mail files respectively. This command may not resultL                           in a batch job, however. That would cause parallelQ                           execution of DOCUMENT on the same set of files, causing O                           a conflict on the access to the .XREF cross referenceSL                           file of the book: it must be executed in sequence.  Q                ___________________________________________________________________  -        7.4     Using_the_MMS_description_file   "        7.4.1   What file to build?  P                        The generated MMS description file can be used in severalO                        ways. As you can see from Example 7-2, a dependency rule K                        is generated for each of the supported destinations.   L                        If you run MMS using all its defaults, it will alwaysP                        generate a dependency line for the Bookreader destination                        only.  H                        As can be seen from Example 7-2 this is the firstM                        dependency rule specified in the generated description P                        file, and by default this is the only action performed by                        MMS.r  P                        If you want any specific destination to be used, you must$                        invoke MMS as  ?                          $ MMS/DESCRIPTION=file.MMS  targetfile   J                        where the targetfile is the output file you want toG                        build. From the Example 7-2 this could be either G                        PROFILE.PS or PROFILE.LN03 or any of the others.M      Q                                                                              7-11   <                                    Digital Internal Use Only         E                DOCTORing SDML files: hierarchy of files within a book         *                ___________________________  -        7.4.2   Another doctype than specifiedt  M                        Once the MMS description file is generated, a value isiL                        assigned to the MMS macro DOCTYPE and ONLINE_DOCTYPE.O                        Either these are the defaults REPORT and SOFTWARE.ONLINE G                        or those that were specified using the qualifier 2                        /DOCTYPE=(PAPER= ,ONLINE= )  O                        If for some reason you still want another doctype, theres8                        are three ways of obtaining this:  M                        1  Edit the MMS description file and change the values L                           specified for DOCTYPE and ONLINE_DOCTYPE macros as=                           specified at the start of the file.   @                        2  Invoke MMS using the /MACRO qualifier:  [                                MMS/MACRO=("DOCTYPE=other_name","ONLINE_DOCTYPE=other_name")S  Q                        3  Define a DCL symbol with the same name as the MMS macroeQ                           before you invoke MMS (not using the /MACRO qualifier):   8                                $  DOCTYPE = "other_name"?                                $  ONLINE_DOCTYPE = "other_name"t  *                ___________________________  1        7.4.3   Another destination than specifiedi  H                        If another destination name is required than thatM                        specified in the MMS description file, you can proceed P                        the same way as specified in Section 7.4.2, replacing the                        macros:  %                           ONLINE_DEST )                           POSTSCRIPT_DESTy#                           LN03_DEST #                           LINE_DESTo#                           MAIL_DEST,  J                        Change of the destination is normally only requiredK                        if the local DOCUMENT system has been set up to know L                        different names than those specified by default. ThisK                        is especially the case with sites that have DOCUMENT G                        installed from V1.0 onwards or that have enabledtL                        automatic printing after processing. Those started atL                        V2.0 normally don't have different names and will notE                        have the need to change the destination names.a                  7-12s  <                                    Digital Internal Use Only i  b    Q                            DOCTORing SDML files: hierarchy of files within a book         *                ___________________________  -        7.4.4   Using DOCUMENT/GRAPHICS (Rags)   M                        A special mention must be made for the use of DOCUMENT I                        /GRAPHICS produced graphics. This utility, that isMP                        delivered with VAX DOCUMENT V2.0 onwards, is a DECwindowsI                        oriented graphics editor, that will produce one orDK                        several different output graphics: PostScript, sixelaI                        or BRF-bookreader files. In addition it can outputtJ                        another .SDML file that only contains <FIGURE_FILE>P                        tags. This enables the author to completely decouple textN                        and graphics components of the document. The only thing7                        written in the text file will beq  @                           <FIGURE>(figure caption\figure_symbol)4                           <INCLUDE>(figurefile.SDML)%                           <ENDFIGURE>s  I                        whereas the figurefile.SDML will be created by the I                        DOCUMENT/GRAPHICS editor and contains the required N                        <FIGURE_FILE> tags with the correct size of the figure,=                        which may differ for each destination.w  O                        When DOCTOR/SDML/MMS is required to produce an MMS file,uN                        it will also add the action rule to invoke the graphicsK                        editor DOCUMENT/GRAPHICS=RENDER to recreate any suchdP                        .SDML file from a graphics meta-file with file type .GRA.K                        However, this will only work, if the MMS descriptionoN                        file is invoked by MMS while running under a DECwindowsN                        environment, as the DOCUMENT/GRAPHICS utility will onlyM                        work when it has the DECwindows environment available- L                        even if it will not display a single window. For thisI                        reason, the MMS file must either be invoked from a M                        DECterm window on your workstation or, if submitted to L                        batch made, the LOGIN.COM file needs to contain a DCLN                        command to create a display on some active workstation:  Y                          $ SET DISPLAY/CREATE/NODE=nodename /TRANSPORT=(LAT|LOCAL|DECNET)   N                        where the specified node name is a workstation in whichJ                        the Session Manager has been told (via the SecurityL                        option) to accept displays from the node on which theM                        batch queue is running and from the username for which P                        the batch job has been submitted. If the security settingJ                        does not allow this, the MMS job will abort becauseN                        DOCUMENT/GRAPHICS will return a fatal error for "unable*                        to create display".    Q                                                                              7-13M  <                                    Digital Internal Use Only m       E                DOCTORing SDML files: hierarchy of files within a book           J                        Instead of the LOGIN.COM file, you can also specifyK                        another MMS file to contain the SET DISPLAY command.eN                        This MMS file is added to the generated one through the9                        DOCTOR/SDML/MMS/INCLUDE qualifier.e  Q                __________________________________________________________________l  )        7.5     Retrieve all index entriesB  L                        When a document is written and it contains many indexM                        entries, your chances are good that some index entriesfK                        that were supposed to be identical, but on different_O                        pages, are actually printed as two entries in the index.PN                        Usually because you mistyped an entry of the <X> or <Y>                        tag.N  P                        Finding those typo's is tedious: you need to get the bookP                        printed, then look in the index, find the errors, look atP                        that page, determine which file is comes from and finally=                        go into the editor and find the entry.   I                        The DOCTOR allows all this to be done much easier, N                        without the overhead of rebuilding the entire book eachL                        time you think you found all the errors. (Usually theM                        fixing of index entries take several repeated loops of 3                        correcting the tag entries).I  N                        By specifying DOCTOR/SDML/INDEX the DOCTOR produces theO                        hierarchy list, but, while scanning through all the SDMLXP                        source files, it also copies each and every occurrence ofN                        the <X> and <Y> tags into a separate file, specified by-                        the /INDEX= qualifier.   L                        The result looks something like Example 7-3. This may7                        look odd, but it is very useful.   6                Example 7-3 Output of DOCTOR/SDML/INDEXQ                ___________________________________________________________________  N                <X>(DOCTOR<XS>installation)       <comment>(    34 DOCTOR.SDML)L                <X>(DOCTOR<xs>invocation)       <comment>(    58 DOCTOR.SDML)C                <X>(CONFORM)       <comment>(    16 DOCTOR_MSG.SDML)RC                <X>(CREATED)       <comment>(    25 DOCTOR_MSG.SDML).N                <Y>(IDENT - See DOCTOR)       <comment>(    34 DOCTOR_MSG.SDML)  Q                __________________________________________________________________M  P                        The fact that all lines start with tag <X> or <Y>, allowsL                        you to use the DCL command SORT to sort the file intoP                        alphabetical order. (It is produced in order of the files1                        referenced by the DOCTOR).                   7-14T  <                                    Digital Internal Use Only .  L    Q                            DOCTORing SDML files: hierarchy of files within a book$          9                          $ SORT  input_file   output_fileP  I                        This will position typo's near each other and easyDJ                        to spot when the sorted file is printed. It is alsoK                        easy to load all the required SDML source files into M                        your editor buffers once, and then move from buffer toIL                        buffer[1] to correct the errors. Since you do not addO                        any lines, but simply re-type an entry, the line numbersLO                        that preceed the file specification that is given in theTP                        <COMMENT> on the same line, allows you to use a goto lineO                        command[2] to quickly move to the indicated line to find /                        the incorrect tag entry.)  M                        Once all these entries have been corrected in the SDML,O                        files, you can run DOCTOR/SDML/INDEX once more on it andEL                        inspect the new output to spot any typo's you forgot.M                        If there are none, you can use the produced index fileEK                        to make a dummy book by processing the index file byPP                        itself. Of course the final output will contain non-senseN                        page numbers, but at least it is processed and build inP                        substantially less time than redoing the entire document.O                        When the processed and printed index also looks correct, N                        then you reprocess the entire book. If you're still notK                        satisfied, you should make additional changes to the -                        incorrect tag entries.n  7                                                   Note:eI                             You may run into %TEX-MEMEXCEEDED errors when_H                             there are many entries in the produced indexI                             file. Because there is no real text, the Text J                             Processor can write all the index entries on aJ                             single page. It stores them in memory, waitingH                             for a new page to start (which never comes).I                             Therefore, it is a good idea to use an editor F                             and insert dummy text between the lines ofF                             index tags, as well as <PAGE> tags. If youJ                             supply the qualifier /RANDOM_TEXT, then DOCTORF                             will add this text for you. Obviously, youJ                             need only to print or inspect the resulting *_*                             INDEX.* files.      #                ____________________   -             [1] "GOTO BUFFER name" for LSEDITe               [2] LINE for LSEDITU  Q                                                                              7-15-  <                                    Digital Internal Use Only                     Q                ___________________________________________________________________  7        8       DOCTORing SDML files: Counting tags usede      Q                __________________________________________________________________           8.1     Overviews  M                        This is a very simple utility that counts all the tags K                        encountered in an SDML file. A tag is defined as any O                        contiguous text string consisting of alphabetic, numericRN                        or underscore characters, surrounded by the opening andP                        closing angle brackets: <LIKE_THIS>. For this reason, theM                        utility also detects and counts all user defined tags.   G                        The utility is invoked through DOCTOR/TAG_COUNT, J                        and takes a single SDML file as input parameter. ItO                        automatically also searches through all files referencedhJ                        by the input file specified: if a profile is given,M                        all elements of the book are also searched, as are thep'                        <INCLUDE> files.f  7                                                   Note:eG                             This utility counts any tag-like construct,iF                             as it does not interpret or validate them.E                             This also means it counts all tags within J                             <COMMENT> blocks and/or <LITERAL> blocks. WhenF                             within these blocks <INCLUDE> or <ELEMENT>D                             or <INCLUDES_FILE> tags are encountered,G                             DOCTOR/TAG will attempt to lookup the filesyD                             referenced by these tags. It will give aD                             warning if those files do not exist, but1                             continues processing.   Q                __________________________________________________________________C          8.2     Options  L                        Because of its simplicity, there are few options withI                        this utility. You can specify your own output file P                        specification using the /OUTPUT qualifier. If omitted, itN                        defaults to the input file specification, but with fileP                        type .TAG_COUNT. Only /LOG can be specified to keep trackM                        of the number of files sofar processed in case several B                        nested SDML included files are encountered.    Q                                                                               8-1   <                                    Digital Internal Use Only _  _    7                DOCTORing SDML files: Counting tags used         Q                __________________________________________________________________a          8.3     Output format  M                        The output file is a simple ASCII text file, formatted L                        as indicated in Example 8-1, which was made against aC                        version of the source file of this document.   L                        Notice that the number of occurrences is given in theN                        first columns 1-7, whereas the tag names are given fromO                        column 9 onwards. They are sorted in alphabetical order,hL                        but if you need them in numerical order, the DCL SORT;                        command can quickly do this for you:   E                          SORT /KEY=(POSITION=1,SIZE=7) infile outfileo  G                        Example 8-1  Sample DOCTOR/TAG_COUNT output fileMQ                        __________________________________________________________   Q                         Generated by DOCTOR/TAG_COUNT.  Digital Internal Use Onlyi  _                        Tags (and their frequency) found in SDML document rooted in DOCTOR.SDML:   )                              2 <ABSTRACT> )                              4 <APPENDIX> (                             10 <CALLOUT>)                              3 <CALLOUTS>D,                              2 <CENTER_LINE>(                             10 <CHAPTER>-                            412 <CODE_EXAMPLE>c(                              7 <COMMAND>0                              1 <COMMAND_SECTION>(                             23 <COMMENT>!                                 :N!                                 :E$                            177 <TAG>$                              6 <TEX>&                              3 <TITLE>+                              2 <TITLE_PAGE>P"                              4 <U>,                              3 <VALID_BREAK>"                            369 <X>#                            104 <XS>gQ                        _____13_<Y>_______________________________________________l  Q                __________________________________________________________________           8.4     Usage  K                        This utility was created to make a quick estimate oniJ                        the amount of conversion effort required if an SDMLP                        encoded file needs to be converted into some other markupN                        language, such as SGML, Runoff or a TeX-flavour such as&                        LaTeX or ZzTeX.                  8-2  <                                    Digital Internal Use Only                     Q                __________________________________________________________________   #        9       DOCTORing XREF filesf      Q                __________________________________________________________________           9.1     Overview   K                        When a large document is built using DOCUMENT, often I                        references are used to point to other parts of the:P                        document. After a while, and certainly if several authorsI                        work on a document, you start losing track of whatDN                        symbols are defined for what tables, sections and otherL                        referable items. Even if a naming convention is used.  O                        For this reason DOCTOR/XREF has been built. It will workaN                        on any document of which the cross reference .XREF fileN                        exists. This is always true for documents built throughL                        a profile. Single file documents do not have an .XREFK                        file - the Tag Translator keeps all data gathered iniP                        Pass 1 in memory and uses it to resolve references duringN                        Pass 2: no need for a file. You must break up this fileO                        into parts and add a profile file to it, in order to usei#                        DOCTOR/XREF.   M                        Using DOCTOR/XREF on a .XREF file will allow you to doM&                        several things:  Q                        o  Build an SDML file with all symbols listed in a <TABLE> Q                           structure. By processing this SDML file (e.g. using therQ                           REPORT doctype) you get a nicely printed listing of all P                           symbols and their textual contents. Those lists can beQ                           alphabetic on symbol name or sorted numerically by typelN                           (e.g. all table symbols sorted by table number). TheJ                           /SORT or /LIST qualifiers are required for this.  N                        o  Build an SDML symbol file containing <DEFINE_SYMBOL>M                           tags of all symbols defined in the .XREF file. This P                           allows you to <INCLUDE> that file into some other bookL                           and thereby enables you to cross reference betweenQ                           books. The /SYMBOL_FILE qualifier is required for this.   7                                                   Note:oE                             In some cases you want to ensure all usedeJ                             <REFERENCE> tags will have proper definitions.H                             Sometimes however those symbols do not (yet)I                             exist. If you need a file where all undefinediF                             symbols can be temporarily defined using a  Q                                                                               9-1c  :                                  Digital Internal Use Only    s    #                DOCTORing XREF files           G                             <DEFINE_SYMBOL>, then use the DOCTOR/ONLINE J                             /DUMMY qualifier, as described in Section 5.4.  Q                __________________________________________________________________   $        9.2     Build symbol listings  O                        DOCTOR/XREF allows you to produce a formatted listing oftO                        all symbols defined in a document. The listings are made O                        in <TABLE> format and can be processed with VAX DOCUMENT L                        using any doctype available that supports table tags.L                        The listings can be made in alphabetical order or theN                        symbol names but also in numerical order of the section)                        or object numbers.   I                        To obtain these lists, you need to use the command   =                          DOCTOR/XREF file.XREF /LIST=filespect  H                        if you want an alphabetical list of all symbols -I                        a mixture of tables, sections, examples, chapters,uO                        appendices and others. If you don't specify the filespecbM                        with the /LIST qualifier, it defaults to the same file"O                        name as the .XREF file, but with file type .SDML_SYMBOL_                         LIST.  L                        To produce a list of symbols sorted by type of symbolM                        (table, chapter, example, user defined and others) the 1                        qualifier /SORT is needed.s  =                          DOCTOR/XREF file.XREF /SORT=filespec   L                        By default all symbols are then sorted alphabeticallyM                        per type. However, in many cases it may be more useful P                        if they are sorted by their numeric value (if applicable)N                        so that you can quickly look up the symbol for Table 5-M                        6. If this is required, the /NUMERIC qualifier is also O                        required. To have both alphabetic and numerically sorted A                        lists of symbols, use /ALPHABETIC/NUMERIC.,  N                        You can decide whether the listings just show the briefO                        information about the symbol or the full text, similarlyoM                        to the working of the <REFERENCE> tag, where argumentsgI                        FULL, TEXT, VALUE are allowed. Use the appropriatep?                        qualifier /FULL, /TEXT, /VALUE for this.                         9-2  <                                    Digital Internal Use Only         Q                                                              DOCTORing XREF filesi        Q                __________________________________________________________________n  0        9.3     Build cross reference symbol file  L                        To build a file with <DEFINE_SYMBOL> tags that defineM                        the symbols plus their reference translation, you need I                        to specify the .XREF file to scan and the /SYMBOL_eC                        FILE=filespec for the resulting output file.l  F                          DOCTOR/XREF file.XREF /SYMBOL_FILE=filespec -K                                      /BOOKTITLE="title text" /PREFIX=prefix<  O                        If you omit the file specification, the file name of theiP                        .XREF file is taken, and file type defaults to .SDML_XREFL                        to avoid it to overrule the profile file of the book,P                        which otherwise would have the same file specicification,O                        but a totally different contents that you would not wanta6                        to lose by an accidental purge.  M                        If the symbols defined are going to be used in another N                        book, a potential collision may occur if the other bookL                        uses the some identical names for symbols. To preventI                        this, a prefix can (and should) be attached to all_J                        symbols derived from the .XREF file to ensure theirL                        uniqueness. Within Corporate Publishing, the bookcodeM                        could be used for this. If /PREFIX is not specified, a C                        warning is issued, but processing continues.   7                                                   Note: E                             Make sure that symbol name + prefix never K                             exceeds the VAX DOCUMENT limit of 31 charactersoH                             maximum length. DOCTOR/XREF will warn you ifI                             this is the case and truncate the symbol name 7                             to maximum allowable length   J                        In addition to specifying a prefix, you should alsoK                        specify the title of the book, using the /BOOKTITLE=fP                        qualifier. This will result in the definition of a symbolN                        prefixBOOK which translates into the specified title ofN                        the book. (The prefix part is specified through /PREFIXM                        or omitted if this is not specified). This way you canhN                        perform a cross reference to the book from another book"                        by writing:  H                         For more information see <reference>(prefixBOOK)A                         in its <reference>(prefixOVERVIEWCHAPTER)   6                        Which could then translate into  I                        ... For more information see The Art of Zen in itsn6                        Chapter 1, How It All Began ...  Q                                                                               9-3b  <                                    Digital Internal Use Only .       #                DOCTORing XREF filess          N                        You can decide whether the listings just show the briefO                        information about the symbol or the full text, similarly M                        to the working of the <REFERENCE> tag, where arguments I                        FULL, TEXT, VALUE are allowed. Use the appropriatet?                        qualifier /FULL, /TEXT, /VALUE for this.a  M                        In order to use the file with all the symbols defined, &                        you must either  Q                        o  Specify /SYMBOLS=file.SDML_XREF on the DOCUMENT command O                           line for the book that references the defined symbols   O                        o  Specify a <INCLUDE>(file.SDML_XREF) in the profile of F                           the book that references the defined symbols  Q                __________________________________________________________________           9.4     Example outputc  L                        This section gives three examples on the final outputM                        produced by DOCTOR/XREF when the .XREF file is scanned P                        that is produced in processing the Hitch Hiker's Guide toG                        VAX DOCUMENT, another publication of the author.   ,                        The command given was  P                         DOCTOR/XREF ENG_COOKBOOK.XREF /LIST/SORT/ALPHA/NUMERIC -_                           /SYMBOL/PREFIX=HHG_/BOOKTITLE="Hitch Hiker's Guide to VAX DOCUMENT" -                            /FULLr  O                        The results are presented below in the next subsections. K                        Only small parts of the complete table are printed - L                        enough to get a feeling of what DOCTOR/XREF produces.  *                ___________________________  !        9.4.1   Symbol file outputC  M                        The output as shown in Example 9-1 has been <INCLUDE>d_P                        into this document. Therefore, we can now cross referenceO                        to the Hitch Hiker's Guide to VAX DOCUMENT book by using >                        the <REFERENCE> to any particular part.  N                        For example, using <REFERENCE>(hhg_chap10) would resultK                        in: "Hitch Hiker's Guide to VAX DOCUMENT Chapter 10,e@                        Using the Language Sensitive Editor LSE".                      9-4  <                                    Digital Internal Use Only i       Q                                                              DOCTORing XREF files         <                        Example 9-1  Sample .SDML_XREF outputQ                        __________________________________________________________   ?                        <CHECK_FOR_INCLUSION>(ENG_COOKBOOK_XREF) L                        <COMMENT> *******************************************.                         Created by DOCTOR V3.0A                         Creation Date:    21-JUL-1992 11:37:28.78                            Command issued:   /XREF [COOKBOOK]ENG_COOKBOOK /SORT/ALPHA/NUME/FULL/LIS/SYMB/PREF=HHG_/BOOKTITLE="Hitch Hik                          ENT" X                         XREF file used:   PSQ:[PRIVATE.THEO.COOKBOOK]ENG_COOKBOOK.XREF;3K                         QAR's to:        Theo de Klerk @UTO,  NSIC00::KLERKk  <                            *** Digital Internal Use Only ***  L                        *****************************************<ENDCOMMENT>  T                        <DEFINE_SYMBOL>(HHG_BOOK\Hitch Hiker's Guide to VAX DOCUMENT)U                        <DEFINE_SYMBOL>(HHG_ALIGNCHAR\<_italic>(<REFERENCE>(HHG_BOOK)) 6                        \Sectionname 4.8, Aligned text)Q                        <DEFINE_SYMBOL>(HHG_CHAP1\<_italic>(<REFERENCE>(HHG_BOOK))2C                        \Chaptername 1, Basic commands for DOCUMENT)rR                        <DEFINE_SYMBOL>(HHG_CHAP10\<_italic>(<REFERENCE>(HHG_BOOK))Q                        \Chaptername  10, Using the Language Sensitive Editor LSE)fQ                        <DEFINE_SYMBOL>(HHG_CHAP3\<_italic>(<REFERENCE>(HHG_BOOK))w9                        \Chaptername 3, Lists in Document)   (                          ... etcetera...  _                        <DEFINE_SYMBOL>(HHG_THUNDERBIRDSSECTION\<_italic>(<REFERENCE>(HHG_BOOK))DJ                        \Sectionname 2.5.1, The origin of the Thunderbirds)a                        <DEFINE_SYMBOL>(HHG_XREFBOOKREADERSECTION\<_italic>(<REFERENCE>(HHG_BOOK))aO                        \Sectionname 2.3, Cross references and Bookreader files) W                        <DEFINE_SYMBOL>(HHG_XREFSECTION\<_italic>(<REFERENCE>(HHG_BOOK))a0                        \Sectionname 9.5.3, XREF)/                        <ENDCHECK_FOR_INCLUSION>i  Q                        __________________________________________________________a  *                ___________________________          9.4.2   List file output   O                        Rather than showing the VAX DOCUMENT constructs produced J                        in the .SDML_SYMBOL_LIST file, we will show a smallL                        sample of the final output, when the <TABLE> has beenH                        processed by VAX DOCUMENT. This table is shown in!                        Table 9-1.c  C                        Symbols in PSQ:[COOKBOOK]ENG_COOKBOOK.XREF;1I  J                        Book title: <HHG_BOOK> = Hitch Hiker's Guide to VAX                        DOCUMENT   F                        All data specified in table is used for output.  Q                                                                               9-5O  <                                    Digital Internal Use Only S       #                DOCTORing XREF files             Q                        Table_9-1__Alphabetic_list_of_symbols_____________________   Q                        Symbol_name________Type_____NumbeText_____________________   E                        HHG_ALIGNCHAR      Section  4.8   Aligned text   K                        HHG_CHAP1          Chapter  1     Basic commands for<A                                                          DOCUMENT   K                        HHG_CHAP10         Chapter  10    Using the Language M                                                          Sensitive Editor LSE   J                        HHG_CHAP3          Chapter  3     Lists in Document  <                                              ... etcetera...  F                        HHG_TB1SECTION     Section  2.5.1.Thunderbird 1  J                        HHG_THUNDERBIRDSSECSection  2.5.1The  origin of theE                                                          Thunderbirds_  M                        HHG_XREFBOOKREADERSSection  2.3   Cross references and I                                                          Bookreader files   Q                        HHG_XREFSECTION____Section__9.5.3XREF_____________________D  *                ___________________________  &        9.4.3   Sorted list file output  H                        When the output is sorted by its symbol type, theP                        following tables occur. Only a small sample is reproduced                        here:  H                        o  Table 9-2 shows the list of chapter symbols in,                           alphabetical order  H                        o  Table 9-3 shows the list of chapter symbols in)                           numerical order_  M                        Similar lists are also produced for sections, figures,uM                        examples, tables, user defined symbols, and other tagsd6                        that allow symbolic references.  C                        Symbols in PSQ:[COOKBOOK]ENG_COOKBOOK.XREF;1   J                        Book title: <HHG_BOOK> = Hitch Hiker's Guide to VAX                        DOCUMENTw                  9-6  <                                    Digital Internal Use Only c  e    Q                                                              DOCTORing XREF files           F                        All data specified in table is used for output.  Q                        Table_9-2__Chapter_symbols_-_in_alphabetical_order________u  Q                        Symbol_name________NumbeText______________________________   K                        HHG_CHAP1          1     Basic commands for DOCUMENT   L                        HHG_CHAP10         10    Using the Language Sensitive:                                                 Editor LSE  A                        HHG_CHAP3          3     Lists in Documenti  ;                                              ...etcetera...   I                        HHG_LAYOUTCHAPTER  2     Document layout and crosso:                                                 references  Q                        HHG_TABLECHAPTER___4_____Tables_in_Document_______________   Q                        Table_9-3__Chapter_symbols_-_in_numerical_order___________   Q                        NumbeSymbol__name________Text_____________________________   K                        1     HHG_CHAP1          Basic commands for DOCUMENT   I                        2     HHG_LAYOUTCHAPTER  Document layout and cross :                                                 references  A                        3     HHG_CHAP3          Lists in Documentu  ;                                              ...etcetera...l  E                        9     HHG_CHAP9          Extra local additionsy  L                        10    HHG_CHAP10         Using the Language SensitiveQ                        _________________________Editor_LSE_______________________b                        Q                                                                               9-7   <                                    Digital Internal Use Only e                 Q                __________________________________________________________________                   Command Section                                                                                                  <                                    Digital Internal Use Only i       Q                                                                   DOCTOR/GLOSSARY           Q                __________________________________________________________________   ?                DOCTOR/GLOSSARY-Sort glossary items in SDML fileO  P                                The DOCTOR/GLOSSARY utility will sort all <GTERM>M                                tags and associated <GDEF> tags within an SDML Q                                source file. The glossary section may be part of a_P                                larger file. There may only be a single glossary.  Q                __________________________________________________________________s                  FORMATe  F                                DOCTOR/GLOSSARY  filespec [/qualifiers]  Q                                __________________________________________________e=                                Command Qualifiers    Defaults   L                                /OUTPUT                /OUTPUT=input_filespec<                                /LOG                   /NOLOGU                                /SORT                  /SORT=(LETTER, NONALPHA=IGNORE)   Q                __________________________________________________________________                   PARAMETERSt'                                filespec M                                A valid VMS file specification of an SDML file O                                that contains a <GLOSSARY> section. No wildcards +                                are allowed.   Q                                __________________________________________________i                  restrictions   D                                o Input file must have <GLOSSARY> andL                                  <ENDGLOSSARY> if non-glossary text preceedsB                                  and follows the glossary section.  J                                o If no <ENDGLOSSARY> tag is available, theM                                  remainder of the input file, starting at thelP                                  first <GTERM> occurrence, is considered part of.                                  the glossary.  K                                o No <INCLUDE> tags are evaluated within thekM                                  glossary section: all glossary items to sorteJ                                  must be present in the source input file.  N                                o Tags for comment blocks and/or literal blocksI                                  are ignored. This may lead to unexpected N                                  results if comment blocks include or span oneM                                  or more <GTERM> tags. Comments on a glossaryeP                                  term should follow the <GTERM>, not preceed it.  Q                                                                                11o  <                                    Digital Internal Use Only                         DOCTOR/GLOSSARY          Q                                __________________________________________________                   prompts/                                File:   filespec_  Q                __________________________________________________________________                   DESCRIPTIONO                                DOCTOR/GLOSSARY scans through the input file andcK                                will sort the file part that starts with the N                                first <GTERM> tag occurrence, and ends with theQ                                <ENDGLOSSARY> tag. All text before this section orc?                                following it, remains untouched./  O                                The glossary terms are sorted in ASCII collatinglP                                sequence, where only the character ranges "A"-"Z"N                                and "0"-"9" are evaluated. Other characters areN                                ignored for the sorting process. Internally allP                                glossary terms are converted to uppercase. OutputO                                remains the same as specified in the input file.   Q                __________________________________________________________________                   QUALIFIERSl#                                /LOG K                                This qualifier result in additional messages N                                on the file being processed. By default no such<                                messages are issued (/NOLOG).  /                                /OUTPUT=filespecoJ                                This qualifier specifies the output file toN                                generate from the input file. When omitted, theO                                output file take will be the next higher versionoP                                of the input file. A warning message will then beP                                generated that the original file may be lost if a-                                purge is done.   -                                /SORT=keywordssL                                This qualifier determines the way the sort isP                                performed. One can either specify LETTER or WORD.O                                With LETTER all terms are sorted with spaces andhO                                hyphens as not significant. This is the default.iD                                WORD does treat those as significant.  O                                In addition one can specify the keyword NONALPHAi@                                with one of the following values:  M                                o NONALPHA=AFTER - all terms starting with nonnP                                  alphabetic characters are positioned at the end1                                  of the glossary.p                  12   <                                    Digital Internal Use Only         Q                                                                   DOCTOR/GLOSSARYm          N                                o NONALPHA=BEFORE - all terms starting with nonL                                  alphabetic characters are positioned at the6                                  start of the glossary  J                                o NONALPHA=IGNORE - all terms are sorted onN                                  their first alphabetic character. This is the)                                  default.s                                                                                    Q                                                                                13d  <                                    Digital Internal Use Only X  /                    DOCTOR/MESSAGE           Q                __________________________________________________________________s  K                DOCTOR/MESSAGE-Create SDML file from VMS Message definitionsC  J                                The DOCTOR/MESSAGE utility can create a VAXK                                DOCUMENT SDML file with explanation of error_N                                messages, from a properly coded VAX/VMS Message+                                source file._  Q                __________________________________________________________________t                  FORMAT   E                                DOCTOR/MESSAGE  filespec [/qualifiers]   Q                                __________________________________________________ =                                Command Qualifiers    Defaults   <                                /FAO                   /NOFAO=                                /HELP                  /NOHELP <                                /LOG                   /NOLOGC                                /OUTPUT                /OUTPUT=.SDML=  Q                __________________________________________________________________                   PARAMETERSe'                                filespec N                                A valid VMS file specification of a VMS MessageM                                definition file. Default file type is .MSG. No 5                                wildcards are allowed.4  Q                                __________________________________________________                   restrictions   P                                o It is assumed the input file has proper VAX/VMSJ                                  Message Utility syntax and will correctly)                                  compile.t  N                                o Comments describing the message should follow=                                  the message definition line.o  Q                                __________________________________________________r                  prompts/                                File:   filespect  Q                __________________________________________________________________                   DESCRIPTIONG                                DOCTOR/MESSAGE reads through the message L                                definition file and produces a SDML file fromP                                the comments that describe the messages. The SDMLP                                file can be included in any SDML source file that                  14D  <                                    Digital Internal Use Only 1  :    Q                                                                    DOCTOR/MESSAGEA          M                                is processed for the SOFTWARE family doctypes. M                                It will then produce a <HEAD1> section in that.O                                document, preferably as part of an appendix. ForR:                                full details see Chapter 4.  Q                __________________________________________________________________>                  QUALIFIERSE#                                /FAOuL                                When this qualifier is specified, the messageP                                string is written into the output .SDML file withP                                all specified FAO arguments unchanged. By defaultQ                                all FAO arguments are replaced by generic strings, E                                such as string for a !AS FAO argument.O  $                                /HELPM                                This qualifier will produce an .SDML file thatEQ                                can be processed for the HELP.MESSAGE doctype thateN                                is currently being developed by CUIP to produceK                                input files for the HELP/MESSAGE utility forCM                                Open VMS and Alpha VMS systems. The default isuP                                /NOHELP, resulting in a normal .SDML message fileN                                for insertion into a paper or online Bookreader,                                user's guide.  #                                /LOGNN                                This qualifier result in additional messages onK                                files being processed and output files being N                                created. By default no such messages are issued(                                (/NOLOG).  /                                /OUTPUT=filespectJ                                This qualifier specifies the output file toN                                generate from the input file. When omitted, theL                                output file take the same values as the inputL                                file, except for the file type, which becomesO                                .SDML. It is allowed to specify only a part of a N                                filespec. Missing fields default from the input=                                fields (except the type part).                     Q                                                                                15   <                                    Digital Internal Use Only I  r                    DOCTOR/ONLINE          Q                __________________________________________________________________f  =                DOCTOR/ONLINE-Modify SDML files for Bookreadera  L                                The DOCTOR/ONLINE scans through the specifiedP                                SDML source file and the files it references, forP                                correct syntax to be processed for the BOOKREADERO                                destination. This implies that symbols are added O                                to all unsymboled sections, tables, examples and '                                figures.   Q                __________________________________________________________________                   FORMAT.  D                                DOCTOR/ONLINE  filespec [/qualifiers]  Q                                __________________________________________________ =                                Command Qualifiers    Defaults   A                                /CONDITION            /NOCONDITION2F                                /DUMMY_SYMBOLS         /NODUMMY_SYMBOLS=                                /LIST                  /NOLISTE;                                /LOG                  /NOLOG J                                /OUTPUT                /OUTPUT=.SDML_ONLINE?                                /REMOVE                /NOREMOVEbA                                /SUPERSEDE            /NOSUPERSEDE C                                /SYMBOL_FILE          /NOSYMBOL_FILE B                                /VERSION_1             /NOVERSION_1  Q                __________________________________________________________________                   PARAMETERSn'                                filespeceO                                A valid VMS file specification of a VAX DOCUMENTsL                                source file. This can be a single file or theK                                profile file of a book. No wildcard allowed.   Q                                __________________________________________________                   restrictions'  N                                o It is assumed the input files have proper VAXO                                  DOCUMENT syntax and will correctly process for A                                  Mail, LN03 or PostScript output.   Q                                __________________________________________________                   prompts/                                File:   filespec_                  16   <                                    Digital Internal Use Only         Q                                                                     DOCTOR/ONLINE         Q                __________________________________________________________________                   DESCRIPTIONO                                DOCTOR/ONLINE scans through the specified source K                                file and its referenced files to ensure that M                                symbols are attached to all sectioning tags as L                                well as the Bookreader "pop up" items: table,O                                example and figure. Use the /VERSION_1 qualifier3M                                if the document is processed with VAX DOCUMENTmN                                V1.2B. A text file explaining what actions mustK                                be taken after processing can be obtained by 0                                specifying /LIST.  Q                __________________________________________________________________                   QUALIFIERS .                                /CONDITION=nameL                                This qualifier instructs DOCTOR to ignore anyJ                                conditional text block whose condition doesL                                not match the one specified. This will resultM                                in ignoring any symbol defined in those blocks L                                (and which hence will show up in the /LIST orP                                /DUMMY_SYMBOL specified files. It does not affectN                                generation of symbols to tags that require one.K                                All of those will get one, regardless of any 8                                condition set or removed.  :                                /DUMMY_SYMBOLS[=(keywords)]L                                This qualifier generates a file that containsH                                <DEFINE_SYMBOL> tags for each <REFERENCE>K                                tag that is used in the document that has nosQ                                definition. This way the document can be processediM                                successfully using DOCUMENT/SYMBOL=symbol_fileDQ                                until the references are written up by the authorss?                                or the reference itself removed.i  H                                If a symbol file for the document alreadyO                                exists, then the dummy symbol file generated can N                                include a reference to this file by inserting aN                                <INCLUDE>(symbol_filespec) tag in the generatedO                                dummy symbol file. This way you can use DOCUMENT O                                /SYMBOL=dummyfile to process the document, using L                                both the predefined symbols and the generated'                                symbols.O            Q                                                                                17   <                                    Digital Internal Use Only                         DOCTOR/ONLINE          N                                There are three keywords that can be specified:  N                                OUTPUT=filespec    Allows to specify the outputK                                                   file spec with the symbol_P                                                   definitions. When omitted, theO                                                   output file name is identical-L                                                   to the input file name andP                                                   file type .SDML_DUMMY_SYMBOLS.  G                                TEXT="text         Allows to specify therJ                                string"            replacement text for allL                                                   undefined references. WhenI                                                   omitted, it defaults to L                                                   <TAG>(reference\undefined_?                                                   symbol_name).f  O                                INCLUDE_SYMBOLS    When specified, the resultingcI                                                   dummy symbols file willeJ                                                   also contain a line withM                                                   <INCLUDE>(symbol_filespec).oI                                                   This is useful when thetL                                                   document is processed withI                                                   DOCUMENT /SYMBOL=dummy_ L                                                   filespec because this willJ                                                   read both the predefinedH                                                   symbols as well as theA                                                   generated ones._  0                                /LIST [=filespec]L                                When this qualifier is specified, a list fileK                                is produced, containing instructions of what L                                actions the author must undertake to make theO                                document truely ready for Bookreader processing. L                                Actions are instructions to create additionalO                                figure files, or adding sentences around created O                                <REFERENCE> tags. By default no list is created. O                                When no file specification is given, it defaults M                                to the input file spec, but with the file type .                                .ONLINE_ERRORS.  #                                /LOG N                                This qualifier result in additional messages onK                                files being processed and output files being N                                created. By default no such messages are issued(                                (/NOLOG).  /                                /OUTPUT=filespechK                                This qualifier specifies the output files tosM                                generate for the modified input. When omitted, Q                                the output files take the same values as the input L                                file, except for the file type, which becomes                  18   <                                    Digital Internal Use Only         Q                                                                     DOCTOR/ONLINE           Q                                .SDML_ONLINE. It is allowed to specify only a parteM                                of a filespec. Missing fields default from the Q                                input fields (except the type part). It is advised O                                either to specify only the disk and directory or Q                                the file type. It is discouraged to specify a file O                                name, as all output will then result in multiple >                                versions of the same file name.  &                                /REMOVEP                                This qualifier allows you to remove any generatedM                                symbols added by DOCTOR/ONLINE during previoustL                                processing. It executes only Pass 1 of DOCTORM                                /ONLINE and does not generate any new symbols. H                                This qualifier is mutually exclusive with*                                /SUPERSEDE.  )                                /SUPERSEDEmM                                This qualifier allows you to remove any DOCTORnN                                /ONLINE generated symbols from the document andM                                re-issue new ones. This enables you to combine O                                document elements that were previously processed N                                individually and therefore might have identicalO                                symbols defined in the sources which may lead to P                                multiple symbol definition errors during DOCUMENTO                                processing. This qualifier is mutually exclusivea*                                to /REMOVE.  4                                /SYMBOL_FILE=filespecQ                                Specifies that DOCTOR should also read a file thatrM                                contains symbol definitions that would be usedTO                                on the DOCUMENT command line through the /SYMBOLN)                                qualifier.   )                                /VERSION_1rP                                Specify this qualifier only for sources that mustP                                be processed with VAX DOCUMENT V1.2B. It inhibitsD                                <SUBHEAD*> tags to be given a symbol.                        Q                                                                                19_  <                                    Digital Internal Use Only                         DOCTOR/PS          Q                __________________________________________________________________   0                DOCTOR/PS-Modify PostScript files  H                                This utility allows to add blank pages toP                                PostScript files when required to have a balancedO                                set of odd/even pages. It also allows to replace Q                                the prolog part of a PostScript file or to produce L                                an alternative output file that consists of a/                                subset of pages.d  Q                ___________________________________________________________________                  FORMATr  G                                DOCTOR/PS  PostScript_file [/qualifiers]a  Q                                __________________________________________________r=                                Command Qualifiers    Defaults   =                                /BLANK[=filespec]     /NOBLANKlE                                /CHANGE_PROLOG        /NOCHANGE_PROLOG :                                /EXTRACT=range        None.=                                /[NO]FIGURES=keyword  /FIGURES D                                /LEADING_BLANK        NOLEADING_BLANK;                                /LOG                  /NOLOG V                                /OUTPUT=filespec      next higher version of input file:                                /PROLOG=filespec      None.:                                /NOPROLOG             None.>                                /SADDLE               /NOSADDLE;                                /2UP                  /NO2UP   Q                __________________________________________________________________                   PARAMETERS .                                PostScript_fileN                                Input file to be scanned through and to produceO                                an output file from. The file must adhere to the L                                Adobe minimal conformant conditions V2 or V3,O                                as described in the PostScript Reference Manual,pN                                published by Addison & Wesley. See Section 6.7.  Q                                __________________________________________________                   restrictions   F                                o Input file must be minimal conformant2                                  PostScript coded.                  20   <                                    Digital Internal Use Only         Q                                                                         DOCTOR/PS           F                                o Input file may not be an encapsulatedM                                  PostScript file: must have proper prolog and )                                  trailer.c  Q                __________________________________________________________________                   QUALIFIERSC0                                /BLANK[=filespec]Q                                This qualifier makes sure the output file consists I                                of a balanced set of odd and even pages toEK                                facilitate proper printing on a double sidedfP                                printing device. It will also append a blank pageN                                if the final page is odd. It will also prefix aO                                blank page if an extract range starts on an even P                                page or append a blank page if a range ends on an(                                odd page.  Q                                You can specify a file specification that containsTP                                a complete description of a blank page. This fileQ                                should not include the %%Page: comment, but shouldeM                                otherwise be complete in itself. If no file is Q                                specified, a simple blank page is produced through ?                                the showpage PostScript command.a  -                                /CHANGE_PROLOG.L                                This qualifier allows to replace the standardN                                prolog with one that defines an additional lineN                                at the top (header) and bottom (footer) of eachO                                page, as well as a faint grey diagonal text line M                                across the page. In addition these changes can_P                                be saved in a new prolog file to be created, thatN                                can be used in subsequent cases through /PROLOG)                                qualifier.   H                                The /CHANGE_PROLOG qualifier takes twelveP                                arguments, all optional, but at least one of them1                                must be specified:   I                                o TOP=text - specifies the text line to be N                                  printed as a header on each page. If the textO                                  contains blanks, the entire text string should ;                                  be within quotation marks.   L                                o BOTTOM=text - specifies the text line to beN                                  printed as a footer on each page. If the textO                                  contains blanks, the entire text string should/;                                  be within quotation marks.     Q                                                                                21   <                                    Digital Internal Use Only    O                    DOCTOR/PS          P                                o COUNTER=integer - specifies the starting numberL                                  to be printed on the bottom line, followingK                                  the text specified with BOTTOM. The number J                                  increments with each page and can be usedL                                  for numbering pages that would otherwise be,                                  unnumbered.  N                                o DIAGONAL=text - specifies the text line to beO                                  printed in a faint grey font diagonally acrosspP                                  each page and underlaying the text on the page.M                                  If the text contains blanks, the entire text'I                                  string should be within quotation marks.p  O                                o OUTPUT=filespec - If specified, the new prolog H                                  is also output as a separate file. ThisJ                                  file can be used in subsequent occassionsM                                  by inputting it through the /PROLOG=filespecs+                                  qualifier.   K                                o HSIZE=pointsize - If specified, determines M                                  the horizontal page width used to accomodate L                                  the top line. If omitted, A4 sized paper is)                                  assumed.   K                                o VSIZE=pointsize - If specified, determines K                                  the vertical page width used to accomodate O                                  the bottom line. If omitted, A4 sized paper is )                                  assumed."  O                                o PAGESIZE=papertype - This allows specification_N                                  of a particular standard sized papersheet. ItO                                  is mutually exclusive to both HSIZE and VSIZE.cN                                  The papersizes recognized are LETTER, LEDGER,M                                  LEGAL, EXECUTIVE, 7X9, 35MM, A5, A4, A3, B5,_3                                  B4, C6, C5 and C4._  K                                o BORDER - if specified the underlay page isTN                                  surrounded with a thin rectangle: the text isN                                  printed within this rectangle. The default is*                                  NOBORDER.  M                                o GRAYSCALE=number - If used, you must specifyaO                                  a number between 00 and 99. This is translatedcO                                  into a percentage (00-99%) indicating the greyiM                                  scale used for the diagonal text. A value ofmP                                  00 is black, 99 is almost white. If omitted, itN                                  defaults to 95%: a light grey text. Note thatN                                  you must enter a leading zero for percentagesK                                  01-09, as a simple "0." is prefixed to the L                                  number, making a "1" into "0.1" - i.e. 10%.                  22a  <                                    Digital Internal Use Only    d    Q                                                                         DOCTOR/PSe          L                                o FONT=fontname - If used, a valid PostScriptJ                                  font must be specified to be used for theI                                  top, bottom or diagonal line. For a fullfN                                  list of keywords see Table 6-1. When omitted,8                                  Helvetica-Bold is used.  N                                o SIZE=number - allows specification of the topL                                  and bottom line font size. When omitted, itN                                  defaults to 15 points. Values above 20 points<                                  are pointless, but allowed.  L                                The /PROLOG and /CHANGE_PROLOG qualifiers are2                                mutually exclusive.  -                                /EXTRACT=range N                                This qualifier allows to copy a subset of pagesO                                from the original file into the output file. The P                                range can be specified by giving the start of theP                                range (compulsory) and either the number of pagesO                                to copy from there onwards or the page number of M                                the final page. For this purpose the qualifier 5                                takes three arguments:i  J                                o START=folio - specifies the starting pageN                                  number. E.g. III or 4-6 or INDEX-6. The validL                                  numbers are those that are available in theJ                                  input PostScript file. If uncertain, do a  J                                          $ SEARCH postscript_file  %%Page:  L                                  command to see which page folio numbers areJ                                  available. Do not specify the opening andI                                  closing parenthesis if the folio numbers K                                  are surrounded by these. (Adobe V3 comment 1                                  standards only).u  O                                o END=folio - specifies the last page of a rangeaM                                  of pages to be printed. A valid folio numberbM                                  must be specified, otherwise the DOCTOR willlP                                  include all remaining pages upto the end of the&                                  file.  O                                o NUMBER=integer - specifies the number of pages M                                  to extract from the specified starting folio K                                  onwards. If this number is larger than the P                                  remaining number of pages, the rest of the file+                                  is copied.   L                                Either END or NUMBER must be present. If bothN                                are present, the shortest range span from START  Q                                                                                23   <                                    Digital Internal Use Only B  r                    DOCTOR/PS          O                                to either END or NUMBER is taken. If neither are Q                                present, the remainder of the file, from the START 8                                folio onwards, is copied.  M                                The EXTRACT qualifier can be specified several O                                times to allow for several ranges to be included 7                                in the same output file.   +                                /[NO]FIGURES M                                This qualifier allows manipulation of properly L                                inserted encapsulated PostScript figures. TheP                                /NOFIGURES qualifier removes the figures from theM                                input file. The /FIGURES (default) leaves them Q                                untouched. By adding the keyword EXTRACT to either P                                /FIGURE or /NOFIGURE the figures are written intoP                                separate figure files as encapsulated PostScript.P                                They receive their original names (displayed whenL                                /LOG is specified). If also the keyword PAGE_Q                                NUMBER is specified, the figures get the same file O                                name as the input file, but with the page numbernP                                appended to it. This allows for easy reference ofG                                the figure to the printed document page.r  1                                /[NO]LEADING_BLANKtN                                This qualifier will produce a blank page beforeK                                the actual document starts. This is required L                                when the PostScript output file is to be usedO                                for reduced size printing (with 2 document pagesEJ                                on a single side of a sheet of paper). ThisN                                qualifier is only required when the output fileK                                is to include the first page of the document P                                also. Default is /NOLEADING_BLANK. The blank pageP                                produced does not use a user-specified blank pageF                                file that can be specified with /BLANK.  '                                /[NO]LOG Q                                Outputs informational messages on blank pages that/,                                are inserted.  /                                /OUTPUT=filespec N                                Specifies the output file that will be created.O                                If omitted, the next higher version of the inputhN                                file is created and a message is issued to warnQ                                the user not to purge (which deletes the original,n.                                complete file).                        24i  <                                    Digital Internal Use Only t  R    Q                                                                         DOCTOR/PS           /                                /PROLOG=filespec K                                Specifies the text of the prolog part of theTJ                                output PostScript file. When specified, theO                                original prolog part is removed and the contents K                                of the specified file is included. This filerL                                must be complete and adhere to the PostScriptP                                conformant style (see Section 6.7. The final lineQ                                should be %%EndProlog. A simple prolog file, using Q                                a header, footer and diagonal line, can be createdtD                                through the /CHANGE_PROLOG qualifier.  K                                If /NOPROLOG is specified, the entire prolog H                                is omitted from the output file. This wayK                                one can include the output file into another I                                PostScript file, e.g. through the <FIGURE_ M                                FILE>(ps\filespec\size) tag. In this case, the O                                output file type is defaulted to .EPS instead of #                                .PS.f  L                                The /PROLOG and /CHANGE_PROLOG qualifiers are2                                mutually exclusive.  &                                /SADDLEN                                The use of this qualifier is mutually exclusiveL                                with all others that are allowed with the /PSP                                qualifier. It allows to re-order pages inside theN                                PostScript file for differently ordered output.K                                This output can be used to produce brochures J                                by folding pages in the middle (to become aM                                signature) and saddle stich them or by drivingNM                                a staple through the spine. This requires that J                                printing is done with two pages on a singleP                                sheet side. For more information see Section 6.6.4                                Default is /NOSADDLE.  C                                Allowed qualifiers with /SADDLE are:   N                                /LOG           Produce additional output duringL                                               processing. Default is /NOLOG.  P                                /OUTPUT=filespeSpecify output file specification.P                                               Default is the next higher version?                                               of the input file             Q                                                                                25e  <                                    Digital Internal Use Only                         DOCTOR/PS          P                                /GATHER=number Number must be a multiple of 4. ItO                                               indicates the range of pages that P                                               are printed as a single signature.L                                               When not specified it defaultsK                                               to the number of pages in the >                                               PostScript file.  #                                /2UPaL                                For PostScript files produced by VAX DOCUMENTL                                V2.1 it is possible to insert additional codeP                                that allows you to print the file on double sizedP                                paper (e.g. A3) with two pages on a side (eg. twoO                                A4 pages). This only works for VAX DOCUMENT V2.1 O                                produced PostScript files and the qualifier must E                                be specified following the /PS/SADDLE.   Q                __________________________________________________________________   O                EXAMPLES        The next example shows how blank pages are added   O                                to an existing PostScript file and the result is 7                                copied into BALANCED.PS.n  B                1   $DOCTOR/PS  myfile.PS /BLANK/OUTPUT=balanced.PS  N                                The following example shows the production of aM                                file that contains only the table of contents, O                                5 pages of Chapter 2 and the Index (which is the P                                final part of the book) of an existing PostScriptH                                file. Blank files are added where needed.  D                2   $DOCTOR/PS book.ps /EXTRACT=(START=III,END=XIV) -  I                                          /EXTRACT=(START=2-1, NUMBER=5) -eC                                          /EXTRACT=(START=INDEX-1) -oB                                          /OUTPUT=SUMMARY.PS /BLANK  N                                The following example shows the production of aN                                file that has a bottom line added "Internal UseN                                Only - Rev. B" and diagonal text "Review Only",L                                which is printed with a 90% grey scale (lightK                                grey. 00 would be black, 99 almost invisibly &                                white).                            26P  <                                    Digital Internal Use Only n       Q                                                                         DOCTOR/PSd          '                3   $DOCTOR/PS book.ps -p  O                                          /CHANGE=(BOTTOM="Internal Use Only", -oK                                                   DIAGONAL="Review Only", -hA                                                   GRAYSCALE=90) -iB                                          /OUTPUT=SUMMARY.PS /BLANK  K                                The next example shows how a 29 page book is L                                converted into a 32 page booklet at half sizeP                                by printing it on an LPS20 with two pages on each5                                side and double sided:   I                4   $DOCTOR/PS/SADDLE book.ps /GATHER=32/OUTPUT=booklet.PS   P                    $PRINT/QUEUE=LPS20/PARAMETER=(DATA=POST,NUMBER=2,SIDE=TUMBLE)                                                                    Q                                                                                27f  <                                    Digital Internal Use Only B  O                    DOCTOR/SDML          Q                __________________________________________________________________f  0                DOCTOR/SDML-Markup Files Included  N                                The DOCTOR/SDML, scans through the VAX DOCUMENTO                                source files for other sources included by them, O                                upto a nesting level of 20. These included filesaN                                can be VMS files or CMS elements, if DEC/CMS isQ                                installed on the system. These files can be any ofdP                                the ones normally accepted through standard tags.  M                                It reports the document structure as a commentsJ                                block in the source file and can produce anJ                                MMS build file as well as a list of all the9                                occurrences of index tags.   Q                __________________________________________________________________r                  FORMAT   B                                DOCTOR/SDML  filespec [/qualifiers]  Q                                __________________________________________________ =                                Command Qualifiers    DefaultsV  ;                                /CMS[=generation]     /NOCMS q                                /DOCTYPE=doctype      /DOCTYPE=(PAPER=REPORT, ONLINE=SOFT.ONLINE, MANPAGE=MANPAGE)tf                                /DESTINATION=destinatiodefaults: LN03, PS, BOOKREADER, ROFF, MAIL, LINE?                                /IGNORE=(options)      /NOIGNORE ?                                /INCLUDE=filespec     /NOINCLUDE =                                /INDEX=filespec       /NOINDEXE<                                /LOG                   /NOLOG;                                /MMS[=filespec]       /NOMMS L                                /OUTPUT=filespec       /OUTPUT=input_filespecC                                /RANDOM_TEXT          /NORANDOM_TEXT ;                                /RULES                /RULES   Q                __________________________________________________________________                   PARAMETERSe'                                filespec L                                A valid VMS file specification. Wildcards areK                                allowed. In that case all files matching theaH                                specification are processed individually.  Q                                __________________________________________________h                  restrictions   P                                o The specified file specification on the commandJ                                  line must be a normal VMS filespec. If itP                                  resides in CMS, you need to fetch it from there                  28   <                                    Digital Internal Use Only         Q                                                                       DOCTOR/SDML           L                                  first. Any file referenced by the specifiedL                                  file will be fetched by DOCTOR/SDML itself.  K                                o If DEC/CMS is not installed on your system P                                  DOCTOR/SDML can only inspect VMS files, not CMS<                                  elements. See also Preface.  D                                o DOCTOR/SDML cannot inspect any .STTM                                  (precompiled tag definition) file due to the D                                  compressed tag definitions in those  M                                o Filespecs must be explicit. DOCTOR/SDML will P                                  not recognize filespecs that are defined withinO                                  a symbol and refered to by <REFERENCE>(symbol) &                                  tags.  P                                o DOCTOR/SDML will notice <INCLUDE_TEX_FILE> tagsN                                  but will not process any of the specified TeX'                                  files.   Q                                __________________________________________________                   prompts/                                File:   filespec   Q                __________________________________________________________________                   DESCRIPTIONK                                DOCTOR/SDML reads the specified VAX DOCUMENTfP                                source file and scans for those tags that includeP                                other files. These tags are <ELEMENT>, <INCLUDE>,M                                <FIGURE_FILE>,<INCLUDE_TEX_FILE>, <ICON_FILE>,-P                                <EXAMPLE_FILE>, <TABLE_FILE> and <INCLUDES_FILE>.P                                The tags introduced in VAX DOCUMENT V1.1 are alsoO                                supported: <FILE_SPEC> and <MEMO_FILE>. When the O                                qualifier /INDEX is specified, it also looks for +                                <X> and <Y>.n  K                                It will then open those files and repeat thesN                                process, upto 20 levels deep. When finished, itO                                will write a special comment header at the start N                                of the source file, indicating the structure ofL                                the document and the files it refers to. WhenM                                DOCTOR/SDML is run several times over the same M                                file, this comment block is refreshed, if left H                                unmodified by the user (it recognizes the  M                                If DEC/CMS is used on your system, DOCTOR/SDML P                                can also attempt to look up the included files inL                                your current CMS libraries if you specify theK                                /CMS qualifier. If a generation or CMS class   Q                                                                                29.  <                                    Digital Internal Use Only r  e                    DOCTOR/SDML          N                                is specified, only elements that belong to that8                                generation are looked up.  M                                Apart from information inside the source file,oN                                it can also generate a description file for MMSP                                to process the file scanned through or any of its%                                parts.   Q                __________________________________________________________________                   QUALIFIERS 4                                /[NO]CMS[=generation]N                                Using this qualifier will urge DOCTOR/SDML alsoQ                                to look into your currently set CMS library if any N                                of the files specified in the SDML source filesL                                cannot be found in the specified directories.Q                                After inspections, these fetched files are deleted Q                                again. The ones found in CMS are marked with "(CMS ?                                Library)" in the comment header.   M                                It only looks into CMS for included files: therN                                "main" source file you specified on the commandQ                                line must exist as file in your directory and will_P                                not be fetched from CMS. Default value is /NOCMS.  M                                If the error message %MARFIN-F-NOCMSSUP occurseO                                when /CMS is specified, it means that DEC/CMS is P                                not installed or available for use on the system.+                                See Preface.N  N                                If with /CMS you also specify a CMS class name,K                                then DOCTOR/SDML will only look into the CMS N                                library for elements that belong to this class.P                                In all other cases, the required file is reported,                                as not found.  +                                /DESTINATION I                                This qualifier accepts four keywords, each N                                allowing to modify the default destination used7                                for DOCUMENT processing:n  P                                o BOOKREADER= . Defaults to BOOKREADER for online-                                  destinationsc  I                                o POSTSCRIPT= . Defaults to POSTSCRIPT for 8                                  PostScript destinations  O                                o LN03= . Defaults to LN03 for LN03 destinations   O                                o MAIL= . Defaults to MAIL for MAIL destinationst                  30   <                                    Digital Internal Use Only r  r    Q                                                                       DOCTOR/SDMLu          M                                o LINE_PRINTER= . Defaults to LINE_PRINTER forn:                                  line printer destinations  O                                o ROFF= . Defaults to ROFF for Roff destinationsy  L                                If more than one destination is modified, theK                                individual keywords are separated by commas.   '                                /DOCTYPEeL                                You can specify the type of document to buildO                                for paper or online destinations. It takes threer(                                keywords:  O                                o PAPER= . Accepts any valid paper doctype name. 4                                  Defaults to REPORT.  K                                o ONLINE= . Accepts any valid online doctypeiB                                  name. Defaults to SOFTWARE.ONLINE  M                                o MANPAGE= . Accepts any valid manpage doctypeg:                                  name. Defaults to MANPAGE  5                                /IGNORE=(keyword-list) L                                When specified, DOCTOR will also scan certainK                                blocks of text that are normally ignored. By N                                default any <COMMENT> or <LITERAL> block is notJ                                scanned for file inclusion tags. SpecifyingM                                /IGNORE will allow you to force DOCTOR to scan L                                one or both of these block types. The allowedQ                                option keywords are LITERAL and COMMENT. When bothuP                                are specified, they must be separated by a comma:9                                /IGNORE=(COMMENT,LITERAL).e  0                                /INCLUDE=filespecQ                                Specifies an MMS include file that allows the user N                                to specify additional rules, macros or symbols.P                                Results in a .INCLUDE line in the MMS description$                                file.  .                                /INDEX=filespecK                                Instructs DOCTOR/SDML also to produce a file Q                                containing all the index tags, together with their K                                occurrence (file spec and line within file).   '                                /[NO]LOGiP                                This outputs additional informational messages onQ                                each included file during the processing of DOCTOR 8                                /SDML. Default is /NOLOG.  Q                                                                                31   <                                    Digital Internal Use Only                         DOCTOR/SDML          2                                /[NO]MMS[=filespec]P                                This generates an MMS description file to rebuildL                                the document. This file has the same filenameO                                as the source file processed, but with file type P                                .MMS. A filespec specified to this qualifier willP                                take precedence. You should not specify filenamesK                                and/or types if the input file specificationg2                                contains wildcards.  /                                /OUTPUT=filespec P                                When specified it will produce the new version ofO                                the SDML file (that will contain the DOCTOR/SDML Q                                header) as the specified filespec. When omitted, a O                                new version of the input file parameter is made.EP                                Note that when wildcard input file specificationsO                                are used one should not specify filenames and/or %                                types..  +                                /RANDOM_TEXT M                                Adds some additional random text to the /INDEX N                                produced output to allow processing of the fileN                                by VAX DOCUMENT without running into TeX memoryN                                exceeded errors. Only valid in combination with&                                /INDEX.  %                                /RULES O                                Specifying /NORULES suppresses the generation of P                                MMS suffixes and default action rules to retrieveQ                                elements from CMS libraries. By default, /RULES isf$                                used.                                                      32n  <                                    Digital Internal Use Only o  h    Q                                                                  DOCTOR/TAG_COUNTb          Q                __________________________________________________________________e  ;                DOCTOR/TAG_COUNT-Count all tags in SDML fileT  J                                The DOCTOR/TAG_COUNT utility counts all tagP                                constructs inside an SDML document. This documentN                                may be a complete book (profile plus elements).Q                                It reports the counted tags in the produced output $                                file.  Q                __________________________________________________________________                   FORMATy  G                                DOCTOR/TAG_COUNT  filespec [/qualifiers]l  Q                                __________________________________________________ =                                Command Qualifiers    Defaults   H                                /OUTPUT                /OUTPUT=.TAG_COUNT<                                /LOG                   /NOLOG  Q                __________________________________________________________________                   PARAMETERS '                                filespec"Q                                A valid VMS file specification of an SDML file. No P                                wildcards are allowed. File may be the profile ofJ                                the book and may refer to other SDML files.  Q                                __________________________________________________                   restrictionsk  L                                o Any tag-like construct is seen and counted,N                                  including those inside <COMMENT> or <LITERAL>(                                  blocks.  Q                                __________________________________________________T                  prompts/                                File:   filespec   Q                __________________________________________________________________                   DESCRIPTIONQ                                DOCTOR/TAG_COUNT scans through the specified inputCM                                SDML file and all its referenced SDML files to_Q                                count all tags. Tags are any consecutive number of O                                alphabetic or numeric characters or underscores, K                                surrounded by angle brackets. It reports its K                                findings in the output file. For details see )                                Chapter 8.i  Q                                                                                33y  <                                    Digital Internal Use Only e  e                    DOCTOR/TAG_COUNTt        Q                __________________________________________________________________                   QUALIFIERSo#                                /LOG N                                This qualifier result in additional messages onQ                                files being processed. By default no such messages_3                                are issued (/NOLOG)._  /                                /OUTPUT=filespec J                                This qualifier specifies the output file toN                                generate from the input file. When omitted, theL                                output file take the same values as the inputL                                file, except for the file type, which becomesO                                .TAG_COUNT. It is allowed to specify only a part M                                of a filespec. Missing fields default from the C                                input fields (except the type part).I                                                                                    34   <                                    Digital Internal Use Only         Q                                                                       DOCTOR/XREF           Q                __________________________________________________________________   7                DOCTOR/XREF-List cross reference symbolsM  M                                The DOCTOR/XREF utility enables you to produce N                                a file with <DEFINE_SYMBOL> tags of all symbolsL                                defined within a book, derived from its .XREF$                                file.  N                                It also enables you to produce a listing of allO                                symbols, sorted alphabetically or by symbol typed<                                (chapter, table, example etc)  Q                __________________________________________________________________                   FORMATs  G                                DOCTOR/XREF  xref_filespec [/qualifiers]   Q                                __________________________________________________i=                                Command Qualifiers    Defaults   @                                /ALPHABETIC           /ALPHABETIC9                                /BOOKTITLE            none <                                /FULL                 /NOFULL=                                /LIST                  /NOLIST <                                /LOG                   /NOLOG=                                /NUMERIC              /NUMERICsD                                /SYMBOL_FILE           /NOSYMBOL_FILE:                                /PREFIX                none<                                /SORT                 /NOSORTD                                /SYSTEM_SYMBOLS       /SYSTEM_SYMBOLS<                                /TEXT                 /NOTEXT;                                /VALUE                /VALUEo  Q                __________________________________________________________________                   PARAMETERS ,                                xref_filespecN                                A valid VMS file specification of a .XREF crossN                                reference file, produced by VAX DOCUMENT duringK                                a book built. Default file type is .XREF. No 5                                wildcards are allowed.   Q                                ___________________________________________________                  restrictions_  O                                o It is assumed the input file is a proper .XREF >                                  file produced by VAX DOCUMENT  Q                                                                                35C  <                                    Digital Internal Use Only                         DOCTOR/XREF          M                                o At least one of the qualifiers /SYMBOL_FILE,>M                                  /LIST or /SORT must be specified in order to<E                                  have DOCTOR/XREF perform any action.E  Q                                __________________________________________________U                  prompts/                                File:   filespecn  Q                __________________________________________________________________d                  DESCRIPTIONJ                                DOCTOR/XREF inspects a valid DOCUMENT .XREFN                                file produced during a bookbuild operation of aO                                multiple file document. It allows the productiontM                                of either a file where all symbols are defined O                                once more explicitly to allow you to incorporatemJ                                those symbols into another set of documentsN                                and enable cross referencing between books. TheG                                qualifier /SYMBOL_FILE is then required.u  K                                In addition it allows you to produce tabularEL                                listing of all symbols defined in a document,L                                for reference by the author or writers. TheseO                                tables are generated as .SDML files with <TABLE>ML                                constructs that can subsequently be processedP                                individually by DOCUMENT using the REPORT doctype%                                style.e  Q                __________________________________________________________________e                  QUALIFIERSt*                                /ALPHABETICJ                                Only valid when also /SORT is specified. ItM                                indicates whether the sorted listing should be Q                                ordered by symbol name or by the object or sectionnO                                number. When none is specified, /SORT/ALPHABETIC Q                                is assumed. To get both features in one file, both <                                also /SORT must be specified.  2                                /BOOKTITLE="string"N                                A quoted string specifying the name of the bookN                                from which the cross reference file originates.J                                This text is used during referencing of theM                                symbols, to output e.g. "See The Life of BriansH                                Chapter 4, Mothers..." The text specifiedJ                                is defined as a symbol prefix_BOOK to allowN                                references to it. The prefix is set by /PREFIX.:                                Default is an empty string.                  36n  <                                    Digital Internal Use Only         Q                                                                       DOCTOR/XREFn          $                                /FULLK                                Defines the symbol value to consist of name,cM                                number and full text (e.g. Chapter 4, Where itCQ                                all happens). Default is /NOFULL. See also /VALUE.s  /                                /LIST[=filespec] N                                Specifies the filespec of a normal VAX DOCUMENTM                                file in which all symbols defined in the .XREF K                                input file are listed in alphabetical order..P                                This output can be processed through VAX DOCUMENTL                                and used by authors and writers for their ownP                                reference. When no filespec is given, it defaultsK                                to the same name as the input file, but withtN                                filetype .SDML_SYMBOL_LIST. Default is /NOLIST.  #                                /LOG.Q                                Outputs additional informational messages. Default )                                is /NOLOG.P  '                                /NUMERIC J                                Only valid when also /SORT is specified. ItM                                indicates whether the sorted listing should be Q                                ordered by symbol name or by the object or section Q                                number. When omitted, /SORT/ALPHABETIC is assumed. P                                To get both features in one file, both qualifiers1                                must be specified.D  /                                /PREFIX=filespec Q                                A short string to prefix to all symbols defined infP                                the input file to make them unique. If omitted noQ                                prefix is used, but symbols from several books mayrQ                                have been defined identically, causing referencing C                                conflicts. A warning is then issued.   /                                /SORT[=filespec]sN                                Similar to /LIST. All symbols are again listed,M                                but now grouped by their class (figure, table, J                                chapter etc). When no filespec is given, itN                                defaults to the same name as the input file but?                                with filetype .SDML_SYMBOL_TYPE.   6                                /SYMBOL_FILE[=filespec]M                                Specifies the output filespec of the file that P                                will contain all the <DEFINE_SYMBOL> definitions.N                                If the filespec is omitted, it defaults to yourP                                current directory, with filename identical to theD                                input file, but file type .SDML_XREF.    Q                                                                                37   <                                    Digital Internal Use Only h                       DOCTOR/XREF          .                                /SYSTEM_SYMBOLSI                                For its own use, DOCUMENT also generates ayM                                number of symbols (like highest section number,M                                in document, page prefix, online chunk). These L                                are normally not of interest for the user andK                                therefore omitted in the DOCTOR/XREF output. N                                Specifying /SYSTEM_SYMBOLS also includes those.<                                Default is /NOSYSTEM_SYMBOLS.  $                                /TEXTN                                Defines the symbol value to consist of the textK                                part of the symbol only. (e.g. "Where it all I                                happens"). Default is /NOTEXT. See /VALUE.   %                                /VALUE N                                Defines the symbol value to consist of the nameN                                and value number only (e.g. Chapter 4). This isM                                the default if no /TEXT or /FULL is specified.                                                                               38   <                                    Digital Internal Use Only D  O                Q                __________________________________________________________________           A       Error messagesn      Q                __________________________________________________________________e          A.1     DOCMSG Messages  .                     CREATED,  Created 'string'  .                        Severity: INFORMATIONAL  L                        Explanation: Indicates the successful creation of the-                        output file specified.   )                        User Action: None.t  I                     PASS1,  Start Pass 1: Read all messages and sort them *                             alphabetically  .                        Severity: INFORMATIONAL  J                        Explanation: Scans through the source .MSG file and6                        registers all messages defined.  )                        User Action: None.p  ?                     PASS2,  Start Pass 2: Generate message file   .                        Severity: INFORMATIONAL  M                        Explanation: Using the information gathered in Pass 1, L                        the output SDML file with messages is constructed forM                        each facility and each messages output in alphabetical                         order.d  )                        User Action: None.   Q                __________________________________________________________________           A.2     DOCTOR Messages  =                     IDENT,  This is 'string' version 'string'   .                        Severity: INFORMATIONAL  P                        Explanation: Indicates the current version of the utilityN                        that is invoked. This is important when bugs and wishes=                        are expressed to the development team.i  K                        User Action: Specify number when submitting SPR's ors                        QAR's.   Q                                                                               A-13  <                                    Digital Internal Use Only                         Error messages           H                     NOTIMPL,  Functionality 'string' not yet implemented  .                        Severity: INFORMATIONAL  J                        Explanation: The specified functionality is not yetP                        implemented, even though the command interface is already                        present.t  ?                        User Action: Wait till the next release.   Q                     SENDQAR,  Internal error. Please send QAR. Error ID: 'string'   .                        Severity: INFORMATIONAL  K                        Explanation: You managed to give a set of input data_K                        that caused the utility program to go to "catch all" ?                        statements that should never be reached.f  O                        User Action: Please notify the developers by SPR or QAR,_M                        describing the error and specifying the version of the O                        software used, the error messages displayed and possibly K                        a sample of the input files that caused the error to_L                        occur, together with the specified command statement.  Q                __________________________________________________________________v  !        A.3     DTAGCOUNT MessagesL  .                     CREATED,  Created 'string'  .                        Severity: INFORMATIONAL  L                        Explanation: Indicates the successful creation of the-                        output file specified._  )                        User Action: None.r  N                     FNF,  File 'string' is referenced in document but does not-                           exist - will ignorec  (                        Severity: WARNING  J                        Explanation: Indicates that the document contains aM                        <INCLUDE> or <INCLUDES_FILE> or <ELEMENT> tag refering P                        to a file that currently does not exist at that location.  P                        User Action: Make file available or correct the SDML fileN                        by removing the reference to it. The DOCTOR/TAG utilityG                        will ignore this file in its counting procedure.s                  A-2  <                                    Digital Internal Use Only         Q                                                                    Error messages           ,                     SCAN,  Scanning 'string'  .                        Severity: INFORMATIONAL  I                        Explanation: Indicates the current SDML file beingrC                        processed in the search for tags used in it.   )                        User Action: None.   Q                __________________________________________________________________            A.4     GLOSSARY Messages  .                     CREATED,  Created 'string'  (                        Severity: SUCCESS  N                        Explanation: Indicates the successful completion of theM                        utility and the creation of the specified output file.d  )                        User Action: None.   N                     DUPLICATE,  Duplicate entry for <GTERM> ''string'' in file  &                        Severity: FATAL  L                        Explanation: The SDML file that contains the glossaryN                        contains multiple identical entries defined by <GTERM>.5                        This makes sorting impossible.   J                        User Action: Remove duplicates or combine them to aO                        single <GTERM> entry with a <LIST>(numbered) to indicate :                        the different meanings of the word.  J                     GTERMOUTBOUND,  Found <GTERM> tag outside <GLOSSARY> -7                                     <ENDGLOSSARY> range   &                        Severity: FATAL  N                        Explanation: DOCTOR found <GTERM> tags ouside the validM                        range of <GLOSSARY> and <ENDGLOSSARY>. This is invalid E                        for DOCUMENT and also unacceptable for DOCTOR._  K                        User Action: Move the <GTERM> tags inside the proper &                        glossary block.  Q                     NEXTGLOSSARY,  Multiple <GLOSSARY> tags encountered. Can only>1                                    sort one block   &                        Severity: FATAL  K                        Explanation: Several <GLOSSARY> tags are encountered K                        in the specified input file. Because DOCTOR can onlys  Q                                                                               A-3p  <                                    Digital Internal Use Only _  _                    Error messages_          K                        sort a single block between the first <GLOSSARY> andeM                        <ENDGLOSSARY> tag, the current file is not acceptable._  N                        User Action: Combine both glossary blocks into a singleJ                        one or split them into two or more files, which areL                        included by <INCLUDE> into the final document. DOCTORL                        can sort each one of the glossary files individually.  F                     NOALPHA,  Found term "'string'" without alphabeticJ                               characters. Do not use /SORT=NONALPHA=IGNORE  &                        Severity: FATAL  K                        Explanation: The sorting process is conducted either G                        explicitly or by default to ignore nonalphabetic F                        characters. The current term consists solely ofO                        nonalphabetic characters and can therefore not be sorted (                        as a null string.  J                        User Action: Specify /SORT=NONALPHA=BEFORE or AFTERL                        to allow the term to occur at the start or end of the@                        glossary. Alternatively, remove the term.  F                     NOENDGLOSSARY,  No closing <ENDGLOSSARY> tag found  (                        Severity: WARNING  M                        Explanation: During the scanning of the input file, no 3                        <ENDGLOSSARY> tag was found.   G                        User Action: Add <NOGLOSSARY>. Or ignore, if the L                        glossary items are included via an <INCLUDE> tag thatN                        is positioned between the <GLOSSARY> and <ENDGLOSSARY>.  N                     NOGLOSSARY,  Opening tag <GLOSSARY> not found before first,                                  <GTERM> tag  (                        Severity: WARNING  I                        Explanation: DOCTOR discovered a <GTERM> without as,                        preceding <GLOSSARY>.  H                        User Action: None. User may wish to check whetherF                        elsewhere in the document the tag <GLOSSARY> isM                        specified. There must be one if this document is to be_;                        processed correctly by VAX DOCUMENT.F                      A-4  <                                    Digital Internal Use Only _  _    Q                                                                    Error messages           G                     NOGTERMS,  Input file does not contain <GTERM> tagsu  &                        Severity: FATAL  L                        Explanation: The SDML input file does not contain any.                        <GTERM> tag to sort on.  O                        User Action: Check on use of proper file or add glossaryo                        terms  N                     SAMEFILESPEC,  Output file is next higher version of input(                                    file.7                        Purging will lose original file.B  (                        Severity: WARNING  J                        Explanation: You did not specify an explicit outputI                        file, hence the utility defaults to the input file M                        specification. However, this may cause the lost of the L                        original input file is an accidental purge command is                        issued.  O                        User Action: Rename the latest version into another fileDP                        name or copy the file to another location to avoid losing)                        the original copy._  Q                __________________________________________________________________           A.5     MARFIN Messages  -                     ATLAST,  Created 'string's  .                        Severity: INFORMATIONAL  N                        Explanation: Indicates the creation of a new version ofN                        the main VAX Document file Marfin has finished reading.  (                        User Action: None  .                     CREATED,  Created 'string'  .                        Severity: INFORMATIONAL  N                        Explanation: Indicates the successful completion of theM                        utility and the creation of the specified output file.   )                        User Action: None.     Q                                                                               A-5T  <                                    Digital Internal Use Only                         Error messages           A                     FNF,  File 'string' referenced, but not foundt  (                        Severity: WARNING  K                        Explanation: In trying to locate all files that wererM                        referenced by the document, the indicated number coulduK                        not be found. In the comment header of the SDML file L                        specified on the command line, you can see which ones                         they are.  M                        User Action: Either remove the indicated references or :                        retrieve/create the files required.  G                     HUMANS,  Humans - always giving the wrong commands.i5                        Marfin do this, Marfin do thatt  &                        Severity: FATAL  L                        Explanation: Invalid DCL parameters or combination of-                        qualifiers were given.   L                        User Action: Specify a correct command line. Read the                        manual!  &                     IGNORED,  'string'  (                        Severity: WARNING  K                        Explanation: At the command line two definitions foraK                        the same entity are made (e.g. destination specifiedhI                        with /DESTINATION as well as for the document type L                        /POSTSCRIPT). In this case the message indicates what"                        is ignored.  P                        User Action: Remove one of the conflicting definitions or.                        accept the set default.  ?                     MMSTOO,  Made MMS description file 'string'   .                        Severity: INFORMATIONAL  H                        Explanation: Indicates Marfin also created an MMSG                        description file to automate the building of the /                        VAX Document source filee  @                        User Action: None. Use this file with MMS,                        /DESCRIPTION=file.MMS                    A-6  <                                    Digital Internal Use Only m       Q                                                                    Error messages           %                     MUMBLE,  'string's  .                        Severity: INFORMATIONAL  F                        Explanation: Marfin is having one of his moods.  O                        User Action: Bear with dignity after all the work he did                         for you  M                     NOCMSSUP,  DEC/CMS not available. Reissue command withoute#                                /CMS   &                        Severity: FATAL  J                        Explanation: DOCTOR/SDML could not find the DEC/CMSL                        product library and therefore assumes this product is4                        not installed on your system.  H                        User Action: Reissue the command without /CMS. InM                        addition, you may want to install (after purchase) DEC J                        /CMS as version management system for your documentO                        files. After that, DOCTOR/SDML/CMS will operate on these %                        libraries too._  I                     NOTFOUND,  There were 'unsigned decimal number' fileseA                                referenced that could not be foundc  (                        Severity: WARNING  K                        Explanation: In trying to locate all files that were M                        referenced by the document, the indicated number could K                        not be found. In the comment header of the SDML file L                        specified on the command line, you can see which ones                         they are.  M                        User Action: Either remove the indicated references ors:                        retrieve/create the files required.  )                     OHMYDIODES,  'string'n  &                        Severity: FATAL  @                        Explanation: Internal programming errors.  P                        User Action: Please submit bug report to IJSAPL::KLERK or*                        Theo de Klerk @UTO.  <                     OHNO,  I won't enjoy processing 'string'  .                        Severity: INFORMATIONAL  O                        Explanation: Indicates the main VAX Document file Marfin $                        tries to read  (                        User Action: None  Q                                                                               A-7   <                                    Digital Internal Use Only m                       Error messages         Q                __________________________________________________________________           A.6     ONLINE Messages  <                     CREATED,  Created modified file 'string'  .                        Severity: INFORMATIONAL  P                        Explanation: The modified input file(s) is written out as                         new file.  )                        User Action: None._  8                     CRELIST,  Created list file 'string'  .                        Severity: INFORMATIONAL  O                        Explanation: The list input file with actions to perform "                        is written.  M                        User Action: Read the file and comply with the actionsh!                        suggested.   O                     FNF,  File to include 'string' not found - will be ignored.e  (                        Severity: WARNING  M                        Explanation: A <ELEMENT> or <INCLUDE> specifies a file I                        that must be included in the document, and as suchEM                        would also be inspected by DOCTOR/ONLINE. However, thesJ                        given file spec does not refer to an existing file.M                        DOCTOR/ONLINE will not attempt to find and inspect the &                        specified file.  M                        User Action: the specified file spec may be incomplete P                        (e.g. only name and type mentioned) and you may currentlyO                        execute DOCTOR from another directory. In that case, you O                        may want to change your default directory to the correct B                        one for DOCTOR to find the files specified.K                        Otherwise either locate the specified file and starts*                        again or ignore it.  <                     INPUTFNF,  Input file 'string' not found  &                        Severity: FATAL  M                        Explanation: The specified input file cannot be found.   H                        User Action: Specify existing input file. CorrectB                        spelling or device/directory specification.  1                     INSPECT,  Inspecting 'string'   .                        Severity: INFORMATIONAL                  A-8  <                                    Digital Internal Use Only         Q                                                                    Error messagest          N                     MODIFY,  Modifying 'string' to be compliant for BOOKREADER)                              destinations   .                        Severity: INFORMATIONAL  N                        Explanation: The original input file(s) are modified toK                        be properly formatted for DOCUMENT online processing   )                        User Action: None.r  F                     PASS1,  Collecting label and reference information  .                        Severity: INFORMATIONAL  N                        Explanation: The input file and the files it referencesN                        are inspected for any labels defined and referenced, toC                        build a data structure to be used in Pass 2.a  )                        User Action: None.   N                     PASS2,  Generating labels, references and figure_file tags  .                        Severity: INFORMATIONAL  N                        Explanation: The input file and the files it referencesE                        are inspected and missing labels are inserted.p:                        Unreferenced labels are referenced.  )                        User Action: None._  <                     REMOVE,  Removed label from 'string' tag  (                        Severity: WARNING  N                        Explanation: Some section tags have no label associatedO                        with them in VAX DOCUMENT V1.* . They are allowed in V2,_N                        but the /VERSION_1 qualifier that was used caused it to"                        be removed.  F                        User Action: None, or do not specify /VERSION_1P                        qualifier. In this case, the output can only be processed+                        by VAX DOCUMENT V2.*   Q                __________________________________________________________________t          A.7     PSSCAN Messages  H                     ABSENTPAGESCHEME,  Page number indicated as 'string'P                        Blank page insertion mechanism may not work properly here  (                        Severity: WARNING  G                        Explanation: It is allowed by PostScript comment M                        standards to define a page comment as '%%Page: ? n' or L                        '%%Page: "" n' if or any other text string without anP                        explict page number specified and printed on the physical  Q                                                                               A-9u  <                                    Digital Internal Use Only r  f                    Error messages           O                        page. The '?' or "" is replaced by DOCTOR/PS to be "?-0"_M                        to allow proper processing of the page as if it were a M                        known page number system. However, since it is unknown L                        whether "?" pages are odd or even, there is no way toN                        know whether additional blank pages should be inserted.  P                        User Action: None. The use of /BLANK on the input file is;                        probably not useful in this context.   A                     CONFORM,  File assumed to conform to 'string'L  .                        Severity: INFORMATIONAL  M                        Explanation: Input PostScript file seems to conform to L                        the Adobe Inc. (minimal) conformant coding standards.  )                        User Action: None.   .                     CREATED,  Created 'string'  (                        Severity: SUCCESS  N                        Explanation: Indicates the successful completion of theM                        utility and the creation of the specified output file.S  )                        User Action: None.t  @                     CREATOR,  Input file was created by 'string'  .                        Severity: INFORMATIONAL  L                        Explanation: This message indicates the origin of theI                        PostScript file that is currently being processed. K                        Depending on this origin, some features of DOCTOR/PSsO                        may not be used. All VAX DOCUMENT produced files will bee(                        handled properly.  (                        User action: None  5                     INSERTED,  Page 'string' insertedi  .                        Severity: INFORMATIONAL  L                        Explanation: Indicates that a blank page was insertedL                        into the output document to balance the number of odd#                        /even pages.   )                        User Action: None.                   A-10_  <                                    Digital Internal Use Only f  t    Q                                                                    Error messagese          O                     INVALCOUNT,  Invalid page counter 'signed decimal number' . 9                                  Must be positive integeri  &                        Severity: FATAL  N                        Explanation: The page counter to be added to the footerO                        must be a positive integer. Negative values and zero areo#                        not allowed.c  L                        User Action: Specify positive integer from 1 upwards.  L                     INVORDINAL,  Input file violates Adobe standard: ordinalB                                  starts at 'signed decimal number'  (                        Severity: WARNING  M                        Explanation: The comments of the first page inside the O                        PostScript file should indicate the folio number as well N                        as the sequence number of the page within the file. TheP                        first page is assumed to have sequence number 1. For someN                        reason, the program that output the PostScript file didP                        not start counting from 1 upwards, but from the indicated                        number.  N                        User Action: None - The DOCTOR will rectify this in theN                        output file it produces. You may wish to file a ProblemK                        Report to the producers of the software package that P                        made your PostScript file, stating they violate the Adobe-                        programming standards.n  Q                     INVPAGCOM,  Page comment "'string'" at line 'unsigned decimal '                                 number' O                        not conforming to Adobe PostScript standards. Ignored as #                        page marker.   (                        Severity: WARNING  N                        Explanation: The input file contains invalid conformantL                        coding comments, whereby the utility cannot interpretN                        the page data correctly. Although DOCTOR will continue,O                        it ignores this line as page and assumes there is no new (                        page that starts.  K                        User Action: Inspect the final output. It may not be O                        exactly what you wanted, but it may. This can be checked "                        through the  0                        $ SEARCH filespec %%Page:  N                        DCL command and see if all pages are correctly odd/even"                        positioned.  Q                                                                              A-11   <                                    Digital Internal Use Only    A                    Error messagesg          N                     NEGPAGNO,  Invalid page number to convert: 'signed decimal&                                number'  &                        Severity: FATAL  L                        Explanation: A page number was passed to a routine toM                        be converted to an ASCII Roman of Arabic numeral. This M                        error occurs when a negative number is passed from the D                        PostScript file or through an internal error.  P                        User Action: See DOCTOR SENDQAR message if the PostScriptC                        file does not contain negative page numbers.i  M                     NOCHANGE,  Input file needed no modification. No new file_(                                generated  .                        Severity: INFORMATIONAL  M                        Explanation: The operation of the utility on the input I                        file resulted in an identical copy for the output.pL                        Therefore no output is generated. The message is alsoN                        issued when one or more page ranges should be extracted?                        but not a single range could be located.n  P                        User Action: Be happy with the current PostScript file or3                        specify correct page ranges.   N                     NOPAGE,  File contains no valid %%Page: markers and is not=                              Adobe Coding Standard conformant   (                        Severity: WARNING  N                        Explanation: Despite the fact that the file starts withL                        a %!PS-Adobe header to suggest it conforms to Adobe's>                        Structured Coding PostScript standards,  N                        it does not, because individual pages are not marked byO                        a %%Page : comment line. Therefore DOCTOR is not able toiO                        distinguish between pages for extraction or re-ordering.r  K                        User Action: Try to create the PostScript file againaO                        from the text processor tool, enforcing Adobe standards. N                        If MS-Windows applications are used, the Print Setup...N                        menu will allow you (after various layers of Options...I                        or Setup... sub menus) to check the box for "AdobeoM                        Structured Coding Standards". Once checked, output thea-                        PostScript file again.f                    A-12q  <                                    Digital Internal Use Only f       Q                                                                    Error messagesG          O                     NOPROLOG,  File does not contain valid %%EndProlog comment.a3                                Not Adobe conformant   (                        Severity: WARNING  M                        Explanation: the %%EndProlog comment line fails in the L                        PostScript file. As such, it is not conforming to the9                        Adobe Structured Coding standards.   K                        User Action: Try to create the PostScript file again O                        from the text processor tool, enforcing Adobe standards. N                        If MS-Windows applications are used, the Print Setup...N                        menu will allow you (after various layers of Options...I                        or Setup... sub menus) to check the box for "Adobe M                        Structured Coding Standards". Once checked, output thee-                        PostScript file again.   L                     NOTCONFORM,  File is not (minimally) conforming to Adobe+                                  PostScript 4                        standards. No output created.  &                        Severity: FATAL  G                        Explanation: The specified input PostScript fileSH                        does not seem to adhere to the Adobe Inc. minimalK                        conformant coding standard. Hence the utility cannottP                        correctly interpret the input file (even if it is correct(                        PostScript code).  J                        User Action: Whatever you wanted to do must be done                         manually.  P                     NOTVAXDOC,  /CHANGE used on PS file not produced by DOCUMENT,                                 or DECwrite.0                        Success is not guaranteed  (                        Severity: SUCCESS  J                        Explanation: The /CHANGE is only guaranteed to workH                        for VAX DOCUMENT and DECwrite produced PostScriptN                        files. Depending on the adherence to standards by otherN                        PostScript creators, /CHANGE may also work successfully:                        here, but no success is guaranteed.  ?                        User Action: None. Use at your own risk.f        Q                                                                              A-13   <                                    Digital Internal Use Only                         Error messagesd          J                     PASS,  Starting input file scan Pass 'unsigned decimal"                            number'  .                        Severity: INFORMATIONAL  I                        Explanation: Because so many PostScript files have N                        figures and plot files included that all have their ownP                        %%Trailer commment, it is necessary to find the very lastN                        %%Trailer position in the file before starting the real"                        processing.  )                        User Action: None.b  I                     RANGESKIP,  Page range starting at 'string' not found.  (                        Severity: WARNING  J                        Explanation: Issued at the end of the processing ofK                        a PostScript file from which a range of pages had to J                        be extracted. The starting page number could not beO                        located in the input file, hence the entire range is not                          included.  B                        User Action: Specify correct starting page.  N                     SAMEFILESPEC,  Output file is next higher version of input(                                    file.7                        Purging will lose original file.o  (                        Severity: WARNING  J                        Explanation: You did not specify an explicit outputI                        file, hence the utility defaults to the input file M                        specification. However, this may cause the lost of theiL                        original input file is an accidental purge command is                        issued.  O                        User Action: Rename the latest version into another file P                        name or copy the file to another location to avoid losing)                        the original copy.   @                     SHORTRANGE,  Two end range values specified.O                        Using shortest of 'unsigned decimal number' and 'string'n  .                        Severity: INFORMATIONAL  M                        Explanation: You specified the /EXTRACT qualifier with K                        both an END and NUMBER keyword. Whichever of the two P                        indicates the smallest number of pages from the specified0                        START page, will be used.  K                        User Action: Accept or respecify the /EXTRACT range, O                        using only one of the two ending keywords END or NUMBER.(                  A-14   <                                    Digital Internal Use Only C       Q                                                                    Error messageso          O                     SKIPFIGURE,  Removing figure from output document: 'string'e  .                        Severity: INFORMATIONAL  H                        Explanation: The specified figure file is removedL                        from the PostScript output to be created. This allowsM                        conversion tools to reconstruct the original text file K                        without the graphics information inserted from other                         tools.r  (                        User Action: None  J                     STARTRANGE,  Including page range starting at 'string'  .                        Severity: INFORMATIONAL  K                        Explanation: Informs you that the specified /EXTRACTaO                        range was found and is activated. The specified range of ?                        pages will be copied to the output file.M  )                        User Action: None.D  Q                     TRUNCATED,  Resulting figure file name too long. Truncated toF(                                 'string'  (                        Severity: WARNING  M                        Explanation: By adding the page number to the originalnL                        input file name to compose the figure EPS output fileO                        name, the name exceeded the maximum allowed RMS filenameIN                        length. DOCTOR therefore truncated the name by removingP                        the last few characters of the input file name to make it                        fit.   N                        User Action: None. You may wish to rename the file name;                        manually after DOCTOR has completed.b  :                     UNKWNPAG,  Unknown page type: 'string'  &                        Severity: FATAL  O                        Explanation: The utility can only handle arabic or roman M                        numbered pages such as 1, 2, 3 or 1-1 or Glossary-6 orrL                        PART1-IX or III. The input file seems to contain pageK                        numbering schemes other than these two. Thereby this F                        utility cannot interpret those pages correctly.  J                        User Action: Whatever you wanted to do must be done                         manually.  Q                                                                              A-15i  <                                    Digital Internal Use Only U                       Error messagesR        Q                __________________________________________________________________           A.8     SADDLE Messages  J                     2UP,  Preparing file for 2UP printing in the next file$                           version...  .                        Severity: INFORMATIONAL  H                        Explanation: The file that was sorted for saddle-M                        stitching is once more modified to add PostScript code:N                        to allow it to be printed as 2-up without any reduction(                        of the page size.  (                        User Action: None  J                     2UPNOTSUP,  The /2UP feature is only supported for VAX-                                 DOCUMENT V2.1i  &                        Severity: FATAL  K                        Explanation: The PostScript code added to allow 2-up I                        printing is specific for the code generated by VAX M                        DOCUMENT V2.1. Until a more generic code is developed, L                        no other PostScript files can be processed with /2UP.M                        The file created can be used for reduced saddle stitchuL                        printing, using the /PARAMETER=(SIDE=TUMBLE,NUMBER=2)3                        feature of the printservers.   B                        User Action: Use the /SADDLE by itself with8                        /PARAMETER=(SIDE=TUMBLE,NUMBER=2)  A                     CONFORM,  File assumed to conform to 'string'i  .                        Severity: INFORMATIONAL  M                        Explanation: Input PostScript file seems to conform toIL                        the Adobe Inc. (minimal) conformant coding standards.  )                        User Action: None.c  .                     CREATED,  Created 'string'  (                        Severity: SUCCESS  N                        Explanation: Indicates the successful completion of theM                        utility and the creation of the specified output file.   )                        User Action: None.e                  A-16i  <                                    Digital Internal Use Only         Q                                                                    Error messagesv          @                     CREATOR,  Input file was created by 'string'  .                        Severity: INFORMATIONAL  L                        Explanation: This message indicates the origin of theI                        PostScript file that is currently being processed.yK                        Depending on this origin, some features of DOCTOR/PS O                        may not be used. All VAX DOCUMENT produced files will be (                        handled properly.  (                        User action: None  ?                     DEFGATHER,  No /GATHER qualifier specified.gI                        Using /GATHER='unsigned decimal number' as defaultt  .                        Severity: INFORMATIONAL  L                        Explanation: When no /GATHER is specified, the entireN                        book is re-ordered into a single gathering. This allowsL                        you to either fold the paper stack into a brochure orK                        to cut the paper stack in the middle for a paperback                         glueing.   L                        User Action: None or specify /GATHER with a different                        value  L                     INVORDINAL,  Input file violates Adobe standard: ordinalB                                  starts at 'signed decimal number'  &                        Severity: FATAL  M                        Explanation: The comments of the first page inside the O                        PostScript file should indicate the folio number as well N                        as the sequence number of the page within the file. TheP                        first page is assumed to have sequence number 1. For someN                        reason, the program that output the PostScript file didP                        not start counting from 1 upwards, but from the indicated                        number.  N                        User Action: None - The DOCTOR will rectify this in theN                        output file it produces. You may wish to file a ProblemK                        Report to the producers of the software package that P                        made your PostScript file, stating they violate the Adobe-                        programming standards.e          Q                                                                              A-17o  <                                    Digital Internal Use Only S  p                    Error messageso          I                     NOFOUR,  The /GATHER='unsigned decimal number' is not +                              divisible by 4i  &                        Severity: FATAL  G                        Explanation: Saddle stapling can only occur whenIN                        multiples of 4 pages are specified (that can be printedN                        on a single sheet - front and back side). The specified4                        number is not divisible by 4.  P                        User Action: Specify a correct number that can be divided                        by 4.  N                     NOPAGE,  No valid %%Page: comment lines. File is not Adobe9                              Structured Coding conformant   &                        Severity: FATAL  P                        Explanation: The specified input PostScript file does not%                        seem to adhere   N                        to the Adobe Inc. minimal conformant coding standard asP                        it lacks the %%Page: page separation comment lines. HenceL                        the utility cannot correctly interpret the input file?                        (even if it is correct PostScript code).   L                        User Action: Attempt to re-create the PostScript fileH                        enforcing the text processor to output conformantL                        Adobe Structured Coding Standard code. For MS-WindowsO                        applications, this may imply to enter the PRINT SETUP... H                        menu and find (under various layers of additionalP                        Setup... or Options... and Advanced Options... menus) theM                        check box for Adobe Structured Coding Standards. Check A                        this and export the PostScript file again.s  L                     NOTCONFORM,  File is not (minimally) conforming to Adobe+                                  PostScript 4                        standards. No output created.  &                        Severity: FATAL  G                        Explanation: The specified input PostScript fileaH                        does not seem to adhere to the Adobe Inc. minimalK                        conformant coding standard. Hence the utility cannotTP                        correctly interpret the input file (even if it is correct(                        PostScript code).  J                        User Action: Whatever you wanted to do must be done                         manually.                  A-18r  <                                    Digital Internal Use Only    g    Q                                                                    Error messages           Q                     ORDERED,  PostScript file already is in special order. Outputr,                               may be useless  (                        Severity: WARNING  L                        Explanation: DOCTOR discovered the PostScript commentL                        %%PageOrder: Special inside the PostScript file. ThisH                        indicates that the pages in the file have alreadyM                        been ordered in some special way. Although DOCTOR will O                        proceed, the final output may have re-arranged the pages B                        in such a way that the order is not useful.  L                        User Action: None. Either do not try to saddle stitchN                        the file or look at the printer output if the result is"                        acceptable.  M                     PAGES,  Document contains 'unsigned decimal number' pageso  .                        Severity: INFORMATIONAL  P                        Explanation: DOCTOR found the indicated number of %%Page:<                        entries that were valid page entries.  P                        User Action: None. It may help in determining the size of9                        the gathering you want to specify.   J                     PASS,  Starting input file scan Pass 'unsigned decimal"                            number'  .                        Severity: INFORMATIONAL  O                        Explanation: Starts reading the input PostScript file inaO                        Pass 1 to collect all page related data before the pagespM                        are randomly accessed in Pass 2 to allow extraction orc<                        re-ordering them in the final output.  )                        User Action: None.   N                     SAMEFILESPEC,  Output file is next higher version of input(                                    file.7                        Purging will lose original file.   (                        Severity: WARNING  J                        Explanation: You did not specify an explicit outputI                        file, hence the utility defaults to the input fileeM                        specification. However, this may cause the lost of the L                        original input file is an accidental purge command is                        issued.  O                        User Action: Rename the latest version into another filerP                        name or copy the file to another location to avoid losing)                        the original copy.t  Q                                                                              A-19.  <                                    Digital Internal Use Only r  t                    Error messagest          J                     UNSUPVER,  File produced by 'string' is not supported.G                        See Message Appendix in DOCTOR manual for manual !                        correctionG  &                        Severity: FATAL  P                        Explanation: The PostScript file is produced by a productM                        that outputs PostScript code that cannot be handled by (                        DOCTOR/PS/SADDLE.  P                        User Action: For some products this is because there is a,                        bug in their PS code.  I                        The following products allow manual correction andoK                        then you can resubmit the corrected file for correctu"                        processing:  '                           DECwrite V1.1wM                           Edit the PS file and at the final occurrence of the M                           %%Trailer line interchange the following two lines:   $                           $D restore#                           %%Trailer                              into  #                           %%Trailer $                           $D restore  O                           Now the restore operation remains with the trailer atnP                           the end of the saddle stitched file rather than movingQ                           with the original last page, causing "offending commandt'                           is a" errors.   Q                __________________________________________________________________o          A.9     XREF Messages  .                     CREATED,  Created 'string'  .                        Severity: INFORMATIONAL  N                        Explanation: XREF has succesfully created the indicated#                        output file.   (                        User Action: None                      A-20s  <                                    Digital Internal Use Only m       Q                                                                    Error messagesi          K                     NOBOOKTITLE,  No /BOOKTITLE specified with /SYMBOL_FILE   (                        Severity: WARNING  O                        Explanation: When a file is created with <DEFINE_SYMBOL> L                        tags, to allow cross referencing between books, it isO                        almost imperative that you also specify the title of the O                        book, so that the cross reference can contain both titlei8                        and section of the book involved.  P                        User Action: Add /BOOKTITLE with proper title of the book  P                     NOPREFIX,  No prefix specified. This may lead to conflicting)                                referencest  (                        Severity: WARNING  H                        Explanation: The user did not specify the /PREFIXI                        qualifier. Hence all symbols from the XREF file toEL                        be extracted as symbol definitions may turn out to be>                        identical to symbols defined elsewhere.  N                        User Action: It is good practise to make all symbols ofN                        a particular book unique by prefixing them with a shortM                        identification. This can be an acronym of the book, an M                        author number, etc. Keep in mind that the total length J                        of prefix + symbol name must not exceed the maximumK                        length allowed to symbols, being 31 characters (A-Z,RO                        0-9 and underscore). The prefix should not start with an 7                        underscore but may end with one.   M                     NOSORTSPEC,  Qualifier 'string' is invalid without /SORT.P0                                  Will be ignored  (                        Severity: WARNING  I                        Explanation: It is only possible to produce sorted ?                        alphabetic or numerically ordered lists.b  L                        User Action: Either add /SORT to the command line (toP                        activate the currently specified qualifier, or remove the+                        specified qualifier.o  M                     SYMTRUNC,  Symbol 'string' exceeds maximum allowed symbolE0                                length. Truncated  (                        Severity: WARNING  I                        Explanation: Due to the prefixing of the specifiedCJ                        string with /PREFIX the length of the entire symbolN                        exceeded the maximum length allowed by VAX DOCUMENT. It  Q                                                                              A-21   <                                    Digital Internal Use Only                         Error messages           O                        is truncated to maximum allowable length by removing theo*                        final character(s).  P                        User Action: None. Alternatively, a shorter prefix can beN                        choosen or in the original document from which the XREFP                        file originates, one should shorten the symbolic names toO                        avoid the problem. This requires processing of that file ;                        by VAX DOCUMENT again after editing.f  M                     WHATTODO,  You must specify at least one of /SYMBOL_FILE, -                                /LIST or /SORTn  &                        Severity: FATAL  O                        Explanation: DOCTOR/XREF can only perform one or severalaK                        of its three possible operations if one of the three6K                        qualifiers indicated is specified. Without either of -                        them, nothing is done.o  K                        User Action: Specify one, two or all three specifiedp"                        qualifiers.                                                                        A-22   <                                    Digital Internal Use Only                       T                    _________________________________________________________________                      Index  2                    _______________________________@                    A                                 DEC/MMSo7-1S                    _______________________________     Use of MMS and DOCUMENTo7-11tJ                    ABSENTPAGESCHEMEoA-9              DECwindows/Motifo7-13C                    ATLASToA-5                        DEFGATHERoA-17iL                                                      <DEFINE_SYMBOL> tago9-3;                    _______________________________   DOCTORlE                    B                                   componentso2-1 G                    _______________________________     installationovii E                    %%BeginDocument: commento6-10,      invocationovii H                      6-18                              using DEC/CMSoviiF                    blank pageo6-2                    DOCTOR/ONLINEo5-1K                      user specifiedo6-5              document structureo7-1eR                    Bookreader                          build MMS description fileo<                      Adding referenceso5-8               7-4B                      Adding symbolso5-8              DUPLICATEoA-3  T                      correcting files for -o5-1      _______________________________6                      figure file for -o5-8           ET                      with DOCUMENT V1.2Bo5-7         _______________________________O                      with DOCUMENT V2 and highero    %%EndComments commento6-18 P                        5-7                           %%EndDocument: commento6-10O                    Bordero6-8                        %%EndDocument commento6-18iM                    Brochure, producing reduced       %%Endprolog commento6-18o                      sizedo6-12 T                    Bug Reportsoviii                  _______________________________  6                    _______________________________   FT                    C                                 _______________________________B                    _______________________________   .FACILITYo4-5;                    CONFORMoA-10, A-16                figureAS                    CREATEDoA-1, A-2, A-3, A-5,         extracting - from PostScript B                      A-8, A-10, A-16, A-20               fileo6-11Q                    CREATORoA-10, A-17                  removing - from PostScriptnB                    CRELISToA-8                           fileo6-11G                    cross referenceo9-3               FNFoA-2,  A-6, A-8 C                                                      FSE formato5-8   T                    _______________________________   _______________________________  6                    D                                 GT                    _______________________________   _______________________________=                    DOCUMENT/GRAPHICS - See RAGS      GlossaryiR                    DEC/CMSo7-3                         International character setA                      class and DEC/MMS rebuildo          sorto3-3 B                        7-7                             sortingo3-1  T                                                                              Index-1  /                       Digital Internal Use Only  o  b                    Index          ;                Glossary (cont'd)                 MMSTOOoA-6 ;                 sort ordero3-3                   MODIFYoA-9n>                GTERMOUTBOUNDoA-3                 <MSG> tago4-2C                <GTERM> tago3-2                   <MSG_TEXT> tago4-2e;                                                  MUMBLEoA-7t.                _______________________________P                H                                 _______________________________  2                _______________________________   NP                HELP/MESSAGE utilityo4-1, 9-15    _______________________________>                HUMANSoA-6                        NEGPAGNOoA-12A                                                  NEXTGLOSSARYoA-3 <                _______________________________   NOALPHAoA-4  A                I                                 NOBOOKTITLEoA-21s>                _______________________________   NOCHANGEoA-12=                IDENToA-1                         NOCMSSUPoA-7tB                IGNOREDoA-6                       NOENDGLOSSARYoA-4<                Include fileso7-1                 NOFOURoA-18?                Index entrieso7-14                NOGLOSSARYoA-4d=                 correction ofo7-15               NOGTERMSoA-5 B                INPUTFNFoA-8                      NOPAGEoA-12, A-18>                INSERTEDoA-10                     NOPREFIXoA-21>                INSPECToA-8                       NOPROLOGoA-13@                INVALCOUNToA-11                   NOSORTSPECoA-21F                INVORDINALoA-11, A-17             NOTCONFORMoA-13, A-18=                INVPAGCOMoA-11                    NOTFOUNDoA-7   <                _______________________________   NOTIMPLoA-2?                                                  NOTVAXDOCoA-13                 LP                _______________________________   _______________________________  2                LaTeXo8-2                         OP                LPS20 printer                     _______________________________?                 Use for double sided printing    OHMYDIODESoA-7 9                    o6-16                         OHNOoA-7s=                LPS40 printer                     ORDEREDoA-19oP                 Use for printingo6-15            _______________________________  2                _______________________________   P  P                M                                 _______________________________J                _______________________________   %%Page: commento6-5, 6-18;                MARFINo7-4                        PAGESoA-19 @                Message file, VMSo4-1             PASSoA-14, A-19?                 elements of a -o4-2              PASS1oA-1, A-9 ?                 sorting messageso4-2             PASS2oA-1, A-9 B                <MESSAGE_SECTION> tago4-2         Perfect bindo6-14                  Index-2  +                   Digital Internal Use Only     W    P                                                                            Index        P                                                  _______________________________2                PostScript                        SP                 Add blank pageo6-2               _______________________________N                 %%BeginDocument: commento        Saddle sticho6-12, 6-14, 9-25M                    6-10                          SAMEFILESPECoA-5, A-14, A-19o9                 conformant PostScript            SCANoA-3 :                    skeletono6-18                 SDML fileP                 drawing page bordero6-8            adding symbols for Bookreader9                 encapsulated figureso6-10            o5-1 <                 %%EndDocument: commento6-10      SENDQARoA-2I                 minimal conformanto2-1,  6-16    SET DISPLAY commando7-14r>                 %%Page: commento6-5,  6-9        .SEVERITYo4-59                 page range descriptiono6-8       SGMLo8-2U@                 prolog replacemento6-5           SHORTRANGEoA-14@                 structured commentso6-4          SKIPFIGUREoA-15@                 structured comments V2o6-4,      STARTRANGEoA-15O                    6-17                          .SUFFIXES for MMS and DOCUMENT 8                 structured comments V3o6-3,        o7-10E                    6-17                          symbolo5-1, 5-8, 9-1 M                 user specified blank pageo         definition of all symbolson8                    6-5                               9-3J                PostScript file                     list of all symbolso9-2>                 prolog replacemento6-5           SYMTRUNCoA-21#                PostScript fileso6-1sP                PS2TEXT utilityo6-11              _______________________________2                %!PS-Adobe commento6-18           T  P                _______________________________   _______________________________5                Q                                 Tags ?                _______________________________     countingo8-1r?                QAR reportsoviii                  TRUNCATEDoA-15   P                _______________________________   _______________________________  2                R                                 UP                _______________________________   _______________________________>                RAGSo5-8, 6-18                    UNKWNPAGoA-15>                 use with MMSo7-13                UNSUPVERoA-209                RANGESKIPoA-14                    2UPoA-16 ?                referenceo9-1                     2UPNOTSUPoA-16c9                reference tago5-1                 UTOXo5-8   P                <REFERENCE> tago5-8               _______________________________2                REMOVEoA-9                        VP                Rules for MMS and DOCUMENTo       _______________________________4                  7-10                            VMSB                Runoffo8-2                          Alphao4-1, 9-15  A                                                    Openo4-1, 9-15A  P                                                                          Index-3  +                   Digital Internal Use Onlyw    e                    Index        .                _______________________________  P                W                                 _______________________________2                _______________________________   YP                WHATTODOoA-22                     _______________________________  B                _______________________________   <Y> tago7-1, 7-14  P                X                                 _______________________________2                _______________________________   ZP                XREF fileo9-1                     _______________________________:                <X> tago7-1, 7-14                 ZzTeXo8-2                                                                                            Index-4  +                   Digital Internal Use Onlyr