Re: [PATCH] doc: simplify man version

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

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, or will this leave us in an incomplete
in-between place?

We have some references to manversion in "git grep manversion
Documentation/" in asciidoc.conf and asciidoctor-extensions.rb
remaining after this ptach is applied, which presumably are no
longer used.  I would imagine that these leftover references end up
substituting them with something benign, like an empty string, in
the output, but it somehow makes me feel dirty [*].

Other than that, I like the simplification of requiring only two
pieces of information to convey the same information that we are
attempting to (and to some backends, failing to) give with three
pieces of information.


[Footnote]

* If I am not guessing correctly how the result of applying this
  patch works in the above "I would imagine ..." that led to my
  possible misunderstanding of feeling "dirty", it would be a sign
  that the proposed log message is not explaining sufficiently and
  deserves an update.  Even just saying "... and when they join the
  `source` and `version`, if `version` is left empty or unspecified,
  the resulting document would not show any extra whitespace.  So it
  is safe to do the joining ourselves and stuff the result in the
  `source` field" or something would be sufficient, I would imagine,
  in order to help the future readers of "git log" that there is no
  need to "feel dirty" the same way I did.