On Wed, Jun 27, 2018 at 12:44:43PM -0400, Todd Zullinger wrote: > I wrote: > > Jeff King wrote: > >> (Related, there's a build target in the local Makefile for using > >> asciidoctor; does it need updated, too?) > > > > I didn't test asciidoctor specficially, but it also respects > > the ASCIIDOC_EXTRA parameters, so I think it will work just > > as well. I'll try to confirm that later today. > > Testing confirmed that asciidoctor works fine with this as > well. Thanks for checking. > Somewhat tangentially, I looked at using asciidoctor for the > Fedora packages last year and one issue that kept me from > using it then was the '[FIXME: source]' it includes in the > footer of the manpage. When I dug into it at the time, it > appeared this was due to no <refmiscinfo> declaration > (similarly missing for manual, and version). It wasn't > clear whether it was possible to include a custom header > template in plain asciidoctor. I got the impression that it > would require using a custom backend, which in turn required > the rubygem 'tilt' for processing. > > I spent about an hour poking around with it and decided that > I'd put off building with asciidoctor until that was fixed. > I felt that displaying '[FIXME: source]' wass worse than > simply not including the version. > > It's always possible that I was doing something wrong in my > use of asciidoctor (I just set USE_ASCIIDOCTOR). Or maybe > the Fedora packages are missing some dependency which I > missed. Hmm. I don't typically use asciidoctor locally (to be honest, I do not typically build the documentation at all locally, and just read the source when I need it). But just setting USE_ASCIIDOCTOR seems to work fine for me out of the box. I'm on Debian unstable, asciidoctor 1.5.7.1. At this point I think we still consider the original asciidoc as our officially supported platform, and mostly are happy if things also work with asciidoctor. But my impression is that there's no more development work happening on asciidoc, and the path forward will be asciidoctor. So at some point we may need to flip that. One nice thing about switching to asciidoctor fully is that it can do direct manpage generation. So we could eventually drop the docbook/xmlto dependencies (right now even with USE_ASCIIDOCTOR we still go through the xml step). > It might also be that we need some adjustments similar to > https://patchwork.kernel.org/patch/10360207/ to get the > mansource attribute passed on to asciidoctor. I only just > ran across that patch and haven't had a chance to test > sometime similar in the git manpage build. That looks > promising though. Yeah, we have to do similar tricks on git-scm.com to handle things like linkgit. Our implementation there is quite horrible (regex search and replace!). It would be wonderful if we could write real ruby snippets to handle extended cases, and then the git-scm.com doc builder could just reuse that logic instead of hackily reimplementing it. Anyway, that's all well outside the scope of your patch today, I think. :)
