README

NEATVI
======

Neatvi is a small vi/ex editor for editing UTF-8 text.  It supports
syntax highlighting, multiple windows, right-to-left languages, and
keymaps.

CONFIGURATION
-------------

If the EXINIT environment variable is defined, Neatvi executes its
contents as ex commands at startup.  Otherwise, it executes the ex
commands in $HOME/.neatvi, if present.  They can set the value of
Neatvi options, change syntax highlighting colours, define new or
modify existing keymaps, or define q-commands.  To change syntax
highlighting and text direction patterns, conf.h must be modified.

The :hl (:highlight) ex-mode command changes syntax highlighting
colours; see the syntax highlighting section of this file for the
default set of highlighting rules.  The :cm command switches the
current keymap.  Also, when in input mode, ^e activates the English
keymap and ^f switches to the alternate keymap (the last keymap
specified with :cm).  The :mk (:mapkey) command modifies key mappings
of the current keymap.

Sadly, VTE-based terminals such as GNOME's implement a
backward-incompatible extension of virtual terminal escape codes to
render bidirectional text by default.  When using these terminal, the
the value of the vte option must be changed to 1.

COMMANDS
--------

Commands not available in ex(1):

:cm[ap][!] [kmap]
  Without argument, prints the current keymap name.
  When kmap is given, sets the alternate keymap to the keymap with
  the given name and, unless ! is given, switches to this keymap.
:ft [filetype]
  Without filetype, prints the current file type.
  When filetype is specified, sets the file type of the
  current ex buffer.
:ta[g] tag
  Jumps to tag (tags file: TAGPATH environment variable or ./tags).
:tn[ext]
  Jumps to the next matching tag.
:tp[rev]
  Jumps to the previous matching tag.
:po[p]
  Pops tag stack.
:b[uffer] [buf]
  Without buf, prints buffer list.  Switches to the given buffer
  if buf is a buffer number or alias.  Also, buf can be -, +, !,
  and ~ to switch to the previous buffer, switch to the next buffer,
  delete the current buffer, and renumber buffers, respectively.
:rs reg
  Reads dot-terminated lines (similar to :a command) from ex input
  and copies them to the given yank buffer.
:rx reg cmd
  Like :! command, executes cmd.  However, the contents of the
  specified yank buffer is given to the command as input, and the
  output of the command is written to the same buffer.
:rk reg path
  Connects to a unix socket, writes the contents of the given buffer
  to it, and reads from the socket into the buffer.
:ra reg
  Similar to :@ command, executes the contents of the given buffer.
  Before executing the buffer, however, it replaces ^rx with the
  contents of buffer x, and ^vx with x, in which x is any character.
:ec[ho] msg
  Prints the given message (useful in ex scripts or q-commands).
:hl name [flags] [fg] [bg]
  Specifies syntax highlighting colours.  Flags can be a combination
  of b for bold, i for italic, and r for reversed mode.  Fg and bg,
  if present, specify the foreground and background colours.
  Colours can be numbers from 0 to 255; numbers greater than 15 can
  be used only if the terminal supports the 256-colour palette.
:mk key [def]
  Maps a key to the given character in the current keymap.  If def is
  missing, the mapping is reset.
:mc ch [def]
  Defines a character placeholder for UTF-8 character ch.  For
  instance, "mc  ^r" maps ^r; ^v can be used to escape non-printable
  characters.

New key mappings:
- ^a in normal mode: searches for the word under the cursor.
- ^p in insert mode: inserts the contents of the default yank buffer.
- ^rX in insert mode: inserts the contents of yank buffer X.
- z>, z<, 2z>, and 2z< in normal mode: changes the value of td option.
- ^e and ^f in insert mode: switches to the English and alternate keymap.
- ze and zf in normal mode: switches to the English and alternate keymap.
- gu, gU, and g~ in normal mode: switches character case.
- ^l in normal mode: updates terminal dimensions (after resizing it).
- ^] and ^t in normal mode: jumps to tag and pops tag stack.
- gf in normal mode: edits the file whose address is under the cursor.
- gl in normal mode: like gf, but it reads line and column numbers too.
- ^ws, ^wo, ^wc, ^wj, ^wk, ^wx in normal mode: manages windows.
- ^wgf, ^wgl, ^w^] in normal mode: executes gf, gl, ^] in a new window.
- zj, zk, zD: equivalent to :b+, :b-, :b !.
- zJ, zK: equivalent to :next, :prev.
- ^a in ex, search, and pipe prompts: inserts from history lines.
- q in normal mode: see the quick access section.
- q;: lists and filters buffers.
- q,: lists and filters files listed in ./ls.
- q=: lists and filters files tags in ./tags.

Other noteworthy differences with vi(1):
- Neatvi assumes POSIX extended regular expressions (ERE) in search
  patterns, conf.h variables, and even tags files.
- If paths start with =, they are assumed to be relative to the
  directory of the current file.
- Neatvi highlights files whose names end with ls as directory
  listings; combined with the gl command, which edits the file
  under the cursor, it can be used to explore and edit files
  under a directory.  For instance, git ls-files >ls && neatvi ls.
- In addition to the standard single-letter yank buffers, Neatvi
  supports a set of extended buffers whose two-letter names begin
  with a backslash, like \x.

Note that in :rs command, input lines are read from ex input stream
(unlike :a), to make it usable in @ commands and ex scripts (files
passed to :so).  This allows setting the value of yank buffers in ex
files, as the following example shows:

  rs a
  :!git add %
  .

OPTIONS
-------

To improve Neatvi's performance, shaping, character reordering, and
syntax highlighting can be disabled by defining the EXINIT environment
variable as "set noshape | set noorder | set nohl | set td=+2".

Options supported in Neatvi:

td, textdirection
  Current direction context.  The following values are meaningful:
  * +2: always left-to-right.
  * +1: follow conf.h's dircontexts[]; left-to-right for others.
  * -1: follow conf.h's dircontexts[]; right-to-left for others.
  * -2: always right-to-left.
  The default value is 0, which assumes left-to-right if the first
  character of the line is single-byte; otherwise, it follows
  dircontexts[].
shape
  If set, Arabic/Farsi letter shaping will be performed.
order
  If set, characters will be reordered based on the rules defined
  in conf.h.  If the value is 1, only lines with at least one
  multi-byte UTF-8 character are reordered.  If it is 2, all lines
  are reordered.
hl, highlight
  If set, text will be highlighted based on syntax highlighting
  rules in conf.h.
hll, highlightline
  If set, the current line will be highlighted.
lim, linelimit
  Lines longer than this value are not reordered or highlighted.
ru, ruler
  Indicates when to redraw the status line:
  * 0: never.
  * 1: always.
  * 2: when multiple windows are visible.
  * 4: when the current file changes.
hist, history
  Indicates the number of lines remembered for ex, search, and
  pipe prompts.  Zero disables command history.
ai, autoindent
  As in vi(1).
aw, autowrite
  As in vi(1).
ic, ignorecase
  As in vi(1).
ts, tabstop
  As in vi(1).
wa, writeany
  As in vi(1).

MARKS AND BUFFERS
-----------------

Special marks:
- * the position of the previous change
- [ the first line of the previous change
- ] the last line of the previous change

Special yank buffers:
- / the previous search keyword
- : the previous ex command
- ! the previous pipe command
- % the name of the current file
- " the default yank buffer
- ; the current line
- . the last vi command
- # cursor line number
- ^ cursor line offset
- \/ search history
- \: ex command history
- \! pipe command history

QUICK ACCESS
------------

When q is pressed in normal mode, Neatvi prints the list of buffers at
the bottom of the screen and waits for a key.

- If the key is a digit, it switches to its corresponding buffer.
- If the key is enter, it switches to the first buffer.
- If the key is , (comma), Neatvi lists the lines in ./ls as files,
  and prompts for a keyword to filter them.  An empty keyword selects
  the first item, and \N (for digit N) selects the N-th item.
- If the key is =, Neatvi lists the tags in ./tags, and prompts
  for a keyword to filter them.
- If the key is ;, Neatvi lists the buffers and prompts for a keyword
  to filter them.
- If it is a letter and the extended buffer with that letter (\X for
  letter X) is defined, the contents of that buffer is executed.
- If the key is a letter, but the extended buffer with that letter
  is not defined, Neatvi executes ECMD (defined in conf.h) with the
  following parameters: i) the letter, ii) the current file, iii) the
  current line number, and iv) the current line offset.  What ECMD
  writes to its standard output, Neatvi executes as ex commands.

ECMD commands can be used to add interesting features to Neatvi, such
as language-dependent IDE features, for instance by connecting to an
LSP (language server protocol) server.  neatvi.sh is an example ECMD
shell script.

AUTO-COMPLETION
---------------

When the hist option is nonzero, Neatvi suggests the most recent
matching entry when reading user input for :, /, and ! prompts; ^a
completes the input using the suggestion.

SYNTAX HIGHLIGHTING
-------------------

The default set of syntax highlighting rules are as follows.

" general text
hl . -		" all text
hl ^ - - 11	" current line (hll option)
hl ~ r		" text in reverse direction
hl & - 2	" mapped characters (mc command)
hl , - 2	" lines after EOF

" for programming languages
hl k b 3	" general keywords
hl r - 2	" control flow keywords
hl o b 3	" operators
hl p b 2	" preprocessor directives
hl m b 4	" imported packages
hl t - 3	" built-in types and values
hl b - 3	" built-in functions
hl c i 4	" comments
hl d b 4	" top-level definitions
hl f b		" called functions
hl 0 - 5	" numerical constants
hl h - 5	" character constants
hl s - 5	" string literals
hl v - 3	" macros
hl i -		" identifiers

" ex-mode and status line
hl _ - 7 0	" status line
hl Z - 7 0	" status line of inactive windows
hl N b 2	" status line normal mode
hl I b 4	" status line insert mode
hl F b 3	" status line file name
hl L b 5	" status line line number
hl W b 1	" status line w/r flags
hl K -		" keymap name
hl C - 5	" status line column number
hl T -		" status line line count
hl X b 7 0	" ex-mode output
hl : - 7 0	" ex-mode prompts
hl ! b 7 0	" ex-mode warnings
hl Q b 7 0	" quick leap header
hl U -		" quick leap items
hl D -		" quick leap item dirname
hl B b 3	" quick leap item basename
hl 1 b 1	" quick leap item identifiers
hl 2 - 4	" quick leap item description

" diff file type
hl xD b		" diff header
hl x@ - 6	" diff hunk information line
hl x- - 1	" diff deleted lines
hl x+ - 2	" diff added lines
hl x= - 0	" diff preserved lines

" file listings
hl xd b 8	" path dirname
hl xb b 1	" path basename
hl xn - 2	" path line number
hl xs - 6	" path symbol
hl xl - 8	" the rest of the line
hl x# - 4	" comments

" messages
hl mh b 6	" mail headers
hl ms b 4	" Subject header
hl mf b 2	" From header
hl mt b 5	" To header
hl mc b 5	" CC header
hl mr i 2	" replied text
hl ml b - 3	" labels

" neatmail listing
hl mN b - 6	" new mails
hl mA b 0 5	" high priority
hl mB b 0 3	" priority level 2
hl mC b 0 3	" priority level 3
hl mD - 8	" low priority
hl mF b - 7	" flagged
hl mI i 7	" ignored lines
hl mX b		" commands
hl mS b 6	" status flags
hl m0 - 12	" ignored zeros of the message number
hl m1 b 4	" message number
hl mM - 3	" mbox path
hl mR - 5	" message from
hl mU - 5	" message subject