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

From: Taylor Blau <me@ttaylorr.com>
Date: Jun 2, 2021, 16:59 UTC
Message-ID: <YLe4+2JKH1LYRTvv@nand.local>
In-Reply-To: <057126a2-81c4-41cf-e41a-52a24a0c9a52@gmail.com>

On Tue, Jun 01, 2021 at 09:17:54PM -0400, Derrick Stolee wrote:

Show 17 quoted lines

> 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.

Thanks, Taylor