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
