Google
 

Trailing-Edge - PDP-10 Archives - BB-4172H-BM - 4-1-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]