****************************************** * * * AlphaText Formatter Version 2.10 * * * * by * * * * Richard M. Abbot * * * * January 27, 1986 * * * ****************************************** AlphaText v2.10 User's Guide Page 2 DISCLAIMER 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. TRADEMARKS CP/M Digital Research Inc. VAX-11 Digital Equipment Corp. Turbo Pascal Borland International AlphaText v2.10 User's Guide Page 3 1. INTRODUCTION 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. 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. 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. 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. Needless to say, this User's Guide was formatted using AlphaText! 2. INSTALLATION The AlphaText product needs very little in the way of installation. The library as supplied contains five files: 1. ALPHATXT.CQM 2. ALPHATXT.RQO 3. ALPHATXT.DQC 4. PFORMAT.TXT 5. MAPCTLS.CQM 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. AlphaText v2.10 User's Guide Page 4 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. 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. 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: 018=027 070 032 002 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. 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. Once the proper printer format file is constructed, it should not have to be changed until system hardware is changed. 3. TEXT PREPARATION 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. Embedded printer control codes should be typed in the following manner, with no adjacent blanks: This line has^Uunderlined text^Vin the middle. AlphaText v2.10 User's Guide Page 5 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." 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. 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. 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. 4. FORMATTING PROCEDURE 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: 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 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. 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. 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 AlphaText v2.10 User's Guide Page 6 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. 5. FORMATTING ALGORITHMS 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. 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. 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. 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 AlphaText v2.10 User's Guide Page 7 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. 6. FORMATTING COMMANDS This section describes the 17 commands available in AlphaText. Margin Commands 1) .lm (Left Margin) 2) .rm (Right Margin) 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. 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 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. Mode Control Commands 3) .fs (Fill Start) 4) .fe (Fill End) 5) .js (Justification Start) 6) .je (Justification End) 7) .ls (Literal Start) 8) .le (Literal End) 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. Paging System Commands AlphaText v2.10 User's Guide Page 8 9) .nm (Number Page) 10) .pa (Force Page Eject) 11) .he (Designate Header) 12) .fo (Designate Footer) 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. 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. 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 Line Spacing Commands 13) .sk (Skip Lines) 14) .sp (Select Line Spacing) 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. 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 Text Shaping Commands 15) .ce (Center Text) 16) .pp (Begin New Paragraph) AlphaText v2.10 User's Guide Page 9 17) .in (Indent Text) 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. Examples: .ce ;This text will be centered .pp ;And this will start a new paragraph .in 4;Coincidentally, so will this 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. 7. FORMATTING DEFAULTS 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: 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 8. FORMATTING TIPS A) The Waste Page 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: .nm 1 AlphaText v2.10 User's Guide Page 10 .he This is the header .fo Not to mention the footer waste waste .pa 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. B) Rewards for Simplicity 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. C) Good Behavior Please 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. 9. FINAL WORDS I hope that you will find AlphaText to be a useful software tool. I certainly enjoyed writing it. I welcome all user bug reports, comments, and suggestions. I can be reached via id [72307,3125] on CompuServe. AlphaText v2.10 User's Guide Page 11 GOOD LUCK WITH ALPHATEXT!! AlphaText v2.10 User's Guide Page 12 APPENDIX A THE MAPCTLS UTILITY 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. 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. 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: A> MAPCTLS A.RNO E B.RNO A> MAPCTLS B.RNO C C.RNO 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. 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: here is a sentence with(UNL_ON)underlined text(UNL_OFF) A global replacement editor command could change this string to: here is a sentence with[006]underlined text[007] Finally, MAPCTLS would change the string to: here is a sentence with^Funderlined text^G 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 AlphaText v2.10 User's Guide Page 13 entry effort for increased clarity within the text. 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. If one's text editor is satisfactory, one never need make use of MAPCTLS. But it's nice to know that it's there.