ait/ait.1

.TH AIT "1" "October 2023" "ait 1.5" "General Commands Manual\fR

.SH NAME
.B ait
\- small yet mighty GNU Emacs style editor
.SH SYNOPSIS
.B ait
.B [-vh]
[\fI\,file\/\fR [+/-\fI\,number\/\fR] ...]
.br
.SH DESCRIPTION
.B ait
is intended to be small, portable, and powerful Emacs-like text editor. While
those are the top 3 main goals,
.B ait
also is intended to be simple in both implemetation and use, support the most
important GNU Emacs keybindings, support UTF8 and unicode, to not reinvent
the wheel, and to not suck. You will find many differences between GNU Emacs
and
.B ait
as
.B ait
is
.I not
intended to be an Emacs clone. Some of the most prominent differences are:
the lacks of a config, of lisp, of 100% custom window layouts, of major syntax
highlighting, and of modes in general.
.B ait
instead is simple enough that you can change the source to change the
keybindings, uses the existing system as the extension language (see
\fBSHELL COMMANDS\fR), uses a simple static-window system that works for 99% of all editing
purposes, and supports the bare-minimum syntax highlighting (see
\fBSYNTAX HIGHLIGHTING\fR). Think of
.B ait
as a microEMACS implementation of GNU Emacs with concepts from Plan 9's acme
editor.

.TP
The options are as follows:
.TP
\fB+/- number\fR
Go to the line specified by number (do not insert a space between the '+' or '-'
sign and the number).  If a negative number is specified, the line number counts
backwards from the end of the file i.e. -1 will be the last line of the file,
-2 will be second last, and so on.
.TP
\fB-v\fR
Print version and exit
.TP
\fB-h\fR
Print help and exit
.TP
.SH POINT & MARK
.B ait
is written using a gap buffer and therefore some of the lingo used to describe
various behaviors come from this. The
.I point
is the location of the cursor in the buffer. The
.I mark
is a point that is set by the user to define either the beginning or end of the
\fIregion\fR.
The region is used for a variety of functions such as cut, copy, and
shell-command. The point and mark are both buffer specific.

There are some note-worthy special cases that may confuse users at first.
Firstly, column-memory. If you haven't explicitly changed the current
column using something fwd-word, back-char, etc.
.B ait
will remember which column you're on. This makes editing things that are
in the same column but seperated by short lines a lot easier. Secondly,
brack-matching is supported for all heterogeneous bracket types (), {}, <>,
and []. It is not supported for homogeneous ones ("", '', ``). You can, however,
still use forward-bracket and backward-bracket to jump to them. Thirdly,
regarding the forward/backward-bracket functions, if there is a mark they will
overshoot to allow you to select the entire enclosed text and its brackets.
For example, if you have the code (+ 1 2) and the point is on ( and you place
a mark there and run forward-bracket, the point will actually go one character
to the right of the), effectively allow you to kill that entire block of code.
If the point were on the ) and you place a mark there and run backward-bracket,
the mark will be moved one character to the right of the ) and then the point
moved to the (. The two previous cases only work when the point is on the
bracket and not next to it like in GNU Emacs.

.SH WINDOWS AND BUFFERS
When a file is loaded into
\fBait\fR, it is stored in a \fIbuffer\fR. This buffer may be displayed on the
screen in more than one \fIwindow\fR. Each window is delineated by a
.I modeline
at the bottom. The modeline contains important information about the buffer
inside the window. The second position in the modeline will contain an "O" if
that buffer is in overwrite mode. If changes are made to a buffer, you will see
an asterisk in the third position of that buffer's window's modeline. If a file
is changed outside
.B ait
and its buffer is about to be changed,
.B ait
prompts if the change should go ahead (y), not go ahead (n) or if the buffer
should be reverted (r) to the latest file on disk. The default buffer is called
.I *scratch*
and is not saved when you close the program. In the modeline you will also find
the buffer name. This name is usually the same as the file's name unless there
is another buffer loaded with the same file name. In that case, the buffer name
will contain the directory name in the name i.e. dir/foo.txt. The file name
usually contains the entire path to that file and is seen when you save the
buffer. Next in the modeline is the row and column inside of parenthesis.
Lastly, there is the percentage of the buffer you're viewing. If you're at the
top and you can't page up anymore, you'll see TOP. If you can't page down
anymore you'll see BOT. Otherwise, you'll see the percent.

Unlike GNU Emacs,
.B ait
doesn't allow the user to make endless window configurations. There are only 8
supported window modes: one, horizontal, vertical, triple horizontal, triple
vertical, Fibonacci right, Fibonacci left, and quad. Horizontal and vertical
mode are 2 window splits in the respective direction. The triple modes are
the same as the previous just with 3 windows. Fibonacci modes are modes that
have 2 small windows that make up the height of the third large window. It is
called this because it resembles the first 3 squares in the Fibonacci sequence.
Lastly, quad mode is a 4 window mode with 4 windows, one in each quadrant. Also
unlike GNU Emacs, close-window doesn't exist. You can only change window modes
and so the keybinding C-x 0 will take you back to one window mode. When you
change modes
.B ait
will attempt to fill the windows by following the buffer trail (explained in the
next parapgraph). This isn't always right but is extremely handy.

The order of buffers and windows is not handled by any array or list. They are
handled by pointers that point to other pointers, thus creating a "trail" of
sorts. The buffer trail is the path to the order of the open buffers i.e.
current-buffer(foo.txt->b_next(bar.txt)->b_next(README)->b_next(NULL). The
list must always end with NULL.

.SH MSGLINE
Under all windows and modlines is the prompt area, namely, the \fImsgline\fR.
This is where all non-editing input is handled. Unlike GNU Emacs, the msgline
is not a buffer but a special place for messages and prompts. In most prompts,
most of the basic movement keybindings are usable: backward-char, forward-char,
back-word, fwd-word, delete, backspace, kill-line, beginning-of-line,
end-of-line, back-word-delete, and fwd-word-delete.

.SH SPECIAL CHARACTERS
There are some unique special things that you may seen while using
.B ait
that may spark a question. First, a tab character is denoted by a 4 space
line red UTF-8 character. This makes it easy to see whether spaces or actual
tabs are being used. Second, if control characters make it into the file they
are denoted, as GNU Emacs does, by a ^ followed by the letter that corresponds
to that control character in red foreground cololr. For example, the form feed
control character (ASCII 0x0C) would show up as ^L because 0x4C is an L in
ASCII. Third, trailing whitespace is denoted by a red background color but only
shows when you are not at the end of the trailing space. Fourth, completely
empty lines that contain no buffer data are denoted by a cyan tilde (~)
similarly to how
.B vi(1)
does it. This makes it easy to see when you're at the bottom of the file
visually. Alternatively one could use the modeline BOT string to obtain
the same conclusion.

.SH KEYBINDINGS
Keybindings in
.B ait
are written similarly to other Emacs clones. "C" means control and "M" means
meta. Therefore, "C-x" means control plus the x key and "M-x" means meta/alt plus
the x key. Since
.B ait
is usable on pretty much any terminal, it was selected to use esc instead of "M" to
describe meta. Therefore, "esc x" means the same as "M-x". The below list has
the keybinding in bold, followed by the common name for the function that the
keybinding runs, followed by a description on how that function works.
.TP
\fBC-a\fR
beginning-of-line, move the point to the beginning of the line.
.TP
\fBC-b / left\fR
backward-char, move the point to the left by 1 character.
.TP
\fBC-d / delete\fR
delete, delete the character that the point is currently pointing to.
.TP
\fBC-e\fR
end-of-line, move the point to the end of the line.
.TP
\fBC-f / right\fR
foward-char, move the point to the right by 1 character.
.TP
\fBC-h / backspace\fR
backspace, delete the character directly to the left of the point.
.TP
\fBC-i\fR
indent, insert 2 spaces.
.TP
\fBC-k\fR
kill-to-eol, cut from the point to the end of the line.
.TP
\fBC-l\fR
recenter, jump the page from top, middle, and end of the window following this
cycle: middle, top, end, repeat.
.TP
\fBC-x u / C-/\fR
undo, unlimited linear undo. See
.B UNDO & REDO
for more information.
.TP
\fBC-n / down\fR
next-line, move the point down by 1 line.
.TP
\fBC-m / enter\fR
newline, insert a newline character at the point.
.TP
\fBC-p / up\fR
previous-line, moved the point up by 1 line.
.TP
\fBC-r\fR
reverse-isearch, prompt the user for a search query and search start at the
point going up. See the section
.B ISEARCH
for more information.
.TP
\fBC-o\fR
newline-below, insert a newline character at the end of the current line.
.TP
\fBC-s\fR
reverse-isearch, prompt the user for a search query and search start at the
point going down. See the section
.B ISEARCH
for more information.
.TP
\fBC-t\fR
transpose, flip the position of the character at the point with the character
directly to the left of it.
.TP
\fBC-u\fR
universal-argument, at the moment all this does is run certain commands
4^(number of C-u presses) times. In Emacs, universal-argument does much more
and
.B ait
does have a framework to do more with it but isn't fully implemented due to lack
of necessity.
.TP
\fBC-v / pagedown\fR
forward-page, move the page by one full page down.
.TP
\fBC-w / esc k\fR
kill-region, cut the region. See
.B POINT AND MARK
for more information.
.TP
\fBC-y\fR
yank, insert the scrap at the point. See
.B POINT AND MARK
for more information.
.TP
\fBC-z\fR
suspend, suspend
.B ait
.
.TP
\fBC-space / esc @\fR
set-mark, set the point as the current mark.
.TP
\fBC-g / C-x C-g\fR
remove-mark, remove the current mark. C-g is also used to quit any command
in
.B ait
.
.TP
\fBC-x 0 / C-x 1\fR
delete-other-window, return to one window mode.
.TP
\fBC-x 2\fR
split-window, split into horizontal window mode.
.TP
\fBC-x 3\fR
chop-window, split into vertical window mode.
.TP
\fBC-x 4\fR
tri-split, split into triple horizontal window mode.
.TP
\fBC-x 5\fR
tri-chop, split into triple vertical window mode.
.TP
\fBC-x 6\fR
fib-right, split into Fibonacci right mode.
.TP
\fBC-x 7\fR
fib-left, split into Fibonacci left mode.
.TP
\fBC-x 8\fR
quad-window, split into quad window mode.
.TP
\fBC-x o\fR
other-window, jump cursor to the next window in the window trail. See
.B WINDOWS AND BUFFERS
for more information.
.TP
\fBC-x =\fR
cursor-position, print information on current cusor location to the msgline.
.TP
\fBC-x i\fR
insert-file, insert a file into the current buffer.
.TP
\fBC-x k\fR
kill-buffer, kill the current buffer. If unsaved, prompt to save.
.TP
\fBC-x C-n / C-x n\fR
next-buffer, switch to the next buffer in the buffer trail. See
.B WINDOWS AND BUFFERS
for more information.
.TP
\fBC-x l\fR
last-buffer, switch to the last buffer you previous had as the current.
.TP
\fBC-x b\fR
switch-to-buffer, prompt the user to select which buffer they'd like to switch to.
.TP
\fBC-x (\fR
start-kbd-macro, begin a keyboard macro.
.TP
\fBC-x )\fR
end-kbd-macro, end a keyboard macro.
.TP
\fBC-x e\fR
run-kbd-macro, execute a keyboard macro.
.TP
\fBC-x C-f\fR
find-file, prompt the user to select a file to open.
.TP
\fBC-x C-s\fR
save-buffer, save the current buffer to disk.
.TP
\fBC-x C-w\fR
write-file, save the current buffer to a new file.
.TP
\fBC-x C-c\fR
exit, quit
.B ait
.
.TP
\fBC-x C-x\fR
pop-to-mark, jump point to the previous mark point.
.TP
\fBesc 0\fR
numeric-arg-0, see
.B NUMERIC ARGUMENT
for more information.
.TP
\fBesc 1\fR
numeric-arg-1, see
.B NUMERIC ARGUMENT
for more information.
.TP
\fBesc 2\fR
numeric-arg-2, see
.B NUMERIC ARGUMENT
for more information.
.TP
\fBesc 3\fR
numeric-arg-3, see
.B NUMERIC ARGUMENT
for more information.
.TP
\fBesc 4\fR
numeric-arg-4, see
.B NUMERIC ARGUMENT
for more information.
.TP
\fBesc 5\fR
numeric-arg-5, see
.B NUMERIC ARGUMENT
for more information.
.TP
\fBesc 6\fR
numeric-arg-6, see
.B NUMERIC ARGUMENT
for more information.
.TP
\fBesc 7\fR
numeric-arg-7, see
.B NUMERIC ARGUMENT
for more information.
.TP
\fBesc 8\fR
numeric-arg-8, see
.B NUMERIC ARGUMENT
for more information.
.TP
\fBesc 9\fR
numeric-arg-9, see
.B NUMERIC ARGUMENT
for more information.
.TP
\fBesc b\fR
back-word, move point to the left by one word.
.TP
\fBesc bksp\fR
back-word-delete, delete one word to the left.
.TP
\fBesc f\fR
fwd-word, move point to the right by one word.
.TP
\fBesc d\fR
fwd-word-delete, delete one word to the right.
.TP
\fBesc x\fR
execute-shell-cmd, execute a shell command. See
.B SHELL COMMANDS
for more information.
.TP
\fBesc g\fR
gotoline, prompt the user to select which line to jump to.
.TP
\fBesc i\fR
indent, insert a tab character at the point.
.TP
\fBesc m\fR
back-to-indentation, jump point to the next non-whitespace character.
.TP
\fBesc n\fR
negate, set the negate flag. This isn't used much and almost no commands use it.
I've found it more valuable to have custom keybindings to run commands in
reverse.
.TP
\fBesc o\fR
open-shell-cmd, execute a shell command to open a new buffer. See
.B SHELL COMMANDS
for more information.
.TP
\fBesc %\fR
query-replace, prompt the user to replace something in the buffer. See
.B QUERY REPLACE
for more information.
.TP
\fBesc v / pageup\fR
backward-page, move the page by one full page up.
.TP
\fBesc w\fR
copy-region, copy the region. See
.B POINT AND MARK
for more information.
.TP
\fBesc < / home\fR
beg-of-buf, set point to the beginning of the buffer.
.TP
\fBesc > / end\fR
end-of-buf, set point to the end of the buffer.
.TP
\fBesc \\\fR
delete-whitespace, delete all whitespace to the rigth and left of the point.
.TP
\fBesc /\fR
redo, redo an undo. You an redo as many undos as there are. See
.B UNDO & REDO
for more information.
.TP
\fBesc t\fR
transpose word, flip the word the point is currently in the the word to the left.
.TP
\fBesc l\fR
lowercase-word, make the next word (starting at the point) lowercase.
.TP
\fBesc c\fR
capitalize-word, capitalize the next word (starting at the point).
.TP
\fBesc u\fR
uppercase-word, make the next word (starting at the point) uppercase.
.TP
\fBesc ;\fR
jump-to-char, prompt the user to select a character to the right of the point
to jump the point to.
.TP
\fBesc :\fR
negated-jump-to-char, prompt the user to select a character to the left of the
point to jump the point to.
.TP
\fBesc z\fR
zap-to-char, delete all characters to the right until the point reaches the
insert character.
.TP
\fBesc Z\fR
negated-zap-to-char, delete all characters to the left until the point reaches the
insert character.
.TP
\fBinsert\fR
toggle-overwrite-mode, toggle between insert and overwrite mode.
.TP
\fBC-M-f\fR
foward-bracket, jump the point to the match of the bracket at the
point going to the right.
.TP
\fBC-M-b\fR
backward-bracket, jump the point to the match of the bracket at the
point going to the left.
.TP
.SH ISEARCH
isearch stands for incremental search and is the normal way to search for
something in a buffer. isearch has two modes: isearch and isearch-reverse.
isearch goes down the buffer and reverse goes up. It is paramount that you
understand how the prompt for isearch works to use it to it's best ability.
While in the isearch function is running, you have a few keybindings at your
disposal other than the normal msgline keybinds:
.TP
\fBesc / C-g\fR
Quit. This will take you back to the original start point.
.TP
\fBC-s\fR
Jump to next match. If in isearch-reverse, switch to isearch.
.TP
\fBC-r\fR
Jump to next match. If in isearch, switch to isearch-reverse.
.TP
\fBenter\fR
Accept match, quit isearch, and stay at that point.
.TP
.PP
Once you've reached a point where there are no more matches, pressing the
respective keybind (C-s in isearch, C-r in isearch-reverse) will continue the
search from the beginning or end of the buffer respectively. Lastly, if you type
an all lowercase query it will search for matches
\fIregardless of case;\fP meaning that it searches with case insensitivity.
If you put any uppercase letter into the query, the search now becomes case
sensitive.
.SH UNDO & REDO
It's not overtly obvious when a undo set happens, the explanation is quick. An
undo set happens whenever you break a chain of similar commands - if you are
typing a big paragraph but don't manually move the cursor, delete
anything, or run any other commands you'll find the undo will remove that entire
paragraph. This is because you haven't broken the chain of commands. A redo
only becomes available once you've undone something.
.SH NUMERICAL ARGUMENT
Numerical argument is a way to run a keybinding many times. It is most useful
when used in combination with keyboard macros but can also be nice when doing
normal editting as well. When you begin entering a numeric argument you'll see
"C-u x", where x is the number you've added, in the msgline. Upon entering the
next number you will find that it doesn't add to the original number but rather
shifts the original number into the next most significant digit. This makes it
very easy to do massive recurring edits.
.SH QUERY REPLACE
The query-replace function is useful to replace multiple occurances of something
with another something. This function is very straightforward on how to use so
an explanation isn't needed. Once in the search, 'y' will accept the replace,
replace the query with the replacement, and move to the next match; 'n' will
skip the current match, '!' will accept all occurances without asking, and 'q'
will quit. You may also use C-g to quit before you get to searching part or
C-g and enter in the searching part.
.SH SHELL COMMANDS
One of the most powerful features in
.B ait
is the support to open files using custom commands and running shell commands.
When running a shell command (esc x) there are 2 types: input and replace. Input
happens when you have no region and you want to input the output of a command.
One of the best uses of this is with xclip(1) or pbpaste(1) (on macOS) allowing
you to paste in the editor. Replace happens when there is a region. In a region
command the region is passed into the shell command and the output of that command,
unless empty (just contains a null terminator or newline), is then placed where
the region was. One of the best uses of this is a spell checker.
.B ait
ships with an example script called "spell" that uses this technique, however,
it requires pick(1) and aspell(1) to be installed.
Open command is very straightforward, use anything you want to find the file you
want to open and make a script that returns just the file and path.
.B ait
ships with a few examples of this "ff" (find file) and "gg" (git grep) which
both require pick(1) and git(1) to be installed.
There may, in the future, be a way to have commands that don't effect the buffer
or commands that effect the entire buffer added in later version.
.SH SYNTAX HIGHLIGHTING
.B ait
lacks good syntax highlighting because it's not really needed. However, it is
helpful to have something to help differentiate when something is in a string
or a comment - which is the only syntax highlighting that
.B ait
supports. This feature is file extension dependent and must be added directly
into the source (buffer.c). The structure allows you to specify the file
extension, a single line comment, multi-line comment start (NULL if there
isn't any), multi-line comment end (NULL if there isn't any), if a single
quote is a string, and if a backquote is a string.
.SH BACKUP FILES
Backup files usually end in ~ and are, by default, sent to $HOME/.backups. These
backups contain the entire path with the slashes replaced with exclamation
points i.e. /home/foobar/foo.txt -> !home!foobar!foo.txt. You can optionally
have backup files be put in the directory where that file is located by setting
the BACKUP_DIR definition to NULL.

Backups are created right before the buffer is written to disk. They contain the
file's contents before it is overwritten.
.SH AUTHOR
.B ait
is a fork of an editor called atto. Atto was a fork of an editor called AE.
From Atto's README: "Atto is based on the public domain code of Anthony Howe's
editor (commonly known as Anthony's Editor or AE, [2])..."
That being said, parts of
.B ait
are written by all three of us: Anthony Howe,
Hugh Barney, and Kevin Bloom.

Kevin Bloom is the current maintainer.
.SH KNOWN ISSUES
You may view and track issues here: https://notabug.org/nuclearkev/ait/issues.

UTF-8 and unicode works for the most part but they are seen as "second-class
citizens" due to the fact that most programming and general text editting is
done with ACSII or ISO646-US or whatever. If you view open `docs/UTF-8.txt`
with
.B ait
you'll see that most of it is fine but lines 123-130 are messed up a little.

.SH "REPORTING BUGS"
Report bugs to https://notabug.org/nuclearkev/ait/issues
.SH COPYRIGHT
Public Domain 1991, 1993 by Anthony Howe.  No warranty.

Public Domain 2014-2022 by Hugh Barney.   No warranty

Copyright \(co 2023 Kevin "The Nuclear" Bloom.
.B ait
comes with ABSOLUTELY NO WARRANTY.
You may redistribute copies of
.B ait
under the terms of the BSD 3-Clause License.
For more information about these matters, see the file named LICENSE.
.SH "SEE ALSO"
.BR mg (1),
.BR emacs (1).