Hacker News Reader

Comment by toastal | Hacker News Reader

One day I wish to see the AsciiDoc(tor) Reader. I'd love to be freed from Ruby as AsciiDoc is superior to Markdown and most other lightweight markup syntax options in features and syntax. This lack of features is why we have an incompatible group of Markdown syntax forks (aka "flavors" to mask that forks are incompatible).

View on HN

As others wrote, Pandoc is Haskell so it compiles to a fairly efficient binary.

But more importantly, unlike the various Markdown flavors or AsciiDoc, it is incredibly extensible thanks to the combination of custom filters and the possibility to add HTML classes and attributes. One can write filters to leverage the class/attribute information and perform transformations at the AST level, which basically lets you define a DSL with an arbitrary number of custom elements.

I wrote a collection of filters for the publication of a large online legal playbook. Not only did Pandoc make it possible to introduce different kind of custom elements that don't exist in plain Markdown or AsciiDoc, but by using different filters it was possible to use a single Markdown source to generate both the book and various summaries such as a list of examples, a list of civil code clauses etc. I don't know Haskell that well so I used Rust for the filters, but that worked very well.

Pandoc is IMO a very underrated tool.

> Pandoc is Haskell so it compiles to a fairly efficient binary.

This is nebulous. Haskell's compiled binaries are not ideal, for a number of reasons.[^1] GHC does very little to optimise for many typical metrics of "efficient". The binaries it produces are enormous because it (unavoidably) bundles the runtime along with the program itself, and there is a lot of empty space in the binaries. Shrinking them can improve startup times significantly especially on spinning rust drives.

That said, Haskell programs are at least _compiled_, and they do result in binaries which, if well written, can result in running times comparable to (or, sometimes, shorter than) your average hand-rolled C code that achieves the same goals.

Of course, none of this casts any shadow on the fact that Pandoc is, indeed, an excellently engineered piece of software that stands as a testament to the value of Haskell for real-world business logic and problem solving.

[^1]: This problem is fairly well-understood in the Haskell community: https://dixonary.co.uk/small

Take a look at https://djot.net/, you might like that.

It does do some things better and I appreciate calling it a new name and 'starting over' instead of another fork, but what's not covered is metadata. If I want to add author, license, tags, keywords, description, etc. there is no in-document way to do this. Almost all other media format types from images, audio, to other documents like ODF have a way to do metadata and this (and Markdown) doesn't cover said important use case.

Seems there's a long-standing (for the project) open issue where it's still being mulled over.

Imports are also very nice for writing longer texts--especially how AsciiDoc lets you +1 all of your headings so the heading hierarchy works as a standalone document and a part of a larger whole.

Yeah, it’s definitely a wip at this point, though it is already general enough to express meta and imports. You could write

    # Title
    : key = value
    
    ```include
    ./examples/hello.rs
    ```

today and write a simple filter to extract meta from the first definition list and resolve includes.

I appreciate that you pointed it out though to give me a chance to reevaluate my thoughts on the project. It seems it has a better trajectory than when I had last looked.

I've successfully used it from Clojure (I think it's through JRuby). With a few lines of code you can configure AsciiDoctor to whatever you need. It's way easier than fiddling at the command-line (I couldn't immediately understand how to get extensions and how it played with whatever version of the software I got through `apt`). It'd be good to have alternatives just for the sake of it - but I didn't find anything particularly lacking

Here is how I made some reveal slides

    (import [org.asciidoctor
             Asciidoctor
             OptionsBuilder
             SafeMode])

    (let [input-file    (clojure.java.io/file
                          "path/to/adoc/file")
          adoctor       (org.asciidoctor.Asciidoctor$Factory/create)
          reveal-option (doto
                              (org.asciidoctor.OptionsBuilder/options)
                          (.backend
                              "revealjs")
                          (.safe
                              org.asciidoctor.SafeMode/UNSAFE)
                          (.attributes
                              (.attribute
                            (org.asciidoctor.AttributesBuilder/attributes)
                            "revealjsdir"
                            "../reveal.js")))]
    (.requireLibrary
        adoctor
        (into-array
          String
          ["asciidoctor-revealjs"]))
    (.convertFile
        adoctor
        input-file
        reveal-option))

You get all the codez from Maven so you don't need to install anything on your system

    {'org.asciidoctor/asciidoctorj-revealjs {:mvn/version "5.0.0.rc1"}
     'org.asciidoctor/asciidoctorj-pdf      {:mvn/version "1.6.2"}
     'org.asciidoctor/asciidoctorj          {:mvn/version "2.5.3"}

The maintainers seem very responsive and active on Github. It's not as nice as a spec and multiple implementations - and I guess you're locked in to one library, but at least it's not as bad as Orgmode - where you're locked in to an editor as well

Yes, the maintainer is great. I have at this point just used Nix and post-processed Asciidoctor instead of trying any sort of other tools, but it gets tricker as you noted if you want to use it inside something else. It's not a compiled binary nor is it a C lib other languages could get at. Much of that could be attributed to the spec being quite.

Pandoc is written in Haskell.

AsciiDoc is written in Python.

Though when it comes to annoyance with Markdown forks: AsciiDoctor is basically that to AsciiDoc. It's mostly compatible, but when it isn't, it really bites.

The more important part is that you end up with a binary instead of needing an interpreted language which makes the tooling a mess. Python and Ruby are the same thing to most people.

Reply on news.ycombinator.com