From 56287daac0216b1759f71c38a34d6539fef41fb7 Mon Sep 17 00:00:00 2001 From: Pound_Hash Date: Mon, 11 Apr 2022 14:00:43 -0700 Subject: [PATCH] Fixed English mechanics: grammar, punctuation, and wording --- doc/pages/command-parsing.asciidoc | 59 +++++++++++++----------------- 1 file changed, 25 insertions(+), 34 deletions(-) diff --git a/doc/pages/command-parsing.asciidoc b/doc/pages/command-parsing.asciidoc index e4b62123c..d628debd6 100644 --- a/doc/pages/command-parsing.asciidoc +++ b/doc/pages/command-parsing.asciidoc @@ -1,26 +1,24 @@ = Command Parsing -Kakoune commands, either loaded from a script, or written in the command -prompt are parsed according to the following rules: +Kakoune commands, either loaded from a script or written in the command prompt, are parsed according to the following rules: == Basic parsing -- Commands are separated by `;` or end of lines +- Commands are delimited by a `;` or an end of line -- Words (command names and parameters) are separated by whitespaces +- Words (command names and parameters) are delimited by whitespaces == Quoted Strings -If a word starts with `'`, `"` or `%X` with `X` a non nestable -punctuation character it is parsed as a quoted string whose delimiter is, -respectively, `'`, `"` or `X`. +If a word starts with `'`, `"`, or `%X` with `X` a non-nestable punctuation character (see below for nestable characters), +it is parsed as a quoted string whose delimiter is, respectively, `'`, `"`, or `X`. -A quoted string contains every character (including whitespaces) until -its closing delimiter. If its closing delimiter is doubled, then it is -considered to be part of the string content as a single delimiter. +A quoted string contains every character (including whitespaces). Doubling a closing delimiter escapes it. +Thus, for example, entering two closing delimiting characters at the end of a quoted string will render one of the characters literally; +that is, it will be considered as part of the quoted string's content. -Inside double quotes, `%`-strings are processed unless the `%` is escaped by -doubling it. Double quotes inside these nested strings must still be escaped. +Inside double quotes, `%`-strings are processed unless the `%` is escaped by doubling it. +Double quotes inside these nested strings must still be escaped. No other escaping takes place in quoted strings. @@ -42,17 +40,11 @@ No other escaping takes place in quoted strings. == Balanced Strings -If a word starts with `%X` with `X` a nestable punctuation character (one -of `(`, `[`, `{` and `<`), it is parsed as a balanced string whose closing -delimiter is the matching character of its opening delimiter (respectively -`)`, `]`, `}` and `>`). +If a word starts with `%X` with `X` a nestable punctuation character (one of `(`, `[`, `{` and `<`), +it is parsed as a balanced string +whose closing delimiter matches that of its opening delimiter (respectively `)`, `]`, `}` and `>`). -A balanced string contains every character (including whitespaces) until -a closing delimiter is found, and opening and closing delimiters are -balanced inside the string (each opening delimiter appearing inside the -string have been closed by a matching closing delimiter). - -No other escaping takes place in balanced strings. +Characters may be escaped in the same manner as those for quoted strings. === Balanced Strings Examples @@ -66,23 +58,22 @@ No other escaping takes place in balanced strings. == Non Quoted words -Other words are non-quoted. Non-quoted words end either on a whitespaces -or a `;`. +Other words are non-quoted. +Non-quoted words end either at a whitespace or a `;`. -If they start with `\` followed by `%`, `'` or `"`, then that leading -`\` is discarded. +If they start with a `\` followed by a `%`, `'`, or `"`, +then that leading `\` escapes those characters and is discarded. -If a whitespace or `;` is preceded by `\`, then the `\` is discarded -and the whitespace or `;` becomes part of the word. Any other `\` -is treated as a literal `\`. +If a whitespace or `;` is preceded by a `\`, +then the `\` is discarded, and the whitespace or `;` becomes part of the word. +Any other `\` is treated as a literal `\`. == Typed Expansions -Quoted and Balanced strings starting with `%` might have an optional -alphabetic *expansion type* between the `%` and their delimiter (which -is always a punctuation character). This *expansion type* defines how the -string content is going to be expanded. Rules for expanding and escaping typed -expansions are the same as for `%`-strings. +Quoted and Balanced strings starting with `%` might have an optional alphabetic *expansion type* between the `%` and their delimiter +(which is always a punctuation character). +This *expansion type* defines how the string's content is going to be expanded. +Rules for expanding and escaping expansion types are the same as for `%`-strings. - If the *expansion type* is empty, the string content is used verbatim.