Library /sys$common/syshlp/helplib.hlb  —  RUNOFF  /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[+...]

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.

2  –  Qualifiers

2.1    /IDENTIFICATION

       /IDENTIFICATION
       /NOIDENTIFICATION (default)

    Reports the current version number of the DSR Indexing utility.

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.

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.

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.

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.

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.

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  –  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