On Sun, 17 Mar 2019 at 20:44, Todd Zullinger <tmz@xxxxxxxxx> wrote:
> Martin Ågren wrote:
> > * Provide the `mansource` attribute to Asciidoctor. This attribute
> > looks promising until one realizes that it can only be given inside
> > the source file (the .txt file in our case), *not* on the command
> > line using `-a mansource=foobar`. I toyed with the idea of injecting
> > this attribute while feeding Asciidoctor the input on stdin, but it
> > didn't feel like it was worth the complexity in the Makefile.
>
> I played with this direction before. Using Asciidoctor we
> can convert directly from .txt to man without docbook
> and xmlto. That does have some other issues which need to
> be worked out though. Here's what I had as a start:
> +ASCIIDOC_EXTRA += -a mansource="Git $(GIT_VERSION)" -a manmanual="Git Manual"
So to be honest, I still don't understand how this works, but it does,
great. I really need to improve my documentation-reading skills.
> I munged up doc-diff to set MANDWIDTH=1000 and set one
> branch to default to asciidoctor to compare. (Your other
> recent series looks like it'll make doing asciidoc and
> asciidoctor comparisons easier.)
>
> There were a number of differences that I didn't work
> through though. Most importantly was the change in the
> links noted in the commit message.
I had some more time to look at this. Thanks for getting started on this
switch. A few things I noticed:
{litdd} now renders as --. We should find some other way to
produce '--'. This should then be a simple change, as we're already
providing this attribute inside an `ifdef USE_ASCIIDOCTOR`.
"+" becomes "+". I didn't immediately find where we do that.
Backticks should result in monospace.
`./doc-diff HEAD^ HEAD` shows how several "git-\nfoo" become
"\ngit-foo", i.e., linkgit expansions are now treated as non-breaking.
That's arguably good, but it brings some noise to the diff. Maybe one
should try and see if it's possible to break that to have a nicer
diff, then remove that breakage in a follow-up commit. Or, if it's
possible to make "git-foo" non-breaking before the switch. Hmm, was this
why you increased MANWIDTH?
A double-space between sentences turns into a single space -- at least
in constructions such as "... to foobar. `git-foo` does ...". Not a
problem perhaps, but noise in the diff.
And I'm sure there's more lurking in that huge diff. Whether any of that
is significant or not is another matter. ;-)
Martin
