File: ACID.AC of Tape: Sources/Other/new-18
(Source file text)
[m72]A C I D -- Document Generator, V-6a [d][w]Page[p] of[t]
[f2,54,0]
[1] INTRODUCTION
ACID is an automatic cross-referencing, hyphenating,
and indexing document generation
program that runs under the OS/8 operating system. ACID is a considerably
more useful program than other programs of a similar genre (such as RUNOFF,
DOC8, JUST etc.) because it directly addresses two of the most serious problems
in a document generation program: (1) it has to be extremely simple to use:
very often, support documents may be generated by personnel with little
understanding of markup commands; (2) it must be designed to cater to the fluid
nature of documentation where new sections are constantly being added and old
sections being deleted.
ACID commands are extremely simple: in most cases, documentation can be
produced with virtually no markup at all. Justification of indented sections
versus. tabular material are processed by a remarkably simple set of semantic
rules (see [=indent recognition] for details). To improve the quality of
the final output, justification spaces are always added after punctuation
whenever possible. When punctuation is not available, justification spaces
are added at random positions on the line to guard against ``rivers'' in the
text. Furthermore, ACID provides high quality automatic hyphenation of the
text. As a run-time option, the automatic hyphenation can be overriden to
allow manual hyphenation when
the source document is originally prepared and also at run-time. The
automatic run-time hyphenation in ACID
avoids the most serious problem of programs
handling mono-space font justification--large gaps of white space. ACID insists
upon hyphenation whenever there are more than two consecutive spaces between
words (or three spaces if following a punctuation mark). This greatly improves
the legibility of the final document.
Another significant feature of ACID is that it is a 3 pass documentation
program. During pass 1, a symbol table is built of all section headers along
with the associated section numbers. During pass 2, the
the hyphenation is handled and the precise page numbers are recorded.
In pass 3, the
actual output document is produced, preceded with an index of all sections.
Furthermore, ACID allows symbolic references to section headers which are
then translated during pass 2 into the actual section numbers and page numbers.
Section numbers themselves are generated automatically by ACID. All that has
to be specified is the current level of the section. In this way, sections
of text can be added or deleted without ever having to update all the
surrounding section numbers--a major problem in maintaining up-to-date
documentation with most document generator programs.
ACID also has a ``proof'' mode. Preceding each line on the output, ACID
lists the file, page, and line numbers from the original source file, thereby
greatly facilitating the subsequent editing of the file.
[1] REQUIREMENTS
ACID will run on any minimum OS/8 configuration (PDP8/i, PDP8/e, PDP12 etc.).
With 8k of memory, about half
of field 1 is available for symbol table storage, which is adequate for all
but the largest documents. Use of the /D option requires a minimum of 16k
memory.
If more memory is available, ACID will use that
additional memory for further symbol table storage if necessary. Standard
OS/8 device drivers are used for all input and output.
Although an upper/lower case console is most convenient for document
preparation, an upper case console can be used for this purpose as detailed in
[=/U option].
[1] RUNNING THE ACID PROGRAM
[2] STARTING THE ACID PROGRAM
[3] DIRECT R COMMAND
To run the ACID program, issue the following command to the OS/8
system:
.R ACID[c]
The program will then respond with an * to show that the OS/8
COMMAND DECODER is active. Up to 9 input files may be specified to the
ACID program with a single file specified for output. If no output file is
specified, ACID runs normally, but no output will be generated (however, any
errors in the source file will be detected and printed on the console).
If a carriage return is typed after the `*' of the COMMAND DECODER, ACID
will print a HELP file on the console, summarizing all the run-time options
and commands that are available.
OS/8 COMMAND DECODER options are described
in [=run time options].
[3] CCL & CHAIN
ACID will also support a chain command in which case the COMMAND
DECODER is not called, and ACID assumes that the COMMAND DECODER tables
have been properly initialized for use by ACID. A command can be added
to the CCL program to allow ACID to be called by a direct keyboard command.
One approach is to use the existing PRINT command in CCL and to
change LPTSPL to ACID in the CCL tables (along with any necessary modifications
to the CCL tables to reflect COMMAND DECODER options).
[2] RUN TIME OPTIONS
There are several run-time options in the ACID program implemented through
options to the COMMAND DECODER:
[3] /D OPTION
The /D option sets double column mode. In this mode, the text is
printed in two columns on the output device. The margin width specified
in the [[]m[]] command should designate the total width of both columns
including the intercolumn gap.
The space between the columns is controlled by a patchable program value
(the exact address is given in the HELP file).
In other words if the margin width is specified as 76 and the intercolumn
gap has its normal value of 4, each column will be 36 positions wide.
The width of the title line is held independently of
the current margin width, so that the title can be made to spread over
both columns.
The /D option requires a minimum of 16k memory, since double column
mode requires extensive buffering of the output text.
[3] /F OPTION
The /F option forces all output from the ACID program to be in upper
case. This option would normally be used only when output is being sent to
an upper case printer that can not handle lower case characters. For example,
a high-speed line printer might be used for proofing purposes, with final
output being produced on a slower, upper/lower case printer.
[3] /H OPTION
The /H option prevents ACID from requesting manual intervention
to hyphenate a line that is badly underset. ACID will justify the line
correctly even though it is underset. Discretionary hyphens in the source
file are still processed normally. This option is useful when running
under OS/8 BATCH and when a high-quality output document is not essential.
[3] /I OPTION
The /I option inhibits the generation of an index at the start of
the document.
[3] /L OPTION
The /L option causes ACID to generate an audit trail of all words
that were hyphenated in the source document. The words are printed in two
columns (3 if the /V option is also set), and are preceded with the file,
page and line number. This latter feature makes it easy to locate words
that were not correctly hyphenated by ACID.
[3] /M OPTION
The /M option force ACID to revert to manual hyphenation of the
source document (as in version 4a of ACID). Rather than attempting automatic
hyphenation, ACID prints the word on the console and waits for the user
to specify the hyphenation point: see section [=manual hyphenation].
[3] /N OPTION
The /N option tells ACID that there are no symbolic references
to section headers in the text. When this option is used, ACID immediately
goes to pass 2 since there is no need to build a symbol table of symbolic
references. The /N option also sets the /I option and therefore disables
the generation of the index of contents. This option may be necessary
to process huge source documents which would otherwise overflow
the available memory of the PDP/8.
[3] /P OPTION
The /P option causes ACID to run in ``proof'' mode where each line
on the output is preceded by the file, page, and approximate line number from
the original source document. The identification is ``approximate'' only in
the sense that the line justification in ACID means that lines will no
longer match the source file exactly. A hash character appearing in the
extreme left-hand margin indicates that the line is underset and that
the word at the beginning of the following line could not be hyphenated
(primarily for internal debugging of the hyphenator).
[3] /T OPTION
The /T option is used to lessen the tight appearance of the output
source document by allowing more white space to be added to each line.
To accomplish this, ACID increases the threshhold for an underset line.
This significantly decreases the number of words that will be hyphenated
in the final document. NOTE: versions prior to V-5a, level 6 had an inverted
sense for this switch.
[3] /U OPTION
The /U option is used when upper/lower case output is to be generated
from a source file that was created on a console which can not
generate lower-case characters. When the
/U option is in effect, ACID assumes that all alphabetic characters in the
input file are in lower case. In order to indicate that certain characters
or strings of characters are to be in upper case, two conventions are used
in the source file:
[4] SINGLE CHARACTER SHIFT
A single `/' character indicates that the next character,
and only the next character is to appear in upper case.
[4] MULTIPLE CHARACTER SHIFT
Two `/' characters in a row indicate that all subsequent
alphabetic characters are to be treated as if they are in upper case. When
in this upper case mode, a single `/' character is then used to return to
the normal lower case.
[4] EXAMPLE OF SHIFTS
The example below shows how this convention is used in an ACID
program. The first line is the input line as it appears in the original source
document. The second line shows what the line looks like when the /U option
is in effect:
Input: /NOW IS THE //TIME/ FOR ALL /GOOD /MEN
Output: Now is the TIME for all Good Men
[3] /V OPTION
The /V option is an extension to the /L option. If /V is specified
in addition to /L, the automatic hyphenation audit trail will appear on
the line printer instead of the console. This audit trail assumes a standard
``DEC'' type line printer on device address 66, with IOT 6666 to output
a character and 6661 to skip on the flag.
[3] /Z OPTION
The /Z option prevents ACID from appending a Control/Z to the end
of the output file. This option is intended for output devices with forms
control where the device handler may generate an extra form feed when
the Control/Z character is detected.
[3] EQUALS SIGN OPTION
When generating output, the left margin is normally defaulted to
column one of the output device. On occasions, it may be desirable to float
the entire left hand margin over a few positions for the entire output
document.
This is handled by indicating the position of the left hand margin after
the equals sign. For example, the COMMAND DECODER line below:
*LPT:<DK3:PAGE8=6[c]
indicates that the left hand margin is to be indented 6 positions
throughout. Note that a default floating margin can be patched into ACID
as described in [=setting permanent defaults].
[3] /0 TO /9 OPTIONS
These options are used to control the conditional listing of
text specifed by the ``switched text'' command. If the
associated switch is set at run-time, the designated section of text
will appear in the final output document. Otherwise, that section
of text will be completely stripped. See [=switched text] for more
details.
[2] SETTING PERMANENT DEFAULTS
ACID allows permanent defaults to be set for the following parameters:
1. Floating Margin
2. Drop from top of page (top margin)
3. Number of lines in output document
4. Bottom Margin
5. Position of right-hand margin
6. Number of spaces in a paragraph indent
7. Number of spaces between columns in double column mode
The specific addresses for each item are listed in the HELP file. To
set a permanent value, use ODT to patch in the desired value as an octal
number and save the file.
[2] DEFAULT EXTENSIONS
The default extension for the output file is ``.LS'' while the
default extension for the input files is ``.AC'' (to identify an input source
document for the ACID program).
[2] SPECIAL CHARACTERS
[3] SQUARE BRACKETS
The square brackets: [[] and []] are used to enclose an ACID command.
For purposes of consistency, all commands are enclosed in brackets even though
the closing bracket is not syntactically required in some cases. The first
character after the [[] identifies the particular command to be executed.
Individual commands are described in section [=ACID commands].
[3] HYPHEN
The hyphen is treated specially in ACID only to the extent that ACID
will permit a line break to occur after the hyphen. Otherwise, the hyphen is
treated as a normal character.
[3] DISCRETIONARY HYPHEN
The discretionary hyphen is the backslash character ([\]).When
ACID finds a line is badly underset (i.e. too many justification spaces
needed to justify the line), ACID hyphenates the word according to logical
rules.
However, if the word to
be hyphenated has a discretionary hyphen, ACID automatically changes
the discretionary hyphen to a real hyphen and then breaks the word at
that point. Under all other conditions, the discretionary hyphen is
completely ignored and stripped from the final output document. Typically
discretionary hyphens are added to a source document after the first
few runs of the ACID program wherever bad hyphenation points occur.
[3] SLASH CHARACTER
The slash is treated as a special character only when the /U
option is being used as detailed in [=/U option]. If the /U option is not being
used, the / character is treated as a normal character.
[3] CONTROL Z
Control/Z marks the end of an input file since this is a standard
convention for OS/8 ASCII files (and all text editor programs supply this
character automatically). ACID does not require that input files end at
a logical division in the text or
that they end with a Control/Z character (although this would normally be
the case).
[3] TAB CHARACTER
The ASCII TAB character (octal 211, or Control/I) is expanded to the
appropriate number of multiple spaces to move to the next tab stop on the
line in a manner identical to that of the OS/8 EDIT and TECO editor programs.
Tab stops occur at every 8th position on the line. For details on how the
TAB character is processed, see section [=multiple spaces] if two or more
spaces are generated, or [=single space] if only a single space is generated
by the TAB code. However, see [=cautions about using TAB codes] for some
warnings on using the TAB code. See also [=indent recognition] for further
details.
[3] SPACE CHARACTER
Because of semantic indent recognition in ACID, the space character
and end-of-line character are treated specially.
IN AN ACID SOURCE DOCUMENT, TWO OR MORE SPACES IN A ROW HAVE A
SPECIAL MEANING. IN PARTICULAR, TWO OR MORE SPACES AT THE END OF A SENTENCE
WILL CAUSE UNEXPECTED INDENTATIONS OF THE FOLLOWING TEXT. ENSURE THAT
YOU UNDERSTAND THE FOLLOWING RULES:
[4] SINGLE SPACE
A single space is treated as a ``justifiable space.'' In other
words, ACID can insert an additional space after this space in order to
justify the current line. To generate non-justifiable spaces, see
section [=fixed space command]. A single space at the start of a line also has
a special meaning: see section [=indent recognition] for details.
[4] MULTIPLE SPACES
A sequence of two or more spaces has a very special meaning
in ACID: the first non-space character after the multiple spaces marks the
position of the new left margin for all subsequent lines of text. Also,
any prior justifiable spaces on the line now become fixed spaces and are
not subject to justification. Careful study of the input source document
for this document you are reading should help to clarify this further.
To generate multiple spaces without affecting the current line indent,
see [=fixed space command].
[3] END OF LINE CODE
The Carriage return character is completely stripped from the
source file input stream. ACID recognizes an end-of-line code by the
ASCII line feed character which follows the carriage return. As with spaces,
ACID treats single line feeds and multiple line feeds differently:
[4] SINGLE END-OF-LINE CODE
A single end-of-line code by itself (and not followed
immediately by a space) is treated as being absolutely
equivalent to a normal, justifiable space.
[4] SINGLE END-OF-LINE CODE, FOLLOWED BY A SPACE
When a single end-of-line code is followed by one or
more spaces, ACID prints the prior text on the line
without any justification. The spaces that follow
the end-of-line code are then used to set the value
for a new margin indent on the subsequent line, see
[=indent recognition] for more details.
[4] MULTIPLE END-OF-LINE CODES
When an end-of-line code is followed by additional
end-of-line codes, the prior text on the line is
printed without justification as described in
[=single end-of-line code, followed by a space].
For each additional end-of-line code, ACID generates
a blank line on the final output. This means that
blank lines in the source input file produce similar
blank lines in the output file. Following the last
end-of-line code, ACID then checks for an indent
on the next line as in [=single end-of-line code, followed by a space].
[2] INDENT RECOGNITION
One of nicest features in ACID is the manner in which indents
are processed--indents normally requiring a fair amount of markup in
conventional programs that perform line justification. The rules themselves
are actually remarkably simple:
(1) Whenever two or more spaces are encountered in the text,
a new indent is established immediately following the last space that
was encountered. Prior text on the line will not be justified. This means
that tabular material where the columns are separated by two or more
spaces are automatically retained in tabular form. Study the source
input document at this point to examine to see how this rule has
governed the indention of this material you are now reading.
(2) One or more spaces at the beginning of a line indicate that
the preceding line is to be printed without justification and a new
margin is to be set for the line of text to follow. An important part of
this rule is that the new margin set by spaces at the beginning of the line
is actually one position less than the margin set in the original source
document. This means that to cancel the current indent in effect and return
to the extreme left-hand margin, a single space is used. If a line does not
begin with a space, the subsequent text is presumed to be part of the indent
currently in effect, and will be justified on that indent. An important
feature here is that TAB codes in the original source document are
correctly reconstituted. In other words, a single TAB code at the start
of a line will generate an indent of 8 spaces (not 7 spaces) since
the TAB code generated 8 spaces in the original source document. ACID
does this by automatically generating an extra space for the first
TAB code seen after a new indent has been generated.
[2] ACID COMMANDS
In the description below, any command beginning with a letter may
appear in either upper or lower case.
[3] / COMMAND [/]
The [[]/[]] command causes a single slash character to be printed
on the final output. This command is only needed when the /U option is
in effect since the / character is used to handle the shift and unshift
conditions as described in [=/u option].
[3] [ COMMAND [[]
This command is used to generate a single [[] character on the
output. This character can not appear by itself, because ACID would
interpret it as the start of a command (except in a section header).
[3] ] COMMAND []]
This command is used to generate a single []] character in the text
for the same reasons as described immediately above.
[3] [[ COMMAND [[
The [[][[] command is used to set a paragraph indent. Note that
typing several spaces at the start of a paragraph sets an indent for
all the following text. To avoid this, the spaces of the indent can either
be enclosed in brackets (viz. [[][ ][]] to generate three spaces) or
the space at the beginning of the line can be followed with [[][[] which
automatically generates the number of spaces specified for a paragraph indent
(the default value for this is 5). Remember that to generate the indent,
the [[][[] sequence must be preceded by a single blank.
[3] FIXED SPACE COMMAND [ ]
This command generates the number fixed spaces that are contained
within the command. Such fixed spaces are NOT treated as multiple spaces
as described in [=multiple spaces] and will there\fore not reset the current
margin indent then in effect. For example, [[][ ][]] will generate exactly
two fixed spaces. Furthermore, ACID will not permit a line break to occur
on such fixed spaces.
[3] \ COMMAND [\]
This command generates a single backslash character ([\]). This command
is needed since a backslash character by itself is other\wise treated as
a discretionary hyphen.
[3] - COMMAND [-]
This command generates a hyphen or minus sign and inhibits ACID
from recognizing the character as a hyphen. This means that ACID will
never attempt to break the line up on this character.
[3] H COMMAND [h]
The H command is used to disable hyphenation on the following word.
If the following word appears at the end of an underset line, ACID will
not hyphenate the word. The line will be justified without the word. The
[[]h[]] command is automatically reset by the next blank or end-of-line
in the input source document. Typically this command is used when the
automatic hyphenator hyphenates a word that should not be hyphenated.
[3] DATE COMMAND [d]
This command generates a string of characters which represents today's
date as it was entered to OS/8. The date is generated in the form:
Mmm.dd, yyyy[c]
Where ``Mmm'' is the first three characters of the month, `dd' is the
day of the month (if the first digit is zero, it is changed to a blank),
and `yyyy' is the year. If the date has not been entered
to OS/8 and ACID encounters this command, an error will be generated. Unlike
most commands, the [[]d[]] command is also permitted within a title -- see
[=title lines].
[3] CENTRE TEXT COMMAND [c]
This command causes all the prior text on the line to be
centred. If an indent is in effect, the line will be centred from
the end of the indent to the right-hand margin. As with the [[]R[]]
command, the line to be centred should begin with at least one blank
to ensure that the previous line is printed out. In type\setting terminology,
this is a quad centre command. See also [=Remaining width] for use of the
[[]c[]] command with the [[]w[]] command.
[3] FORMAT PAGE COMMAND [Faa,bb,cc]
This command sets the format for the output page. The command is
followed by three numbers, separated by commas. It is important that this
command be issued IMMEDIATELY after the title line. If not issued immediately
after the title, the parameters may not all take
effect on the very first page. If the
page format is to be changed later on in a file, this command should be given
immediately after a [[]P[]] command so that it will take effect at the
beginning of the following page. This command should be issued on a line by
itself, since all remaining characters on the line up to the end-of-line code
will be stripped. Note that the default settings in ACID can be permanently
changed as described in [=setting permanent defaults].
[4] aa: TOP MARGIN
`aa' represents a 1-3 digit number which specifies the number
of blank lines to appear after the title line and before the first line of
text. The default value for the drop is 2 which indicates that there are
normally two blank lines provided by ACID.
[4] bb: NUMBER OF LINES PER PAGE
``bb'' represents a 1-3 digit number which specifies the
number of lines to appear on each page of the final output. The default value
is 55 indicating that pages will be 55 lines long. The number of lines per
page does NOT include the title line or the top and bottom margins.
Note that in double column mode, the number of lines per page reflects the
number of lines in one column.
[4] cc: BOTTOM MARGIN
``dd'' represents a 1-3 digit number which specifies the
number of lines to appear in the bottom margin. A value of 0 has the
special meaning that instead of generating blank lines, a single form feed
code is output. The default value for the bottom margin is 0 (output
device has forms control).
[3] MARGIN COMMAND [Mnn]
``nn'' represents a 1-3 digit number which specifies the
column position of the right-hand margin for the page. For example a value
of 80 indicates that there will be 80 character positions from the extreme
left-hand margin to the right-hand margin. The default value for the right-hand
margin is 80. This command should be issued on a line by itself since
all following characters on the line up to the LF code will be stripped
as with the [[]f[]] command. The [[]m[]] command can also appear in the title
line.
[3] JUSTIFY COMMAND [J]
This command causes ACID to resume line justification which has
presumably been inhibited by a prior [[]n[]] command. This command sets the
normal mode in which ACID runs.
[3] NON-JUSTIFY COMMAND [N]
This command causes ACID to stop justifying lines of text. ACID will
still fill up the text to the right-hand margin, but will not add additional
spaces to the line to set a flush, right-hand margin. In typesetting
terminology, this command sets a ragged-right condition.
Note that this command is rarely used. In particular, it is NOT needed
nor intended for tabular material since the justification algorithm in
ACID does not interfere with tables. It is only used when the right-hand
margin justification is not desired.
[3] SWITCHED TEXT COMMAND [Sn]
This command causes all the following text to be conditionally
stripped out by the ACID program. ACID reads the decimal digit `n' following
the `S' and examines the associated run-time switch. If that switch is set
the [[]s[]] command is ignored and the following text will appear in the
output document. If the switch is not set, ACID will strip all the following
text until another [[]s[]] command appears. If the `n' is absent (i.e. the
command appears as [[]s[]]), ACID will automatically turn the listing
back on (if it was off). If the `n' is present, and the listing is
currently switched off, ACID will turn the listing back on and then
process the new [[]s[]] command. Conditional listings are not nested.
[3] PAGE EJECT COMMAND [Pnn]
If ``nn'' is absent (i.e. the command appears as [[]P[]]), ACID
will start the next line of text at the top of the next page.
If present, ``nn'' indicates that there must be at least ``nn' lines left
on the current page. If not, a new page is started. Otherwise, this command
has no effect. As with the [[]F[]] command, this command should appear
on a line by itself, since all remaining characters on the line will be
stripped out. If a page eject is required, all blank lines following
the [[]p[]] command are stripped and ignored. On a conditional [[]p[]]
command that is not going to cause an eject, these blank lines will
be retained. This makes it possible to insert blank lines only if a
page eject is not performed.
[3] FLUSH TEXT RIGHT COMMAND [R]
This command is used to set the prior text on the line flush
against the right-hand margin. For this command to work correctly,
the line of text should begin with a space (to ensure that the line
prior to the current line
is printed out). In typesetting terminology, this is a quad right command.
See also [=remaining width] for use of the [[]r[]] command with the
[[]w[]] command.
[3] SYMBOLIC REFERENCE COMMAND [=label]
This command is replaced by the section number and page number
associated with the specified section header. Because ACID is a 3-pass
program, forward references are permitted. In searching the section header
tables, ACID looks for the first section which matches all the text
specified in this command. Leading blanks are ignored during the comparison
and differences in upper or lower case are ignored. If the section header
does not exist, an error message will be generated on the console during
pass 2. In searching the tables, ACID first attempts to find a perfect
match. A perfect match means that the referenced section header not only
matches exactly but is also exactly the same length.
If no perfect match is found, ACID will use a header whose first part
matches the reference contained in the command. If the reference is
not completely unique, ACID generates an error message: [=section
reference is not unique].
[3] LEVEL COMMAND [n] section header
In this command, `n' represents a digit from 1-9 that specifies
the current level of the section number. Note that ACID automatically keeps
track of the sequential section numbers. The only information needed by
ACID is the current level of the section. ACID increments the number at that
level and then sets the levels of all subordinate sections back to zero.
The command is then replaced by the appropriate section number on final output.
Following this command, all text on the line up to the end-of-line code
is treated as a ``section header'' which is used to generate the index of
contents and also handle symbolic section references as described
immediately above. Before processing the section number, ACID checks
that there are at least four lines left on the current page. If there
are less than four lines, a new page is started before this new section.
The section header must fit on the current line without overflowing
the margin. If it is too long, an error message will be generated by ACID:
[=section header overflowed].
[3] SPECIAL CODE COMMAND [nnn]
This command is used to generate any ASCII code where `nnn' is
the octal value of the ASCII code to be produced. An important
point here is that the character generated with this command has
NO width to ACID. This feature has many uses. For example it can be
used to generate an ASCII code that can not normally be produced (such
as 376 which many editor programs treat as an ALTMODE). As another example,
if a 210 code is a backspace character, the sequence: ``=[[]210[]][[]257[]]''
will generate a `not-equals' sign, without affecting the justification
of the current line. Also, if only an upper-case terminal is available
for preparing source files, this feature is needed to generate the ASCII
codes: 340, and 373-376.
[3] VERTICAL TAB COMMAND [Vnn]
This command generates a vertical tabulation to line ``nn'' on
the output document. If line ``nn'' has already been passed, this command
has no effect. Otherwise, ACID generates the appropriate number of blank
lines to reach line ``nn''.
[3] REMAINING WIDTH COMMAND [Wx]
This command is used in conjunction with the [[]r[]] or [[]c[]]
commands to indicate where the remaining width of the line should be
placed. Normally, the remaining line width (or half the width for a [[]c[]]
command) is placed after the indent for that line. However, if a [[]w[]]
command exists at a previous spot on the line, that remaining width is
placed at that point. If a [[]w[]] command is not followed by a [[]r[]]
or [[]c[]] command, nothing appears on the final output. In typesetting
terminology, this is a quad middle command. The example below shows
a typical application for the [[]w[]] command. The first line shows
the original command in the source file, and the second line shows how
ACID processes that line:
This is set left[[]w[]]and this is set to the right[[]r[]]
This is set left[w]and this is set to the right[r]
If the [[]w[]] command is followed by another character, then
a ``leadering'' function is performed. Instead of spacing out the line
ACID duplicates the character after the `w' the appropriate number
of times to fill out the line as shown below:
ACID license[[]w.[]]$125.00[[]r[]]
ACID license[w.]$125.00[r]
[2] TITLE LINES
The first line of the first input file is treated as a title line for
all pages of the source document. If a title line is not wanted, this first
line must be blank. In processing the title line, five special commands are
allowed. All other ACID commands are illegal
and will cause an error message.
[3] DATE COMMAND IN TITLE
The [[]D[]] command is permitted in the title line and functions
as described previously.
[3] WIDTH COMMAND IN TITLE
The [[]w[]] command is permitted in the title line and functions
as described previously. However, no character is permitted after the `w'
(i.e.[ ]the `leadering' type function is not available in the title line).
The line width for the title line is specified either by an [[]m[]] command
in the title line or, if none was specified, by the last margin setting
in the text of the source document (remembered from the prior pass).
[3] PAGE NUMBER COMMAND
Within the title line, a [[]P[]] command indicates where the page
number is to go. Leading blanks are provided on the page number so that
the title line can be centred or set flush with the margins.
A page number of 2 would be represented as '[ ]2'.
[3] PAGE COUNT COMMAND
Within the title line, a [[]t[]] command indicates where
the total number of pages in the document is to go. Leading blanks are
provided on the page number as with the [[]p[[] command. This is
typically used as follows:
Page [[]p[]] of [[]t[]][c]
which generates:
Page 14 of 26[c]
where there are 26 pages in the entire document.
[3] MARGIN WIDTH IN TITLE
An [[]m[]] command in the title line defines the margin width to be
used for the title line. The command also sets the margin width for subsequent
text (if no other margin command is encountered). A subsequent [[]m[]] command
in the text will not affect the margin width used for the title line.
[2] AUTOMATIC HYPHENATION
Unless otherwise specified, ACID automatically hyphenates the text
when necessary. ACID depends upon conventional rules of suffix and prefix
extraction followed by application of logical rules. Owing to irregularities
in the English language, perfect hyphenation is impossible. Even with
extensive exception dictionaries there are still problems. For example the
word `present' can be hyphenated as `pre-sent' (as in <gift>) or
as `pres-ent' (as in <I-am-here>). Only exhaustive semantic analysis could
lead to the correct hyphenation.
Automatic hyphenation in ACID is extremely good considering that
an exception dictionary is not used. Accuracy is better than 95% and it
is relatively unusual for a really bad hyphenation point to occur.
It is true that ACID
hyphenates `screwdriver' as `screwd-river' but it does hyphenate `therapist'
as `ther-apist' rather than `the-rapist'!).
In conjunction with automatic hyphenation, remember that the discretionary
hyphen can be used to override the normal hyphenation point in a word. In the
event a word is hyphenated that should not be hyphenated at all, the [[]h[[]
command can be used to disable hyphenation on that word.
For aesthetic reasons, ACID will not
attempt hyphenation on the last line of a page.
[2] MANUAL HYPHENATION
In addition to the use of a discretionary hyphen, ACID has exceptionally
convenient features for run-time hyphenation of the text. ACID enters
manual hyphenation mode in pass 2 when the /M option is used
and when a line is underset. Manual hyphenation mode was the only mode
available with previous versions of ACID (4a and earlier).
An underset line is defined to mean
a line which can not justify to the right-hand margin even when an additional
space has been entered on every position on the line and one further,
additional space has been added after every space following a punctuation
character. All hyphenation points encountered in pass 2 are remembered for
pass 3 when the final output document is generated. This is convenient
because it means that the operator does not have to hyphenate the words
as the document is being printed.
When an underset line is found, the following action is taken
by ACID:
[3] OVERSET WORD
The word which overset the line is printed out on the console with
an indication as to the exact position in the word where the line is solid
set. Hyphenating after this position will be of no avail since the line will
still be overset. For example, if the word ``interesting'' caused the
current line to be overset, but there is room for the first 9 characters,
the following will be printed on the console:
INTERESTI'NG[c]
The quote mark indicates that the latest point at which the word
can be hyphenated is after the second `I'. After printing out the word,
there are four options available:
[3] OPTIONS FOR HYPHENATION
[4] TYPING A CARRIAGE RETURN
Typing a carriage return indicates that the word in question
can not be hyphenated, and the line should be justified as is, no mattter
how many spaces have to be added.
[4] TYPING A SEARCH CHARACTER
Typing any character in the word causes ACID to echo all
the characters in the word up to and including the character which matches
the search character (in a manner somewhat similar to the `.S'' search in
the OS/8 EDIT editor and FOCAL programs). At this point, all options still
remain open. In other words another search character can be typed in at that
point--in particular if the character appears twice, typing the character
again will cause ACID to continue echoing characters until the second
occurrence of the character is found. If the search character does not appear
in the word, the entire word will be echoed and ACID will then start over
again just as if a Rubout was typed.
[4] TYPING A HYPHEN
Typing a hyphen indicates that the word is to be hyphenated
immediately after the last character that was echoed on the console. For
example to hyphenate the word ``INTERESTING'' after the `S':
INTERESTI'NG (ACID prints word on console)
INTERES (User typed `S' for search)
INTERES-TING (User typed `-')
[4] TYPING A RUBOUT
Typing a rubout causes ACID to go back and print out the
word again on the console and start the search over again. It would normally
be used when the hyphenation point was accidentally skipped over.
[2] LINE JUSTIFICATION
In order to improve the legibility of the final document, ACID
ensures that justification spaces are inserted at random positions on the
line. The exact position for insertion of a justification space will remain
the same on subsequent runs of the program since the randomization algorithm
is based on the numeric character codes of the characters on the line that
is being justified. In inserting justification spaces, highest priority
is given to placing a blank after a period. Slightly lower priority is
then given to placing a blank after a punctuation character. The third
priority level is given to placing an additional blank after a period.
The fourth priority level is given to placing an additional space after
a punctuation character.
The fifth and lowest priority is given to placing a blank after a normal
justification blank. This algorithm ensures nearly optimal justification
of a mono-spaced font. In particular, note that unless a line is perfectly
set, a period will always be followed by at least two blanks. If the line
is perfectly set and still has a period, it is more desirable to leave only
a single space after the period than risk having the line badly underset by
removing the last word on the line and justifying the line without it.
[2] CAUTIONS ABOUT USING TAB CODES
Although the TAB code can be freely used in an ACID source, it is important
to realize that there are some restrictions on its use.
In most cases there will not be a problem: for example, on a [[][[][]] type
command, ACID knows that only a single character will be produced and
adjusts the column count accordingly. This means that if a TAB code follows
this command, the correct number of spaces will be generated by ACID to
maintain the original column position that existed in the source file.
However, there are some conditions under
which the expected number of spaces
may not be generated. The places to watch are:
[3] LINES WITH [D] OR [=] TYPE COMMANDS
If a line contains a TAB code after a [[]d[]] or
[[]-[]] type command there may be a problem owing to the fact that
the columns in the original source and the final output may not match
because the commands are not replaced by the same number of characters.
In this case, the user should carefully study the proof to determine
the correct spacing.
[3] LINES WITH [nnn] TYPE COMMANDS
With the [[]nnn[]] type command, ACID assumes that the character
has no width but does assume that it takes up one column position on the
final output. In this case, one has to be careful if such a command is
followed by a TAB.
[1] ACID ERROR MESSAGES
For all error messages, the file, page and approximate line number of
the location of the error in the original source file are printed
in front of the error message. All error messages are printed
on the console. In all cases, the line containing the error
will be omitted from the output file. The line on the output file
will contain just the file/page/line number of the approximate
location of the error.
Fatal errors cause ACID
to return to the OS/8 monitor after the message has been printed out.
[2] NON-FATAL ERRORS IN SOURCE FILE:
[3] LINE BUFFER OVERFLOWED
This error message indicates that the 200 character line buffer
overflowed without finding any spaces, hyphens or other points where the
line could be broken. This should only occur if a ``garbage'' file is
provided as input.
[3] SECTION HEADER OVERFLOWED
This error message indicates that a section header could not
fit on a single line. Section headers must fit on the current line
and, in any event, must be less than 80 characters long.
[3] UNDEFINED COMMAND IN '[]'
This message indicates that the character immediately following
the [[] is not a defined ACID command. Most likely cause is the use of
the [[] character in the text as a text character (it should have been
entered as [[][[][]]).
[3] NO ']' AT END OF COMMAND
This message indicates that the closing []] was not found in a command.
This message can also be generated if ACID finds the end-of-file and the
listings is still off from an [[]s[]] type command.
[3] LINE TO JUSTIFY HAS NO SPACES
This message appears when the justification circuit finds a line
that has no spaces at all. Most likely cause of this error (since it is
not usually a ``legitimate'' error is two or more blanks near the end of
a line that were not intended (ACID set a new margin indent when the blanks
were found).
[3] [D] COMMAND BUT NO OS/8 DATE ENTERED
This message is self-explanatory. If a [[]D[]] command is encountered
in the title line, it is treated as a fatal error.
[3] NUMERIC SYNTAX ERROR IN COMMAND
This message is generated for the P, V, F, and M commands when
an error is encountered in the numeric arguments.
[3] [=] TYPE REFERENCE NOT FOUND
A symbolic section header reference could not be found in the symbol
table.
[3] SECTION REFERENCE IS NOT UNIQUE
This message occurs when ACID can not find a unique match
on a section header. This error condition occurs if there are two
or more perfect matches, or, if there are no perfect matches, if
there are two or more imperfect matches.
[p8]
[2] FATAL ERRORS IN SOURCE FILE
[3] OUTPUT BUFFER HAS OVERFLOWED
This message occurs when the allocated space for the output file
on a directory device is not large enough to handle the output file.
[3] INSUFFICIENT MEMORY FOR TABLES (FATAL)
The symbol table that keeps track of
section headers has overflowed available memory. By using the /N option
the document can still be processed (although ACID will not generate an
index of contents, and [[]=[]] type references will not be allowed--
see [=/N option].
This message also occurs if the /D option is used with less than 16k memory.
[3] HYPHENATION TABLE OVERFLOW
The table which keeps track of hyphenation points for subsequent
processing in pass 2, has overflowed. There is room for 256 hyphenation
points which should be more than adequate for most purposes. If this table
legitimately overflows, discretionary hyphens should be inserted into the
text.
[2] FATAL SYSTEM ERRORS:
[3] USR ERROR 9
This message indicates that either the input or output device handlers
could not be loaded, or a fatal I/O error was returned by an OS/8 device
driver.
[3] USR ERROR 8
This message indicates that OS/8 returned a fatal error on the USR
CLOSE function. Most likely cause was an I/O error on the directory or an
overlay.
[3] USR ERROR 7
This message indicates that OS/8 returned a fatal error on the USR
ENTER function. Most likely cause is that the output device is a read-only
device, or that a directory device was specified for output but no name
was provided.