SP0012 HUMANE ENVIRONMENT MANUAL V37 15 Aug 2002 AUTHORS AND EDITORS Jef Raskin (This document's organization is based partially on the Canon Cat manual by David Alzofon, David Caulkins, Jef Raskin, and Dr. James Winter.) Contains edits by Rebecca Fureigh, Astrid Raffinpeyloz, and Richard Karpinski. EPIGRAPH It's extremely important to always bear in mind that we are all creatures of habit, down to the most minute detail, so we tend to confuse what is "natural" with what is "comfortable." Things that are comfortable are so almost entirely because we are used to them. When things become habitual through repeated application, they start to feel natural because we can't imagine them any other way; but we have to take a few steps back and objectively reassess what we do in order to find out whether our comfortable habits are actually natural and efficient. --Murray, Peter. "Essential Bass Technique". Hal Leonard Corporation, Milwaukee WI 2001 used by the kind permission of Peter Murray MAINTAINER Jef Raskin DOCUMENT SCOPE AND PREREQUISITES This alpha test manual for The Humane Environment (THE) assumes that you have used conventional computer-based editors, and therefore sometimes strays from being a manual to explain why we have deviated from present common practices and how these changes make for a better human-computer interface. Please display this document in a monospaced font such as Courier so that examples are aligned correctly. This version is intended for developers, reviewers, futurists, writers, editors, early adopters of new technologies, the curious, and people who used a Canon Cat or SwyftWare and have missed the ease and fluency with which those products worked. Readers (except those in the last category) should have a grasp of the principles behind the design, which differs considerably from current practice. This knowledge is especially necessary for developers if their contributions are to work well with the rest of the system, and who -- being very experienced with current systems and ways of doing things -- are most likely to do things as they have been done in the past. Unfortunately, this can quickly ruin the humane interface qualities of this work. Please read "The Humane Interface" in this regard. In particular, understanding that humans have a single locus of attention and the implications of that fact, the principles of monotony and modelessness, the importance of habituation, how habits are formed, and the use of quasimodes in reducing error rates are all fundamental when making design decisions. If these terms and ideas are not familiar to you, and you want to develop for this environment, please read THI. INTRODUCTION The Humane Environment comprises, among other things, a simple editor for quickly creating drafts of documents with a minimum of effort and hassle. It drastically cuts down on the number of keystrokes and mouse moves it takes to do editing tasks compared with GUI editors such as Word or AppleWorks. In this environment, mouse moves are used only when doing graphic operations such as resizing a window or working on a drawing or photo. After you've become familiar with the Humane Environment, it also greatly reduces your error rate and the chances of making catastrophic errors that cause you to lose your work. It is also a pleasant Python programming environment. It is impossible to design an editor that is better than current practice while keeping it the same as other editors with which you are familiar. Therefore, using this editor means learning some new techniques and abandoning some familiar ones. The new techniques are simpler and faster than the ones that you already know, but they are unfamiliar and will feel odd and slow at first. You will find yourself reaching for the mouse, trying to use the old methods, and becoming annoyed. Please persist in spite of this. Be assured that learning will not take long. After you have used it enough for its operation to become habitual, you will find that standard editing methods -- even if you've been using them for years -- are clearly slower and more difficult. Experience with users of this interface suggests that you will soon wish that all of your software included at least some of the methods that this environment makes available. The Humane Editor stores documents, especially short ones, in far less space than does Microsoft Word -- and without converting it from something readable to MSmishmosh. NOMENCLATURE When you are expected to press and immediately release a certain key with no intervening actions on your part, this manual uses the word "tap", as in "tap the Delete key". Sometimes you are asked to press and hold a key and, while holding it, to tap one or more other keys (as when using the Shift key to type a string of capital letters). One-letter key names are in quotes, as in "to type the word 'the' tap the 't' key, the 'h' key, and then the 'e' key." Longer key names, as with the Delete key, are capitalized but not quoted. UNTESTED This manual has not been tested, problems of clarity, correctness, grammar, punctuation, tone, or whatever should be pointed out to the author (jefraskin at aol.com). You are helping to test it. Thank you. USING THE KEYBOARD To make keyboard operations clear without having to write something like, "in order to type a capital 'A' press and hold the shift key while typing the letter 'a' ", we use a simple shorthand. A backslash after a key name (\) indicates a key going down, and the slash (/) indicates a key going up. Thus, the normal way to type a capital "A", is to perform this sequence of actions: Shift \ a \ a / Shift / Inside this notation we do not use quotes around the names of keys, and individual letters always appear in lower case. In the manual we will not need to use either slash in our examples, so there will be no ambiguity. Holding Shift establishes a quasimode, called the Shift quasimode. A quasimode exists only as long as a key that establishes it is held down. For a discussion of why quasimodes can aid usability, see "The Humane Interface", pp. 35 ff. This book will be referred to as "THI". GETTING STARTED WITH A NEW DOCUMENT IN THIS EARLY VERSION When you double click on the Humane Editor icon to launch it, this prototype will quickly go through a few gyrations where it puts up a window and takes it away. To start a new document, use the New command from the File menu, or type Command \ n \ n / Command / The editor gives you a conventional "Save As" box so that you can name the document you are about to create; in the full implementation this step will not be necessary. After you do that, click inside the Humane Environment window and you are in our brave new world. THE CURSOR A red blinking rectangle about the size of a character is called the "cursor", it always shows you exactly where the next character you type will appear. If it is on top of an existing character, that character will slide to the right (in left-to-right languages such as Latin) or down to the next line (if there's no room to its right) to make room for your typing. When you are moving a block of text, discussed below, insertion works just as though you had typed each of those characters one at a time. When the cursor is on a Return character you will see a paragraph symbol (¶). THE SELECTION AND THE HIGHLIGHT On typing a character you will see a blue highlight to the left of the blinking cursor. The blue highlight always shows you exactly what will be deleted when you tap Delete (sometimes called Backspace or Erase). The blue highlighted information is called the "selection". When a portion of the text is highlighted, it is said to be "selected". When a Return is selected or is part of a selection, you will see a paragraph symbol, when a Tab is selected, an arrow will appear. Similarly, when spaces are selected you will see a dot that is like a period but in the middle of the line rather than at the bottom. This convention (and another, introduced below) makes invisible characters visible when you need to see them -- without having to use a command. They also automatically go away when you don't need them. PRE-SELECTION At those times when you can make a selection, a faint yellowish highlight (the pre-selection) shows you what will be selected if you use the selection command. See THI pp. 105-106. CREEPing (tm) A tap of a right or left arrow key will move the cursor one character further on or further back in the text. This is called "CREEPing". The cursor is not typically moved this way because this method is even slower than using a mouse except for very short moves, but CREEPing is sometimes useful. SCROLLING The up and down cursor arrows scroll the window up and down. They do not move the cursor; if they did, you'd have to get to the top or bottom of the window before the text would start to scroll. If you want to move the cursor up or down, use LEAP (tm) (described immediately below) to move it to exactly where you want it. This is much faster than CREEPing or using a mouse. It is possible to scroll the cursor off the screen. To get back to it, tap the right and left cursor arrows. If you just tap one of them, the cursor will not be where you left it, even though you will be brought back to a view that has the cursor on the screen. The cursor is always returned to a place near the center of the editor's screen area unless it is close to either end of the text, in which case as much text as possible is shown rather than wasting window space. THE HUMANE QUASIMODE When designing this system, we needed a way of entering into a quasimode that does not interfere with existing quasimodes (e.g. control, alt, option, and the like) and which would work with nearly all personal computer keyboards. We know of no exceptions, but if you find a keyboard with which this method will not work, please let us know. To get into the Humane Quasimode (HQ) takes 1 1/2 keystrokes (why the keystroke count is important is discussed in THI's Chapter 4): Shift \ Space \ Space / To get out of the HQ takes 1/2 keystroke: Shift / This does not conflict with normal use of Shift. Here's why: If you are typing in all caps, for example, "I AM" you would type Shift \ i \ i / Space \ Space / a \ a / m \ m / Shift / Which does not trigger the HQ because it does not begin with Shift \ Space \ Space /. If you were typing a line that began with a space, such as " PI", almost everybody (we've seen no exceptions) types the space before they press Shift: Space \ Space / Shift \ p \ p / i \ i / Shift / And again, the HQ is not engaged, even though Shift is held down. Sometimes people will take advantage of keyboard rollover and the sequence might come out: Space \ Space / Shift \ p \ i \ p / i / Space / But, as far as we know, rarely if ever do people Shift until they come to the first non-blank character in a capitalized string they are typing. Thus, the HQ will rarely, if ever, be entered accidentally (and, as we shall see, even if it is, the mistake will probably not cause any difficulties). COMMANDS From a user perspective, we do not have to discuss the HQ because we have a simple rule: Commands always begin with an uppercase space and are typed in uppercase (that is, while holding down the Shift key). The command will appear as you type it, in transparent letters that float over the text; we don't use dialog boxes that obscure whatever is behind them, and our messages disappear automatically when they are no longer needed (you never have to close a dialog box). The command is executed when you let go of Shift. You can backspace and make corrections of typing errors before executing the command. The word "done" appears to show you when the command has been completed. WHAT IS LEAP[TM]? LEAP is our trademarked name for the fastest known method of moving a cursor in text. Compared to moving the cursor to an on-page location with the mouse, it saves an average typist about 1 second. That's 1 second for every mouse move (think about the number of such mouse moves made in the world's hundreds of millions of computers every day!). For off-page moves where you'd use the scroll bar in a conventional system, LEAP saves you at least 4 seconds, usually more. Because using scroll bars is so slow, the Humane Editor does not have scroll bars at all. LEAP is used for cursor motion, as a text search method, and for information retrieval tasks. LEAP In this preliminary manual (designed for developers, not users), we are not using screen shots. This helps to preserve ease of modifying and emailing this document. So in our examples, we will indicate the position of the blinking cursor with an asterisk below a character. The examples will use lowercase characters, allowing us to indicate the selection by capitalizing letters. Each example has a number to its right for reference purposes. Let us say that you have typed the word "remember" and the cursor is on the first "r". The first "r" is also selected. It is best to download the software and try the examples as we go along. To set up this example, type the word and use the Creep (arrow) keys to move the cursor to the beginning of the word). Remember * (1) As a first task, let's LEAP to the letter "b". To do this, you press "Shift" and while holding it, tap the Space bar to get into the HQ. Type ">", which is the command for LEAPing further ahead in the text. You now have to enter a "pattern". The text that the pattern is intended to match is called the "target". You type "b" and the cursor moves to the "b" in "remember". You do not have to leave the HQ, the move happens as soon as you type the pattern. You have typed: Shift \ Space \ Space / > \ > / b \ You are still in the Humane Quasimode, but the cursor (and selection) will immediately jump to the "b". We get to this situation faster than you could move your hand to the mouse and point to the "b" (to see the improvement in time saved, you can do a GOMS analysis. See THI's Chapter 4 for details on how to calculate how long an interface task will take): rememBer * (2) You can think of LEAPing forward as pressing the "Shift" key, tapping the space bar and ">",and typing the letter you want to land on. As soon as you enter the LEAP quasimode you will instantly see all the hidden characters (Spaces, Returns, and Tabs) appear so that you can easily LEAP to patterns including them (think what you have to go through to include characters like that in a conventional FIND dialog box!). Back to our example: To LEAP to the first "r", use the same method but indicate that the LEAP searches backward by using "<". This returns us to example (1). The command ">" followed by the pattern LEAPs forward. The command "<" followed by the pattern LEAPs backward. Moving the cursor from the initial "r" to the second "e" in "remember" requires letting the editor know which "e" you mean. To do this, use the pattern "emb". Creep the cursor to the beginning of the word "Remember". To see why you need "emb", let's do the LEAP in slow motion. You press "Shift" and tap Space, continuing to hold down the "Shift" key. While still holding Shift, you type "e" and you see the cursor move to the first "e" in "remember". Then, while still holding the "Shift" key down, you type "m". The pattern now matches the first "em" in the word "remember". Lastly, while still holding down "Shift", type "b". The cursor leaps to the proper "e" because this is the first instance of "emb". This is how LEAP always works: After activating the Humane Quasimode and the desired LEAP command, you type the character that you want the cursor to be on and then whatever characters follow it. LEAP wraps: after reaching the end of the document, it continues searching from the beginning of the document. If an instance of your pattern occurs in the text, LEAP will find it. LEAPing backwards also wraps. If an instance of the pattern does not occur in the document, the next document will be searched, and so on until all text in the window (which may be many documents) has been searched through. The search pattern is shown in a transparent overlay. Such overlays and how they operate are discussed in THI p 117. LEAPING TO UPPERCASE LETTERS AND SPECIAL SYMBOLS You can't use Shift in a pattern because you are already holding it down. Therefore, a lowercase letter in the pattern matches not only itself, but also its corresponding uppercase letter in the text. Similarly, if you want to LEAP to an asterisk (normally typed by pressing and holding Shift and then tapping the "8" key), you LEAP to the pattern "8", which will match an "8" or an "*", whichever occurs earlier in the text. Adding characters to the pattern usually resolves any ambiguity that might arise from this convention. For example the numeral "7" and the ampersand "&" are on the same key. If the text was * 17 & 5 are both primes with the cursor at the asterisk, then a LEAP to the pattern "7 7" would LEAP to the 7. A LEAP to "7 5" would Leap to the ampersand. They are distinguished by context, just as we distinguish between LEAPing to one of two instances of the same letter. The Spaces in the LEAP patterns are important. A simple method for LEAPing to a completely explicit pattern is discussed below; in practice it is seldom used. TIPS FOR USING LEAP Returns are especially handy to LEAP to and as part of LEAP patterns. This can be hard to get used to because most of today's computer interfaces have Find commands that make it difficult to use a Return as a part of a pattern. As a consequence, users of present systems are not accustomed to thinking of routinely using Return in a pattern. However, it is the easiest way to move to the end of a paragraph you are working in the middle of. The key to using LEAP is to focus on where you want the cursor to be, which is usually exactly where you want the next typed character to appear (or exactly where you want to erase a character) -- even if that character is a Return. Remember that when you are LEAPing we make Returns visible. It is slightly faster to tap the Space bar with the hand opposite the one you use to press and hold Shift (another handy human factors fact). ADJUSTING A LEAP PATTERN You can backspace while making a LEAP pattern, so long as you are still holding down Shift, and the cursor will retreat as you remove characters from the pattern, landing on the places it just visited as you typed the pattern. You can also add to the pattern again after you've backspaced to re-aim the LEAP at the desired target. You may sometimes want to use scroll (an up or down arrow) to find a place to which you want to LEAP, and then use LEAP to move the cursor to the place you are looking at in the text. It can be useful to leave markers in places in your text that you want to get back to quickly. I use "xxx" as I seldom have need for that in my writing. A LEAP to "xxx" will nearly instantly get you back to your marker. The danger is, of course, that you might leave an "xxx" lying around in your text. You can instantly check if you have with a LEAP, of course. A very satisfying trick is based on the fact that if you LEAP to a pattern that is not in the text, you are returned to where you started from; you will also get a warning sound. However, a positive use of this fact is that if you LEAP and get to the wrong place, and if you have not yet released the Shift key, then just hitting a bunch of keys will cancel the LEAP because it will almost certainly generate a pattern not in the text. Banging on the keyboard also relieves your frustration at having not found the target you were going for in the first place. A quieter way is to backspace to delete the pattern. WHY WE HAVE A SOUND WHEN LEAP DOES NOT FIND A TARGET The Humane Environment's editor is usable by blind and other visually impaired users, who need the sound to tell that a LEAP has not found a target (they can hear the text via the talk command, described below). SELECTING To perform an operation on a chunk of text such as deleting it or changing it to boldface, you LEAP from one end of the chunk to the other and then invoke the Select command. Shift \ Space \ Space / S \ S / Shift / Which means simply to type Space S while holding the Shift key. When you let go of Shift, the selection is highlighted. You can use Creep (the right and left arrow keys) to adjust the ends of the selection. A tap of Creep causes the selection to collapse to the end pointed to by the cursor control (arrow) key. You can then move the cursor with the Creep keys and use the Select command. REPLACING TEXT If you wish to replace one word (I'll call it the old word) with another word (the new word), you select the old word, tap Delete to delete it, just as you would delete any selection, and then type the new word. This method applies to any amount of selected text, not just a single word. This is a bit different than the way most current word processors work. In those, deletion is a side effect of typing whenever there is a text selection. This side effect occasionally causes major problems. For example, in most word processors you can select (highlight) a large section of your text, intending, say, to move it. However, if you are distracted for a moment so that you forget that you had made a selection and then you start typing, or if you accidentally hit a key on the keyboard, the selected section of your text is unexpectedly erased. You risk losing the text unless you notice that this has happened. In the Humane Editor, typing is never anything other than typing. We feel strongly that the integrity of your work is more important than having to tap Delete when you want something deleted. Because we save all deletions, you might argue that there is no danger to accidental deletion, however if you have ever tried to figure out just where an inadvertent deletion came from, you will know why this is only a partial solution. We will provide unlimited Undo levels, so that going back to any previous state is possible. However, using this method can be slow, and you have to use various tricks to preserve later work as you recover the earlier. It is best not to have deletion be a side effect of typing. COMMAND PRESENTATION FORMAT Here are some of the commands presently implemented. As noted above, to operate a command, you get into the HQ, type the name of the command, and then exit the HQ. THE REPEAT THE LAST COMMAND COMMAND Return This is probably the second most often used command after select. For example, LEAP to a space, then reenter the HQ and tap Return. The cursor will move to the end of the next word. Continue tapping Return while still holding Shift and you will be moving the cursor a word at a time. If you hold Return down, the cursor will jump from word to word quickly, sort of a fast creep. If you do the same but with a period as the pattern, you will be scrolled through the text a sentence at a time. If you had LEAPed to a Return before using the repeat command, you will be scrolled a paragraph at a time. This gives you a fine control over scrolling speed. You can also quickly glance at every occurrence of the word "dinosaur" (or whatever) in a text or find every place that a variable is mentioned in a program. COMMANDS THAT REQUIRE NO SELECTION (if there is a selection, it is ignored) S Select. After a Leap, this command selects the text Leaped over. The previously selected text becomes the "old selection", which will be explained in the section on commands that require two selections. This is probably the most used command. Return Repeat last command (including LEAPs). AB Again Backwards. Does a backward LEAP using the most recent pattern. This allows you to force the direction of a repeated LEAP to backward. AF Again Forwards. Does a forwards LEAP using the most recent pattern. This allows you to force the direction of a repeated LEAP to forward. COMPILE This is a programmer thing, not needed otherwise. DELETE Remove the contents of the Deletion Document. This is only used to clean up something you want to share, as it permanently removes the Deletion Document. Use with care and discretion. T Talk. This command pronounces the text starting at the cursor location. It is stopped with the STOP command. TE Talk for Editing. The same as Talk, except that punctuation is read aloud. Used by the visually disabled who wish to edit documents and therefore must know where punctuation marks, returns, and other formatting information are located in the text. It is stopped with the STOP command. STOP This command stops the ongoing operation of any time-consuming command. It is especially useful for stopping the talking commands. COMMANDS Inserts a list of the currently available commands into the text. It leaves them selected so that you can delete them if you wish. This feature should be consulted whenever you update your system to see what commands are available. Though we try, we cannot guarantee that the list is complete. Sometimes we implement two or three commands in a day, sometimes we don't add any for a few weeks. We hope that others will start writing specs for adding commands (anybody want to do print?) See the specification (available from Jef) for how some future commands will operate. The idea here for cooperative development is to first develop and discuss the specification, and when consensus is reached on the spec, then the command (or whatever) is implemented. SAVE The usual save function. Saving is also done automatically whenever you finish a paragraph by typing two returns and when you quit. QUIT Executes the usual system Quit command. When you later re-open the document the cursor and document state will be the same as when you left it (except for window size and placement, which will be fixed). CLOSE Closes the frontmost window. COPYIN Copies the system cut/paste buffer into the text. This allows moving material from other applications into the Humane Environment. COMMANDS THAT REQUIRE ONE SELECTION COPYOUT Copies the selected text into the system cut/paste buffer. This allows moving material from the Humane Environment into other applications. LEAP This command uses the current selection as the pattern for a LEAP. Note that this is very different than the usual LEAP where you are typing the pattern as the search is being made. This LEAP command allows you to specify upper- and lowercase letters in the pattern, for example. LEAPBACK Same as the LEAP command, except that it searches backward. CALC Treat the selection as an arithmetic expression by placing the selection into the deletion document and replacing it with the result of evaluating the expression or an error message if the expression could not be evaluated. The syntax of the expression is that of the underlying Python. Variables can be set in an expression and later used in other expressions. RUN Execute all lines in the selection preceded by two or more spaces as a Python program. The program is not deleted. The first line of the program must be preceded by exactly two spaces (as leading spaces are significant in Python code). DO Execute the selection as if it were a command name. This allows you to use a list of commands as a menu, just select the one you want and execute the DO command. Some seldom-used command names can be very long, and selecting them can be easier than typing them. COPY Place a copy of the selection at the current cursor location as if it had been typed there. The copy is left selected. MOVE Place a copy of the selection at the current cursor location without changing any of its formatting and delete the selection. The copy is left selected. This is better than the usual cut-and-paste model as you cannot lose the material to be moved (as when you perform a second cut before you've pasted in a conventional system). BOLD Puts a copy of the selection into the Deletion document and makes any text in the selection bold. A copy is put into the Deletion document so that if it had a mix of bold and unbold characters, you can get back to that state. ITALIC Puts a copy of the selection into the Deletion document and italicizes any text in the selection. UNDERLINE Puts a copy of the selection into the Deletion document and underlines any text in the selection. NORMAL Removes italic, bold, or underline or any combination of those styles from the selected text. COUNT Counts the number of characters in the selection. Divide by 5 to get a good approximation of the number of words (we will have a real word counter presently). Remember that you can do a calculation anywhere at any time in the Humane Environment -- you needn't do the divide by 5 in your head. COMMANDS THAT REQUIRE TWO SELECTIONS SWAP Interchanges the contents of the old selection and the current selection. Preserves formatting. APPENDIX 1: QUIRKS AND WORK-AROUNDS While a saved file will reopen with the cursor in the same place and the state of the text exactly as it was left, the window always reverts to a certain size. It is a bother to have to drag it open. This will be fixed. APPENDIX 2: LEGALESE Distribution of this in-progress software is for testing and illustrative purposes only and does not confer any rights, including rights to reproduce copyrighted material and patented inventions. Please do not share it further. Any files created with it may or may not be readable with future versions, though as far as we know they can be cut-and-pasted into almost any word processor. Send any comments on our work to jefraskin@aol.com This editor started out as the WASTE text editor and is being gradually transformed into the Humane Editor; ultimately, there will be little or no WASTE code left. If you wish to use the WASTE Text Engine without our modifications, it is available for free for non-commercial purposes. See www.merzwaren.com/waste/ Similarly, Python is available at www.python.org See the licensing agreements on those sites for details. WASTE Text Engine © 1993-2000 Marco Piovanelli This document and accompanying software and interface design, additions, other documents, and changes we have made to WASTE and Python © 2001 Jef Raskin. When completed, the changes will be made available in accord with the agreements covering the use of Python and WASTE. Various parts of this work are covered by one or more patents and patents pending.