Provided by: aoeui_1.7+20160302.git4e5dee9-3_amd64 bug

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

       aoeui is an interactive display text editor optimized for users  of  the  Dvorak  keyboard
       layout.

       When  run  with  no  file  name arguments, aoeui displays a short command introduction and
       summary.

       aoeui can browse very large read-only files with quick start-up time, since  the  original
       texts  are  memory-mapped from files and not duplicated in memory unless they are about to
       be modified.

OPTIONS

       -k     Disable keyword highlighting.

       -o     Do not save the original contents of a modified file in file~.

       -r     Read-only mode: do not modify the file on disk.

       -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, use this command (within which
              the string %s will be replaced with the path name of the file) to  attempt  to  put
              the  file  into  a writable state.  This is useful for interacting with source code
              control systems (e.g., p4 edit %s).

INTENTIONALLY MISSING FEATURES

       aoeui has no embedded extension language, since it is 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  such
       scripting.   Further,  since  aoeui  ships  will 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, IRC client, or artificial intelligence psychologist
       mode.

       There is no X window system interface; that's what xterm(1) and gnome-terminal(1) are used
       for.

BASICS

       A  text  is a sequence of characters to be viewed or edited, such as a file.  If it is not
       ASCII, the editor will automatically determine whether it is encoded in legal UTF-8 and do
       the right thing.  The editor can also automatically detect DOS-style line endings.

       A  view  comprises all or part of a text.  A text in the editor has at least one view, and
       possibly more.

       A window is a rectangular portion of the display, and is always associated with  a  single
       view,  a contiguous portion of whose text is rendered in the window.  Not every view has a
       window.

       Each view has a cursor and possibly a selection, which has the cursor at one end  and  the
       mark  at the other.  The view's window, if any, always renders part of the text containing
       the view's cursor.

       The selection plays a critical role in aoeui.  Besides highlighting regions to be  cut  or
       copied,  it  also  serves to supply arguments to some commands, such as the path name of a
       file to open.

       The clip buffer is not visible in any window.  It receives snippets of data that have been
       cut  or  copied  out  of  texts,  so  that they may be moved or copied elsewhere.  It also
       supplies the standard input to a background command launched with ^E  (below).   There  is
       one clip buffer shared by all views.

COLOR CUES

       aoeui  uses  colors to convey information without cluttering the display with status lines
       or borders between windows.

       aoeui uses distinct background colors to distinguish tiled windows.  The active window  is
       always  presented in the terminal's default color scheme.  Color is also used to highlight
       the current selection (in cyan) and folded regions (in red).

       Needless tabs and spaces are marked in violet.  These include any tabs  or  spaces  before
       the  end  of a line, as well as any spaces followed by a tab or multiple spaces that could
       be replaced by a tab.

       Bracketing characters are presented in alternating colors so  that  matching  parentheses,
       brackets, and braces are colored identically.

       A  red  cursor  signifies  a read-only text, whereas a green cursor indicates a dirty text
       (meaning one that needs saving, not one unfit for young persons).

COMMANDS

       aoeui understands the arrow, page up and down, and Delete keys on your  keyboard,  so  you
       can  actually  just use it like a dumb notepad with no mouse if you don't want to read any
       further than the next section, which tells you how to leave the editor.

       In the following sections of the manual, commands are denoted by ^key to signify  the  use
       of Control, Alt, or a preceding Escape key.  They all mean the same thing.

       Variant  commands  always  begin  with  ^Space, or its synonym, ^@.  A few commands take a
       numeric argument, which is specified by  ^Space  followed  by  a  decimal  or  hexadecimal
       number, the latter using C language syntax (0xdeadbeef).

       Many commands are sensitive to the presence or absence of a selection.

LEAVING

       ^Space^\
              aborts  the  editor,  leaving  no original file modified since the last time ^K was
              used.

       ^Q     suspends the editor and returns the terminal to the shell that invoked it.  Use the
              shell's foreground command, probably fg, to resume editing.

       ^Space^Q
              saves all modified texts and terminates the editor.

NAVIGATION

       The  "backward and forward by unit" commands treat a numeric argument, if any, as a repeat
       count.

       ^H     moves the cursor backward by characters.

       ^T     moves the cursor forward by characters.

       ^Space^H
              moves the cursor up a line on the screen.

       ^Space^T
              moves the cursor down a line on the screen.

       ^N     moves the cursor backward by words.

       ^S     moves the cursor forward by words.

       ^Space^N
              moves the cursor backward one sentence.

       ^Space^S
              moves the cursor forward one sentence.

       ^G     moves the cursor back to the beginning of the line.  If  already  there,  it  moves
              back to the beginning of the previous line.

       ^C     moves  the  cursor  forward  to  the  end  of the line.  If already there, it moves
              forward to the end of the next line.

       ^Space^G
              moves the cursor back to the beginning of the  paragraph.   If  already  there,  it
              moves back to the beginning of the previous paragraph.

       ^Space^C
              moves  the  cursor forward to the end of the paragraph.  If already there, it moves
              forward to the end of the next paragraph.

       ^R     moves the window backward by screenfulls.

       ^L     moves the window forward by screenfulls.

       ^Space^R
              moves to the very beginning of the view.

       ^Space^L
              moves to the very end of the view.

       ^]     moves to the corresponding parenthesis, bracket, or brace, respecting  nesting,  if
              the  cursor  sits  atop  such  a  character.   Otherwise,  it  moves to the nearest
              enclosing bracketing character.

       ^Z     recenters the window so that the line containing the cursor lies in the  middle  of
              its portion of the display.

       ^Space^Z
              causes  the  current  window to occupy the entire display and recenters the window.
              With a numeric argument, however, it simply moves the cursor to the indicated  line
              in the view, with 1 being the number of the first line.

       ^Space=
              (note  that  = is not a control character) sets a bookmark on the current selection
              or cursor position.  A numeric argument may be used to manage multiple bookmarks.

       ^Space-
              (note that - is not a control character) returns  to  a  previously  set  bookmark,
              possibly identified with a numeric argument.

       ^Space'
              (note  that  the  single quote ' is not a control character) looks an identifier up
              the identifier in the TAGS files, which are sought in the  same  directory  as  the
              current  view  and  then  all  of its parents, until one is found that contains the
              identifier.  A new little window is opened for each of the identifier's entries  in
              the TAGS file.

       The  TAGS  files should be generated with the ctags or exuberant-ctags utilities and their
       -x output format.  If there is a selection, it is deleted from the  view  and  its  entire
       contents will constitute the identifier to be looked up; otherwise, the identifier that is
       immediately before or around the cursor is sought.

SELECTION

       These commands are sensitive to the presence or absence of a current selection.

       ^V     begins a new selection if non exists, setting its mark at the current cursor, which
              is  then  typically  navigated  to  its  intended other end.  ^V in the presence of
              selection simply removes the mark.

       ^Space^V
              without a selection causes the entire current line to be selected  by  placing  the
              mark at the end of the line and the cursor at its beginning.  It is the same as the
              command sequence ^C^V^G with no selection.   With  a  selection  present,  ^Space^V
              exchanges its cursor with its mark.

       Note  that  ^Space^V with a numeric argument unconditionally unsets the mark, which can be
       handy in a macro.

       ^Space^D
              with no selection causes all of the contiguous white space  characters  surrounding
              the  cursor  to  be  selected, with the cursor at the beginning so that they can be
              easily replaced by retyping.

UNDO

       aoeui has infinite undo capabilities.

       ^U     reverses the effects of the last command, apart from ^U itself, that  modified  the
              current text in any of its views.

       ^Space^U
              reverses  the  effects  of  the most recent undo.  After ^U, any other command that
              modifies the text will permanently commit the undo(s).

MODIFICATION

       In the default mode, characters typed without a command  indicator  are  inserted  at  the
       current  cursor  position.  Further, if the cursor is at the beginning of a selection, the
       selection is first cut to the clip buffer, so that the new text replaces it.

       ^^     (that's Control-Shift-6, the caret  character,  on  most  keyboards,  and  ^6  will
              probably  also  work)  inserts  an  otherwise untypeable control character into the
              text.  The very next key to be pressed is  either  taken  literally,  if  it  is  a
              control  character, or converted to a control character if it is not, and inserted.
              (For example, you can press ^^ and then hit either Control-A or just a plain A,  to
              get the character code 0x01 inserted.)

       ^Space^^
              with  a  numeric  argument,  probably in hexadecimal, inserts the specified Unicode
              character into the text in UTF-8 format.  If the text is not UTF-8,  the  character
              code is inserted directly as a big-endian literal.

       Tab    (or  ^I)  attempts  to  perform  tab  completion; if that fails, a TAB character is
              inserted.  If there is a selection with the cursor at its end, the editor tries  to
              find an unambiguous continuation based on path names and words in all the views.  A
              continuation, if found, is appended to the selection, to facilitate opening a  file
              with  ^X.   With  no  selection,  but  the  cursor  immediately  after  one or more
              identifier characters, the editor searches for an  unambiguous  continuation  using
              the words in the views.  A continuation, if found, is inserted as the new selection
              with the cursor at its end.  No tab completion occurs when the  cursor  is  at  the
              beginning  of  a  selection; in that case, the selection is cut and replaced with a
              single TAB character.

       ^SpaceTab
              (or ^Space^I) will align the current line to the indentation of the  previous  one.
              With  a  numeric  argument  of  1,  it toggles the text's use of tab characters for
              indentation.  With a numeric argument between 2 and 20, it will set  the  tab  stop
              pitch.

       Enter  (or ^M) inserts a new line into the text without automatic indentation.

       ^J     (or  ^Enter  under  some  good terminal emulators) inserts a new line into the text
              with automatic indentation.  If ^J is executed immediately after a { character that
              does not yet have a closing }, ^J will 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 immediately 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 will select surrounding white space, as described earlier.  When
              a selection exists, ^Space^D moves it into the clip buffer, putting it  before  any
              old  text if the cursor was at its beginning and appending it to the clip buffer if
              the cursor was at its end.  The intent is for multiple ^Space^D commands to collect
              data together in the same order in which they are most likely to have been visited.

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

       ^F     requires a selection, which is 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 in the same way as ^Space^D (above).  A
              numeric argument to ^Space^F places the indicated number of copies of the selection
              into the clip buffer.

       ^B     with  no  selection  will  paste  the  current  clip buffer's contents.  But in the
              presence of a selection it performs a more general function: the  contents  of  the
              selection and the clip buffer are 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 means for preserving some
              text for longer periods of editing,  the  registers  also  serve  as  a  means  for
              extracting the text that matches a parenthesized subpattern in a regular expression
              search.

SEARCHING

       ^_     and its synonyms ^/, ^-, and ^A enter search mode.  The many synonyms  are  defined
              because  they're  often  synonymous 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).)

       The  variant  version of this command (^Space^_ and its synonyms) searches for occurrences
       of POSIX regular expressions.  Each non-command character that is typed thereafter will be
       appended  to  the  current  search  target  string  and the selection is moved to the next
       occurrence thereof.

       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 be
       its selection.

       A few commands have different meanings in search mode:

       Backspace
              will remove the last character from the search target and move 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  will  cause  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,  with the mark returned to where it was before the search (if anywhere).  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, as the new selection, the path name of the current text.
              With  a  selection containing a path name, possibly constructed with the assistance
              of tab completion (above), ^X will raise up a window containing  a  view  into  the
              indicated file, creating a new text to hold it if one does not already exist.

       ^Space^X
              with  a selection will rename the current text, so that it will be saved in another
              file.

       ^W     finds an invisible view and associates it  with  the  current  window,  making  its
              current view invisible.  Hitting ^W repeatedly will cycle through all of the views.
              If there was no invisible view, ^W creates a new  scratch  text,  as  does  ^Space;
              below.

       ^Space^W
              does the same thing. but will close the window's current view, and also its text if
              it was the last view thereof.

       ^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
              positions 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  the recording of your keystrokes as the macro, which continues until the
              next ^O or another macro recording.

       ^SpaceF1-F12
              commences the recording of your keystrokes as a new macro for a function key.  Note
              that  F1  and  F11 are typically hijacked by window managers for their own purposes
              and probably will not 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.  Note that 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.  Further, to provide outline views of texts such as
       source code that are heavily indented, aoeui has an automatic nested folding capability.

       ^Space,
              with a selection will fold the  selection.   Otherwise,  it  will  repeatedly  fold
              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, causing the folding of any line that isn't left-
              justified.

       ^Space.
              with a selection, or immediately atop a folded section,  will  unfold  the  topmost
              foldings within it.  Otherwise, and if there is a numeric value, it will completely
              unfold the entire view.

SHELLS

       ^E     with no selection will launch an interactive shell in a new scratch text.   With  a
              selection,  however,  ^E  will  execute the shell command in the selection with the
              contents of the clip buffer, if any, as its standard input, and collect its  output
              asynchronously  in  the  background  to  replace  the  selection.  This allows many
              helpful UNIX text processing commands to be used directly.  Some handy commands  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 that commands in other windows may direct their output
              into a text running cat in the background.

       cd path
              to change the editor's current working directory (a special case  command  that  is
              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 such as a log

       make(1)
              to compile your code

       aspell list | sort | uniq | column
              to get a list of words that may be misspelled

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

TIPS

       *      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,  using  ^V^N  and  then
              retyping.

       *      Transposing  multiple  blocks  of text is easy with ^B, which generalized the usual
              paste operation 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,  and on search hits that are to be replaced, using ^V^B^F^/^/ to
              exchange the hit with the replacement text, copy it back to the  clip  buffer,  and
              proceed  to  the  next  occurrence of the search pattern.  But when the replacement
              text is short, it's sometimes 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, which is probably
              labeled Caps Lock, is interpreted as a Control modifier instead.

       *      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 screenfull, 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 with ^Space^D, and then paste with ^B.

BUGS

       Inevitable; please tell me about any that you find.

ENVIRONMENT

       SHELL  is used to name the program run by the ^E command.

       ROWS   and

       COLUMNS
              may be set to override aoeui's automatic mechanisms for determining the size of the
              display surface.

       TERM   will, when set to a string beginning with xterm, cause aoeui use the title  bar  of
              the  terminal  emulator  as  a  status indicator that displays the path name of the
              active view and whether or not it has been saved since last modified.   Unless  the
              file is large, it also displays the line number of the cursor.

       TERM_PROGRAM
              will,  if set to Apple_Terminal, make aoeui work around Apple's Terminal emulator's
              behavioral differences from standard Xterm.

       AOEUI_WRITABLE
              Default command used in the absence of the -w option.

       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

       file~  is overwritten with the original contents of file unless the -o option is used.

       file#  contains  the temporary image of the edited file while aoeui is running, and may be
              useful in recovery if the editor is killed.

       TAGS   is found and read in by the ^Space' command to supply the tags  that  are  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

       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.

                                        November 27, 2012                                aoeui(1)