search

0xAX / linux-insides

A little bit about a linux kernel
http://0xax.gitbooks.io/linux-insides/content/index.html
Other
29.86k stars 3.35k forks source link

Asciidoc vs gfm #185

Closed kostaz closed 9 years ago

kostaz commented 9 years ago

Hi guys,

Why not to use asciidoc instead of gfm? Good example is Bitcoin book (https://github.com/aantonop/bitcoinbook).

Thanks, --- KostaZ

kylemanna commented 9 years ago

Primary benefits?

kostaz commented 9 years ago

... found none ... :-(

rastus-vernon commented 9 years ago

The primary benefit is that AsciiDoc was designed to be converted into DocBook the same way Markdown was designed to be converted into HTML. DocBook is a very superior format to HTML for technical books, because it was made specifically for creating technical documents, and the DocBook XSL stylesheets can produce high quality output in EPUB, PDF, HTML and multiple other formats from a DocBook document written using a semantic XML vocabulary (which has all the other advantages related to separation between presentation and content). DocBook documents aren't easy to write by hand, but AsciiDoc makes it as easy as writing Markdown, and thus it's possible to have the advantages of Markdown with the advantages of DocBook.

I can't claim these advantages are worth converting the whole book to a new format, however. There are tools like Pandoc that can convert from Markdown to AsciiDoc, but it requires some manual cleanup and DocBook publishing toolchains are confusing.

kostaz commented 9 years ago

What about visual diagrams? Can AsciiDoc convert text diagram to visual image (PNG e.g.)?

kostaz commented 9 years ago

I mean visual diagram could be a real boost to the documentation of as complex project as Linux Kernel!

0xAX commented 9 years ago

Hello all, The reason why I write this book with markdown is simple, I know it and I do no see no one reason to write it in other formats. If you version in EPUB, PDF you can find it on gitbook page - https://www.gitbook.com/book/0xax/linux-insides/details