4 ms·

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 opti

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).

thekaleb 4y ago
Pandoc is written in Haskell.
chungy 4y ago
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.
- toastal 4y ago
  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.
binarycoffee 4y ago
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.
- johnday 4y ago
  > 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 https://dixonary.co.uk/small
matklad 4y ago
Take a look at https://djot.net/ https://djot.net/, you might like that.
- toastal 4y ago
  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.
  - matklad 4y ago
    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.
    - toastal 4y ago
      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.
geokon 4y ago
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
- toastal 4y ago
  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.

thekaleb 4y ago

Pandoc is written in Haskell.

chungy 4y ago

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.

toastal 4y ago
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.

binarycoffee 4y ago

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.

johnday 4y ago
> 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 https://dixonary.co.uk/small

matklad 4y ago

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

toastal 4y ago
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.
- matklad 4y ago
  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.
  - toastal 4y ago
    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.

geokon 4y ago

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

toastal 4y ago
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.