Reviews run for a minimum of one week. The outcome of the review is decided on this date. This is the last day to make comments or ask questions about this review.
AsciiDoc has gained traction as a preferred choice for technical writing because it’s expressive, author-friendly, and tool agnostic. The AsciiDoc community has asserted that a specification for AsciiDoc is needed to solidify the ecosystem’s current foundation. We anticipate a specification will also provide pathways for new capabilities that adapt the language to the ever-changing technology landscape. The goal of this project is to produce that specification and its artifacts.
The AsciiDoc Language project defines and maintains the AsciiDoc Language Specification and Technology Compatiblity Kit (TCK), its artifacts, and the corresponding language and API documentation. The AsciiDoc Language Specification describes the syntax and grammar, Abstract Semantic Graph (ASG), Document Object Model (DOM), referencing system, and APIs for processing, converting, and extending the language. The TCK is used to verify and certify that an AsciiDoc processor implementation is compatible with this specification.
Specifically, the project scope includes the:
- AsciiDoc language syntax and grammar (e.g., EBNF)
- doctype structure and objects
- ASG: namely the encoded form for use in the TCK (e.g., JSON)
- TCK: Technology Compatiblity Kit for the AsciiDoc language
- DOM API: in memory semantic representation of the encoded information
- Processor API (load, convert)
- Converter API
- Extension API
- Extended syntax processors (e.g., custom block or macro)
- Resolvers (e.g., path and attribute resolvers, ID generator)
- Parse events and lifecycle interceptors (e.g., input processor, output processor, tree processor)
- Integration adapters: syntax highlighter, STEM, bibliography, docinfo
- Expected converter behaviors (e.g., toc, ID generation, icon type, safe mode)
- Internal and external referencing system: (e.g., xrefs, includes, images)
- Reference converter and output format (e.g., HTML w/ reference stylesheet, DocBook)
- Built-in attributes and reserved attribute namespaces
- AsciiDoc media type (MIME) and .adoc file extension
The project also provides the:
- AsciiDoc language documentation for writers
- AsciiDoc API documentation
AsciiDoc is a comprehensive, semantic markup language for producing a variety of presentation-rich output formats from content encoded in a concise, human-readable, plain text format. It also includes a set of APIs for transforming the encoded content, extending the syntax/grammar and processor lifecycle, and integrating with tools and publishing platforms. Teams and individuals use AsciiDoc to write product documentation, technical specifications, architectural guides, scientific and analytical reports, academic courses and training materials, books, and other technical communication.
The AsciiDoc Language isn’t coupled to the output format it produces. Software that implements the AsciiDoc Language Specification can parse and comprehend AsciiDoc and convert the parsed document structure to one or more output formats, such as HTML, PDF, EPUB, man page, DocBook. The ability to produce multiple output formats allows AsciiDoc to be used in static site generators, IDEs, git tools and services, CI/CD systems, and other software.
AsciiDoc bridges the gap between ease of writing and the rigorous requirements of technical authoring and publishing.
AsciiDoc is used across a spectrum of industries and communities, many that are associated with or members of the Eclipse Foundation. Being co-located with so many groups that are invested in AsciiDoc will provide a neutral and diverse forum for collaborating on and improving the language, its software, and related initiatives. Additionally, the Eclipse Foundation’s values of open source, transparency, and vendor neutrality are of the utmost importance to AsciiDoc and its community.
The Asciidoctor project will provide the following initial contributions:
- The AsciiDoc language user documentation with syntax examples. (CC BY 3)
- Documentation build, configuration, and assets.
- Scenarios from the test suite. (MIT)
In preparation for this project, the documentation and its build, configuration, and assets are being decoupled from the Asciidoctor implementation and scrubbed of implementation references. The documentation build and configuration depends on Antora (MPL-2.0).
The .adoc extension was once associated with a now obsolete file format. Otherwise, we don’t know of any legal issues at this time.
The initial contributions are expected to be ready in Q2 2020. Once the initial contributions are accepted and the project infrastructure and team process established, the plan is to iterate on the specification and TCK in coordination with the compatible implementation project(s). The goal of the first, stable version of the specification is to match the AsciiDoc Language as described by Asciidoctor 2.0.x as best as possible to minimize syntax and structure impacts on active AsciiDoc documents, but not propagate deprecations.
Future functionality and activities will be driven by community feedback and their requirements. Proposed specification advancements could include:
- defining syntax patterns for common, stable content models (e.g., tabbed blocks)
- exploring accessibility functionality
- improving integration with compatible tooling
- adapting to the latest output format specifications and related web browser and output standards
- providing additional doctypes to accommodate the needs of other types of technical writing
- implementing language server protocol support for AsciiDoc