Re: [PATCH] doc: substitute ETC_GIT(CONFIG|ATTRIBUTES) in generated docs

On Wed, Jun 27, 2018 at 12:44:43PM -0400, Todd Zullinger wrote:

I wrote:

quoted

Jeff King wrote:

quoted

     (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.
:)