Re: [PATCH] config doc: indent descriptions of feature.* variables

[Todd Zullinger <tmz@pobox.com>]

Taylor Blau wrote:
> On Tue, Jun 01, 2021 at 09:17:54PM -0400, Derrick Stolee wrote:
>> On 6/1/2021 8:11 PM, Andrei Rybak wrote:
>>> Config variables feature.experimental and feature.manyFiles are grouped
>>> together under "feature.*".  However, this is not easily visible when
>>> scanning the help page of git-config.
>>>
>>> Indent the descriptions of individual feature.* config variables to help
>>> the reader distinguish this group of variables.
>>
>> I'm not sure how these extra tabs help in the rendered text, or in
>> the formatted HTML output for the git-scm.com web page. I do believe
>> that we would want to re-wrap the paragraphs to ensure we are not using
>> too many characters per line.
>>
>> Is there precedence for a simple tabbing like this? I was able to find
>> a similar grouping for advice.* in Documentation/config/advice.txt, but
>> it uses a different kind of grouping. Perhaps reorganize the file to use
>> that strategy instead?
> 
> AsciiDoc has a couple of ways to indent a subsection, one example (which
> uses the same style '--' header as in these patches) can be found in
> 9218c6a40c (midx: allow marking a pack as preferred, 2021-03-30).
> 
>> Or, perhaps just point me to an existing use of this pattern.
> 
> git-scm.com doesn't have 9218c6a40c yet, since it won't be released
> until 2.32, but grepping around for '^--' in Documentation shows some
> other results.

One thing worth noting if this is picked up, I think the `+`
continuations inside the `--` open block should be removed.
They render fine in asciidoc, but in asciidoctor the `+`
characters remain in the rendered output.

Here's a doc-diff with and without the additional `+`
continuations in asciidoctor:

    --- a/git-config.1	2021-06-01 21:39:56.769640893 -0400
    +++ b/git-config.1	2021-06-01 21:40:03.318893602 -0400
    @@ -2474,7 +2474,7 @@
                    version updates. These settings may have unintended
                    interactions since they are so new. Please enable this setting
                    if you are interested in providing feedback on experimental
    -               features. The new default values are: +
    +               features. The new default values are:
     
                    •   fetch.negotiationAlgorithm=skipping may improve fetch
                        negotiation times by skipping more commits at a time,
    @@ -2484,10 +2484,10 @@
                    Enable config options that optimize for repos with many files
                    in the working directory. With many files, commands such as git
                    status and git checkout may be slow and these new defaults
    -               improve performance: +
    +               improve performance:
     
                    •   index.version=4 enables path-prefix compression in the
    -                   index. +
    +                   index.
     
                    •   core.untrackedCache=true enables the untracked cache. This
                        setting assumes that mtime is working on your machine.

Here's what I suggest be squashed into this patch:

diff --git a/Documentation/config/feature.txt b/Documentation/config/feature.txt
index 2c4dee170b..7975ec35fd 100644
--- a/Documentation/config/feature.txt
+++ b/Documentation/config/feature.txt
@@ -12,7 +12,7 @@ feature.*::
 		have unintended interactions since they are so new. Please enable this
 		setting if you are interested in providing feedback on experimental
 		features. The new default values are:
-	+
+
 	* `fetch.negotiationAlgorithm=skipping` may improve fetch negotiation times by
 	skipping more commits at a time, reducing the number of round trips.
 
@@ -20,9 +20,9 @@ feature.*::
 		Enable config options that optimize for repos with many files in the
 		working directory. With many files, commands such as `git status` and
 		`git checkout` may be slow and these new defaults improve performance:
-	+
+
 	* `index.version=4` enables path-prefix compression in the index.
-	+
+
 	* `core.untrackedCache=true` enables the untracked cache. This setting assumes
 	that mtime is working on your machine.
 --

With the above, the man page output renders identically with
asciidoc (9.1.0) and asciidoctor (I tested both 2.0.10 and
2.0.15).

The asciidoc documentation[1] says:

    If you’re attaching more than one block to a list item,
    you’re strongly encouraged to wrap the content inside an
    open block. That way, you only need a single list
    continuation line to attach the open block to the list
    item. Within the open block, you write like you normally
    would, no longer having to worry about adding list
    continuations between the blocks to keep them attached
    to the list item.

[1] https://docs.asciidoctor.org/asciidoc/latest/lists/continuation/#list-continuation

Only mildly related, but while I was looking at the output,
I noticed that the man page renders the phrase "The config
settings that start with `feature.` modify the defaults"
oddly.  It places two spaces after the full stop.  It might
be worth writing that sentence slightly differently to avoid
that.  Maybe something like:

-       The config settings that start with `feature.` modify the defaults of
+       The `feature.*` variables modify the defaults of

-- 
Todd