Re: [PATCH v2 0/2] asciidoctor-extensions: provide `<refmiscinfo/>`

[Jeff King <peff@peff.net>]

On Tue, Sep 03, 2019 at 08:51:19PM +0200, Martin Ågren wrote:

> Almost half a year ago, I wrote:
> > To be clear. *This* patch has a sufficiently incorrect commit message
> > that it really needs a makeover. You can expect a v2.
> 
> Finally, here's that v2. I should probably refresh memories: The goal of
> the main patch here is to make the headers and footers of our manpages
> built by Asciidoctor look a lot more like those generated by AsciiDoc.
> In particular, this gets rid of the ugly "[FIXME: source]".

Thanks for resuming this work. The patches both look good to me.

> I spent a little bit of time trying to work on the XML as XML, and
> quite a lot of time procrastinating on that. In the end, I decided that
> the outcome of my attempts wouldn't get better and that there is some
> value to the stupid approach from v1 of doing a simple search-and-replace
> in the text. I've preserved my attempts in the commit message.

I think your hack is better than introducing yet another dependency.
And because it's isolated and you've documented it well, it will be easy
to undo later if we choose.

The doc-diff tool should tell us if we catch any false positives inside
the text (though it seems quite unlikely to me).

> When I posted v1, it turned into quite a thread [1] on AsciiDoc vs
> Asciidoctor vs Asciidoctor 2.0 and differences in rendering. (I am on
> Asciidoctor 1.5.5.)

Yes, sadly I still can't format the docs at all with 2.0.10 (which is
what ships in Debian unstable).

> Among other things, the v1-thread discussed switching the rendering
> toolchain entirely to avoid the detour over xmlto. Doing that would
> render this patch obsolete. While I agree that such a switch is the
> correct long-term goal and that we can be fairly aggressive about it, I
> do also think it makes sense to first make the "softer" switch to
> Asciidoctor-by-default and get that particular hurdle behind us. Then,
> once we're ok with dropping AsciiDoc entirely, we can do the switch to
> an Asciidoctor-only toolchain.

Yeah, I do still like that as an endgame, but I like what you have here
as an intermediate step in the right direction.

> (I'm preparing a second, independent series of patches that should halve
> the difference (sans headers/footers) between these two engines -- at
> least the versions of them that I'm using. The remaining differences are
> then mainly, but not exclusively, in favor of Asciidoctor. That series
> should appear on the list within the next couple of days. After that,
> there's user-manual.html/pdf that needs looking into...)

Yay. :)

-Peff