Re: [PATCH] doc: simplify man version

[Jeff King <peff@peff.net>]

On Sat, Apr 08, 2023 at 03:45:48PM -0700, 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, 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 [*].

I think we are OK with this patch on its own. Asciidoc seems to be smart
enough to omit the empty XML element on its own. Asciidoctor isn't (and
nor is ruby hack which adds it in), but docbook is essentially just
concatenating them anyway. Either way, the generated roff looks like:

  .TH "GIT" "1" "2023\-04\-06" "Git 2\&.40\&.0\&.316\&.g67fafd" "Git Manual"

(the first "GIT" is the command name, so this is from git.1).

I do think we probably want to pair this with another patch removing the
asciidoctor-extensions hack, but the reasoning there is separate (it was
needed for some older versions that we can probably declare as "too old"
now).

-Peff