From 56287daac0216b1759f71c38a34d6539fef41fb7 Mon Sep 17 00:00:00 2001 From: Pound_Hash Date: Mon, 11 Apr 2022 14:00:43 -0700 Subject: [PATCH 1/2] 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 e4b62123..d628debd 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. From a3c0665accf9e095336f7928e0b4e8e39dac9596 Mon Sep 17 00:00:00 2001 From: Pound_Hash Date: Tue, 10 May 2022 09:53:03 -0700 Subject: [PATCH 2/2] 1) Modified some wording to be more precise 2) Reformatted paragraphs to wrap at column 80 3) Added periods are the end of several lines for overall consistency --- doc/pages/command-parsing.asciidoc | 74 ++++++++++++++++-------------- 1 file changed, 40 insertions(+), 34 deletions(-) diff --git a/doc/pages/command-parsing.asciidoc b/doc/pages/command-parsing.asciidoc index d628debd..bd585292 100644 --- a/doc/pages/command-parsing.asciidoc +++ b/doc/pages/command-parsing.asciidoc @@ -1,36 +1,40 @@ = 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 delimited by a `;` or an end of line +- Commands are terminated by a `;` or an end of line. -- Words (command names and parameters) are delimited 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 (see below for nestable characters), -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). 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. +A quoted string contains every character (including whitespaces). Doubling +a closing delimiter escapes it. Thus, for example, entering two closing +delimiters 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 also be escaped. No other escaping takes place in quoted strings. === Quoted Strings Examples -- `'foo'` contains *foo* +- `'foo'` contains *foo*. -- `foo'bar'` is read verbatim, so it contains *foo'bar'* +- `foo'bar'` is read verbatim, so it contains *foo'bar'*. - `foo%|bar|` is read verbatim, so it contains *foo%|bar|*. -- `'foo''bar'` is a single word whose content is *foo'bar* +- `'foo''bar'` is a single word whose content is *foo'bar*. - `"baz"""` is a single word whose content is *baz"*. @@ -40,44 +44,46 @@ 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 matches that 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 `>`). Characters may be escaped in the same manner as those for quoted strings. === Balanced Strings Examples -- `%{foo}` contains *foo* +- `%{foo}` contains *foo*. -- `%{foo\{bar}}` contains *foo\{bar}* +- `%{foo\{bar}}` contains *foo\{bar}*. -- `foo%{bar}` contains *foo%{bar}* +- `foo%{bar}` contains *foo%{bar}*. -- `"foo %{bar}"` is a single word whose content is *foo bar* +- `"foo %{bar}"` is a single word whose content is *foo bar*. -== Non Quoted words +== Non-Quoted words -Other words are non-quoted. -Non-quoted words end either at a whitespace or a `;`. +Other words are non-quoted. Non-quoted words are terminated by either a +whitespace or a `;`. -If they start with a `\` followed by a `%`, `'`, or `"`, -then that leading `\` escapes those characters and 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 a `\`, -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's content is going to be expanded. -Rules for expanding and escaping expansion types 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. - If the *expansion type* is one of `sh`, `reg`, `opt`, `val` or `arg`, - The string is expanded as described in <> + the string is expanded as described in <>. -- For any other *expansion type* a parsing error is raised. +- For any other *expansion type*, a parsing error is raised.