Re: [PATCH 0/6] AsciiDoc vs Asciidoctor, once again

From: Junio C Hamano <gitster@pobox.com>
Date: May 13, 2021, 20:35 UTC
Message-ID: <xmqqsg2q9xts.fsf@gitster.g>
In-Reply-To: <cover.1620928059.git.martin.agren@gmail.com>

Martin Ågren <martin.agren@gmail.com> writes:

Show 17 quoted lines

> These patches reduce
>
>   ./doc-diff --from-asciidoc --to-asciidoctor --cut-footer HEAD HEAD
>
> from ~1200 to ~1000 lines. It's the usual mix of things where one or the
> other of the tools renders something less well, or where we're doing
> something odd in the source and we just happen to notice it in the diff.
>
> My ulterior motive here is to have a smaller doc-diff when I post a
> patch to switch the default to Asciidoctor (with xmlto), so that it gets
> a bit easier to reason about. But if everybody gets prettier docs,
> that's also good.
>
> Some of these rephrase wording such as "other peoples' commits" to avoid
> that apostrophe at the end of a word. I'm hoping those rephrasings don't
> regress the quality of the text -- if they do, I'll be happy to try
> something else.

It is sad, but we really should try "something else", unfortunately.

I do agree with the "motive" very much---even though condensing it down to plain text before running comparison already loses too much information, doc-diff is the only tool we currently have to effectively review regressions in rendered document, and the proposed transition cannot be done safely with confidence without being able to vet the differences. I am happy to hear about 17% reduction already, but the requirement to rewrite things like "other peoples' commits" is a dealbreaker.

I am not so worried about the existing text you rewrote in these patches. I however do not want to see asciidoc(tor) dictating use of a strange dialect of English when we write new documentation or update existing ones by imposing rules like "you are not allowed to use apostrophe-es to express possessive, and instead use 'of'"; it will become a continuing burden for anybody who writes documentation for us.

A typesettig rule like "instead of double-dashes --, use {litdd}" is an acceptable way out. At least that wouldn't constrain what the final product that gets delivered to the end-users can say.

Thanks.