Compare AsciiDoc and Markdown • Hacker News Board

Re: Compare AsciiDoc and Markdown

#31

Post by globular-toast » Tue, Jul 06, 2021, 10:04 AM UTC

taftster wrote: post #2

I really like AsciiDoc and would encourage anyone to give it a try, especially for things like software documentation (in all forms). I very much despise the trend to write sharepoint or wiki/Confluence pages as a means for software documentation. I want my documentation to reside next to my source code, not at some obscure corporate URL. The problem is simply that github, gitlab, and friends adopted Markdown and so…

> I very much despise the trend to write sharepoint or wiki/Confluence pages as a means for software documentation. I want my documentation to reside next to my source code, not at some obscure corporate URL.

It wouldn't be so bad if Confluence/whatever could just render the Asciidoc from the source repository. But they are generally closed systems. There's no way in or out of Confluence without significant headaches.

Re: Compare AsciiDoc and Markdown

#32

Post by rm445 » Tue, Jul 06, 2021, 10:05 AM UTC

neetrain wrote: post #16

The worst part of AsciiDoc I think is its name. It sounds so archaic.

It does tend to make one worry that all the tools will be hideously un-unicode aware and mangle any non-ASCII documents.

I would like to imagine that in this day and age that isn't the case, but the name works against it.

Re: Compare AsciiDoc and Markdown

#33

Post by 0mp » Tue, Jul 06, 2021, 10:06 AM UTC

FreeBSD has recently switched from DocBook to AsciiDoc for its documentation: https://docs.freebsd.org/en/books/fdp-primer/asciidoctor-pri...

Markdown was also an option but it was missing too many features for a documentation set of this size.

Re: Compare AsciiDoc and Markdown

#34

Post by dnsmichi » Tue, Jul 06, 2021, 10:16 AM UTC

toastal wrote: post #22

encryptluks2 wrote: post #4

Earlier quoted context omitted.

There is nothing really preventing GitHub and others from implementing a AsciiDoc/tor converter. AsciiDoctor is already written in Ruby, which is probably what they use on the backend for Markdown conversion. Hugo supports it as well, and I'm sure there are other static site generators. I agree 100% about documentation on Confluence or Sharepoint. Seriously, will not even work at a company that is heavily invested in…

GitLab also support AsciiDoc. SourceHut unfortunately does not. You can go through the hoops of POSTing to its GraphQL API from CI a new README from any format to HTML.

You can also embed diagrams and flowcharts with Mermaid into Asciidoc, not only in Markdown.

https://docs.gitlab.com/ee/user/asciidoc.html#mermaid

Examples for Mermaid layouts in the GitLab handbook: https://about.gitlab.com/handbook/tools-and-tips/mermaid/

Re: Compare AsciiDoc and Markdown

#35

Post by oneeyedpigeon » Tue, Jul 06, 2021, 10:22 AM UTC

rm445 wrote: post #32

neetrain wrote: post #16

The worst part of AsciiDoc I think is its name. It sounds so archaic.

It does tend to make one worry that all the tools will be hideously un-unicode aware and mangle any non-ASCII documents. I would like to imagine that in this day and age that isn't the case, but the name works against it.

Particularly when the syntax bakes in things like support for converting certain ASCII sequences into Unicode characters [0]

[0] https://docs.asciidoctor.org/asciidoc/latest/text/quotation-...

Re: Compare AsciiDoc and Markdown

#36

Post by baby » Tue, Jul 06, 2021, 10:27 AM UTC

I just wrote an entire book in asciidoc and honestly I don't like a lot of the decisions and the syntax, the tooling is also quite messy and hard to use/configure.

Having said that, I'm not sure if there's really any alternative. If you need the extensibility and diff-ability of asciidoc, then you're probably going to have to use it. If you don't need it, stick with markdown.

EDIT: so that people get an idea, I use asciidoc because it provides callouts, sidebars, captions, figures, cross references, LaTeX (via hard-to-use plugins), themes, fonts, etc. when converting to pdf or epub, etc.

Re: Compare AsciiDoc and Markdown

#37

Post by conaclos » Tue, Jul 06, 2021, 10:32 AM UTC

ygra wrote: post #8

miohtama wrote: post #6

Earlier quoted context omitted.

Github already supports Restructured Text (reST) in READMEs, and some other markdown flavours. Do not know about AsciiDoc but looks interesting.

As can be seen here, GitHub renders Asciidoc just fine: https://github.com/asciidoctor/asciidoctor.js

According to GitHub Docs [1], GitHub supports several markup languages, including Markdown, AsciiDoc, Textile, ReStructuredText, Rdoc, Org, Creole, MediaWiki, and Pod.

[1] https://docs.github.com/en/github/managing-files-in-a-reposi...

Re: Compare AsciiDoc and Markdown

#38

Post by jokteur » Tue, Jul 06, 2021, 10:40 AM UTC

baby wrote: post #36

I just wrote an entire book in asciidoc and honestly I don't like a lot of the decisions and the syntax, the tooling is also quite messy and hard to use/configure. Having said that, I'm not sure if there's really any alternative. If you need the extensibility and diff-ability of asciidoc, then you're probably going to have to use it. If you don't need it, stick with markdown. EDIT: so that people get an idea, I use a…

This question may be a bit naive, but it comes from somebody who has never used asciidoc but used a lot of LaTeX to make reports, poster, presentations, ...

Why are you using asciidoc to write a book, instead of LaTeX ? I see the advantage of using this for documentation, but for an entire book ?

Re: Compare AsciiDoc and Markdown

#39

Post by qznc » Tue, Jul 06, 2021, 10:41 AM UTC

baby wrote: post #36

I just wrote an entire book in asciidoc and honestly I don't like a lot of the decisions and the syntax, the tooling is also quite messy and hard to use/configure. Having said that, I'm not sure if there's really any alternative. If you need the extensibility and diff-ability of asciidoc, then you're probably going to have to use it. If you don't need it, stick with markdown. EDIT: so that people get an idea, I use a…

RestructuredText (usually used within Sphinx) is the only alternative in the same class. Unfortunately there are hardly any comparisons. Maybe there are no people who have significant experience with both.

Re: Compare AsciiDoc and Markdown

#40

Post by qznc » Tue, Jul 06, 2021, 10:42 AM UTC

jokteur wrote: post #38

baby wrote: post #36

I just wrote an entire book in asciidoc and honestly I don't like a lot of the decisions and the syntax, the tooling is also quite messy and hard to use/configure. Having said that, I'm not sure if there's really any alternative. If you need the extensibility and diff-ability of asciidoc, then you're probably going to have to use it. If you don't need it, stick with markdown. EDIT: so that people get an idea, I use a…

This question may be a bit naive, but it comes from somebody who has never used asciidoc but used a lot of LaTeX to make reports, poster, presentations, ... Why are you using asciidoc to write a book, instead of LaTeX ? I see the advantage of using this for documentation, but for an entire book ?

My guess: To convert it into an ebook.