AsciiDoc
Creating better documents in AsciiDoc
Making well-formatted documents is a snap for Karsten Günther because he’s learnt how to use a metaformat – and now you can, too.
ASCIIDOC
Credit: http://asciidoc.org
OUR EXPERT
Karsten Günther makes documents with AsciiDoc, LaTeX and other formats. If he needs a metaformat, he uses AsciiDoc.
The different AsciiDoc styles for paragraph formatting. Here the examples have been formatted in AsciidocFX as HTML5. Outputs to other formats, such as PDF, vary slightly.
A sciiDoc is a shell program that takes source text, formats it and produces legible, correct output. A plus of AsciiDoc is that there are several versions in Ruby, Java, JavaScript and Python (plus Rust and Go unofficially) that produces mostly identical output.
Markup or formatting languages are about separating content from presentation. So tables are special structures with rows and columns, not text aligned by indents and spaces.
AsciiDoc tries to emulate many functions of LaTeX, albeit at a low level. LaTeX documents, for example, allow data to be automatically read in and prepared, as well as define their own macros and more. AsciiDoc does not do this directly, so there is no simple way to define your own elements – the existing ones must suffice. On the other hand, AsciiDoc syntax is much simpler, easier-to-understand and use than LaTeX, and much faster to write. In some places, AsciiDoc takes over elements from LaTeX, such as when citing references. Then the corresponding LaTeX macros are provided as AsciiDoc macros.
A special feature of AsciiDoc is the internal data format. This is closely based on (X)HTML and thus easily supports many output formats with which LaTeX has problems. EPUB and other ebook formats, for example, are based on HTML, which makes AsciiDoc an ideal input. In fact, AsciiDoc is even able to translate the supported formats directly into LaTeX and DocBook formats. While the conversion is largely error-free, it still must still be manually post-processed.
GET THE LATEST BUILDS
AsciiDoc and often Asciidoctor are available as packages in the repositories of most distributions. Docker solutions are also increasingly being developed and propagated. There are often also various packages available with extensions for AsciiDoc and editors. For example, there are extensions for special diagram forms, but plugins are also available for Emacs and Vi (and various modern editors), which mostly perform a type of syntax highlighting in the source code.
AsciiDoc was originally made available at www. methods.co.nz/asciidoc/, however the page is currently only sporadically accessible. Asciidoctor can be downloaded and installed directly from the current homepage – https://asciidoctor.org – as a gem (a Ruby package).
This is also possible for special variants of Asciidoctor – for example, for direct PDF output: gem install asciidoctor-pdf . (The output generated by this is important.)
For some components, this does not work because there are no official versions yet – Asciidoctor LaTeX, for example. But preliminary versions can be installed: gem install asciidoctor-latex--pre will do it.
If AsciidocFX is not available in the repositories, the tar.gz package will be available on the website: https://github.com/ asciidocfx/AsciidocFX/ releases/download/v1.8.4/ AsciidocFX_Linux.tar.gz. After unpacking – usually to /opt/ – the program is started directly from a terminal.