Hi Junio,
Junio C Hamano <gitster@xxxxxxxxx> writes:
> Collin Funk <collin.funk1@xxxxxxxxx> writes:
>
>> + When documenting multiple related `git config` variables, place them on
>> + a separate line instead of separating them by commas. For example:
>> + core.var1::
>> + core.var2::
>> + This is a description of 'core.var1' and 'core.var2'.
>
> As `core.varN` in the above example are all what the end-user would
> give literally, just like `git config` command name in the first
> sentence, they should be marked up as literal strings, i.e.
>
> ... For example, do not write this:
>
> `core.var1`, `core.var2`::
> Description common to `core.var1` and `core.var2`.
>
> Instead write this:
>
> `core.var1`::
> `core.var2`::
> Description common to `core.var1` and `core.var2`.
This markup is different than what is used in
Documentation/config/*.adoc though. Here is just one example:
$ head -n 3 Documentation/config/core.adoc
core.fileMode::
Tells Git if the executable bit of files in the working tree
is to be honored.
That was my reasoning for writing it how I did in the patch. Are you
saying that all of these should be changed? I do not have any experience
with AsciiDoc so I am not sure if that is correct.
>> +This format is required for the `generate-configlist.sh` script to
>> +properly generate "config-list.h".
>
> It is not wrong per-se, but this tempts people to "fix" the
> generate-configlist.sh script so that it can grok the comma
> separated list "again". And when that fix is done and reviewed
> carelessly, we'd again break some implementations of sed the same
> way and we will come back full circle ;-)
> [...]
> we explained that the reason why we want to do so is because it is
> easier to "grep". Does this "do not comma-list variables, but list
> them one per line" also give us better greppability, and if so we
> want to explain that way, perhaps?
>
> $ git grep '`core\.var1`::' Documentation/config/
Yes, that is a good side affect of the change that can be documented.
I will send V2 after clarification on the other point.
Collin
