search

alan-if / alan-docs

Alan IF Documentation Project
https://git.io/alan-docs
Other
3 stars 0 forks source link

Alan-Design: Fix Curly Quotes & Spelling #92

Closed tajmone closed 3 years ago

tajmone commented 3 years ago
thoni56 commented 3 years ago

Thanks for proof-reading! The only comment I have is that the "curly" quotes, meaning back-ticks, indicate "monospace" according to the AsciiDOC documentation, as far as I understand. And in most cases the quotes was not meant for "reserved words", but just as a quote, e.g. a backreference to word used in the previous sentence. So I feel those are incorrect changes. I could point to them exactly, but wanted to bring up the more general comment first.

tajmone commented 3 years ago

The only comment I have is that the "curly" quotes, meaning back-ticks, indicate "monospace" according to the AsciiDOC documentation, as far as I understand.

Usually in Asciidoctor's documentation the term "curly/curved quotes" refers to the generated punctuation marks being represented as “ ”/‘ ’ instead of as straight " "/' '; whereas Monospace refers to the typeface that will be used to represent the generated text:

Although they both rely on back-ticks, their use is quite different — monospace formatting will make the quotations marks disappear in the generated output (e.g. `IsA` → IsA).

And in most cases the quotes was not meant for "reserved words", but just as a quote, e.g. a backreference to word used in the previous sentence. So I feel those are incorrect changes. I could point to them exactly, but wanted to bring up the more general comment first.

I only tweaked manually picked (one by one, no search & replace) occurrences of those double quotes that were intended as part of speech, not code, so these changes won't affect the typeface (no monospace fonts) but just the punctuation marks; e.g.

source result
before sequences of "instructions" sequences of "instructions"
after sequences of "`instructions`" sequences of “instructions”

wherever single or double quotes are intended as speech, they should be curly, whereas if they are part of literal code they should be straight.

tajmone commented 3 years ago

The use of back-ticks in Asciidoctor can be tricky, due to constraint vs unconstrained pairing. E.g.

source result
so called "`friendly`" so called “friendly”
the `IsA` keyword | the IsA keyword
the "``IsA``" keyword | the “IsA” keyword
the `"key: value"` string | the "key: value" string
Joe`'s car Joe’s car

Even though back-ticks usage partly overlaps with the way they are used in Markdown, in many contexts AsciiDoc uses back-ticks differently.

But if you check the generated HTML document, I believe that my changes are in line with your original formatting intentions.

thoni56 commented 3 years ago

Right, sorry. I misinterpreted the diff, thought the double quotes where replaced, but now I see that the back-ticks was actually inserted. So, quite ok.