  9 DOCTOR is a collection of seven tools under one umbrella:           DOCTOR/GLOSSARY        DOCTOR/MESSAGE         DOCTOR/ONLINE        DOCTOR/PS        DOCTOR/SDML        DOCTOR/TAG_COUNT         DOCTOR/XREF  A Each working on different files used or produced by VAX DOCUMENT.   I DOCTOR is Digital proprietary software. It may not be further duplicated  3 or distributed other than through Digital channels.   " DOCTOR is an unsupported product.   B __________________________________________________________________   1 DOCTOR's components   :   The utility consists of several more or less independent:   parts, each working on some sort of file produced by the7   VAX DOCUMENT typesetting software. Only the part that 6   works on PostScript files can also be used for other7   PostScript files, as long as they adhere to the Adobe /   specified minimal conformant file structure.    ;   The types of files that can be handled by the DOCTOR are:      o  PostScript files   /   o  XREF cross reference files of VAX DOCUMENT   &   o  SDML source files of VAX DOCUMENT  <   o  MSG message files of the VMS Message utility to produce      SDML files   B __________________________________________________________________  0 2 DOCTORing SDML files: Sorting glossary entries  E   Using the DOCTOR/GLOSSARY qualifier invokes the glossary item sort  F   utility. It will accept the input of any properly coded SDML source K   file with <GTERM> entries and sorts these in ASCIIbetical order with some L   small corrections on its collating sequence. Under a properly coded file, N   it is understood that only a single <GLOSSARY> - <ENDGLOSSARY> block exists E   in the .SDML file. Multiple glossaries inside a single file are not    supported by DOCTOR.  H   The glossary does not need to be the only part of the file: it may be I   embedded in a larger SDML file. Only the glossary part is sorted. Text  @   preceding or following the glossary section remains untouched.  B __________________________________________________________________  $ 3 DOCTORing VMS Message source files  J   When a software product is coded and one uses the VAX/VMS error message K   utility to produce error messages on SYS$ERROR when the software detects  K   an error (like the %DOCTOR messages you get from DOCTOR), the best place  K   to describe the reason of the error message occurring, and what the user  J   could possibly do to prevent it next time, is to write this information K   immediately when the message is defined. That's when you know best which  D   message is added, why it was added and what you could do about it.  K   The DOCTOR/MESSAGE utility will format a properly coded source file with  K   VAX/VMS message definitions and embedded comments in such a way that the  I   comments of the file are reformatted into a <MESSAGE_SECTION> section,  C   ready for inclusion into the User's Guide message appendix of the J   documentation that describes the software to which these error messages 	   belong.      Note: F        If you use DOCTOR/MESSAGE/HELP then the produced .SDML file is ?        compatible for processing with the HELP.MESSAGE doctype.   F   The produced SDML file can be <INCLUDE>d into a VAX DOCUMENT source 4   that is processed for the SOFTWARE family doctype.    B __________________________________________________________________  , 4 DOCTORing SDML files for Bookreader output  J   VAX DOCUMENT can be used to build books for printing on paper, but also K   for using them as online books using the DECwindows Bookreader on either     VMS or ULTRIX.  M   Unfortunately, the Bookreader product imposes a more strict use of some of  J   the tags, available in DOCUMENT, due to its unique features of "pop up" K   elements (tables, figures, examples) that appear when you click on a "hot    spot".  H   Because any part of the document must be accessible from the table of J   contents, a symbol must be attached to them so an implicit reference is <   made from the table of contents to the section pointed at.  L   DOCTOR/ONLINE will go through your SDML files and add symbols where there N   are none, and also add references to pop up elements, where none is written H   in the text.  If you specify a profile file, all elements will also be=   searched, as will any file referenced in a <INCLUDE> tag.     B __________________________________________________________________   5 DOCTORing PostScript files  G   PostScript files are produced by a wide variety of products, such as  I   VAX DOCUMENT, DECwrite, DECpaint or MS-Word. With the arrival of laser  I   printers lots of documentation is produced in the PostScript format and +   printed. Several problems can then occur:   K   o  A file print is halfway ready when the system crashes or the job gets  1      aborted for all the right and wrong reasons.   :   o  Only a section of a document is interesting to print.  I   o  Some products, like VAX DOCUMENT, do not produce blank pages when a  L      section ends on an odd page. This causes double sided printers to skip J      a page and print the following section on the wrong side of the page 1      (recto pages on verso pages and vice versa).   K   o  The same file is needed, but one would like a different standard page  O      layout (e.g. with DRAFT written over the page) as defined in the prologue        of the PostScript file.  M   o  The PostScript file contains figures that were inserted as encapsulated  N      PostScript and you would like to remove those from the file or to create 4      them as separate files to re-use those figures.  L   o  A PostScript document should be re-ordered in page output to allow for L      saddle stitching of double sided printed sheets (4 pages/sheet, like a 5      magazine with page sheets folded in the middle).   C   The DOCTOR utility does all this in an easy manner, provided the  D   PostScript file that must be inspected adheres to Adobe's minimal K   conformant coding style. This is assumed to be true if the first line of  J   the PostScript file contains %!PS-Adobe, possible followed by a version 	   number.    Replacing the prologue:   P   The prologue contains definitions and a general page layout applicable to all L   pages. Hence, you can add or replace certain features to give the printed L   pages a different look, without modifying any of the text that is part of M   the document itself. You can create your own prologue, either based on the  L   original one, or entirely homewritten, to replace the prologue that comes M   with the input file. This way you can produce effects like writing "DRAFT"  L   diagonally across all pages, or print a faint logo on each page or border    the text in a frame.  K   To allow some simple modification, the qualifier /CHANGE_PROLOG has been  8   implemented. You can specify three items on each page:  ;   o  A bold printed text at the top of each page (a header)   >   o  A bold printed text at the bottom of each page (a footer)  <   o  A faintly grey printed text diagonally across the page.(      The grey scale can be set manually.     Extracting ranges:  H   Using the /EXTRACT  qualifier you can specify to copy only a range of 2   pages from the input file into the output file.      Removing or re-using figures:   J   A PostScript file contains text and possibly figures. Those figures are I   very often made separately (using a drawing package) and then inserted  H   into the text body by the text formatting tool such as VAX DOCUMENT's ;   <FIGURE_FILE> tag or DECwrite's "LINK TO PICTURE" option.   E   Occasionally there is a need to either remove the figures from the  H   PostScript file (to allow the remainder to be converted back to plain A   ASCII text file) or to re-use those figures in other documents.      Removing figures:   J     For some time now several tools are available to convert a PostScript M     file back into its plain ASCII text file.  This can come in handy if the  L     sources to produce the PostScript file are lost or part of the document G     could be used in another file. These PostScript-to-ASCII converters J     sometimes cannot handle embedded figures. DOCTOR enables you to remove-     that code before conversion it attempted.        Extracting figures:   L     When you want to extract figures from a document into individual figure N     files, this function will result in DOCTOR scanning the PostScript source J     file and to extracting each included figure to become a separate .EPS I     file. This file can then be used in other documents or presentations.      Saddle stitch printing:   N   When one wants to use a printer that allows for printing on both sides of a K   sheet of paper, it may be advantageous to print the pages on half format  L   (allowing two pages on a single sheet side) and then fold the pages in theK   middle to make a signature (like a magazine), ready for saddle stitching.   N   When the book is very thick, one may decide to divide the book into several 4   of these signatures and then stitch them together.  N   In both cases this requires the output order of the pages in the PostScript N   file to be modified. Rather than the usual sequential order of page 1, 2, 3 N   etc, we now need the first and the last page to be printed after each other M   (and on the same sheet side if printing is setup for two pages/sheet). And  E   then page 2 and the one-but-last page on the backside of the sheet.       Saddle stitched printing E    __________________________________________________________________   P +-------+-------+    +-------+-------+    +-------+-------+    +-------+-------+P |       |       |    |       |       |    |       |       |    |       |       |P |       |       |    |       |       |    |       |       |    |       |       |P |       |       |    |       |       |    |       |       |    |       |       |P |       |       |    |       |       |    |       |       |    |       |       |P |       |       |    |       |       |    |       |       |    |       |       |P |8      |      1|    |2      |      7|    |6      |      3|    |4      |      5|P +-------+-------+    +-------+-------+    +-------+-------+    +-------+-------+  N __front_sheet_1_________back_sheet_1_________front_sheet_2__      back sheet 2  N   SADDLE only works for printing 4 pages on a sheet (two on each side). There K   is no support for 4 or more pages printed on a single side of a sheet of     paper.   Minimal conformant files:   L   Adobe Inc. defined a "Document Structuring Conventions Specification" for K   PostScript files that utilities such as VAX DOCUMENT and DECwrite should  M   adhere to. Only then other utilities such as DOCTOR can inspect those files N   and manipulate them. DOCTOR's output is also conformant to these styles, so 4   one could use DOCTOR on its own files recursively.  B __________________________________________________________________  8 6 DOCTORing SDML files: hierarchy of files within a book  M   A complex document written for VAX DOCUMENT processing can consist of many  D   elements. The text may all be written in a single source file, or G   distributed over many others, that are all <INCLUDE>d into the final  I   printable document. Besides text, other tools and utilities can provide D   additional graphical or tabular data. Often a complex document is K   built using a profile file where this profile specifies the names of the  :   other SDML files that are part of the complete document.  L   When several people work on such a compound document, it is easy to loose L   track of the number of files that are referenced from the main, the root,    source file.  I   Here, the DOCTOR/SDML utility, can assist you in the process. Given any K   top level root file that is coded in VAX DOCUMENT, it will produce one or 
   several of:   O   o  An organizational hierarchy of how the document is composed of individual  F      elements (that in turn may also be composed of smaller elements).  L   o  A DEC/MMS description file that lists all the dependencies between the L      individual components in order to rebuild the final printable document H      in any of the supported destinations: LN03, PostScript, Bookreader,      Line_printer or Mail.  K   o  A list of all occurrences of the <X> and <Y> tags that are written in  K      those VAX DOCUMENT source files, annotated with the exact line number  *      of the file in which they were found.     Listing all included files:   M   When a document is processed to the final output, the VAX DOCUMENT command  N   line indicates the top level source SDML file to be processed.  When one of E   VAX DOCUMENT's three components (Tag Translator, Text Processor and E   Device Converter) encounter any of the tags (or their equivalents), K   the specified files will be opened and included into the final printable  	   output.   * Producing MMS description (rebuild) files:  M   Because once the hierarchy list is made, the DOCTOR also knows which files  O   depend on which other ones, it is an easy task to produce a description file  L   that can be read by DEC/MMS to rebuild the document if one of the elements   is modified.  O   Because DEC/MMS does not know how to build an LN03 or PostScript file from an I   SDML file, the DOCTOR/SDML also inserts all the required MMS rules and  M   suffixes to allow DEC/MMS to retrieve the sources from a CMS library and to 1   rebuild it using a proper VAX DOCUMENT command.    Using DOCUMENT/GRAPHICS:  L   A special mention must be made for the use of DOCUMENT /GRAPHICS produced L   graphics. This utility, that is delivered with VAX DOCUMENT V2.0 onwards, M   is a DECwindows oriented graphics editor, that will produce one or several  K   different output graphics: PostScript, sixel or BRF-bookreader files. In  L   addition it can output another .SDML file that only contains <FIGURE_FILE>I   tags. This enables the author to completely decouple text and graphics  M   components of the document. The only thing written in the text file will be   -        <FIGURE>(figure caption\figure_symbol) !        <INCLUDE>(figurefile.SDML)         <ENDFIGURE>  N   whereas the figurefile.SDML will be created by the DOCUMENT/GRAPHICS editor L   and contains the required <FIGURE_FILE> tags with the correct size of the 0   figure, which may differ for each destination.  L   When DOCTOR/SDML/MMS is required to produce an MMS file, it will also add L   the action rule to invoke the graphics editor DOCUMENT/GRAPHICS=RENDER to M   recreate any such .SDML file from a graphics meta-file with file type .GRA. J   However, this will only work, if the MMS description file is invoked by M   MMS while running on a DECwindows display (terminal or workstation), as the G   DOCUMENT/GRAPHICS utility will only work when it has this environment ;   available - even if it will not display a single window.     Retrieve all index entries:   N   When a document is written and it contains many index entries, your chances N   are good that some index entries that were supposed to be identical, but on N   different pages, are actually printed as two entries in the index.  Usually 6   because you mistyped an entry of the <X> or <Y> tag.  O   Finding those typo's is tedious: you need to get the book printed, then look  L   in the index, find the errors, look at that page, determine which file it ?   comes from and finally go into the editor and find the entry.   M   The DOCTOR allows all this to be done much easier, without the overhead of  K   rebuilding the entire book each time you think you found all the errors.  E   (Usually the fixing of index entries take several repeated loops of    correcting the tag entries).  O   By specifying DOCTOR/SDML/INDEX the DOCTOR produces the hierarchy list, but,  L   while scanning through all the SDML source files, it also copies each and M   every occurrence of the <X> and <Y> tags into a separate file, specified by    the /INDEX= qualifier.  L   The result looks something like the following example. This may look odd,    but it is very useful.  *        Example Output of DOCTOR/SDML/INDEXI        __________________________________________________________________   G         <X>(DOCTOR<XS>installation)       <comment>(    34 DOCTOR.SDML) E         <X>(DOCTOR<xs>invocation)       <comment>(    58 DOCTOR.SDML) <         <X>(CONFORM)       <comment>(    16 DOCTOR_MSG.SDML)<         <X>(CREATED)       <comment>(    25 DOCTOR_MSG.SDML)G         <Y>(IDENT - See DOCTOR)       <comment>(    34 DOCTOR_MSG.SDML)g  I        __________________________________________________________________r  K   The fact that all lines start with tag <X> or <Y>, allows you to use the aM   DCL command SORT to sort the file into alphabetical order. (It is produced _2   in order of the files referenced by the DOCTOR).  '        $ SORT  input_file   output_filel  M   This will position typo's near each other and easy to spot when the sorted oN   file is printed. It is also easy to load all the required SDML source files K   into your editor buffers once, and then move from buffer to buffer[1] to lL   correct the errors. Since you do not add any lines, but simply re-type an L   entry, the line numbers that precede the file specification that is given N   in the <COMMENT> on the same line, allows you to use a goto line command[2] H   to quickly move to the indicated line to find the incorrect tag entry.  L   Once all these entries have been corrected in the SDML files, you can run K   DOCTOR/SDML/INDEX once more on it and inspect the new output to spot any aK   typo's you missed. If there are none, you can use the produced index file M   to make a dummy book by processing the index file by itself. Of course the  G   final output will contain non-sense page numbers, but at least it is mI   processed and built in substantially less time than redoing the entire iE   document.  When the processed and printed index also looks correct,bI   then you reprocess the entire book. If you're still not satisfied, you  >   should make additional changes to the incorrect tag entries.  -             [1] "GOTO BUFFER name" for LSEDITm               [2] LINE for LSEDITt  B __________________________________________________________________  * 7 DOCTORing SDML files: Counting tags used  K   This is a very simple utility that counts all the tags encountered in an gJ   SDML file. A tag is defined as any contiguous text string consisting of J   alphabetic, numeric or underscore characters, surrounded by the opening H   and closing angle brackets: <LIKE_THIS>. For this reason, the utility 0   also detects and counts all user defined tags.  K   The utility is invoked through DOCTOR/TAG_COUNT, and takes a single SDML eO   file as an input parameter. It automatically also searches through all files  N   referenced by the input file specified: if a profile is given, all elements <   of the book are also searched, as are the <INCLUDE> files.     Note:m@      This utility counts any tag-like construct, as it does not @      interpret or validate them.  This also means it counts all ?      tags within <COMMENT> blocks and/or <LITERAL> blocks. WheneC      within these blocks <INCLUDE> or <ELEMENT> or <INCLUDES_FILE> oA      tags are encountered, DOCTOR/TAG will attempt to lookup the e?      files referenced by these tags. It will give a warning if  8      those files do not exist, but continues processing.  G      __________________________________________________________________ 8            Example   Sample DOCTOR/TAG_COUNT output file?      ___________________________________________________________  I                 Generated by DOCTOR/TAG_COUNT.  Digital Internal Use Onlya  J   Tags (and their frequency) found in SDML document rooted in DOCTOR.SDML:  )                              2 <ABSTRACT>u)                              4 <APPENDIX> (                             10 <CALLOUT>)                              3 <CALLOUTS> ,                              2 <CENTER_LINE>(                             10 <CHAPTER>-                            412 <CODE_EXAMPLE>p(                              7 <COMMAND>0                              1 <COMMAND_SECTION>(                             23 <COMMENT>!                                 : !                                 : $                            177 <TAG>$                              6 <TEX>&                              3 <TITLE>+                              2 <TITLE_PAGE>n"                              4 <U>,                              3 <VALID_BREAK>"                            369 <X>#                            104 <XS>rK                        _____13_<Y>__________________________________________  B __________________________________________________________________   8       DOCTORing XREF files    K   When a large document is built using DOCUMENT, often references are used hK   to point to other parts of the document. After a while, and certainly if tE   several authors work on a document, you start losing track of what  K   symbols are defined for what tables, sections and other referable items.  &   Even if a naming convention is used.  K   For this reason DOCTOR/XREF has been built. It will work on any document mJ   of which the cross reference .XREF file exists. This is always true for J   documents built through a profile. Single file documents do not have an G   .XREF file - the Tag Translator keeps all data gathered in Pass 1 in  H   memory and uses it to resolve references during Pass 2: no need for a I   file. You must break up this file into parts and add a profile file to h"   it, in order to use DOCTOR/XREF.  H   Using DOCTOR/XREF on a .XREF file will allow you to do several things:  K   o  Build an SDML file with all symbols listed in a <TABLE> structure. By  I      processing this SDML file (e.g. using the REPORT doctype) you get a pM      nicely printed listing of all symbols and their textual contents. Those -I      lists can be alphabetic on symbol name or sorted numerically by type 6      (e.g. all table symbols sorted by table number).   N   o  Build an SDML symbol file containing <DEFINE_SYMBOL> tags of all symbols L      defined in the .XREF file. This allows you to <INCLUDE> that file into N      some other book and thereby enables you to cross reference between books.   Build symbol listings:  G   DOCTOR/XREF allows you to produce a formatted listing of all symbols bL   defined in a document. The listings are made in <TABLE> format and can be N   processed with VAX DOCUMENT using any doctype available that supports table L   tags.  The listings can be made in alphabetical order on the symbol names ?   but also in numerical order of the section or object numbers.c  N   By default all symbols are then sorted alphabetically per type. However, in M   many cases it may be more useful if they are sorted by their numeric value  M   (if applicable) so that for example, you can quickly look up the symbol foro
   Table 5-6.     " Build cross reference symbol file:  I   To build a file with <DEFINE_SYMBOL> tags that define the symbols plus OJ   their reference translation, you need to specify the .XREF file to scan >   and the /SYMBOL_FILE=filespec for the resulting output file.  B __________________________________________________________________  G In Summary, the various tools under DOCTOR are invoked by the followingl	 commands:t   DOCTOR/GLOSSARYr  2   DOCTOR/GLOSSARY-Sort glossary items in SDML file  H   The DOCTOR/GLOSSARY utility will sort all <GTERM> tags and associated K   <GDEF> tags within an SDML source file. The glossary section may be part i8   of a larger file. There may only be a single glossary.     DOCTOR/MESSAGE  >   DOCTOR/MESSAGE-Create SDML file from VMS Message definitions  F   The DOCTOR/MESSAGE utility can create a VAX DOCUMENT SDML file with F   explanation of error messages, from a properly coded VAX/VMS Message   source file.     DOCTOR/ONLINE   0   DOCTOR/ONLINE-Modify SDML files for Bookreader  I   The DOCTOR/ONLINE scans through the specified SDML source file and the  B   files it references, for correct syntax to be processed for the E   BOOKREADER destination. This implies that symbols are added to all n4   unsymboled sections, tables, examples and figures.    	 DOCTOR/PSo  #   DOCTOR/PS-Modify PostScript filese  J   This utility adds blank pages to PostScript files when required to have J   a balanced set of odd/even pages. It also replaces the prologue part of I   a PostScript file or produces an alternative output file that consists  I   of a subset of pages. It can extract or remove encapsulated PostScript oF   figures from a document, or re-order the page sequence to allow for &   saddle stitching the printed output.     DOCTOR/SDMLx  #   DOCTOR/SDML-Markup Files Included   H   The DOCTOR/SDML scans through the VAX DOCUMENT source files for other H   sources included by them, up to a nesting level of 20. These included I   files can be VMS files or CMS elements, if DEC/CMS is installed on the tG   system. These files can be any of the ones normally accepted through     standard tags.  J   It reports the document structure as a comment block in the source file A   and can produce an MMS build file as well as a list of all the r   occurrences of index tags.     DOCTOR/TAG_COUNT a  .   DOCTOR/TAG_COUNT-Count all tags in SDML file  H   The DOCTOR/TAG_COUNT utility counts all tag constructs inside an SDML I   document. This document may be a complete book (profile plus elements). :   It reports the counted tags in the produced output file.     DOCTOR/XREFd  *   DOCTOR/XREF-List cross reference symbols  =   The DOCTOR/XREF utility enables you to produce a file with  J   <DEFINE_SYMBOL> tags of all symbols defined within a book, derived from    its .XREF file._  B   It also enables you to produce a listing of all symbols, sorted @   alphabetically or by symbol type (chapter, table, example etc)