/sys$common/syshlp/HELPLIB.HLB  —  RUNOFF
    Invokes the DIGITAL Standard Runoff (DSR) text formatter to
    format one or more ASCII files (see file).

    Invokes the DIGITAL Standard Runoff (DSR) Table of Contents
    utility to create an .RNT file that can be processed by DSR to
    make a table of contents (see /CONTENTS).

    Invokes the DIGITAL Standard Runoff (DSR) Indexing utility to
    create an .RNX file that can be processed by DSR to create an
    index (see /INDEX).

1  –  file

    Invokes the DIGITAL Standard Runoff (DSR) text formatter to
    format one or more ASCII files. Creates formatted files from
    source DSR (.RNO) files, unformatted table of contents (.RNT)
    files, and unformatted index (.RNX) files. Optionally creates
    intermediate (.BRN) files for input to RUNOFF/CONTENTS and
    RUNOFF/INDEX commands.

    The RUNOFF command allows you to do the following:

    o  Adjust the amount of text on a page.

    o  Control the position of text on a page.

    o  Control underlining, overwriting, and bolding of text.

    o  Override some DSR commands and flags in your input file.

    o  Process all or part of your input file.

    o  Create an intermediate file for indexes or tables of contents.

    For a complete description of the DSR formatter, including more
    information about the RUNOFF command, see the OpenVMS DIGITAL
    Standard Runoff Reference Manual.

    Format

      RUNOFF  filespec[,...]

1.1  –  Parameter

 filespec[,...]

    Specifies one or more ASCII files (containing text and DSR
    commands) to be formatted by the RUNOFF command. The input file
    type defaults to .RNO; you must specify the file type for .RNT
    and .RNX files. Wildcard characters are not allowed in the file
    specification.

    DSR produces an output file having the same file name as the
    input file. The output file type depends on the input file type.
    The default output file type is .MEM. For a list of input file
    types and the associated output file types, see the OpenVMS
    DIGITAL Standard Runoff Reference Manual.

    Specify SYS$INPUT to type the input from your terminal or a
    command procedure; terminate input from the terminal by pressing
    Ctrl/Z.

1.2  –  Qualifiers

1.2.1    /BACKSPACE

    Positional qualifier.

    Controls whether DSR uses the ASCII backspace character to
    perform character-by-character overprinting. By default, DSR
    performs line-by-line overprinting.

1.2.2    /BOLD

       /BOLD[=n]
       /NOBOLD

    Positional qualifier.

    Specifies the number of times characters are overstruck in
    a bolding operation. You can specify the number of times
    DSR overprints flagged text by stating a value for n. The
    value n must be 0 or a positive integer and defaults to 1.
    A specification of /BOLD=0 or /NOBOLD disables all boldface
    printing, even if the appropriate flags are recognized and
    enabled.

1.2.3    /CHANGE_BARS

       /CHANGE_BARS[=character]
       /NOCHANGE_BARS

    Positional qualifier.

    Controls whether DSR generates change bars in the formatted file.
    The default change bar character is the vertical bar (|).  The
    change bars appear 3 spaces to the left of the lines of text that
    you have marked for change bars.

    For information on the .BEGIN BAR and .END BAR commands, enter
    HELP DSR at the DCL prompt.

    You can replace the default change bar character by supplying a
    substitute character for the /CHANGE_BARS[=character] qualifier.
    You must specify the replacement character as either a character
    enclosed in quotation marks (" ")  or as an octal, decimal, or
    hexadecimal value for the desired character.

    The /CHANGE_BARS qualifier without a value uses the default
    change bar character (|). The /NOCHANGE_BARS qualifier overrides
    any change bar commands in the input file and disables the output
    of change bars.

1.2.4    /DEBUG

       /DEBUG[=(option[,...])]
       /NODEBUG (default)

    Positional qualifier.

    Traces certain operations by placing the DSR commands in the
    output file. You can specify the following options:

    o  ALL

       Specifies all five options (CONDITIONALS, CONTENTS, FILES,
       INDEX, and SAVE_RESTORE).

    o  CONDITIONALS

       Causes DSR to ignore all conditional processing commands (.IF,
       .IFNOT, .ELSE, .ENDIF) in the input file. DSR includes both
       true and false conditional information in the output file
       along with formatted text. For further details on the .IF,
       .IFNOT, .ELSE, .ENDIF, and .VARIABLE commands and the /VARIANT
       qualifier, enter HELP DSR at the DCL prompt.

    o  CONTENTS

       Causes DSR to output all .SEND TOC commands along with the
       text being sent to the table of contents.

    o  FILES

       Causes DSR to output all .REQUIRE commands as well as the text
       of the require files.

    o  INDEX

       Causes DSR to output the indexing commands, .INDEX and .ENTRY,
       in addition to the text to which they refer.

    o  SAVE_RESTORE

       Causes DSR to output all .SAVE and .RESTORE commands.

    If you specify only one option, you can omit the parentheses.
    If you specify /DEBUG without specifying any options, ALL is
    assumed.

1.2.5    /DEVICE

       /DEVICE=(option[,...])

    Positional qualifier.

    Controls whether DSR generates an output file (.LNI) that is
    suitable for printing on an LN01, an LN01E, or an LN03 laser
    printer.

    If you do not get the output that you expect when you print an
    .LNI file on an LN01 or an LN01E printer, check with your system
    manager. The OpenVMS DIGITAL Standard Runoff Reference Manual
    contains information for system managers about setting LN01 and
    LN01E laser printers to print .LNI files.

    You can choose options from the following list to indicate
    output device, page orientation, and type of emphasis for flagged
    characters in your .LNI file:

    o  LN01

       Produces an output file suitable for printing on an LN01 laser
       printer; the default paper size is 8 1/2 by 11 inches; the
       default mode is PORTRAIT. The output file name is the same
       as the input file name; the default file type is .LNI. This
       option is incompatible with the LN01E option.

    o  LN01E

       Produces an output file suitable for printing on an LN01E
       laser printer using the standard European paper size (A4).
       The output file name is the same as the input file name. The
       default file type is .LNI; the default mode is PORTRAIT. This
       option is incompatible with the LN01 option.

    o  LN03

       Produces an output file suitable for printing on an LN03 laser
       printer; the default paper size is 8 1/2 by 11 inches. The
       output file name is the same as the input file name. The
       default file type is .LNI; the default mode is PORTRAIT.

    o  LANDSCAPE

       Causes the appropriate fonts for landscape mode to be loaded
       into an LN01 printer; pages are printed with the long
       dimension at the top and use a smaller type size. (The page
       is 11 inches wide and 8 1/2 inches long.) Allowable page
       dimensions are 0 to 73 lines per page and 0 to 132 characters
       per line. This option is incompatible with the PORTRAIT
       option.

    o  PORTRAIT (default)

       Causes the appropriate fonts for portrait mode to be loaded
       into an LN01 printer; pages are printed with the short
       dimension at the top and use a larger type size. (The page
       is 8 1/2 inches wide and 11 inches long.) Allowable page
       dimensions are 0 to 66 lines per page and 0 to 80 characters
       per line. This option is incompatible with the LANDSCAPE
       option.

       PORTRAIT mode is the default when you specify /DEVICE=LN01,
       /DEVICE=LN01E, or /DEVICE=LN03.

    o  ITALIC (default)

       Causes the italic and bold-italic fonts to be loaded into an
       LN01 printer, and makes characters flagged for underlining
       appear in italic type. Italicized characters can also appear
       in boldface type, depending on the type of emphasis you
       specify in your input file.

       The LN03 printer requires no loading of fonts, because default
       fonts are present. Text flagged for emphasis is printed in
       italic type if the current font has the ITALIC attribute;
       otherwise the flagged text is underlined.

    o  UNDERLINE

       Causes the text and bold fonts to be loaded into an LN01
       printer, and underlines characters flagged for underlining.
       The LN01 printer allows only 63 consecutive characters
       (counting a space as a character) to be underlined per line.
       If you want to underline individual words and not the spaces
       between them, you will be able to underline only 63 words per
       line. This option is incompatible with the ITALIC option.

       DSR does not report an error if the user exceeds this limit
       of the hardware. On an LN03 printer, the flagged text is
       underlined if you have specified the UNDERLINE option. The
       printer does not default to italic even if the current font
       has the ITALIC attribute.

1.2.6    /DOWN

       /DOWN[=n]
       /NODOWN (default)

    Positional qualifier.

    Controls whether DSR inserts a specified number of blank lines
    at the top of each page. These blank lines precede any header
    information. The number of blank lines you specify (n)  does not
    affect the number of text lines on a page. For example, if you
    specify /DOWN=10 with a .PAGE SIZE of 58 lines, up to 58 lines of
    text will be output after 10 blank lines.

    If you specify the /DOWN qualifier without a value, five blank
    lines are inserted. If you specify /DOWN=0 or omit the qualifier,
    no blank lines are inserted, except those associated with the
    print device or header layout.

1.2.7    /FORM_SIZE

       /FORM_SIZE=n

    Specifies the maximum number of lines per page including running
    heads and running feet. Defaults to /FORM_SIZE=66, which is
    standard for 11-inch paper. For laser printers, set the number
    of lines as follows:

    Paper
    Size       Lines Mode

    8.05       69    Landscape
    8.28       71    Landscape (LN01E default)
    8.51       73    Landscape (LN01, LN03 default)
    11.00      66    Portrait (LN01, LN03 default)
    11.66      70    Portrait (LN01E default)
    12.33      74    Portrait
    13.00      78    Portrait
    14.00      84    Portrait

    When used with the /SIMULATE qualifier, the /FORM_SIZE qualifier
    controls the physical size of the page by putting out line feeds
    to match the number specified by the value n. When used with the
    /NOSIMULATE qualifier, the /FORM_SIZE=n qualifier causes DSR to
    suppress the form feed that DSR would normally insert at the line
    number specified by the value n. If the number of lines that DSR
    is going to put on any given page does not match the value n, a
    form-feed character is written into the output file.

    The default value for the value n is derived from the OpenVMS
    Run-Time Library (RTL) routine LIB$LP_LINES. This defaults to
    66 unless the logical SYS$LP_LINES is defined, in which case the
    assigned value is used. To change the default value, specify a
    different value for the /FORM_SIZE=n qualifier.

1.2.8    /INTERMEDIATE

       /INTERMEDIATE[=filespec]
       /NOINTERMEDIATE (default)

    Positional qualifier.

    Controls whether DSR generates an intermediate output file that
    can be used as input to the DSR table of contents utility and the
    DSR indexing utility. For more information on producing tables of
    contents and indexes, see the descriptions of the /CONTENTS and
    /INDEX qualifiers.

    If you specify the /INTERMEDIATE qualifier, DSR creates an
    output file that has the same file name as the input file and
    a file type of .BRN. To rename the output file, supply a file
    specification that is different from the default values.

1.2.9    /LOG

       /LOG
       /NOLOG (default)

    Controls whether a termination message is displayed at the
    terminal after successful completion of the DSR operation. The
    message states the DSR version number, the number of diagnostic
    messages (if any), the number of output pages, and the output
    file specification.

    If you specify the /INTERMEDIATE qualifier, the message also
    includes the number of index records produced and the number of
    table of contents records produced.

    If there are errors in processing, DSR displays a message on the
    terminal even if the /NOLOG qualifier is specified.

1.2.10    /MESSAGES

       /MESSAGES=(option[,...])

    Positional qualifier.

    Specifies the destination of all DSR error messages. To indicate
    a specific destination, use one or both of the following options:

    OUTPUT     Messages are sent to the output .MEM file.
    USER       Messages are displayed on the terminal (SYS$ERROR).

    If you specify both options, separate them with commas and
    enclose the list in parentheses.

    The default, /MESSAGES=(OUTPUT,USER), sends messages to the
    output .MEM file and displays them on the terminal.

1.2.11    /OUTPUT

       /OUTPUT[=filespec]
       /NOOUTPUT

    Positional qualifier.

    Specifies that an output file is to be produced and optionally
    names it. If you specify the /OUTPUT qualifier without a file
    specification, or if you omit the qualifier, the directory and
    file name default to that of the DSR file. If you specify the
    /NOOUTPUT qualifier, no output file is produced. The output file
    type depends on the input file type. The default input file type
    is .RNO and the default output file type is .MEM.

    The file type defaults to one of the following:

    Output   Input
    File     file

    .BLB     .RNB
    .CCO     .RNC
    .DOC     .RND
    .ERR     .RNE
    .HLP     .RNH
    .LNI     .RNO with /DEVICE set to LN01, LN01E, or LN03
    .MAN     .RNM
    .MEC     .RNT
    .MEM     .RNO with no /DEVICE qualifier specification
    .MEX     .RNX
    .OPR     .RNP
    .PLM     .RNL
    .STD     .RNS

    For a complete list of input file types and the associated output
    file types, see the OpenVMS DIGITAL Standard Runoff Reference
    Manual.

    To change the name of the output file, supply a file
    specification for the value filespec.

    The /OUTPUT=SYS$OUTPUT qualifier causes output to be sent to
    the terminal rather than to a disk file. You can use the value
    SYS$OUTPUT when you are logged in to a hardcopy terminal device
    that uses a daisy wheel.

    The /NOOUTPUT qualifier suppresses the creation of an output
    file. Using the /NOOUTPUT qualifier with the /INTERMEDIATE
    qualifier causes DSR to produce only an intermediate .BRN file
    and not a formatted output file.

    You can also use the /NOOUTPUT qualifier to check an input file
    for errors without using system resources to generate a formatted
    output file.

1.2.12    /PAGES

       /PAGES=string

    Positional qualifier.

    Specifies that only the pages within the specified range be
    generated as output. By default, DSR generates output for all
    pages. Specify the range as follows:

    start-page-number:end-page-number,...

    You can specify up to five ranges (for example, /PAGES="2-9:2-12,
    4-1:4-10, 5-9:5-9, A-1:A-3, and Index-1:Index-5"). You can omit
    the colon (:)  and the end page number on the last range. You can
    omit the quotation marks (" ")  if you specify only one range.
    Page numbers must be specified in their default form, not the
    form specified in a .DISPLAY command. You can specify just the
    appendix letter or name to produce an entire appendix. You can
    specify just the word INDEX to produce an entire index.

    If you specify only a starting page number, output begins at the
    specified page and continues to the end of the file. To output a
    single page, the start range and end range must be the same (for
    example, /PAGES=5:5).

    For an entire appendix, only a letter is required (for example,
    /PAGES=A). For an entire index, only the word INDEX is required
    (/PAGES=INDEX). You can refer to specific appendix or index pages
    with a numeric suffix such as INDEX-10.

    Note that the /PAGES qualifier does not recognize any display
    modes. You must specify the default form of page numbers (5-15)
    rather than any special form you may have specified with the
    .DISPLAY NUMBER command (for example, V-15). For details on the
    .DISPLAY NUMBER command, enter HELP DSR at the DCL prompt.

1.2.13    /PAUSE

       /PAUSE
       /NOPAUSE (default)

    Controls whether DSR pauses after printing each page of output.

    You can use the /PAUSE qualifier to insert single sheets of paper
    or reproduction masters into hardcopy output devices. When output
    is halted, the terminal bell rings to remind you to insert a new
    form. Press the space bar to resume processing.

    Do not use this qualifier in a batch job.

1.2.14    /REVERSE_EMPHASIS

    Positional qualifier.

    Directs DSR to change the order in which flagged text is
    underlined on an output device. If you use this qualifier, the
    printer first prints the characters to be underlined, then issues
    a carriage return without a line feed, and finally prints the
    underscores to underline the flagged text. If you view your file
    on the terminal, the flagged text is overwritten by the underline
    character.

1.2.15    /RIGHT

       /RIGHT[=n]
       /NORIGHT (default except for LN01)

    Positional qualifier.

    Causes the text on each page (including header information) to
    be shifted to the right the number of columns specified by n.
    This qualifier does not affect the page width. If you specify
    the /RIGHT qualifier without specifying a number, text is shifted
    five spaces to the right. If you specify a value of zero or omit
    the qualifier, no shift occurs.

    The defaults (if the /RIGHT qualifier is not specified) for LN01
    files are as follows:

    Mode      LN01     LN01E   LN03

    Landscape 9        13      9
    Portrait  2         2      2

1.2.16    /SEPARATE_UNDERLINE

       /SEPARATE_UNDERLINE[="character"]

    Positional qualifier.

    Prints underlines as separate characters on the next line instead
    of overstriking with underscores on the same line. The value
    specifies the character to be used for the underline character
    and defaults to a hyphen (-).  You can specify the underline
    character as a single printable character or as a number preceded
    by a radix indicator (%D, %O, or %X)  to represent the ASCII
    value of a printable or nonprintable character.

    This qualifier is incompatible with the /[NO]UNDERLINE_CHARACTER
    qualifier.

1.2.17    /SEQUENCE

       /SEQUENCE
       /NOSEQUENCE (default)

    Positional qualifier.

    Controls whether DSR precedes the lines in the output file with
    the line numbers of the corresponding lines in the DSR file.

    For editors that generate line numbers in the input file, the
    /SEQUENCE qualifier causes similar numbering to appear in the
    output file. The line numbers appear in the left margin at the
    beginning of each line of output.

    If the text editor does not generate sequential numbers in the
    input file, sequential numbers are still generated in the output
    file, but without leading zeros.

1.2.18    /SIMULATE

       /SIMULATE
       /NOSIMULATE (default)

    Controls whether DSR uses line feeds or form feeds to advance to
    the top of each page.

    For devices that do not have a form-feed capability, use the
    /SIMULATE qualifier to generate enough blank lines to cause a
    skip to the top of each new page. The /SIMULATE qualifier also
    causes a pause before the first page of output. To continue after
    the pause, press the space bar.

1.2.19    /UNDERLINE_CHARACTER

       /UNDERLINE_CHARACTER[="character"]
       /NOUNDERLINE_CHARACTER

    Positional qualifier.

    Specifies the character to be used for the underline character.
    Defaults to an underscore (_).  You can specify the underline
    character as a single printable character (enclosed in
    quotation marks) or as a number preceded by a radix indicator
    (%D, %O, or %X)  to represent the ASCII value of a printable or
    nonprintable character. A specification of /NOUNDERLINE_CHARACTER
    overrides any .ENABLE UNDERLINING command in the DSR file.

    This qualifier is incompatible with the /SEPARATE_UNDERLINE
    qualifier.

1.2.20    /VARIANT

       /VARIANT="string[,...]"

    Positional qualifier.

    Controls the processing of the conditional commands (.IF, .IFNOT,
    .ELSE, and .ENDIF) by specifying the names of the segments to be
    processed. For descriptions of the conditional commands, enter
    HELP DSR at the DCL prompt.

    You must name conditional structures introduced by the .IF
    command to process them. You must name conditional structures
    introduced by the .IFNOT command to exclude them. You must not
    name conditional structures introduced by the .ELSE command to
    process them. If you specify only one name in a string, you can
    omit the quotation marks (" ").

1.3  –  Examples

    1.$  RUNOFF CHAPT1.RNO

      The RUNOFF command in this example takes the input file,
      CHAPT1.RNO, and writes formatted output to the file CHAPT1.MEM.

    2.$ RUNOFF CHAPT1/RIGHT=10,CHAPT2

      The RUNOFF command in this example produces a CHAPT1.MEM file
      with margins 10 spaces to the right of the margins specified in
      the input file CHAPT1.RNO. It also generates a CHAPT2.MEM file
      whose margins are not affected by the /RIGHT=10 qualifier.

    3.$ RUNOFF/OUTPUT=SYS$OUTPUT TEXT.DAT,INTRO

      The RUNOFF command in this example sends output to the terminal
      rather than to a disk file. The qualifier applies to both the
      input files, TEXT.DAT and INTRO.RNO.

    4.$ RUNOFF/NOOUTPUT/INTERMEDIATE -
      _$CHAPT1,CHAPT2,CHAPT3,CHAPT4,CHAPT5/LOG

      The RUNOFF command in this example generates intermediate
      .BRN files for each of the input files. The .BRN files are
      used as input for the DSR table of contents utility, and for
      the DSR indexing utility. The /NOOUTPUT qualifier suppresses
      the generation of formatted text files for each input file.
      The /LOG qualifier produces a termination message after DSR
      processes each file.

2    /CONTENTS

    Invokes the DIGITAL Standard Runoff (DSR) Table of Contents
    utility to create an .RNT file that can be processed by DSR to
    make a table of contents. The input file for this command is
    an intermediate binary file (.BRN) that is produced with the
    RUNOFF command and the /INTERMEDIATE qualifier. Qualifiers to
    this command allow you to specify the following characteristics
    for table of contents entries:

    o  Using boldface type or underlining for entries

    o  Deepest header level to be included

    o  Running page numbers or chapter-oriented page numbers

    o  Displaying or not displaying section numbers

    For a complete description of the DSR Table of Contents utility,
    see the OpenVMS DIGITAL Standard Runoff Reference Manual.

    Format

      RUNOFF/CONTENTS  filespec[,...] or filespec[+...]

2.1  –  Parameter

 filespec[,...] or filespec[+...]

    Specifies one or more intermediate binary files (.BRN) that
    contain information (chapter titles, header levels, sections,
    and so on) for making a table of contents. To create a .BRN file,
    use the RUNOFF command with the /INTERMEDIATE qualifier. See
    the RUNOFF command for more information on the /INTERMEDIATE
    qualifier.

    If you omit the input file type, the DSR Table of Contents
    utility uses a default file type of .BRN. The RUNOFF/CONTENTS
    command also processes BTC files that the previous version of DSR
    produced.

    For single input files, the DSR Table of Contents utility
    produces an output file with the same file name as the input
    file. The output file type is .RNT.

    If you separate multiple input files with commas (,),  separate
    .RNT files for each input file are created. If you separate
    multiple input files with plus signs (+),  a single .RNT file
    that contains table of contents information for all of the input
    files is created. The default output file name is the same as the
    first input file name; the default file type is .RNT. Wildcard
    characters are not allowed in the file specification.

2.2  –  Qualifiers

2.2.1    /BOLD

       /BOLD
       /NOBOLD (default)

    Controls whether the boldface type specified in chapter and
    header titles in the input file appears in the table of contents.

    If you specify the /BOLD qualifier, the text flagged for boldface
    type in the body of the document is marked for overprinting in
    the finished table of contents.

    If you specify the /NOBOLD qualifier, the text flagged for
    boldface type in the document is not overprinted in the table
    of contents.

2.2.2    /DEEPEST_HEADER

       /DEEPEST_HEADER=n

    Controls how many levels of header levels are output in the table
    of contents. You can specify any number of header levels (up to
    six) to be displayed by changing the value of n.

    The default is /DEEPEST_HEADER=6.

2.2.3    /IDENTIFICATION

       /IDENTIFICATION
       /NOIDENTIFICATION (default)

    Controls whether the current version number of the DSR table of
    contents utility is reported.

2.2.4    /INDENT

       /INDENT
       /NOINDENT (default)

    Controls how many spaces the header levels after level 1 are
    indented in the table of contents.

    If you omit this qualifier, or if you specify the /NOINDENT
    qualifier, all header levels after header level 1 are indented
    2 spaces.

    If you specify the /INDENT qualifier, each header level after
    header level 1 is indented 2 spaces beyond the preceding header
    level.

2.2.5    /LOG

       /LOG
       /NOLOG (default)

    Controls whether the DSR Table of Contents utility displays
    the name of each input file as it is processed and after it
    is processed. The name of each output file created may also be
    displayed. If there are any errors in processing, the DSR Table
    of Contents utility sends messages to the terminal even if the
    /NOLOG qualifier is in effect.

2.2.6    /OUTPUT

       /OUTPUT[=filespec]
       /NOOUTPUT

    Specifies that an output file is to be produced and optionally
    names it. If you specify the /OUTPUT qualifier without a file
    specification, or if you omit the qualifier entirely, the output
    file name matches the input file name. The default file type is
    .RNT.

    You can change the name of the output file by supplying a file
    specification for the value filespec.

    The /NOOUTPUT qualifier suppresses the creation of an output
    file. You can use the /NOOUTPUT qualifier to check an input file
    for errors without using system resources to generate an output
    file.

2.2.7    /PAGE_NUMBERS

       /PAGE_NUMBERS=(option[,...])

    Controls whether the page number references in the table of
    contents are running page numbers or chapter-oriented page
    numbers; also controls how many levels of headers have page
    references listed in the table of contents. You can specify the
    following options:

    o  LEVEL=n

       Specifies that header levels up to and including header level
       n have page numbers listed in the table of contents. The
       default is to display page numbers for six levels of headers.

    o  NORUNNING

       Specifies chapter-oriented page numbers (such as 1-3, 10-42).
       You can specify chapter-oriented numbers for the table of
       contents even if the document does not have chapter-oriented
       numbers. NORUNNING is the default.

    o  RUNNING

       Specifies running page numbers (such as 3, 42). You can
       specify running page numbers for the table of contents even
       if the document does not have running page numbers.

    If you supply more than one option, separate them with commas and
    enclose the list in parentheses.

2.2.8    /REQUIRE

       /REQUIRE=filespec
       /NOREQUIRE (default)

    Allows you to change or delete the heading on the first page of
    a table of contents. The default heading is the word CONTENTS
    centered on the page and followed by one blank line. You can
    either substitute another word as a heading, or have no heading.

    To change the heading, do one of the following:

    o  If you do not want any heading, specify a null file as the
       file specification for /REQUIRE.

       $ RUNOFF/CONTENTS/REQUIRE=nl:

    o  If you want to use a different heading, create or edit a
       file that specifies the heading that you want. Use the file
       that you create as the file specification for the /REQUIRE
       qualifier.

    When you use the /REQUIRE qualifier, the default heading for the
    first page of the contents is not generated. The file that you
    are "requiring" must provide the heading. The file can contain
    both DSR commands that change the format of the first page and
    the text that you want to appear at the top of the page. Or the
    file can contain only DSR commands to format the first page of
    the contents. For example, you can put the command .FIGURE 10
    in the file. This command generates 10 blank lines at the top of
    the first page of the table of contents. You can use these blank
    lines for later pasteup.

2.2.9    /SECTION_NUMBERS

       /SECTION_NUMBERS (default)
       /NOSECTION_NUMBERS

    Controls whether the DSR Table of Contents utility displays
    section numbers in the table of contents. The /SECTION_NUMBERS
    qualifier displays section numbers for all header levels in the
    table of contents. The /NOSECTION_NUMBERS qualifier suppresses
    the display of section numbers for all header levels.

2.2.10    /UNDERLINE

       /UNDERLINE
       /NOUNDERLINE (default)

    Controls whether the underlining specified in chapter and header
    titles in the input file appears in the table of contents.

    If you specify the /UNDERLINE qualifier, the text flagged for
    underlining in the body of the document is underlined in the
    table of contents.

    If you specify the /NOUNDERLINE qualifier, the text flagged for
    underlining in the body of the document is not underlined in the
    table of contents.

2.3  –  Examples

    1.$  RUNOFF/INTERMEDIATE CHPT1,CHPT2,CHPT3

      Before using the RUNOFF/CONTENTS command, you must use the
      RUNOFF/INTERMEDIATE command to create a .BRN file as input for
      the DSR Table of Contents utility. The command line in this
      example creates three separate files: CHPT1.BRN, CHPT2.BRN, and
      CHPT3.BRN.

    2.$  RUNOFF/CONTENTS CHPT1.BRN

      In this example, the RUNOFF/CONTENTS command takes the file
      CHPT1.BRN as input and creates CHPT1.RNT, which can be
      processed by DSR to produce a final table of contents for
      Chapter 1.

    3.$  RUNOFF/CONTENTS/INDENT/NOSECTION_NUMBERS CHPT2

      The command in this example takes the file CHPT2.BRN as input
      and creates CHPT2.RNT. When processed with the RUNOFF command,
      the .RNT file will produce a table of contents in which each
      header level after header level 1 is indented 2 spaces beyond
      the preceding header level. The table of contents will not have
      section numbers listed. See the following example for a sample
      command line for processing .RNT files.

    4.$  RUNOFF/LOG CHPT2.RNT

      The command in this example produces CHPT2.MEC, which is a
      formatted table of contents. You can use the TYPE or the PRINT
      command to view the table of contents.

3    /INDEX

    Invokes the DIGITAL Standard Runoff (DSR) Indexing utility to
    create an .RNX file that can be processed by DSR to create an
    index. The input file for this command is an intermediate binary
    file (.BRN) that is produced with the RUNOFF command and the
    /INTERMEDIATE qualifier (see the RUNOFF command). For a complete
    description of the DSR Indexing utility, see the OpenVMS DIGITAL
    Standard Runoff Reference Manual.

    The formatted index is a 2-column index with balanced columns on
    each page. This index can be used for draft copies or for final
    production. Qualifiers to this command allow you to specify the
    following characteristics for index entries:

    o  Running page numbers or chapter-oriented page numbers

    o  The number of lines of index entries per page

    o  Special text and heading on the first page of the index

    Format

      RUNOFF/INDEX  filespec[,...] or filespec[+...]

3.1  –  Parameter

 filespec[,...] or filespec[+...]

    Specifies one or more intermediate binary files (.BRN) that
    contain information (index entries, page number references, and
    so on) for making an index. To create a .BRN file, use the RUNOFF
    command with the /INTERMEDIATE qualifier. See the RUNOFF command
    for more information on the /INTERMEDIATE qualifier.

    If you omit the input file type, the DSR Indexing utility uses
    a default file type of .BRN. The RUNOFF/INDEX command also
    processes .BIX files that the previous version of DSR produced.

    For single input files, the DSR Indexing utility produces an
    output file with the same file name as the input file. The output
    file type is .RNX.

    If you separate multiple input files with commas (,),  separate
    .RNX files for each input file are created. If you separate
    multiple input files with plus signs (+),  a single .RNX file
    that contains indexing information for all of the input files
    is created. The default output file name is the same as the
    first input file name; the default file type is .RNX. Wildcard
    characters are not allowed in the file specification.

3.2  –  Qualifiers

3.2.1    /IDENTIFICATION

       /IDENTIFICATION
       /NOIDENTIFICATION (default)

    Reports the current version number of the DSR Indexing utility.

3.2.2    /LINES_PER_PAGE

       /LINES_PER_PAGE=n

    Specifies, with the value n, the number of lines of index entries
    on each page of the finished index. This number does not include
    the number of lines required for running heads and feet.

    The default is 55 lines. This value is designed to work properly
    in the default formatting environment of DSR. You must calculate
    the value n if you change the default environment in any of the
    following ways:

    o  If you use subtitles in the document that requires the .RNX
       file.

    o  If you make the page length for the document anything other
       than 58 lines per page.

    o  If you use any .LAYOUT command other than zero.

    To calculate the correct value for the /LINES_PER_PAGE qualifier,
    use the following formula:

    /LINES_PER_PAGE=n
    n = .PAGE SIZE ( the first parameter is length value)
        minus 4 if subtitles are used, minus 3 if no subtitles
        minus the number of lines reserved for .LAYOUT 1,
              .LAYOUT 2, or .LAYOUT 3.

3.2.3    /LOG

       /LOG
       /NOLOG (default)

    Controls whether the DSR Indexing utility displays the name of
    each input file as it is processed and after it is processed, as
    well as the name of each output file created. If there are any
    errors in processing, the RUNOFF/INDEX command sends messages to
    the terminal even if the /NOLOG qualifier is in effect.

3.2.4    /OUTPUT

       /OUTPUT[=filespec]
       /NOOUTPUT

    Specifies that an output file is to be produced and optionally
    names it. If you specify the /OUTPUT qualifier without a file
    specification, or if you omit the qualifier entirely, the output
    file name matches the input file name. The default file type is
    .RNX.

    You can change the name of the output file by supplying a file
    specification for the value filespec.

    The /NOOUTPUT qualifier suppresses the creation of an output
    file. You can use the /NOOUTPUT qualifier to check an input file
    for errors without using system resources to generate an output
    file.

3.2.5    /PAGE_NUMBERS

       /PAGE_NUMBERS=option

    Controls whether the page number references in the index are
    running page numbers or chapter-oriented page numbers. To specify
    the type of page numbers you want, select from the following
    options:

    Option       Purpose

    NORUNNING    Specifies chapter-oriented page numbers (such as 1-
                 3, 10-42). You can specify chapter-oriented numbers
                 for an index even if they do not appear in the
                 document. The NORUNNING option is the default.

    RUNNING      Specifies running page numbers (such as 1, 50, 230).
                 You can specify running page numbers for an index
                 even if the document does not display running page
                 numbers.

3.2.6    /REQUIRE

       /REQUIRE=filespec
       /NOREQUIRE (default)

    Allows you to change the heading on the first page of an index.
    The default heading is the word INDEX centered on the page
    and followed by three blank lines. The substitute heading is
    contained in the file you specify, which can contain DSR commands
    and text.

    To change the heading:

    1. Create or edit a file that specifies the format and the text
       that you want as the heading on the first index page.

    2. Use the file you create as the filespec parameter for the
       /REQUIRE qualifier.

    When you use the /REQUIRE qualifier, the default heading for the
    first page of the index is not generated. Your file must provide
    the heading. The file can contain DSR commands and text that you
    want to appear at the top of the first page of the index, or it
    can contain only DSR commands. For example, you can put the DSR
    command .FIGURE 10 in the file. This command generates 10 lines
    of white space at the top of the first page of the index. You
    can use these blank lines for later pasteup. For a sample file
    that changes the index heading, see the OpenVMS DIGITAL Standard
    Runoff Reference Manual.

    If you are adding lines of text or white space to the heading
    on the first page of the index, you must allow space for this
    addition. Use the /RESERVE=n qualifier to provide the space you
    need.

    See the /RESERVE qualifier for more information.

3.2.7    /RESERVE

       /RESERVE=n
       /NORESERVE (default)

    Allows you to reserve space at the top of the first page of the
    index for text or white space that you want to include with the
    /REQUIRE=filespec qualifier. Determine how many lines of text or
    white space you are adding to the top of the first page of the
    index. Use this number as the value n for the /RESERVE qualifier.

3.3  –  Examples

    1.$  RUNOFF/INTERMEDIATE CHPT1,CHPT2,CHPT3

      Before using the RUNOFF/INDEX command, you must create a .BRN
      file as input for the DSR Indexing utility. The command in this
      example creates three separate files: CHPT1.BRN, CHPT2.BRN, and
      CHPT3.BRN.

    2.$  RUNOFF/INDEX CHPT1.BRN

      In this example, the RUNOFF/INDEX command takes the file
      CHPT1.BRN as input and creates CHPT1.RNX, which can be
      processed by DSR to produce an index for Chapter 1.

    3.$  RUNOFF/INDEX/LINE_PER_PAGE=52 CHPT2

      In this example, the RUNOFF/INDEX command takes the file
      CHPT2.BRN as input and creates CHPT2.RNX. The .RNX file
      produces an index with 52 lines of index entries per page.
      The lines per page had to be adjusted because the writer used a
      page layout with the page numbers centered at the bottom of the
      page (.LAYOUT 1, .LAYOUT 2, .LAYOUT 3). This page layout takes
      up three more spaces than .LAYOUT 0, which is the default for
      DSR. To produce the final index, you must use the .RNX file as
      input to DSR. See the following example.

    4.$  RUNOFF CHPT2.RNX

      In this example, the RUNOFF command produces CHPT2.MEX, which
      is a formatted index. You can type or print this file to view
      the index.
Close Help