CP/M/CPM_CDROM.iso/lambda/soundpot/a/alphatxt.lbr/ALPHATXT.RZO/ALPHATXT.RNO

Text File | 1993-10-26 | 22.6 KB | 564 lines

.sk 15
.lm+14
******************************************
*                                        *
*    AlphaText Formatter Version 2.10    *
*                                        *
*                   by                   *
*                                        *
*            Richard M. Abbot            *
*                                        *
*            January 27, 1986            *
*                                        *
******************************************
.lm-14
.he AlphaText v2.10 User's Guide
.pa
DISCLAIMER
.js
.pp;The AlphaText Formatter may be used
freely  by anyone for  non-commercial purposes,  but may not be  sold,
included in a package for sale,  or used as an incentive to  buy,
by   any  person,   organization  or  corporation  without  prior
arrangement   with   the   author, Richard Abbot.
Furthermore, Richard Abbot will bear no responsibility for losses
resulting  from  the  use  or  inability  to  use  this  program.
ALPHATXT.COM  may not be distributed without ALPHATXT.DOC.
Finally, Richard Abbot shall retain all commercial rights to the AlphaText
program and related documentation.
.je
.sk 5
TRADEMARKS
.sk
CP/M            Digital Research Inc.
VAX-11          Digital Equipment Corp.
Turbo Pascal    Borland International
.pa
1. INTRODUCTION
.js
.pp  ;AlphaText is an embedded command ASCII text formatter
for CP/M based systems.  It is similar
in nature to several other public domain and commercial products.  Like
its predecessors, it
has the ability to produce professional quality formatted documents.
AlphaText, however, has several capabilities not present in many other text
formatters.  Its biggest "selling point" is that it can issue printer
dependent escape sequences to control the special features present
in many modern printers.  The user defines these sequences in a
printer definition file.  AlphaText can also output formatted text to the crt,
the lst: device, or to a disk file.  Disk file outputs can later
be printed with the pip utility, mailed to a BBS, etc.
.pp;No text editing capability is included in AlphaText.  The user is expected to
prepare his/her text inputs with a separate editor program.  There are many
fine quality screen-oriented text editors available, both in the
public domain and via commercial sources.
.pp ;AlphaText was coded originally in HP Fortran for the HP-1000
minicomputer.  It has been rewritten in BASIC 2.0 for the Commdore 64,
as well as BASIC 7.0 for the Commodore 128.  Both Commodore versions
also included a simple, line-oriented text editor to form a complete
word-processing package.  The text formatter portion was also ported to
the VAX-11/780 system in both BASIC and RATFOR.  AlphaText has now been
ported to the CP/M environment using Borland Turbo Pascal.
.pp ;This document provides a quick overview of AlphaText.  Users who are
familiar with other embedded-command text formatters should have no
trouble adapting to AlphaText.  Enough information is provided here to
initiate novice
users as well.
.pp ;Needless to say, this User's Guide was formatted using AlphaText!
.je
.sk 3
2. INSTALLATION
.js
.pp;The AlphaText product needs very little in the way of installation.
The library as supplied contains five files:
.sk
.lm+10
.je
1. ALPHATXT.CQM
2. ALPHATXT.RQO
3. ALPHATXT.DQC
4. PFORMAT.TXT
5. MAPCTLS.CQM
.lm-10
.js
.pp  ;The ALPHATXT.COM file is ready to execute.  The .RNO file
contains the
text for this document in raw form, to serve as a handy tutorial for
users.  The .DOC file is a formatted copy of the .RNO file, that
hopefully is pleasing enough to the user that he/she will continue
to pursue the matter.  PFORMAT.TXT is a copy of the printer definition
file in use at my installation.  The MAPCTLS.COM file is a utility
described in Appendix A.
.pp  ;The main user installation task is to customize PFORMAT.TXT
for the hardware in use at the user's site.  There
is no printer or font information embedded in
AlphaText itself; this data comes from the printer definition
file.  If a user has no need for
embedded printer code capability, then it is quite safe to run with
no PFORMAT.TXT file.  A warning will be displayed in this case.
.pp  ;The user can choose up to 23 printer format strings.  A string
is activated by embedding a corresponding control character
in the input text stream.  For example, an embedded
control-d will cause printer string 004 to be inserted in the text stream.
.pp;The printer definition file can contain two types of lines: comment
lines, which have a semicolon in column 1, and printer format lines,
which do not.  An arbitrary number of comment lines can be
included in the definition file.  A correct printer format line looks like:
.sk
.je
.ce ;018=027 070 032 002
.js
.pp;The line above contains the numeric notation for control
character desired (018 is ^R) , followed
by an equal sign, followed by groups of 3-digit decimal ASCII
strings, separated by blanks.  Note that there should be
--NO-- trailing blanks on the line.
.pp;Control-j, control-m, and control-z should not be chosen, as
those characters are special to CP/M.
No internal syntax checking is done on the printer definition file,
other than a check for correct line length.  For this reason, the user
should take care when creating PFORMAT.TXT.
.pp;Once the proper printer
format file is constructed, it should not have to be changed until
system hardware is changed.
.sk 3
.je
3. TEXT PREPARATION
.js
.pp;The user should prepare his/her text using an ASCII text
editor.  The embedded printer controls are control characters, so it
is helpful if the editor in use has the ability to take control
characters as input, and display them on output.  Most editors seem to
implement the input feature utilizing a control-p character prior to the
desired control character.  Fewer editors know how to display control
characters.  Some opt for the traditional display of an uparrow character
followed by the control character (^C for instance).  Other editors
adjust the video brightness (if possible) to shade control characters.
The worst situation is to have an editor which takes control
characters as input, but can not display them.
.pp;Embedded printer control codes should be typed in the following manner,
with no adjacent blanks:
.sk
.je
.ce;This line has^Uunderlined text^Vin the middle.
.js
.sk
In the above example, the user has defined ^U as the character for
"start underline mode" and ^V as the character for "cancel underline
mode."
.pp;An alternative exists for those users who prefer an editor that
does not handle control characters well.  The MAPCTLS utility can
convert control characters to printable characters, and vice versa.  MAPCTLS
is described in Appendix A.
.pp;AlphaText command lines have a period character (.) in column 1.  The
user should be aware of this, because any line that LOOKS like a
command line will be interpreted as such.  Sentences which inadvertently
place a period in column 1 will probably cause a formatting error message
later.
.pp;The user should try to stay within the traditional 80-column
screen boundaries
when preparing input text.  AlphaText
will compensate to an extent for extra-long
input lines, but the editing phase will be complicated by the
wrap-around (or hidden) text line fragments.
.je
.sk 3
4. FORMATTING PROCEDURE
.js
.pp;AlphaText needs up to three pieces of information to successfully
process user text: the name of the input file, the name of the
output device, and (if the output device is the disk) the name
of the output file.  The user may supply these data items on the
AlphaText command line or within the program by responding to
prompts.  The
user is free to mix and match
these methods as desired, as shown in the legal command
lines below:
.sk
.lm+10
.je
A> ALPHATXT
A> ALPHATXT C:TFILE.RNO
A> ALPHATXT B:PRICES.RNO S
A> ALPHATXT CANDY.RNO D
A> ALPHATXT STOCKS.RNO D B:STOCKS.DOC
.lm-10
.js
.pp;The device names that AlphaText recognizes are p (printer), s (screen),
d (disk), and n (null).  They may
be given in upper or lower case.  The file
extensions in the above examples (.RNO and .DOC) are used here out of
habit, and are in no way mandatory.  Any legal CP/M filename may be
used.  Note that AlphaText should always be run from the currently
logged disk drive.
.pp;If any error conditions are encountered during the formatting
process, the error messages are displayed on the crt along with the
number of the source line that provoked the error.  The user can use
the direct jump feature of his/her text editor to go right to the
offending line for inspection and correction.
.pp;The purpose of the null output device is to permit AlphaText to
function as a sort of "word compiler."  With a null output device, the
only output that AlphaText will produce will be the formatting error
messages that come out on the crt.  Users may wish to run AlphaText
with a null output device initially, to see if any formatting errors exist.
If control-p is entered before executing AlphaText, then the error
messages will be logged to the printer as well as to the crt.
Once these errors are corrected, AlphaText can be rerun with
document text output to
the printer.  This procedure will be economical if a user creates output
on expensive bond paper which should not be wasted.
.je
.sk 3
5. FORMATTING ALGORITHMS
.js
.pp;AlphaText is capable of producing three types of output text: unfilled,
filled, and justify-filled.  Unfilled text is almost a mirror of the
input text, differing only in the addition of
a leading left margin and paging.  Filled
text mode causes the maximum number of words to be packed onto each
output line, with the right text margin left jagged. In justify-filled
output mode, text is filled, and then sequences of blanks are added
between words to create a uniform right margin.
.pp ;There can be three types of input lines for AlphaText: literal lines,
command lines, and text lines.  AlphaText supports a literal mode, whereby
the input text is directly copied to the output area, with a left
margin string prepended.  This mode is useful if the input text
contains charts, tables, or crude "character graphics."  The only embedded
command recognized in literal mode is the .le command (literal end).
AlphaText command lines are easy to isolate by locating the leading period.
Most dot commands cause the immediate output of text, but a few
(such as .in, indention) insert text into the text buffer for later
extraction.  In both filled and justify-filled modes, normal text lines
are appended to a text buffer and extracted in chunks not larger than
the current page width.  A sliding buffer-start and buffer-end concept
is used, to minimize buffer housekeeping time.  When the buffer-start
address is near the top of the buffer, the buffer is reorganized in a
form of "garbage collection."  The text buffer is unconditionally
dumped prior to
the processing of all command lines, and when the end-of-file
condition is reached on the input file.
.pp ;The embedded font control characters are kept as such until the
very last operations of AlphaText, prior to output.  The control characters
are mapped into a blank character plus an appropriate escape sequence.
This is done to preserve text justification, where the position of the
control character was counted in the calculation that determines the
number of extra blanks needed to complete the line.
.pp;The justification of text is both a science and an art form.
Professional
typesetting programs use a technique called "proportional spacing," which
inserts minute amounts of space between printed letters.  The effect is to
produce a uniform-looking page of text.  AlphaText is less flexible, and
therefore must "try its best" to produce aesthetic pages of text via the
embedded-blank mechanism.  For the most part, AlphaText succeeds in this
effort.  There are sequences of input text which, due to long wordlengths,
just can not be justified aesthetically.  AlphaText realizes this, and will
produce a warning message when the user has called for justification
on an line which will be "sparsely populated" in the output document.
.sk 3
.je
6. FORMATTING COMMANDS
.js
.pp ;This section describes the 17 commands available in AlphaText.
.sk 2
.je
Margin Commands
.sk
.lm+5
1) .lm (Left Margin)
2) .rm (Right Margin)
.sk
.js
The margin commands have two forms: absolute and relative.
The absolute forms set the margin to a particular column, while
the relative
forms set the margins to a column value relative to the previous margin
value.
.sk
.je
Examples:
 .lm 5    sets left margin to column 5
 .lm+10   sets left margin to ten greater than current value
 .rm 60   sets right margin to column 60
 .rm-15   sets right margin to 15 less than current value
.sk
.js
Note that when using relative margin values, there may not be any
blank characters embedded in the command.  AlphaText also does not
check for "silly" combinations of left and right margin values.
It is up to the user to use sensible margins.
.je
.sk 2
.lm-5
Mode Control Commands
.sk
.lm+5
3) .fs (Fill Start)
4) .fe (Fill End)
5) .js (Justification Start)
6) .je (Justification End)
7) .ls (Literal Start)
8) .le (Literal End)
.sk
.js
These commands control the processing mode of AlphaText, as discussed in the
section on Formatting Algorithms.  The commands are designed to bracket
a block of affected text lines.  The justification mode is a superset
of the fill mode, so only the justification commands need be given
when justification is desired.  If no mode is requested, then the
unfilled mode is supplied by default.  All modes continue until changed
by another mode command.
.je
.lm-5
.sk 2
Paging System Commands
.lm+5
.sk
9)  .nm (Number Page)
10) .pa (Force Page Eject)
11) .he (Designate Header)
12) .fo (Designate Footer)
.sk
.js
These commands control the breakup of input text into physical pages.
The .nm command is useful when a document is split across several
input files, and will be formatted in sections.  With .nm, the user
can control the value of the first page number that AlphaText will use.
A good example of this can be found in the section on Formatting
Tips.  The .pa command will force the start of a new page at all times
EXCEPT when the output file is already at the top of a new page.
Form ejects are done via line-counting, a safer course of action than
assuming a particular formfeed character.  The header and footer
commands allow a string up to 65 characters long to be placed on the
top and bottom of each output page.  This document makes use of the
header capability.  Note that the .nm and .he commands take their
action on the NEXT text page, not the current page.
.sk
The .he and .fo commands may be given with or without a text string
on the command line.  When a text string is supplied, header (footer)
usage is enabled.  When no text string is supplied, then the output
of headers (footers) is cancelled as of the next output opportunity.
.sk
.je
Examples:
 .nm 3                            next page will be page 3
 .he This is some header text     designate header
 .he                              turn off header
 .fo And here is footer text      designate footer
 .fo                              turn off footer
.sk 2
.lm-5
Line Spacing Commands
.lm+5
.sk
13) .sk (Skip Lines)
14) .sp (Select Line Spacing)
.sk
.js
These commands control how text is spaced vertically in the output
document.  Each takes a numeric parameter which is not checked for
"sensibility" by AlphaText.
.sk
.je
Examples:
 .sk           skip one line
 .sk 1         skip one line
 .sk 12        skip twelve lines
 .sp 2         set double spacing
 .sp 3         set triple spacing
.sk 2
.lm-5
Text Shaping Commands
.sk
.lm+5
15) .ce (Center Text)
16) .pp (Begin New Paragraph)
17) .in (Indent Text)
.sk
.js
These commands control how text is indented and "shaped" on the output
page.  The .in command takes a numeric parameter which indicates how many
spaces to indent.
The .pp command is actually a combination of a .sk command followed
immediately by a .in 4; command.  The .ce command performs
centering between the current
pair of margin settings.  All three of these commands are followed by a
semicolon to delimit the command from the affected text.
.sk
.je
Examples:
 .ce ;This text will be centered
 .pp ;And this will start a new paragraph
 .in 4;Coincidentally, so will this
.sk
.js
Note that the .in command is the PROPER way to achieve indentation
with AlphaText.  One may supply lines to AlphaText that contain leading
blanks, but this will result in potentially uneven indentation, due
to AlphaText's justification algorithm.  This algorithm assumes that all
blanks found on a text line are possible justification points.
.je
.sk 3
.lm-5
7. FORMATTING DEFAULTS
.js
.pp;The user can create output text by completely specifying format
data with AlphaText commands, or he/she can rely on AlphaText defaults,
which remain in effect until changed by a command.  When AlphaText is
run, the following defaults are present:
.je
.lm+5
.sk
left margin =  5
right margin = 75
page number = 1
line spacing = 1
fill flag = false
literal flag = false
justify flag = false
header used  = none
footer used  = none
.lm-5
.sk 3
8. FORMATTING TIPS
.sk 2
A) The Waste Page
.js
.lm+5
.pp;As stated above, the .he and .nm commands take effect
on the NEXT text page, rather than the current one.  So if it desired
to have them take effect on page one of a document, the following
sequence may be used:
.sk
.lm+5
.je
 .nm 1
 .he This is the header
 .fo Not to mention the footer
 waste
 waste
 .pa
.lm-5
.js
.pp;It is worth noting that this "waste page method" is the only way
to have AlphaText number the first page of a document.
Normally, page one doesn't receive a page number
because it would look out of place on many common, single-page documents like
letters.  AlphaText will automatically start numbering on page two unless
the above sequence is inserted at the start of the input text.
.lm-5
.sk 2
.je
B) Rewards for Simplicity
.js
.lm+5
.pp;As discussed in the Formatting Algorithms section, it is possible to create
an input text sequence that just won't look nice when justified.  This
problem can be minimized by (gulp) the use of lots of small words, giving
AlphaText many choices of location for justification blanks.  Who knows,
the reader may appreciate it too!  In addition, text that contains
lines with NO blanks (i.e program listings with solid lines of asterisks) will
justify poorly, because AlphaText has nowhere for its blanks to go.
I have found that a small reorganization of input text, with a word added
or removed here or there, can often make the difference between nicely
formatted text, and "buckshot" text, with lots of holes.
.lm-5
.sk 2
.je
C) Good Behavior Please
.js
.lm+5
.pp;In the discussions above, the phrase "does not check" was used many times.
I wrote AlphaText to be a personal productivity tool, and geared its error
resistance to my own kindly, low-pressure user environment.
Rather than spend the time making every program operation monkey-proof,
I decided to spend my time on other matters (one of them being the creation
of a readable User's Guide).
It is definitely
possible to bomb this program by giving it inputs that don't make sense.
Users should resist the temptation to "walk on the wild side," and provide
program inputs that will result in a pleasing output document, rather
than a CP/M reboot.
.lm-5
.je
.sk 3
9. FINAL WORDS
.js
.pp;I hope that you will find AlphaText to be a
useful software tool.  I certainly enjoyed writing it.
.pp;I welcome all user bug reports, comments, and suggestions.  I can be
reached via id [72307,3125] on CompuServe.
.pp;GOOD LUCK WITH ALPHATEXT!!
.sk 3
.pa
.je
.ce;APPENDIX A
.sk
.ce;THE MAPCTLS UTILITY
.sk 2
.js
.pp;As mentioned in the section on Text Preparation, it is possible that
a user may prefer a text editor that does not handle control characters
well.  Some editors are ill-equipped for the input and output of
unprintable characters.
.pp;A utility program, MAPCTLS, has been included in the AlphaText
library to assist users who find themselves in this position.  MAPCTLS
can translate text in a bidirectional way: unprintables can be mapped
into printable strings, and later back into unprintable form.  In MAPCTLS,
control characters are represented by a three-digit decimal sequence
surrounded by square brackets.  For example, the string "[018]" would
be equivalent to control-r.
.pp;In MAPCTLS terminology, the conversion of a control-r to "[018]" is
called "expansion."  The conversion of the string "[018]" to a control-r
is called "compression."  MAPCTLS is executed as follows:
.je
.sk
.lm+10
A> MAPCTLS A.RNO E B.RNO
A> MAPCTLS B.RNO C C.RNO
.lm-10
.js
.sk
The general command format is the MAPCTLS command name, followed by the
name of the input file, followed by the operation code, followed by the
name of the output file.  The operation code may be either a "c" (for
compress mode) or an "e" (for expand mode).  In the example above,
the file c.rno will be identical in content to a.rno.  If a.rno contained
any embedded control characters, they will be expanded into digit strings
in b.rno.
.pp;MAPCTLS allows all users an additional degree of freedom when preparing
input for AlphaText.  It is possible for a user to embed strings that are
meaningful to him/her in the input text, and then use the "global replace"
command found in many editors to globally substitute a string meaningful
to MAPCTLS (or to AlphaText for that matter).  For example, a user
could type:
.je
.sk
.lm+10
here is a sentence with(UNL_ON)underlined text(UNL_OFF)
.lm-10
.sk
A global replacement editor command could change this string to:
.sk
.lm+10
here is a sentence with[006]underlined text[007]
.lm-10
.sk
Finally, MAPCTLS would change the string to:
.sk
.lm+10
here is a sentence with^Funderlined text^G
.lm-10
.sk
.js
which is what AlphaText understands.  The degree to which a user
makes use of MAPCTLS will depend on how sophisticated his/her
text editor is, and also on how much the user is willing to pay in
increased text entry effort for increased clarity within the text.
.pp;MAPCTLS provides a nice way for a user to get a copy of a raw
AlphaText input file that can be safely sent to the lst: device.  The
utility will also be useful in the general situation where a user
wants to print a file that may be corrupt.
.pp;If one's text editor is satisfactory, one never need make use
of MAPCTLS.  But it's nice to know that it's there.
rupt.
.pp;If one's text editor is