From 60b24c6a3204e515b57e6db7df9a6afb8aa7c42a Mon Sep 17 00:00:00 2001 From: Frank LENORMAND Date: Sun, 21 Oct 2018 14:02:23 +0300 Subject: [PATCH] doc: Convert the man page to the TROFF format Fixes #2504 --- README.asciidoc | 3 +- doc/kak.1 | 173 +++++++++++++++++++++++++++++++++++++++++++++ doc/kak.1.asciidoc | 116 ------------------------------ src/Makefile | 5 +- 4 files changed, 175 insertions(+), 122 deletions(-) create mode 100644 doc/kak.1 delete mode 100644 doc/kak.1.asciidoc diff --git a/README.asciidoc b/README.asciidoc index 7bc5d7b5..c7e3b572 100644 --- a/README.asciidoc +++ b/README.asciidoc @@ -106,7 +106,6 @@ Kakoune dependencies are: * A {cpp}14 compliant compiler (GCC >= 5 or clang >= 3.9) along with its associated {cpp} standard library (libstdc{pp} or libc{pp}) * 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 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. ---------------------------------------------------------------- -sudo apt install libncursesw5-dev asciidoc +sudo apt install libncursesw5-dev git clone https://github.com/mawww/kakoune.git && cd kakoune/src make PREFIX=$HOME/.local make install diff --git a/doc/kak.1 b/doc/kak.1 new file mode 100644 index 00000000..e40ae56a --- /dev/null +++ b/doc/kak.1 @@ -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" *.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. diff --git a/doc/kak.1.asciidoc b/doc/kak.1.asciidoc deleted file mode 100644 index 802a8677..00000000 --- a/doc/kak.1.asciidoc +++ /dev/null @@ -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 :: - execute *command* after the client initialization phase - --E :: - execute *command* after the server initialization phase - --f :: - enter in 'filter mode': select the whole file, then execute *keys* - --i :: - backup the files on which a filter is applied using the given suffix - --q:: - when in 'filter mode', don't print any errors - --p :: - send the commands written on the standard input to session *session_id* - --c :: - connect to the given session - --s :: - set the current session name to *session_id* - --ui :: - 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" *.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. diff --git a/src/Makefile b/src/Makefile index b582de5e..271febeb 100644 --- a/src/Makefile +++ b/src/Makefile @@ -94,13 +94,10 @@ kak$(suffix) : $(objects) .version.o # Generate the man page ifeq ($(gzip_man),yes) -../doc/kak.1.gz: ../doc/kak.1.asciidoc - a2x --no-xmllint -f manpage $< +../doc/kak.1.gz: ../doc/kak.1 gzip -n -9 -f $(basename $<) man: ../doc/kak.1.gz else -../doc/kak.1: ../doc/kak.1.asciidoc - a2x --no-xmllint -f manpage $< man: ../doc/kak.1 endif