Subject: Re: [PATCH v7 1/5] command-list.txt: prepare with [commands] header

From: Junio C Hamano <[email-masked]>
Date: Fri, 15 May 2015 15:26:52 -0700

Eric Sunshine <[email-masked]> writes:

> On Fri, May 15, 2015 at 4:44 PM, Junio C Hamano <[email-masked]> wrote:
>> Sébastien Guimmara  <[email-masked]> writes:
>>>> You could for example have used the existing "# List of known git
>>>> commands" as such a signal to tell that all the no comment lines
>>>> below are commands.
>>>
>>> I tend to think that relying on comments as marks for parsers is brittle,
>>> but indeed square brackets get in the way of sed regexes. I'll think of
>>> something better. Thanks.
>>
>> Heh, we, and more importantly our users, already rely on a marker in
>> comments when writing their commit log messages ;-)
>>
>> I would not be opposed to a new header that is outside comment, but
>> I do not think the marker line that is also a comment is "brittle"
>> and would not be opposed to that, either.
>>
>>     # do not molest the next line
>>     ### command list
>>     # name category
>>     git-add mainporcelain
>>     ...
>>
>> would be perfectly acceptable.
>>
>> I was just pointing out that you did not even have to have patch
>> 1/5.
>
> Is that entirely accurate? The machinery (Makefiles, cmd-list.perl)
> does have to be updated at some point to skip the "common" block which
> get added in patch 2/5.

That is true, but if "# List of known git commands" instead of
[commands] were used as the separator line, 1/5 wouldn't have needed
any change to the Makefile.

Of course, if you need to add lines that would appear as junk to the
old parser (e.g. the grouping info), at that point you would of
course need to tell the parser to skip them.