[Indigo]<AltoSource>ALTOUSERSHANDBOOK.DM!2>BrMan1.bravo

This manual describes the Bravo system for creating, reading and changing text documents on the Alto. It is supposed to be readable by people who do not have previous experience with computers. You should read the first four sections of the Non-Programmers Guide to the Alto before starting to read this manual.

This manual is written on the assumption that you have the user profile, fonts and other Bravo-related material from the BASIC NON-PROGRAMMER’S DISK. If this is not the case, some of the things which depend on that stuff will not work the same way.

Bravo was designed by Butler Lampson and Charles Simonyi, and implemented mainly by Tom Malloy, with substantial contributions from Carol Hankins, Greg Kusnick, Kate Rosenbloom and Bob Shur.

Bravo is the standard Alto system for creating, editing and printing documents containing text. It can handle formatted text, but it doesn’t know how to handle pictures or drawings; for these you should use Draw, Markup or Sil.

When you start up Bravo (do it now, by saying Bravo/eCR to the Executive), you will see two windows on the screen, separated by a heavy horizontal bar. The top one contains three lines with some useful introductory information; it is called the system window. The bottom one contains a copy of the material you are reading, which was put there because of the "/e" you typed to the Executive. If you had omitted the "/e", as you do when using Bravo normally, the bottom window would be empty, except for a single triangular endmark which indicates the end of a document. In the bar separating the two windows is the name of the document in the lower window.

As you do things in Bravo, the first two lines of the system window will give you various useful pieces of information which may help you to understand what is going on and to decide what you should do next. Usually, the top line tells you what you can do next, and the second line tells you what you just did, and whether anything went wrong in doing it. Make a habit of looking at these two lines while you are learning Bravo, and whenever you are unsure of what is happening.

The characters which you type (Q and CR) are underlined in this example; the characters which are not underlined are typed by Bravo. This convention is used throughout the manual. Notice that you only type the first character of the Quit command; this is true for all the Bravo commands.

Each Bravo window (except the top one) contains a document which you can read and change. Usually you read the document from a file when you start Bravo, and write it back onto a file after you have finished changing it. Later, you will find out how to do this (section 2.3). It is possible to have several windows, each containing a document; this too is explained later on (section 4.2).

Bravo is controlled partly from the keyboard and partly from the mouse, the small white object with three black buttons which sits to the right of the keyboard. As you push the mouse around on your working surface, a cursor moves around on the screen. Pushing the mouse to the left moves the cursor to the left, pushing the mouse up (away from you) moves the cursor up; and so forth. You should practice moving the mouse around so that the cursor moves to various parts of the screen.

The three buttons on the mouse are called RED (the top or left-most one, depending on what kind of mouse you have), YELLOW (the middle one) and BLUE (the bottom or right-most one). They have different functions depending on where the cursor is on the screen and what shape it has. Don’t push any buttons yet.

If the cursor doesn’t move smoothly when the mouse is moving, try turning the mouse upside down and spinning the ball in the middle with your finger until the cursor does move smoothly as the ball moves. If this doesn’t help, your mouse is broken; get it fixed.

You can pick the mouse up and move it over on your work surface if you find that it isn’t positioned conveniently. For instance, if you find the mouse running into the keyboard when you try to move the cursor to the left edge of the screen, just pick the mouse up and set it down further to the right.

This section describes the minimum set of things you have to know in order to do any useful work with Bravo. When you have finished this section, you can read the other parts of the manual as you need the information.

Move the cursor to the left edge of the screen and a little bit below the heavy black bar. Notice that it appears as a double-headed arrow. It will keep this shape as long as you stay near the left edge, in a region called the scroll bar. If you move it too far right, the shape will change. Keep the cursor in the scroll bar for the moment.

Now push down the RED (top or left) button and hold it down. Notice that the cursor changes to a heavy upward arrow. This indicates that when you let the button go, the line opposite the cursor will be moved to the top of the window. Try it. This is called scrolling the document up.

Next push down the BLUE (bottom or right) button and hold it down. Now the arrow points down, indicating that when you let the button go, the top line on the screen will be moved down to where the cursor is. Try it. This operation takes a few seconds, so don’t get impatient. Practice scrolling the document up and down until you feel comfortable with it. It is useful to know that if you don’t move the mouse, scrolling with RED and BLUE are symmetrical operations: one reverses the effect of the other.

You may have noticed that the text on the screen doesn’t fill up the window, but that more text appears when you scroll up. The reason for this is that in addition to space on the screen, Bravo needs space inside itself (in the Alto’s memory) to display lines of text on the screen. When a line has only a few characters, it doesn’t take up much internal space, but when it runs all the way across the page, like the lines in this document, it takes a lot of internal space. When Bravo runs out of internal space, it stops displaying text and leaves the rest of the window blank. You can tell that there is more text in the document (i.e., that you aren’t seeing the end), because when Bravo gets to the end it displays a triangular endmark as the very last thing to mark the end. If you don’t see the endmark at the bottom of the displayed text, you can be sure that there is more text in the document which isn’t being displayed.

If you keep the cursor in the scroll bar, near the left edge, and hold down YELLOW (the middle mouse button), you will see the cursor change into a striped right-pointing arrowhead. Think of it as a thumb, and the entire left edge of the window as the pages of a closed book, corresponding to your whole document (not just to what is displayed). If you stick the thumbnail into the book and flip it open, you will find yourself someplace in the book. If the thumb is near the middle, you will be about in the middle. If it is all the way at the top, you will be at the beginning; if all the way at the bottom, you will be at the end.

The tip of the arrowhead acts like the thumbnail, and letting go of YELLOW is like flipping open the book. You will also see another striped arrow, enclosed in a box. This one is called the bookmark; it points to your current location in the document. After you let up YELLOW, if you hold it down again without moving the mouse, the thumbnail and the bookmark should coincide exactly, making a solid arrowhead; this happens because the thumbing operation moved the document exactly to the place indicated by the thumbnail. To move forward a little, push the thumbnail down a little below the bookmark and thumb again; to move back, push the thumbnail up a little above the bookmark. To get to the beginning, push the thumbnail up until the arrowhead overlaps slightly the horizontal bar at the top of the window. Try thumbing your way through the document until you feel comfortable with it. Also try thumbing and then scrolling up and down.

You always make the selection first, then give the command. If you change your mind about where you want the change made, you can always make another selection. Making a selection is just like pointing with a pencil: it doesn’t have any effect on the document. Only commands can change the document. You never have to worry about getting rid of a selection, since it never does any harm. If you make a selection, and then give a command that doesn’t require any selection, that is perfectly all right; the needless selection will be ignored.

You make selections by pointing with the mouse and pushing one of the buttons. To try this out, move the cursor into the region of the screen where the text of the document is displayed. Notice that the cursor is displayed as an arrow which points up and slightly to the left. Point the arrow at a character (any character) in the document, and click RED. The character you pointed at should be underlined; if it is, you have just selected it. If it isn’t, look nearby and see if some other character is underlined. If you find one, then that is the one Bravo thought you were pointing at. Experiment until you feel confident that you can point easily at characters.

You should note that each selection erases the previous one; there is only one selection at a time, and it is the most recent one. Also, you can make a selection at any time, except when you are in the middle of a command. Once you have started a command, you must either finish it normally, or abort it by striking DEL, before you can make another selection.

Something useful to know: if you hold RED down, you can move the cursor around and the selection will follow it. The selection won’t freeze until you release RED (or move the cursor out of the text area). Try this too.

Now try a selection using YELLOW instead of RED. Notice that instead of underlining a character, Bravo now underlines a whole word. A word is defined as consecutive letters and digits, or consecutive punctuation characters. For convenience, apostrophe is counted as a letter. Also, a number containing a decimal point is a single word.

There is one more thing to learn about selecting text: how to select more than one character or one word. To do this, first select a character with RED. Then point to another character and click BLUE; Bravo will underline all the characters between the one you selected with RED and the one you pointed at with BLUE. This is called extending the selection. Try holding down BLUE and moving the cursor around. The selection will change continuously so that it includes the characters between the one you originally selected with RED and the one you are pointing at now. As before, when you let up the button, the selection will freeze. You can change the extension as many times as you want by using BLUE over and over; Bravo will remember the original selection you made with RED until you make another one.

Finally, try selecting a word with YELLOW and then using BLUE to extend the selection. Notice that the end of the selection will be a word also. To select the entire document, issue the Everything command.

Space, TAB and carriage return (CR) characters in the document simply appear as white space on the screen, just as they do on paper. You can, however, select them like any other characters. Try it. You will notice that not all the white space on the screen can be selected; in fact, the space on a line after a CR, and the space to the left of the left margin, cannot be selected. Bravo’s handling of white space is discussed in detail in section 3.5.

Now that you know how to say where you want a change made, it’s time to make a change. Select something (for instance, a word). Now type D (for Delete). The word you selected is deleted from the document, and the selection moves over to the character after the original selection. The rest of the text is adjusted to make up for the deleted material; if necessary some words may be brought up from the next line to fill up the one which contained the deleted material.

You can undo the deletion by typing U (for undo). Try it; you will see the stuff you deleted reappear, and it will be selected again, just as it was before you deleted it. Do several deletions, followed by undos, until you are sure you know what will happen. Try deleting larger pieces of text by extending your selections. Be sure not to move the selection between doing the Delete and the Undo.

To add new text, select something in front of which you want the new text to go (if you want it to go at the very end of the document, you can select the endmark). Then type I (for Insert). You will see that a blinking caret appears just before the selection. This marks the place where the new text will go. Anything you type will appear where the caret is, and as you type each character, the caret will move over to make room for it. Try typing a few characters, and notice that the rest of the text is automatically rearranged to make room for the new stuff.

If you strike the wrong key while typing, you can erase the mistake by striking the BS key (on the right side of the keyboard). You can erase as many typed characters as you like using BS. You can also use Ac (hold down the CTRL key and type A) to erase a character; it works just like BS, and may be more convenient to type with your left hand, if your right hand is on the mouse. To erase typing on a larger scale, you can use Wc (hold down the CTRL key and type W) to erase a word and its following spaces or punctuation characters. When you have typed as much as you care to, hit ESC to finish the insert. Notice that the caret disappears, and that the inserted material is selected. You can undo the insertion with Undo. Then you can undo the undo and get the insertion back. Try it.

Sometimes it is more convenient to insert after a selection, rather than before. You can do this with the Append command (remember that you just type the A). Except for where the new material goes, Append is exactly like Insert.

If you want to change one word into another, or correct a typo, you have to delete some text and insert other text in its place. This can be done by a Delete followed by an Insert, but it is more convenient to use the Replace command, which combines these two functions into one. Replace can also be undone.

Whenever Bravo first displays the blinking caret, you can insert a copy of some existing text rather than typing in new text. You do this by making another selection, called a copy selection, instead of typing. The copy selection is made exactly like an ordinary selection, and you can even use the scroll bar to move around in the document in order to find the text you want to copy. You can distinguish a copy selection from an ordinary one by its dotted underline, which contrasts with the solid underline of an ordinary selection.

You can change your copy selection as many times as you like. When you are satisfied with it, type ESC, and a copy of the copy selection will be inserted in place of the blinking caret. You can’t do anything else while you are making a copy selection, except to scroll the document.

There is one more useful thing to know about insertion. If you just type an ESC for an insertion, without making a copy selection or typing anything else, a copy of the last thing you inserted or deleted will be inserted. This is called repeating or defaulting an insertion; it is very convenient for inserting the same thing in several places, e.g., a dollar sign in front of several numbers. It also gives you another way to move text: first delete it, and then insert it in its new place by selecting the new place and typing Insert followed by ESC.

You now know all three ways of doing an insertion: typing the text, selecting some existing text to be copied, or defaulting the previous insertion by simply typing ESC. These three ways of inserting text can be used whenever a Bravo command needs some text. You will see many references to "inserting text" as you read on.

Whether you use Bravo simply to read or browse through a document, or to create or change it, you will need to fetch the document from a file before starting, and to file it away again afterwards if you have changed it. This section tells you how to do these things.

To fetch a document from a file, give the Get command. You will see the blinking insertion caret appear in the heavy black bar above the window. Insert the text of the file name, usually by typing it in, and ending it with an ESC just as for any other insertion. The document will appear in the document window, and there will be a note in the system window telling you how long it is. A Get will erase the old contents of the window, if any.

To file a document away, give the Put command, and type the file name as you did for Get. If the name you want is already in the black bar, you can just type ESC to default the name. It is also possible to edit the file name in the black bar, exactly like an ordinary document. Put always files away the entire document, regardless of what the selection is; when it is done, you will see a note which tells you how long it is. Bravo turns most of the screen black while executing a Put; this makes the Put run faster. Do not be alarmed at this.

Warning: If you make some changes to your document and then attempt to Quit from Bravo without having done a Put, Bravo will warn you that the document has not been filed and will ask you whether you still wish to Quit. If you want to save the document, strike DEL to cancel the Quit command, then file the document using Put. If you want to quit without saving the document, type Yes. If you do this, you will lose any changes you have made to the document. If this does happen to you, read section 4.3 on replaying to see if you can still be saved.

If you Get a document from a file and Put it back on the same file, Bravo will save the original on a backup file. Normally the backup file’s name will be the name of the original file followed by a "$". The backup file is sometimes useful if you discover that some of the changes you made are not to your liking after all. If you have enabled version numbers at Install time (not recommended), the backup file will be the old version of the file from which you did the Get, and Bravo will make a new version for the Put (see section 8.7 of the Alto Non-programmer’s Guide for a discussion of file versions).

You can do an "unformatted Get" with the Zc command (type Zc instead of Get); this treats the formatting information at the end of each paragraph as ordinary text. The main use of Zc is for patching up a file which has been damaged by hardware failure or cosmic rays. In particular, if Bravo refuses to Get the file because "End of file not in Bravo format", you can usually correct the problem by doing an unformatted Get of the file, deleting the last line or two, and Putting it back. Then Quit, restart Bravo and try again to Get the file.

Printed copies of a document may be obtained using the Hardcopy command. Before using Hardcopy for the first time, you must tell Bravo the name of the printer you intend to use regularly. To do this, Get the file User.cm. In that document, you will find an entry that looks like this:

Replace the words "Name-of-your-Press-printer" with the name of the printer you intend to use (every printer has a registered name such as Clover, Menlo, or Daisy). Then Put the document, Quit, and type Bravo/iCR to the Alto Executive.

To print one copy of the document you are editing, simply give the Hardcopy command followed by CR. This will print the entire document, regardless of what the selection is. While doing the hardcopy, Bravo displays in the cursor a count (modulo 10) of the number of pages it has processed; hardcopy takes about 8 seconds per full page, like this one. After sending the document to the printer, Bravo will report success. If there is a problem, Bravo will leave a note in the system window. If the printer is not responding, Bravo will leave a note to that effect, and keep trying. You can abort the Hardcopy by typing DEL, as always.

The hardcopy may fail for several reasons. If there is an EFTP error, trying again will usually work. If the problem is that there is a character in your document which is in a font for which there is no printable representation, Bravo leaves one of the offending characters selected, and puts it at the top of the screen. You can try again after modifying the looks of the selected character. If you have a page with so many different fonts that it exceeds the capacity of the printer, Bravo leaves the first character of the page selected and at the top of the window. There is no remedy for this problem except to simplify the offending page. See section 4.6 for more information about fonts.

You may want more than one copy of a document. The Hardcopy command has an option called Copies, which allows you to specify the number of copies you want; you type in the number, and it will appear in the leftmost buffer in the system window, much like a file name. You must give the Copies option right after the Hardcopy command, every time you want more than one copy.

If you compare the hardcopy of your document with Bravo’s display, you will see that although the text is identical, the hardcopy has more words on each line, so that the two versions look quite different. In order to see a nearly exact facsimile of the hardcopy on the screen, you can give the command

You are now in hardcopy mode on the screen. Until further instructed, Bravo will represent the printed version of your document as faithfully as it can, by positioning each character on the screen within one-half screen dot (about .007 inches) of its position in the final hardcopy. The screen representation is 10% larger than the printed one. To turn off the hardcopy simulation, type

You can edit normally in hardcopy mode. In fact, if your document contains tables whose appearance is critical to you, it is advisable to stay in this mode, because in the normal mode text will take up much more space on the screen than it will in the final hardcopy (if you have such tables, you should also read section 3.5 on white space and tabs). In hardcopy mode it is also possible to see exactly where lines will be broken, so that you can insert hyphens by hand if necessary.

The Hardcopy command has options for printing on the Diablo printer, and for producing a Press file which can be combined with drawings into a larger printable document, or sent to a file server for public distribution. These are described in section 4.8.

As you edit, Bravo keeps track of the changes you make to the document. In doing this, Bravo consumes space in the Alto memory. During a long editing session, it is possible to consume all the available space, in which case Bravo will leave a warning note ("Core storage getting low") in the system window, and will refuse to execute any more editing commands. If this happens, you should Put your document onto a file immediately, and then Quit, restart Bravo, and Get the document back from the file. Now you can continue with another editing session.

When you have finished editing one document and have filed it away, you can Get another file, and continue working. It you are making extensive changes, however, it is better to Quit and restart Bravo when you start to work on a new document. If you do this, you are less likely to provoke a bug in Bravo, and you will be able to recover from a crash with the replay feature (section 4.3) much more quickly.

The maximum size of a Bravo document is 65,536 characters. Whenever Bravo Gets or Puts a document, it leaves a note telling you how long the document was. When your document has reached 65,536 characters, you won’t be able to add any more text, and peculiar things may occur if you do try to add more text. It is a good idea to split the document into two parts well before this happens. To encourage you to do this, Bravo will flash the screen and display a warning message after every command if the length of the document exceeds 60,000 characters.

Depending on exactly what Bravo is doing, the amount of text it can display on the screen will vary. You can always get the maximum amount of text displayed by doing a scrolling operation; if you scroll up with the cursor at the top of the scroll bar, the text won’t move, and Bravo will just display as much more as it can. If you then give a command, some of the text may disappear from the screen, but you can always get it to reappear by doing another scrolling operation.

Bravo keeps copies within itself of information in your user profile (file User.cm; see section 4.6) and in various files on your disk: font files (named *.al and Fonts.Widths), and the files containing the Bravo system and its temporary storage (named Bravo.*). It refreshes these copies whenever you start it up with

This is called initializing Bravo. It is necessary to initialize whenever you get a new version of Bravo or the Alto Operating System and when you change your user profile or any font file. Initializing is just like starting Bravo up normally, except that it takes about a minute. If you are in any doubt about whether something has changed since the last time you initialized Bravo, or if your Bravo is crashing with messages which refer to disk or file errors, you should initialize Bravo by starting it with Bravo/i.