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.