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

["Sébastien Guimmara" <sebastien.guimmara@gmail.com>]

On 05/15/2015 10:26 PM, Junio C Hamano wrote:
> Sébastien Guimmara  <sebastien.guimmara@gmail.com> writes:
>
>> diff --git a/Makefile b/Makefile
>> index 25a453b..0cb2045 100644
>> --- a/Makefile
>> +++ b/Makefile
>> @@ -2454,7 +2454,7 @@ check-docs::
>>   		esac ; \
>>   		test -f "Documentation/$$v.txt" || \
>>   		echo "no doc: $$v"; \
>> -		sed -e '/^#/d' command-list.txt | \
>> +		sed -e '1,/^\[commands\]/d' -e '/^#/d' <command-list.txt | \
>>   		grep -q "^$$v[ 	]" || \
>>   		case "$$v" in \
>>   		git) ;; \
>> @@ -2463,6 +2463,7 @@ check-docs::
>>   	done; \
>>   	( \
>>   		sed -e '/^#/d' \
>> +		    -e '1,/^\[commands\]/d' \
>>   		    -e 's/[ 	].*//' \
>>   		    -e 's/^/listed /' command-list.txt; \
>>   		$(MAKE) -C Documentation print-man1 | \
>> diff --git a/command-list.txt b/command-list.txt
>> index 54d8d21..caed872 100644
>> --- a/command-list.txt
>> +++ b/command-list.txt
>> @@ -1,5 +1,6 @@
>>   # List of known git commands.
>>   # command name                          category [deprecated] [common]
>> +[commands]
>>   git-add                                 mainporcelain common
>>   git-am                                  mainporcelain
>>   git-annotate                            ancillaryinterrogators
>
> This is largely just a "taste" thing, but with all these backslashes
> in the supporting infrastructure you had to add in Makefiles and
> scripts, don't you think the choice of the way you designed the
> format to use '[commands]' was a rather poor one?  After all, all
> you need is a clear separator line for a block of commands and
> another block of groups, and there wasn't a reason why you needed to
> use square brackets for that, and the sed scripts are suffering from
> that poor choice.
>
> 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.