search

GlacierProtocol / glacierprotocol.github.io

the source for https://glacierprotocol.org
27 stars 26 forks source link

Consider asciidoctor instead of markdown #13

Open another-hodler opened 5 years ago

another-hodler commented 5 years ago

As mentioned in https://github.com/GlacierProtocol/glacierprotocol.github.io/pull/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:

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

bitcoinhodler commented 5 years ago

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.

another-hodler commented 5 years ago

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 commented 5 years ago

@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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

@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 commented 5 years ago

@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.