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

From: Martin Ågren <martin.agren@gmail.com>
Date: Mar 22, 2019, 21:01 UTC
Message-ID: <CAN0heSpJvsPm_qq63VumokmyOG6N=6fwMZRqf_9CzoCeHsdiyQ@mail.gmail.com>
In-Reply-To: <20190320181715.GJ31362@pobox.com>

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

Show 12 quoted lines

> Martin Ågren wrote:
> > {litdd} now renders as &#x2d;&#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`.
>
> I noticed that one and didn't work out a good fix, but it
> sounds like you have one in mind.  That's great.
>
> > "+" becomes "&#43;". I didn't immediately find where we do that.
>
> For this one, I was working on replacing "{plus}" with `+`
> (along with " " and "-").  That's probably not ideal though.

The "plus" and "litdd" issues seem like they can be solved by doing:

  ASCIIDOC_EXTRA += -aplus='+'
  ASCIIDOC_EXTRA += -alitdd='\--'

Show 21 quoted lines

> > `./doc-diff HEAD^ HEAD` shows how several "git-\nfoo" become
> > "\ngit-foo", i.e., linkgit expansions are now treated as non-breaking.
> > [...] Hmm, was this
> > why you increased MANWIDTH?
>
> Yeah, I noticed a number of places where asciidoc and
> asciidoctor wrapped lines at slightly different places.  I
> didn't see if they were all due to wrapping at a dashed git
> command, but that could certainly have been the main cause.
>
> I set the large MANWIDTH and then I think I added
> --color-words to the diff call in doc-diff.
>
> > 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. ;-)
>
> Oh my yes, I'm sure. :)

:)

Using origin/ma/doc-diff-doc-vs-doctor-comparison, you can do something like

  ./doc-diff --asciidoctor --cut-header-footer foo bar --
--ignore-space-change --word-diff

to reduce the amount of noise in the diff by a great deal. Going through the result, I noted two issues which should be fixed by Asciidoctor 1.5.7, according to some initial searching (but I haven't tested):

"--" renders as an em dash followed by a ";". Looks like it's https://github.com/asciidoctor/asciidoctor/issues/2604

"&" turns into "&". Seems to be known and fixed: https://github.com/asciidoctor/asciidoctor/issues/2525

Plus a few other problems. There's the odd problem here and there, but most of the diff seems to be a large number of occurences of just a few issues.

It would probably be worthwhile to try 1.5.7+ to see how much that improves things. Seems like you're already underway there.

Martin