Re: [PATCH] doc: asciidoc: remove custom header macro

[Felipe Contreras <felipe.contreras@gmail.com>]

On Wed, Apr 5, 2023 at 11:22 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> Jeff King <peff@peff.net> writes:
>
> > On Thu, Mar 23, 2023 at 04:15:23PM -0600, Felipe Contreras wrote:
> >
> >> In 2007 we added a custom header macro to provide version information
> >> 7ef195ba3e (Documentation: Add version information to man pages,
> >> 2007-03-25),
> >>
> >> However, in 2008 asciidoc added the attributes to do this properly [1].
> >>
> >> This was not implemented in Git until 2019: 226daba280 (Doc/Makefile:
> >> give mansource/-version/-manual attributes, 2019-09-16).
> >>
> >> But in 2023 we are doing it properly, so there's no need for the custom
> >> macro.
> >>
> >> [1] https://github.com/asciidoc-py/asciidoc-py/commit/ad78a3c
> >
> > This should be OK to do, as it is just touching the python asciidoc
> > side. When we discussed those attributes in 2019:
> >
> >   https://lore.kernel.org/git/20190320183229.GK31362@pobox.com/
> >
> > asciidoctor support was new and incomplete. It needed v1.5.7 (from
> > 2018), and even today still does not seem to handle manversion. But
> > since this patch leaves in place the equivalent hack in
> > asciidoctor-extensions.rb, it will continue working.
>
> Sounds like the proposed log message can use a bit more polishing to
> help future readers of "git log", then.

Yes, *if* what Jeff King was saying were true, which is not. At least
not completely.

> But I think it is not required to be explicit about us leaving the
> asciidoctor side untouched to keep it working (in other words, we do
> not talk about things that we are not doing in our log message, unless
> it is so unnatural not to do them at the same time to warrant such an
> explanation).

I did explain that we could fix all the issues of this particular
problem for both asciidoc and asciidoctor as far back as 2021 [1].
This fix did not materialize in subsequent patches: [2][3][4][5][6].

But the fix exists, and it's explicitly explained (multiple times).

Basically: instead of trying to make docbook-xsl understand "$version"
in order to join it as "$source $version". We can just say
`source="$source $version"` and forget about $version.

I don't know how I can say it more clearly: we can fix all the
problems for all the tools and all their backends with one simple
patch.

So after 6 attempts I'm trying to change the strategy and only clarify
the problem for asciidoc.py, which hopefully is clear now. But it can
be fixed for asciidoctor as well...*today*.

Cheers.

[1] https://lore.kernel.org/git/20210514121435.504423-7-felipe.contreras@gmail.com/
[2] https://lore.kernel.org/git/20210515115653.922902-4-felipe.contreras@gmail.com
[3] https://lore.kernel.org/git/20210521223701.526547-4-felip01e.contreras@gmail.com/
[4] https://lore.kernel.org/git/20210608090026.1737348-4-felipe.contreras@gmail.com/
[5] https://lore.kernel.org/git/20210618215231.796592-420-felipe.contreras@gmail.com/
[6] https://lore.kernel.org/git/20210621163110.1074145-4-felipe.contreras@gmail.com/

-- 
Felipe Contreras