SPECIAL SYMBOLS LIST

• <CR> - carriage return. A space or move to a new line just before or after <CR> is not a space to be typed; it is there to improve readability.

Computer braille: Samples of print data entry are transcribed in computer braille. The letters in special entry codes are always lowercase. transcriber's notes will point out capital letters where significant. We distinguish a few punctuation marks, like tilde which is ordinarily the same as caret, with a prefix of dots 5-6; see Special Symbols List in Volume I.

Symbols used when not in computer braille:

• # - print number sign.
• $ - dollar sign, as in the chapter name MAKE$.
• % - per cent sign.
• < - less-than.
• > - greater-than.

TRANSCRIBER'S NOTES

Embedded Commands; Entry Codes

Embedded commands, like the TranscriBEX \\ (backslash backslash) and BEX $$ (dollar dollar) commands, appear in computer braille, as you would enter them on a braille keyboard. The letters in them are lowercase print letters. When punctuation immediately follows such a command, it is preceded by dots 4-5-6. Material enclosed in computer braille parentheses of with is shown in computer braille; we show data entry codes this way--for example, ( $p ).

Computer Dialog

Computer dialog sessions are presented in computer braille, with each computer screen line outdented. The print manual uses courier font (typewriter-style printing). A semicolon ; means the rest of the line is what you enter.

Sample Text Entry

Samples of print text entry are shown in computer braille. The print manual uses courier font. Except when next to a <CR>, a space or move to a new line in these samples means a space to be typed. (Just before or after <CR>, it is there only for better readability.)

CONTENTS

• ChapterPage

Section 18: Master Level TranscriBEX

As we were writing the TranscriBEX manual, we kept thinking up clever tricks and techniques for "power users." Eventually, they've all wound up in this grab-bag Section, which assumes that you're very familiar with both BEX and TranscriBEX. All along we've been sending you back to certain portions of the BEX Dox. For this Section, we hope you've read and understood all of the User and Master Levels. Part 1 explains why MAKE$ exists. Part 2 discusses three "do-it-yourself" \\ commands experienced transcribers may find useful. Part 3 details two $$ commands you can enter in your final braille chapters. Part 4 assumes you've configured at the Master Level: it describes some TranscriBEX-SPECIFIC ways of using the Zippy chapter. Part 5 skims the surface of a fascinating and complex topic: working with files from other programs. Section 10 of the User Level is good background reading for this. Part 6 provides a step-by-step example of transferring AppleWorks files to BEX.

Part 1: Inside MAKE$

As you use TranscriBEX more and more, sooner or later you explore a formatted chapter in the Editor. There you encounter the $$ commands that actually control TranscriBEX's braille formatter. (The really adventuresome may have directly explored the MAKE$ transformation chapter, having first made a copy.) You may wonder why we have not provided a list of what these $$ commands do. With such a list at hand, it might seem that you could create your own formats for any and every transcribing situation. The TranscriBEX design team deliberated long and hard over this issue: here are our reasons why we do not document the $$ commands that MAKE$ creates.

These TranscriBEX-oriented $$ commands are very complex; they interact in non-intuitive ways. Documenting how they work would require tremendous effort with very little reward. It's more than explaining what each command does--essentially, it would mean teaching you everything we know about the inner workings of BEX's Print program. You'd need to understand this to see why commands must be issued in a particular order, and why some combinations of commands don't work in the ways you might expect.

Not convinced? Here's the explanation for just one of the $$ commands: "$$vx -- set MAINOUT for non-zero. This flag is used to set BWID\\ to take into account the effects of the right margin. See routine S/EWID. The value BWID\\ is used for $$vr, $$vj, $$vk, and $$vq."

Even when you know what $$ commands to use, it's tricky to enter them correctly. We know this from our experience. When we started doing transcribing at Raised Dot, we were occasionally too lazy to go through the entire TranscriBEX process. "We know what MAKE$ creates," we confidently murmured to ourselves, "let's just enter those commands directly." Guess what? We always made at least three mistakes. Even for TranscriBEX's designers, using the \\ commands is the only way to ensure correct format.

Most importantly, providing you with the nitty-gritty details of how the Print program executes $$ commands contradicts the fundamental TranscriBEX approach. Our goal is to increase the availablility of properly-formatted braille; our method is to provide people with \\ commands that relate to the intent of the braille format. To help satisfy the needs of the most exacting transcriber, we've supplied a few do-it-yourself \\ commands, which we describe next. Part 2 also explains how you can request us to design new braille page formats. There are two $$ commands that expert TranscriBEX users can enter in their text--more details in Part 3.

Part 2: Do-it-yourself \\ Commands

Adding centered dashes with \\majording and \\minording

Some transcribers have requested the ability to generate a centered line of some sort of dashes. These distinctive lines are sometimes seen separating articles and sections in braille magazines and catalogs. In print, non-text decorations like this are called "dingbats"; the parallel TranscriBEX commands are \\majording and \\minording. Both commands generate a centered line of symbols: the variation is the symbol used. The \\majording command immediately generates a centered line of twelve dot 2-5's (dropped Cs, the digit 3 in screen braille). The \\minording command immediately generates a centered line of twelve dot 5's (the quote symbol in screen braille). Here's a sample of its placement:

[article] $p \\majording $p \\hd [heading]

No blank lines precede or follow the line of dashes in the samples we've seen. When you'd like one line skipped before or after \\majording or \\minording, use the skip-line ( $s ) indicator.

Changing the "number zone" with \\rightzone#

The do-it-yourself \\rightzone# command lets you change the size of the "number zone" on the right hand side of the braille page. This "number zone" contains page numbers in tables of contents and line numbers for poems and plays with numbered lines.

Section 12 describes the TranscriBEX \\ commands for five basic table of contents formats. All these commands assume that the braille page number never exceeds five characters in length. (In print, that's a 4-digit number--the extra character is the number sign.) The Code requires a space before the page number, and you must count this space when calculating the value # in \\rightzone#. In other words, the table of contents commands have \\rightzone! built in to them.

The \\rightzone! is an arbitrary value and it violates one provision of the Code. (The Code requires that the "number zone" vary with the length of the page number within it: it should be one cell larger than the longest page number on each table of contents page. This means that the table of contents pages for pages 1 through 200 should have a smaller "number zone" than the table of contents pages for pages 1000 through 2000.)

In some cases, you wish to decrease the length of the number zone. Suppose you're transcribing a short book; the highest page number is 88. In braille that's three cells; using \\rightzone. in this situation more closely conforms to the Code's requirements.

When your page numbers are longer than 4 digits, you should increase the number zone with the \\rightzone# command. This command must follow immediately after the \\contents command from CLIPHEAD. For example, you're transcribing a literary table of contents for a multi-volume work; the first volume contains the entire table of contents. To allow for twelve-character page numbers plus one space before them, you enter:

\\contents \\rightzone,: \\hd CONTENTS$so\\hd VOLUME I$so\\left ... (etc.)

No matter what width you set with \\rightzone#, the actual data you place in the zone must be one BEX word. A BEX word is defined as a group of characters bordered by spaces or <CR>s. For example, your supervising agency requires that the table of contents shows both the print and braille page numbers, and these numbers must be separated by one blank cell. If you enter

<CR>\\con Chapter 6: Understanding Glacial Action \\gd b285 p102 <CR>

The page number is two words, and things won't be formatted correctly. The answer is to use a "sticky space," a non-breaking space that joins the two page numbers into one BEX word. The sticky space token is control-S; To enter it in the Editor, enter Control-C followed by plain S. On the Editor screen the sticky space appears as an underlined S; we show it in the following sample as <S>.

\\con Chapter 6: Understanding Glacial Action \\gd b285<S>p102 <CR>

(The sticky space is introduced in M6-1. In that discusion, we stress the importance of $$ss, which enables the control-S as the sticky space token. You don't need to worry about $$ss in TranscriBEX; its function is automatically built in to the core \\ commands.)

Section 16, Part 4 explains the \\ln [number] command you use to place line numbers for poems and plays. Before you can enter \\ln [number] commands in your poem, you must activate this feature with \\numberedlines. The "line number zone" built into \\numberedlines assumes that no line number exceeds 5 digits in print. (You don't use a number sign before these line numbers; TranscriBEX automatically suppresses it.) To change the value of the line number zone, place a \\rightzone# command immediately after the \\numberedlines command. Here's an example of widening the line number zone to 8 characters:

\\poem \\conlevel \\numberedlines \\rightzone?

Do-it-yourself paragraph formats: \\i#r#

After you've become thoroughly familiar with TranscriBEX and the braille formats it supports, you may encounter some transcribing situations TranscriBEX does not specifically handle. BEX's formatter controls paragraph formats in a relatively isolated way; this allows you to change indent and runover values without messing up other aspects of page format. That's why we were able to design open-ended \\ commands to control indent and runover.

You use the \\i#r# commands for "do-it-yourself" formatting of braille paragraphs. The I stands for Indent and the R stands for runover: to establish indent to cell 5 and runover to cell 3, you enter \\ienr: in your text. The value of # must be an odd number from 1 up to and including 11. Always place \\i#r# before the first paragraph ( $p ) or skip-line ( $s ) indicator you wish to affect. The beginning of each paragraph is placed at the specified indent; subsequent lines go to the specified runover.

When foreign language material is presented with a parallel English translation, \\i#r# is the way to go. The Code requires that the foreign text indent to cell 3 and runover to cell 1 while the English translation indent to cell 7 with runover to cell 5. This is what you’ enter:

\\i3r1 $p [Foreign paragraph] \\i7r5 $p [English translation] \\i3r1 $p [Foreign paragraph] \\i7r5 [english translation] \\i3r1 $p [Foreign paragraph] \\i7r5 $p ...

If you're unsure about the correct indent and runover for a particular situation, consult an experienced transcriber. We've provided these do-it-yourself commands for experienced transcribers who are well-versed in the format requirements of the various braille codes.

Bypassing some hierarchical commands

In Section 11 we introduced a hierarchical family of commands for complex indexes: the \\mi and \\si family. We introduced a similar family of commands for complex tables of contents in Section 12: the \\con, \\mc, and \\sc family. When you use these sets of commands the first few times, it's best to follow the directions exactly and enter one command before each index or table of contents entry. When you're more familiar with how these command families work, there is a shortcut.

When you have two entries in a row that are of the same level, you don't need to enter the hierarchical command again. For example, when a table of contents has two main sections, each with five subsections, you can enter them as follows:

[Contents heading] \\mc Section 1 <CR>

\\sc Part 1 <CR>

Part 2 <CR>

Part 3 <CR>

Part 4 <CR>

Part 5 <CR>

\\mc Section 2 <CR>

\\sc Part 1 <CR>

Part 2 <CR>

Part 3 <CR>

Part 4 <CR>

Part 5 <CR>

You can't omit the <CR> between each row. If you did, TranscriBEX wouldn't know when to move to the next line; it would treat subsequent entries as continuations of the first.

These are the only two familes of hierarchical commands that this trick applies to. DON'T try to use this shortcut for long outlines or poems; it won't work.

Requesting custom page formats

As we stated in Section 1, Part 3, we're quite willing to consider your documented request for support of non-standard braille formats. We'd like to accommodate a great number of additional formats, but there are some unavoidable limits to our ability to do so.

We designed TranscriBEX to support most of the translation rules and page formats described in the Code of Braille Textbook Formats and Techniques and English Braille--American Edition. Supporting the rules and formats from these two books strains the Apple 2's capacity to the utmost. We're very close to physically running out of program space in the Apple's work-memory. We must leave ourselves enough room to fix the bugs that inevitably rear their ugly antennae.

However, in the process of creating TranscriBEX, we've developed a rich and varied selection of $$ format commands. It's possible that some combination of these commands may be able to create the non-standard format you desire. If you wish TranscriBEX to support a non-standard format, please supply us with the following information: In- dent and runover values, where braille page numbers appear, where (or if) print page indicators appear, placement of runningheads, and most important of all, what other TranscriBEX \\ commands are used in conjunction with the new format. This last item is crucial because of how the $$ commands can interact.

For example, you want a 9-digit braille page number at the end of line 25 with no runninghead and no print page indicators. Paragraph formats alternate between standard (indent to cell 3, runover to cell 1) and blocking to cell 7. You wish to use major, minor, and centered headings, or \\hd, \\mh, or \\c, in TranscriBEX parlance. Finally, this format must also support numbered lines of poetry.

Along with a detailed description like this, please supply hard copy braille samples of this type of format. With this information in hand, we'll be able to research the question: "Can we effect this format using the existing $$ commands?" If the answer is "yes," we'll advise you on how to do it. If the answer is "no," please understand why maintaining TranscriBEX's ability to support standard page formats takes precedence over more experimental techniques.

Part 3: Adding $$ Commands to Braille Chapters

Now that we've hectored you about the impossibility of understanding TranscriBEX's $$ commands, it's time for an abrupt about-face. There are indeed two $$ commands that you can safely enter directly in your braille chapters: $$vl# and $$vn.

Check MAKE$, and you'll see that \\nobreak# is simply replaced by $$vl#. Check the BEX Dox, page U7-13 and you see that $$vl# is the "variable discretionary page break."

When the formatter executes the $$vl# command, it compares the value of # with the number of lines remaining on the current page. For example, the formatter encounters as it starts line 22 on the braille page. Since there are less than five lines remaining, the formatter immediately moves to the next page.

Understanding this, you can enter $$vl# in your final braille chapters when it's really necessary. Suppose you're transcribing hierarchical poetry. The Code says that when more than one braille line represents a single print line at a particular level, the braille lines should not be broken between two braille pages. You can't enter the appropriate \\nobreak# in your \\ chapters, because you can't know how many braille lines the text occupies until you preview the final braille chapter.

In this case, when you preview your chapter, you notice a problem where one print line is represented by three braille lines. The first two braille lines occupy lines 24 and 25 of one braille page; the third braille line appears at the start of the next braille page, violating the Code. In this situation, you can enter $$vl5 in your braille text at the beginning of the first troublesome braille line. The next time you preview it, the formatter moves to a new braille page before it prints the first braille line. You must enter $$vl3 after the ( $s ) or <CR> that begins the first line. You're instructing the formatter to move to a new page unless there are 3 lines remaining in the current page. If you place $$vl3 before the ( $s ) or <CR> that begins the first line, then the formatter counts it as one of the three lines.

The other $$ command you can enter in your final braille text is the "discretionary page break" command, documented in the User Level, page U7-12. Check MAKE$, and you see that \\newpage is simply replaced by $$vn. (You'd also see that $$vn appears in a number of other \\ commands as well, wherever the codes require that a particular format begin on a new braille page.) When the formatter encounters $$vn it immediately moves to a new page, unless that would create a blank page. This means that when the formatter encounters the $$vn as it's about to move from line 25 of one page to the top of the next, it ignores the $$vn command. For that reason, two $$vn commands in a row don't create a blank page.

You're probably thinking, "Well why not use the $$vn command in the poetry situation described above?" While it would accomplish the same thing, we don't recommend it. If for any reason the length of your braille text changes, using $$vn would waste space. For example, if you later delete one poem from the text, the "problem" poetic line of the previous example could appear on lines 10 through 13 on the braille page. When the formatter ecnounters the $$vl5 in this situation, there are at least 3 lines left, so the formatter does not advance to a new page. But if it encountered $$vn, it would faithfully move to a new page, and lines 10 through 25 would be wasted.

Part 4: TranscriBEX and the Zippy Chapter

The Zippy chapter, introduced in the Master Level, Section 7, can really turbo-charge TranscriBEX. That's because the contents of the Zippy chapter are in memory rather than on disk. Replace characters and Grade 2 translation speed up considerably when they don't need to read from and write to disk. It's perfect for people with a one-drive Apple 2c system, since much less disk-swapping is involved. Although the benefits are considerable, the technique we describe here is a little riskier than the standard TranscriBEX process. You must consciously and conscientiously copy the Zippy chapter to disk to make a permanent record of your work. Don't attempt to Zippy the TranscriBEX process until you're quite comfortable with the Zippy chapter.

Here's the general technique. Copy MAKE$ and FINETUNE to your BEX program disk. Do your data entry in the Zippy chapter. Save your work by copying the Zippy chapter to disk occasionally. For purposes of example, let's call this chapter TEXT--copy the Zippy chapter to TEXT each time you save it. When you've proofread the \\ command chapter and it's ready to roll, copy to disk one more time. As always, saving your original \\ command chapter is essential.

Use Replace characters with MAKE$ to change the \\ commands to $$ commands in your text. Since we've saved the \\ chapter to disk, you can specify the Zippy chapter as both source and target chapter for Replace characters. Replace characters reads and writes from memory, so it's much faster than when the source and target chapters are both on disk. Now your \\ chapter's on disk, and the $$ chapter is in the Zippy chapter.

As soon as Replace is finished, use option G - Grade 2 translation, again specifying the Zippy chapter as both source and target chapter. When this is done, your $$ chapter is gone, and the Zippy chapter is your grade 2 chapter. When you want to FINETUNE your braille, use the Zippy chapter as source and target yet a third time for Replace characters with the FINETUNE transformation chapter. (Now the finetuned braille chapter is in Zippy; all the intermediate chapters are gone, and your original \\ command chapter is safely on disk.)

Print the Zippy chapter to your braille previewer, Printer 3. If everything looks great, copy the Zippy chapter to disk, adding the two characters "$2" to the original \\ chapter name. The only two chapters you need to save are now on disk: the original \\ chapter, TEXT, and the formatted, translated, finetuned chapter, TEXT$2.

When there are format problems with the processed Zippy chapter, don't bother to Kill it off. Simply overwrite the bogus braille in the Zippy chapter by copying the original \\ chapter from disk to the Zippy chapter. Fix the errors in the Zippy chapter and copy it back to disk to save your work. Now, go through the whole procedure again. Once you've tried this technique, you'll probably become addicted to the speed. As a summary, here's a sample of the computer dialogue. The Zippy chapter's name is always the single Delete character; it's shown here with <DEL>.

Main: C

Copy chapters

Chapter: <DEL> <CR>

Chapter: <CR>

Target chapter: TEXT <CR>

Main: R

Replace characters

Chapter: <DEL> <CR>

Chapter: <CR>

Target chapter: <DEL> <CR>

Use transformation chapter: 1make$ <CR>

Continue? arY <CR>

Chapter <DEL> Done Main: G

Grade 2 translator

Chapter: <DEL> <CR>

Chapter: <CR>

Target chapter: <DEL> <CR>

Chapter <DEL> Done

Main: R

Replace characters

Chapter: <DEL> <CR>

Chapter: <CR>

Target chapter: <DEL> <CR>

Use transformation chapter: 169netune <CR>

Continue? arY <CR>

Chapter <DEL> Done

Main: P

Print chapters

Chapter: <DEL> <CR>

Chapter: <CR>

Which printer? 3 <CR>

You preview the text with Printer 3 and it looks great. The final step goes like this:

Main: C

Copy chapters

Chapter: <DEL> <CR>

Chapter: <CR>

Target chapter: TEXT$2 <CR>

Super-charged tables

There's an even faster technique when you are working on material that fits in one BEX page. It's particularly appropriate for tables, since they're short and you usually need to process them two or three times for perfect format. As we warned in Section 9, Part 2, the safe upper character count for tables is much smaller than for prose text. It depends on the number of columns: with a 4-column table, limit the page to 1100 characters.

The plan here is to create two identical copies of your \\ chapter: one on the Clipboard and one in the Zippy chapter. The Clipboard serves as temporary storage for your print \\ command data. The Clipboard can contain up to one full BEX page; these characters are stored in a special pocket of memory outside of any chapter.

Start out by entering your data in the Zippy chapter. Proofread the \\ commands using control-V mode (M3:2), where you can print to the 80-column screen without leaving the Editor. When you're ready to Replace characters with MAKE$, copy the entire page onto the Clipboard. Enter control-B X to exchange the current page with the Clipboard. Your cursor is now at position 0; enter control-D A to delete any material that had been on the Clipboard prior to the exchange. Now, enter control-B I to Insert the contents of the Clipboard in the page. You now have two identical copies of your table: one's on the Clipboard and one's in the page. (Caution demands we tell you to copy the Zippy chapter to disk at this point. Honesty demands that we tell you we never bother.)

From now on, proceed as in the last sample: specify the Zippy chapter as both source and target as you format your text with MAKE$, then use the Grade 2 translator to translate it, then use Replace characters with FINETUNE to make the braille perfect. Finally, print the Zippy chapter braille table to your braille previewer.

When the text is perfect, Edit the Zippy chapter once more. Move to BEX page 2 and insert the contents of the Clipboard--your original print \\ data. Quit the Editor and Zip over to the Page menu. Option G - Grab pages into another chapter allows you to create new chapters. Grab page 1 of the Zippy chapter into TA$2; Grab page 2 of the Zippy chapter into TABLE. You can merge these one-page chapters into the surrounding text at your leisure, following the hints in Section 9.

As if this weren't fast enough, here at Raised Dot we've automated the process one more step. We wrote an Automatic procedure chapter that enters the Editor, copies the page to the Clipboard, quits the Editor, then does Replace and Grade 2 translation. Before handing control back to the user, this Auto chapter prints the Zippy chapter to printer 3. We've saved it on our program disk as "TTT." Once \\ data entry is complete and we quit the Editor, we enter control-A at the Main: prompt. At the "Auto chapter:" prompt, we enter 1TTT and then stroll down the hall. When we come back to the computer two minutes later, the first page of the formatted braille table is waiting to be proofread on the previewer screen.

Part 5: Working with Files from Other Programs

In some ways, BEX and TranscriBEX are unique: few other Apple word processing program produce textbook format braille! The basic elements of BEX are common to all word processors: you enter and correct text in some form of editor; you save your work on disk in some type of file; you control output to printers with some sort of print formatting program. The single most time-consuming step in the TranscriBEX process is the original data entry. Once the text you wish to transcribe is on disk, then the BEX-SPECIFIC fun--Replacing, translating, and previewing--begins.

The fundamental similarity of word processors means that you don't have to do your data entry in BEX. Any word processor that can save data as either DOS 3.3 or ProDOS textfiles can be used for TranscriBEX data entry. Before we go any further, we'd like to present an argument against infringing on our copyright. The BEX licensing agreement assumes that you treat BEX and the TranscriBEX module as you'd treat a book. Only one person can use it at one time. You don't photocopy an entire book so that your co-worker can read it: you buy another copy. We're providing you with information about using files from other programs for two situations. Since it's maximized for voice and large print output, some sighted people find BEX's Editor a little clunky. You may yourself own another Apple word processor whose editor you prefer. We want to allow you the flexibility to do the bulk of your data entry with that other program. You can then use BEX's Editor to make minor corrections.

Alternatively, you may be fortunate enough to have willing volunteers on hand who are eager to help in the creation of braille. These people can use another Apple word processor for print data entry, and then hand their disk over to you for addition of \\ commands.

Remember, only you can discourage software piracy and encourage careful program development and support. Please, please, please don't photocopy the TranscriBEX manual and pass it out to those volunteers! If you're interested in setting up a transcribing system with several TranscriBEX users, please contact us. We've designed a "Transcriber's Package" for just that situation.

Overview of file transfer issues

Before we dive deep into the specifics of file transfer, here are some words of wisdom from burned-out (or is that experienced?) professionals. First and foremost, pace yourself. Never accept data files from other programs with the promise to make perfectly-formatted braille by the next morning. Creating a routine requires some time: it's basically trial and error. Once the routine is established, however, it's very straightfoward.

Secondly, transferring files between programs requires that you're comfortable in the Apple environment. You should know your way around BEX, of course; you should also know something about the other, "foreign" word processor whose files you're transferring. Additionally, you should understand the difference between binary files and textfiles, and be comfortable with Apple DOS commands.

The first step is discovering how the "foreign" word processor saves files on disk. No other word processor saves files as BEX chapters. (We discuss some common file types below under "Data file format.") BEX needs textfiles; which some programs do not create directly. Once you have a readable textfile, you do a trial transfer, using Read textfile to chapter on the Second menu.

The first time you work with a foreign word processor file, you must manually reformat some of the text. This gives you the lay of the land; you learn what transformation rules to write to change the text for better format. It also shows you what kind of \\ commands should be entered in the foreign word processor to minimize your work once it's a BEX chapter.

Having done it once you'll quickly see why manually reformatting text from other word processors is hardly any faster than doing the data entry with BEX in the first place. Fortunately, Replace characters is designed for exactly this task: it's worth your while to understand how it works. (Therefore, the following discussion assumes that you've read all of Section 8 of the User Level.)

Once you settle on a transformation chapter that reformats the files to your needs, you've established the routine. Given that you safeguard a copy of the transformation chapter, away from stray two-year-olds and belligerent magnets, you can rest assured that file transfers work smoothly from now on.

Data file format

Before you can transfer data from another, "foreign" word processor to BEX, you must know what kind of files it creates. Many word processors always save data as either DOS 3.3 or ProDOS textfiles. ProWORDS, Screen Writer II, Word Perfect 1.1, and Apple Writer II are just a few of the many programs like this. No extra effort is involved to transfer these files: insert the foreign word processor's data disk in your drive and BEX can Read textfiles from it.

Other word processors routinely save information in a "unique" file format that's only accessible to the creating program. BEX is a good example: BEX chapters are composed of binary page files and a binary directory file. (More details on BEX file structure are available in Learner Level, 12-7 through 12-12.) Another example is AppleWorks: its word processing files are saved as "AWP" type ProDOS binary files. To read BEX chapters, you must have BEX; to read an AWP file, you must have AppleWorks. (Three other well-known programs in this category are MouseWrite, The Write Choice, and Magic Slate.) Fortunately, these programs usually offer you the opportunity to save or print to disk as a textfile. The most common application for textfiles is preparing information to be telecommunicated--sent over telephone lines through a modem. Check under "telecommunications" in the foreign word processor's manual if you're having trouble locating the textfile-creating feature.

The battle of the <CR>s

For successful file transfers, you must learn how your foreign word processor uses <CR>s. No other program uses BEX's ( $p ) or ( $s ) indicators to mark new paragraphs. Some word processor programs mark the end of every line with a <CR>. This is especially true when the word processor's option for creating textfiles is designed to prepare information to be telecommunicated. If your program marks the end of every line with a <CR>, you must delete these <CR>s from your text.

Many other word processor programs use the <CR> to mark the end of a paragraph. For correct braille format, it's crucial to distinguish between a new paragraph, a new line that's meaningful (a new poetic line in verse, for example), and a new line that's only germane to the print copy. There are several ways to make this distinction clear.

The most direct is to enter ( $l ), ( $p ), and ( $s ), as appropriate, in your text in the foreign word processor. (This contradicts our suggestion in Section 6, Part 1 to use the <CR> in favor of the new-line ( $l ) indicator. In this case, the longer ( $l ) is much less ambiguous.) These indicators are ignored by other word processors. There are three steps to bringing these types of files into BEX. First, use Read textfile to chapter to make a BEX chapter. Next, use Replace characters and change every <CR> to one space. (When a program ends every line with <CR>, then that <CR> is the boundary between the last word on one line and the first word on the next. If you deleted the <CR>s, then some words would run together.) Finally, you Edit the chapter to add the \\ commands not in the foreign file. The foreign word processor user can enter <CR>s wherever they feel like it, so that the text does not appear as one humongous paragraph as they're entering data.

Learning about the ( $l ), ( $p ), and ( $s ) indicators may be a hurdle for some volunteers. Here's another approach: In your foreign word processor, enter a single <CR> for a new line, two <CR>s for a new paragraph, and three <CR>s for a skip-line indicator. To reformat this type of file, you first replace all occurrences of three <CR>s with ( $s ), then replace two <CR>s with ( $p ). You leave the <CR>s alone. But be warned! You may find a few seemingly random <CR>s in the transformed text. This isn't due to data entry errors: it's because most programs need one <CR> for every 255 characters they save to disk.

We can't provide you with hard and fast rules. Every word processor program is a little bit different; as is every word processor user. You must establish a system that's workable and comfortable for you (as data coordinator) and the data entry people (as foreign word processor users). The most important guideline we can give is: be consistently distinctive. You must set up a method that Replace characters can recognize. For example, if the foreign word processor user enters 2 <CR>s after each and every line of poetry, there's no way for Replace characters to know the difference between new poetic lines and new stanzas. In the AppleWorks example that follows, we show you a shortcut around a problem like this.

Part 6: AppleWorks Example

To give you an understanding of the issues involved, we've chosen to illustrate the file transfer with AppleWorks. AppleWorks is the best-selling Apple program of all time, so there's a good chance you'll be able to use this information directly. You can use this procedure at all BEX Levels, but you must have two disk drives. It took some trial and error to develop the process described here; it's important to keep in mind that, as with any data transfer, establishing the routine is the challenging and time-consuming part.

AppleWorks file storage options

AppleWorks allows you to store text on disk in three ways. Most often, it's stored in AppleWorks' unique binary file format. When you use AppleWorks to obtain a list of these files on disk, they are labeled "Word Processor", "Database", or "Spreadsheet". When you do a ProDOS CAT or CATALOG, the three-letter file types for these files are AWP, ADB, or ASP respectively. (These files are to AppleWorks as BEX chapters are to BEX.) BEX can't directly read any of these files. However, when you instruct AppleWorks to print by pressing Open-Apple-P, AppleWorks gives you an option "Save the File as A Textfile (ASCII) on Disk." Inside AppleWorks, these files are labeled "Other"; outside AppleWorks, the label is TXT.

When you save a textfile this way, AppleWorks doesn't try to format the information at all. The only <CR>s or spaces in the textfile are those that appear in the original AppleWorks file. Depending on how the data was entered, there are some number of <CR>s at the end of each paragraph. <CR>s do not appear at the end of each line. None of AppleWorks' print options (centering, underlining, page numbering, page headers or footers) appear either. (The third way of storing files is to define one of your printers as printing to disk. This procedure is better for a Database file, and is explored in the June 1986 RDC Newsletter.)

When you're consistent about paragraph format, it makes it easier to place ( $p ) paragraph indicators in the BEX chapter later with Replace characters. When the AppleWorks paragraphs always end with two <CR>s, then you can globally Replace every appearance of "<CR> <CR>was with "space dollar-sign lowercase p space". AppleWorks occasionally throws in a random <CR> in the middle of a paragraph. If the end of the AppleWorks paragraph is signalled by just one <CR>, then there's no way for Replace characters to distinguish genuine paragraph ends from these random <CR>s.

Doing it

Boot AppleWorks, and add the Word Processor file to the Desktop. Press Open-Apple-P to print, and then choose whether to print the entire document or a portion. Next, you're presented with the list of destinations. Choose the last option, "Save as a Textfile (ASCII) on disk."

Here comes the tricky part: in the lower left hand corner, AppleWorks prompts: Pathname? You must type in the complete ProDOS pathname: first a slash, then the volume name for the floppy disk where you write the file, then another slash, then the name of the textfile you're creating. (You give floppy disks volume names when you format them. At AppleWorks Main Menu, choose 5: "Other Activities." Number 5 here allows you to format a blank disk and assign it a volume name.)

For example, your floppy disk volume name is "stpoems." The Word Processor file is named "Sonnetble12." To minimize confusion, save the textfile with a similar yet different name: enter "/poems/sonnetXII". (To make life easier, always name ProDOS textfiles without spaces and without periods, thereby satisfying the naming rules for both ProDOS and BEX. It doesn't matter whether the names are upper- or lowercase, as BEX always interprets the file names as uppercase.)

This sounds simple enough, but the kind of error messages you can encounter when trying this procedure are not mentioned in the AppleWorks manual. This is what we've inferred: When you save a textfile on disk, AppleWorks does not automatically write to "the standard location for your data disk." Instead, the textfile is written to the ProDOS volume containing the AppleWorks program. (The data disk "standard location" appears in the upper left hand corner when you're at AppleWorks' Main Menu. If it's a floppy, it reads "Disk: Drive 1" or "Disk: Drive 2." If it's not a floppy, then it reads "Path: sthard1" or whatever.)

If you typed just a file name with no slash at the beginning, AppleWorks would try to write the "Sonnet12" textfile on the AppleWorks program disk. There's never enough room on the AppleWorks program disk, so you get the message: "Unable to continue writing this file."

On the other hand, if you typed "stsonnet12" then AppleWorks would look for the directory with that name. AppleWorks can't find that directory, so it says: "Unable to begin this file."

The moral is: always note the volume name of a floppy on the label! When you enter the complete ProDOS pathname, everything goes fine. It may take some time to save your file as a textfile: a sample 14K document required 75 seconds to save.

Now, pop the ProDOS disk in drive 2 and boot BEX. Go to BEX's Second menu and choose option R - Read textfile to chapter. BEX doesn't recognize the floppy's volume name; when you want to specify the textfile by name, enter: "SONNET12". It's easier to just enter "2 <CR>was and let BEX present you with a numbered list.

Since BEX can't write DOS 3.3 textfiles on a disk that's formatted for ProDOS, you must write the BEX chapters on drive 1, providing a different name. BEX reads the ProDOS textfiles into chapters. (And boy, is it fast! The same sample file took only 40 seconds for BEX to read into a chapter.)

Now you have BEX chapters which are ready to be reformatted. When the data entry in AppleWorks has been consistent, then the transformation task is easier. For the purposes of example, let's assume that the data entry in this case has not been consistent. The AppleWorks user entered 2 <CR>s after each and every line of poetry. There's no way for Replace characters to know the difference between new poetic lines and new stanzas.

You don't have to change everything manually, though. Here's a shortcut that involves just enough manual work to give Replace characters the information it needs. Edit the BEX chapter just created, the poem that's formatted with scores of double <CR>s. Copy a single unusual character, for example, the right brace, to the Clipboard. Print original in hand, move through the text on disk, Locating for the first few words of every stanza. As you hit on the beginning of each stanza, enter control-B I to insert the right brace after the 2 <CR>s and before the first letter of the stanza. When you're done, use Replace characters. Your first rule changes "<CR><CR>);" to "$s"; a subsequent rule changes "<CR><CR>" to "<CR>".

TranscriBEX Index