diff mbox series

[1/1] config doc: highlight the name=value syntax

Message ID 20180924222416.5240-2-philipoakley@iee.org (mailing list archive)
State New, archived
Headers show
Series [1/1] config doc: highlight the name=value syntax | expand

Commit Message

Philip Oakley Sept. 24, 2018, 10:24 p.m. UTC
Stas Bekman reported [1] that Git config was not accepting single quotes
around a filename as may have been expected by shell users.

Highlight the 'name = value' syntax with its own heading. Clarify that
single quotes are not special here. Also point to this paragraph in the
'include' section regarding pathnames.

In addition clarify that missing include file paths are not an error, but
rather an implicit 'if found' for include files.

[1] https://public-inbox.org/git/ca2b192e-1722-092e-2c54-d79d21a66ba2@stason.org/

Reported-by: Stas Bekman <stas@stason.org>
Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/config.txt | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

Comments

Junio C Hamano Sept. 25, 2018, 10:03 p.m. UTC | #1
Philip Oakley <philipoakley@iee.org> writes:

> +Variable name/value syntax
> +^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
>  All the other lines (and the remainder of the line after the section
>  header) are recognized as setting variables, in the form
>  'name = value' (or just 'name', which is a short-hand to say that
> @@ -69,7 +72,8 @@ stripped.  Leading whitespaces after 'name =', the remainder of the
>  line after the first comment character '#' or ';', and trailing
>  whitespaces of the line are discarded unless they are enclosed in
>  double quotes.  Internal whitespaces within the value are retained
> -verbatim.
> +verbatim. Single quotes are not special and form part of the
> +variable's value.
>  
>  Inside double quotes, double quote `"` and backslash `\` characters
>  must be escaped: use `\"` for `"` and `\\` for `\`.

Hmph.  This feels a bit backwards.  

The original paragraph is horrible in that there is no clear mention
that a pair of dq can be used to quote (which primarily is useful if
your value have leading or trailing whitespaces); the closest hint
is "enclosed in double quotes" we see in the pre-context.  The added
sentence singles out sq but it is unclear why it is necessary to
call out that it is not special---the readers can legitimately
wonder if backquotes are special or not and why.

I wonder if this is easier to understand:

    diff --git a/Documentation/config.txt b/Documentation/config.txt
    index ad0f4510c3..5eebd539df 100644
    --- a/Documentation/config.txt
    +++ b/Documentation/config.txt
    @@ -61,12 +61,16 @@ the variable is the boolean "true").
     The variable names are case-insensitive, allow only alphanumeric characters
     and `-`, and must start with an alphabetic character.

    +The value part can have segments that are enclosed in a pair of
    +double quotes (note: other kinds of quoting character pairs are not
    +special)--the double quotes are stripped from the value.
    +
     A line that defines a value can be continued to the next line by
     ending it with a `\`; the backquote and the end-of-line are
     stripped.  Leading whitespaces after 'name =', the remainder of the
     line after the first comment character '#' or ';', and trailing
    -whitespaces of the line are discarded unless they are enclosed in
    -double quotes.  Internal whitespaces within the value are retained
    +whitespaces of the line are discarded.
    +Internal whitespaces within the value are retained
     verbatim.

     Inside double quotes, double quote `"` and backslash `\` characters

> @@ -89,10 +93,14 @@ each other with the exception that `includeIf` sections may be ignored
>  if their condition does not evaluate to true; see "Conditional includes"
>  below.
>  
> +Both the `include` and `includeIf` sections implicitly apply an 'if found'
> +condition to the given path names.
> +

Mentioning that missing target file is not an error is definitely an
improvement.  I've never viewed it as applying "if found" condition
myself, but it is not wrong per-se to do so, I would think.

>  You can include a config file from another by setting the special
>  `include.path` (or `includeIf.*.path`) variable to the name of the file
>  to be included. The variable takes a pathname as its value, and is
> -subject to tilde expansion. These variables can be given multiple times.
> +subject to tilde expansion and the value syntax detailed above.
> +These variables can be given multiple times.

I have a mild suspicion that this adds negative value.  Singling out
that "[include] path = ..."  follows the usual value syntax makes
the readers wonder if there are some "[section] variable = ..." that
does not follow the value syntax that they have to be aware of and
careful about.
diff mbox series

Patch

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 1264d91fa3..b65fd6138d 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -19,8 +19,8 @@  characters and `-`, and must start with an alphabetic character.  Some
 variables may appear multiple times; we say then that the variable is
 multivalued.
 
-Syntax
-~~~~~~
+Config file Syntax
+~~~~~~~~~~~~~~~~~~
 
 The syntax is fairly flexible and permissive; whitespaces are mostly
 ignored.  The '#' and ';' characters begin comments to the end of line,
@@ -56,6 +56,9 @@  syntax, the subsection name is converted to lower-case and is also
 compared case sensitively. These subsection names follow the same
 restrictions as section names.
 
+Variable name/value syntax
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 All the other lines (and the remainder of the line after the section
 header) are recognized as setting variables, in the form
 'name = value' (or just 'name', which is a short-hand to say that
@@ -69,7 +72,8 @@  stripped.  Leading whitespaces after 'name =', the remainder of the
 line after the first comment character '#' or ';', and trailing
 whitespaces of the line are discarded unless they are enclosed in
 double quotes.  Internal whitespaces within the value are retained
-verbatim.
+verbatim. Single quotes are not special and form part of the
+variable's value.
 
 Inside double quotes, double quote `"` and backslash `\` characters
 must be escaped: use `\"` for `"` and `\\` for `\`.
@@ -89,10 +93,14 @@  each other with the exception that `includeIf` sections may be ignored
 if their condition does not evaluate to true; see "Conditional includes"
 below.
 
+Both the `include` and `includeIf` sections implicitly apply an 'if found'
+condition to the given path names.
+
 You can include a config file from another by setting the special
 `include.path` (or `includeIf.*.path`) variable to the name of the file
 to be included. The variable takes a pathname as its value, and is
-subject to tilde expansion. These variables can be given multiple times.
+subject to tilde expansion and the value syntax detailed above.
+These variables can be given multiple times.
 
 The contents of the included file are inserted immediately, as if they
 had been found at the location of the include directive. If the value of the