Merge remote-tracking branch 'somasis/mandoc'

This commit is contained in:
Maxime Coste 2021-06-26 10:00:01 +10:00
commit 272350c32c

527
doc/kak.1
View File

@ -1,251 +1,276 @@
.TH KAK 1 .Dd June 15, 2021
.Dt KAK 1
.SH NAME .Os
.Sh NAME
kak \- a vim inspired, selection oriented code editor .Nm kak
.Nd a vim-inspired, selection oriented code editor
.SH SYNOPSIS .
.Sh SYNOPSIS
.PP .Nm
.B kak \-help .Op Fl d
.Op Fl n
.PP .Op Fl ro
.B kak \-version .Op Fl c Ar session_id | Fl s Ar session_id
.Op Fl ui Ar ui_type
.PP .Op Fl e Ar command
.B kak \-l .Op Fl E Ar command
.Op Sy + Ns Ar line Ns Oo Sy \&: Ns Ar column Oc | Sy +:
.PP .Op Ar file ...
.B kak \-clear .
.Nm
.PP .Fl f Ar keys
.B kak \-f .Op Fl q
.I keys .Op Fl i Ar suffix
[\fB\-q\fR] [\fB\-i\fR] .Op Ar file ...
.IR file ... .
.Nm
.PP .Fl p Ar session_id
.B kak \-p .
.I session_id .Nm
.Fl l
.PP .Nm
.B kak \-s .Fl clear
.I session_id .
.B \-d .Nm
[\fB\-n\fR] [\fB\-ro\fR] .Fl version
[\fB\-E\fR \fIcommand\fR] .
[\fB+line\fR[\fB:column\fR]|\fB+:\fR] .Nm
.IR file ... .Fl help
.
.PP .Sh DESCRIPTION
.B kak .Sy Kakoune
[\fB\-c\fR \fIsession_id\fR|\fB\-s\fR \fIsession_id\fR] is a code editor heavily inspired by
[\fB\-n\fR] [\fB\-ro\fR] .Xr vim 1
[\fB\-ui\fR \fIui_type\fR] [\fB\-e\fR \fIcommand\fR] and
[\fB\-E\fR \fIcommand\fR] .Xr vi 1 .
[\fB+line\fR[\fB:column\fR]|\fB+:\fR] As such, most of its commands are similar to
.IR file ... .Xr vi 1 Ap s,
sharing its
.SH DESCRIPTION .Dq keystrokes as a text editing language
model.
Kakoune is a code editor heavily inspired by Vim. As such, most of its commands .Pp
are similar to Vi's and it shares Vi's "keystrokes as a text editing .Sy Kakoune
language" model. operates in two modes, normal and insertion.
In insertion mode, keys are directly inserted into the current buffer.
Kakoune can operate in two modes, normal and insertion. In insertion mode, In normal mode, keys are used to manipulate the current selection and to
keys are directly inserted into the current buffer. In normal mode, keys enter insertion mode.
are used to manipulate the current selection and to enter insertion mode. .Pp
.Sy Kakoune
Kakoune has a strong focus on interactivity, most commands provide immediate has a strong focus on interactivity.
and incremental results, while still being competitive (as in keystroke Most commands provide immediate and incremental results, while still
count) with Vim. being competitive in keystroke count with vim.
.Pp
Kakoune works on selections, which are oriented, inclusive ranges of .Sy Kakoune
characters. Selections have an anchor and a cursor. Most commands works on selections, which are oriented, inclusive ranges of characters.
move both of them except when extending selection, where the anchor character Selections have an anchor and a cursor.
stays fixed and the cursor moves around. Most commands move both of them except when extending selection, where
the anchor character stays fixed and the cursor moves around.
For more information, use the \fB:doc\fR command after starting Kakoune, .Pp
the Kakoune wiki at https://github.com/mawww/kakoune/wiki The options are as follows:
or the main Kakoune web site: https://kakoune.org/ .Bl -tag -width indent
.It Fl help
.SH OPTIONS Display a help message and quit.
.
.TP .It Fl version
.BR \-help Display Kakoune version and quit.
display a help message and quit .
.It Fl n
.TP Do not load the system's kakrc.
.BR \-version .Pq often, Pa /usr/share/kak/kakrc
display kakoune version and quit .
.It Fl l
.TP List existing sessions.
.BR \-n .
do not load resource files on startup (\fIkakrc\fR, \fIautoload\fR, \fIrc\fR etc) .It Fl d
Run as a headless session
.TP .Pq requires Fl s .
.BR \-l .
list existing sessions .It Fl e Ar command
Execute
.TP .Ar command
.BR \-d after the client initialization phase.
run as a headless session (requires \fB\-s\fR) .
.It Fl E Ar command
.TP Execute
.BR \-e " " \fIcommand\fR .Ar command
execute \fIcommand\fR after the client initialization phase after the server initialization phase.
.
.TP .It Fl f Ar keys
.BR \-E " " \fIcommand\fR Enter in
execute \fIcommand\fR after the server initialization phase .Sq filter mode :
select the whole file, then execute
.TP .Ar keys .
.BR \-f " " \fIkeys\fR .
enter in \fIfilter mode\fR: select the whole file, then execute \fIkeys\fR .It Fl i Ar suffix
Backup the files on which a filter is applied, using the given suffix.
.TP .
.BR \-i " " \fIsuffix\fR .It Fl q
backup the files on which a filter is applied using the given suffix When in
.Sq filter mode ,
.TP don't print any errors
.BR \-q .
when in \fIfilter mode\fR, don't print any errors .It Fl p Ar session_id
Send the commands written on the standard input to session
.TP .Ar session_id .
.BR \-p " " \fIsession_id\fR .
send the commands written on the standard input to session \fIsession_id\fR .It Fl c Ar session_id
Connect to the given session
.TP .Ar session_id .
.BR \-c " " \fIsession_id\fR .
connect to the given session .It Fl s Ar session_id
Set the current session name to
.TP .Ar session_id .
.BR \-s " " \fIsession_id\fR .
set the current session name to \fIsession_id\fR .It Fl ui Ar type
Select the user interface type, which can be
.TP .Em ncurses ,
.BR \-ui " " \fItype\fR .Em dummy ,
select the user interface, can be one of \fIncurses\fR, \fIdummy\fR or \fIjson\fR or
.Em json .
.TP .
.BR \-clear .It Fl clear
remove sessions that terminated in an incorrect state (e.g. after a crash) Remove sessions that were terminated in an incorrect state
.Pq e.g. after a crash .
.TP .
.BR \-ro .It Fl ro
enter in \fIreadonly mode\fR, all the buffers opened will not be written to disk Begin in
.Em readonly mode ,
.TP all the buffers opened will not be written to disk.
.BR +line "[:" column "]" .
specify a target \fIline\fR and \fIcolumn\fR for the first file; when the .It Sy + Ns Ar line Ns Oo Sy \&: Ns Ar column Oc | Sy +:
plus sign is followed by only a colon, then the cursor is sent to the last Specify a target line and column for the first file.
line of the file When the plus sign is followed by only a colon, then the cursor is sent
to the last line of the file.
.TP .
.BR file .It Ar file ...
one or more \fIfile\fRs to edit One or more
.Ar file(s)
.SH ENVIRONMENT to edit.
.El
.TP .
.BR KAKOUNE_POSIX_SHELL .Sh ENVIRONMENT
Overrides the posix shell binary path to use for \fI%sh{...}\fR expansion. .Bl -tag -width 6n
.It Ev KAKOUNE_POSIX_SHELL
.TP Overrides the POSIX shell used for
.BR KAKOUNE_CONFIG_DIR .Em %sh{...}
Overrides the location of the directory containing kakoune user configuration, expansion, which is
defaults to \fI$XDG_CONFIG_HOME/kak\fR if unset. .Pa /bin/sh
.Pq Xr sh 1
.TP if unset.
.BR XDG_CONFIG_HOME .
Path to the user configuration directory, defaults to \fI$HOME/.config\fR if unset. .It Ev KAKOUNE_CONFIG_DIR
Overrides the location of the directory containing Kakoune user
.TP configuration.
.BR XDG_RUNTIME_DIR If unset,
Path to the user session sockets, defaults to \fI$TMPDIR/kakoune\fR if unset. .Pa $XDG_CONFIG_HOME/kak
is used.
.SH FILES .
.It Ev XDG_CONFIG_HOME
In the paths documented below, \fI<rtdir>\fR refers to the runtime directory, Path to the user's configuration directory.
whose value is determined in relation to the path to the \fBkak\fR binary: If unset,
\fI<rtdir>\fR = \fI<path_to_kak_binary>/../share/kak\fR. .Pa $HOME/.config
is used.
If not started with the \fB\-n\fR switch, Kakoune will first load .
\fI<rtdir>/kakrc\fR, which will in turn load the following additional files: .It Ev XDG_RUNTIME_DIR
Path to the user's session's sockets.
.nf If unset,
.RS .Pa $TMPDIR/kakoune
if the \fI$KAKOUNE_CONFIG_DIR/autoload\fR directory exists, recursively load every is used.
\fI*.kak\fR files in it and its sub-directories .El
.RE .
.fi .Sh FILES
In the paths documented below,
.nf .Pa <rtdir>
.RS refers to the runtime directory, whose value is determined in relation
if it does not exist, fall back to the system\-wide autoload directory to the path to
in \fI<rtdir>/autoload\fR, and recursively load all files in a similar way .Nm Ap s
.RE binary location:
.fi .Pa <rtdir>
=
.nf .Pa <path_to_kak_binary>/../share/kak .
.RS .
\fI<rtdir>/kakrc.local\fR, if it exists; this is a user\-defined system\-wide .Pp
configuration If not started with the
.RE .Fl n
.fi switch,
.Nm
.nf will first load
.RS .Pa <rtdir>/kakrc ,
\fI$KAKOUNE_CONFIG_DIR/kakrc\fR, if it exists; this is the user configuration which will in turn load the following additional files:
.RE .
.fi .Bl -bullet
.It
Consequently, if the \fI$KAKOUNE_CONFIG_DIR/autoload\fR directory exists, If the
only scripts stored within that directory will be loaded \- the built-in .Pa $KAKOUNE_CONFIG_DIR/autoload
\fI*.kak\fR files \fBwill not be\fR. directory exists, recursively load every
.Pa *.kak
Users who still want to have the built\-in scripts loaded along their own file in it, and its sub-directories.
can create a symbolic link to \fI<rtdir>/autoload\fR (or to individual .
scripts in it) in their user\-configuration directory: .It
If it does not exist, fall back to the system-wide autoload directory in
.nf .Pa <rtdir>/autoload ,
.RS and recursively load all files in a similar way.
ln -s \fI<rtdir>\fR/autoload "${XDG_CONFIG_HOME:-$HOME/.config}"/kak/autoload .
.RE .It
.fi .Pa <rtdir>/kakrc.local ,
if it exists; this is a user-defined system-wide configuration.
.SH EXAMPLES .
.It
.PP .Pa $KAKOUNE_CONFIG_DIR/kakrc ,
Edit a file: if it exists; this is the user configuration.
.
.nf .El
.RS .
kak /path/to/file .Pp
.RE Consequently, if the
.fi .Pa $KAKOUNE_CONFIG_DIR/autoload
directory exists, only scripts stored within that directory will be
.PP loaded \(em the built-in
Edit multiple files (multiple buffers will be created): .Pa *.kak
files will not be.
.nf .
.RS .Pp
kak ./file1.txt /path/to/file2.c Users who still want the built-in scripts to be loaded along their own
.RE can create a symbolic link to
.fi .Pa <rtdir>/autoload
.Pq or to individual scripts in it
.PP in their user-configuration directory:
Insert a modeline that sets the tabstop variable at the beginning of several .
source code files: .Pp
.Dl ln -s \fI<rtdir>\fR/autoload "${XDG_CONFIG_HOME:-$HOME/.config}"/kak/autoload
.nf .
.RS .Sh EXAMPLES
kak \-f "ggO// kak: tabstop=8<esc>" *.c .Bl -tag -width 6n
.RE .It Edit a file:
.fi .Nm
.Pa /path/to/file
.SH SEE ALSO .
.It Edit multiple files (multiple buffers will be created):
.BR vi (1), .Nm
.BR vim (1), .Pa ./file1.txt
.BR sam (1plan9) .Pa /path/to/file2.c
.
.It Prepend a modeline that sets the tabstop to multiple files:
.Nm
.Fl f Qq ggO// kak: tabstop=8<esc>
.Pa *.c
.El
.
.Sh SEE ALSO
For the complete on-line documentation, use the
.Ic :doc
command after starting
.Nm .
.
.Pp
.Lk https://github.com/mawww/kakoune/wiki The Kakoune wiki .
.Pp
.Lk https://kakoune.org The main Kakoune web site .
.Pp
.Xr vi 1 ,
.Xr vim 1 ,
.Xr sam 1plan9 .
.
.Sh AUTHORS
.An Maxime Coste Aq Mt frrrwww@gmail.com
and many others.