asciidocr

A(n in-progress, but more or less functional) Rust tool/library for processing Asciidoc files.

Now with a fairly high-functioning docx backend! (See feature flag.)

Installation

Right now the crate provides an asciidocr executable with a default HTML build as well as a json backend that can be used to check against the still-in-progress asciidoc official spec/technology compatibility toolkit. An experimental docx build is provided behind a feature flag.

To install from crates.io:

$ cargo install asciidocr

To install from source, clone and cd into the repo and run:

$ cargo install --path .

To include the experimental docx backend, enable the docx feature:

$ cargo install --features "docx" asciidocr

$ cargo install --path . --features "docx"

Usage (Command-Line)

Here's the usage with the docx feature enabled:

$ asciidocr --help
A CLI and library for processing and converting asciidoc files

Usage: asciidocr [OPTIONS] <FILE>

Arguments:
  <FILE>
          Asciidoc file for processing. To read from standard input (stdin), use "-"

Options:
  -o, --out-file <OUTPUT>
          Optionally provide a filename for the output. To send to standard out (stdout), use "-"

  -b, --backend <BACKEND>
          Optionally select a backend for conversion
          
          [default: htmlbook]

          Possible values:
          - htmlbook: Produces "Htmlbook-like" HTML documents
          - json:     Produces the Abstract Syntax Tree generated by the parser as json. When STDIN ("-") is provided as FILE, this backend serves as an Asciidoc TCK adapter
          - docx:     !Experimental! Produces a "manuscript-styled" DOCX document

  -c, --count-words
          Print a document word count (excludes comments, markup characters, etc.)

  -x, --allow-unresolved-targets
          Run asciidocr without resolving resource targets; by default, asciidocr will fail to parse a document if a given resource is not found. This option allows parsing to continue if the backend supports missing targets

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Limitations

asciidocr currently produces "Htmlbook"-style HTML for all handled blocks/inlines and has limited, experimental support for producing docx files, namely prose files without tables, lists, etc., etc. Fair warning: content may be dropped while creating docx files until that feature stabilizes a little more. It should, however, be good to go for your next great short story.

asciidocr (more or less) parses the vast majority of "common" asciidoc markup features. Some things it does not do (yet):

• Checklists
• Tag filtering* (including by tags is now supported)
• Conditionals
• Complex table markup
• Complex nested lists
• The "subs" attribute in blocks

For a more complete list of the current limitations and caveats, see LIMITATIONS.adoc.

Recent Additions

That said, new language features are being added in addition to other capabilities with each release -- if there's something you want but don't have, please open an issue. The most up-to-date information will be found on each release's page, but some language features recently introduced include:

• Handling for tagged regions (tag::foo[], include::bar.txt[tag=foo], etc.)
• Filtering included files by line (include:foo.txt[lines=4..20], etc.), including "end of file" filtering ([lines=5..-1)

Project Goals

A non-exhaustive list:

• Coverage of the majority, if not all, asciidoc language features
• Passes the language compatibility toolkit tests
• Clean, simple HTML output as a default
• Native "document" (docx) output in a "manuscript" template, like what you might send to a publisher or literary journal
• PyO3 hooks/project for use inside Python contexts (will be behind a feature flag)

Similar Projects

Great minds think alike, and as such, a few other people are working on asciidoc tools in Rust now, too. Here are at least a few I know about:

• asciidork
• acdc
• asciidoc-parser

Known Bugs

Things that should work, but are currently acting up:

• Definition list term ordering under certain circumstances.

If you discover other bugs, please open an issue.