doc: Convert the man page to the TROFF format

Fixes #2504
This commit is contained in:
Frank LENORMAND 2018-10-21 14:02:23 +03:00
parent 7470c85a1a
commit 60b24c6a32
4 changed files with 175 additions and 122 deletions

View File

@ -106,7 +106,6 @@ Kakoune dependencies are:
* A {cpp}14 compliant compiler (GCC >= 5 or clang >= 3.9) along with its * A {cpp}14 compliant compiler (GCC >= 5 or clang >= 3.9) along with its
associated {cpp} standard library (libstdc{pp} or libc{pp}) associated {cpp} standard library (libstdc{pp} or libc{pp})
* ncurses with wide-characters support (>= 5.3, generally referred to as libncursesw) * ncurses with wide-characters support (>= 5.3, generally referred to as libncursesw)
* asciidoc (for the `a2k` tool), to generate man pages
To build, just type *make* in the src directory. To build, just type *make* in the src directory.
To generate man pages, type *make man* in the src directory. To generate man pages, type *make man* in the src directory.
@ -189,7 +188,7 @@ Building on Ubuntu 16.04.
Make sure you have .local/bin in your path to make the kak binary available from your shell. Make sure you have .local/bin in your path to make the kak binary available from your shell.
---------------------------------------------------------------- ----------------------------------------------------------------
sudo apt install libncursesw5-dev asciidoc sudo apt install libncursesw5-dev
git clone https://github.com/mawww/kakoune.git && cd kakoune/src git clone https://github.com/mawww/kakoune.git && cd kakoune/src
make make
PREFIX=$HOME/.local make install PREFIX=$HOME/.local make install

173
doc/kak.1 Normal file
View File

@ -0,0 +1,173 @@
.TH KAK 1
.SH NAME
kak \- a vim inspired, selection oriented code editor
.SH SYNOPSIS
.B kak
[\fB\-help\fR] [\fB\-version\fR] [\fB\-q\fR] [\fB\-n\fR] [\fB\-l\fR] [\fB\-ro\fR] [\fB\-clear\fR] [\fB\-ui\fR \fIui_type\fR] [\fB\-e\fR \fIcommand\fR] [\fB\-E\fR \fIcommand\fR] [\fB\-f\fR \fIkeys\fR] [\fB\-p\fR \fIsession_id\fR] [\fB\-c\fR \fIsession_id\fR|[[\fB\-d\fR] \fB\-s\fR \fIsession_id\fR] [\fB+line\fR[\fB:column\fR]|\fB+:\fR]
.IR file ...
.SH 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.
.SH OPTIONS
.TP
.BR \-help
display a help message and quit
.TP
.BR \-version
display kakoune version and quit
.TP
.BR \-n
do not load resource files on startup (\fIkakrc\fR, \fIautoload\fR, \fIrc\fR etc)
.TP
.BR \-l
list existing sessions
.TP
.BR \-d
run as a headless session (requires \fB\-s\fR)
.TP
.BR \-e " " \fIcommand\fR
execute \fIcommand\fR after the client initialization phase
.TP
.BR \-E " " \fIcommand\fR
execute \fIcommand\fR after the server initialization phase
.TP
.BR \-f " " \fIkeys\fR
enter in \fIfilter mode\fR: select the whole file, then execute \fIkeys\fR
.TP
.BR \-i " " \fIsuffix\fR
backup the files on which a filter is applied using the given suffix
.TP
.BR \-q
when in \fIfilter mode\fR, don't print any errors
.TP
.BR \-p " " \fIsession_id\fR
send the commands written on the standard input to session \fIsession_id\fR
.TP
.BR \-c " " \fIsession_id\fR
connect to the given session
.TP
.BR \-s " " \fIsession_id\fR
set the current session name to \fIsession_id\fR
.TP
.BR \-ui " " \fItype\fR
select the user interface, can be one of \fIncurses\fR, \fIdummy\fR or \fIjson\fR
.TP
.BR \-clear
remove sessions that terminated in an incorrect state (e.g. after a crash)
.TP
.BR \-ro
enter in \fIreadonly mode\fR, all the buffers opened will not be written to disk
.TP
.BR +line "[:" column "]"
specify a target \fIline\fR and \fIcolumn\fR for the first 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
one or more \fIfile\fRs to edit
At startup, if \fB\-n\fR is not specified, Kakoune will try to source the file
\fI../share/kak/kakrc\fR relative to the kak binary. This kak file will then
try to recursively source any files in \fI$XDG_CONFIG_HOME/kak/autoload\fR
(with \fI$XDG_CONFIG_HOME\fR defaulting to \fI$HOME/.config\fR, and falling back
to \fI../share/kak/autoload\fR if that autoload directory does not exist),
and finally \fI$XDG_CONFIG_HOME/kak/kakrc\fR.
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
.PP
Edit a file:
.nf
.RS
kak /path/to/file
.RE
.fi
.PP
Edit multiple files (multiple buffers will be created):
.nf
.RS
kak ./file1.txt /path/to/file2.c
.RE
.fi
.PP
Insert a modeline that sets the tabstop variable at the beginning of several
source code files:
.nf
.RS
kak \-f "ggO// kak: tabstop=8<esc>" *.c
.RE
.fi
.SH FILES
If not started with the \fB\-n\fR switch, Kakoune will source the \fI../share/kak/kakrc\fR file relative to the kak binary,
which will source additional files:
.nf
.RS
if the \fI$XDG_CONFIG_HOME/kak/autoload\fR directory exists, load every
\fI*.kak\fR files in it, and load recursively any subdirectory
.RE
.fi
.nf
.RS
if it does not exist, fall back to the system wide autoload directory
in \fI../share/kak/autoload\fR
.RE
.fi
After that, if it exists, source the \fI$XDG_CONFIG_HOME/kak/kakrc\fR 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 \fI../share/kak/autoload\fR into your local autoload directory.

View File

@ -1,116 +0,0 @@
kak(1)
======
NAME
----
kak - a vim inspired, selection oriented code editor
SYNOPSIS
--------
*kak* [-help] [-version] [-q] [-n] [-l] [-ro] [-clear] [-ui ui_type] [-e command] [-E command] [-f keys] [-p session_id] [-c session_id|[[-d] -s session_id] [+line[:column]|+:] 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
-------
-help::
display a help message and quit
-version::
display kakoune version and quit
-n::
do not load resource files on startup ('kakrc', 'autoload', 'rc' etc)
-l::
list existing sessions
-d::
run as a headless session (requires -s)
-e <command>::
execute *command* after the client initialization phase
-E <command>::
execute *command* after the server initialization phase
-f <keys>::
enter in 'filter mode': select the whole file, then execute *keys*
-i <suffix>::
backup the files on which a filter is applied using the given suffix
-q::
when in 'filter mode', don't print any errors
-p <session_id>::
send the commands written on the standard input to session *session_id*
-c <session_id>::
connect to the given session
-s <session_id>::
set the current session name to *session_id*
-ui <type>::
select the user interface, can be one of 'ncurses', 'dummy' or 'json'
-clear::
remove sessions that terminated in an incorrect state (e.g. after a crash)
-ro::
enter in 'readonly mode', all the buffers opened will not be written to disk
+line[:column]::
specify a target line and column for the first file; when the plus sign is followed by only a colon,
then the cursor is sent to the last line of the file
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
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 exist, 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

@ -94,13 +94,10 @@ kak$(suffix) : $(objects) .version.o
# Generate the man page # Generate the man page
ifeq ($(gzip_man),yes) ifeq ($(gzip_man),yes)
../doc/kak.1.gz: ../doc/kak.1.asciidoc ../doc/kak.1.gz: ../doc/kak.1
a2x --no-xmllint -f manpage $<
gzip -n -9 -f $(basename $<) gzip -n -9 -f $(basename $<)
man: ../doc/kak.1.gz man: ../doc/kak.1.gz
else else
../doc/kak.1: ../doc/kak.1.asciidoc
a2x --no-xmllint -f manpage $<
man: ../doc/kak.1 man: ../doc/kak.1
endif endif