Martin Ågren <martin.agren@xxxxxxxxx> writes:
> 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.
