Trailing-Edge
-
PDP-10 Archives
-
BB-J710A-BM
-
tools/dsr/dsr.doc
There is 1 other file named dsr.doc in the archive. Click here to see a list.
Notes for DSR, version 1(115)
1.0 INTRODUCTION
DSR (DEC Standard RUNOFF) is an enhanced version of RUNOFF which is used
as an internal tool on several of Digital's systems. It is being made
available to DECSYSTEM20 customers as catagory "C" software (Customer
installed and supported). Since this is not vendor supported software,
all SPRs will be treated as suggestions. DSR Features are highlighted
in the "help" files (DSR.HLP, DSRINP.HLP). Full documentation can be
found in the manual (available for purchase from the SDC):
DEC Standard RUNOFF
(DSR) User's Guide
Order No. AA-J268-TK
DSR will not accept TOPS20 long file names as does RUNOFF. Because it
is a TOPS-10 compatible program, file names and extensions are
restricted to a maximum of 6 and 3 characters respectively.
The form of the command line to DSR is:
@DSR OUTPUT=INPUT
or
@RU DSR
*OUTPUT=INPUT/SWITCHES
or
@DSR
*OUTPUT=INPUT/SWITCHES
On the DECSYSTEM20, the DSR.EXE file cannot be renamed if you want the
@DSR OUTPUT=INPUT form of the command line to work. This is because DSR
rescans the command line in order to bypass its name (which it believes
to be DSR).
In the text that follows the term "new RUNOFF" is used to refer to DSR
and the term "old RUNOFF" is used to refer to the normal version.
2.0 NEW FEATURES
The following are features of the new RUNOFF.
NOTE
This list of new features is in reverse
order. I.e., the features most recently
added are near the top of the list.
1. On VAX/VMS installations, RUNOFF now returns severity codes
consistant with other VAX/VMS utilities. A severity code of 1
is returned in the "normal" case, when there have been no error
messages. A severity code of 4 is returned when RUNOFF has not
generated any output file; this happens as the result of an
invalid command line switch, or the input or output file cannot
be opened. A severity code of 2 is returned if RUNOFF
generates an output file, but errors were detected.
Note that system messages are suppressed (i.e., bit 28 of the
condition value is set).
2. Overstriking now influences indexing, as follows:
Overstriking is handled just like other emphasis; overstriking
is defined to be more emphasis than underlining, but less than
upper case. NOTE THAT THE ACTUAL OVERSTRIKE SEQUENCE IS NOT
TAKEN INTO ACCOUNT. THIS MEANS THAT OVERSTRUCK ENTRIES HAVING
IDENTICAL SPELLING AND DIFFERING ONLY IN THE CHARACTERS USED IN
OVERSTRIKING WILL BE MERGED INTO A SINGLE ENTRY.
If you choose to generate your index via the TCX method,
overstriking will appear in the resultant index.
Currently, overstriking is not displayed in an index generated
by means of the .DO INDEX or .PRINT INDEX commands, althought
the sorting takes place as described previously.
3. New abbreviations. You can abbreviate the .END FOOTNOTE
command as .EFN. You can abbreviate .NUMBER RUNNING as .NMR.
You can now say .[NO]FLAGS ACCEPT instead of .[NO]FLAGS QUOTE;
ACCEPT is a better name for the flag than is QUOTE.
4. New page layout supported, .LAYOUT 3,n. The page arrangement
is the same as for .LAYOUT 0, except that now, centered at the
bottom of the page, a running page counter appears, enclosed in
a dash-space combination. The running page counter is just a
simple page counter that doesn't "know" about chapters, etc.
Also, there's no display characteristics supported other than
decimal. Note that when you run TOC you can specify which type
of page number you want. Note that when you run TCX you can
specify which type of page number you want. Currently, there
is no command that lets you get running page numbers into the
one-column index generated by .PRINT/DO INDEX commands.
5. New command .NUMBER RUNNING that's used to specify/modify the
running page counter. Parameters are just like for
.NUMBER PAGE. Side effects and restrictions are identical.
Currently, the only way of getting them to appear in the
document is to use .LAYOUT 3,n (see above). They are also
available via TOC and TCX. See the .DOC files for these
utilities.
6. The flag pair ^< can be used to force all letters to upper
case.
7. The /MESSAGES switch can be used to control where error
messages appear. See the description, below.
8. The /FORMSIZE switch can be used to tell RUNOFF about printer
forms longer/shorter than "normal". See the description,
below.
Note that previously, RUNOFF would always output a formfeed in
response to a .PAGE command, even if you had already filled a
page; this would sometimes result in extra blank pages being
output. But it had the advantage of generating a file in which
every page was also an SOS type of page. Now, you won't get a
formfeed if you're already at the position specified on the
/FORMSIZE switch; so, to get back the "old" file organization
specify some large value for /FORMSIZE.
9. You can now control how dark bolded output appears. See
description of /BOLD switch, below.
10. New switch /DEBUG. See description below.
11. Tabs have been made easier to use. In the list of tabs
settings given on the .TAB STOPS command, each setting can now
be a signed number to indicate an adjustment to the current
setting. Existing files do not have to be changed. HOWEVER,
there is one incompatibility that is EXTREMELY unlike to show
up, as follows: before this change was made you could use a
"+" before a tab setting, except that no adjustment would
occur. For example, the following two commands USED to be
equivalent.
.TS+20+30+40
.TS 20,30,40
Also, there are no longer any validity checks made on the
resultant tab settings. This means that you can have negative
tabs, etc; but such tab settings simply don't ever get used
when tabs are expanded.
12. The commands .ENABLE TOC and .DISABLE TOC are now available to
control what is written into the .BTC file. (Abbreviation for
.ENABLE TOC is .ETC, abbreviation for .DISABLE TOC is .DTC.) If
you say /CONTENTS the default is .ENABLE TOC, which means that
all header levels and chapter/appendix titles will be written
into the .BTC file. If you say .DISABLE TOC, nothing will be
written to the .BTC file, even information given on a .SEND TOC
command.
NOTE: If you don't say /CONTENTS you cannot get out of
.DISABLE TOC mode, even by specifying .ENABLE TOC.
13. You can now send information directly to the .BTC file. This
is done via the .SEND TOC command (abbreviation .STC). The
format of the .SEND TOC command is
.SEND TOC n,text
The parameter n, if present, must be a number. This number
serves as an identifier associated with the information that is
written to the .BTC file. ***NOTE*** The use made of "n"
depends on the version of TOC used to process the .BTC file;
if you use the version of TOC supplied with RUNOFF, either
specify 0 (zero) for n, or leave it out entirely. The text
parameter will be parsed by RUNOFF so that you can use RUNOFF's
flags to specify underlining, etc. The INDEX flag is not
recognized on a .SEND TOC command line.
For example, suppose you wanted the following runoff command
.CENTER;APPENDICES
to appear in the .RNT file generated by TOC. Then you would
insert in your .RNO file the following .SEND TOC command:
.SEND TOC .CENTER;APPENDICES
Note that RUNOFF and TOC "normalize" underlining, bolding, and
overstriking flags so that if they are used in the text
argument of the .SEND TOC command they will be rearranged (and
translated to the "standard" flags if others are in use).
Note that there is no case translation done on letters, unless
you specify it's to be done via flags.
14. As of version 1(54) of RUNOFF, there is support for generating
a table of contents. See the description of the /CONTENTS
switch, below, for further information.
15. There are additional formatting possibilities available for
list elements. They are selected by means of the .DISPLAY
ELEMENTS command (abbreviation .DLE). The format of this
command is
.DISPLAY ELEMENTS lch,DD,rch
All parameters are optional, in which case the option currently
used is not modified. The parameter DD is the same as for the
.DISPLAY LEVELS command (see below). It determines how the
list element will be displayed. The paramaters rch and lch are
of the form "x" or 'x' or "" or '' (including the quotes) and
specify single characters to be output to the right and left
(rch and lch) of the list element. For example, a command
formatted as
.DLE "(",RU,")"
can be used to generate list elements looking like (I), (II),
(III), etc. The usual setting for list elements is
.DLE "",A,".". The proper location for the .DLE command is
AFTER the opening .LS command, and before the first .LE command
for that list. If you have specified a "bulleted list" a .DLE
command overrides it.
16. You can now get header level numbers displayed the same ways as
the components of a page number. The command is
.DISPLAY LEVELS (abbreviation .DHL). The format is as follows:
.DISPLAY LEVELS DD1,DD2,....DD6
DD1 through DD6 are the same as the DD parameter of the
.DISPLAY CHAPTER, .DISPLAY APPENDIX, .etc commands (see below).
DDn determines how the nth header-level number is displayed.
If a DDn is not specified the current display characteristics
are left unchanged.
17. Besides $$TIME and $$DATE, the items $$YEAR, $$MONTH, $$DAY,
$$HOURS, $$MINUTES, and $$SECONDS are supported. The latter
three will be generated with a leading zero, if necessary, to
make sure that they are precisely two digits in length.
$$MONTH produces the month completely spelled out, with only
the first letter capitalized.
18. You can use either numbers or letters as arguments to .NUMBER
PAGE, .NUMBER SUBPAGE, .NUMBER CHAPTER, and .NUMBER APPENDIX.
Note that the type of argument does NOT determine how that item
is displayed later. That is determined by the appropriate
.DISPLAY command (see below).
19. You can now specify how the number, chapter, appendix, and
subpage constituents of a page number are to appear in your
document. This accomplished through commands given as
.DISPLAY XXXX DD
XXXX can be NUMBER, CHAPTER, APPENDIX, or SUBPAGE; it
indicates which part of the page number you are referring to.
DD is a display descriptor that specifies how the item is to
appear. Valid DDs are
D Decimal
O Octal
H Hex
LU Letters, all upper case
LL Letters, all lower case
LM Letters, first one capitalized
(i.e., mixed)
RU Roman numerals, upper case
RL Roman numerals, lower case
RM Roman numerals, mixed case
If you don't specify DD then the standard DD for the specified
XXXX is supplied as a default.
Abbreviations are as follows: .DAX for .DISPLAY APPENDIX, .DCH
for .DISPLAY CHAPTER, .DNM for .DISPLAY NUMBER, and .DSP for
.DISPLAY SUBPAGE.
The display characteristics will be carried over into any index
entries. And the indexing routines DO distinguish between page
numbers that are identical but have different display
characteristics.
The appropriate place to give one of these commands is at the
top of a page. In particular, be careful about giving one of
these commands in the middle of your document. For example, if
you are going to start a chapter/appendix, and you want to give
one of these commands, and you had some previous text
formatted, insert a .PAGE command before the .DISPLAY command,
even though the .CHAPTER/APPENDIX command will start a new page
anyway.
20. Another page layout, set by specifying
.LAYOUT 2,n
The parameter n is as for .LAYOUT 1,n (see below) and has the
same meaning/restrictions. Otherwise, the layout is as
follows:
The title and subtitle appear at the top of the page, and
appear flush to the right/left depending on whether the page is
"odd" or "even". Odd pages have the title/subtitle flush to
the right. Even pages have the title/subtitle flush left. By
definition, the first page of a document is odd. Also, the
first page of a section started via .CHAPTER, .APPENDIX, or
.DO INDEX is odd.
21. You can now specify the date that is generated when requested.
This is done via the .SET DATE command (abbreviation SDT). The
format is as follows:
.SET DATE dd,mm,yy
**OR**
.SET DATE (without parameters)
The parameters dd, mm, and yy specify the day, month, and year,
respectivally, or adjustments thereto. For example, the
following command
.SET DATE 12,3,1943
causes RUNOFF to generate
12 MAR 43
If later you say
.SET DATE -5,,+10
then the next time RUNOFF generates the date it will appear as
07 MAR 53
If you don't specify any parameters then the current system
date is supplied.
NOTE: If you say .DATE to get the date generated, the date
supplied on each subtitle line will be that date specified via
the last .SET DATE command that appeared before the page was
started. However, if you construct a title/subtitle line using
$$DATE, the date is computed only once, namely when $$DATE is
expanded.
22. You can now specify the time that is generated when requested.
This is done via the .SET TIME command. The format is as
follows:
.SET TIME hh,mm,ss
**OR**
.SET TIME (without parameters)
The parameters hh, mm, and ss specify hours, minutes, and
seconds, respectivally, or adjustments thereto. For example,
the following command
.SET TIME 14,04,43
causes RUNOFF to generate
14:04:43
If later you say
.SET TIME +5,,-10
the next time RUNOFF generates the time the result will be
19:04:33
None of hh, mm, and ss can be less than zero. The maximum
value for hh is 23; that for mm and ss is 59.
If you just say .SET TIME with no parameters you get the
current system time. The short form for .SET TIME is .STM.
NOTE: If you say $$TIME in a title line, for example, the time
is only computed once, when the title line is set up; it is
not re-computed each time the title is output.
23. The .LAYOUT command is now supported. Two page layouts are
provided. The .LAYOUT command can be given as follows:
o .LAYOUT 0
This is the default. Pages are arranged as they currently
are. The '0' (zero) is not optional.
o .LAYOUT 1,n
This form is used to get titles/subtitles centered at the
top of the page and the page number centered at the bottom.
Note that 'n' is required and must be greater than zero.
The second parameter, 'n', reserves a footer area of 'n'
lines at the bottom of each page. The page number will be
centered at the bottom of the footer area. This means that
there will always be AT LEAST 'n-1' blank lines between the
last line of text and the centered page number.
The 'n' lines are taken from the page size as given on the
.PAGE SIZE command. All .TEST PAGE commands (explicit or
implicit) check to see that the specified number of lines
are available above the footer area. Footnotes are output
above the footer area.
The short form of .LAYOUT is .LO.
NOTE: You can't use .LAYOUT to modify the format of the top of
a page started by .CHAPTER, .APPENDIX, or .DO INDEX.
24. .AUTOSUBTITLE now takes an optional numeric parameter that
specifies the highest header level that is to be made a
subtitle. .NO AUTOSUBTITLE turns off .AUTOSUBTITLE, but the
next .AUTOSUBTITLE restores the previous status. Existing
files don't need to be changed. For example,
.AUTOSUBTITLE 99
causes all header levels to be made into subtitles.
.AUTOSUBTITLE 1
followed sometime later by
.AUTOSUBTITLE +1
has the same effect as
.AUTOSUBTITLE 2
The command sequence
.AUTOSUBTITLE 5
.NOAUTOSUBTITLE
.AUTOSUBTITLE
resumes .AUTOSUBTITLE 5.
Note the following important interaction with "runon" header
levels: if you say
.hl3;whatever
"whatever" will not be part of the subtitle because it comes
after the ';', which terminates the text part of the header
level.
25. New command .STYLE HEADERS (abbreviation .STHL) that can be
used to control header level commands. The command takes up to
three numeric parameters, (n1, n2, n3). N1 specifies the first
header level which is to be a "run-on" header level. N2
specifies the largest header level for which all letters in the
header are to be translated to upper case. N3 specifies the
largest header level for which only the first letter of each
word in the header is to be capitalized.
If no .STYLE HEADERS command is ever specified, RUNOFF acts as
if .STYLE HEADERS 3,1,6 had been given. You can change just
one of the values by specifying only the one to be changed.
E.g., the command .STHL ,99 specifies n2 but leaves n1 and n3
unchanged.
The case rules are applied as follows:
1. If N2 and N3 don't specify any "valid" header levels (i.e.,
less than 1 or greater than 6) then the text on all
.HEADER LEVEL commands is left in the input case (unless,
of course, you put in some flags on the .HEADER LEVEL line)
2. The N2 parameter takes precedence over the N3 parameter, so
if you specify, for example both N2 and N3 the same, the N2
parameter determines the case rules. (The default case
rules are a good example of how this works.)
Finally, there is no adjustment implied by using signed numbers
(in contrast to many other RUNOFF commands).
26. New command .SET PARAGRAPH which has the same parameters as
.PARAGRAPH. The command does everything a .PARAGRAPH does
except start the paragraph.
27. New commands .ENABLE/.DISABLE HYPHENATION as synonyms for
.HYPHENATION/.NO HYPHENATION. The latter two commands have
been retained for compatibility with -11 versions of runoff.
28. You can now get the date and time generated into your output
file. To do it first say
.FLAG SUBSTITUTE
The date/time gets substituted for occurrences of
$$DATE/$$TIME. To turn off recognition of the SUBSTITUTE flag
(i.e., restore the default state) say
.NO FLAG SUBSTITUTE
Finally, if you want to use some other character as the
SUBSTITUTE flag, say
.FLAG SUBSTITUTE ch
where "ch" is the character to be used instead of "$".
Generation of the date/time works wherever the standard flag
characters are valid, including titles, header levels, and
indexing commands.
29. You can now give a negative value as the second operand to the
.paragraph command. It functions just like .SKIP with a
negative value.
30. Support for a two-column index. See the description of the
/INDEX switch.
31. The .DATE and .NO DATE commands, for having/not having the
current date generated on the subtitle line, now work.
NOTE: The date will appear only if .LAYOUT 0 is in effect (see
above).
32. You can now get index hits echoed back, to help you debug the
index. See the description of the /DEBUG switch, below.
33. User controlled hyphenation is now available. Say
.FLAG HYPHENATE to activate it. Then insert a '=' between
those parts of a word that can be broken up. If the remainder
of the word will not fit on the current line, the new RUNOFF
will insert a '-' for you at that point; otherwise no '-' will
be generated.
The HYPHENATE flag is manipulated like other flags. It's
disabled, initially. Default character is '='.
NOTE: The HYPHENATE flag causes other actions associated with
end of word processing to take place, such as terminating a
phrase flagged via the INDEX flag, or turning off the
CAPITALIZE flag at that point.
34. New flag called BREAK that can be used to force a word break,
but without the insertion of an inter-word space. The facility
is useful for indicating to the new RUNOFF where a word can be
broken if it does not fit on the current line.
The flag is initially disabled. Default character is '|'
(vertical bar). Say .FLAG BREAK and insert a '|' between the
parts of a word where it is ok to separate them. Note that
this is similar to hyphenation, except that no '-' is
generated.
Note: the BREAK flag causes other things to happen that are
associated with the end of a word. For example, it will
terminate a word being entered into the index via the INDEX
flag, and turn off the CAPITALIZE flag, if it's on.
35. You now have full control over telling the new RUNOFF what
constitutes the end of a sentence. This is achieved via the
PERIOD flag (initially disabled, default character '+'). The
PERIOD flag can be manipulated just like other flags.
You put the '+' AFTER the character that you want to indicate
is the end of a sentence, i.e., where two spaces are to be
inserted.
The PERIOD flag is entirely independent of the .PERIOD and
.NO PERIOD commands. This means that you can say
.NO PERIOD.FLAG PERIOD and take over complete end-of-sentence
control yourself. Or you can use both .PERIOD and .FLAG PERIOD
to increase the number of cases where end-of-sentence spacing
is inserted. However, like the .PERIOD command, the double
inter-word spacing works only if .FILL is in effect.
36. The '!' that is used in the context '.!' to introduce a comment
is now a flag called COMMENT. You can use the various .FLAG
commands to manipulate it.
37. You can now control the number of blank lines between elements
of a list. The number of lines to be skipped between elements
of a list is specified as the first parameter on the opening
.LIST command. If no value is given, the paragraph skip in
effect at that time will be used.
For example,
.LIST 0
.LE;first
.LE;second
.LE;third
(etc)
generates
1. first
2. second
3. third
(etc)***NOTE: no blank lines between entries!!
Note that this brings the new RUNOFF into line with various old
-11 versions of runoff.
38. You can now draw lines and generate repetitive patterns with
the new RUNOFF. The command is .REPEAT <count>,'XXXXXX'. For
example,
.repeat 20,'*'
generates ********************.
Let the quoted string character positions, exclusive of the
quotes, be A.....Z. 'A' is processed like the first character
of a new record, except that there is an implied .NO SPACE
command before it. Also, 'A' cannot be a '.'; and
autoparagraph and autotable don't apply. 'Z' is like the last
character of a record. At the end of an iteration, after
processing 'Z', the appropriate end-of-record action is taken;
if you said .NO FILL, this means you get a new line.
Flags, spaces, and tabs in the character string have their
usual meanings. Therefore, you can generate a string of
underlined '*'s with the command .REPEAT 50,'&*'. Likewise
don't expect the command .REPEAT 50,'_' to work as you might be
tempted to expect; what you (probably) want is .REPEAT
50,'__'.
.REPEAT can be abbreviated as '.RPT'.
39. 'Bullets' are now available as an alternative way of marking
list elements. To get a "bulleted" list specify a second
parameter on the .LIST command; it must be a single quoted
character (between 's or "s) which is to be the bullet. E.g.,
.LS,'*' causes following list elements (for that list depth,
and until the matching .END LIST command) to be marked with a
'*' instead of numbered.
40. You can get "run-on" HEADER LEVEL 3s without the '-' by not
putting any text on the line with the .hl command. For
example,
".hl3;this text will be filled and justified."
(REMEMBER, ';' is like end-of-record for most commands.) But
note the interaction with table of contents generation; the
only information that gets written to the table of contents
(from a .HL command) is that text that appears BEFORE the
semi-colon or end-of-line marking the end of the command. So
if you use this capability, be aware that there will be no
corresponding entry in your table of contents.
41. The .REQUIRE command can be used to pull pieces of a document
together. (.REQUIRE "<file-spec>", e.g. .require
"prjpln.toc").
.REQUIRE can be abbreviated '.REQ'.
42. Bolding is available (.FLAG BOLD ch, where default ch is *,
flag initially disabled.). Bolding is used like underlining;
you can turn it on and off like underlining (^* and \*) as well
as specify it for a single character.
Characters that are bolded are printed darker than characters
that are not bolded.
43. Overstriking is available (.FLAG OVERSTRIKE ch, default ch is
%, flag initially disabled) e.g., =%/ produces a "not equal"
sign.
Overstriking is strictly on a "per-character" basis; it cannot
be turned on and off for an extended range, as can underlining
and bolding.
44. .AUTOSUBTITLE and .NOAUTOSUBTITLE commands allow/disallow
redefinition of subtitles by .HL1s.
45. Instead of having to live with the case rules set up for header
levels and indexing, you can now use ^^ to force text to be
taken "as is", or \\ to force it to lower case.
46. Error messages and warnings (but not the page count and summary
information) are written into the output file as well as
displayed on the tty:.
47. New indexing command .ENTRY (abbreviation "Y") with syntax like
.SUBINDEX. Result is same as .SUBINDEX, except that no page
number is attached. This means you can now put things like
xyz
see grumble
in the index.
48. New commands .ENABLE UNDERLINING, .DISABLE UNDERLINING,
.ENABLE BOLDING, .DISABLE BOLDING, .ENABLE OVERSTRIKING,
.DISABLE OVERSTRIKING, .ENABLE INDEXING and .DISABLE INDEXING
for enabling/disabling effects of related flags/commands while
still allowing their recognition.
49. In a .VARIABLE command, the two characters (flags) following
the variable name are now optional. They default to space.
50. Nested .IFs work correctly.
51. If change bars get enabled in the middle of a document, the new
RUNOFF remembers that fact for subsequent lines, so that the
remainder of the document is shifted right uniformly.
52. The line count on a .FOOTNOTE command is now an optional
parameter. If present, it must match the number of lines
actually generated by the footnote; if present and the count
is wrong you get an error message. If absent, RUNOFF counts
for you.
53. It is possible to have footnotes and still say .NO PAGING. The
footnotes appear at the end of the document. (The old runoff
went into a loop).
54. Use of variants has been made much easier. Now, the only need
for the .VARIABLE command is to supply the /DRAFT flags (the
default /DRAFT flags are spaces). Variables mentioned on a
/VARIANT switch are TRUE. All others are FALSE.
55. It is possible to enter bolding AND underlining information
into the index. Within the index the order of entries is as
follows:
1. All special characters come before letters. Numbers are
considered special characters, as are spaces and control
characters.
2. All entries that start with the same "naked" character are
grouped together. This means for example, that all entries
starting with the letter 'a' are together, independent of
case, bolding and/or underlining.
3. Entries are ordered according to a lexical sort that is not
identical to simply sorting on the internal representation.
The more emphasis a character has the higher up in the set
of entries it appears. In terms of emphasis, upper case
for a letter gives it the most emphasis. Underlining
provides the next level of emphasis, and bolding supplies
the least emphasis. This means for example, that in the
index, all entries starting with 'E' appear before all
entries starting with 'e'; but they occur after all
entries starting with 'D' or 'd'. A bolded and underlined
'E' appears before just underlined 'E's. An underlined 'E'
appears before a bolded 'E'. A bolded 'E' appears before a
simple 'E'.
56. There are many more error messages in the new RUNOFF. Also,
error detection is improved. This means that some files that
previously went through old RUNOFF without errors may generate
error messages.
57. When the new RUNOFF puts out a message, and the text contains a
control character, the character is shown in the message.
58. New RUNOFF is more consistant and forgiving as far as how lists
of parameters can be input. The basic rules are as follows:
o There need be no spaces or tabs before the first parameter
of a command, if the first character of that parameter is
not a letter. This rule is unchanged from old runoffs.
o Between parameters, no spaces or tabs or comma is needed if
it is clear from looking at the parameters, or from the
definition of the command, what the parameters are.
You can use this fact even to leave out parameters, where
it is clear what would normally be expected. E.g., the
command '.ls"o"' is ok because RUNOFF can see that there is
no number after '.le', and so it correctly takes "o" as the
second parameter.
o The separator can be either any number of spaces and/or
tabs, or a comma surrounded by any number of spaces and/or
tabs.
3.0 DIFFERENCES
In general, there should be no difference between output produced by old
and new RUNOFF. Many files have been put through both old and new
RUNOFF and compared to check for differences. Nevertheless, there is a
difference in processing that might lead to differences in results.
The following list describes those cases when old and new RUNOFF produce
different results. In many cases the differences are due to bugs in the
old runoff.
1. The new RUNOFF tends to accumulate information until it uses
it. Only then is that information checked for correctness.
This means that there is a bit more freedom regarding the
ordering of certain commands. The old runoff checked
information as it got it, not when it used it. After having
looked at many many RUNOFF files the experience is that the new
RUNOFF will usually make sense out of those things that the old
one did badly. However, there are some subtle differences.
2. A .PAGE command does not cancel pending indentation in the new
RUNOFF.
3. If you specified .SPACING 2 to the old runoff, it would
generally not put text on the last line of the page. The new
RUNOFF does write on the last line of the page.
4. The .SPACING command takes effect sooner than in the older
version. Basically, the old version always skips ".SPACING"
lines after a line of text before picking up the next line or
command. The new version skips ".SPACING" lines before
outputting a line of text, and then gets the next line or
command.
The old version was wrong.
5. The new RUNOFF does not process/recognize .TYPESET/.SELECT
commands. These lead to error messages.
6. The syntax of the .VARIABLE command has been changed slightly.
The old one did not allow numbers in the variable name. The
new one does.
See also under "MISCELLANEOUS".
7. The new RUNOFF ignores fewer flags/characters than the old one.
This means that flags/characters that are left in input files
as artifacts of battles with old runoffs will now be looked at.
8. The new RUNOFF makes it more difficult to have the same
character representing more than one flag. In particular,
attempting to use the UNDERLINE, BOLD, OVERSTRIKING and QUOTE
flags to represent more than one flag will give an error
message. If you really want to have a single character
representing more than one flag say .NO FLAGS ALL before your
.FLAGS whatever ch command, and then .FLAGS ALL afterwards.
9. The new RUNOFF does not get mixed up when you say "<\\".
10. The old runoff does not turn off a '<' (capitalize flag) when
it encounters a '>' (subindex flag) while processing a
.SUBINDEX command.
The new RUNOFF recognizes a subindex flag as terminating a
'<'ed sequence.
11. In the old runoff, if you said ^^ before a .header level
command, some header levels would not have all letters
translated to the "correct" case. The new RUNOFF uses the case
rules specified by the most recent .UPPER CASE or .LOWER CASE
command.
The old runoff was wrong.
12. Because of the more uniform handling of lists of parameters you
can now say '.hl1,abc', which is the same as '.hl1abc'. This
means that if you have a header level having a text parameter
that starts with a comma, the comma will be looked at as just a
parameter separator and discarded. Quote the comma using the
QUOTE flag if you really need it.
13. In new RUNOFF, .HEADER LEVEL commands cancel pending
indentation and "autoed" paragraphs. This is a difference, and
does not represent a bug in either the old runoff or the new
RUNOFF.
14. The old runoff will adjust your paragraph indentation setting
whenever you issue a .LM command. This meant that you could
not temporarily have a left margin that was inconsistant with
the .PARAGRAPH command setting, even if you did not intend to
use a .PARAGRAPH command at that place, and reset your left
margin later; under certain circumstances that lead to
erroneous error messages. And in at least one instance the old
RUNOFF fails to detect an error situation that it is trying to
detect.
The new RUNOFF leaves your .PARAGRAPH settings alone.
15. Consider the following case: a line of text ends with a '.'
followed by a space; further, the number of characters on the
input record is exactly equal to the page width (the count
includes the space after the '.'); further, the text line is
followed by a command such as .SKIP or .BREAK. In other words,
the input line would fit exactly within the margins of the
page.
The old runoff justifies the line; it shouldn't. The new
RUNOFF does not justify the line.
16. The old RUNOFF did not check tab settings thoroughly enough,
with the result that it was possible to force a word to extend
past the right margin. The new RUNOFF checks more thoroughly
and does not allow it.
17. When the old runoff discovers a tab that it cannot expand, but
there are some tab settings, it arbitrarily tabs right some
amount, apparently past the right margin. The new RUNOFF
handles the unexpandable tab as if it were a simple space.
18. After .TITLE or .SUBTITLE, the old runoff skipped precisely one
space, if it was present. The new RUNOFF skips all leading
spaces and tabs in front of the title.
19. Indentation, as specified by the .INDENT command, is not done
until some text is found that is to be indented. The old
version generates the required number of spaces as soon as
indentation is specified. This leads to a difference in how
tabs are expanded. In the old version, an .INDENT command in
front of a line starting with a tab results in "double"
indentation: once as specified by the .INDENT command, and
again, as specified by the tab setting.
The new RUNOFF's processing is simpler: the tab overrides the
indentation, so that the text is moved right only by the amount
specified by the tab setting. The .INDENT command is handled
just like a .BREAK in this case.
20. The old RUNOFF erroneously put the last digit of the page
number of an appendix out past the right margin. The new
RUNOFF does it correctly. But this means that if you FILCOM
results, all appendix title lines that have page numbers will
not compare.
21. Text entered into the index via one of the indexing commands
is, by definition, associated with the last word of text that
occured before that command. In other words, indexing commands
belong immediately after the word of text to which they refer.
It is not clear exactly what the old runoff does. To date, no
indexing differences have been discovered that have anything to
do with the topic mentioned here.
22. If you used the index flag in a title/subtitle/chapter-heading,
the old RUNOFF didn't compute the width of the text correctly.
The result was lines centered even worse than usual, or a page
number pulled to the left a bit. The new RUNOFF does not have
that problem.
23. If you say .DO INDEX in a document that does not contain
chapters old runoff uses ' to ' to join adjacent page
references in the index. New RUNOFF uses a '-'.
It is not clear if this is a bug or feature; I have decided it
is a bug in the old runoff.
24. If, for a particular entry in the index, the list of page
numbers is so long that they don't fit on a single line, then
occasionally there is a difference between how many entries are
put on a line.
This is probably no bug, but merely a minor difference; the
difference shows up exceedingly rarely.
25. The old RUNOFF allowed you to do things such as skip a page by
forcing a FORMFEED into the output. The new RUNOFF does not
support the idea of having control characters in the input to
force things to happen for which there is an equivalent
command.
26. NULLs and DELs are ignored only in "normal" text. Control
characters (including NULL and DEL and FORMFEED) in the middle
of commands are significant characters.
27. The old RUNOFF tended to not center lines correctly. The new
RUNOFF does it right.
28. The old RUNOFF tended to forget to put page numbers on the tops
of pages in the index. The new RUNOFF does it correctly.
29. Footnotes are now expanded as soon as they are encountered
rather than being saved until they are needed. This means
that, except for case translation rules, they use the RUNOFF
environment in effect when the .FOOTNOTE command is
encountered, not some other arbitrary environment.
Case translation rules are determined by the most recent
.UPPER CASE or .LOWER CASE command. They are not "inherited"
from flags set in the main body of text.
30. The new RUNOFF saves footnotes in a file called '001RNO.TMP'
until the footnotes are needed. The file is NOT deleted when
RUNOFF terminates. However, RUNOFF will overwrite it on
subsequent runs.
31. The old RUNOFF sometimes generated extra spaces for subindexed
entries in the index; the result was improper indentation.
The new RUNOFF does it correctly.
32. When sorting the index, it makes a difference to the old RUNOFF
as to exactly how you got spaces between words; although two
entries had the same visual effect, they would sometimes not be
merged correctly. The new RUNOFF does not suffer from this
deficiency.
33. The page count output by the new RUNOFF after termination of a
document may be different than that given by the old RUNOFF.
Old runoff counted physical pages. If your document is not
page oriented (e.g., a .HLP file) the new RUNOFF still counts
spooled pages. Otherwise, it counts logical (i.e., RUNOFF)
pages.
34. When you said /DRAFT to the old runoff it assumed /SEQUENCE as
well. The new RUNOFF does not automatically assume /SEQUENCE.
35. /ORANGE has been renamed to /PAGES.
36. The /PAGES switch no longer accepts a line number. Now it just
accepts a starting page number. The page number is input
exactly as it would appear in the document. Output is
generated as soon as that page is started. To get an entire
appendix, just input the appendix letter; to output just the
index say /PAGES:"INDEX". E.g.
/PAGES:"A"
is identical in meaning to
/PAGES:"A-1"
This shortcut is not available for chapters.
37. When RUNOFF looks at the /PAGES information to see if it should
produce output, all parts of the current page number must match
all parts of the page number given on the /PAGES switch.
The old RUNOFF attempted to see if the current page was somehow
described by the /PAGES information, with the result that you
would sometimes get extra pages.
38. The new RUNOFF justifies text using the same algorithm as the
old version. However, one case has been found in which this is
not the case. Text immediately following an .END LITERAL
command is justified differently in the two RUNOFFs. Note that
this applies only if there are no .SKIP or .BREAK or equivalent
commands before the text after the .END LITERAL command.
Justification becomes identical again as soon as a .SKIP,
.BREAK, etc command is encountered. If you are trying to
FILCOM output generated by the two RUNOFFs and this becomes a
problem, just insert a .BREAK command after all your
.END LITERAL commands.
39. If you say .SUBPAGE at the top of the document, old runoff
generates subpage 1@. New RUNOFF generates 1A.
The old runoff was wrong.
40. If you specify one of the switches that results in additional
output being generated to the left of the document, there is no
guarantee that that information will be identical, if you
compare output generated by the various versions. In general
the information generated by the new RUNOFF is more carefully
gathered than the same information as output by the old runoff.
41. Old runoff allows you to use .NUMBER whatever to set the page
number whenever you want. New RUNOFF provides the same
commands, but does not allow the effects to take place in the
middle of a page. This means that, for example, if you say
.NUMBER PAGE 9999, your document won't show that page number
until you cross a page boundary. Further, to cross a page
boundary, you must do something other than just say .PAGE; in
addition, you must actually generate some text and force it
out. In practical terms this means you should set the page
number only when you are at the top of a page; i.e., before
you have input any text, or after some command that implies
.PAGE.
42. If you issue a .DO INDEX command and you have already said
.NUMBER INDEX, the numbering starts over new.
4.0 RESTRICTIONS
The following restrictions and warnings apply to the new RUNOFF.
1. If you give no input-file type, the new RUNOFF only considers
.RNO as the intended file type. Specify the file type
explicitly for all other input files. Determination of the
output file type and formatting conventions are still
determined automatically as before.
NOTE
If you really want to get RUNOFF to use a file with no
extension, input a single '.' after the file name.
E.g., "TTY:=A" will cause RUNOFF to look for A.RNO and
fail if not found; "TTY:=A." will get you the file "A"
with no extension.
2. The following commands/facilities are not available:
1. When using indexing commands (.INDEX, .SUBINDEX, .ENTRY)
overstriking information in the index entries is discarded
(on purpose).
2. You cannot use the index flag to enter bolding or
overstriking information into the index.
5.0 COMMAND LINE SWITCHES
The new RUNOFF supports the following "RUNOFF-related" switches:
1. /BACKSPACE is used to indicate that RUNOFF can use the
backspace character to accomplish special effects.
NOTE
If you use the OVERSTRIKE flag to overstrike a
character more than once only the final overstriking
character is used if you do not say /BACKSPACE. For
example, if you say
=%/%\%^
the result is the same as if you said just
=%^
2. /BOLD and /NOBOLD
If you say /BOLD:n bolded output will be overprinted "n" times
to achieve the desired degree of darkness. The default value
for "n" is 1. Zero is equivalent to /NOBOLD
3. /CHANGE and related
4. /CONTENTS
The /CONTENTS switch is used to help prepare a table of
contents. If you say /CONTENTS you get a special file with
file type .BTC (binary table of contents). The utility program
TOC is used to generate a RUNOFF input file with file type .RNT
that generates a table of contents. The format of the
/CONTENTS switch is
/CONTENTS:<file-spec>
or
/CONTENTS
If you say /CONTENTS:xyz, for example, then the binary table of
contents is written to a file called XYZ.BTC. If you just say
/CONTENTS then the binary table of contents is written to
<input-file-spec>.BTC. So, for example, you can say
RUNOFF NUL:=ABC/CONTENTS
to generate just a binary table of contents called ABC.BTC, and
no document. The binary table of contents alone is generally
not useful; it must be processed by the program TOC. See the
file TOC.DOC for further information about this program.
Note however, that TOC creates a file with extension .RNT;
RUNOFF will accept such a file to create a file containing a
table of contents; the type of the file thus created is .MEC.
E.g., the command line
RUNOFF ABC.RNT
results in a file ABC.MEC containing a table of contents.
5. /DOWN
6. /DEBUG
/DEBUG:ALL is the same as specifying
/DEBUG:(FILES,CONTENTS,CONDITIONALS,INDEX)
/DEBUG:INDEX means echo index hits in the .MEM file
The index hit appears BEFORE the line of text with which
it is associated; note that this is even though you are
supposed to put your indexing commands AFTER the reference
point in your file. An additional note: index hits which
are echoed at the bottom of the page, after the last line,
are associated with the first non-blank line after the
title and subtitle on the next page; i.e., they are
echoed on the previous page.
Finally, note that the manner of marking index entries is
as follows: Indexing information coming from .INDEX and
.SUBINDEX commands, as well as from the <INDEX flag>, is
preceeded by ".INDEX". Indexing information from .ENTRY
commands is preceeded by ".ENTRY"
/DEBUG:CONDITIONALS means ignore all .IF, .ENDIF, .IFNOT, and
.ELSE commands and output the draft flags (See description of
the .VARIABLE command) in the .MEM file.
/DEBUG:CONTENTS means echo all .SEND TOC commands in the .MEM
file
/DEBUG:FILES means echo all .REQUIRE commands in the .MEM file
NOTE
See the NOTE for the /SIMULATE switch.
7. /DRAFT
This switch has the same meaning as /DEBUG:ALL
8. /FORMSIZE:n
This switch is used to indicate how many lines can be
accommodated on the form on which the document appears. If you
say /SIMULATE, "n" is interpreted as the number of physical
lines on a page of forms. If you don't say /SIMULATE (or do
say /NOSIMULATE) "n" is interpreted as the number of lines you
can fit on a page of forms (remember that whatever controls the
line printer reserves a few lines at the top and bottom of each
page of forms, and "n" specifies what's left over). If you
don't say anything, RUNOFF assumes 66 if you say /SIMULATE and
60 if you don't.
9. /INDEX
The /INDEX switch is used to help prepare a two-column index.
If you say /INDEX then, instead of getting the index with the
dots, you get a special file with file type .BIX (binary
index). The utility program TCX is used to generate a RUNOFF
input file with file type .RNX that generates a two-column
index. The format of the /INDEX switch is
/INDEX:<file-spec>
or
/INDEX
If you say /INDEX:xyz, for example, then the binary index is
written to a file called XYZ.BIX. If you just say /INDEX then
the binary index is written to <input-file-spec>.BIX. So, for
example, you can say
RUNOFF NUL:=ABC/INDEX
to generate just a binary index called ABC.BIX, and no
document. The binary index alone is generally not useful; it
must be processed by the program TCX. See the file TCX.DOC for
further information about this program.
Note however, that TCX creates a file with extension .RNX;
RUNOFF will accept such a file to create a file containing a
two-column index; the name of the file thus created is .MEX.
E.g., the command line
RUNOFF ABC.RNX
results in a file ABC.MEX containing a two-column index.
10. /MESSAGES
Say either /MESSAGES:USER or /MESSAGES:OUTPUT to control where
output messages appear. The default is /MESSAGES:OUTPUT.
/MESSAGES:USER means that only the RUNOFF user sees the error
messages, i.e., on the terminal; they are not written into the
output file too. /MESSAGES:OUTPUT means that messages are
written only to the output file. The default is
/MESSAGES:(USER,OUTPUT).
11. /PAGES
*****NOTE***** This switch can only recognize page numbers that
are input using the default display characteristics for their
various parts (see the description of the .DISPLAY commands,
above). This means, for example, that even if your .RNO file
contains a .DISPLAY CHAPTER RU command so that chapter numbers
appear in uppercase Roman numerals, you are still required (on
this switch) to used chapter numbers given as decimal numbers.
The test for the requested page(s) is made without regard to
the display characteristics.
12. /PAUSE
13. /RIGHT
14. /SEQUENCE
15. /SIMULATE
NOTE
Extra lines generated as the result of specifying
/DEBUG with certain options disturb the line counting
done by /SIMULATE.
16. /UNDERLINE and related
Note the following difference: in old runoff you said
/UNDERLINE:CHARACTER if the character used to do the
underlining was non-spacing. In new RUNOFF you say
/UNDERLINE:NONSPACING instead.
17. /VARIANT
The new RUNOFF supports the following "general-purpose" switches:
1. /HELP
NOTE
The help file you get is the one for the old runoff,
not one for the new RUNOFF.
The new RUNOFF will take information from your SWITCH.INI FILE.
No input-file wild-carding is available. Nor do other file-selection
switches work. However, you can say
*.DOC=XXXX
Note that even though the new RUNOFF has fewer command-line switches
than old runoff, most of the capabilities can still be invoked via the
use of the .REQUIRE command and specifying TTY: as the input. Enter
your command line as usual, but specify just TTY: as the input, instead
of the file name. Then, type commands directly to RUNOFF, in RUNOFF
style. After you have typed your commands then say .REQUIRE
"<file-spec>" to complete the processing. Finally use ^Z to indicate
end-of-file.
6.0 KNOWN BUGS AND DEFICIENCIES
o 021 Found in 1(101) of RUNOFF. The bug is transportable. If
you say /SEQUENCE, the input page number and line number for an
"auto'ed" subtitle are sometimes 0 (i.e., zero).
o 002 If you say RUN RUNOFF, and you then supply it with no file
to process, you need two ^Zs to get back to monitor level
rather than one. Ditto with the /EXIT switch.
o 001 The following sequence generates an internal logic error:
.center ^&(tab)(tab)(tab)\&
Note that any additional character other than (tab) between the
^& and \& causes the internal logic error to go away.
7.0 MISCELLANEOUS
The following undocumented short forms of commands are no longer
supported. Note that these commands have been found in only a very few
files.
1. .NOF
2. .PAG
The following undocumented command syntax is no longer supported:
1. The old version of RUNOFF did not allow numbers to be in
variable names specified on a .VARIABLE command. Therefore, in
old runoff, a .VARIABLE command such as
.VARIABLE ABC12
was equivalent to
.VARIABLE ABC 1,2
as far as old runoff was concerned. In the new RUNOFF, numbers
are allowed as characters in the name, so that the example is
taken, by the new RUNOFF, as defining a variable with the name
ABC12 having no /DRAFT flags.
The following undocumented command behavior is no longer supported:
1. In the old RUNOFF, you could end a .LIST or .NOTE with just
".END". Also, ".END LIST" could end a .NOTE, and conversely.
The new RUNOFF requires you to say explicitly which construct
you are ending.
2. In the old version, .BREAK and related commands did not cancel
a .INDENT command.
3. The first parameter of a .LIST command used to be processed as
if the user said .SPACING n after the .LIST command. While
processing an extensive number of files, none were found that
used that facility; therefore, the first parameter has been
given a new meaning, described above, under NEW FEATURES.
If you really need to have a list with different spacing than
that specified on the last .SPACING command, you can just
insert an appropriate .SPACING command after the .LIST command;
you don't need to reset the spacing after the end of the list,
since that gets done automatically for you.
Note that this change duplicates the behavior shown by various
old -11 versions of runoff.
4. In old -10 runoff, the only difference between the .INDEX and
.SUBINDEX commands is that the SUBINDEX flag is disabled in the
scan of the .INDEX command's text argument. Also, termination
of the scan of the text items was different in both cases (but
only slightly so).
In the new RUNOFF, .INDEX and .SUBINDEX have no differences.
The two command names and their abbreviations are retained for
source language compatibility. In other words, you can do
everything with the .INDEX command and don't need to use
.SUBINDEX at all.
There have been no problems found that can be traced back to
the simplification just described.
The only place where this may be a problem is when you have a
'.INDEX ;' command; old runoff would put the ';' into the
index. In the new version, you have to force the ';' via the
QUOTE flag.
5. Old runoff merges page numbers in the index regardless of
whether or not it makes sense. New RUNOFF uses a bit more
discretion, as follows: If your document contains pages having
duplicate page numbers for one reason or another, and these
pages give rise to duplicate index entries, new RUNOFF will
keep them apart. Old runoff does not keep them apart.
NOTE: This difference is not to be construed as a feature; in
particular, it is an accident of the implementation and
probably doesn't always hold.
For example, suppose you had a file generating, say, a page 5
at the start of the document and another page 5 much later in
the document; further, suppose both pages had index references
to "xyz". Old runoff will either merge the two references, or
get confused. New RUNOFF will generate
xyz. . . . .5, 5
to indicate that there are two pages numbered 5.
6. The old version of runoff used the following "method" of
generating blank lines at the top of a page in response to a
.CHAPTER or .APPENDIX command. Normally, 12 lines were
skipped, unless the user specified a page size greater than
1000; in that case, old runoff divided the page length by 64
and multiplied the result by 12 to get the number of lines to
skip. If you had specified a page size of say 99999, say, this
leads to several pages full of blank lines being generated.
New RUNOFF always skips the same number of lines, regardless of
the length of the page.