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

From: Jeff King <peff@peff.net>
Date: Apr 6, 2023, 07:19 UTC
Message-ID: <20230406071914.GA2143526@coredump.intra.peff.net>
In-Reply-To: <CAMP44s2u4tj7hUZHZ9H4qsJGp1a=Y=YUTBAxmSzftdfHX_HqwQ@mail.gmail.com>

On Thu, Apr 06, 2023 at 01:18:36AM -0500, Felipe Contreras wrote:

Show 17 quoted lines

> > 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?

I don't know of any particular reason why we couldn't put both in the source field.

I had forgotten we discussed this 2 years ago.

Show 10 quoted lines

> >   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].

You say "insist" like somebody is arguing for it. It looks like the series you linked got some review comments, and you followed-up. I didn't carefully read the re-rolls (then or now), but the original patches seem like a good direction to me.

Looking at the timing in the archive, I suspect that inter-personal drama in other threads caused people not to read those re-rolls.

At any rate, I don't think any of that needs to hold up this patch, which is not touching the asciidoctor side at all (I only wondered while reviewing it what the implications might be).

-Peff