From 4fabba3d120096b91d385ef544f530c92bd67d21 Mon Sep 17 00:00:00 2001 From: Maxime Coste Date: Thu, 2 Nov 2017 10:03:24 +0800 Subject: [PATCH] doc.kak: Render documentation internally instead of relying on man doc.kak now behaves as a basic asciidoc renderer. Asciidoc is unfortunately still a dependency to generate the manpage of the `kak` command. --- doc/pages/commands.asciidoc | 22 ++++----- doc/pages/execeval.asciidoc | 13 ++---- doc/pages/expansions.asciidoc | 20 +++------ doc/pages/faces.asciidoc | 13 ++---- doc/pages/faq.asciidoc | 67 +++++++++------------------ doc/pages/highlighters.asciidoc | 24 ++++------ doc/pages/hooks.asciidoc | 17 +++---- doc/pages/keys.asciidoc | 57 +++++++++-------------- doc/pages/mapping.asciidoc | 12 ++--- doc/pages/options.asciidoc | 16 ++----- doc/pages/regex.asciidoc | 40 +++++------------ doc/pages/registers.asciidoc | 28 +++++------- doc/pages/scopes.asciidoc | 19 +++----- rc/core/doc.kak | 80 ++++++++++++++++++--------------- src/Makefile | 19 ++------ 15 files changed, 162 insertions(+), 285 deletions(-) diff --git a/doc/pages/commands.asciidoc b/doc/pages/commands.asciidoc index d97e9554..664f977e 100644 --- a/doc/pages/commands.asciidoc +++ b/doc/pages/commands.asciidoc @@ -1,12 +1,6 @@ -kakoune(k) -========== += Commands -NAME ----- -commands - a - -Builtins --------- +== Builtins Some commands take an exclamation mark (*!*), which can be used to force the execution of the command (i.e. to quit a modified buffer, the @@ -169,8 +163,8 @@ command *q!* has to be used). Aliases are mentionned below each commands. remove the highlighter whose id is *highlighter_id* (c.f. the 'highlighters' documentation page) -Helpers -------- +== Helpers + Kakoune provides some helper commands that can be used to define composite commands: @@ -230,14 +224,14 @@ commands: Note that those commands are also available in the interactive mode, but are not really useful in that context. -Multiple commands ------------------ +== Multiple commands + Commands (c.f. previous sections) can be chained, by being separated either by new lines or by semicolons, as such a semicolon must be escaped with a backslash (\;) to be considered as a literal semicolon argument -Declaring new commands ----------------------- +== Declaring new commands + New commands can be defined using the *define-command* command: *define-command* [flags] :: diff --git a/doc/pages/execeval.asciidoc b/doc/pages/execeval.asciidoc index 91b049d6..309cdbb4 100644 --- a/doc/pages/execeval.asciidoc +++ b/doc/pages/execeval.asciidoc @@ -1,12 +1,7 @@ -kakoune(k) -========== += Exec and Eval -NAME ----- -execeval - a +== Description -Description ------------ The *exec* and *eval* commands can be used to run Kakoune commands, and should be used as follows: @@ -23,8 +18,8 @@ the last key/command is reached, or an error is raised. These two commands also save the following registers, who are then restored when the commands have been executed: */*, *"*, *|*, *^*, *@*. -Optional flags --------------- +== Optional flags + *-client* :: execute in the context of the client named *name* diff --git a/doc/pages/expansions.asciidoc b/doc/pages/expansions.asciidoc index 895b8af1..516dc110 100644 --- a/doc/pages/expansions.asciidoc +++ b/doc/pages/expansions.asciidoc @@ -1,12 +1,7 @@ -kakoune(k) -========== += Expansions -NAME ----- -expansions - a +== Strings -Strings -------- \'strings':: uninterpreted strings, use a backslash (\') to escape the separator "strings":: @@ -29,8 +24,7 @@ e.g. %[string], %, %(string), %~string~, %!string! e.g. %{ roger {}; } is a valid string, %{ marcel \} as well ----------------------------------------------------------- -Typed expansions ----------------- +== Typed expansions %\{strings\} can have an expansion type between the *%* and the opening character. They will be written *%\{\}*. They will be @@ -54,8 +48,8 @@ parameter: argument expansion, expand to the arguments of the current command, ** can be a number, or @ for all arguments -Shell expansions ----------------- +== Shell expansions + The '%sh{...}' expansion replaces its content with the output of the shell commands in it. The following environment variables are used to pass informations about Kakoune's state: @@ -131,8 +125,8 @@ informations about Kakoune's state: Note that in order for Kakoune to pass a value in the environment, the variable has to be spelled out within the body of the expansion -Markup strings --------------- +== Markup strings + In certain contexts, Kakoune can take a markup string, which is a string containing formatting informations. In these strings, the {facename} syntax will enable the face facename until another face gets activated, diff --git a/doc/pages/faces.asciidoc b/doc/pages/faces.asciidoc index 6e6ba3d8..c69fa9c7 100644 --- a/doc/pages/faces.asciidoc +++ b/doc/pages/faces.asciidoc @@ -1,12 +1,7 @@ -kakoune(k) -========== += Faces -NAME ----- -faces - a +== Declaration -Declaration ------------ A 'face' refers how the specified text is displayed, it has a foreground color, a background color, and some attributes. The value of a face has the following format: @@ -42,8 +37,8 @@ fg_color[,bg_color][+attributes] exclusive, override previous faces instead of merging with them -Builtin faces -------------- +== Builtin faces + The following default faces are used by color schemes to highlight certain areas of the user interface: diff --git a/doc/pages/faq.asciidoc b/doc/pages/faq.asciidoc index 3a723da4..02d6ca60 100644 --- a/doc/pages/faq.asciidoc +++ b/doc/pages/faq.asciidoc @@ -1,19 +1,12 @@ -kakoune(k) -========== += FAQ -NAME ----- -faq - a - -How to pronounce the name of the project and what does it mean ? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +== How to pronounce the name of the project and what does it mean ? The name of the project is pronounced "Kak-oon", and is a word taken from a New Caledonian dialect based on french. It means a hard blow, usually a punch, but generally refers to a blow into which all of one's strength went. -Is there going to be a Windows port of Kakoune ? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +== Is there going to be a Windows port of Kakoune ? As many features provided by UNIX systems would be missing, or if anything much less efficient on a Windows system, the incentive to porting the @@ -22,8 +15,7 @@ project to this operating system is pretty low. Moreover, you can get pretty decent performance by using Kakoune on Cygwin (which is officially supported). -Kakoune is very slow on big files, what can I do about it ? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +== Kakoune is very slow on big files, what can I do about it ? The default build mode (set in the `Makefile` of the `src` directory of the project) is "debug", which makes it convenient to track issues but also @@ -34,21 +26,18 @@ Note that if your distribution provides a "kakoune" package, the program should already be built in non-debug mode (if you still experience slowness, please report the issue on the bug tracker). -Can I use Kakoune as a pager ? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +== Can I use Kakoune as a pager ? Kakoune can be used as a pager, either by setting the `PAGER` environment variable to `kak`, or by writing data directly to its standard input using a shell pipeline. -Are there any non-console based frontends available ? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +== Are there any non-console based frontends available ? No graphical frontend is currently officially maintained, you can however try experimental community-developed ones. -Why are colors misrendered in my Kakoune clients ? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +== Why are colors misrendered in my Kakoune clients ? The most probable cause for that is a very widespread practice that consists in setting the `TERM` environment variable in the shell's configuration file. @@ -60,16 +49,14 @@ Note that if you're using `tmux`, the proper -official- way to get Kakoune to work is to add the following line to your `tmux` configuration file: `set -sg default-terminal screen-256color` -Why does leaving insert mode take more than half a second in `tmux` ? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +== Why does leaving insert mode take more than half a second in `tmux` ? Upon hitting the escape key, `tmux` waits for a short period of time to determine whether it's part of a function or a meta key sequence. In order to fix this "lag", set the waiting period in your `tmux` configuration file to a short time, e.g. 25ms: `set -sg escape-time 25` -How do I automatically indent code, as Vim does with `=` ? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +== How do I automatically indent code, as Vim does with `=` ? As `Kakoune` doesn't parse the contents of the buffers, there is no builtin equivalent for this Vim feature. Use a formatter/prettifier dedicated to @@ -80,8 +67,7 @@ Example: `%|indent` to indent an entire buffer with C code. Note that some languages have a default formatter set, which you can use with the `:format` command. -Can Kakoune automatically complete the parameters of my functions ? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +== Can Kakoune automatically complete the parameters of my functions ? As mentioned in the above question about Vim's `=` key, Kakoune does not parse the contents of a buffer by itself, which makes it impossible for @@ -95,8 +81,7 @@ editing a C/C++ file, and completion will work on function parameters. Note that the same features are available for python buffers, with the `jedi` script. -Why aren't widely known command line shortcuts such as or available in Kakoune ? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +== Why aren't widely known command line shortcuts such as or available in Kakoune ? Despite their widespread availability in multiple tools, those shortcuts do not fit the paradigm that Kakoune implements, which is based on selections @@ -106,8 +91,7 @@ However, you can easily declare key mappings in your configuration file to be able to use those control-based shortcuts in insert mode (c.f. the "map" command in the "commands" documentation page). -How can I explore the filesystem the way Vim's NerdTree does ? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +== How can I explore the filesystem the way Vim's NerdTree does ? The builtin file completion engine used when opening a file for editing (using the `:edit` command and letting the suggestions popup in the menu @@ -119,8 +103,7 @@ which should in return send an "edit" command followed by the path of the file you selected to the current Kakoune session (e.g. `echo "eval -client $kak_client edit /path/to/file" | kak -p $kak_session`). -Why aren't there other scopes similar to `%sh{}` e.g. python ? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +== Why aren't there other scopes similar to `%sh{}` e.g. python ? Supporting custom scopes would add hard dependencies to the project, which is too much of a drawback when balanced against the low cost of using @@ -129,8 +112,7 @@ The shell scope allows users to spawn any interpreter they want, for a minimal cost in terms of performance, it is therefore the reason why it's the only one available by default. -What shell is used to expand `%sh{}` scopes ? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +== What shell is used to expand `%sh{}` scopes ? The server expands shell scopes using the `sh` binary, stored in one of the directories where all the POSIX standard utilities can be found -this list @@ -139,22 +121,19 @@ by Kakoune at startup. In most distributions, `/bin/sh` will end up being used. -Can I disable auto-indentation completely ? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +== Can I disable auto-indentation completely ? All the indentation hooks are conventionally named `-indent`, which allows us to use the `disabled_hooks` variable to disable indentation globally with the following command: `set global disabled_hooks '.+-indent'` -How to enable syntax highlighting ? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +== How to enable syntax highlighting ? The mimetype of the files opened in new buffers is detected using the `file` command, and syntax highlighting enabled automatically when possible. -My file seems to be highlighted with the wrong colors, I thought syntax highlighting was detected automatically ? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +== My file seems to be highlighted with the wrong colors, I thought syntax highlighting was detected automatically ? The `file` utility has several short comings, such as detecting the wrong mimetype for a file containing data with different syntax, e.g. @@ -166,16 +145,14 @@ for a given format for instance), but not much can be done about those ambiguous cases. You might consider writing a custom `$HOME/.magic` file if needed. -Can I disable syntax highlighting completely ? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +== Can I disable syntax highlighting completely ? Similarly to the indentation hooks, the name format followed by the highlighting hooks is `-highlight`. You can thus disable syntax highlighting using the following command: `set global disabled_hooks '.+-highlight'` -Why does a dot `.` in a regex select newline characters ? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +== Why does a dot `.` in a regex select newline characters ? Data in buffers is a stream of characters, and newlines do not receive special treatment compared to other characters, with regards to regex matching. In @@ -183,8 +160,7 @@ order to select data in a line without any trailing newline characters, one coul use the `[^\n]+` pattern, which is arguably a good compromise when balanced against the ability to select data over several lines. -Can I split the window to display different buffers in them ? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +== Can I split the window to display different buffers in them ? As a fairly compliant follower of the UNIX philosophy, Kakoune does not try to implement features that are best handled by separate, dedicated @@ -198,8 +174,7 @@ In order to open buffers in the same window simultaneously using `tmux` and simply use the `:new` command to spawn new clients as you would have otherwise in an X11 environment. -Why does `a` extend the current selection, but `i` leaves it untouched ? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +== Why does `a` extend the current selection, but `i` leaves it untouched ? Selections are ranges of characters whose delimiters are an "anchor" and a "cursor", and inserting characters is always done before the cursor in diff --git a/doc/pages/highlighters.asciidoc b/doc/pages/highlighters.asciidoc index 9931355e..3e103696 100644 --- a/doc/pages/highlighters.asciidoc +++ b/doc/pages/highlighters.asciidoc @@ -1,12 +1,6 @@ -kakoune(k) -========== += Highlighters -NAME ----- -highlighters - a - -Description ------------ +== Description Manipulation of the displayed text is done through highlighters, which can be added or removed with the following commands: @@ -30,8 +24,8 @@ separated path starting with a scope. Scopes are *global*, *buffer*, completion in a prompt on the *remove-highlighter* command to see the existing highlighters ids. -General highlighters --------------------- +== General highlighters + *regex* : ...:: highlight a regex, takes the regex as first parameter, followed by any number of face parameters. For example: @@ -119,8 +113,8 @@ add-highlighter window regex //\h*(TODO:)[^\n]* 0:cyan 1:yellow,red *line* :: highlight line *number* with face *face* -Highlighting Groups -------------------- +== Highlighting Groups + The *group* highlighter is a container for other highlighters. You can add a a subgroup to an existing group, or scope using: @@ -143,8 +137,7 @@ or several (separated with a pipe sign) of *colorize*, *move* or *wrap* (default add-highlighter window group -passes colorize|move|wrap -------------------------------------------------------------- -Regions highlighters --------------------- +== Regions highlighters A special highlighter provides a way to segment the buffer into regions, which are to be highlighted differently. @@ -221,8 +214,7 @@ add-highlighter //string ... add-highlighter //comment ... ----------------------------------------------------------------- -Shared Highlighters -------------------- +== Shared Highlighters Highlighters are often defined for a specific filetype, and it makes then sense to share the highlighters between all the windows on the same filetypes. diff --git a/doc/pages/hooks.asciidoc b/doc/pages/hooks.asciidoc index a971e47b..b542dd81 100644 --- a/doc/pages/hooks.asciidoc +++ b/doc/pages/hooks.asciidoc @@ -1,12 +1,6 @@ -kakoune(k) -========== += Hooks -NAME ----- -hooks - a - -Description ------------ +== Description Commands can be registered to be executed when certain events arise. To register a hook use the following command: @@ -38,8 +32,8 @@ remove-hooks A call to the command above will remove every hooks in *scope* that are part of the given *group*. -Default hooks -------------- +== Default hooks + *NormalIdle*:: a certain duration has passed since last key was pressed in normal mode @@ -172,8 +166,7 @@ the following expansions: * `kak_hook_param`: filtering text passed to the currently executing hook * `kak_hook_param_capture_N`: text captured by the hook filter regex capture N -Disabling Hooks ---------------- +== Disabling Hooks Any normal mode command can be prefixed with `\` which will disable hook execution for the duration for the command (including the duration of modes diff --git a/doc/pages/keys.asciidoc b/doc/pages/keys.asciidoc index 160afa7a..f1777ceb 100644 --- a/doc/pages/keys.asciidoc +++ b/doc/pages/keys.asciidoc @@ -1,12 +1,7 @@ -kakoune(k) -========== += Keys -NAME ----- -keys - a +== Key Syntax -Key Syntax ----------- Usual keys are written using their ascii character, including capital keys. Non printable keys use an alternate name, written between *<* and *>*, such as ** or **. Modified keys are written between @@ -17,8 +12,8 @@ name or ascii character), for example **, **. In order to bind some keys to arbitrary ones, refer to the 'mapping' documentation page. -Insert mode ------------ +== Insert mode + **:: leave insert mode @@ -73,8 +68,7 @@ Insert mode **:: escape to normal mode for a single command -Using Counts ------------- +== Using Counts In normal mode, commands can be prefixed with a numeric count, which can control the command behaviour. @@ -82,8 +76,7 @@ the command behaviour. For example, *3W* selects 3 consecutive words and *3w* select the third word on the right of selection end. -Disabling Hooks ---------------- +== Disabling Hooks Any normal mode command can be prefixed with *\* which will disable hook execution for the duration for the command (including the duration of modes the command could @@ -92,8 +85,8 @@ move to, so *\i* will disable hooks for the whole insert session). As autoindentation is implemented in terms of hooks, this can be used to disable it when pasting text. -Movement --------- +== Movement + 'word' is a sequence of alphanumeric characters or underscore, and 'WORD' is a sequence of non whitespace characters @@ -212,8 +205,7 @@ is a sequence of non whitespace characters **:: repeat last object or *f*/*t* selection command -Changes -------- +== Changes *i*:: enter insert mode before current selection @@ -364,8 +356,7 @@ Changes rotate (1, 2, 3) and (3, 4, 6) independently -Goto Commands -------------- +== Goto Commands *g*, *G*:: When a count is specified, *G* only extends the current selection to the given line, @@ -408,8 +399,7 @@ Goto Commands *.*::: go to last buffer modification position -View commands -------------- +== View commands *v*, *V*:: *V* enters lock view mode (which will be left when the is hit), @@ -441,8 +431,8 @@ View commands scroll the window count columns right -Marks ------ +== Marks + Marks use the *^* register by default. *Z*:: @@ -477,8 +467,8 @@ Marks use the *^* register by default. *-*::: select the shortest selection -Macros ------- +== Macros + Macros use the *@* register by default **:: @@ -490,8 +480,8 @@ Macros use the *@* register by default *q*:: play a recorded macro -Searching ---------- +== Searching + Searches use the */* register by default ***:: @@ -502,8 +492,8 @@ Searches use the */* register by default set the search pattern to the current selection (verbatim, no smart detection) -Jump list ---------- +== Jump list + **:: Jump forward @@ -514,8 +504,7 @@ Jump list **:: save current selections -Multiple selections -------------------- +== Multiple selections *s*:: create a selection @@ -548,8 +537,7 @@ Multiple selections pipe each selection to the given shell command and keep the ones for which the shell returned 0 -Object Selection ----------------- +== Object Selection **:: selects the whole object @@ -620,8 +608,7 @@ object you want *c*:: select user defined object, will prompt for open and close text -Prompt Commands ---------------- +== Prompt Commands **:: validate prompt diff --git a/doc/pages/mapping.asciidoc b/doc/pages/mapping.asciidoc index 18863d39..99b32675 100644 --- a/doc/pages/mapping.asciidoc +++ b/doc/pages/mapping.asciidoc @@ -1,12 +1,7 @@ -kakoune(k) -========== += Mapping -NAME ----- -mapping - a +== Description -Description ------------ Creating and removing shortcuts boils down to the following commands, respectively: @@ -51,8 +46,7 @@ set to the same sequence of keys passed using the *expected* argument. For more information about the values of the *scope* parameter, refer to the 'scopes' documentation page. -Mappable keys -------------- +== Mappable keys For *key* and *keys* in the *map* command, the following key names can be used: diff --git a/doc/pages/options.asciidoc b/doc/pages/options.asciidoc index d13dc9f5..b075c189 100644 --- a/doc/pages/options.asciidoc +++ b/doc/pages/options.asciidoc @@ -1,12 +1,6 @@ -kakoune(k) -========== += Options -NAME ----- -options - a - -Options -------- +== Description Kakoune can store named and typed values that can be used both to customize the core editor behaviour, and to store data used by extension scripts. @@ -28,8 +22,7 @@ declare-option [-hidden] [] If `-hidden` is specified, the option will not be displayed in completion suggestions. -Types ------ +== Types All options have a type, which defines how they are translated to/from text and their set of valid values. @@ -76,8 +69,7 @@ are exclusively available to built-in options. a set of flags, taking a combination of the given values joined by a '|' character -Builtin options ---------------- +== Builtin options *tabstop* 'int':: *default* 8 + diff --git a/doc/pages/regex.asciidoc b/doc/pages/regex.asciidoc index 81c47c96..763b0442 100644 --- a/doc/pages/regex.asciidoc +++ b/doc/pages/regex.asciidoc @@ -1,20 +1,13 @@ -kakoune(k) -========== += Regex -NAME ----- -regex - a - -Regex Syntax ------------- +== Regex Syntax Kakoune regex syntax is based on the ECMAScript syntax, as defined by the ECMA-262 standard (see <>). Kakoune's regex always run on Unicode codepoint sequences, not on bytes. -Literals --------- +== Literals Every character except the syntax characters `\^$.*+?[]{}|().` match themselves. Syntax characters can be escaped with a backspace so `\$` @@ -32,8 +25,7 @@ Some literals are available as escape sequences: * `\xXX` matches the character whose codepoint is XX (in hexadecimal). * `\uXXXX` matches the character whose codepoint is XXXX (in hexadecimal). -Character classes ------------------ +== Character classes The `[` character introduces a character class, matching one character from a set of characters. @@ -76,13 +68,11 @@ non-digit character. Character class escapes can be used outside of a character class, `\d` is equivalent to `[\d]`. -Any character -------------- +== Any character `.` matches any character, including new lines. -Groups ------- +== Groups Regex atoms can be grouped using `(` and `)` or `(?:` and `)`. If `(` is used, the group will be a capturing group, which means the positions from @@ -95,8 +85,7 @@ for the whole sequence that matched. `(?:` introduces a non capturing group, which will not record the matching positions. -Alternations ------------- +== Alternations `|` introduces an alternation, which will either match its left-hand side, or its right-hand side (preferring the left-hand side) @@ -104,8 +93,7 @@ or its right-hand side (preferring the left-hand side) For example, `foo|bar` matches either `foo` or `bar`, `foo(bar|baz|qux)` matches `foo` followed by either `bar`, `baz` or `qux`. -Quantifier ----------- +== Quantifier Literals, Character classes, Any characters and groups can be followed by a quantifier, which specifies the number of times they can match. @@ -123,8 +111,7 @@ match more characters if possible. Suffixing a quantifier with `?` will make it non-greedy, meaning it will prefer to match as few characters as possible. -Zero width assertions ---------------------- +== Zero width assertions Assertions do not consume any character, but will prevent the regex from matching if they are not fulfilled. @@ -163,8 +150,7 @@ For example, `(?*:: when in insert mode or in a prompt, insert the value stored in the *c* register (single character) @@ -20,14 +15,13 @@ Interacting *"*:: in normal mode, select the ** register (single character) -Alternate names ---------------- +== Alternate names Non alphanumeric registers have an alternative name that can be used in contexts where only alphanumeric identifiers are possible. -Default registers ------------------ +== Default registers + Most commands using a register default to a specific one if not specified: *"* (dquote):: @@ -48,8 +42,8 @@ Most commands using a register default to a specific one if not specified: default shell command register, used by command that spawn a subshell such as *|*, **, *!* or ** -Special registers ------------------ +== Special registers + Some registers are not general purposes, they cannot be written to, but they contain some special data @@ -68,8 +62,8 @@ contain some special data *:* (colon):: last entered command -Integer registers ------------------ +== Integer registers + Registers *1* to *9* hold the grouped sub-matches of the regular expression used to make the last selection. Example: applying the following regular expression to the date of the day would put the day of diff --git a/doc/pages/scopes.asciidoc b/doc/pages/scopes.asciidoc index 9df5458b..52609d3b 100644 --- a/doc/pages/scopes.asciidoc +++ b/doc/pages/scopes.asciidoc @@ -1,19 +1,12 @@ -kakoune(k) -========== += Scopes -NAME ----- -scopes - a - -Description ------------ +== Description Scopes are groups in which a particular Kakoune object (a variable, hook, alias etc) can have different values, depending on the group the value was declared in. -Names and hierarchy -------------------- +== Names and hierarchy Scopes are named as follows: @@ -34,8 +27,7 @@ The above priority line implies that objects can have individual values that will be resolved first in the *window* scope (highest priority), then in the *buffer* scope, and finally in the *global* scope (lowest priority). -Uses ----- +== Uses The scope paradigm is very useful as it allows the user to customize the behavior of the editor without modifying the configuration globally, as @@ -56,8 +48,7 @@ Examples: customized in the *buffer* scope with 'set', c.f. the 'options' documentation page) -Execution context ------------------ +== Execution context Some commands work in a specific context that might exclude one or several scopes altogether, consequently ignoring some values of a given diff --git a/rc/core/doc.kak b/rc/core/doc.kak index 84c56c6e..c1a3c1e5 100644 --- a/rc/core/doc.kak +++ b/rc/core/doc.kak @@ -1,54 +1,64 @@ decl -docstring "name of the client in which documentation is to be displayed" \ str docsclient -def -hidden -params 1..2 doc-open %{ - %sh{ - manout=$(mktemp "${TMPDIR:-/tmp}"/kak-man-XXXXXX) +declare-option -hidden range-specs doc_render_ranges - # This option is handled by the `man-db` implementation - export MANWIDTH=${kak_window_width} - - if man "$1" > "${manout}" 2>/dev/null; then - readonly manout_noescape=$(mktemp "${TMPDIR:-/tmp}"/kak-man-XXXXXX) - - sed -e $(printf 's/.\x8//g') -e 's,\x1B\[[0-9;]*[a-zA-Z],,g' "${manout}" > "${manout_noescape}" - mv -f "${manout_noescape}" "${manout}" - - printf %s\\n " - edit! -scratch '*doc*' - exec |cat${manout}gg - nop %sh{rm ${manout}} - set buffer filetype man - remove-hooks window man-hooks - " - - if [ $# -gt 1 ]; then - needle=$(printf %s\\n "$2" | sed 's,<,,g') - printf %s\\n "try %{ exec '%(?i)^\h+[^\n]*?\Q${needle}\E\z' } catch %{ exec gg }" - fi - else - printf %s\\n "echo -markup %{{Error}doc '$@' failed: see *debug* buffer for details}" - rm ${manout} - fi - } +define-command -hidden -params 4 doc-render-regex %{ + eval -draft %{ try %{ + exec \%s %arg{1} + exec -draft s %arg{2} d + exec "%arg{3}" + %sh{ + ranges=$(echo "$kak_selections_desc" | sed -e "s/:/|$4:/g; s/\$/|$4/") + echo "update-option buffer doc_render_ranges" + echo "set -add buffer doc_render_ranges '$ranges'" + } + } } } -def -params 1..2 \ +define-command -params 1 -hidden doc-render %{ + edit! -scratch *doc* + exec "!cat %arg{1}gg" + + # Join paragraphs together + try %{ exec -draft \%S \n{2,}|(?<=\+)\n|^[^\n]+::\n ^-{2,}(\n|\z) S\n\z \n } + + # Remove some line end markers + try %{ exec -draft \%s \h*(\+|:{2,})$ d } + + # Setup the doc_render_ranges option + set buffer doc_render_ranges %val{timestamp} + doc-render-regex \B(?.*? .*,| 'H' link + + # Remove escaping of * and ` + try %{ exec -draft \%s \\((?=\*)|(?=`)) d } + + set-option buffer readonly true + add-highlighter buffer ranges doc_render_ranges + add-highlighter buffer wrap -word -indent +} + +def -params 1 \ -shell-candidates %{ - find "${kak_runtime}/doc/" -type f -name "*.gz" | while read l; do + find "${kak_runtime}/doc/" -type f -name "*.asciidoc" | while read l; do basename "${l%.*}" done } \ doc -docstring %{doc []: open a buffer containing documentation about a given topic An optional keyword argument can be passed to the function, which will be automatically selected in the documentation} %{ %sh{ - readonly PATH_DOC="${kak_runtime}/doc/${1}.gz" + readonly page="${kak_runtime}/doc/${1}.asciidoc" shift - if [ -f "${PATH_DOC}" ]; then - printf %s\\n "eval -try-client %opt{docsclient} doc-open ${PATH_DOC} $@" + if [ -f "${page}" ]; then + printf %s\\n "eval -try-client %opt{docsclient} doc-render ${page}" else - printf %s\\n "echo -markup '{Error}No such doc file: ${PATH_DOC}'" + printf %s\\n "echo -markup '{Error}No such doc file: ${page}'" fi } } diff --git a/src/Makefile b/src/Makefile index 01db5c8d..534db36e 100644 --- a/src/Makefile +++ b/src/Makefile @@ -16,8 +16,6 @@ endif sources := $(sort $(wildcard *.cc)) objects := $(addprefix ., $(sources:.cc=$(suffix).o)) deps := $(addprefix ., $(sources:.cc=$(suffix).d)) -docs := $(wildcard ../doc/pages/*.asciidoc) -mandocs := $(docs:.asciidoc=.gz) PREFIX ?= /usr/local DESTDIR ?= # root dir @@ -77,16 +75,6 @@ kak$(suffix) : $(objects) a2x --no-xmllint -f manpage $< gzip -n -9 -f $(basename $<) -# Generate the editor's documentation pages -# Since `a2x` won't generate man pages if some sections are missing (which we don't need), -# we generate the pages, patch them and then compress them -../doc/pages/%.gz: ../doc/pages/%.asciidoc - a2x --no-xmllint -f manpage $< - sed -i -r -e "s,^\.TH .+,.TH kakoune k \"\" \"\" \"$(basename $(notdir $<))\"," \ - -e "/^\.SH \"NAME\"/{N;d;}" $(@:.gz=.k) - gzip -n -9 -f $(@:.gz=.k) - mv -f $(@:.gz=.k.gz) $@ - check: test test: cd ../test && ./run @@ -95,7 +83,6 @@ TAGS: tags tags: ctags -R man: ../doc/kak.1.gz -doc: $(mandocs) clean: rm -f .*.o .*.d @@ -114,10 +101,10 @@ installdirs: $(docdir) \ $(mandir) -install: kak man doc installdirs +install: kak man installdirs install -m 0755 kak $(bindir) install -m 0644 ../share/kak/kakrc $(sharedir) - install -m 0644 ../doc/pages/*.gz $(sharedir)/doc + install -m 0644 ../doc/pages/*.asciidoc $(sharedir)/doc install -m 0644 ../rc/base/* $(sharedir)/rc/base install -m 0644 ../rc/core/* $(sharedir)/rc/core install -m 0644 ../rc/extra/* $(sharedir)/rc/extra @@ -136,4 +123,4 @@ uninstall: $(mandir)/kak.1.gz .PHONY: check TAGS clean distclean installdirs install install-strip uninstall -.PHONY: tags test man doc kak +.PHONY: tags test man kak