UTILITY

ALL RESOLUTIONS

1st Convert Utility

Changes a standard ASCII file to be reformatted in 1st Word or Word Writer ST.

by Roderick W. Smith

Roderick W. Smith is currently attending Oberlin College in Oberlin, Ohio, where he's majoring in psychology. He mainly uses his ST for word processing and communicating with Oberlin's VAX, but enjoys programming, as well.

How many times have you loaded a text file into 1st Word or Word Writer ST, only to find that the person who wrote it did not use 1st Word text format? The first time you did this, you may have tried reformatting the document, but to no avail.

Now, though, there is an answer: 1st Convert Utility. This program, written in Personal Pascal, will take a standard ASCII file and convert it so that it can be reformatted in 1st Word or Word Writer ST.

To run the program.

If you're a disk subscriber, simply click on the 1ST__CNVT.PRG icon; the program will load and run. If you don't have the program in a compiled form, though, you'll have to compile it yourself with Personal Pascal. My apologies to those without this language: I refuse to program in ST BASIC; Logo is inadequate; and Hippo C nauseates me. Since Pascal is the only other language I have, I used it.

If you have Personal Pascal, enter the editor and type in the program listing. Press the F9 key, and the program will be saved to disk and compiled automatically. Then you can run it. (Note: if you're using a RAMdisk, you should copy the source file to floppy or hard disk before running the program; certain typos might cause your ST to lock up!)

When the program runs, a dialog box will come up with a copyright message, three option buttons, and the usual "OK" and "Cancel" exit buttons. If your file is from a "generic" text editor, choose the "ASCII" source. Just about everything except space characters will be passed through as is. Paragraphs will be defined by two blank lines—so if there are no blank lines in the file, 1st Word will see it as one very large paragraph unless you do some manual editing.

If your source file is from ST Writer, choose the middle button. The codes for new paragraphs, line centering, underlining, superscripting, subscripting and page ejects will be recognized and converted to their 1st Word equivalents. Other control codes—such as margin settings, headers and footers—will be ignored, along with all the text after such codes on the same line. Finally, if your file was generated using WordStar on an MS-DOS or CP/M machine, select the third button. The codes for underlining, boldfacing/double-striking, superscripting, subscripting and forced page breaks will be converted to their 1st Word counterparts. Most "dot commands" will be ignored.

After you click on the OK button, you'll be presented with an alert box informing you that you must select the source file. Click on the "Ready" button, and a file selector dialog box will appear. Click on your source file, then on OK. Another alert box should appear, informing you that a 1st Word filename will be requested. When the file selector box appears, a filename will already be entered. This filename is the same as the one you selected as the source file, but with a .DOC extension. Click on OK if this is acceptable; or edit the pathname and filename fields. Do not enter the same filename as the original. When you click on OK, your file will be copied and converted. This may take a while if the document is of any length, so be patient. Make sure you have enough space on your disk to hold another copy of your document! When the conversion is finished, you will be asked if you wish to convert another file. A word of warning: do not remove your destination disk from the drive until the program is finished; Pascal appears to close the files only after the program is done.

You can now load 1st Word or Word Writer, and view or modify the converted document(s). Note that, especially with ST Writer files, the formatting may not be pretty—but that's not a big problem, since you can reformat the document at will. If you convert an ASCII file and find that 1st Word thinks it's one large paragraph, try deleting trailing spaces at the ends of all the paragraphs to eliminate the problem.

What the code does.

This section is intended for those interested in the actual workings of the program. Others need not read on.

The program begins—as does any other Pascal program which utilizes GEM—with a number of CONSTant and VARiable declarations and includes from the Pascal disk. The function TYPE__TRANSFER is the code that is necessary to put a dialog box on the screen. It consists of a call to NEW__DIALOG, followed by a series of calls to ADD__DITEM and SET__DTEXT, which add an item and specify what text that item is to contain, respectively. DO__DIALOG is all the programmer has to do to actually put the dialog box on the screen and allow the user to interact with it—GEM does the rest. The calls to OBJ__STATE determine which of the three buttons the user selected. END__DIALOG removes the dialog box from the screen, and DELETE__DIALOG deletes it from memory.

Procedure GETINFO returns the filenames for the source and destination files. At each call, the default pathname (DEF__PATH) is used, but the filename for the source (FILE__SIMPLE) is set to null. The procedure looks for a period in the input filename and, if one is found, uses its location to construct the default filename for the destination file.

Procedure HANDLELINE is the bulk of the program, and it contains many sub-subprograms. The first of these, NEW__LINE, simply starts a new line. TOGGLE__CODE toggles an internal flag (STATUS, the second parameter) representing what text style is currently being written. The first of its parameters is a CONSTant which, effectively, represents 1 bit of 6 which are used by 1st Word in determining text styles. This value is either added to or subtracted from STATUS, which is then written to disk. NEW__PAGE writes a blank line, which is necessary to avoid formatting difficulties should the user reformat the document, and then the code for a new page. FIX__CHAR strips the high bit from alphanumerics. This is required because WordStar sets this bit in the last character of each word in a file, making the file unreadable in 1st Word—and, for that matter, in most other word processors. DO__SIMPLE is the procedure called when the user requests an ASCII conversion; it merely replaces standard spaces with 1st Word's "variable spaces."

DO__STWRITER is considerably more sophisticated, and contains several subprograms of its own. Procedure NEXT__LINE is essentially identical to a READLN call, but works with ST Writer files. These files use the NUL character (ASCII code 0), instead of the usual carriage return. UP__ARROW is called whenever the code for begin superscript/end subscript is encountered. It has to determine whether subscripting is on or not, then toggle either subscripting or superscripting. DOWN__ARROW is UP__ARROW's counterpart for begin subscript/end superscript. CENTER__LINE is called whenever the center line character is encountered. It reads in the entire line, determines its length, writes out blanks, then writes out the text. Note that the procedure does not support any text enhancements except underlining. DO__STWRITER itself is nothing more than a CASE statement which calls earlier procedures.

DO__WORDSTAR is considerably less sophisticated than DO__STWRITER; this is because 1st Word's file format is more akin to WordStar's than to ST Writer's. Subprocedure CHECK__DOT checks to see if a period occurred in the first column. If so, it's a "dot command," and is either ignored or signals a page break. Like DO__STWRITER, DO__WORDSTAR is really a CASE statement which calls earlier subroutines, mostly TOGGLE__CODE.

PAST75 is a procedure which was originally designed for ST Writer files, but ended up being used for all files, simply out of caution. It is called only if the program's internal column counter exceeds 75. It's basically a miniature HANDLELINE, but it stops execution and puts in a RETURN when a space is read. This is the first place that the means for coding paragraph ends becomes readily apparent. 1st Word, throughout a paragraph, places what might be called a "null space" at the end of each line; but there is no such null space at the end of a paragraph.

The HANDLELINE main loop is mostly a WHILE loop which reads a character, strips the high bit for alphanumerics, calls a character handler, depending upon the input source, and advances the column counter. The procedure then rids itself of the end-of-line (EOL) by the READLN statement. The final IF statement determines whether the program should put out the null space which was mentioned above. If the column number is 1 (that is, if the line is blank), if the source is an ST Writer or WordStar file (which already have the null space at the end of the line), or if the next character is an EOL (that is, if the next line is blank), no space character is output.

The program's main procedure basically glues all these together and handles some preliminary initialization details. GEM is notified of impending use of its resources, the mouse is set to the arrow form, and a default pathname (the current drive's root directory) is defined. Then begins a loop which ends when the user does not wish to convert another file. STATUS is set to 128 (1st Word's code for normal text), the type of source file is determined, and both source and destination filenames are requested. Then the work begins: the mouse form is set to the "busy bee" and files are reset. If the file is an ST Writer file, the first thirty-four characters—which are junk as far as 1st Word is concerned—are read and ignored. Then, until the end of the file is reached, the HANDLELINE routine is called. Finally, the mouse is returned to its arrow form, the user is asked about further conversions, and, if no further conversions are wanted, GEM resources are, de-allocated and the program is exited.

Concluding remarks.

While controlling GEM will never be easy, Personal Pascal makes it at least somewhat simple, with redesigned GEM and AES calls. Even outside the GEM interfacing, the advantage of Pascal—or, for that matter, any other structured language—over something like BASIC in this program is also fairly clear, if you think about actually writing the program. I could contemplate what I wanted the program to do in very broad terms at first—handle a line here, put up a dialog box there—and only after writing this outline did I need to actually code the details, which I saw to be much simpler when viewed away from the context of the program as a whole. The clumsiness of subroutines in BASIC makes this more difficult to do, and the temptation to use GOTOs, if not resisted, results in code that's more difficult to follow, even to the person who wrote the program. In any event, I hope 1st Convert Utility will be used well by people—both in terms of converting files and in terms of learning about programming, if that's an interest of yours.