AsciiDoc in Comparison
AsciiDoc is the tool of choice for technical editors. Here are the advantages over Markdown, LaTeX and reStructuredText.
Choosing the right markup language is crucial for technical writers. In this article, we take a look at AsciiDoc and compare it to other popular languages. AsciiDoc is an easy-to-read markup language. AsciiDoc files can be converted to many formats, including HTML, PDF, ePub and manpage, depending on the converter.
We compare AsciiDoc with the markup languages Markdown, LaTeX and reStructuredText. Each language has its advantages and disadvantages. Therefore, the intended use always plays a major role in choosing the right language. We therefore ask ourselves the question: How suitable are they for technical writers?
Table of Contents
AsciiDoc vs. Markdown
AsciiDoc vs. LaTex
AsciiDoc vs. restructured Text
What is Markdown?
Markdown is a lightweight markup language with a simple syntax. The language has been adopted by blogs, forums and short message services in particular and is therefore especially popular with author. Thanks to its simple syntax, it is easy to get started, making it the most popular markup language. According to John Gruber, who developed Markdown together with Aaron Schwartz, the language is a text-to-HTML converter. The developers pursued the design goal of making Markdown texts readable and publishable even in source code. This is because they contain only a few tags or other formatting instructions.
When is AsciiDoc better?
Although Markdown appeals to a wide audience, it does not have the necessary scope to be used for technical documentation. Here are the main advantages of AsciiDoc over Markdown:
All functions in one Language
Markdown is split into many dialects, such as Markdown, Python Markdown, Markdown XL, MultiMarkDown and more. Each of these dialects adds certain functions that are missing in standard Markdown. Examples are tables, admonitions or cross-references. As soon as you need these elements, you have to embed HTML code or use Markdown dialects. In AsciiDoc, on the other hand, all these functions are contained in a language that is on the way to standardization. The functions are included natively, you do not need any HTML knowledge.
Versatile output formats
By default, Markdown is limited to the output of HTML. AsciiDoc, on the other hand, enables the creation of various output formats such as HTML, PDF, manpage and DocBook. You can then use the latter to convert files into many other formats such as ePub. This offers greater flexibility when publishing your content.
No programming required for custom attributes
Attributes are a term from AsciiDoc. They are used to customize documents in terms of content, form or style. In Markdown, you often need programming knowledge to implement your own attributes, whereas this function is included as standard in AsciiDoc. In AsciiDoc, you can choose from the supplied attributes or define your own. You use your own attributes, for example, to set text variables for recurring content. Let's assume that you want to name the URL of your company website several times. To do this, we create our own attribute called :url:. Before you name the URL in the document for the first time, write :url: www.xyz.com in a line. Now output the attribute at any point with {url}. Make changes in the definition, all further instances are updated automatically. Attributes can also be nested.
To summarize: AsciiDoc is the more efficient and flexible choice for technical writers. You have all functions in one language. Once your text is ready, you can publish the content in multiple formats - not just HTML.
What is LaTeX?
Leslie Lamport developed the LaTeX typesetting system, which is based on Donald E. Knuth's TeX system. LaTeX is particularly popular with scientists and experts in the field of academic writing. It is a typesetting system that is based on a typographic typesetting system. It is often used for scientific and technical documents as well as for books, articles and reports. In academia, LaTeX is particularly popular due to its ability to accurately represent complex mathematical formulas and scientific notation. Due to the high quality of the typography, many scientific journals and universities prefer LaTeX for the publication of articles and theses.
Both LaTeX and AsciiDoc allow the author to focus on the content, while the design is handled independently via the styles. Both are independent of a specific editor, which means you can edit the sources in any text editor. In addition, they are cross-platform and deliver the same quality output on any operating system. LaTeX has a wider range of functions. Nevertheless, mathematical formulas, footnotes and other core elements can also be mapped in AsciiDoc.
When is AsciiDoc better?
AsciiDoc uses shorter and more concise markup compared to LaTeX. The principle is to enable a readable and simple syntax. This makes it easier for new users to get started. In contrast, LaTeX has a steeper learning curve due to its more complex syntax.
If you still need functions from LaTeX for your AsciiDoc document, this is not a problem: programmes like pandoc allow you to convert to LaTeX. This gives you the flexibility to use the advantages of both languages, depending on the requirements of your project.
To summarize: LaTeX excels at specialized, academic papers and documents with complex mathematical formulas. AsciiDoc, on the other hand, is simpler and more intuitive. This results in advantages that make it more attractive for a wider range of projects. The choice between AsciiDoc and LaTeX therefore depends on your requirements and personal preferences.
What is reStructuredText?
reStructuredText is primarily used for software documentation. It comes from the Python programming language ecosystem. In this ecosystem, it is mainly used in combination with the Docutils or Sphinx converters. A key feature of reStructuredText is its extensibility: with tools such as Sphinx, users can activate built-in extensions or create their own extensions to customize the document in almost all areas almost all areas.
When is AsciiDoc better?
AsciiDoc offers a syntax that is easier to understand than reStructuredText. This reduces the training period for new users. In particular, the indentations, unusual notations and different syntax forms make it difficult for newcomers to learn the language easily, as it is considered to be particularly unique and difficult to access.
AsciiDoc is designed in such a way that it is also accessible to less technically experienced users, which facilitates collaboration in teams. For example, you need to install Python to set up reStructuredText. While reStructuredText was primarily created by and for the Python community created by and for the Python community, AsciiDoc enjoys broader support. An active community has formed around the markup language, constantly helping to improve the language and associated tools.
To summarize: reStructuredText has its strengths in the Python community and in its extensibility. AsciiDoc, on the other hand, impresses with its simple syntax and wide range of functions. This makes the language an excellent choice for a wide range of documentation projects, regardless of the user's technical background.
Our Conclusion
After comparing the different markup languages AsciiDoc, Markdown and reStructuredText, it becomes clear that each language has its specific strengths and areas of application. The choice between these languages depends not only on the technical requirements of a project, but also on the personal preferences of the editor or developer:
Markdown is an excellent choice for simple documents. This simplifies collaboration with other users, as the entry level is the lowest for both variants. LaTex is mainly used in academic circles. The output of mathematical formulas is particularly worth mentioning here. reStructuredText is especially popular in the Python community and impresses with its expansion options.
AsciiDoc, on the other hand, shines as soon as documents become more extensive and require more sophisticated formatting such as complex tables, footnotes or cross-references. AsciiDoc is on the way to standardization, which means that all functions are contained in one language. This means that, unlike Markdown, you have no dialects. Nevertheless, the language remains legible and easy to learn. Its greater user-friendliness sets it apart from LaTeX and reStructuredText.
By the way: In another blog post, we compared the amount of characters needed for simple elements in AsciiDoc, Markdown and LaTeX.
AsciiDoc with adoc Studio
Creating AsciiDoc files in the terminal may have been an obstacle for some, but with adoc Studio this is a thing of the past. You write your text in the editor and always see the current preview as HTML and PDF. No conversion via the terminal is necessary to see the document in the output format. Gone are the days when technically complex installations or manual updates in the terminal kept you from your work. And for those who like to work on the iPad: adoc Studio runs on the latest macOS and iOS devices, so you can take your work with you wherever you go.
It's time to take full advantage of AsciiDoc. Try out adoc Studio and experience how uncomplicated and productive your documentation work can be.
