Provided by: aoeui_1.6~dfsg-2_amd64 bug

NAME

       asdfg - a lightweight visual editor optimized for the QWERTY keyboard

SYNOPSIS

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

DESCRIPTION

       asdfg  is  an  interactive  display text editor optimized for users of the QWERTY keyboard
       layout.

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

       asdfg  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.

       -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

       asdfg 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 asdfg 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.

       asdfg 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 asdfg.  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 ^R (below).  There is
       one clip buffer shared by all views.

COLOR CUES

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

       asdfg  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

       asdfg  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  ^W  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.

       ^G     moves the cursor backward by characters.

       ^H     moves the cursor forward by characters.

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

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

       ^K     moves the cursor backward by words.

       ^L     moves the cursor forward by words.

       ^Space^K
              moves the cursor backward one sentence.

       ^Space^L
              moves the cursor forward one sentence.

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

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

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

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

       ^O     moves the window backward by screenfulls.

       ^P     moves the window forward by screenfulls.

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

       ^Space^P
              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.

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

       ^Space^N
              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.

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

       ^Space^U
              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  ^Y^U^T  with  no  selection.  With a selection present, ^Space^U
              exchanges its cursor with its mark.

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

       ^Space^X
              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

       asdfg has infinite undo capabilities.

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

       ^Space^Z
              reverses the effects of the most recent undo.  After ^Z,  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 ^E.  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.

       ^X     with  no  selection  deletes  the  character  "under" the cursor.  When a selection
              exists, ^X moves it into the clip buffer, discarding any previously clipped text.

       ^Space^X
              with no selection will select surrounding white space, as described earlier.   When
              a  selection  exists, ^Space^X 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^X commands to collect
              data together in the same order in which they are most likely to have been visited.

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

       ^C     requires a selection, which is copied into the clip buffer and then unmarked.

       ^Space^C
              is  to  ^C  what  ^Space^X  is  to ^X.  It copies the selection to the clip buffer,
              putting it at the beginning or the end in the same  way  as  ^Space^X  (above).   A
              numeric argument to ^Space^C places the indicated number of copies of the selection
              into the clip buffer.

       ^V     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, ^V 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.

       ^U     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.

       ^G     and ^H 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

       ^W     saves all modified texts back to their files.

       ^Space^W
              saves just the current text.

       ^E     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),  ^E 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^E
              with a selection will rename the current text, so that it will be saved in  another
              file.

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

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

       ^D     splits  the current window horizontally, raising up an invisible or new view in the
              lower half of the original window.

       ^Space^D
              splits the current window vertically, raising up an invisible or new  view  in  the
              right half of the original window.

       ^S     moves to another window.

       ^S     with  a numeric argument moves to a specific window; number 1 is in the upper left-
              hand corner of the display.

       ^Space^S
              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  contral  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^B
              commences the recording of your keystrokes as the macro, which continues until  the
              next ^B 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.

       ^B     ends  the  recording of a macro, if one is in progress.  Afterwards, ^B replays the
              macro, possibly with a repeat count as the argument.  Note that a failed search  in
              a macro will terminate its execution.

FOLDING

       asdfg 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, asdfg 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

       ^R     with  no  selection will launch an interactive shell in a new scratch text.  With a
              selection, however, ^R 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

       tailf(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^R 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 ^U^Y

       *      It  is  often  faster  to retype a bungled word than to fix it, using ^U^K and then
              retyping.

       *      Transposing multiple blocks of text is easy with ^V, 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  ^U^V^C^/^/  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
              ^U^X 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 asdfg if you configure the
              terminal's scrollback limit to a relatively small value.

       *      To move backward or forward by half a screenfull, use ^O or ^P and  then  ^N.   (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^X, and then paste with ^V.

BUGS

       Inevitable; please tell me about any that you find.

ENVIRONMENT

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

       ROWS   and

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

       TERM   will,  when  set to a string beginning with xterm, cause asdfg 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 asdfg 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 ^O or down with ^P.  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 asdfg 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

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

       Helpful commands to use with ^R: 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 <pmk@google.com> wrote asdfg.

                                        February 15, 2009                                asdfg(1)