Re: [PATCH] doc: simplify man version

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

Felipe Contreras <felipe.contreras@gmail.com> writes:

> Junio C Hamano wrote:
>> Felipe Contreras <felipe.contreras@gmail.com> writes:
>> 
>> > diff --git a/Documentation/Makefile b/Documentation/Makefile
>> > index a6ba5bd460..4721b000c1 100644
>> > --- a/Documentation/Makefile
>> > +++ b/Documentation/Makefile
>> > @@ -150,8 +150,7 @@ ASCIIDOC_HTML = xhtml11
>> >  ASCIIDOC_DOCBOOK = docbook
>> >  ASCIIDOC_CONF = -f asciidoc.conf
>> >  ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \
>> > -		-amanversion=$(GIT_VERSION) \
>> > -		-amanmanual='Git Manual' -amansource='Git'
>> > +		-amanmanual='Git Manual' -amansource='Git $(GIT_VERSION)'
>> >  ASCIIDOC_DEPS = asciidoc.conf GIT-ASCIIDOCFLAGS
>> >  TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)
>> >  TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK)
>> 
>> Is this a complete patch,
>
> Yes it is complete.

Good.

> I don't know know what could give this impression, given that a link to
> the documentation and the link to the source code was given:
> ...
> The code clearly tests for empty strings:
>
>   test="not($Name = '') and not($Version = '')

This part is exactly what I meant.  The readers of "git log"
shouldn't have to dig to external source material and find that
line to convince themselves why this is safe thing to do.

> And it's not clear to me what else it would be checking for.

Good.  The job of reviewers is not about nitpicking, but work with
and help a patch author to polish the patch text (both proposed log
message or diff) by pointing out what the author may have thought
obvious to everybody, because it was obvious to the author, but may
not be so obvious.  The goal is not to convince reviewers how the
patch text is correct in review discussion thread.  The goal is to
use reviewers' input to identify such parts of the patch text that
needs clarifying and update the patch text.  It is to avoid future
readers of "git log -p" to ask the same question, because unlike
reviewers, they will not have the original author readily available
to answer their questions.

Thanks.