Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

I wish Asciidoc was more popular

pdx.su

Post reply on HN
Print view View original

11–20 of 124 posts

Re: I wish Asciidoc was more popular

#11

Post by vmiklos »

hobo_mark wrote: post #5

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?

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.

Re: I wish Asciidoc was more popular

#12

Post by ethanwillis »

gorgoiler wrote: post #4

Very briefly on admonitions: there is nothing stopping you from adding them to markdown yourself: You _really_ shouldn’t play with matches, Debbie. Later on in that document: warning { display: block; color: red; } 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…

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.

Re: I wish Asciidoc was more popular

#13

Post by fiddlosopher »

vmiklos wrote: post #11
hobo_mark wrote: post #5

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?

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.

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!

Re: I wish Asciidoc was more popular

#14

Post by teknopaul »

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

Re: I wish Asciidoc was more popular

#15

Post by teknopaul »

ethanwillis wrote: post #12
gorgoiler wrote: post #4

Very briefly on admonitions: there is nothing stopping you from adding them to markdown yourself: You _really_ shouldn’t play with matches, Debbie. Later on in that document: warning { display: block; color: red; } 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…

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…

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.

Re: I wish Asciidoc was more popular

#16

Post by eevilspock »

gorgoiler wrote: post #4

Very briefly on admonitions: there is nothing stopping you from adding them to markdown yourself: You _really_ shouldn’t play with matches, Debbie. Later on in that document: warning { display: block; color: red; } 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…

> 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 "", "", "" or ""?

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.

Re: I wish Asciidoc was more popular

#17

Post by zh3 »

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.

Re: I wish Asciidoc was more popular

#18

Post by wmat »

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.

Re: I wish Asciidoc was more popular

#19

Post by splix »

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.

Re: I wish Asciidoc was more popular

#20

Post by oneng »

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.
Post reply on HN