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]". 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. 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.) 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. (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...) [1] https://public-inbox.org/git/20190317144747.2418514-1-martin.ag...@gmail.com/ Martin Ågren (2): asciidoctor-extensions: provide `<refmiscinfo/>` doc-diff: replace --cut-header-footer with --cut-footer Documentation/asciidoctor-extensions.rb | 15 +++++++++++++++ Documentation/doc-diff | 17 ++++++++--------- 2 files changed, 23 insertions(+), 9 deletions(-) -- 2.23.0
