aoeui(1)

Heads up, bestie: -x isn't anywhere in this page, so I didn't invent it. Everything that is in the original is kept below 💅

Manual page aoeui(1) from the General Commands Manual, part 1 of 3 🦋

✨ NAME ✨

aoeui - a lightweight visual editor optimized for the Dvorak keyboard 💖

✨ SYNOPSIS ✨

aoeui [ -k ] [ -o ] [ -r ] [ -s | -S ] [ -t tab stop ] [ -u | -U ] [ -w command ] [file...]

✨ DESCRIPTION ✨

okay so aoeui is an interactive display text editor that's basically made for people on the Dvorak keyboard layout 🎀⌨️

when you run it with no file name arguments, it shows you a short command introduction and summary, so you're never just staring at a blank screen 🌸

and the big flex: aoeui can browse very large read-only files with super quick start-up time 🚀 because the original texts are memory-mapped from the files and aren't duplicated in memory unless they're about to be modified. no cap, that's iconic 😭🔥

✨ OPTIONS ✨

• -k — kills the keyword highlighting 🙅‍♀️ (it's disabling keyword highlighting, bestie)
• -o — don't save the original contents of a modified file in file~ 🧚
• -r — read-only mode! the file on disk does not get modified 🔒
• -s — use spaces, not tabs, for automatic indentation, even if the file seems to currently use tabs 🌈
• -S — use tabs, not spaces, for automatic indentation, even if the file seems to currently use spaces 💜
• -t 8 — set the tab stop to 8 or to some unreasonable value 💀 this setting can be overridden on a per-text basis later 🍓
• -u — treat files as UTF-8 even if they contain invalid UTF-8 encodings 🫶
• -U — don't treat files as UTF-8 even if they look like it 🙈
• -w writability command — when an attempt is made to modify a read-only file, this command runs to try to put the file into a writable state ✨ inside it, the string %s gets replaced with the path name of the file. it's super useful for source code control systems, e.g. p4 edit %s 🎀

✨ INTENTIONALLY MISSING FEATURES ✨

okay this section is giving "we did this on purpose" energy 💅 aoeui has no embedded extension language, because it's trivial to pass regions of text from the editor to any program or script that can read standard input and write standard output. the shell, sed(1), awk(1), python(1), and perl(1) are all usable for that kind of scripting 🧚‍♀️ and since aoeui ships with full sources and the rights to modify it, users can customize it directly 👑

the editor has only basic syntax highlighting of C and C++ keywords, with subtle color cues that help match up parentheses, brackets, and braces 🌸

aoeui has no mail or news reader, no IRC client, and no artificial intelligence psychologist mode 💀🙈

there is no X window system interface, bestie. that's what xterm(1) and gnome-terminal(1) are for 🦋

✨ MODIFICATION ✨

okay so in the default mode, any characters you type without a command indicator just get inserted right at your cursor 💖. And this part is lowkey important: if your cursor is at the start of a selection, that selection gets cut to the clip buffer first, so your new text replaces it ✨.

• ^^ — (that's Control-Shift-6, the caret character, on most keyboards, and ^6 will probably also work) 🦋 this sneaks an otherwise untypeable control character into your text. The very next key you press gets taken literally if it's already a control character, or turned into one if it isn't, and then inserted. (Like, press ^^ and then hit Control-A or just a plain A, and you'll get character code 0x01 🫶.)
• ^Space^^ — with a numeric argument, probably in hexadecimal 🔥, this drops the specified Unicode character into the text in UTF-8 format. If the text isn't UTF-8, the character code gets inserted directly as a big-endian literal.
• Tab (or ^I) — tries tab completion first 💅, and if that flops, a TAB character gets inserted instead. If there's a selection with the cursor at its end, the editor hunts for an unambiguous continuation based on path names and words in all the views. Any continuation it finds gets appended to the selection, which makes opening a file with ^X way easier 📁. With no selection, but the cursor sitting right after one or more identifier characters, the editor searches for an unambiguous continuation using the words in the views. Any hit gets inserted as the new selection, with the cursor at its end. No tab completion happens when the cursor is at the beginning of a selection. In that case, the selection gets cut and replaced with a single TAB character.
• ^SpaceTab (or ^Space^I) — aligns the current line to the indentation of the previous one 🌸. With a numeric argument of 1, it toggles whether the text uses tab characters for indentation. With a numeric argument between 2 and 20, it sets the tab stop pitch.
• Enter (or ^M) — inserts a new line with no automatic indentation.
• ^J (or ^Enter under some good terminal emulators) — inserts a new line with automatic indentation ✨. If you hit ^J right after a { that doesn't have a closing } yet, it'll also add a properly-indented closing brace 🙈.
• Backspace (or more properly, its synonym ^? and sometimes, as in Mac OS X's Terminal application, ^/) — deletes the character right before the cursor.
• ^D — with no selection, deletes the character "under" the cursor. When a selection exists, ^D moves it into the clip buffer, discarding any previously clipped text 💅.
• ^Space^D — with no selection, selects the surrounding white space, as described earlier. When a selection exists, ^Space^D moves it into the clip buffer. It goes before any old text if the cursor was at its beginning, and gets appended if the cursor was at its end. The whole point is that multiple ^Space^D commands collect data together in the order you're most likely to have visited it 🧚.

A numeric argument to ^Space^D places the indicated number of copies of the selection into the clip buffer.

• ^F — requires a selection 💜. The selection gets copied into the clip buffer and then unmarked.
• ^Space^F — is to ^F what ^Space^D is to ^D 👑. It copies the selection to the clip buffer, putting it at the beginning or the end the same way ^Space^D does (see above). A numeric argument to ^Space^F places the indicated number of copies of the selection into the clip buffer.
• ^B — with no selection, pastes the current clip buffer's contents. But with a selection, it does something bigger: the contents of the selection and the clip buffer get exchanged 🔄. With a numeric argument, ^B pastes or exchanges with a numbered register, which is an alternate clip buffer. (The main clip buffer is the same as register 0.) Besides being a way to keep text around for longer stretches of editing, registers also help you pull out the text that matches a parenthesized subpattern in a regular expression search 🧠.

🔍 SEARCHING 🔍

• ^_ — and its synonyms ^/, ^-, and ^A all enter search mode 🔎. There are so many synonyms because they're often the same thing, or reserved key sequences, in the various window managers and the screen(1) utility.

(Specifically, ^/ gets mapped to ^_ by many X terminal emulators, while ^- gets mapped to ^_ by the Mac OS X Terminal application. ^A is the default escape sequence in screen(1).)

• ^Space^_ (and its synonyms) — the fancier version 🧐 searches for occurrences of POSIX regular expressions. Each non-command character you type after that gets appended to the current search target string, and the selection jumps to the next occurrence of it 🎯.

The case of alphabetic characters is not significant to the search 🔡.

Most command characters will automatically take the editor out of search mode before executing, and the most recently discovered occurrence of the search target string will become the selection ✨.

A few commands have different meanings in search mode 👀:

• Backspace — removes the last character from the search target and moves the selection back to its previous position.
• ^V — is typically used to leave search mode with the currently highlighted search target as the selection.
• ^_ (or its synonyms) — with no characters in the search target string, causes the last successful search's target string to be reused.
• ^H and ^T — cause motion to the previous and next occurrences of the search target string, not single-character motion.
• Enter (and ^_ and its synonyms) — simply leaves search mode with the cursor at the latest hit, and the mark returned to where it was before the search (if there was one) 🎀. This is useful for using search to place the bounds of a selection.

📄 TEXTS, VIEWS, and WINDOWS 📄

• ^K — saves all modified texts back to their files 💾.
• ^Space^K — saves just the current text.
• ^X — with no selection, inserts the path name of the current text as the new selection. With a selection containing a path name (possibly put together with the help of tab completion, see above), ^X raises up a window with a view into the indicated file. It creates a new text to hold it if one doesn't already exist 🪟.
• ^Space^X — with a selection, renames the current text so it gets saved in another file.
• ^W — finds an invisible view and associates it with the current window, making the current view invisible 👻. Hitting ^W repeatedly cycles through all of the views. If there was no invisible view, ^W creates a new scratch text, as does the ^Space; command down below.
• ^Space^W — does the same thing, but closes the window's current view, and also its text if it was the last view of that text 🙃.
• ^Y — splits the current window horizontally, raising up an invisible or new view in the lower half of the original window ⬇️.
• ^Space^Y — splits the current window vertically, raising up an invisible or new view in the right half of the original window ➡️.
• ^P — moves to another window 🏃.
• ^P with a numeric argument — moves to a specific window. Number 1 is in the upper left-hand corner of the display 📍.
• ^Space^P — moves to another window, closing the old one 👋.
• ^Space; (note that ; is not a control character) — creates a new anonymous text 🌈.
• ^Space# (note that the number sign is not a control character) — displays the current position's path name and line number 🔢.
• ^Space? (note that the question mark ? is not a control character) — displays a new window with the built-in help summary of commands 🆘.

🎀 MACROS 🎀

• ^Space^O — commences recording your keystrokes as the macro. The recording keeps going until the next ^O or another macro recording 🎬.
• ^SpaceF1-F12 — commences recording your keystrokes as a new macro for a function key 🎹.

Heads up, bestie 💀: F1 and F11 are typically hijacked by window managers for their own purposes, so they probably won't be usable.

• ^O — ends the recording of a macro, if one is in progress 🛑. Afterwards, ^O replays the macro, possibly with a repeat count as the argument ▶️.

Watch out 🙈: a failed search in a macro will terminate its execution.

🦋 FOLDING 🦋

aoeui supports the "folding" of portions of text into what appear to be single characters 🪄, and the reverse "unfolding" operation too. To give outline views of texts like heavily-indented source code, aoeui also has an automatic nested folding capability 🌳.

• ^Space, — with a selection, folds the selection. Otherwise, it repeatedly folds indented regions of the text to provide an outline view 🌿. A numeric value, if any, specifies the number of leading spaces or equivalent tabs at which code lines will be folded. The default is 1, which causes the folding of any line that isn't left-justified.
• ^Space. — with a selection, or immediately atop a folded section, unfolds the topmost foldings within it 🔓. Otherwise, and if there is a numeric value, it completely unfolds the entire view ✨.

✨ SHELLS ✨

Okay bestie, this is where aoeui gets wild 🔥. ^E with no selection just launches an interactive shell in a brand new scratch text 🐚. But with a selection? ^E runs the shell command in your selection, feeds it whatever's in the clip buffer as standard input (if anything's there) 🧠, and collects the output asynchronously in the background, then swaps it in to replace your selection 💅. So a bunch of super helpful UNIX text processing commands are literally at your fingertips 🫶. Some handy ones to know:

• cat(1) — to include another entire file, or to receive writes to a named pipe 🌸
• mkfifo(1) — to create a named pipe so commands in other windows can pipe their output into a text running cat in the background 🧚
• cd path — to change the editor's current working directory (a special case, since it's not actually passed to a shell) 📂
• grep(1) — to search for lines containing a pattern 🔍
• sort(1) — to rearrange lines alphabetically or numerically, possibly reversed 🔃
• uniq(1) — to discard duplicated lines 🗑️
• sed(1) — as in sed 's/FROM/TO/g' to perform unconditional search-and-replace with regular expressions 🪄
• tr(1) — to convert lower to upper case with a-z A-Z, and to remove DOS carriage returns with -d '[\r]' 🧹
• fmt(1) — to reformat paragraphs of natural language text 📝
• indent -st -kr -i8 -nbbo — to reformat C language source code sensibly 💻
• column -t — to realign data nicely into columns 📊
• man | colcrt — to read a man page 📖
• tail(1) — to monitor additions to a file, like a log 👀
• make(1) — to compile your code 🛠️
• aspell list | sort | uniq | column — to get a list of words that may be misspelled 🙈

And ^Space^E with no selection will terminate the output of any asynchronous child process that's still running 🛑.

---

✨ TIPS ✨

Okay, these tips are lowkey the best part 💖 Here we go:

• To select the rest of the line after the cursor, use ^V^C 🦋
• It is often faster to retype a bungled word than to fix it. Just use ^V^N and then retype 💅
• Transposing multiple blocks of text is easy with ^B. It basically takes the usual paste operation and turns it into an exchange of the clip buffer with the selection 🔄✨
• Incremental search and replacement can be done with a macro, or by clipping the replacement text. On search hits you want to replace, use ^V^B^F^/^/ to exchange the hit with the replacement text, copy it back to the clip buffer, and move on to the next occurrence of the search pattern 🧠. But when the replacement text is short, it's honestly easiest to just overwrite the selection by hitting ^V^D and immediately retyping the new text 💨
• Reconfigure your keyboards so that the key to the left of A (probably labeled Caps Lock) is interpreted as a Control modifier instead 🎀 This is a whole glow-up for your fingers 🫶
• The gnome-terminal(1) terminal emulator works well with aoeui if you configure the terminal's scrollback limit to a relatively small value 🌈
• To move backward or forward by half a screenful, use ^R or ^L and then ^Z. (Or set the environment variable AOEUI_OVERLAP to 50.) 🌊
• To insert characters with a repeat count, type the characters into a new selection, cut into the clip buffer with a repeat count using ^Space^D, and then paste with ^B 🍓

---

✨ BUGS ✨

Bugs? Bestie, they're inevitable 💀 Please tell me about any that you find 🫶

---

✨ ENVIRONMENT ✨

Okay, environment variables. Let's go 🌸

• SHELL — names the program that the ^E command runs 🐚
• ROWS and COLUMNS — may be set to override aoeui's automatic mechanisms for figuring out the size of the display surface 📐
• TERM — when set to a string beginning with xterm, makes aoeui use the title bar of the terminal emulator as a status indicator. It shows the path name of the active view and whether or not it's been saved since it was last modified 🪧 Unless the file is large, it also shows the line number of the cursor 🔢
• TERM_PROGRAM — if set to Apple_Terminal, makes aoeui work around Apple's Terminal emulator's behavioral differences from standard Xterm 🍎
• AOEUI_WRITABLE — the default command used when the -w option isn't given 💾
• AOEUI_OVERLAP — the percentage of overlap when scrolling a window up with ^R or down with ^L. The default is 1, for minimal overlap 🌀

---

✨ FILES ✨

Let's talk about the files aoeui leaves around 📁

• file~ — gets overwritten with the original contents of file unless the -o option is used 🫣
• file# — holds the temporary image of the edited file while aoeui is running. It may be useful for recovery if the editor gets killed 🚑
• TAGS — is found and read in by the ^Space' command to supply the tags that get scanned. The search for TAGS begins in the same directory as the current view's text, and proceeds up through its parents 🌳
• $HOME/.aoeui — holds any new "anonymous" texts created during editing sessions 🧚

---

✨ SEE ALSO ✨

Read these next, you won't regret it 🤓✨

asdfg(1), ctags(1), exuberant-ctags(1), regex(7)

Helpful commands to use with ^E: aspell(1), cat(1), colcrt(1), column(1), fmt(1), grep(1), indent(1), mkfifo(1), sed(1), sort(1), tailf(1), tr(1), uniq(1) 💜

---

✨ AUTHOR ✨

Peter Klausler <pmklausler@gmail.com> wrote aoeui 👑

---

💜 And that's the whole page, bestie! 💅 This is aoeui(1), dated November 27, 2012. Go forth and slay your editor 🦋✨