There are so many markup languages and conversion possibilities, just have a look on the to-from option from pandoc.
Personally, I prefer reStructuredText, its design feels more consistent in comparison to the ambiguous implementations of the various markdown dialects.
In Asciidoc, I do not like that lower lever headings occupy more markers than higher level ones. Visually,
There's a couple reasons why I think it would be bad if higher level headings would be considered more important. First, in HTML, <h1> is the top heading which directly maps to
= heading
If you were to do it the other way around, there's no easy way to know which would would map to h1
======= this?
============= this?
The second reason why is because you have to have a baseline of maximum-importance. It's like ticket priorities capping out at P0 for maximum priority. The first intuitive thought would be that P5 should be more important than P0, but if you don't set a baseline of maximum importance, then there will always be someone who feels their thing is slightly more important.
========== Top level heading
=========== Super top level heading
============== Extra super top level heading deluxe
Another argument in favor of adding markers for lower levels is that indenting the first character of a header typically indicates lower level headings in a table of contents.
# Chapter 1
Lorem ipsum dolor sit amet.
## Section 1a
Lorem ipsum dolor sit amet.
## Section 1b
Lorem ipsum dolor sit amet.
# Chapter 2
Lorem ipsum dolor sit amet.
## Section 2a
Lorem ipsum dolor sit amet.
Concerning the baseline, doesn't the HTML5 standard just specify 6 ranks from <h1> … <h6>? Would be at least a candidate for common agreement on the lowest (highest) rank.
I think this is a bikeshedding criticism more than something that requires serious concern. Asciidoctor simply supports more out-of-the-box and officially than reStructuredText. Preferring reStructuredText to Asciidoctor this way is like comparing Python to Ruby for syntax alone. Function is just as important.
In Asciidoctor, I can:
* Use GraphViz (and other diagram) docs to describe architectural components.
* Actually test my example code, using named, delineating comments in my test suite and including the code between those comments as an example in my file.
* Support for WARNING, NOTE, etc. callout "admonitions"
* Auto-numbered list blocks with "."
Some of these may be possible with reStructuredText, and can definitely be supported with third party plugins, but all of this is first-party and amazing.
Note: IntelliJ's Asciidoctor plugin is incredible and it live renders mathematical equations AND graphing support in addition to everything else.
"AsciiDoc is a human-readable document format, semantically equivalent to DocBook XML, but using plain-text markup conventions."
And Asciidoctor is a toolchain for working with AsciiDoc.
One thing to have in mind is that AsciiDoc syntax is incredibly complex [1]: it maps to the already complicated-on-its-own-right DocBook standard [2]. It has a lot of bells and whistles that one may want to use on a real print book, but maybe not for general documentation.
I feel like if you are not writing something that you actually intend to print, Asciidoc (and DocBook) are overkill.
I've written my book in Asciidoc [1]. It's a brilliant tool and far more powerful than Markdown but it does have some quirks (for example, you need to escape "C++").
Asciidoc has many more feature and as easy to use as Markdown. Markdown definitely does the job for very quick documentation, but when it comes to more in depth documentation I've found asciidoc to be much better.
I'll use an example: I often need to create "Warning Notes" (aka "Admonitions") in my documentation. Those notes need to stand out, but they also need to not break the flow of reading. I need them to be visible, but easy to spot with the eye and ignore. It makes reading the doc and ignoring less important information easier. With Markdown, I can't create those notes.
Other interesting and useful thing is the ability to use variables. This allows me to make the documentation dynamic. Imagine, for example, a documentation that has many CURL requests examples that must include an X-Auth-Token. I can dynamically generate the documentation with the Auth-Token of the user reading the doc, allowing them to Copy/Paste the examples without having to modify them first.
FWIW, I use a macro processor with markdown. Markdown supports arbitrary inline HTML, which makes it very convenient to use like this. You can create a macro for the warning box. I have another one to insert not just code snippets, but the result of running the code snippet.
I've used asciidoc before, and I don't recall it having arbitrary programmability? I'd be interested in how that works.
Can you please elaborate on how exactly you create the macros? I started using asciidoc because I could not find a neat way of embedding code snippets (stored in separate file) into markdown text. Asciidoc has this as built in feature.
This is one of my favorite features, too. I've found it works amazing when you generate the documentation or render it locally. Unfortunately, it doesn't work in "safe" mode sites like GitHub or GitLab where having a lightweight include feature for samples or tests would be useful.
For macros in AsciiDoc, I've made do with the little bit of support mentioned at https://asciidoctor.org/docs/user-manual/#pass-macros . Everything I found for Markdown always required an additional tool or "something else". I like that AsciiDoctor, for the most parts, has nearly everything I want built-in.
I'm not suggesting this as the right solution, but I wrote a lot of assignments for my MSc with Markdown + build scripts + a heavy amount of Perl.
Variously this did things like running embedded unit tests in code examples, validating XSL schemas, making sure GraphViz images were created and up-to-date, running a Z-Notation type-checker, and code that created both SQL and Relational Algebra from a simplified SQL-like DSL.
I'm not saying this is a superior approach to AsciiDoc, just that it's amazing what you can create when you turn your mind to avoiding working on your MSc assignments and let your OCD about creating perfect assignments run wild.
I wrote a script which preprocesses the .md file, passes certain sections to shell scripts, and inserts the result of the script back into the .md file.
It's very much a Unix stdin-stdout thing. My whole blog [1] uses this, especially the code examples highlighted with pygments, and also links to the glossary, etc.
I dumped a snapshot here [2] awhile ago. It may or may not be of use if asciidoc already works for you.
The bad thing about this format is that it's not pure markdown anymore, so Vim syntax highlighting gets messed up sometimes. If I had to do it again, I would probably try to hook into a CommonMark [3] library to parse HTML blocks. So basically certain <div></div> blocks would get transformed into others.
My book was written in asciidoc for O'Reilly. Honestly, the asciidoc docs are a mess, for example, trying to add a header to a set of documents is much more challenging than it needs to be.
I recently came across mdtk (https://github.com/ynohat/mdtk) which renders text-based input (not asciidoc, but md) into nice documents by configurable packagers (currently revealjs & typora).
Also provides option to extend md with custom logic, such as variable interpretation
Eh, I'd say they're pretty different goals and use cases in reality. Pandoc is great for translation into other formats, where the other format then is applied final styling using downstream tools.
AsciiDoctor is for the Asciidoc format, but, generally includes some nice tooling for commonly used output formats.
Yes, you can use pandoc to convert asciidoc to something else, but in general, I've noticed that asciidoctor has great support for HTML themes:
The PDF styling directly out of the asciidoctor tool, on the other hand, isn't as advanced. So going from asciidoc to DocBook can make sense here, and I think is probably still done to do things like create truly professional looking PDFs.
What to use? Depends on your toolchain. I almost never need anything but HTML and PDF.
I've found that people, used to Markdown, can jump into Asciidoc and use `asciidoctor` easily.
Pandoc and AsciiDoctor are fairly similar in their purpose. Pandoc aims to provide conversion between a bunch of different formats, while AsciiDoctor primarily focuses on the AsciiDoc format, a "competitor" for markdown.
I prefer AsciiDoc over Markdown because it is just a bit more robust. While both are equally simple to use for the most common use cases of marking up a document and adding bold, italics, headings, and code snippets, AsciiDoc has features to add figure captions, cross references, and other slightly more robust features that I use for a lot of my writing.
Oh believe me I love AsciiDoc. I would use it all the time if half the tools out there would support it. Sadly, as it stands most forums and chat apps still think Markdown is the only format ever to be invented.
I think, this is a wonderful tool. The Asciidoc format is much better specified than Markdown, which is okay for a short text like a Github readme, but lacks consistency between rendering engines, and is not really feature rich for anything more serious than a short text.
The Asciidoctor tool also comes with a very high-quality default CSS style, which makes it very appealing and ready to use. Thumbs up from me for the work on this tool and the format.
One thing I have found useful but difficult to do in both markdown and AsciiDoc: I have a block of code, and I want to highlight, say, a variable name by making it italic or bold. Or, I have several lines that have changed from one example to the next, and I want to somehow show that those lines are the ones that have been modified by some form of marker (“change bar”) or highlighting.
Mh in the past many work came from another project ConTeXt from Pragma-ade a sort of LaTeX with an easy DSL and a tons of style. however many other are in a similar state while LaTeX survive, the others, included mythical languages like *roff or docbook die or remain marginal...
Long story short: thanks for sharing your work, that's good and if it serve you it's a very smart move but I do not expect a real "success".
Personally, I prefer reStructuredText, its design feels more consistent in comparison to the ambiguous implementations of the various markdown dialects.
In Asciidoc, I do not like that lower lever headings occupy more markers than higher level ones. Visually,
=== This heading
appears more important than
== This heading
By the way, a good comparison is at http://hyperpolyglot.org/lightweight-markup