| Message ID | cover.1620928059.git.martin.agren@gmail.com (mailing list archive) |
|---|---|
| Headers | show |
| Series | AsciiDoc vs Asciidoctor, once again | expand |
Martin Ågren <martin.agren@gmail.com> 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.
Martin Ågren wrote: > 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. These changes are good, but what happens the next time somebody inadvertedly introduces something that "trips" asciidoctor? We should be submitting bug reports to the asciidoctor project as well, so in the future it's less likely we find ourselves in the same scenario. Preferably the bug report should be in the commit message. Cheers.
On Thu, 13 May 2021 at 22:35, Junio C Hamano <gitster@pobox.com> wrote: > > Martin Ågren <martin.agren@gmail.com> writes: > > > 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. OK, calling it a dealbreaker is fair. Thanks. > 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. I've done some experimenting now with a new attribute "apos" which expands to a lone SQ. It seems to work fine across the different tools. The rule could be that all ' should be {apos}. That's a quite aggressive rule in a sense. It could be narrowed down to something like "... if the paragraph contains other quotation, such as backticks or single quotes", but that's probably just overly complicating things. I don't see an immediate need to go s/'/{apos}/ just because we can. We've identified five problematic spots, four of which are with the tool we're moving away from. Martin
On Fri, 14 May 2021 at 03:40, Felipe Contreras <felipe.contreras@gmail.com> wrote: > We should be submitting bug reports to the asciidoctor project as well, > so in the future it's less likely we find ourselves in the same > scenario. > > Preferably the bug report should be in the commit message. I don't have an account with the website they use for their issue tracking. If you want to submit a bug report and post the link here, that's fine by me and I'll include it in the reroll. Martin
Martin Ågren wrote: > On Thu, 13 May 2021 at 22:35, Junio C Hamano <gitster@pobox.com> wrote: > > > > Martin Ågren <martin.agren@gmail.com> writes: > > > > > 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. > > OK, calling it a dealbreaker is fair. Thanks. If I understood correctly the deal-breaker is as a long-term solution. These particular patches may be welcome right now to reduce the doc-diff, but eventually these issues should be fixed in asciidoctor. > > 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. > > I've done some experimenting now with a new attribute "apos" which > expands to a lone SQ. It seems to work fine across the different tools. > The rule could be that all ' should be {apos}. That's a quite > aggressive rule in a sense. It could be narrowed down to something like > "... if the paragraph contains other quotation, such as backticks or > single quotes", but that's probably just overly complicating things. I would rather fix it in asciidoctor (the ones that are actually asciidoctor issues)
Martin Ågren wrote: > On Fri, 14 May 2021 at 03:40, Felipe Contreras > <felipe.contreras@gmail.com> wrote: > > > We should be submitting bug reports to the asciidoctor project as well, > > so in the future it's less likely we find ourselves in the same > > scenario. > > > > Preferably the bug report should be in the commit message. > > I don't have an account with the website they use for their issue > tracking. GitHub? It probably takes a couple of minutes to set up an account. > If you want to submit a bug report and post the link here, > that's fine by me and I'll include it in the reroll. If you would rather have me act as a proxy, that's fine by me. Just give me a simple example that produces the issue. Cheers.
On Fri, 14 May 2021 at 14:24, Felipe Contreras <felipe.contreras@gmail.com> wrote: > > Martin Ågren wrote: > > On Fri, 14 May 2021 at 03:40, Felipe Contreras > > <felipe.contreras@gmail.com> wrote: > > > > > We should be submitting bug reports to the asciidoctor project as well, > > > so in the future it's less likely we find ourselves in the same > > > scenario. > > > > > > Preferably the bug report should be in the commit message. > > > > I don't have an account with the website they use for their issue > > tracking. > > GitHub? It probably takes a couple of minutes to set up an account. Yes, it's GitHub. I'm not interested in having an account there. There's some trade-off there with me not being able to report bugs, but that cuts both ways, so I don't feel bad about it. > > If you want to submit a bug report and post the link here, > > that's fine by me and I'll include it in the reroll. > > If you would rather have me act as a proxy, that's fine by me. Thanks. If you have better things to do, no worry. > Just give me a simple example that produces the issue. Here are three variants where AsciiDoc 8.6.10 renders the same, with emphasis: single quotes that will not render literally: 'git cat-file'. single quotes that won't render literally: 'git cat-file'. single quotes that\'ll render literally: 'git cat-file'. With Asciidoctor (2.0.15), asciidoctor -b docbook5 -d manpage -o test.xml test.txt the XML contains <simpara>single quotes that will not render literally: <emphasis>git cat-file</emphasis>.</simpara> <simpara>single quotes that won’t render literally: <emphasis>git cat-file</emphasis>.</simpara> <simpara>single quotes that’ll render literally: 'git cat-file'.</simpara> That last paragraph is not as expected. I expect <emphasis>. I realize that a good answer here is "don't do that then". But the background is that there's some other stuff going on that means AsciiDoc needs that backspaced apostrophe. So this is a minimal reproduction for Asciidoctor where we've lost some of the AsciiDoc-specific background. A fix that works with both tools is an attribute: :apos: ' single quotes that won{apos}t render literally: 'git cat-file'. Martin
Martin Ågren wrote: > On Fri, 14 May 2021 at 14:24, Felipe Contreras > <felipe.contreras@gmail.com> wrote: > > > > Martin Ågren wrote: > > > On Fri, 14 May 2021 at 03:40, Felipe Contreras > > > <felipe.contreras@gmail.com> wrote: > > > > > > > We should be submitting bug reports to the asciidoctor project as well, > > > > so in the future it's less likely we find ourselves in the same > > > > scenario. > > > > > > > > Preferably the bug report should be in the commit message. > > > > > > I don't have an account with the website they use for their issue > > > tracking. > > > > GitHub? It probably takes a couple of minutes to set up an account. > > Yes, it's GitHub. I'm not interested in having an account there. There's > some trade-off there with me not being able to report bugs, but that > cuts both ways, so I don't feel bad about it. I don't see what are those both ways, but OK. > > > If you want to submit a bug report and post the link here, > > > that's fine by me and I'll include it in the reroll. > > > > If you would rather have me act as a proxy, that's fine by me. > > Thanks. If you have better things to do, no worry. I do, but reporting bugs doesn't that *that* much time. > > Just give me a simple example that produces the issue. > > Here are three variants where AsciiDoc 8.6.10 renders the same, with > emphasis: > > single quotes that will not render literally: 'git cat-file'. > > single quotes that won't render literally: 'git cat-file'. > > single quotes that\'ll render literally: 'git cat-file'. > > With Asciidoctor (2.0.15), > > asciidoctor -b docbook5 -d manpage -o test.xml test.txt > > the XML contains I'm not talking about the XML, I'm talking about the man pages. I'm not interested in intermediary code, I'm interested in the final output, which does seem to work correctly: ruby -r asciidoctor <<\EOF puts Asciidoctor.convert(<<REOF, backend: :manpage) single quotes that will not render literally: 'git cat-file'. single quotes that won't render literally: 'git cat-file'. single quotes that\'ll render literally: 'git cat-file'. REOF EOF single quotes that will not render literally: \(aqgit cat\-file\(aq. single quotes that won\(cqt render literally: \(aqgit cat\-file\(aq. single quotes that\(cqll render literally: \(aqgit cat\-file\(aq. Cheers.