Migrate the raw troff kakoune man page to the asciidoc format

This commit is contained in:
Frank LENORMAND 2016-02-03 14:51:32 +02:00
parent caa87608d4
commit b6e930a57d
3 changed files with 93 additions and 149 deletions

View File

@ -1,147 +0,0 @@
'\" t
.\" ** The above line should force tbl to be a preprocessor **
.\" Man page for kakoune
.\"
.pc
.TH KAKOUNE 1 "" "1.0" "editor"
.SH NAME
kakoune \- a vim inspired, selection oriented code editor
.SH SYNOPSIS
.B kak
.RB [\| \-q \|]
.RB [\| \-u \|]
.RB [\| \-n \|]
.RB [\| \-l \|]
.RB [\| \-e
.IR command \|]
.RB [\| \-f
.IR command \|]
.RB [\| \-p
.IR session_id \|]
.RB [\| \-c
.IR session_id \||\c
.RB [\| [\| \-d \|]\c
.RB \ \-s
.IR session_id \|]
.IR file \ .\|.\|.\|
.SH DESCRIPTION
Kakoune is a code editor heavily inspired by Vim, as such most of its commands are similar to vis ones, and it shares \
Vis "keystrokes as a text editing language" model.
Kakoune can operate in two modes, normal and insertion. In insertion mode, keys are directly inserted into the current \
buffer. In normal mode, keys are used to manipulate the current selection and to enter insertion mode.
Kakoune has a strong focus on interactivity, most commands provide immediate and incremental results, while still being \
competitive (as in keystroke count) with Vim.
Kakoune works on selections, which are oriented, inclusive range of characters, selections have an anchor and a cursor \
character. Most commands move both of them, except when extending selection where the anchor character stays fixed and \
the cursor one moves around.
.SH OPTIONS
.TP
.BR -q
in filter mode, be quiet about errors applying keys
.TP
.BR -u
use a dummy user interface, for testing purposes
.TP
.BR -n
do not source kakrc files on startup
.TP
.BR -l
list existing sessions
.TP
.BR -d
run as a headless session (requires -s)
.TP
.BR -e " <command>"
execute argument on initialisation
.TP
.BR -f " <command>"
act as a filter, executing given keys on given files
.TP
.BR -p " <session_id>"
just send stdin as commands to the given session
.TP
.BR -c " <session_id>"
connect to given session
.TP
.BR -s " <session_id>"
set session name
.TP
.BR file
one or more files to edit
.RE
At startup, if -n is not specified, Kakoune will try to source the file
.IB ../share/kak/kakrc
relative to the kak binary. \
This kak file will then try to recursively source any files in
.BR $XDG_CONFIG_HOME/kak/autoload
(with
.BR $XDG_CONFIG_HOME
defaulting to
.BR $HOME/.config ","
and falling back to
.IB ../share/kak/autoload
if that autoload directory does not exist), and finally
.BR $XDG_CONFIG_HOME/kak/kakrc "."
That leads to the following behaviour: by default, with no user autoload directory, the system wide autoload directory is used, once the user \
wants control on autoloading, they can create an autoload directory and eventually symlink individual scripts, or the whole system wide autoload \
directory. They can as well add any new scripts not provided with Kakoune.
.SH EXAMPLES
.TP
.BR kak " /path/to/file"
Edit a file
.RE
.TP
.BR kak " ./file1.txt /path/to/file2.c"
Edit multiple files (multiple buffers will be created)
.RE
.TP
.BR kak " -f 'ggO// kak: tabstop=8<esc>' *.c"
Insert a modeline that sets the
.IR tabstop
variable at the beginning of several source code files
.RE
.TP
.BR kak " -e 'man dup2'"
Use Kakoune as a man pager
.RE
.SH FILES
If not started with the
.BR -n
switch, Kakoune will source the
.BR ../share/kak/kakrc
file relative to the kak binary, which will source additional files:
\[bu] if the
.BR $XDG_CONFIG_HOME/kak/autoload
directory exists, load every
.IR *.kak
files in it, and load recursively any subdirectory
\[bu] if it does not exists, fall back to the system wide autoload directory in
.BR ../share/kak/autoload
After that, if it exists, source the
.BR $XDG_CONFIG_HOME/kak/kakrc
file which should be used for user configuration.
In order to continue autoloading site-wide files with a local autoload directory, just add a symbolic link to
.BR ../share/kak/autoload/
into your local autoload directory.

90
doc/kakoune.1.txt Normal file
View File

@ -0,0 +1,90 @@
kakoune(1)
==========
NAME
----
kakoune - a vim inspired, selection oriented code editor
SYNOPSIS
--------
*kak* [-q] [-u] [-n] [-l] [-e command] [-f command] [-p session_id] [-c session_id|[[-d] -s session_id] file ...
DESCRIPTION
-----------
Kakoune is a code editor heavily inspired by Vim, as such most of its commands are similar to Vi's ones, and it shares Vi's "keystrokes as a text editing language" model.
Kakoune can operate in two modes, normal and insertion. In insertion mode, keys are directly inserted into the current buffer. In normal mode, keys are used to manipulate the current selection and to enter insertion mode.
Kakoune has a strong focus on interactivity, most commands provide immediate and incremental results, while still being competitive (as in keystroke count) with Vim.
Kakoune works on selections, which are oriented, inclusive range of characters, selections have an anchor and a cursor character. Most commands move both of them, except when extending selection where the anchor character stays fixed and the cursor one moves around.
OPTIONS
-------
-q::
in filter mode, be quiet about errors applying keys
-u::
use a dummy user interface, for testing purposes
-n::
do not source kakrc files on startup
-l::
list existing sessions
-d::
run as a headless session (requires -s)
-e <command>::
execute argument on initialisation
-f <command>::
act as a filter, executing given keys on given files
-p <session_id>::
just send stdin as commands to the given session
-c <session_id>::
connect to given session
-s <session_id>::
set session name
file::
one or more files to edit
At startup, if -n is not specified, Kakoune will try to source the file '../share/kak/kakrc' relative to the kak binary. This kak file will then try to recursively source any files in
*$XDG_CONFIG_HOME*'/kak/autoload' (with *$XDG_CONFIG_HOME* defaulting to *$HOME*'/.config', and falling back to '../share/kak/autoload' if that autoload directory does not exist), and finally
*$XDG_CONFIG_HOME*'/kak/kakrc'.
That leads to the following behaviour: by default, with no user autoload directory, the system wide autoload directory is used, once the user wants control on autoloading, they can
create an autoload directory and eventually symlink individual scripts, or the whole system wide autoload directory. They can as well add any new scripts not provided with Kakoune.
EXAMPLES
--------
kak /path/to/file::
Edit a file
kak ./file1.txt /path/to/file2.c::
Edit multiple files (multiple buffers will be created)
kak -f "ggO// kak: tabstop=8<esc>" *.c::
Insert a modeline that sets the tabstop variable at the beginning of several source code files
kak -e "man dup2"::
Use Kakoune as a man pager
FILES
-----
If not started with the -n switch, Kakoune will source the '../share/kak/kakrc' file relative to the kak binary, which will source additional files:
* if the *$XDG_CONFIG_HOME*'/kak/autoload' directory exists, load every '*.kak' files in it, and load recursively any subdirectory
* if it does not exists, fall back to the system wide autoload directory in '../share/kak/autoload'
After that, if it exists, source the *$XDG_CONFIG_HOME*'/kak/kakrc' file which should be used for user configuration.
In order to continue autoloading site-wide files with a local autoload directory, just add a symbolic link to '../share/kak/autoload' into your local autoload directory.

View File

@ -67,8 +67,9 @@ test:
cd ../test && ./run
tags:
ctags -R
man:
gzip -fk ../doc/kakoune.1
man: ../doc/kakoune.1.txt
a2x -f manpage $<
gzip -fk $(basename $<)
clean:
rm -f .*.o .*.d kak tags