README

   1 NEATVI
   2 ======
   3
   4 Neatvi is a vi/ex editor.  It can edit bidirectional UTF-8 text.
   5
   6 CONFIGURATION
   7 -------------
   8
   9 Edit conf.h to adjust syntax highlighting rules and text direction
  10 patterns.  To define a new keymap, create a new array in kmap.h, like
  11 kmap_fa, and add it to kmaps array in the same header (the first entry
  12 of the new array specifies its name).  The current keymap may be
  13 changed with :cm ex command.  When in input mode, ^e activates the
  14 English keymap and ^f switches to the alternate keymap (the last
  15 keymap specified with :cm).
  16
  17 Sadly, VTE-based terminals such as GNOME's implement a
  18 backward-incompatible extension of virtual terminal escape codes to
  19 render bidirectional text by default.  When using these terminal, the
  20 value of LNPREF macro in conf.h needs to be edited.
  21
  22 COMMANDS
  23 --------
  24
  25 Commands not available in ex(1):
  26
  27 :cm[ap][!] [kmap]
  28   Without kmap, prints the current keymap name.
  29   When kmap is specified, sets the alternate keymap to
  30   kmap and, unless ! is given, switches to this keymap.
  31 :ft [filetype]
  32   Without filetype, prints the current file type.
  33   When filetype is specified, sets the file type of the
  34   current ex buffer.
  35 :ta[g] tag
  36   Jumps to tag (tags file: TAGPATH environment variable or ./tags).
  37 :tn[ext]
  38   Jumps to the next matching tag.
  39 :tp[rev]
  40   Jumps to the previous matching tag.
  41 :po[p]
  42   Pops tag stack.
  43 :b[uffer] [buf]
  44   Without buf, prints buffer list.  Switches to the given buffer
  45   if buf is a buffer number or alias.  Also, buf can be -, +, !,
  46   and ~ to switch to the previous buffer, switch to the next buffer,
  47   delete the current buffer, and renumber buffers, respectively.
  48 :ye reg
  49   Reads dot-terminated lines (similar to :a command) from ex input
  50   and copies them to the given register.
  51
  52 New key mappings:
  53 - ^a in normal mode: searches for the word under the cursor.
  54 - ^p in insert mode: inserts the contents of the default yank buffer.
  55 - ^rX in insert mode: inserts the contents of yank buffer X.
  56 - zL, zl, zr, and zR in normal mode: change the value of td option.
  57 - ^e and ^f in insert mode: switches to the English and alternate keymap.
  58 - ze and zf in normal mode: switches to the English and alternate keymap.
  59 - gu, gU, and g~ in normal mode: switches character case.
  60 - ^l in normal mode: updates terminal dimensions (after resizing it).
  61 - ^] and ^t in normal mode: jumps to tag and pops tag stack.
  62 - gf in normal mode: edits the file whose address is under the cursor.
  63 - gl in normal mode: like gf, but it reads line and column numbers too.
  64 - ^ws, ^wo, ^wc, ^wj, ^wk, ^wx in normal mode: manages windows.
  65 - ^wgf, ^wgl, ^w^] in normal mode: executes gf, gl, ^] in a new window.
  66 - zj, zk, zD: equivalent to :b+, :b-, :b !.
  67 - zJ, zK: equivalent to :next, :prev.
  68 - qX in normal mode: see q-commands section (X can be any letter).
  69 - ^a in ex, search, and pipe prompts: inserts from history lines.
  70
  71 Other noteworthy differences with vi(1):
  72 - Neatvi assumes POSIX extended regular expressions (ERE) in search
  73   patterns, conf.h variables, and even tags files.
  74 - If paths start with =, they are assumed to be relative to the
  75   directory of the current file.
  76 - Neatvi highlights files whose names ends with ls as directory
  77   listings; the gl command can be used to edit its files.
  78
  79 Note that in :ye command, input lines are read from ex input stream
  80 (unlike :a), to make it usable in @ commands and ex scripts (files
  81 passed to :so).  This allows setting the value of registers in ex
  82 files, as the following example shows:
  83
  84   ye a
  85   :!git add %
  86   .
  87
  88 OPTIONS
  89 -------
  90
  91 To improve Neatvi's performance, shaping, character reordering, and
  92 syntax highlighting can be disabled by defining the EXINIT environment
  93 variable as "set noshape | set noorder | set nohl | set td=+2".
  94
  95 Options supported in Neatvi:
  96
  97 td, textdirection
  98   Current direction context.  The following values are meaningful:
  99   * +2: always left-to-right.
 100   * +1: follow conf.h's dircontexts[]; left-to-right for others.
 101   * -1: follow conf.h's dircontexts[]; right-to-left for others.
 102   * -2: always right-to-left.
 103 shape
 104   If set (default), Arabic/Farsi letter shaping will be performed.
 105 order
 106   If set, characters will be reordered based on the rules defined
 107   in conf.h.
 108 hl, highlight
 109   If set (default), text will be highlighted based on syntax
 110   highlighting rules in conf.h.
 111 hll, highlightline
 112   If set, the current line will be highlighted.
 113 lim, linelimit
 114   Lines longer than this value are not reordered or highlighted.
 115 ru, ruler
 116   Indicates when to redraw the status line:
 117   * 0: never.
 118   * 1: always.
 119   * 2: when multiple windows are visible.
 120   * 4: when the current file changes.
 121 hist, history
 122   Indicates the number of lines remembered for ex, search, and
 123   pipe prompts.  Zero disables command history.
 124 ai, autoindent
 125   As in vi(1).
 126 aw, autowrite
 127   As in vi(1).
 128 ic, ignorecase
 129   As in vi(1).
 130 wa, writeany
 131   As in vi(1).
 132
 133 MARKS AND BUFFERS
 134 -----------------
 135
 136 Special marks:
 137 - * the position of the previous change
 138 - [ the first line of the previous change
 139 - ] the last line of the previous change
 140
 141 Special yank buffers:
 142 - / the previous search keyword
 143 - : the previous ex command
 144 - ! the previous pipe command
 145 - % the name of the current file
 146 - " the default yank buffer
 147 - ; the current line
 148 - . the last vi command
 149
 150 Q-COMMANDS
 151 ----------
 152
 153 For qX command in normal mode, Neatvi executes ECMD (defined in conf.h)
 154 with the following parameters:
 155 - X (the key following q)
 156 - current file
 157 - current line number
 158 - current line offset
 159
 160 ECMD must print a line of ex commands and Neatvi executes this line.
 161 Q-commands can be used to add interesting features to Neatvi, such as
 162 language-dependent IDE features, for instance by connecting to an LSP
 163 (language server protocol) server.  As an example, the following
 164 script shows how to use gopls to implement goto definition and find
 165 references for Go.
 166
 167   # Compile.
 168   if test "$1" = "c"; then
 169     go build >.make.ls 2>&1
 170     echo ":e +1 .make.ls | :e"
 171   fi
 172   # Goto definition; uses gopls (not very efficient without using LSP).
 173   if test "$1" = "d"; then
 174     loc=`gopls definition $2:$3:$4`
 175     if test -n "$loc"; then
 176       echo $loc | sed -E 's/^([^:]+):([^:]+):([^:]+).*$/:e +\2 \1/'
 177     fi
 178   fi
 179   # Find references.  Use gl command on each line.
 180   if test "$1" = "f"; then
 181     gopls references $2:$3:$4 >$OUT/.out.ls
 182     echo ":e +1 $OUT/.out.ls | :e"
 183   fi