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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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



[Index of Archives]     [Linux Kernel Development]     [Gcc Help]     [IETF Annouce]     [DCCP]     [Netdev]     [Networking]     [Security]     [V4L]     [Bugtraq]     [Yosemite]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Linux SCSI]     [Fedora Users]

  Powered by Linux