From e4f7d42396c9c2b3a8c6264bf5a92394c1f100da Mon Sep 17 00:00:00 2001 From: Johannes Altmanninger Date: Thu, 28 May 2020 18:37:26 +0200 Subject: [PATCH] doc: fix typos and clarify some parts --- doc/autoedit.asciidoc | 14 +++++++------- doc/pages/changelog.asciidoc | 2 +- doc/pages/commands.asciidoc | 16 ++++++++-------- doc/pages/faces.asciidoc | 18 +++++++++--------- doc/pages/faq.asciidoc | 8 ++++---- doc/pages/highlighters.asciidoc | 8 ++++---- doc/pages/hooks.asciidoc | 4 ++-- doc/pages/keys.asciidoc | 12 ++++++------ doc/pages/options.asciidoc | 14 +++++++------- doc/pages/regex.asciidoc | 5 ++--- doc/pages/registers.asciidoc | 2 +- 11 files changed, 51 insertions(+), 52 deletions(-) diff --git a/doc/autoedit.asciidoc b/doc/autoedit.asciidoc index f82ecd78..98204199 100644 --- a/doc/autoedit.asciidoc +++ b/doc/autoedit.asciidoc @@ -1,12 +1,12 @@ Edition auto insertion in Kakoune ================================= -It is a quite common feature for code editor to help the programmer by -automatically inserting some text in certain contexts. This document +It is a quite common feature for a code editor to help the programmer +by automatically inserting some text in certain contexts. This document goal is to explain how this is done in Kakoune. -There is no special support in Kakoune for this problem, hooks are -expected to be used in order to manage that, and the normal kakoune +There is no special support in Kakoune for this task, hooks are +expected to be used in order to manage that, and the normal Kakoune editing command are expected to be expressive enough so that relatively complex indentation can be written concisely. @@ -27,7 +27,7 @@ s^\h+y # 2. select the leading spaces and copy them jP # 3. go back to next line start and paste the spaces ---------------------------------------------------------------- -note that if nothing gets selected on phase *2.*, an error will be raised. +Note that if nothing gets selected on phase *2.*, an error will be raised. We want to do that each time the user jumps a line, just after the new line is inserted. So the hook would be: @@ -71,13 +71,13 @@ k # 1. select the previous line j # 3. go back to next line and indent it even if it is empty ------------------------------------------------------------------------------- -Note that if no previous lines end with a +{+ or +(+, the ++ command will +Note that if no previous line ends with a +{+ or +(+, the ++ command will raise an error, and stop the execution. This is what we want: it is similar to what would happen if we would continue with no selections; the following commands would have no effects. However, the error would end up being caught by the hook execution code, and -it will write informations about it in the debug buffer, which we do not want, +it will write information about it in the debug buffer, which we do not want, as this is actually expected. In order to prevent that, the exec should be wrapped in a try command. So we would have: diff --git a/doc/pages/changelog.asciidoc b/doc/pages/changelog.asciidoc index 67be2fc4..da087bd2 100644 --- a/doc/pages/changelog.asciidoc +++ b/doc/pages/changelog.asciidoc @@ -13,7 +13,7 @@ released versions. * replace-ranges highlighter now support empty and multi-lines ranges -* `%var{...}` now expands to list of strings, `$kak_quoted_...` now work +* `%val{...}` now expands to list of strings, `$kak_quoted_...` now work as expected with these. == Kakoune v2020.01.16 diff --git a/doc/pages/commands.asciidoc b/doc/pages/commands.asciidoc index baff045a..9fa82a37 100644 --- a/doc/pages/commands.asciidoc +++ b/doc/pages/commands.asciidoc @@ -2,7 +2,7 @@ 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 -command *q!* has to be used). Aliases are mentionned below each commands. +command *q!* has to be used). Aliases are mentioned below each command. *doc* :: *alias* help + @@ -74,12 +74,12 @@ of the file onto the filesystem *write-all* [-sync]:: *alias* wa + - write all changed buffers that are associated to a file + write all changed buffers that are associated with a file *quit[!]* []:: *alias* q + exit Kakoune, use quit! to force quitting even if there is some - unsaved buffers remaining. If specified, the client exit status + unsaved buffer remaining. If specified, the client exit status will be set to *write-quit[!]* [-sync] []:: @@ -227,7 +227,7 @@ of the file onto the filesystem filesystem. *-quoting* ::: - define how each arguments are quoted in echo output: + define how arguments are quoted in echo output: - *raw* (default):::: just join each argument with a space @@ -446,10 +446,10 @@ New commands can be defined using the *define-command* command: *-shell-script-completion*::: following string is a shell command which takes parameters as - positional params and output one completion candidate per line. + positional params and outputs one completion candidate per line. The provided shell command will run after each keypress - during the executing of the shell command, the following env vars are + during the execution of the shell command, the following env vars are available: - *kak_token_to_complete*:::: @@ -461,12 +461,12 @@ New commands can be defined using the *define-command* command: *-shell-script-candidates*::: following string is a shell command which takes parameters as - positional params and output one completion candidate per line. + positional params and outputs one completion candidate per line. The provided shell command will run once at the beginning of each completion session, candidates are cached and then used by kakoune internal fuzzy engine - during the executing of the shell command, the following env vars are + during the execution of the shell command, the following env vars are available: - *kak_token_to_complete*:::: diff --git a/doc/pages/faces.asciidoc b/doc/pages/faces.asciidoc index eb7910de..50472637 100644 --- a/doc/pages/faces.asciidoc +++ b/doc/pages/faces.asciidoc @@ -2,7 +2,7 @@ == Declaration -A 'face' refers how the specified text is displayed, it has a foreground +A 'face' determines how text is displayed, it has a foreground color, a background color, and some attributes. The value of a face has the following format: @@ -41,9 +41,9 @@ following format: *i*::: italic *F*::: - final, override the previous face instead of merging with it - an will only be replaced if another face with the final - attribute is applied + final, override the previous face instead of merging with it, + and this face will only be replaced if another face with + the final attribute is applied *f*::: final foreground, as final but only applies to face's foreground color @@ -56,7 +56,7 @@ following format: 'base':: The base face on which this face applies, which can be any face name, - as long as a cycle is not introduced. A face can reference itself, in + as long as no cycle is introduced. A face can reference itself, in which case it will apply on top of the parent scope version. == Builtin faces @@ -80,10 +80,10 @@ areas of the user interface: cursor of the secondary selection *PrimaryCursorEol*:: - cursor of the primary selection when it lies on and end of line character + cursor of the primary selection when it lies on an end of line character *SecondaryCursorEol*:: - cursor of the secondary selection when it lies on and end of line character + cursor of the secondary selection when it lies on an end of line character *MenuForeground*:: face for the selected element in menus @@ -147,7 +147,7 @@ The following faces are used by builtin highlighters if enabled. == Markup strings In certain contexts, Kakoune can take a markup string, which is a string -containing formatting informations. In these strings, the {facename} +containing formatting information. In these strings, the {facename} syntax will enable the face facename until another face gets activated, or the end of the string is reached. @@ -167,7 +167,7 @@ and can be used to avoid having to escape text that might be mistaken for markup instructions. For example this will prevent any '{' in the current buffer name from -being incorrectly interpreted as markup instructions. +being incorrectly interpreted as markup instruction. ---- echo -markup "{Information}name:{\} %val{bufname}" diff --git a/doc/pages/faq.asciidoc b/doc/pages/faq.asciidoc index afe1af16..b97856d2 100644 --- a/doc/pages/faq.asciidoc +++ b/doc/pages/faq.asciidoc @@ -3,7 +3,7 @@ == 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, +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 ? @@ -88,7 +88,7 @@ dedicated tool, as is the case with `clang` and C code: you can use the `clang-enable-autocomplete` and `clang-complete` builtin commands whenever editing a C/C++ file, and completion will work on function parameters. -Note that the same features are available for python buffers, with the +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 ? @@ -145,7 +145,7 @@ possible. == 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 +The `file` utility has several shortcomings, such as detecting the wrong mimetype for a file containing data with different syntax, e.g. a Python script containing hardcoded HTML templates detected as an HTML file. @@ -174,7 +174,7 @@ balanced against the ability to select data over several lines. As a fairly compliant follower of the UNIX philosophy, Kakoune does not try to implement features that are best handled by separate, dedicated -tools. Windows splitting in terminals is a prime example of that +tools. Window splitting in terminals is a prime example of that concept, where the editor provides commands to interact with several terminal multiplexers (e.g. `tmux`), as opposed to emulating their functionalities. diff --git a/doc/pages/highlighters.asciidoc b/doc/pages/highlighters.asciidoc index 441356b3..81e834ba 100644 --- a/doc/pages/highlighters.asciidoc +++ b/doc/pages/highlighters.asciidoc @@ -62,7 +62,7 @@ highlighter is replaced with the new one. highlight the cursor line with a separate face *-separator* ::: - specify a string to separate the line numbers column with + specify a string to separate the line numbers column from the rest of the buffer (default is '|') *-min-digits* ::: @@ -123,7 +123,7 @@ add-highlighter window/ dynregex '%reg{/}' 0:+i == Specs highlighters The following highlighters are useful to add indicators like lint warnings, -git blame output or spelling typos. +git blame output or spelling mistakes. See <> for the format of `line-specs` and `range-specs`. @@ -217,7 +217,7 @@ add-highlighter // region \ match of *end*, preventing it from closing the region. *type* and *params*:: - An highlighter type, and associated params, as they would be passed + A highlighter type, and associated params, as they would be passed to `add-highlighter` if they were not applied as a region. If the *-match-capture* switch is passed, then region closing and recurse @@ -249,7 +249,7 @@ another region. That matches the rule governing most programming language parsing. -A default region, that will apply its given highlighter for segments of the +A default region, that will apply its given highlighter to the segments of the buffer that are not in any defined region, can be added with the *default-region* highlighter type. diff --git a/doc/pages/hooks.asciidoc b/doc/pages/hooks.asciidoc index 2d9f0c08..a7ba20c8 100644 --- a/doc/pages/hooks.asciidoc +++ b/doc/pages/hooks.asciidoc @@ -171,7 +171,7 @@ name. Hooks with no description will always use an empty string. *RawKey* `key`:: Triggered whenever a key is pressed by the user, regardless of what mode Kakoune is in, or what mappings are present (see - <>). It cannot triggered by `execute-keys`, + <>). It cannot be triggered by `execute-keys`, even with the `-with-hooks` option (see <>). @@ -194,7 +194,7 @@ vars are available: == 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 +execution for the duration of the command (including the duration of modes the command could move to, so `\i` will disable hooks for the whole insert session). diff --git a/doc/pages/keys.asciidoc b/doc/pages/keys.asciidoc index c1600a3e..dee69832 100644 --- a/doc/pages/keys.asciidoc +++ b/doc/pages/keys.asciidoc @@ -144,7 +144,7 @@ the Shift modifier and moving will extend each selection instead. repeat last object or *f*/*t* selection command *m*:: - select to the next sequence enclosed by matching character, see the + select to the next sequence enclosed by matching characters, see the `matching_pairs` option in <> *M*:: @@ -152,12 +152,12 @@ the Shift modifier and moving will extend each selection instead. character, see the `matching_pairs` option in <> **:: - select to the previous sequence enclosed by matching character, see the + select to the previous sequence enclosed by matching characters, see the `matching_pairs` option in <> **:: extend the current selection to the previous sequence enclosed by matching - character, see the `matching_pairs` option in <> + characters, see the `matching_pairs` option in <> *x*:: select line on which the end of each selection lies (or next line when end lies @@ -292,10 +292,10 @@ Yanking (copying) and pasting use the *"* register by default (See <*:: - deindent selected lines, do not remove incomplete indent (3 leading + unindent selected lines, do not remove incomplete indent (3 leading spaces when indent is 4) *u*:: @@ -347,7 +347,7 @@ Yanking (copying) and pasting use the *"* register by default (See < ---------- - rotate (1, 2, 3) and (3, 4, 6) independently + rotates (1, 2, 3) and (3, 4, 6) independently **:: rotate selections content backward diff --git a/doc/pages/options.asciidoc b/doc/pages/options.asciidoc index db070781..9ee4504e 100644 --- a/doc/pages/options.asciidoc +++ b/doc/pages/options.asciidoc @@ -31,7 +31,7 @@ command: unset-option --------------------------- -Unsetting an option will make it fallback to the value of its parent mode, +Unsetting an option will make it fallback to the value of its parent scope, hence options cannot be unset from the *global* scope. [[declare-option]] @@ -111,9 +111,9 @@ are exclusively available to built-in options. All numeric fields are 1-based. - When the `update-option` is used on an option of this type, its - ranges gets updated according to all the buffer modifications that - happened since its timestamp. + When the command `update-option` is used on an option of this type, + its ranges get updated according to all the buffer modifications + that happened since its timestamp. `set -add` appends the new pair to the list @@ -122,8 +122,8 @@ are exclusively available to built-in options. *line-specs*:: a list of a line number and a corresponding flag (`|`), except for the first element which is just the timestamp - of the buffer. When the `update-option` is used on an option of this - type, its lines gets updated according to all the buffer modifications + of the buffer. When `update-option` is used on an option of this + type, its lines get updated according to all the buffer modifications that happened since its timestamp. See <>) `set -add` appends the new spec to the list @@ -134,7 +134,7 @@ are exclusively available to built-in options. `.[+]@` format to define where the completion apply in the buffer. - Select commands are arbitrary kakoune commands that will be executed + Select commands are arbitrary Kakoune commands that will be executed each time the element is selected in the menu. The common use case is to display element specific documentation. diff --git a/doc/pages/regex.asciidoc b/doc/pages/regex.asciidoc index 9ed8c469..6c1a5ee7 100644 --- a/doc/pages/regex.asciidoc +++ b/doc/pages/regex.asciidoc @@ -147,8 +147,7 @@ More complex assertions can be expressed with lookarounds: not match the text preceding the current position For performance reasons lookaround contents must be sequence of literals, -character classes or any-character (`.`); The use of quantifiers -are not supported. +character classes or any-character (`.`); Quantifiers are not supported. For example, `(?