[PATCH v2 3/7] Documentation/config.txt: describe the structure first and then meaning

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 4, 2015, 21:33 UTC
Message-ID: <1425504803-16039-4-git-send-email-gitster@pobox.com>
In-Reply-To: <1425504803-16039-1-git-send-email-gitster@pobox.com>

A line can be continued via a backquote-LF and can be chomped at a comment character. But that is not specific to string-typed values. It is common to all, just like unquoted leading and trailing whitespaces are stripped and inter-word spacing are retained.

Move the description around and desribe these structural rules first, then introduce the double-quote facility as a way to override them, and finally mention various types of values.

Note that these structural rules only apply to the value part of the configuration file. E.g.

    [aSection] \
        name \
	= value

does not work, because the rules kick in only after seeing "name =". Both the original and the updated text are phrased in an awkward way by singling out the "value" part of the line because of this.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/config.txt | 31 +++++++++++++++----------------
 1 file changed, 15 insertions(+), 16 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 405bf25..1444614 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -59,32 +59,31 @@ is taken as 'name' and the variable is recognized as boolean "true".
 The variable names are case-insensitive, allow only alphanumeric characters
 and `-`, and must start with an alphabetic character.
 
-Leading and trailing whitespace in a variable value is discarded.
-Internal whitespace within a variable value is retained verbatim.
+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
+verbatim.
 
-The values following the equals sign in variable assign are all either
-a string, an integer, or a boolean.  Boolean values may be given as yes/no,
-1/0, true/false or on/off.  Case is not significant in boolean values, when
-converting value to the canonical form using '--bool' type specifier;
-'git config' will ensure that the output is "true" or "false".
-
-String values may be entirely or partially enclosed in double quotes.
-You need to enclose variable values in double quotes if you want to
-preserve leading or trailing whitespace, or if the variable value contains
-comment characters (i.e. it contains '#' or ';').
-Double quote `"` and backslash `\` characters in variable values must
-be escaped: use `\"` for `"` and `\\` for `\`.
+Inside double quotes, double quote `"` and backslash `\` characters
+must be escaped: use `\"` for `"` and `\\` for `\`.
 
 The following escape sequences (beside `\"` and `\\`) are recognized:
 `\n` for newline character (NL), `\t` for horizontal tabulation (HT, TAB)
 and `\b` for backspace (BS).  No other char escape sequence, nor octal
 char sequences are valid.
 
-Variable values ending in a `\` are continued on the next line in the
-customary UNIX fashion.
+The values following the equals sign in variable assign are all either
+a string, an integer, or a boolean.  Boolean values may be given as yes/no,
+1/0, true/false or on/off.  Case is not significant in boolean values, when
+converting value to the canonical form using '--bool' type specifier;
+'git config' will ensure that the output is "true" or "false".
 
 Some variables may require a special value format.
 
+
 Includes
 ~~~~~~~~

-- 
2.3.1-316-g7c93423