Crate asciidocr

Source
Expand description

Fast and (eventually) compliant Asciidoc parsing!

(For information about Asciidoc, see https://asciidoc.org/)

This crate provides a CLI tool (asciidocr) for working with/building asciidoc files, a way to interface with the official Technology Compatibility Kit adapter (see https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-tck) via the json backend, and library access to the parser, scanner, backends, and Abstract Syntax Graph elements.

NOTE: This crate is still in progress and nothing, including library elements, should be considered stable. If something disappears that you’re interested in, please open an issue.

While eventually the goal is to support the vast majority of the language features, many are not yet implemented. Notable misses include:

  • Some Asciidoctor document attributes (e.g., :toc:, :icons:, etc.)
  • Indented source blocks
  • Offsets
  • Tagged regions
  • Conditionals (ifdef, ifndef, ifeval)

It’s also important to note that though we have targeted (and are passing) all of the compatibility tests included in the TCK, there have been areas where we’ve deviated from the published schema, esp. in cases where it’s not obvious what’s to be done.

Current backends (parse targets) includes:

  • HTMLBook: fairly good support; can be used as a relatively “unadorned” HTML generator
  • Docx (behind docx feature): experimental and still very much in-progress; but good enough for “simple” documents without tables, images, etc.

Modules§

backends
Backends serve as the “targets” for the parser, which itself only produces an Asg, or Abstract Syntax Graph. Currently the backends include:
graph
This module contains elements of the Abstract Syntax Graph used to represent an Asciidoc document, roughly meaning to follow the “official” schema: https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang/-/blob/main/asg/schema.json
parser
Parses a stream of tokens into an Asg (Abstract Syntax Graph)
scanner
The Scanner scans the asciidoc string into Tokens, which is then consumed by the Parser.