[HN Gopher] I wish Asciidoc was more popular
___________________________________________________________________
I wish Asciidoc was more popular
Author : M911T
Score : 80 points
Date : 2023-02-06 17:12 UTC (5 hours ago)
(HTM) web link (pdx.su)
(TXT) w3m dump (pdx.su)
| gorgoiler wrote:
| Very briefly on admonitions: there is nothing stopping you from
| adding them to markdown yourself: <warning>
| You _really_ shouldn't play with matches, Debbie.
| </warning>
|
| Later on in that document: <style>
| warning { display: block; color: red;
| } </style>
|
| Which is a very long winded way of saying that you can use
| markdown for authoring actual content, and then use good old HTML
| for styling whatever else you want to.
|
| Relying on asciidoc for styling elements like admonitions always
| felt like the wrong tool for the job. Like writing a Java
| generator in Perl, instead of just writing actual Java.
| ethanwillis wrote:
| This is both the power and "problem" with Markdown. The
| "promise" (I'd say) of Asciidoc in general versus Markdown is
| that it aims to truly be a standard.
|
| Markdown itself comes (not even implicitly, but explicitly!)
| with the philosophy that there is no "true" standard. It's very
| flexible, very customizable, and does not aim for interop
| between implementations, for tooling, and so on.
|
| Asciidoc tries to focus on being a Standard with a capital "S"
| so that the entire ecosystem around it can interop properly
| without implementation specific quirks/incompatibilities.
|
| Both are good tools but with completely different philosophies.
| I learned all of this because I wanted to make a _fast_
| markdown parser in WASM directly. And at the same time I wanted
| to have a common way to put together a book to be published.
| What I learned quickly when trying to come at Markdown from a
| _technical_ perspective is that there are dozens or more
| Markdown flavors and the idea of "Markdown" as a "general
| thing" isn't accurate, there's not even really a "core" shared
| between the variants/flavors. Which is in stark contrast to
| Asciidoc.
|
| edit: A small aside, I also learned that a few publishers that
| focus on tech writing specifically use Asciidoc for their
| "publishing" workflows. So in that realm Asciidoc is
| practically useful to know.
| teknopaul wrote:
| While it's true markdown isnt a standard. What ever your tool
| does defines it. For source code docs converted to HTML or
| man pages you only have one build.
|
| Common mark is a standard if you need one.
| Symbiote wrote:
| That assumes you are writing only HTML.
|
| With Asciidoctor, we produce decent-looking PDF documentation
| as well as HTML.
| microflash wrote:
| There's also a generic directive proposal[1] that enables
| admonitions, YouTube embeds, etc. With remark[2] plugins,
| markdown can be as extensible as you may need. Here's a sample
| plugin for admonitions[3] by yours truly.
|
| [1]. https://talk.commonmark.org/t/generic-directives-plugins-
| syn...
|
| [2]. https://github.com/remarkjs/remark
|
| [3]. https://github.com/Microflash/remark-callout-directives
| eevilspock wrote:
| > Which is a very long winded way of saying that you can use
| markdown for authoring actual content, and then use good old
| HTML for styling whatever else you want to.
|
| Why does Markdown bother to have * and ** markup? Why not just
| use "<i>", "<b>", "<em>" or "<strong>"?
|
| 1. An admonition is no more "just styling" than is Markdown
| emphasis or strong markup, exclamation points at the end of a
| sentence or bullet lists (why not just use commas and "and"?).
| Admonitions are semantic.
|
| 2. HTML is not the only output rendering for Markdown.
| gorgoiler wrote:
| Because the majority of writing is text and lists.
| Admonitions don't hit the sweet spot of requiring any extra-
| HTML markup. You can simply mark block level elements up with
| blocks.
|
| You pretty much do this anyway in asciidoc, just with _extra
| steps_.
| hobo_mark wrote:
| I write all my professional docs in AsciiDoc (even made a tool to
| pull AsciiDoc comments out of the code and into various
| documents), but always disliked having to pull ruby into my
| toolchain.
|
| Is the Python3 asciidoc (any of the several that have sprung up)
| good enough to replace asciidoctor nowadays?
| Tomte wrote:
| Use AsciiDoctorJ. Under the hood it's JRuby, but as a user you
| won't really notice, it's just a Java program.
| baby wrote:
| You're proposing a Java solution to someone not happy with a
| Ruby solution, that seems backward.
| hobo_mark wrote:
| Having to download a JRE is not any better than having to
| pull Ruby from the RH Software Collections, meanwhile Python
| is already there...
| type0 wrote:
| There's https://github.com/asciidoctor/asciidoctor.js
| vmiklos wrote:
| I'm not sure about the current state, but the Python2
| implementation was the original one, and the Ruby one came
| later.
|
| So this statement:
|
| > First off, it's a single implementation.
|
| Is a bit misleading. It's more like there are no several
| flavors, like with markdown.
| fiddlosopher wrote:
| In fact, both claims are misleading. There are two
| implementations, and they implement distinct flavors with
| syntactic differences: https://consolelog.gitee.io/docs-
| asciidoctor/asciidoc-asciid... Markdown has a smaller
| flavors/implementations ratio!
| mbeex wrote:
| In fact, also this claim is wrong, because there are three
| :D
|
| 1. https://asciidoctor.org/
|
| 2. https://github.com/asciidoc-py/asciidoc-py
|
| 3. https://asciidoc3.org/
|
| 1 and 2 seem to hate 3 (see issue trackers / web sites of
| all three) and meanwhile probably also vice versa. The
| discussion was quickly dragged into the legal realm by 1 in
| particular, which very obviously dampened number 3's
| initial enthusiasm. Additionally, 2 describes itself
| somewhat prominently as a "legacy processor" for Python
| (technically correct in the current version, but legacy's
| meaning here is the relationship to the new Asciidoctor-
| specific constructs). At the same time it promises further
| development but nothing usable has come out of it so far.
|
| As a Python programmer, I would simply like to see a pure
| Python3 toolchain. It is quite an absurd situation at this
| moment. For example, my blog is supporting Markdown and
| ReST natively (Pelican-based). For Asciidoc - my preferred
| language - Pelican has a plugin, supporting different
| Asciidoc processors, but only at the first glance. It has
| also to support KaTeX. This on the other hand is no problem
| for Pelican's native Markdown languages (simply another
| plugin), but the Asciidoc plugin is too high-level. It can
| only use Asciidoctor in this case, requiring Ruby's KaTeX
| gem as an extra dependency. This gem seems to be abandoned
| and has compatibility issues with newer Asciidoctor
| versions ...
|
| 2 is no option for its installation hell alone (Asciidoc3
| is pure Python, simply a pip install). I don't know, if it
| is able to interact with KaTeX.
|
| From what I can see, 3 would technically offer the best
| initial platform for further development as a package.
| Could be wrong, of course.
| baby wrote:
| I used asciidoc to write a book with Manning, and what I have to
| say is that I'm personally not a fan. The main reason is the
| tooling in ruby. Maybe if asciidoc was more popular than it would
| have more implementations in more languages, but it's really
| tedious to work with it in the current situation IMO.
|
| The other thing is that, it was not easy to work with LaTeX in
| asciidoc last time I was doing it.
|
| Smaller issues: the syntax really sucks.
| [deleted]
| oneng wrote:
| We adopted Asciidoc at work (migrated from Word and Markdown),
| and it has been a stellar tool for editing and reviewing our
| technical documentation, as it fits well into our code review
| process. We also use Mermaid and PlantUML for our diagrams, which
| the asciidoctor extension has handled well.
| gnutrino wrote:
| I love Asciidoc, especially with PlantUML. I have used them
| together on various projects to version, and host internal
| documentation. The code block snippet generator is super useful
| as well. Spring Framework documentation is a shining example of
| how useful it can be!
| Freak_NL wrote:
| Aside from the merits of Markdown and Asciidoc, Asciidoc has a
| name that doesn't help. Depending on the (natural) language,
| ASCII (the encoding, that is) annoys anything from a small
| percentage of users (e.g., English, Esperanto), to many people
| (e.g, Dutch, German, French), to almost everyone (anything that
| doesn't use Latin characters). In the context of a markup
| language intended for structuring normal text its name just
| screams obsolescence for a lot of potential users!
| avgcorrection wrote:
| Absolutely, or at least I was also put off the name when I
| first heard of it. The name sounds like something that requires
| you to use (HTML) entities or some kind of Unicode code point
| syntax if you want to input non-ASCII. Blegh...
| kitsunesoba wrote:
| > Asciidoc has a name that doesn't help.
|
| Along with the notion of obsolescence one might derive from it,
| it's also not particularly sticky/memorable. It might sound
| silly but I think snappiness or lack thereof has an impact on
| rate of adoption, because for people to use things they have to
| first remember them.
| memorythought wrote:
| I love AsciiDoc and want to use it more. The main problem is, as
| noted, that it's hard to get this ruby library into whatever
| platform you want to deploy to. Consequently it's hard to build
| tooling based on AsciiDoc.
|
| I've had a brief play with trying to implement AsciiDoc in Rust
| (and others have too, see https://github.com/Veykril/pagliascii).
| I got bored of trying to figure out what the semantics should be
| by reading the implementation and decided to wait until the
| upcoming specification effort at https://asciidoc-wg.eclipse.org/
| bears fruit, the Zulip seems a bit more active recently
| preommr wrote:
| Everything in that article is why I don't like asciidoc. I think
| a lot of documentation should be absolute dead simple - no macros
| and complex behavior. It should just work. Markdown is great for
| that.
| mkesper wrote:
| Not having includes in markdown is a real bummer, though.
| TheRealPomax wrote:
| You get links, if you need more than that you're probably
| overcomplicating your documentation. Transclusion might sound
| nice, but now your docs have depedencies and they become
| harder to send, harder to host, and harder to edit (is this
| edit in this transcluded file going to work for every other
| file that includes it?). Then someone goes "I use it for
| templating" and now you have a CMS. It's a slippery slop that
| markdown sidesteps by going "no. You get links. If you need
| more than links, you're probably overcomplicating your
| documentation".
| dmitriid wrote:
| Documentation should have includes and transcludes (?) where
| you can include a part of a different document that stays in
| sync with the original doc.
| teknopaul wrote:
| "the ability to format and fit content in your editor, loosely
| independent of how it would be presented to the user"
|
| ?? Markdown is the opposite, no? Ability to format text in an
| editor that looks sufficiently like formatted final text so you
| don't need to render it all the time.
|
| That's what I like about markdown anyway.
| paradox460 wrote:
| I was more referring to the behavior some markdown parsers
| have, which is that they (deliberately) make line-breaks
| significant.
|
| Try writing something in your text editor of choice, and hard
| wrapping it at 80 columns. You then paste it into a github
| issue, and you'll see that the line breaks are preserved. It
| gets pretty annoying, even if all you have to do is join all
| the lines in the paragraph/section.
|
| I'm not advocating for a total decoupling of presentation from
| raw code, but I do think that significant newlines are a point
| of particular irritation.
| lfmunoz4 wrote:
| [dead]
| matklad wrote:
| If you like AsciiDoctor, another option to take a look at is
| https://djot.net/.
| darekkay wrote:
| We use AsciiDoc for our technical documentation, and it's great.
| Last year we moved from AsciiDoctor to Antora [1] and I can't
| recommend it enough.
|
| [1] https://antora.org/
| amelius wrote:
| Markdown is still a poor man's XML. I'd say one of them is
| enough.
| 2h wrote:
| AsciiDoc is so close to being good. It slam dunks Markdown, but
| they just have a few nagging issues that they refuse to fix, for
| 9 years now:
|
| https://github.com/asciidoctor/asciidoctor/issues/1087
| aidenn0 wrote:
| AsciiDoc is great for writing, but don't try to auto-generate it;
| e.g. pandoc still can't correctly do so:
| https://github.com/jgm/pandoc/issues/2337
|
| Note that Asciidoctor (the Ruby implementation) has a reasonable
| solution now, but it's not portable to Asciidoc (the original
| python implementation).
| innocentoldguy wrote:
| I love working with Asciidoc. For me, it's the right balance
| between Markdown and Latex. I like Org-mode quite a bit too, but
| Asciidoc, when paired with Antora for generating static sites and
| asciidoctor-pdf for generating PDF files, creates much better
| looking documentation than I've been able to achieve using Org-
| mode.
| trynewideas wrote:
| AsciiDoc/AsciiDoctor are better than DITA, and that's the nicest
| thing I'll say about them.
| westernpopular wrote:
| > For example, Markdown has a syntax for inserting a break,
| inside a paragraph. You put two space characters at the end of a
| line, and the parser will inject a line break.
|
| Don't most Markdown implementations allow you to use an empty
| line as a paragraph separator as well?
| JasonFruit wrote:
| Yes, and that differs from a line break inside a paragraph,
| which is what the author is discussing.
| westernpopular wrote:
| Oh I never realized that was the difference, thank you.
| chungy wrote:
| It's not accurate to say AsciiDoc only has a single
| implementation, there is the original AsciiDoc written in Python,
| and also there is AsciiDoctor written in Ruby. Unfortunately,
| AsciiDoctor is merely _mostly_ compatible and deliberately opted
| to not support some features. (And being Ruby, GitHub will use
| AsciiDoctor to render AsciiDoc files; whether you should conform
| your documents to this environment depends on what you're doing
| with them.)
|
| AsciiDoc was written primarily as a way to write DocBook without
| having to use XML. AsciiDoctor has an alternative goal of writing
| HTML without having to use HTML. The subtle differences between
| these goals leads to a lot of "gotchas" if you try to serve both
| of them at the same time. At least if AsciiDoc is only a
| consumable in your build system and you deliver the compiled
| artifacts (be it HTML, PDF, man pages, etc), you can probably be
| fine enough knowing what your implementation does and does not
| do.
| kazinator wrote:
| I tried installing it years ago (in a GNU/Linux distro, using its
| packages); it needed so many dependencies (like hundreds of
| megs), and in the end didn't work.
|
| Total bait and switch in terms of the simplicity "sales pitch".
|
| My expectation was that there would be some kind of script (just
| one, possibly all in one file) which scans the simple input
| syntax and outputs it into several markup formats based on some
| command line option.
| zh3 wrote:
| Main killer for me - admittedly because I like sharp tools, and
| it used to claim to be 'lightweight': 'apt install asciidoc' (and
| I had to delete most of it, because - for the first time ever - I
| got an HN message about "comment too long"):-
| Reading package lists... Building dependency tree...
| Reading state information... The following additional
| packages will be installed: asciidoc-base asciidoc-common
| asciidoc-dblatex asciidoc-doc dblatex dblatex-doc docbook-
| dsssl docbook-utils docbook-xml docbook-xsl dvisvgm file
| fonts-droid-fallback fonts-gfs-baskerville fonts-gfs-porson
| fonts-lato fonts-lmodern fonts-noto-mono fonts-texgyre
| fonts-urw-base35 ghostscript .... x11-common
| x11-utils x11-xserver-utils xdg-utils xfonts-encodings
| xfonts-utils xml-core xmlto xsltproc xvt 0 upgraded, 271
| newly installed, 0 to remove and 4 not upgraded. Need to
| get 455 MB of archives. After this operation, 1,127 MB of
| additional disk space will be used. Do you want to
| continue? [Y/n] Abort.
| yrro wrote:
| Probably because asciidoc recommends asciidoc-dblatex (used for
| producing LaTeX via docbook). Try 'apt install asciidoc
| asciidoc-dblatex-' to install just asciidoc without pulling in
| the other package.
| zh3 wrote:
| Thanks, hopefully this'll turn up on a google search for
| someone who just wants to turn simple text markup into a PDF
| ('apt' didn't offer the option of not installing asciidoc-
| dblatex).
| paradox460 wrote:
| I'll stick it in the article, in a closing notes section
| anthk wrote:
| apt --no-install-recommends foobar
|
| You can set some settings for apt-get in the config file so
| it doesn't pull the recommended packages as enforced
| dependencies.
| 1f60c wrote:
| How does that command work?
| yrro wrote:
| It lets you do the equivalent of "apt install asciidoc; apt
| remove asciidoc-dblatex" in one command, so avoids
| downloading the unwanted packages only to remove them.
|
| "The requested action can be overridden for specific
| packages by appending a plus (+) to the package name to
| install this package or a minus (-) to remove it"
|
| https://manpages.debian.org/bullseye/apt/apt.8.en.html
| [deleted]
| [deleted]
| pizza234 wrote:
| Not on my machine: # apt install asciidoc
| Reading package lists... Done Building dependency
| tree... Done Reading state information... Done
| The following additional packages will be installed:
| asciidoc-base asciidoc-common docbook-xsl xsltproc
| Suggested packages: asciidoc-doc docbook-utils
| source-highlight dbtoepub docbook-xsl-doc-html | docbook-xsl-
| doc-pdf | docbook-xsl-doc-text | docbook-xsl-doc docbook-xsl-
| saxon fop libsaxon-java libxalan2-java libxslthl-java xalan
| Recommended packages: asciidoc-dblatex xmlto
| The following NEW packages will be installed:
| asciidoc asciidoc-base asciidoc-common docbook-xsl xsltproc
|
| I wonder if one gets that dependency tree on a Wayland-only
| setup.
| zh3 wrote:
| You probably have X and Wayland installed (quite why those
| are required for asciidoc is a question I'll leave for
| others).
| pizza234 wrote:
| A lot of dependecies are pulled from the (recommended)
| asciidoc-dblatex package, which depends, indirectly, on x11
| packages. Don't install the recommended packages (whose
| concept is anyway in conflict with keeping a system lean)
| and see what happens.
| zh3 wrote:
| How to not install recommended packages? (there wasn't a
| choice, and anyway not installing recommended packages
| often implies - rightly or wrongly - security risks).
| pizza234 wrote:
| The `apt` tool provides the option `--no-install-
| recommends`.
|
| If you want to disable the recommended packages
| installation by default, you can: echo
| 'APT::Install-Recommends "0";' >
| /etc/apt/apt.conf.d/99disable-recommends.conf
|
| You may also want to disable the suggested packages:
| echo 'APT::Install-Suggests "0";' >>
| /etc/apt/apt.conf.d/99disable-recommends.conf
| pizza234 wrote:
| Regarding the apt "recommended" concept, it's a generic
| concept of optional functionality; it's orthogonal to
| security. If one wants to make a generic association with
| security, less recommended packages -> less functionality
| -> smaller attack surface.
| adminu wrote:
| Well, here comes the obligatory org-mode comment:
|
| Org mode does most of that, too. And a lot more. And while you
| cannot use it in Github issues, you can in README files on
| Github.
| mort96 wrote:
| I don't use emacs, so an emacs mode isn't that useful for me.
| bitwize wrote:
| Org-mode stuff can be authored outside emacs. There's even a
| Visual Studio Code addon for it. And pandoc groks it.
|
| But yeah, to unlock the true power of org-mode you need
| emacs.
| richiebful1 wrote:
| Org is also just a file format with extensions available in
| VS Code, vim, sublime, and Atom. I've personally used the VS
| Code extension, I think it works just as well as the Markdown
| extension.
|
| [1]. https://orgmode.org/install.html
| maximus-decimus wrote:
| It's not just a doc format though, it's also a task manager
| format, a literate programming format, an everything format
| with no clear separation.
|
| I can't help but feel like it would be a lot more widely
| accepted if they divided it in multiple projects each with
| their own goals and requirements.
| BeetleB wrote:
| That is a much more challenging task - even if they had
| planned it from the get go. One of the reasons people
| gravitate to Emacs is that it is much easier to build
| integrated systems like Org mode.
|
| The other barrier, of course, is that it doesn't really
| benefit existing Org mode users/developers.
| wmat wrote:
| I really like asciidocs support for diagramming via the
| asciidoctor-diagram extension. It's supports lots of unique and
| useful diagramming formats, such as graphviz, ditaa, bytefield,
| etc.
| Freak_NL wrote:
| Markdown does all of that via Mermaid etc. too. Treating the
| specified code block as a sort of extensible container.
| splix wrote:
| I like Asciidoc and think it's a perfect format for tech
| documentation. It has all you need for cross referencing in docs,
| great table support, notes, etc.
|
| The main problem, as author has noticed, is the single
| implementation. That significantly limits its usage and support
| in other tools. And to my understanding it's because the owners
| of the format had overprotected it with trademarks and so on. So
| no one wants to make another implementation because it's easy to
| get into legal troubles.
| 60secs wrote:
| Asciidoc is a no-brainer. The TOC macro alone is a game changer.
|
| Just wish the documentation were so absolutely awful -- extremely
| bare and hard to find examples. Enumerated values poorly
| explained, if at all.
___________________________________________________________________
(page generated 2023-02-06 23:01 UTC)