Fix formatting

[spotlesscoder]

No description provided.

[ben]

🤔 We only set a name in monospace if it's a literal term used in a code editor or a terminal. I don't know SVN that well, but my google-fu doesn't turn up any use of a peg-revision literal. If I'm right, we should change this to ``peg revisions''.

[spotlesscoder]

The problem with the old revision was that all text starting with ``peg-revisions'' was displayed as an inline code-block because the code block marks were not ended properly

[ben]

That may be true with the GitHub asciidoc renderer, but that's not our main front-end. The HTML version that renders on git-scm.com looks like this:

And the PDF version looks like this:

Both of which are exactly what we want.

I do wonder if the GitHub renderer would agree with the other outputs if we used the "`newer syntax`" mentioned in the Asciidoctor documentation.

[max123kl]

I already mentioned a similar issue in this comment.

[spotlesscoder]

So which of the mentioned alternatives would you suggest, @max123kl

[max123kl]

Unfortunately, this depends on the editor and/or the operating system used.
For macOS and Windows you can use the following table.

The complete list can be found here (look for quotation and/or punctuation)
On Linux machines you can program a keyboard shortcut or copy+paste the Unicode special characters from a second file.

[spotlesscoder]

On Linux you can hold right Ctrl+right Shift+u and then type x201C
Its a bit painful but works

[ben]

I already mentioned a similar issue in this comment.

And in that thread I mentioned that I don't want to adopt "frozen" curly quotes in the source code for this book:

In the end, it's much easier for new contributors to type the standard ASCII characters, regardless of their keyboard layout, OS, or editor, so we should stick to either the old (``quote'') or new ("`quote`") Asciidoc notation.

To that end, please replace this change with ``peg revisions''. That's consistent with our current style, and renders properly everywhere but on GitHub, which is not a recommended way to read the book.

[max123kl]

I do respect your decision in this repo.

But I don't think I understand what you mean by "frozen". Is anything be blocked or locked?

The key code I do propose in my last post will produce the typographically correct quotes, not the straight ones. That's what you want, isn't it?

Because the punctuation (quotation marks) in German, as well as in other foreign languages, is visually different from here, you have to find an alternative, working solution.
Fortunately, the UTF-8 code offers all required characters. So you can, without conversion via the text editor, get the desired characters by key code.

In the German Repo I implemented my suggestion and didn't detect any error in any of the important output formats. On the other hand, the GitHub renderer also displays the quotation marks correctly.

DE_quotation_HTML

DE_quotation_PDF

DE_quotation_ePub

DE_quotation_mobi

DE_quotation_GitHub

[ben]

I don't think I understand what you mean by "frozen".

I just mean that the "curliness" of the quotation mark is embedded in the choice of utf-8 character, where the "` notation makes a source-code token that renders to a curly quote.

We did the opposite of what you're doing in your repo with en- and em-dashes a while back; the literal "–" character was un-rendered to -- in the source code so it would be easier to type, and harder to mistake for a hyphen.

I like having source code that can render to a configurable target character. If we decide to convert all dashes to hyphens in the future, we can do that in the renderer. If we decide we want all quotation marks to be straight, we can do that without having to sed through the entire source code.

Oh, and as it turns out, the GitHub renderer handles the "`new style`" notation properly.

[max123kl]

the literal "–" character was un-rendered to -- in the source code

That's not correct. The literal character you are showing is an en-dash, but if you enter -- in the source code, it will be rendered to an em-dash, as described in the Asciidoctor manual here.
For English texts the use of -- is correct anyway, because the em-Dash should be used there. In German texts the en-dash must be used instead. The render code that the Asciidoctor manual suggests is– (see the table here).
It's true, in text editors the en-dash is visually hard to identify from the simple dash or hyphen. Therefore, it makes sense to perform a "search&replace" pass.

Oh, and as it turns out, the GitHub renderer handles the "new style" notation properly.

That's wonderful for English writing.
In the table from my second last post the left character is also called "high 66" and the right one " high 99".
In German texts we use another character for the left, opening quotation mark (for which I found no code in the Asciidoctor manual).
The right, closing quotation mark “ is the same character ("high 66") as the left, opening quotation mark in English texts.
If I now follow your proposals in German texts, the renderer will recognize the correct "high 66" quotation mark at first. But it expects a closing character afterwards. Then the second time it is used, it will decode to the wrong closing "high 99" quotation mark.

This is one the main reasons why I prefer using the UTF-8 code, by keyboard shortcut, you call "frozen", as long as the files are used for printed texts.
In the case of program code, this is certainly a different thing.

[spotlesscoder]

You can ping me if you have agreed on a solution ;)

[jnavila]

Just to chime in (a bit late), I'm working on making the book compilable with asciidoctor 2.0.10, so we have to switch to the new syntax, which basically makes me sed through the source code. So in the end, we are tied to possible evolutions of the renderer. I would tend to agree with @max123kl that we should use full unicode source, because that way, we rely only on the coding system, not on possibly evolving publishing tools.