Re: [PATCH] asciidoctor-extensions: provide `<refmiscinfo/>`

From: Martin Ågren <martin.agren@gmail.com>
Date: Mar 19, 2019, 07:02 UTC
Message-ID: <CAN0heSrajiswzpm+au_5nmZMZG9406iZa-CK9p5CaHLTuxm8nw@mail.gmail.com>
In-Reply-To: <20190317194431.GY31362@pobox.com>

On Sun, 17 Mar 2019 at 20:44, Todd Zullinger <tmz@pobox.com> wrote:

Show 12 quoted lines

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

Show 8 quoted lines

> 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 -&#x2d. 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 "&#43;". 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