[HN Gopher] Asciidoctor: A fast text processor and publishing to...
___________________________________________________________________
Asciidoctor: A fast text processor and publishing toolchain
Author : Tomte
Score : 38 points
Date : 2024-09-06 15:10 UTC (1 days ago)
(HTM) web link (asciidoctor.org)
(TXT) w3m dump (asciidoctor.org)
| Diti wrote:
| AsciiDoc is a pretty nice plaintext format with a rich offer of
| components.
|
| I wish it was more widely supported. Unfortunately, the only
| worthy implementation is in Ruby (AsciiDoctor), which is what all
| the other projects (in Java, Python) use.
|
| AsciiDoc would see more adoption, I think, if independent
| implementations existed in other languages.
| bobbylarrybobby wrote:
| The JavaScript version is an automatic translation of the ruby
| code and also works great (and of course can be used in a
| browser context). It is obviously not independent though
| kamma4434 wrote:
| As Ruby is very brittle when you move between OS we use jruby
| with gradle - all plugins included. One day I should make it
| into a native executable with Graal.
|
| Current workplace maintains a good amount of tech docs written
| in AsciiDoc that have been written over approx 20 years, that
| create PDF/ebooks and are published as a searchable online
| version with Antora. It works pretty well.
| abdullahkhalids wrote:
| Is there by any chance some variant of Jupyter that supports
| asciidoc for the text formatting? If so, how difficult would it
| be to replace Jupyter's marked.js renderer with asciidoctor?
| RadiozRadioz wrote:
| Better than Markdown, but I have trouble with muscle memory and
| the ubiquity of Markdown. One of these days I'll switch. It's
| similar to the QWERTY/Dvorak problem.
| klauserc wrote:
| I prefer Asciidoc over markdown for _documents_ where chapters,
| cross references, call outs, etc are valuable. For things that
| one might want to turn into a PDF.
|
| The tooling is a bit of a pain, but the Java world has pretty
| good integration (gradle, intellij)
| tapirl wrote:
| AsciiDoc is a feature-rich markup language. It's great. But I
| have two complaints:
|
| 1. Its readability is not very good. There is too much non-
| content text for me.
|
| 2. The grammar set is not small and natural.
| skwee357 wrote:
| I successfully used AsciiDoc and AsciiDoctor to write 2 books
| [0].
|
| I found it better suit for long form content than, say, markdown,
| due to the fact it has more language grammar for things like
| chapter, admonitions, etc.
|
| [0] https://yieldcode.blog/post/asciidoc-for-book-writing/
| toastal wrote:
| I've in recent years started to favor reStructuredText over
| AsciiDoc for three reasons. 1) Docutils's output in like 95%
| good, semantic HTML where Asciidoctor has a lot of issues (I
| would note that non-Docutils is often bad, second-class & reliant
| on what Markdown outputs for 'compatibility' (meaning less
| features for you)) 2) the features difference between the two I
| prefer the rST set (such as abbreviations) 3) the spec seems so
| complicated Pandoc can't realistically have a reader, just a
| writer & pretty much the Ruby-based Asciidoctor application ends
| up _being_ the AsciiDoc specification.
|
| That said, I would choose AsciiDoc every single day without
| hesitation over Markdown the minute you are talking about
| documentation or any sort of technical writing since Markdown is
| far too feature poor & buying into one specific fork is locking
| you into incompatibility & other headaches/compromises.
| ctenb wrote:
| I switched from pandoc markdown to asciidoc for writing technical
| blog posts, but switched back after a year due to the fact that
| pandoc is easier to setup and tweak with plugins
___________________________________________________________________
(page generated 2024-09-07 23:02 UTC)