Consider asciidoctor instead of markdown

[another-hodler]

As mentioned in #11 I would like to start discussion whether Markdown should be replaced by AsciiDoc. AsciiDoc has following advantages over Markdown:

1. It supports conversion to HTML and PDF out of the box. Current solution with weasyprint can be avoided.
2. It supports includes. Current catmd solution can be avoided.
3. Rich editor AsciidocFX is available.

I played with it for a while and I liked PDF export quite a lot. There is a difference between native and AsciidocFX PDF export though. Native is more like from web, AsciidocFX uses DocBook in between so result looks more like a book - footnotes are back! :-) Please see example below.

Example:

• source for verify.adoc - https://gist.github.com/another-hodler/717a3bb71c0a5c52d9b42833f93b23d8
• exported PDF from AsciidocFX - http://ge.tt/6g4Sumr2

If we decide AsciiDoc is a way to go I can start working on the conversion. What needs to be investigated is:

• Highlighting as used for critically- and moderately-sensitive data.
• Full site HTML export as required for https://glacierprotocol.org/

[bitcoinhodler]

Leaving aside the sloppy conversion from Google Doc (see #7) there's several issues I have with the current PDF doc as compared to the old format. If Asciidoc (or anything) will improve these, then I'm all for it.

• The TOC has no page numbers
• Footnotes are gone, now cluttering up the main text instead
• Missing screenshots

[another-hodler]

Started the conversion work. My current work-in-progress document looks like this - http://ge.tt/8cNSyts2 (some pages are not yet formatted properly). You can see the overall document layout with chapter / section numbering, headers, footers, footnotes and links. Feedback is welcome.

Now I will focus on Jekyll and static web generator to check that it is usable with asciidoctor.

[another-hodler]

@Doweig Can you please explain your reasons for thumb down? Do you have any previous experience with asciidoctor or why do you think we should not follow this path? Thank you!

[bitcoinhodler]

Started the conversion work. My current work-in-progress document looks like this - http://ge.tt/8cNSyts2 (some pages are not yet formatted properly). You can see the overall document layout with chapter / section numbering, headers, footers, footnotes and links. Feedback is welcome.

I like it. Obviously there is a lot of work to do but I think it has better potential than the current system.

[bitcoinhodler]

One request. Perhaps you're already doing this, but please keep a strict separation between formatting changes and substantive changes, if any. Each Git commit should be strictly one or the other, to facilitate review.

[another-hodler]

Correct, I am not performing any changes in the protocol content. It is formatting only. If I make any content change, I will explicitly mention it in the PR.

[bitcoinhodler]

Softcover is a publishing system based on Markdown that can easily generate both PDF and HTML. It might make for an easier conversion, since the doc is already Markdown.

[Doweig]

@another-hodler The reason for my thumb down is that I'm opposed to unnecessary complication. Markdown is wild spread and well known, easy to learn and use, natively supported on github, does the job.

[bitcoinhodler]

@Doweig except it is not doing the job. The PDF is the primary, canonical doc for Glacier, and it is currently in a bad state due to this incomplete and sloppy doc format conversion done last spring. Footnotes and screenshots are missing, command lines are truncated, etc.

If we can find a way to create a PDF with equivalent (or better) functionality to the 0.91 release (which came from Google Docs) using only Markdown, I would prefer that, but so far that doesn't seem possible.