Re: [RFC suggestion] Generate manpage directly with Asciidoctor

From: Jeff King <peff@peff.net>
Date: May 8, 2021, 03:23 UTC
Message-ID: <YJYERMX0OZI6DEWR@coredump.intra.peff.net>
In-Reply-To: <YJYBOrm2cQkkVteb@coredump.intra.peff.net>

On Fri, May 07, 2021 at 11:10:50PM -0400, Jeff King wrote:

Show 16 quoted lines

> On Fri, May 07, 2021 at 11:57:32PM +0000, brian m. carlson wrote:
> 
> > It's not quite that simple.  It requires changes to
> > asciidoctor-extensions.rb and we also need to consider
> > NO_MAN_BOLD_LITERAL and GNU_ROFF.  The latter especially is likely to be
> > inconvenient, since according to the Makefile, it's impossible to write
> > man output that works across troff versions.
> > 
> > We will also want to preserve the ability to use xmlto because we
> > currently have doc-diff which helps us find divergences in the behavior
> > of AsciiDoc and Asciidoctor, many of which affect all formats, and that
> > will be completely useless if we use two different rendering toolchains.
> 
> Speaking of doc-diff: with that patch applied, try "./doc-diff
> --asciidoctor HEAD^ HEAD", which shows quite a few of the complications
> (another one seems to be that all of the linkgit macros are broken).

Hmph. Actually, this seems to give inconsistent results. There definitely is a problem. Try:

  cd Documentation
  make USE_ASCIIDOCTOR=1 git.1
  man -l git.1 >old
  git am .../the_patch
  make USE_ASCIIDOCTOR=1 git.1
  man -l git.1 >new
  diff -u old new

which shows it. I think the patch does not specify the dependencies to make correctly (and doc-diff reuses the worktree to avoid work). Doing this:

  git am .../the_patch
  ./doc-diff --asciidoctor HEAD HEAD
  ./doc-diff --asciidoctor HEAD^ HEAD

works around it and shows the extent of the problem.

(Not really a critique on the patch, which I know was meant to be a quick illustration, but I thought it worth pointing out a doc-diff command which actually works).

-Peff