AsciiDoc

From Canonica AI

Introduction

AsciiDoc is a human-readable document format, semantically equivalent to DocBook XML, but using plain-text mark-up conventions. AsciiDoc documents can be created using any text editor and read “as-is”, or rendered to HTML or any other format supported by a DocBook tool-chain, i.e. PDF, TeX, Unix manpages, e-books, slide presentations, etc.

History

AsciiDoc was first released in Nov 2002 by Stuart Rackham. The original intention was to create a lightweight mark-up language for writing notes, documentation and articles that could be processed to produce HTML or DocBook without requiring the author to be familiar with the complexities of DocBook XML and its processing tools. AsciiDoc has since been adopted and extended by several open source projects, notably the Linux Kernel Documentation Project, as their main documentation tool.

Syntax

The AsciiDoc syntax is designed to be quick to learn and easy to write with, inspired by the Markdown and reStructuredText syntax. The AsciiDoc syntax is intuitive and the document format is highly configurable. AsciiDoc has been designed to be as simple as possible; for example, to create a title in AsciiDoc, you simply prefix the line with a single equals sign. To create a level two heading, you prefix the line with two equals signs, and so on.

Features

AsciiDoc has a number of features that make it a versatile documentation tool:

1. AsciiDoc files are plain text, so they can be edited with any text editor and can be version-controlled with tools like Git. 2. AsciiDoc is highly configurable: both the AsciiDoc source file syntax and the backend output markups (which can be almost any type of SGML/XML markup) can be customized and extended by the user. 3. AsciiDoc is a mature, lightweight markup language that is compatible with the DocBook standard, a widely used schema for technical documentation. 4. AsciiDoc is platform independent. You can run it on Linux, Windows, Mac and any other platform that supports Python, which is the language AsciiDoc is written in. 5. AsciiDoc has a high quality PDF output capability, thanks to the a2x toolchain wrapper, which translates an AsciiDoc document to DocBook, then to PDF using fop.

Usage

AsciiDoc is used in a wide range of applications, from writing small notes and documentation, to books and even published scientific articles. It is also used in many open source projects for writing documentation.

See Also

A screenshot of a text editor with an AsciiDoc document. The document includes various AsciiDoc syntax such as headings, lists, and links.
A screenshot of a text editor with an AsciiDoc document. The document includes various AsciiDoc syntax such as headings, lists, and links.