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

[Junio C Hamano <gitster@pobox.com>]

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 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 ;-)


When we standardized writing negatable options this way

    `--option`::
    `--no-option`::
	Description of `--option` that can be turned off with
	`--no-option`.

instead of

    `--[no-]option`::
	Description of `--option` that can be turned off with
	`--no-option`.

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/

Thanks.