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

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

On Wed, Apr 5, 2023 at 10:57 PM Jeff King <peff@peff.net> wrote:
>
> 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),

Except that isn't true.

The `manmanual` and `mansource` attributes were supported since day 1
[1], back in 2015 and included in v1.5.3. But for the manpage backend,
which we refuse to use.

It's true they were added in 2018 and in v1.5.7 for the docbook5
backend [2], which is what we use when we do USE_ASCIIDOCTOR=y, but we
could have used the manpage backend instead, which already had support
for that 3 years prior.

> and even today still does not seem to handle manversion.

Why do we need `manversion`?

All that it's used for is in the DocBook Stylesheets to join the
source name and the version, even its own documentation explains what
it looks like in practice [3]:

  In practice, there are many pages that simply have a version number
in the "source" field. So, it looks like what we have is a two-part
field, Name Version

So if we have `source="Git"`, and `version="2.4.0"`, we can just have
`source="Git 2.40.0"`.

Why do we have to split that information only for the DocBook
Stylesheets to join it in?

>   Aside: If we think asciidoctor 1.5.7 is recent enough to rely on, then
>   we might want to simplify our hack to just output manversion.

There is no need for any hack: we can just set the "mansource"
attribute to "Git $(GIT_VERSION)", and everything will work correctly
for both asciidoc and asciidoctor in all backends.

Why do we insist on hacks for asciidoc.py/2007 and asciidoc|docbook5/2017?

Especially when I sent the fix for *everything* in 2021 [4].

This is absolutely no reason to complicate the joining of two strings this much.

Cheers.

[1] https://github.com/asciidoctor/asciidoctor/commit/7bddc416
[2] https://github.com/asciidoctor/asciidoctor/commit/6b07b0ba
[3] https://docbook.sourceforge.net/release/xsl/current/doc/common/template.get.refentry.source.html
[4] https://lore.kernel.org/git/20210514121435.504423-7-felipe.contreras@gmail.com/

-- 
Felipe Contreras