Trailing-Edge
-
PDP-10 Archives
-
SRI_NIC_PERM_SRC_1_19910112
-
6-documentation/runoff.bwr
There are 4 other files named runoff.bwr in the archive. Click here to see a list.
RUNOFF.BWR -- Differences Between MACRO-10 Runoff and DSR Page 1
November 1982
COPYRIGHT (C) 1976,1979,1982 BY
DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS.
THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER
COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY
OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY
TRANSFERRED.
THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT
CORPORATION.
DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL.
RUNOFF.BWR -- Differences Between MACRO-10 Runoff and DSR Page 2
November 1982
Files produced for input to the old, MACRO-10 version of Runoff (here
called RUNOFF/10) should produce identical output in most cases when
processed through DIGITAL Standard Runoff (DSR). Many hundreds of
files have been put through both RUNOFF/10 and DSR and compared to
check for differences.
The major types of differences that can be expected are listed below
in the following sections:
I. Section I below details the results of numerous bug fixes and
minor algorithmic changes.
II. The name or the form of some few commands have been changed in
DSR; these are listed in Section II.
III. Section III lists differences caused by undocumented RUNOFF/10
behavior not supported by DSR.
IV. Section IV discusses undocumented RUNOFF/10 command
abbreviations not supported by DSR.
V. Finally, Section V lists the many new commands available in
DSR. While these commands do not touch on the issue of
compatiblity with existing files, they are included here for
completeness. See the TOPS-20 DIGITAL Standard Runoff (DSR)
User's Guide, order number AA-N389A-TM, for full descriptions
of the functions of these commands.
DSR's command parsing, command and flag processing, error detection,
and error recovery are much more consistent and robust than was the
case in RUNOFF/10. For this reason, files that the user had "tinkered"
in some way to circumvent a RUNOFF/10 bug, or to take advantage of an
undocumented RUNOFF/10 "feature," may not generate the same ouput from
DSR.
The names and syntax of many of the command-line switches are
different. These differences are not documented here. See the Help
file for DSR (type /HELP in response to the RUNOFF> prompt), or use
incremental help; or consult the User's Guide for the new forms of the
switches.
How to Tell Whether You Are Running RUNOFF/10 or DSR
DSR is a native TOPS-20 program, so incremental help and command
completion should quickly tell you if you are in fact running DSR.
DSR's prompt is "RUNOFF>", while that of RUNOFF/10 is "*".
DSR's version number is 2(103), as shown by INFORMATION (ABOUT)
VERSION. Also, if you specify the /LOG switch when running DSR, it
reports its version number upon termination (by default it does not
report it).
RUNOFF.BWR -- Differences Between MACRO-10 Runoff and DSR Page 3
November 1982
I. Minor Algorithmic Differences and Bug Fixes
The following list describes those cases when RUNOFF/10 and DSR
produce different results. In many cases the differences are due to
bugs in RUNOFF/10.
1. DSR accumulates 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.
RUNOFF/10 checks information as it gets it, not when it uses
it. Thus, DSR will usually make sense out of those things that
the old one does badly.
2. A .PAGE command does not cancel pending indentation in DSR.
3. If .SPACING 2 is specified to RUNOFF/10, it generally does not
put text on the last line of the page. DSR does write on the
last line of the page.
4. The .SPACING command takes effect sooner than in the older
version. The old version always skips ".SPACING" lines after a
line of text before picking up the next line or command. DSR
skips ".SPACING" lines before outputting a line of text, and
then gets the next line or command.
RUNOFF/10 was wrong.
5. RUNOFF/10 does not allow numbers to be in variable names
specified on a .VARIABLE command. Therefore, in RUNOFF/10, a
.VARIABLE command such as
.VARIABLE ABC12
is equivalent to
.VARIABLE ABC 1,2
In DSR, numbers are allowed as characters in the name, so that
the first example is taken, by DSR, as defining a variable with
the name ABC12 having no /DEBUG flags (/DEBUG is the new name
for the /DRAFT switch).
6. DSR ignores fewer flags or characters than RUNOFF/10. This
means that flags or characters that are left in input files as
artifacts of battles with RUNOFF/10 will now be looked at.
7. DSR does not allow you to have the same character representing
more than one flag.
8. DSR does not get confused by "<\\", as RUNOFF/10 does.
9. RUNOFF/10 does not turn off a '<' (capitalize flag) when it
encounters a '>' (subindex flag) while processing a .SUBINDEX
command.
DSR recognizes a subindex flag as terminating a cap-flag
RUNOFF.BWR -- Differences Between MACRO-10 Runoff and DSR Page 4
November 1982
sequence.
10. In RUNOFF/10, a ^^ before a .HEADER LEVEL command will cause
some header levels not to have all letters translated to the
correct case. DSR uses the case rules specified by the most
recent .UPPER CASE or .LOWER CASE command.
RUNOFF/10 was wrong.
11. Because of the more uniform handling of lists of parameters,
'.hl1,abc' is now equivalent to '.hl1abc'. This means that in a
header level having a text parameter that starts with a comma,
the comma will be interpreted as just a parameter separator,
and will be discarded. The comma can be forced by using the
ACCEPT flag (_,) if necessary.
12. In DSR, .HEADER LEVEL commands cancel pending indentation and
"autoed" paragraphs. This is a difference in behavior, and does
not represent a bug in either RUNOFF/10 or DSR.
13. RUNOFF/10 adjusts the paragraph indentation setting whenever it
encounters a .LM command. This means that one cannot
temporarily set a left margin that is inconsistent with the
.PARAGRAPH command setting, even if no .PARAGRAPH command is
used there, and reset the left margin later. Under certain
circumstances this leads to erroneous error messages, or to
RUNOFF/10 failing to detect an error condition.
DSR leaves .PARAGRAPH settings alone.
14. If the text for header-levels is longer than the width of the
margins currently in effect, RUNOFF/10 puts it out nonetheless,
in violation of the right margin. DSR fills and justifies such
long header-level text.
15. RUNOFF/10 incorrectly justifies an input line that fits exactly
within the margins of the page, including a following space.
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.
RUNOFF/10 justifies the line but shouldn't. DSR does not
justify the line.
16. RUNOFF/10 does not check tab settings thoroughly enough, with
the result that it is possible to force a word to extend past
the right margin. DSR checks more thoroughly and does not allow
it.
17. When RUNOFF/10 discovers a tab that it cannot expand, but there
are some tab settings in effect, it arbitrarily tabs right some
amount, sometimes past the right margin. DSR handles the
unexpandable tab as if it were a simple space.
RUNOFF.BWR -- Differences Between MACRO-10 Runoff and DSR Page 5
November 1982
18. When parsing a .TITLE or .SUBTITLE command, RUNOFF/10 skips
precisely one space after the command keyword, if it is
present. DSR 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. RUNOFF/10
generates the required number of spaces as soon as indentation
is specified. This leads to a difference in how tabs are
expanded. In RUNOFF/10, 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.
DSR'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. RUNOFF/10 erroneously places the last digit of the page number
of an appendix past the right margin. DSR does it correctly.
21. Text entered into the index via one of the indexing commands
is, by definition in DSR, 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 RUNOFF/10 does. No indexing
differences have been discovered that result from this
convention.
22. RUNOFF/10 doesn't compute the width of the text correctly if an
INDEX flag is used in a title, subtitle, or chapter-heading.
The result is poorly centered lines, or a page number offset a
bit to the left. DSR does not have that problem.
23. In a document that does not contain chapters, for .DO INDEX
RUNOFF/10 uses the word " to " to join adjacent page references
in the index. DSR uses a dash, "-".
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.
25. RUNOFF/10 allows you to do things such as skip a page by
forcing a FORMFEED into the output. DSR 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, and therefore generate
error messages when the command is parsed.
RUNOFF.BWR -- Differences Between MACRO-10 Runoff and DSR Page 6
November 1982
27. RUNOFF/10 tends not to center lines correctly. DSR does it
correctly.
28. RUNOFF/10 tends to forget to put page numbers on the tops of
pages in the index. DSR 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 formatting
environment that is in effect when the .FOOTNOTE command is
encountered, rather than some other arbitrary environment.
Case translation rules in footnotes 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. DSR saves footnotes in files called 001RNO.TMP and 002RNO.TMP
until the footnotes are needed. The files are deleted when DSR
is done with them.
31. If there is not room enough for all saved footnotes at the
bottom of a page, DSR will hold some of them until the next
page.
32. RUNOFF/10 sometimes generates extra spaces for subindexed
entries in the index; the result is improper indentation. DSR
does it correctly.
33. When sorting the index, it makes a difference to RUNOFF/10 as
to exactly how spaces got between words; although two entries
have the same visual effect, they will sometimes not be merged
correctly. DSR does not suffer from this deficiency.
34. The page count output by DSR after termination of a document
may be different than that given by RUNOFF/10.
RUNOFF/10 counts physical (spooled) pages. If a document is not
page-oriented (for example, a .HLP file) DSR still counts
spooled pages. Otherwise, it counts logical pages.
35. For RUNOFF/10, the /DRAFT switch implies /SEQUENCE as well. DSR
does not automatically assume /SEQUENCE for /DEBUG (the new
name for /DRAFT).
36. When DSR 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.
RUNOFF/10 attempts to see if the current page is somehow
described by the /PAGES information, sometimes resulting in
extra pages.
37. DSR justifies text using the same algorithm as RUNOFF/10.
However, one difference has been found: text immediately
following an .END LITERAL command is justified differently in
the two RUNOFFs. This applies only if there are no .SKIP or
RUNOFF.BWR -- Differences Between MACRO-10 Runoff and DSR Page 7
November 1982
.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.
38. Upon encountering .SUBPAGE at the top of a document, RUNOFF/10
generates subpage 1@. DSR generates 1A.
RUNOFF/10 was wrong.
39. If you specify one of the switches that result in additional
output being generated to the left of the document (/SEQUENCE,
/CHANGE-BARS), there is no guarantee that this information will
be identical. In general the information generated by DSR is
more carefully gathered than the same information as output by
RUNOFF/10.
40. RUNOFF/10 allows .NUMBER to set the page number at any point.
DSR 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 432, the document won't show
that page number until a page boundary is crossed. Further, to
cross a page boundary, DSR requires that you 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: before you have input any text, or after some command
that implies .PAGE.
41. If DSR encounters .DO INDEX after .NUMBER INDEX, the page
numbering starts anew.
II. Commands Whose Name or Form is Different
1. DSR does not process or recognize .TYPESET or .SELECT commands.
These lead to error messages.
2. In RUNOFF/10 the first parameter of a .LIST command is
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, as described in the
documentation.
To get a list with different spacing than that specified on the
last .SPACING command, insert an appropriate .SPACING command
after the .LIST command. Spacing is reset automatically after
the end of the list.
3. In RUNOFF/10, 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 is slightly different in the two
cases.
In DSR, .INDEX and .SUBINDEX have no differences. The two
RUNOFF.BWR -- Differences Between MACRO-10 Runoff and DSR Page 8
November 1982
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.
No problems have been found to result from this simplification.
The only place where it may matter is in a command of the form
'.INDEX ;'. RUNOFF/10 would put the ';' into the index and
terminate the command. In DSR, the ';' must be forced via the
ACCEPT flag (_;).
4. Although RUNOFF/10 was documented as recognizing the .NO SPACE
command, in fact only .NOSPACE was recognized. DSR honors
.NO SPACE. But DSR is more rigorous in giving error messages if
.NO SPACE is used in an illegal context. RUNOFF/10 often does
not complain, but does not honor the command in these cases.
III. Undocumented RUNOFF/10 Command Behavior Not Supported in DSR
1. In RUNOFF/10, ".END" terminates either a .LIST or .NOTE. Also,
".END LIST" can end a .NOTE, and conversely. DSR requires you
to say explicitly which construct you are ending.
2. In RUNOFF/10, .BREAK and related commands do not cancel an
.INDENT command.
3. RUNOFF/10 merges page numbers in the index regardless of
whether or not it makes sense. DSR uses a bit more discretion,
as follows: If a document contains pages having duplicate page
numbers for some reason, and these pages give rise to duplicate
index entries, DSR will keep them apart. RUNOFF/10 does not
keep them apart.
For example, suppose a file generates a page 5 at the start of
the document and another page 5 later in the document. Further,
suppose both pages have index references to "xyz". RUNOFF/10
will either merge the two references or get confused. DSR will
generate
xyz. . . . .5, 5
to indicate that there are two pages numbered 5.
4. RUNOFF/10 uses the following method of generating blank lines
at the top of a page in response to a .CHAPTER or .APPENDIX
command. Normally, 12 lines are skipped, unless the user
specifies a page size greater than 1000; in that case,
RUNOFF/10 divides the page length by 64 and multiplies the
result by 12 to get the number of lines to skip. If the
specified page size were 99999, say, this leads to several
pages full of blank lines being generated.
DSR always skips the same number of lines, regardless of the
length of the page.
RUNOFF.BWR -- Differences Between MACRO-10 Runoff and DSR Page 9
November 1982
IV. Undocumented Short Forms of Commands Not Supported in DSR
RUNOFF/10 allowed an unknown number of special-case truncations in
recognizing commands. These are not duplicated in DSR. In addition,
DSR has a number of new commands that may change the allowed unique
truncation of command names.
In general, spelling out a command in full or using its legal
abbreviation (not its truncation) will lead to the greatest degree of
RUNOFF/10 - DSR compatibility.
For example, ".PAGE" is recognized by both processors; ".PG" is its
defined abbreviation and is recognized by both; ".PAG" was a legal
truncation in RUNOFF/10 but is no longer so in DSR.
Similarly, the undocumented abbreviation .NOF, for .NO FLAGS, is no
longer supported.
V. New DSR Commands Not Present in RUNOFF/10
The following is a list of new DSR commands. While these commands do
not touch on the issue of existing-file compatiblity, they are
included here for completeness. See the TOPS-20 DIGITAL Standard
Runoff (DSR) User's Guide, order number AA-N389A-TM, for full
descriptions of the functions of these commands.
.AUTOJUSTIFY .NO AUTOJUSTIFY
.AUTOSUBTITLE .NO AUTOSUBTITLE
.DATE .NO DATE
.DISPLAY APPENDIX
.DISPLAY CHAPTER
.DISPLAY ELEMENTS
.DISPLAY SUBPAGE
.ENABLE BOLDING .DISABLE BOLDING
.ENABLE HYPHENATION .DISABLE HYPHENATION
.ENABLE INDEXING .DISABLE INDEXING
.ENABLE OVERSTRIKING .DISABLE OVERSTRIKING
.ENABLE TOC .DISABLE TOC
.ENABLE UNDERLINING .DISABLE UNDERLINING
.ENTRY
.FLAGS ACCEPT .NO FLAGS ACCEPT
.FLAGS BOLD .NO FLAGS BOLD
.FLAGS BREAK .NO FLAGS BREAK
.FLAGS COMMENT .NO FLAGS COMMENT
.FLAGS HYPHENATE .NO FLAGS HYPHENATE
.FLAGS OVERSTRIKE .NO FLAGS OVERSTRIKE
.FLAGS PERIOD .NO FLAGS PERIOD
.FLAGS SUBSTITUTE .NO FLAGS SUBSTITUTE
.KEEP .NO KEEP
.LAYOUT
.NUMBER RUNNING
.REPEAT
.REQUIRE
.SEND TOC
RUNOFF.BWR -- Differences Between MACRO-10 Runoff and DSR Page 10
November 1982
.SET DATE
.SET LEVEL
.SET PARAGRAPH
.SET TIME
.STYLE HEADERS
.XLOWER .XUPPER
[End of RUNOFF.BWR]