Section 9: Translating Print and Braille

At the User Level, you gain access to several more braille translation features. You can translate inkprint source chapters to grade 2 and grade 1 braille target chapters. You can also switch between grade 2 braille and no translation within a chapter. A new option is available on the Main Menu: option H - Heading test. It allows you to do almost instantaneous braille translation. It's a quick way to find out how BEX translates a particular word.

Also new at the User Level is option B - Back translate from Grade 2. You supply BEX with grade 2 braille source chapters, and BEX creates inkprint target chapters. You can create grade 2 source chapters on a braille-oriented device like the VersaBraille or Cranmer--see Sections 11 and 12 for information on how you transfer braille text to the Apple. You can also input grade 2 braille using BEX's braille keyboard mode in the Editor--details in Section 5, Part 7.

Whether you translate inkprint to grade 2 braille chapters, or whether you create braille chapters yourself, you must configure a braille device before you can emboss them. See Learner Level Section 8 for details.

Part 1: Option G - Grade 2 Translator

In Section 7 of the Learner Level, we described how to use option G - Grade 2 translator. You supply BEX with the names of source chapters. BEX creates correctly translated braille target chapters. We stressed the importance of consistently naming braille and print chapters so you can tell them apart. We suggested that you name your braille chapters by adding the digit 2 to the end of the print chapter name. In Section 4 of the User Level, we explain selective drive scanning. You can enter 1/2 <CR> or 2/2 <CR> at the Drive or chapter: prompt and get a list of all chapters that end with the digit 2. In this Part we detail how the translator handles some tricky translating situations. Part 3 discusses the translator controls that allow you to switch between grade 2, grade 1, and no translation within a chapter.

Embossing Braille Chapters

You must configure your braille embosser appropriately or you won't get correct format. Suppose you have a Cranmer Brailler in slot 2, but you configured it as a class G - Generic inkprint printer, with carriage width 40 and form length 25. Print a correctly translated grade 2 chapter to the Cranmer, and things look all wrong.

Because BEX thinks it's formatting text for a printer, BEX executes the underlining commands $$ub and $$h. For any underlined word, you see character, dots 4-5-6, character, dots 4-5-6, character, etc. BEX executes the $$np number pages format command by centering the word Page followed by Nemeth digits on line 25. There would be a blank line between paragraphs. Only when you accurately reconfigure the Cranmer as a class B - Braille embosser, brailler code 3, can you get the correct format.

And as mentioned in Section 6, when you define a New printer without reconfiguring, BEX always uses inkprint defaults. So if you attempted to send text to a brailler by answering N at the Which printer: prompt, you would get the same incorrect format.

Some basic hints for braille format are supplied in the Learner Level, Section 9. BEX's format commands are designed to make the transition easy. The page numbering command $$np and paragraph ( $p ) indicator are executed appropriately for print and braille format, depending on how the printer is defined in your configuration. When you send chapters to a device configured as a brailler, then BEX suppresses the execution of the $$ub and $$h underlining commands. The relative format commands l $$tinin or $$ting; automatically adjust for the differences in word length between print and braille.

One aspect of BEX's $$ commands can prove confusing to experienced transcribers. In all the reference works on braille format, the first cell on the line is called cell one. In terms of BEX's $$ commands, that same cell appears at position zero. In other words, the numbers in BEX's $$ commands are one less than the cell numbers transcribers are accustomed to.

A plug for TranscriBEX

You can do a variety of braille formats using BEX's $$ commands. However, some braille formats require extensive, involved strings of $$ commands. RDC has developed an add-on module for BEX named TranscriBEX. TranscriBEX fully supports the exacting braille translation and page formats mandated by English Braille--American Edition, the Code of Braille Textbook Formats and Techniques, and the Code for Computer Braille Notation. But you don't have to enter complex strings of $$ commands to create these complex page formats--TranscriBEX does it for you. When you are doing a lot of braille transcribing, TranscriBEX is the right tool for the job. TranscriBEX formats include general text, textbook format, line-numbered poetry and plays, and more. TranscriBEX also includes special symbols that let you switch between grade 1 and grade 2 translation in the middle of a word; control placement of braille boldface indicators and the braille letter sign; and a host of other subtle translation issues--contact us for further details.

Notes on Translation

BEX's Grade 2 translator is quite accurate. You can improve the accuracy through some manual intervention based on an understanding of how it works. When you find that the translator makes a systematic error, you can create a transformation chapter to fix it. Section 8 discusses transformation chapters in detail. RDC always appreciates written comments about how we can improve the accuracy of the translator.

Print underlining and braille italics

Braille italics are shown with the italics sign, dots 4-6 or the period in screen braille. The Grade 2 translator uses the presence of the format commands $$ub and $$uf to place the italics sign as appropriate. When three or less words are underlined, a single italics sign is placed before each word. When more than three words are underlined, a double italics sign (two dots 4-6, two periods in screen braille) is placed before the first underlined word and a single italics sign is placed before the last underlined word. For more details on the braille italics, see Learner Level Section 9.

Hyphens and dashes

In Master Level Section 5, we explain the discretionary linebreak. When BEX's formatter encounters the <ASCII 30> control character it's treated as an acceptable place to break the line, just like a <space>. As the Grade 2 translator translates inkprint, it places <ASCII 30> after a hyphen and both before and after two hyphens (a braille dash). The discretionary line break means more characters can fit on a line, especially useful with the relatively narrow 41-cell carriage width of most braillers. Please note that the Grade 2 translator cannot place discretionary hyphens, only discretionary linebreaks.

Accent sign

The braille accent sign is dot four, the at-sign in screen braille. When you want to show an accented letter in grade 2, precede that letter with at-sign @ in your inkprint chapter. For example, enter clich@e in inkprint when referring to a stale expression. The translator creates cli*@e in the grade 2 target chapter, where the asterisk stands for the two letters ch.

Less-than and greater-than symbols

These two symbols are used in various contexts. They can be symbols of enclosure, a function they serve in this manual. For example, the single linefeed control character is shown as <control-J>. In that context, < and > are sometimes called left and right angle brackets. At other times, these symbols are used mathematically to compare two values. BEX's Grade 2 translator always places a braille accent, dot 4, before these symbols, to distinguish them from the gh and ar contractions. < is translated to dot 4, dots 1-2-6 or @< in screen braille. > is translated to dot 4, dots 3-4-5, or @> in screen braille.

Backslash

The Grade 2 translator places a dot 4, or at-sign in screen braille, before a backslash. This distinguishes between a backslash in print and the ou sign.

Equals sign

The translator violates the rules for literary braille when translating the equals sign. The rules require the insertion of the word equals. Instead, the translator changes the inkprint = equals sign into the braille Nemeth Code equals sign: dots 4-6, dots 1-3, or .k in screen braille.

Percent

In inkprint, the percent sign % follows a number: 80% for example. The grade 2 braille rules require that the percent sign (dots 2-5, dots 1-2-3-4) immediately precede the number: 3p#hj is how 80 per cent should be translated. The translator has two ways of coping. When you place the percent sign before the digits in your inkprint, the grade 2 result follows the rules. Inkprint %80 becomes 3p#hj in grade 2. When the percent sign follows the digits in inkprint, then the grade 2 version use the properly contracted words per cent with a space before and after. Inkprint 80% becomes #hj p] c5t in grade 2.

Single quote marks and apostrophe

On most typewriter keyboards, and in the ASCII Code, opening single quote, closing single quote and apostrophe are the same symbol. However, in grade 2 braille, the opening quote, the closing single quote, and the apostrophe are three different symbols. The opening single quote is dot 6, dots 2-3-6 or ,8 in screen braille; the closing single quote is dots 3-5-6, dot 3, or 0' in screen braille; and the apostrophe is dot 3, or ' (apostrophe) in screen braille. The Grade 2 translator guesses which symbol to use depending on context, and it does a pretty good job. One situation requires manual intervention: when an apostrophe appears at the beginning of a word, usually in poetry or dialectical speech. The translator assumes that the apostrophe symbol at the beginning of a word should be translated as an opening single quote. You force this symbol to be translated as an apostrophe by preceding it with the greater-than sign. When your inkprint contains something like 'twas the night 'fore Christmas, enter
>'twas the night >'fore Christmas
The translator then creates
'twas ! ni<t '=e ,*ri/mas
instead of creating
,8twas ! ni<t ,8=e ,*ri/mas

Limitations of the Grade 2 Translator

Sometimes the rules for grade 2 braille require that you braille a word in more than one way, depending on the word's context or pronunciation. BEX's Grade 2 translator always chooses the more common usage. For example, the word do can be a verb of action, or it can be the first note of the musical scale. The translator assumes do is a verb; it becomes the single letter do. When you talk about the first note of the musical scale, however, the rules say spell it out in full, but the translator still contracts.

Foreign words, names, and made-up words are not always reliably translated. When you have questions about how a word translates, use option H - Heading test to get instant answers. When you have a lot of questions, enter the words in a separate BEX chapter. Translate that chapter and examine the results. Then write a transformation chapter to fix the errors with option R - Replace characters--details in Section 8.

For example, suppose you're writing a story about a law firm named Hallshurst and Granthorn. Those names are pronounced halls hurst and grant horn, so they should use neither the sh nor the th contractions. But the translator doesn't know any better, so it uses these contractions. You can create a transformation chapter like this, where the terminator is vertical bar:
|,hall%ur/|,hallshur/|,gran?orn|,granthorn||
and then use this transformation chapter on the final grade 2 braille chapters.

We know there will always be some idiosyncrasies in the translators. We are grateful for the written reports from users which have enabled us to continually upgrade the translators' performance.

Part 2: Braille to Print with the Back Translator

Option B - Back translate from grade 2 on the Main Menu is the opposite of option G - Grade 2 translator. Your source chapters are grade 2 braille, your target chapters are inkprint. Braille chapters can be typed in through the braille keyboard or imported from a remote braille device. As far as specifying chapters, both braille translation options are the same. However, the action of the back-translator is not a mirror image of the "forward" translator. While the Grade 2 translator can also create grade 1 braille, the Back from Grade 2 translator cannot back-translate grade 1 to inkprint. Part 3 explains how you can turn off back-translation within a chapter.

Grade 2 braille is a highly context-dependent code. The same character can have different meanings depending on where it appears in a word. When you carefully follow the rules for grade 2 braille, you get more accurate results with the Back from Grade 2 translator.

Back translate from grade 2 allows you to prepare material entirely in braille. When you enter BEX's format commands, use the ed sign (dots 1-2-4-6) for the dollar sign, and Nemeth numbers (dropped a through just) for any numbers. Parts of this manual were written in grade 2 braille on the VersaBraille, and then back translated to be merged with the rest of the text.

Prevent overflow

There is a crucial space consideration when back-translating. Grade 2 braille uses many one and two cell contractions to represent long inkprint words. An extreme example is this silly sentence: According to her, tomorrow's question is about knowledge. In print this is 57 characters (counting spaces): in grade 2 braille, its equivalent is 25 characters. Of course, that sentence uses a high proportion of contractions, but a full BEX page of grade 2 braille would probably overflow when it's expanded by translation back to inkprint.

The rule of thumb is, expect a 22 per cent increase. For grade 2 chapters that you intend to back-translate, keep your pages under 3200 characters. You can use option A - Adjust pages on the Second menu to create chapters that back-translate successfully.

If you did not follow this rule, you would get a spirited audio reminder. If there's too much text and BEX gets an overflow error, you hear the overflow shriek, which sounds like a spaceship taking off. Press <ESC> to cancel back-translation. In the unfortunate situation where you are using the same name for source and target chapters, and you have an overflow error after the first page is saved, you have data salad. You won't be able to recover the information in the original first page.

In addition to entering grade 2 through BEX's braille keyboard mode, there are two other ways to create grade 2 braille chapters. Braille text can be transferred from the tape-based VersaBraille with option F - From VersaBraille, or it can be imported from any serial braille device by option I - Input through slot. (Section 11 discusses Input through slot and the disk-based VersaBraille II.) Recognizing the need to prevent overflow, BEX tries to limit page size to under 3200 characters in these situations.

() VersaBraille: Take advantage of option A - Autoprint from VersaBraille on the Main Menu. This one option transfers a grade 2 file from the tape-based VersaBraille to the Apple, performs a back translation, and sends the result to an inkprint printer. See Section 11 for details. Raised Dot Computing also distributes a program called NUMBERS which back translates both literary braille and Nemeth mathematics braille.

Increasing Accuracy of Back-translation

As mentioned above, careful data entry on your part results in more accurate back-translation. The following suggestions are a general guide. Whenever your grade 2 text contains possibly ambiguous abbreviations or technical material with many symbols, it's a good idea to back-translate a sample and check it out in the Editor. Back-translation can create some pretty hilarious errors, which make perfect sense to braille readers but are quite opaque to those who only read print.

Avoid grade 2 slang

The back-translator simply cannot cope with grade 2 slang. For example, many experienced braille users write the word income as in sign, com sign, every, or 9-e in screen braille. The rules state that dots 3-6 only stands for com when it appears at the beginning of word. When dots 3-6 appears in the middle of a word, the back translator considers this a hyphen. When you enter 9-e it becomes in-every in inkprint, because the back-translator is faithfully following the grade 2 rules. Similarly, the back translator won't translate an en-sign directly before punctuation as the word enough. Experienced braille users often forget the grade 2 rule that forbids any dropped-letter word contraction before punctuation.

Use the letter sign

The letter sign (dots 5-6) distinguishes between an isolated letter and a grade 2 whole-word contraction. When you want an isolated letter in your inkprint, you must alert the back translator with the letter sign. This prevents back translating an isolated b into o but, an isolated c into o can, and so forth.

The Back from Grade 2 translator requires the letter sign in some contexts where good grade 2 does not. For example, in good grade 2 you do not use a letter sign before the E in E. Washington Avenue. But, you must use the letter sign for correct back-translation, or you get: E. Washington Avenue. Similarly, when you letter each element in an outline, you must precede the letter with the letter sign--even when you place punctuation after the letter. There's one exception: when you enclosed a single letter within parentheses, the back translator recognizes that you couldn't mean a single-cell contraction. So 7c7 back-translates to (c) and 7,e7 back-translates to (E) as they should.

The back translator just can't understand contextual clues as well as the human braille reader. When your text includes many isolated letters, write a test grade 2 chapter and back-translate it. Examine the inkprint results, and discover where you need to use the letter sign.

The slash character

The B - Back from Grade 2 translator does not exactly reverse the G - Grade 2 translator. The inkprint slash character is unchanged when translated to grade 2. The abbreviation I/O becomes ,i/,o when translated. However, the Back from Grade 2 translator always interprets the slash character (dots 3-4) as an st-sign. When you want to have a slash in inkprint, precede the slash with the letter sign, dots 5-6 or ; in screen braille. Enter ,i/,o in braille and you get IstO in inkprint; enter ,i;/,o in braille and you get I/O in inkprint.

Capitalization

Most braille embossers respond the same way to uppercase and lowercase letters. Send either an a or an A and you get dot 1. Some braille input devices allow you to choose between lowercase and uppercase data entry. (BEX's braille keyboard mode limits you to lowercase data entry.) As it processes grade 2 text, the Back from Grade 2 translator changes any uppercase letters to lowercase letters.

When you want uppercase letters in your inkprint chapter, use the caps sign in your grade 2 chapters. (Part 3 explains how you can use the no-translation translator control to exempt some text from back-translation.) The back-translator recognizes a mid-word change in capitalization signalled by the termination sign, dot 6, dot 3 or ,' in screen braille.

This second half of the 20th century seems to have brought with it an uncontrollable urge to coin new words, making the most remarkable assemblages of letters, numbers, and punctuation. In response, we've provided the back translator with some techniques to handle mid-word change of capitalization.

For example, dot 6, dots 1-3-5-6 generally stands for the suffix ation. Yet those two cells also appear in the word VersaNews. As a mark of respect to that fine publication, when the back-translator encounters ,v]sa,news it creates the right result. In fact, the back translator assumes that any double dot 6 in the middle of a word is signalling a change in capitalization. So when you braille 9,,l>ge & ,transcri,,bex in your chapter, the back translator creates inLARGE and TranscriBEX using the double dot 6 to create uppercase letters.

However, there are some patterns of punctuation that the translator can't cope with. When a grade 2 word ends with dots 3-4-6, or + in screen braille, the translator creates ing. You must make a conscious effort to get a word that ends with the plus sign in inkprint: you can either turn the translator off or use Replace characters.

Develop transformation chapters to help you

Section 8 discusses Replace characters in detail. Replace characters is the perfect companion to the back-translator. Create a grade 2 chapter containing all your ambiguous text, back-translate it, then edit it. You will quickly see where the back-translator has difficulty. It's usually easiest to fix problems after they have occurred, in the inkprint target chapters. Words like in-every or I/O in an inkprint chapter are unambiguously wrong. Part 3 discusses turning off the back-translator entirely within a document. When you know the back-translator would mangle some text, use this feature to ensure that your inkprint contains what you want.

Part 3: Controlling Translation within a Document

You can enter special symbols in your text that control how it's translated. Not surprisingly, these symbols are called translator controls, or TC'S for short. When using option G - Grade 2 translator, you can switch between four translation modes: grade 2, grade 1, grade 2 with "British style" capitalization, and no translation. When using option B - Back translate from grade 2 you can switch between two translation modes: grade 2 or no translation.

All TC'S are four keystrokes long; the first and fourth character are always spaces. Just like BEX's paragraph ( $p ) indicator, the leading and trailing spaces must be present for the TC to work; we enclose the full TC in parentheses to emphasize the leading and trailing space.

Disappearing translator controls

Residual translator controls

The third character in the TC stands for the translation mode you're choosing. Grade 2 is shown with the lowercase letter l for literary braille. Grade 1 is shown with the lowercase letter o for grade one braille. "British style" suppressing of caps sign is shown with the lowercase letter b for British. No translation is shown with the hyphen character; think of a minus sign.

The second character in the TC determines whether the TC appears in your target chapter. A switch in translation is usually obvious to the reader; you don't need an explicit symbol to alert the reader to a change in modes. In some rare instances, however, you do want an explicit symbol. For these two situations, BEX provides two types of TC'S: the disappearing TC uses the underbar as the second character; the residual TC uses the at-sign as the second character.

Ninety-nine percent of the time, you use the disappearing TC: the four characters change the translation mode and then become one space in the target chapter. For those rare occasions when you want evidence of a change in translation, use the residual TC'S. The residual TC can be useful as on or off strings in Contextual Replace, discussed in Master Level Section 6. Each constant TC changes the translation mode and remains in the target chapter.

Using Grade 1 TC with the Grade 2 Translator

The Grade 1 translator is built in to the Grade 2 translator. Grade 1 braille requires much more space than grade 2 braille, because grade 1 does not use any contractions. But grade 1 braille is not the same thing as untranslated braille: inkprint and grade 1 use different symbols for numbers and punctuation. Grade 1 uses the same composition signs as grade 2 to show capitalization and italics. Grade 1 is appropriate when you need to have a letter-for-letter representation of inkprint material. Grade 1 braille may be preferred for adults just learning braille, and is used to represent foreign languages.

() Caution! Option B - Back translate from grade 2 cannot back-translate grade 1 to inkprint.

Once the Grade 2 translator encounters the grade 1 TC it continues to do grade 1 translation until you explicitly tell it to return to grade 2 translation with the grade 2 TC.

Sample: Grade 1 and grade 2 TC'S

In most situations, you use the disappearing TC'S. When a word is intentionally misspelled, you should transcribe it in grade 1 instead of grade 2. Here's how you would place grade 1 and grade 2 TC'S in a hypothetical child's letter to Santa Claus:
Dear Santa: $p I am _o riting_lyou because my mother told me I _o shud. _l I have been a good girl this year and Mommy says you will bring me a _o Kemistry _l Set. I would love it! $p Regards, your friend Francie
When this chapter is processed through the Grade 2 translator, the result is:
,de> ,santa3 $p ,i am riting y 2c my "m told me ,i shud4 ,i h be5 a gd girl ? ye> & ,mommy says y w br+ me a ,kemistry ,set4 ,i wd love x6 $p ,reg>ds1 yr fr ,francie
Every four character disappearing TC has become one space. While in grade 1 translation mode, the translator still places italics signs when it encounters $$ub and $$uf.

Using no translation

When using either Grade 2 translator or Back translate from grade 2, you may wish to take control of translation yourself. You accomplish this with the no-translation translator control. The residual (-) TC still appears in your text once it's translated; the disappearing (-) TC becomes a single space in the translated text.

Once the translator encounters (-) or (-), it stops translating or back-translating until you explicitly return to grade 2 translation with the Grade 2 translator control.

No translation with option G - Grade 2 translator

When you are doing inkprint data entry, it's easiest to use the full Apple keyboard. When you want to include occasional Nemeth or other braille codes in your text, you can switch off translation and enter the braille directly. Once you do, you probably want to use BEX's braille keyboard mode. (This feature is not available on the Apple IIgs keyboard.) In the Editor, depress the Caps Lock key, and enter control-S K B. Now you can use the S-D-F J-K-L keys and the spacebar for braille data entry.

When you return to regular inkprint data entry, type the grade 2 TC, and then enter control-S control-K control-N to return to normal keyboard mode. Finally, release your Caps Lock key.

No translation with option B - Back translate from grade 2

Turning off the back-translator can be a handy way to enter tricky letter and number combinations. For example, you're writing some advertising copy for a new diet soda called Cherry77. Back-translation of ,*]ry#gg results in Cherryblegg which does not sound very appetizing. When you enter _-Cherry77_l in your grade 2 text, you turn off back-translation, so you get Cherry77 in your inkprint.

You cannot enter uppercase letters with BEX's braille keyboard mode; the braille keyboard always creates lowercase letters. When you are doing braille data entry in BEX, you must switch to full Apple keyboard to type _-Cherry77_l and then switch back to braille keyboard. (Alternatively, you can enter _-cherry77_l on the braille keyboard, then use Replace characters to change the initial c from lowercase to uppercase.

Most other braille devices allow you to distinguish between upper- and lowercase inkprint letters as you enter them. On the disk-based VersaBraille II, for example, you type an uppercase C by brailling chord-K dots 1-4.

Section 10: Textfiles

BEX stores information as chapters, a collection of binary files on disk. Many other programs store information as textfiles. In Section 12 of the Learner Level, we demonstrated option R - Read textfiles to BEX chapters on the Second Menu. Read textfile lets you import data from other Apple programs, both DOS 3.3 and ProDOS. At the User Level, there are three options on the Second Menu concerned with textfiles: option R - Read textfiles to chapters; option W - Write chapters into a textfile, and option T - Textfile kill.

Option W - Write chapters into a textfile is the opposite of option R - Read textfiles to chapters. Write chapters into a textfile lets you export BEX data to other DOS 3.3 Apple programs. RDC distributes a ProDOS utility called QTC that copies BEX chapter directly to ProDOS textfiles. When you want to export BEX data to ProDOS programs, use QTC.

Part 1: Background on Textfiles

BEX operates in the computer environment called Apple DOS 3.3. DOS 3.3 controls how information moves between the computer and the user, in particular, how characters are read from and written to disk. Within DOS 3.3, there are four ways of saving information on disk--four file types. Each type of file has its uses, and is identifiable by the letter in the second column of a DOS disk catalog.

The letter A identifies Applesoft BASIC programs. You can LOAD, RUN, SAVE, and LIST type A files. While you can include text in a BASIC program, it's not very efficient. On the Main side of BEX, an Applesoft program named SECOND contains the Second Menu. It includes text like There are # chapters on this disk.

Binary files store information for use by application programs: type B files can contain either programs or data, and your BEX disk contains samples of both. On the Boot side, for example, there's a type B file named FID, the File Developer utility. You can BLOAD, BRUN or BSAVE type B files, but you can't LIST them.

Also on the Boot side are these files:
B017MESSAGES.A
B015MESSAGES.B
B013MESSAGES.C
B003MESSAGES
which together make up the BEX chapter named MESSAGES. The MESSAGES chapter contains most of BEX's prompts, and at the Master Level, you learn how to modify it. More details about BEX chapter structure appear in Section 13 at both Learner and User Levels.

The third file type is T for textfiles, and that's what we concentrate on in this Section. The fourth file type is I for Integer BASIC, a slightly different dialect from Applesoft BASIC. BEX doesn't use it, so we'll leave it at that.

Textfiles vs. Binary files

You don't need a word processing program to use textfiles. In fact, all you need is Apple's DOS 3.3 or ProDOS. Commands to create, read and modify textfiles are built in to these operating systems. This has two consequences: almost any Apple program can handle textfiles, and, if a program is lacking this facility, a fairly inexperienced programmer can incorporate textfile-handling into the program.

But there are some disadvantages to storing data in textfiles with DOS 3.3, and that's why BEX stores data in binary files. One big minus is speed. Most textfile-related DOS 3.3 commands are very slow. BEX's Read textfile option is very fast, but only because it totally bypasses DOS 3.3. The other minus relates to a textfile's structure: it's basically one long string of characters. Imagine a textfile containing 8000 characters. If you decide to delete 200 characters somewhere in the middle, then you have to rewrite all of the characters after the deleted ones--and this process is doubly slow.

On the other hand, as you create BEX chapters, each BEX page is stored as one binary file. BEX adds extensions to your chapter name to make the binary filename. Every BEX chapter also has one three-sector binary file with the same name as the chapter name--that's the directory file that serves as the internal table of contents for the chapter. Since each BEX page is one file, it's easy to swap pages around. You only have to change the information in that chapter's directory file. If you were working with a textfile, you would have to rewrite all the data to disk.

Part 2: Working with Textfiles

All the chapter selection and naming features we've described in Section 4 also apply to selecting and naming textfiles. For example, when BEX presents the Textfile: prompt, you can type 1/Q <CR> to scan drive 1 for all the textfile names ending in the letter Q.

There's one difference between target naming methods for chapters and textfiles. Never use the same name for a textfile and a BEX chapter, even when the two files are on different disks. This means you can't use the S naming method. Follow the same rules for textfile names as for BEX chapters: the first character must be a letter; never use a period, comma, semicolon, or colon; and limit your textfile names to 25 characters. When your disks get cluttered with textfiles, use option T - Textfile kill to delete them.

Textfiles do not appear in the list of chapters supplied by option D - Disk catalog. In a DOS catalog, you identify textfiles by the letter T in the second column. The quickest way to locate textfiles on a disk is to scan the disk drive with either option R - Read textfiles to chapters or option T - Textfile kill.

Option R - Read textfiles to chapters can copy ProDOS textfiles to DOS 3.3 BEX chapters. However, BEX can neither catalog nor delete a file from a ProDOS disk. The only way to see a ProDOS textfile on disk is to scan the ProDOS disk with option R - Read textfiles.

Part 3: Using Option W - Write Chapters into a Textfile

After you press W at the Second Menu, you supply BEX with a list of one or more chapters to print to disk. When you finish the list of source chapters, BEX gives you the Target textfile: prompt. All your source chapters are combined and written to one DOS 3.3 textfile. You can specify source chapters from both drive 1 and 2, but you must make sure there's enough room on the disk for your target textfile. A textfile uses slightly fewer sectors than its BEX chapter counterpart.

Format Defaults for Write chapters into a textfile

BEX's formatter controls what characters appear in your textfile. Every time you press W at the Second Menu, the default format is $$f0 $$w0 by $$l0 $$s2 $$i5. These values are different from the defaults for printing to the screen, a printer, or a brailler; let's see what each means in detail:

At any point in your chapters, you can enter the reset to default format command $$d. This reestablishes these defaults: $$l0 $$s; $$i5. When you have established new values for carriage width or form length with $$w# or $$f#, the new values continue; $$d does not change them.

Part 4: Format Considerations

Here at RDC, we have experience transferring files between BEX and a few, but by no means all, other programs. The details of file transfer are the kind of topic covered in the RDC Newsletter. What follows is a spotty summary of a rich and complex field. When the target software has a feature like BEX's Replace characters, you can basically use any format you want. Some programs are less flexible, so you want to create just the right format with BEX.

Transfer to other word processors

Most word processors use <CR> to mark the end of a paragraph. The default value $$l" for linespacing suppresses soft <CR>s at the end of each line. The only <CR>s in the target textfile are created by ( $p ) or hard <CR>s you have typed in your source chapter.

Some word processors have filtering features that, though not quite as sophisticated as Replace characters, can automatically get rid of <CR>s at the end of each line. AppleWorks does this automatically. In the Macintosh environment, MacWrite, Microsoft Word, and JustText ask you a question like Do you want every <CR> interpreted as a new paragraph? or Does your source textfile use <CR>s to mark the end of every line? When you use the default $$l" value for line spacing, you would answer Y to the first question and N to the second.

Most ProDOS programs can't directly read DOS 3.3 textfiles. Programs like AppleWorks and ProWORDS can read ProDOS textfiles. RDC'S QTC utility can copy either a BEX chapter or a DOS 3.3 textfile to a ProDOS textfile. AppleWorks won't know what to do with BEX's $$ format commands. You can globally delete them from your BEX chapter, then use QTC to copy the chapter to a textfile. Or you can use Write chapters to textfile to print the data to disk, then use QTC to copy the formatted DOS 3.3 textfile to a ProDOS textfile.

Proofreading with textfiles

You can use textfiles to proofread exactly how your output appears. This can be particularly handy when you're creating forms and other line-oriented material. At the start of your chapter, establish the form length, carriage width, etc. as it should appear in the final output. It's important to establish the form length first, and then the carriage width. If you want to see any page-oriented commands, your form length must be 4 or greater. Write your chapters to a textfile, then Read the textfile back to a chapter. Review this chapter to see exactly where all the <CR>s and spaces appear in your final output. A new page is shown by the <control-L> character in your text.

Textfiles for telecommunications

When you send plain text over the phone with a terminal program, you do want a <CR> every 70 to 80 characters. You can create this format when writing chapters to textfile by inserting $$l, (lowercase l, digit one) at the start of your chapter.

Textfiles for programming

When writing Applesoft BASIC programs you definitely don't want BEX to automatically generate <CR>s every 80 characters, since the <CR> signals the end of a BASIC statement. Enter $$w240 $$l1 $$s1 $$i0 at the start of your chapter. The formatter then executes ( $p ) indicators just like <CR>s. You also may wish to use $$su to create all uppercase output.

Textfiles with NO format

Sometimes you don't want any format commands executed in your textfile. A good example is when you're using a DOS 3.3 spell-checker program. (When you want to use a ProDOS spell-checker, then it's quicker to use QTC.) You write a textfile and then let the spell-checker make changes in that. Then you read the improved textfile back to a BEX chapter. Insert $$z at the start of your chapter. The $$z command turns off the formatter entirely, so the textfile contains exactly the same characters as those in your BEX page. All BEX's format commands become lifeless dollar signs, letters and numbers in your textfile, while hard <CR>s you've typed in your text still appear in your textfile.

Things That Can Go Wrong

Because textfiles store information in a fairly standard pattern, you can use textfiles as a trade language for moving data between programs. We've tried to make BEX write very correct textfiles, but sometimes another application program may rebel at reading them. Often, this rebellion is traceable to weaknesses in the other software's read textfile features. In particular, some programs need textfiles with frequent <CR>s--at least one <CR> every 250 characters. BEX's default values for writing textfiles only place <CR>s at paragraph ( $p ) indicators, but it's easy to change that default by using the $$l, command. Some terminal programs won't let you transmit many control characters, so control characters that are really there in the textfile BEX wrote seem to disappear.

Part 5: Option R - Read Textfiles to Chapters

This option copies the information in both DOS 3.3 and ProDOS textfiles into a BEX chapter. You can use this option to Read more than one textfile to the same number of BEX chapters. To name the BEX chapters you create, you can use all of BEX's target chapter naming methods except S.

() Caution! ProDOS allows you to establish subdirectories on any storage medium. Generally you use this feature to organize the large amount of storage on a hard disk. However, you can create a subdirectory on a ProDOS floppy disk. When you write a ProDOS textfile in a subdirectory, BEX can't find it. BEX can only read ProDOS textfiles at the root level directory. For example, /LETTERS is the ProDOS volume name. When you create a /LETTERS/SANDY textfile, BEX can find it and copy it. But if you create a /LETTERS/APRIL/ subdirectory, and write the SANDY textfile there, BEX won't be able to find it.

Textfiles can be formatted in two fashions. When a word processing program always saves data as textfiles, then the textfile probably contains format commands and data. The format commands may be plain text, like BEX's $$ commands. For example, ProWORDS and AppleWriter use "dot" commands. It's also possible that the format commands are control characters.

Other programs use a unique format to save data--AppleWorks is the prime example. AppleWorks and other software like this creates textfiles by printing to disk. (In the next Part, we show you exactly how to do this.) In this situation, when you edit the new chapters, they contain no BEX format commands. There's just plain text, <CR>s, and spaces. As we demonstrated at the Learner Level, use option R - Replace characters with the BEXtras disk transformation chapter FIX TEXT to change the spaces and <CR>s to BEX format commands.

When a textfile contains underlining, it can be messy. When underlining the word dog, many word processors (including BEX), create:
d<control-H>_ o<control-H>_ g<control-H>_
FIX TEXT'S transformation rules change this tangle of <control-H> and underbars to BEX'sAND underlining commands.

After the transformation, there is only one space at the end of each sentence in the target chapters. When you want two spaces at the end of sentences, use Replace characters with the SP2 transformation chapter, also on your BEXtras disk.

At the User Level, you are limited to 5.25-inch disk drives. This means you can only read DOS 3.3 and ProDOS textfiles on 5.25-inch floppy disks. At the Master Level, you can read textfiles from 3.5-inch disks (both DOS 3.3 and ProDOS), as well as DOS 3.3 textfiles on the Sider hard disk and on RAM drives. Also at the Master Level, we explain how FIX TEXT and SP2 work.

Importing data from ED-IT

The ED-IT software is a line-oriented braille word processor. It saves data as all uppercase DOS 3.3 textfiles. When you do data entry in ED-IT, all your formatting is manual; you press <CR> at the end of each line. You can copy this information to a BEX chapter with option R - Read textfile.

However, don't use FIX TEXT to reformat data from ED-IT; FIX TEXT assumes that paragraphs are marked by a blank line. In braille, a standard paragraph is shown with one <CR> and two spaces. So you can replace <CR><space><space> with ( $p ). But, there's an additional complication. Transcribers doing ED-IT data entry probably create other paragraph formats, for example an outdented list with indent to cell 1, runover to cell 3. In this case, you must reformat information manually.

Part 6: Creating ProDOS Textfiles in AppleWorks

The following information focuses on AppleWorks' Word Processor. The June 1986 RDC Newsletter details exporting textfiles from AppleWorks' Database. Back issues are available--contact RDC for details.

AppleWorks, like BEX, saves information in a unique binary file format. BEX cannot read AppleWorks files directly. The general procedure for exporting information from AppleWorks to BEX requires four steps.

AppleWorks has gone through four versions. At this writing, it's at Version 2.0. The big difference between AppleWorks 2.0 and all earlier versions is where <CR>s appear in the ProDOS textfile. For AppleWorks 1.1, 1.2, and 1.3, the only <CR>s in the textfile are those in the Word Processor file--usually, only at the end of every paragraph. But AppleWorks 2.0 places at least one <CR> at the end of every line when you create the textfile.

When you do data entry with AppleWorks 2.0, you must take special care. While regular print output contains between 70 and 80 characters per line, braille is usually limited to 41 cells. When you bring rigidly line-oriented data from a print to a braille environment, the resulting braille is not properly formatted.

It's crucial to differentiate between a new paragraph, a meaningful new line (like a new poetic line in verse), and a new line that's only pertinent in the print copy. Because AppleWorks 2.0 places a <CR> at the end of every line, the AppleWorks data entry must clearly distinguish between <CR>s that matter and those that don't.

After you Read the ProDOS textfile to a BEX chapter, Replace characters must be able to find patterns of <CR>s from the AppleWorks file and change these to the appropriate ( $p ) and ( $l ) indicators.

Tailoring AppleWorks Data Entry for BEX

First, we discuss two strategies for distinctive data entry. At the end, we summarize the step by step procedure.

Tabs and blank lines

When you open a new Word Processor document, it has preset tab stops every five characters. The first strategy for distinctive data entry builds on a habit that's well-developed in most typists; this works best for straight textual material. At the start of each paragraph, you type two <CR>s and then press the Tab key. By adding a blank line before each paragraph and indenting five spaces at its start, you create the kind of distinctive pattern that Replace characters can easily find.

By the way, AppleWorks doesn't have "real" tabs: when you press the Tab key, AppleWorks simply inserts enough spaces to move to the next tab stop. Because of this, you can't insert tabs after you've typed your text, only as you go.

For a meaningful new line, enter two <CR>s but don't press Tab; the line begins at the margin. Once you make a ProDOS textfile and Read this to a BEX chapter, you want to use Replace characters. Here's what the dialogue looks like the first time you do this.
Replace characters
Drive or chapter: 2 <CR>
There are 3 chapters:
1QUIZ
2TAKEHOME
3FINAL
Use entire list? Y <CR>
Target chapter naming method: S <CR>
Use transformation chapter: <CR>
Enter terminator: |
Find: <CR><CR><space><space><space><space>&l t;space>|
Change to: <space>$p<space>|
Find: <CR><CR>|
Change to: <space>$l<space>|
Find: <CR>|
Change to: <space>|
Find: <space><space>|
Change to: <space>|
Find: |
Continue? Y <CR>
Starting to replace ...
Replaced (big number) times
Save transformation chapter: 1AWTRANS <CR>

In this sample, the target chapter naming method is S, which means that the transformed chapters overwrite the source chapters. You only have to go through this dialogue once, because you save the AWTRANS transformation chapter on your BEX disk. Next time you bring data from AppleWorks, enter 1AWTRANS <CR> at the Transformation chapter name: prompt. BEX reads the transformation rules into memory, then prompts, Continue? Y Press <CR>, then sit back and listen to a symphony of clicks.

Use unambiguous indicators

The other strategy for distinctive data entry is a universal solution for BEX data entry in any "foreign" word processor--AppleWorks, PC Write, WordPerfect, or what have you. An essential quality of BEX is that every format indicator can be entered with plain printing characters; BEX's formatter does not require you to use any control characters at all. Instead of using patterns of <CR>s and tabs, enter <space>, dollar sign, lowercase people, <space> to mark the beginning of every paragraph. To unambiguously define the start of a meaningful new line, enter <space>, dollar sign, lowercase like, <space>. The BEX ( $p ) and ( $l ) format indicators are treated just like text in a foreign word processor.

This method, although it requires a little more training for the person doing data entry, is guaranteed to work. As long as they faithfully enter paragraph and new-line indicators where appropriate, they can place <CR>s wherever they feel like it. Once you bring this data into BEX, the Replace characters task is very simple: Replace every <CR> with one space.

Step-by-step Summary: Exporting ProDOS Textfiles from AppleWorks

Whether you use <CR> plus space patterns or enter unambiguous indicators, the export procedure is basically the same. The only difference lies in which transformation chapter you use as the last step. Here's what you do.

Section 11: BEX and the VersaBrailles

Telesensory Systems Inc. has marketed two very different devices. The first device was the tape-based VersaBraille. TSI now refers to this machine as the classic VersaBraille. Beginning in 1986, TSI started selling the disk-based VersaBraille II, and in 1987, the disk-based VersaBraille II Plus. From here on in, we use a shorthand: VB for the tape-based VersaBraille, and VB II for the disk-based VersaBraille II and II Plus. Before you attempt to use either VB with BEX, please read the appropriate section in the BEX Interface Guide: Section 8 for the classic VB, and Section 9 for the disk-based VB II.

Part 1: Are You Ready?

This Section assumes that you understand the differences between the two machines and know which one you have. Having read the Interface Guide, you know how to interface your machine to the Apple. For the tape-based VB, you have set up the appropriate overlay chapters. For either VB, you have connected and tested communication between the Apple and the VB or VB II.

Additionally, you must supply appropriate answers in your configuration. For the tape-based VB, you must supply your model letter and slot number when asked. For the disk-based VB II, you must answer Y to Do you have a remote serial device to input text through slot? and define one of your printers as a class P - Paperless brailler.

Back in 1981, the first device supported by BRAILLE-EDIT (the precursor of BEX) was the classic VersaBraille. Thanks to this heritage, many BEX features facilitate transferring information between the Apple and the VB or VB II. BEX and the VB'S use the same symbol to mark a paragraph: ed sign, people. Dots 1-2-4-6, dots 1-2-3-4 is dollar sign p in computer braille--the same as BEX's paragraph ( $p ) indicator.

Like BEX, the tape-based VB stores data in units called chapters, which consist of some number of pages. But the VB page is much smaller than a BEX page: a totally full VB page is 1000 characters compared with 4096 for a BEX page. When BEX transfers information to and from the VB, it automatically preserves the VB page breaks. You can also control this manually--more details in Part 3. The disk-based VB II does not use a chapter and page structure, but it does use ( $p ) to mark paragraphs.

Part 2: Three BEX Options for the Tape-Based VB

When you transfer information from the VB to the Apple, you use option F - From VB. When you move information in the opposite direction, you use option T - To VB. Option A - Auto print from VB combines three Main Menu options. It transfers text from the VB to the Apple, then back-translates it, then prints the resulting inkprint chapter to the printer you've defined as number 1 in your configuration.

Using Option F - From VB

Cable the VB to the Apple. Turn on the Apple, then turn on the VB. On the VB, load the FROM VB overlay, and press chord-R R to put the VB in remote. Make sure you have enough room on the data disk in drive 2. To start the transfer, press F at the Main Menu. BEX asks you two questions with supplied defaults.
Main Menu: F
From VB
Do you want control characters? N

When you are transferring a grade 2 chapter, press <CR> to accept the N default. Part 3 discusses when you would answer Y. After you answer the first question, BEX continues:
Do you want VB page indicators? N
Most of the time, you want to press <CR> to accept the N default. Once you answer these questions, BEX prompts: enter chord X H at VB chapter name and then BEX waits for around two minutes.

Now pay attention to the VB. After you load the FROM VB overlay, eject it and load the tape containing the chapter you want to send to the Apple. Find the chapter title in the table of contents, and stay there--do not press the advance bar to enter the chapter. Press chord-X H on the VB and the rest is automatic. You hear the VB tape moving the moment you press the H. When the transfer is finished, the BEX chapters are on disk with the same names as the VB chapters.

Using Option T - To VB

Cable the VB to the Apple. Turn on the power for both devices. On the VB, load the TO VB overlay. When it is loaded, press chord-R R to put the VB in remote. Eject the tape, and load a tape with enough room to contain the text you're sending.

On BEX's Main Menu, press T. Specify a list of chapters to transfer (details on BEX chapter selection appear in Section 4). Once the list is complete, BEX asks two questions and supplies defaults.
Main Menu: T
To VB
Drive or chapter: 2 <CR>
There are 3 chapters
1SAMPLE1
2SAMPLE2
3SAMPLE3
Use entire list? N Y <CR>
Have you defined all VB page breaks? N
Unless you are positive no VB page would end up with more than 1000 characters, press <CR> to accept this default. BEX continues:
Maximum VB page size is: 950
Enter new page size:
Use this default value for material you'll be reading; simply press <CR>. When you intend to do extensive editing, supply a lower number in the range of 500 to 700.

Once you answer the page size question, BEX starts sending material to the VB. When the transfer is finished, the VB is in local. Before doing another transfer, you need to press chord-R R again.

Using Option A - Auto print from VB

Auto print from VB combines three Main Menu options: From VB, Back translate from Grade 2, and Print chapters. This one option transfers your grade 2 chapter from the VB to the Apple, runs the Back from Grade 2 translator, and prints the translated text to printer number 1.

() Caution! You must have at least two disk drives to use option A - Auto print from VB.

Before you use this option, you must specify your inkprint printer as printer 1 in your configuration; set top of form and make sure it's on-line. Set up the VB as described above for option F - From VB. Make sure you have enough room on the data disk in drive 2. On the Apple, press A at the Main Menu. BEX uses the N defaults for control characters and page breaks; the only prompt you get is Enter chord-X H to send chapters

Enter the chord-X H command on the VB, and the rest is automatic. Isn't technology fun? The Auto print option creates a BEX chapter named XXX containing the back-translated text.

Part 3: Finer Control of VB Transfers

In Part 2, we recommended you use the default values for the questions BEX asks for option T - To VB and option F - From VB. Here we explore the cases when you may wish to use different values.

VB and BEX chapter naming

When a VB chapter is transferred to the Apple, BEX tries to use the same chapter name as the VB'S chapter name. When the VB chapter is named DIARY then the BEX chapter is also named DIARY. However, it's possible for a VB chapter to begin with a character that's not a letter. When this happens BEX inserts ] right bracket at the beginning of the BEX chapter name. This becomes part of the name, which you must type when specifying BEX chapters individually. When the VB chapter is named -PUT] then BEX names it ]-PUT] once it arrives in the Apple. When this chapter is transferred back to the VB, the ] is stripped off.

VB page breaks

For option F - From VB, BEX asks you Do you want VB page indicators? and supplies a N default. When you answer Y, then <control-P> appears in your BEX chapter wherever there's a new VB page. When transferring back to the VB, a <control-P> within your text forces a new VB page. You can enter <control-P> characters in BEX text that you create for the VB to make better VB format. When you need to reserve ten blank VB pages in a row, just type ten <control-P> characters in your BEX page.

When transferring to the VB, BEX asks Have you defined all VB page breaks? with a N default. When you are positive that your BEX text contains 1000 or less character between each <control-P> character, then you can answer Y. This way, you can transfer the same text back to the VB with the same page boundaries.

() Warning! Only answer Y if you have been very careful about your <control-P> characters. A VB page cannot contain more than 1000 characters. If there are more than 1000 characters between <control-P>s, then some text is overwritten in the VB.

In most situations, let the computer keep track of VB page breaks. During option T - To VB, BEX asks
Maximum VB page size is: 950
Enter new page size:
When you enter a lower value, BEX creates VB pages within the limits you provide, making a smaller page when a new paragraph starts within 100 characters of the page size. BEX tries to divide at the end of a line or a word. If there is a very long word at the end of the page, however, BEX would divide that word. During the transfer, a <control-P> still forces a VB page break.

Control characters

For option F - From VB, BEX asks Do you want control characters? and supplies a N default. Depending on your VB model, some common grade 2 contractions are identical to ASCII control characters. When you choose to answer Y, you do want control characters, make sure that your text does not contain ambiguities. For example, dots 4-5-6, dots 1-3-4 could mean either many or <CR> on a model B VB. For a model C, dot 4, dots 1-5 could mean an accented letter or <control-E>.

When using option T - To VB, BEX strips out four control characters that could appear in your text: <control-S>, <control-T>, <ASCII 30>, and <ASCII 31>. The Grade 2 translator places <ASCII 30>, the discretionary linebreak, as it translates. The other control characters would be there because you typed them in.

Part 4: Two BEX Options for the Disk-based VersaBraille II

Please be aware that the tape-based, classic VB and the disk-based VB II are very different machines. You can't use the three options described in Part 2 to move text between the Apple and the disk-based VB II. However, two options make transferring data between them quite straightforward. Section 9 in the BEX Interface Guide describes getting the two machines communicating.

Input through slot: from the VB II to the Apple

On the Second Menu, option I - Input through slot allows you to import data from another computer cabled to the Apple. Complete instructions on Input through slot appear in Section 12. To use Input through slot, you must provide BEX with the slot number of the interface card in your configuration. Check Section 9 in the BEX Interface Guide for what cable to use and how to set the CCP'S on the VersaBraille II.

Once you're ready, press I at the Second Menu. BEX requests a target chapter name. After you supply it, BEX tells you to start sending text from your remote device.

Now pay attention to the VB II. To send text to the Apple, enter F for files, P for print, and S for serial. You're asked if you want to format text. Answer Y when you want the VersaBraille to format text. Answer N when you want BEX to format text.

Next, answer the VersaBraille questions about the device (internal, drive 1 or drive 2), and the file name appropriately. Finally, you're asked if you want to pause; answer N. The file is now moving to the Apple; you hear a steady series of clicks. When the transmission is over, press Q on the Apple keyboard; your chapter is saved to disk.

When the VersaBraille is formatting text, you can reduce blank lines and spaces by entering the appropriate format commands in your VB II file. The commands .pk to pack text and .op to omit page numbers, as well as the commands that zero the margins, should prove useful.

Printing: from the Apple to the VB II

To send a file to the VB II, you must define one of the four printers in your configuration as a class P - Paperless brailler. This turns off BEX's formatter, so that your entire text is transferred as is, format commands intact. The class P - Paperless brailler also strips out four control characters that could appear in your text: <control-S>, <control-T>, <ASCII 30>, and <ASCII 31>. The Grade 2 translator places <ASCII 30>, the discretionary linebreak, as it translates. The other control characters would be there because you typed them in.

Before you can specify a list of chapters to print, you must tell the VB II to expect some text. When the VB II is receiving text, you can set VersaBraille emulation either on or off. We recommend turning VersaBraille emulation off.

To tell the VB to accept a file, enter F for files, P for print, and I for serial in. You are asked for the file name and device (internal, drive 1, or drive 2); supply the appropriate answers. Finally, you are asked Send commands? Answer N by pressing any key except execute. Now specify a list of chapters to print, and direct it to the printer number you defined as a class P printer. When the transmission is over, press chord-Z on the VB II keyboard.

When the file is less than 10,000 characters and you want to examine the text as it's being absorbed, you can turn VersaBraille emulation on, by using the communications submenu of the parameters menu. When VersaBraille emulation is on, the procedure is slightly different. Once you specify F, P, and I, commence printing with BEX. Once BEX is back at the Main Menu prompt, press chord-R on the VB II keyboard. Once it arrives in the VB II, the file VERSABRL.SAV contains the text from the Apple. You should immediately rename the file, or it would get clobbered the next time you transfer a file.

Section 12: Importing Text with Input through Slot

There are several ways to get text into BEX. The most common way is to enter text in the Editor, either in print or in braille. A second way is to copy the information from a DOS 3.3 or ProDOS textfile into a BEX chapter. Option R - Read textfiles to chapters is on the Second Menu; it's explained in detail in Section 10.

Section 11 discusses transferring files between the tape-based VersaBraille and BEX. Section 11 also discusses the disk-based VersaBraille: you use option I - Input through slot to send text from the VersaBraille II to the Apple.

Part 1: How Input through Slot Works

Option I - Input through slot on the Second Menu allows you to import information from a remote serial computer device. You establish communication between the remote device and the Apple, and then provide BEX with a new chapter name. From this point on, BEX accepts the information through the interface card in a slot instead of through the Apple keyboard.

BEX pages are limited to 4096 characters, so BEX must be able to send a message to the remote device to pause occasionally. While the device pauses, BEX writes the current page to disk and opens a new page. Finally, BEX must be able to tell the remote device to start sending again. This kind of dialogue between computers is called handshaking in the interfacing subculture.

To capture the data, BEX uses option I - Input through slot. How the remote computer sends the data can vary from device to device. We have successfully interfaced a wide variety of devices, including the Kurzweil Reading Machine, the IBM-PC, the Macintosh, and the Keynote and SmallTalk notebook computers.

() Hint! The KRM Interface is tricky. Please check out Section 10 in the Interface Guide.

Part 2: Equipment Requirements

There are two basic requirements for the remote device: It must support handshaking and it must be controllable externally. Input through slot supports two handshaking methods or protocols: software handshaking and hardware handshaking.

Handshaking issues

Software handshaking is known by several other names: Xon/Xoff, control-S control-Q, and flow control are all terms you may encounter. Software handshaking is universally provided by a terminal or communications program. This means that one way to send text to the Apple is to run a terminal program on the remote device. Software handshaking is also one way a computer can communicate with a serial printer. You may be able to define the Apple using BEX as a printer. Then you can use a word processing program on the remote device to send the data to BEX.

Hardware handshaking is sometimes called Data Terminal Ready or simply DTR handshaking. Hardware handshaking is the most common way that a computer communicates with a serial printer. Chances are very good that you can tell your remote device to print and capture the data with BEX using Input through slot. Sometimes this requires a word processing program. No other software is required for the MS-DOS and PC-DOS operating systems, as printing is built in to the DOS.

Controlling communications on remote device

During Input through slot, BEX is concentrating on ingesting information, so you can't use the Apple keyboard to tell your remote device anything. This means that you must be able to control the device externally through its keyboard or other buttons.

If you cannot push buttons on the remote device to specify which file to send and when to start sending it, then Input through slot won't work. (That's one of the things you can do with a true terminal program. Terminal software lets you run another computer remotely.)

Apple interface cards

Input through slot is very picky. You can only establish communications with three interfaces: an Apple Super Serial Card, an Apple IIc port, or the modem port on a SlotBuster II. You can't use an Apple IIgs port for Input through slot.

Getting the Right Connections

When you get two computers to talk to each other successfully, you've interfaced them. Establishing a serial interface requires some patience and experimentation. Once you have interfaced two devices, however, actually sending data is a snap.

The first issue is getting the correct cable. RDC sells a wide variety of cables that work with different interfaces; see Section 14 in the Interface Guide for details.

Once you have the correct cable, you must match the values for four parameters on the sending device and the Apple. RDC'S standard parameters for the Super Serial Card, IIc ports, and SlotBuster modem port are:

The simplest interface is when you can set these same parameters on your remote device. If you insist on using other parameters, Section 6 of the Interface Guide tells you how to change these values for the Super Serial Card and IIc.

Part 3: Using Input through slot

When you establish a configuration at the User Level, BEX asks Do you have a remote serial device to input text through slot? When you answer Y, you specify the interface card and an optional set-up sequence. Before you can use Input through slot, you must establish a configuration where you answer Y to this question. Next, you must test the connection to make sure that data is transferring correctly--Part 4 offers some advice. Once the Apple and your remote device are on speaking terms, using Input through slot is simple.

On the Second Menu, press I and BEX asks for a target chapter name. Once you provide this, BEX tells you to start sending data. You then move to your remote device and type the commands or push the buttons that initiate sending text.

BEX clicks once for every character as it enters the BEX page. When the remote device sends characters in a steady stream, you hear a steady tone. When the remote device thinks it's printing, then you hear bursts of clicks for each line. Your baud rate determines the pitch: 2400 baud is a low moan; 19,200 baud is a high shriek.

BEX page size

A BEX page can contain from zero to 4096 characters. When you are back-translating grade 2 text, it's important to limit your pages to around 3200 characters. You can fill your pages more when you're not translating the data. Knowing this, BEX uses two different limits when creating pages during Input through slot.

When the first sector of data is all lowercase or all uppercase, BEX limits the pages to about 3072 characters. BEX assumes this data is braille text, and the 3072 limit minimizes overflow errors when back-translating. When the first sector of data is a mixture of upper- and lowercase, then BEX uses a higher limit for pages; BEX moves to a new page at about 3840 characters. If neither limit suits your preferences, you can modify the chapter when the session's over. Once the target chapter is saved to disk, you can use option A - Adjust pages on the Second Menu to establish page boundaries you prefer.

When the first BEX page is full, BEX tells the remote device to pause. The program tries software handshakes first. If the remote device doesn't respond, then BEX sends a hardware handshake signal.

Controlling Input through slot

During the Input through slot process, you can press three letters on the Apple keyboard:

Part 4: Tips and Techniques

When you first work out the interface between two devices, allow yourself enough time. A successful serial interface requires matching a number of parameters on both sending and receiving devices. It's easy to become flustered; when you do, it's unlikely you'll get all the parameters to match.

When you start changing the serial parameters, it's crucial that you keep track of what you're doing. Never change more than one parameter at a time, or you won't know what the correct combination is.

Step-by-step interfacing instructions for Input through slot are frequently published in the RDC Newsletter. Call us to see if you can purchase a back issue that has the details on a specific interface. In addition, keep Section 6 of the Interface Guide close at hand, as it lists the command sequences for the Super Serial Card and IIc ports.

Testing different parameters without reconfiguring

When you're experimenting with different interface parameters, you don't want to turn off your Apple just to change switch settings on the Super Serial Card. As an alternative to flipping switches, you can write a BEX chapter containing the command sequences to change any parameter. Suppose your Input through slot Super Serial Card is in slot 2. You want to lower the baud rate from the "standard" 9600 to 4800. Edit a new BEX chapter and press control-C I then type 12 B <CR> and control-Q to quit. This chapter contains <control-I> 12 B <CR> which sets the SSC to 4800 baud. When you print this chapter to the SSC, then you change its parameters.

Chances are that you have not configured any of your printers in slot 2. But you can still print the chapter, by defining it as a N printer:
Main Menu: P
Print
Drive or chapter: BAUD <CR>
Drive or chapter: <CR>
Which printer: N <CR>
Old carriage width: 80
New width: <CR>
Old form length 23
New form length: <CR>
Printer slot is 0
Enter new slot: 2 <CR>
No pause on form feed
Change it? N <CR>
The important question is the slot number; respond with the interface card for Input through slot. Your answers for the carriage width, form length, and pause on form feed questions don't matter.

Troubleshooting

Before you start interfacing the two devices, create some test data on both devices, if you can. The data should follow a recognizable pattern so that you instantly know when characters are missing. The data should include long and short words and long and short lines. Your test data must be large enough to assess whether handshaking is working correctly.

12,000 characters is a good number; BEX must handshake with the remote device for three BEX pages. An ideal test file would be the numbers from 0 to 9 repeated again and again, with different clusters of digits simulating the distribution of letters in words and sentences.

Missing characters

Symptoms of inadequate handshaking usually pop up at BEX page breaks. When the last character of one BEX page and the first character of the next are not sequential in the source data, then you know that BEX is not able to tell the remote device to pause. Some characters are being lost as BEX saves the current page and opens a new page. As mentioned earlier, BEX tries software handshaking first, and then uses hardware handshaking. If your remote device is unusually sluggish to acknowledge software handshaking, BEX may use hardware handshaking instead. The result is no handshaking. RDC may be able to offer advice on how to cope--call the Technical Hotline for assistance.

Garbage characters

When the data you receive is totally gar4, then the first suspect is baud rate. Check to see that both devices are set at the same rate. The next suspect is stop bits: you get garbage characters when the remote device is set for one stop bit while the BEX standard parameter is two stop bits. If you can't change the remote device to two stop bits, then use command sequences to change the Apple interface card.

A rarer cause for totally gar4 data is the number of data bits. Plain text only uses seven data bits; the eighth data bit is used for different functions on different computers. The RDC standard parameter is eight data bits. During Input through slot, BEX always "strips off" the eighth data bit.

When you know that the baud rate and stop bits match yet your data is totally gar4, try changing the remote device to seven data bits while keeping the Apple at eight data bits. While this advice baldly contradicts our earlier statements about matching parameters, it has worked in a number of situations--the VersaBraille II and the Macintosh in particular. Call it voodoo interfacing!

Rare and random garbage characters

When you examine the BEX chapter, you may encounter occasional garbage control characters, as well as random punctuation or unexpected capital letters. These characters are the BEX result of special characters like accented letters and copyright or registered trademark symbols. In the Apple II environment, there are 128 possible characters (96 printable ones plus 32 control characters). In many other computers, there are 256 possible characters. These extra 128 characters are known as high bit set characters. Input through slot strips off the high bit, so the characters seem like random garbage. When your source file contains a lot of accented letters, you should globally change them before you send the file to the Apple.

IBM-PC Example

Use a 9F cable to connect an IBM serial port to an Apple Super Serial Card. The male end of the cable connects to the Super Serial Card. The female end of the cable plugs into the IBM serial port. For an Apple IIc, use a 106 cable. When you configure, supply the slot number for the Super Serial Card or IIc port.

Get BEX up and running on the Apple, and get DOS up and running on the IBM-PC. Connect the two devices. Move to BEX's Second Menu and press I, then provide a target chapter name.

The A> prompt appears on the IBM. Type the following:
A> MODE LPT1:=COM1: <CR>
A> MODE COM1:96,N,8,2,P <CR>
If you're using COM1 for a voice device, you can substitute COM2 in place of COM1. When you are using more than one serial interface on the IBM, you may have to modify the DOS commands slightly. See the DOS manual for details.

You can establish a list of files to print, or print queue, using this formula:
print <space> /p <space> [disk drive]:[filenames] <CR>
To print one file named REPORT.TXT on drive B, you enter:
A> print p/b:report.txt <CR>
To print this file plus a MEMO.FMT file on drive A, enter:
A> print p/b:report.txt memo.fmt <CR>
To print every file on drive B, enter:
A> print p/b:*.* <CR>

Once the queue is defined, you're ready to print. The first time you print on the IBM, you must change the printing device to COM1. DOS tells you:
NAME OF LIST DEVICE PRN=:
If you pressed <CR> here, PRN would become the printing device. But you want to print out the serial port, so you type:
com1 <CR>
and the IBM tells you which files are printed as it sends them. As the IBM begins to transmit, you should hear the Apple squeal. Once the chapter is captured to disk, you can use the FIX TEXT transformation chapter on your BEXtras disk to strip out the <CR><linefeed> at the end of each line and place paragraph ( $p ) indicators.

Section 13: Advanced Data Recovery Techniques

In Learner Level Section 13, we discussed how to cope when things went wrong. This Section provides you with three tools to help you cope with most of the problems you could encounter using BEX. One important tool is an understanding of the DOS commands that BEX itself issues. Next, we provide the full details of how option F - Fix chapters works, and present several hints for coping with problem chapters. Finally, we demonstrate the FID utility on the Starting Menu.

Most of the time BEX handles routine housekeeping tasks, like making sure a chapter's directory file accurately describes its page files, perfectly well. However, there are times when BEX becomes befuddled. Fortunately, your human problem-solving skills are a thousand times superior to any computer, so with the right tools, you can almost always put things right.

Part 1: Introduction to Apple DOS Commands

Every menu has option Q - Quit. When you press Q, the Apple responds with the BASIC prompt, the single ] right bracket character. The Echo pronounces this as "Ready." You also get the BASIC prompt when you press Control-Reset to stop a BEX option in progress. In the following samples, we show the BASIC prompt where it will appear. Don't type the right bracket itself, just the commands after it.

A complete discussion of Apple DOS 3.3 commands is outside the scope of this manual. Older editions of the Apple IIe Owner's Guide contain an in-depth discussion of these commands. However, starting in 1987, all references to DOS 3.3 have been expunged from Apple's Owner's Guides. Fortunately, many excellent books about Apple DOS 3.3 and BASIC programming have been written by third parties. See Appendix 5 for publishers of accessible manuals.

Here are some fundamental facts: Always depress the Caps Lock key when you type DOS commands. DOS commands always end with <CR>. In a DOS filename, every character, including punctuation and spaces, is very important; DOS won't be able to find a file on disk unless you type its name exactly. If you make a typing mistake in a DOS command, DOS lets you know with the words SYNTAX ERROR and a high beep. If you mistype a filename, DOS responds with FILE NOT FOUND and a high beep. In the following samples, we enclosed the word filename in brackets to show where you type the filename of your choosing.

When you have more than one disk drive, you must tell DOS which drive you want to operate on. When you press Control-Reset or Quit from any BEX Menu, DOS'S default drive is the BEX program drive, usually slot 6, drive 1. To direct DOS'S attention to a different drive, you add the slot and drive number to the end of any DOS command. The syntax for this is typing S6,D1 for slot 6, drive 1 or S6,D2 for slot 6, drive 2. Once you supply a slot and drive, DOS assumes all subsequent commands are directed to that drive until you give a new instruction. (At the Master Level, you learn about RAM drives, portions of the Apple's memory that you can configure to hold the BEX program and data.)

$$vl: Speech and large print at the BASIC prompt

Quitting allows you to use Apple DOS 3.3 while maintaining BEX's control of input and output--speech and large print display. When you press Control-Reset, you temporarily lose BEX's input and output control. To restore large print display, type RUN <CR> and then Quit again. To relink speech at this point, you can type either ] PR#0 <CR> to restore speech with 40-column screen or ] PR#3 <CR> to restore speech with 80-column screen. When BEX is sending output to the Echo or SlotBuster, it sets the combination of speech and screen output itself. When you type PR#0 or PR#3 at the BASIC prompt, you reset the speech software to "speech only" mode. If you want output to the synthesizer plus the screen, issue the appropriate command.

To relink a serial voice or braille device in slot 5, you type: ] PR#5 <CR> When a serial device is in a different slot, change the digit 5 to that slot number.

The Most Important DOS Command: RUN

When you are at the BASIC prompt, you return to BEX by typing
] RUN <CR>
It's possible to Quit BEX, type NEW and then create your own Applesoft BASIC program. When you do this, you erase the BEX Menu program from the Apple's memory. To return to a BEX Menu, you need to type RUN followed by the filename of the BASIC Menu program, followed by the slot and drive numbers for the BEX program disk. For the Starting Menu, you type: cher/ RUN START,S6,D1 <CR>. For the Main Menu, you type: cher/ RUN MAIN,S6,D1 <CR>. For the Second Menu, you type: cher/ RUN SECOND,S6,D1 <CR>. For the Page Menu, you type: cher/ RUN PAGEMENU,S6,D1 <CR>

When you press Control-Reset or Quit, you can move directly to a different menu from the one you left by typing cher/ RUN [menuname],S6,D1 <CR>

Six More DOS Commands

The BEX Menu programs issue a number of DOS commands as they copy, merge, delete, rearrange chapters and pages within chapters. When you understand the commands that BEX uses, you are better able to issue these commands yourself when BEX is befuddled.

CATALOG

Shows the contents of a DOS 3.3 disk. BEX issues this command when you press <space> after the list of chapters with a BEX D - Disk catalog. When you are having problems with a chapter, it's a good idea to perform a DOS catalog. It shows you every file on the disk. When you Quit BEX and type CATALOG you see every file on the disk in BEX drive 1, usually slot 6, drive 1. To see the files on the disk in drive 2, type:
] CATALOG,S6,D2 <CR>

The catalog information is shown in four columns. The first column is one character wide: when a file is locked, position 1 contains an asterisk. The second column is also one character wide: it contains a single letter that corresponds to the type of file. For binary files, the letter is But, for Applesoft BASIC files the letter is A, for textfiles the letter is That, and for Integer BASIC files the letter is I. The third column occupies positions four through six; it always contains a three-digit number. This number is the sector count for the file. From position eight on to the end of the line is the fourth column; it contains the filename.

INIT HELLO and CLOSE

Initializes a disk, preparing it to save files. This sequence of two commands does the same thing as option I - Initialize disks on the Starting Menu. Be cautious when using this command: any information on the disk is wiped out when it's initialized. While Initialize disks on the Starting Menu prevents you from initializing your BEX program disk by mistake, no such protection exists when you type INIT HELLO at the BASIC prompt. Assuming the disk to initialize is in drive 2, this is the safest way to proceed.
] CATALOG,S6,D2 <CR>
DOS gives you a listing of all files on the disk, allowing you to be sure you don't need them.
] INIT HELLO <CR> %%%ms0%%%ml0


] CLOSE <CR>
to prepare the Apple's memory to run another program.

DELETE [filename]#[Xstyle=Heading level 4]#

Permanently erases a file from the disk. When you kill a chapter, BEX issues one more DELETE command than the number of pages in the chapter. One DELETE command is required for each page file, and then one more for the chapter directory file. BEX uses DELETE whenever you Kill chapters, textfiles, configuration files, or pages. In Part 3, we demonstrate when you might wish to DELETE files instead of letting BEX do it for you.

RENAME [old filename] [new filename]#[Xstyle=Heading level 4]#

Changes a file's name on disk. Second Menu option N - Name change for chapters uses the RENAME command to change the names of the page and directory files. As it renames the page files, it reletters them to follow their numerical order. This requires a fresh directory file, which BEX saves on top of the old one. A situation where you'd use RENAME is described in Part 3.

() Caution! DOS 3.3 unfortunately has a bug regarding file names: This operating system allows you to have more than one file with the same name on a given disk. This is why you should never copy a chapter to the same disk with the same name, or rename a chapter to a name that already is on a disk. We discuss ways of coping with this problem in Part 3.

LOAD SAVE BLOAD and BSAVE

() Warning! The following information is here to whet your curiosity. When you use these commands, it's quite possible that you could damage some of the programs on your BEX disk. It's also possible that you can learn a lot about Applesoft BASIC, by exploring the Apple's power in great detail. Only you can guarantee the safety of your BEX disk by always using a back-up copy.

The LOAD command copies information from disk into the Apple's memory. The SAVE command is its opposite; it copies information from the Apple's memory to a file on disk. You can only LOAD and SAVE Applesoft programs, a type of file identified by the letter A in the second column of a DOS catalog. All of BEX's menu programs are Applesoft BASIC. Once it's loaded into memory, you can look at an Applesoft program by typing LIST at the BASIC prompt.

Binary files, (identified by the letter B in the second column of a DOS catalog), use a variation on the LOAD and SAVE commands. BLOAD copies information from disk into the Apple's memory, and BSAVE copies from memory to disk. Many of BEX's smaller programs are binary files, and all BEX chapters are composed of binary files. Whenever BEX is reading and writing chapters between memory and disk, it's issuing BLOAD and BSAVE commands. BLOAD and BSAVE commands are frequently accompanied by a specific address in memory. For example, when BEX copies a 2795-character page into the page buffer, BEX asks DOS to BLOAD beginning at the address A$9500 a file of length L$2795

Eavesdropping on BEX with MON C

Perhaps all this talk about DOS commands has piqued your curiosity, and you want to know more. There's an interesting Apple feature that lets you watch a program as it's running. One way to understand DOS housekeeping is to look over BEX's shoulder. At the BASIC prompt, type:
] MON C <CR>
and all the DOS commands that BEX issues become visible to you. For example, when you Quit from the Second Menu, type MON C and then RUN you eavesdrop on BEX telling DOS to CLOSE any open textfile, then allocate a lot of memory for the program with MAXFILES 2

To stop eavesdropping on BEX, type:
] NOMON C <CR>
Using MON C doesn't fix anything by itself; it just lets you see how BEX works when things are going smoothly. Before using MON C make sure that you've made lasting copies of anything you want to keep.

() Warning! Monitoring the computer while it's running BEX can easily overwhelm the Apple, resulting in a "deep" crash. In a "deep" crash, the DOS in the Apple's memory is incorrect, and even simple DOS commands like CATALOG yield ?SYNTAX ERROR In particular, using MON C in the Editor or during Fix chapters is guaranteed to create havoc. You probably will have to turn off the Apple and reboot. But a "deep" crash doesn't really harm anything. As long as all essential data is saved to disk, sit back and enjoy the show!

DOS Error Messages

When BEX gets overwhelmed, it usually crashes with an error message. These error messages can help you diagnose the problem and point the way to a solution.

BREAK IN LINE four digit number

As we said in Learner Level 13, you may encounter the BREAK IN LINE followed by a four-digit number error message. From that discussion, you know that when BEX says BREAK your BEX disk is not broken. Rather, it means that the BASIC program crashed at a particular line number. When BEX crashes at line 7410, it means there's some problem writing to disk. Perhaps you specified an illegal chapter name? Maybe the disk drive door is open? When BEX crashes at line 7105, then there's a problem reading from disk. You want to remove and insert the disk a few times to make sure it's seated correctly in the drive.

OUT OF MEMORY error

Whenever BEX presents a list of chapters, it's doing a lot of analytical work behind the scenes. So when you press D for a BEX catalog, or enter a drive number to scan the disk, BEX uses blocks of the Apple's memory to build up the chapter list for your perusal. When you ask BEX to create chapter lists several times in a row, BEX can run out of room in the Apple's memory. The result is that you crash with an OUT OF MEMORY error message. Typing RUN <CR> solves this problem.

SYNTAX ERROR IN 65239

When BEX crashes with this error message, it's a symptom of major disorganization in the Apple's memory. The actual number can vary; it's always five digits long and begins with 65. There's a chance that you can recover, so type RUN MAIN,S6,D1 <CR> at the BASIC prompt. When you try this two times in a row and just get the same SYNTAX ERROR IN 65239 message, you must reboot.

The Asterisk Prompt: Crashing into the Monitor

The Monitor is a unique feature deep inside the Apple. It allows programmers to directly examine the contents of the Apple's memory. When BEX encounters problems, it usually crashes to the right-bracket BASIC prompt. When BEX gets really confused, you could crash directly into the Monitor. The Monitor's prompt is an asterisk (the Echo calls this character star). When you crash into the Monitor, you get a star and then at least one line of what looks like totally incomprehensible garbage. (It's actually useful information about the contents of the Apple's memory, expressed as base 16 numbers.)

To leave the Monitor and get back to the BASIC prompt, press control-C <CR>. Try this twice; if this doesn't give you the right-bracket prompt, it's time to reboot.

Part 2: Advanced Techniques for Recovering Chapters and Pages

In Learner Level Section 13, we gave an example of using option F - Fix chapter directory on the Second Menu. You use Fix chapters when one or more pages of data seem to have disappeared from a BEX chapter, and you know you haven't killed those page files. A thorough understanding of how Fix chapters works can help you cope when Fix chapters doesn't solve the problem.

Fix Chapters in Detail

BEX adds a two-character extension to the chapter name to make a unique identifier for each page file. The first character of this extension is always period, the second character is usually a letter. (More details in Learner Level Section 12, part 3.) There are only 26 letters in the alphabet, and a BEX chapter can contain up to 30 pages. For the last four page file extensions, BEX uses the left bracket, the backslash, the right bracket, and the caret, in that order.

Suppose you've created a chapter named TERM PAPER that's 20 pages long. When you print it, some of the data is missing, yet you know you did not kill any pages. Time to try Fix chapters. After you press F at the Second Menu, you must type in the exact name of the chapter you want to fix. BEX then attempts to find any page file that could exist for a chapter with that name.

First, BEX tries to BLOAD a file named TERM PAPER.A into the page buffer. When TERM PAPER.A exists on disk, then this load is successful, and BEX counts the characters in the page buffer and creates an entry in the new directory file for that page. When a file named TERM PAPER.A does not exist, then BEX tries again with the next possible page extension. When TERM PAPER.B exists, then BEX creates an entry in the new directory file. BEX repeats this process for every possible page.

Normally, the directory file for a chapter keeps track of which file on disk corresponds with which BEX page number. When you cut pages in the Editor, or change the order of pages with the Page Menu, it's quite possible that page 5 corresponds to TERM PAPER.A and TERM PAPER.G corresponds to page 1. Because Fix chapters searches for page files in alphabetical order, the directory file it creates always makes TERM PAPER.A page 1, TERM PAPER.B page 2, and so forth.

After you use Fix chapters, you may have to rearrange the pages with the Page Menu or the Clipboard. If you Zip to the Page Menu and check a newly-fixed chapter with File list, you may find that the chapter has some pages with zero characters. As we mentioned in Section 5, Part 3, you should avoid creating a BEX page with zero characters by deleting text in the Editor. That's because you'll end up with residual files on disk. But when Fix chapters creates a zero page, however, it doesn't create an empty disk file--just an entry in the chapter directory. If the TERM PAPER chapter contained zero characters in page 1, for example, it means that BEX couldn't locate TERM PAPER.A

When Fix chapters can't find the page files

Fix chapters moves through the alphabet as it tries to BLOAD page files. Fix chapters gives up if it tries and fails 20 times in a row. Suppose your TERM PAPER chapter started out at 25 BEX pages. You deleted the first sixteen pages. Then you copied this chapter to a too-full disk, and BEX crashed before it created the directory file. Next time, press # to check the free sector count!

When you ask Fix chapters to recover the TERM PAPER chapter, it tells you that no page files could be located. Fix chapters has tried to BLOAD the page files named TERM PAPER.A through TERM PAPER.P and those files don't exist. Since Fix chapters has failed 20 times in a row, it has given up. The solution is to change the page file names manually to earlier letters in the alphabet. Quit BEX and catalog the full disk with the problem TERM PAPER chapter. Just to make typing easier, the following sample uses the shorter name TP Here's what you type:
] RENAME TERM PAPER.V,TP.A <CR>
] RENAME TERM PAPER.W,TP.B <CR>
] RENAME TERM PAPER.X,TP.C <CR>
] RENAME TERM PAPER.Y,TP.D <CR>
Now you can go through the process outlined above to make room for the directory file then use Fix chapters with target chapter TP.

Coping with DISK FULL Errors

The directory file is always the last file of a chapter written to disk. When some event interrupts the saving of a BEX chapter to disk, then it's likely that the disk contains some of the page files, but no directory file. This can easily happen when the disk you copy to is close to full. Before you create a target chapter by translating, replacing, copying, adjusting, or whatever, you should check that there's enough room on the target disk. You can obtain a free sector count by pressing # at any menu prompt.

When a disk fills up before the directory file is created, Fix chapters alone won't help you. BEX can find all the page files without problem, but there won't be room to write the new directory file to disk. Before you can use Fix chapters, you must make room for the directory file.

First, Copy any other chapters from the problem disk to another disk. Then use Kill chapters on the problem disk to delete the chapters you just copied. Now there's enough room for Fix chapters to write a new directory file.

If you already have copies of every chapter on the disk except the problem chapter, you can use a shortcut. Quit BEX, CATALOG the disk, and then erase just one page file from the target disk by typing DELETE [filename] <CR> at the BASIC prompt. This makes enough room to save a directory file, so you can use Fix chapters. After Fix chapters is successful, you copy the just-fixed chapter to another data disk, and initialize the problem disk.

When a Disk Contains More than One File with the Same Name

As mentioned in Part 1, DOS 3.3 does not prevent you from renaming one file to a name that's already taken. We're not talking here about overwriting an old chapter with a new chapter. When your target disk already contains a chapter named INVOICES and you copy a chapter to the name INVOICES on this disk, the new INVOICES information replaces the old. And usually, that's exactly what you want to happen.

You only encounter the duplicate filename problem when you are renaming chapters, or when you try to create a BEX chapter with the same name as a textfile (or vice versa). Suppose your target disk contains two chapters: a two-page chapter named INVOICES and a BILLS chapter containing three pages. A DOS catalog of this disk shows:
B 010 INVOICES.A
B 015 INVOICES.B
B 003 INVOICES
B 016 BILLS.A
B 008 BILLS.B
B 008 BILLS.C
B 003 BILLS
Further suppose you move to the Second Menu and use option N - Name change for chapters. You specify BILLS as your source chapter and INVOICES as your target chapter. After BEX has renamed the chapter, a DOS catalog of this disk reveals:
B 010 INVOICES.A
B 015 INVOICES.B
B 003 INVOICES
B 016 INVOICES.A
B 008 INVOICES.B
B 008 INVOICES.C

BEX uses the RENAME command to change BILLS.A to INVOICES.A, BILLSDDB to INVOICES.B, and BILLSDDC to INVOICES.C. While it isn't evident in this sample, Name change for chapters reletters the page files so they are in alphabetical order. BEX's final step in Name change is saving the new directory file. In this case, the new INVOICES overwrites the old INVOICES. When you ask to print INVOICES, you get the contents of the chapter that used to be named BILL.

We hope this problem remains completely hypothetical for you. But if you should encounter it, you can use Fix chapters to recover. In our sample, copy INVOICES to BILLS. Then, Kill INVOICES. Now, you have the two page files left from the original INVOICES chapter. Create a new directory file by using Fix chapters with target chapter INVOICES.

FILE TYPE MISMATCH error

Textfiles are type T files and BEX chapters are type B binary files. There are some DOS commands that only work for textfiles, and some others that only apply to binary files. If you try to do a binary file operation on a textfile, or vice versa, DOS 3.3 reports a FILE TYPE MISMATCH error.

When a disk contains a BEX chapter named APPENDIX one binary file named APPENDIX is its directory file. If you told BEX to Write a textfile named APPENDIX on that same disk, DOS 3.3 would complain with the FILE TYPE MISMATCH error. That's because BEX has asked DOS to OPEN a type T file named APPENDIX, but DOS has found a type B file named APPENDIX that can't be OPENed.

You would encounter the same error message if a textfile named APPENDIX existed on disk and you tried to copy a chapter to the name APPENDIX. BEX asks DOS to BSAVE the directory file named APPENDIX, and DOS is upset because you can't BSAVE a textfile. If you tried to edit a new chapter named APPENDIX, you would get a Disk read error message from BEX.

Part 3: FID

FID stands for File Developer. The FID utility program helps you manage DOS 3.3 files. FID lets you copy, delete, lock, and unlock files, as well as cataloging disks. Some FID functions can also be done manually, but FID lets you act upon many files at once.

FID is a binary file on BEX's Boot side. When you press F at the Starting Menu, BEX BRUN'S the FID program. (You don't need to have booted BEX to use FID, however. Once you have booted any DOS 3.3 program, you can insert the BEX boot side and start the program by typing BRUN FID at the BASIC prompt.) The FID software is incompatible with BEX large print. In fact, once FID is loaded, many of BEX's software pointers are erased. That's why you must reboot BEX after using FID.

We've modified the original FID to make it a little easier to use with speech. As with BEX, FID lists its numbered options when you press <CR> at its FILE DEVELOPER ENTER OPTION prompt. You must depress the Caps Lock key for FID to correctly interpret your responses. To make a choice, you type a number followed by <CR>. The options are: Since FID'S output is all uppercase, the remaining samples are transcribed in reverse capitalization mode
1 - copy files
2 - catalog
3 - space on disk
4 - unlock files
5 - lock files
6 - delete files
7 - reset slot & drive
8 - verify files
9 - quit

FID allows you to search for files on a disk without knowing their names. When FID prompts filename you can specify the exact file, or you can use = (equals sign) for any portion of a filename you don't know or want to specify. The equals sign functions as a wildcard. When you type m=d FID finds any file that begins with M and ends with Do, no matter how many characters come between these two letters. Whenever you use the wildcard, FID asks you if you want prompting. When you answer no, then FID performs the requested action without further intervention. When you answer yes, FID presents each filename that matches the wildcard, and waits for your Y or N decision.

For example, suppose you want to copy some of your configurations on to another disk. The four character suffix .con identifies BEX configuration files. Here's how that dialogue goes:
enter option 1 <CR>
copy files
source slot? 6 <CR>
drive? 1 <CR>
destination slot? 6 <CR>
drive? 2 <CR>
filename =.con <CR>
do you want prompting? y <CR>
insert disks. press <ESC> to return to main menu or any other key to begin
filename: =.con
filename default.con y <CR>
done
filename dm.con n <CR>
cancelled
filename nj.con y <CR>
done
filename thiel.con n <CR>
cancelled
filename teach.con y <CR>
done

You can use the wildcard for all FID'S options. Since deleting a file by mistake can be tragic, it's a good idea to take advantage of the prompting feature illustrated above when deleting files. For less destructive operations like LOCK and UNLOCK, you can answer n <CR> to the do you want prompting? question. At the Master Level, we recommend that you lock all the files on the BEX Main side before you load the software on to a RAM drive. You can use the equals sign wildcard with FID'S option 5.