Re: [PATCH] CodingGuidelines: document formatting required by generate-configlist.sh.

[Collin Funk <collin.funk1@gmail.com>]

Hi Junio,

Junio C Hamano <gitster@pobox.com> writes:

> Collin Funk <collin.funk1@gmail.com> 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