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 – 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.
2 – Qualifiers
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
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.
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.
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.
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 (" ").
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.