asciidocr 0.1.1

A CLI and library for processing and converting asciidoc files
Documentation

= asciidocr

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

== Installation

Right now the crate provides an asciidocr executable as well as an asciidocr-tck-adapter executable. The latter is for future checking against the still-in-progress asciidoc official spec. To install from crates.io:

[source, console]

$ cargo install asciidocr

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

[source, console]

$ cargo install --path .

== Usage (Command-Line)

Here's the usage:

[source, console]

$ asciidocr --help A Rust CLI and library for processing Asciidoc files.

Usage: asciidocr [OPTIONS]

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

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

-b, --backend Optionally select a backend for conversion

      [default: htmlbook]

      Possible values:
      - htmlbook: Produces "Htmlbook-like" HTML documents
      - docx:     !Experimental! Produces a "manuscript-styled" DOCX document
      - json:     Produces the Abstract Syntax Tree generated by the parser as json

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

== Features and 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 (yetfootnote:[Timing, and actual implementation TK. If you want to use this and are missing some feature, please create an issue or send in a PR.]):

  • "Literal" blocks (...) and inlines (+ delimited text)
  • Checklists
  • Offsets
  • Tagged regions/tagged includes
  • Conditionals
  • Complex table markup
  • Complex nested lists

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

== Project Goals

A non-exhaustive list:

  • Coverage of the majority, if not all, asciidoc language features
  • Passes the https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-tck[language compatibility toolkit] tests
  • Clean, simple HTML output as a default with extant but minimal styling
  • Native "document" (docx or odt, probably 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

== 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: