6 ms·

I wish Asciidoc was more popular

164 points by M911T 4y ago

yencabulator 4y ago
> 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. Unfortunately, spaces are a "weird" character. They're not visible, unless you turn on the "show invisibles" equivalent in your editor, and even with that enabled, it can be difficult to see them while scanning a document. Also, many editors will remove trailing spaces, causing your break to disappear. Feel free to use a trailing backslash for the same thing. line one\ line two https://spec.commonmark.org/0.30/#hard-line-breaks https://spec.commonmark.org/0.30/#hard-line-breaks
gnutrino 4y ago
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!
adminu 4y ago
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 4y ago
  I don't use emacs, so an emacs mode isn't that useful for me.
  - bitwize 4y ago
    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 4y ago
    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 https://orgmode.org/install.html
    - maximus-decimus 4y ago
      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 4y ago
        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.
- Oreb 4y ago
  GitHub’s org-mode support for README files was so broken that I just gave up the last time I tried, about a year ago. Is it better now?
gorgoiler 4y ago
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 4y ago
  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 4y ago
    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.
hobo_mark 4y ago
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 4y ago
  Use AsciiDoctorJ. Under the hood it's JRuby, but as a user you won't really notice, it's just a Java program.
  - hobo_mark 4y ago
    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 4y ago
      There's https://github.com/asciidoctor/asciidoctor.js https://github.com/asciidoctor/asciidoctor.js
  - baby 4y ago
    You're proposing a Java solution to someone not happy with a Ruby solution, that seems backward.
- vmiklos 4y ago
  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 4y ago
    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-asciidoctor-diffs.html https://consolelog.gitee.io/docs-asciidoctor/asciidoc-asciid... Markdown has a smaller flavors/implementations ratio!
teknopaul 4y ago
"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 4y ago
  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.
zh3 4y ago
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.
- pizza234 4y ago
  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 4y ago
    You probably have X and Wayland installed (quite why those are required for asciidoc is a question I'll leave for others).
    - pizza234 4y ago
      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.
wmat 4y ago
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 4y ago
  Markdown does all of that via Mermaid etc. too. Treating the specified code block as a sort of extensible container.
splix 4y ago
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.
oneng 4y ago
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.
- dman 4y ago
  Is the documentation publicly available by any chance?
- bobbylarrybobby 4y ago
  Curious whether you use Antora to build your docs, or something else?
preommr 4y ago
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 4y ago
  Not having includes in markdown is a real bummer, though.
  - dmitriid 4y ago
    Documentation should have includes and transcludes (?) where you can include a part of a different document that stays in sync with the original doc.
  - TheRealPomax 4y ago
    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".
    - fhennig 4y ago
      I find this view a bit simplistic. As a reader I find it much easier to follow if I don't have to piece information together from different documents. Including relevant sections in the correct place will improve the flow of the text a lot. I think the bigger downside is that the include directive doesn't really help you when you're reading the source file, but markdown was explicitly designed to also be pleasant to read "raw". Realistically however, you will render you docs into HTML (or pdf) so that doesn't really matter. I also find includes neat to include code snippets from separate files, so I can run linting and other checks on them independently (and sometimes even run scripts as independent files).
kazinator 4y ago
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.
Freak_NL 4y ago
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 4y ago
  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…
  - crottypeter 4y ago
    100% this. It might not occur to people in North America that even British English users are inconvenienced when restricted to ASCII only (GBP vs £) and therefore the name implies that this tool is not for us.
- kitsunesoba 4y ago
  > 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.
- MilStdJunkie 4y ago
  Yeah, I second this. Why not lightbook or something derived from the DocBook legacy? Things I will never understand, volume XXXIV.
chungy 4y ago
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.
- thayne 4y ago
  There is also a haskell implementation that can be used with pandoc. I'm not sure how compatible it is.
- stock_toaster 4y ago
  > And being Ruby, GitHub will use AsciiDoctor to render AsciiDoc files; but without support for includes. ;_; ref: https://github.com/github/markup/issues/1095 https://github.com/github/markup/issues/1095
aidenn0 4y ago
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 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 4y ago
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.
matklad 4y ago
If you like AsciiDoctor, another option to take a look at is https://djot.net/ https://djot.net/.
60secs 4y ago
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.
- rfdonnelly 4y ago
  The table of contents feature is killer. The AsciiDoc docs got an overhaul 2 years ago. I find them to be quite good. What are enumerated values? Do you mean ordered lists?
memorythought 4y ago
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 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/ https://asciidoc-wg.eclipse.org/ bears fruit, the Zulip seems a bit more active recently
- dragonwriter 4y ago
  > The main problem is, as noted, that it's hard to get this ruby library into whatever platform you want to deploy to There are JVM (via Jruby) and JS (compiled by Opal) versions of Asciidoctor, to the extent that is a problem with the Ruby version.
westernpopular 4y ago
> 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 4y ago
  Yes, and that differs from a line break inside a paragraph, which is what the author is discussing.
  - westernpopular 4y ago
    Oh I never realized that was the difference, thank you.
trynewideas 4y ago
AsciiDoc/AsciiDoctor are better than DITA, and that's the nicest thing I'll say about them.
amelius 4y ago
Markdown is still a poor man's XML. I'd say one of them is enough.
darekkay 4y ago
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/ https://antora.org/
- rfdonnelly 4y ago
  Antora is built on top of AsciiDoctor.
baby 4y ago
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 4y ago
  [deleted]
lfmunoz4 4y ago
[dead]
2h 4y ago
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 https://github.com/asciidoctor/asciidoctor/issues/1087
- fhennig 4y ago
  I read the thread, and it is said that by now the implementation cannot be changed without breaking a lot. But there are multiple workarounds and fixes you can apply depending on your situtation. There also seems to be a new HTML renderer where the problem is already fixed. I think this is actually a great example of how dedicated Dan Allen is to the project! He has been following up on the ticket for over 6 years! I have interacted with him briefly on the Antora Zulip Chat a couple of times and he is always very helpful, it's a pleasure.
  - 2h 4y ago
    the issue is still open, and for good reason. whatever excuse they may have, the current HTML output for lists is not idiomatic, and their suggestion is essentially to use CSS hacks to fix the problem. sadly the AsciiDoc version with the problem is the one being used by GitHub itself. So until the issue is properly fixed, a new version pushed, and the new version accepted and put into use by GitHub, I am not interested to switch. This could all happen in a week with the proper motivation. I am not sure what the worry is with backward compat. The only difference with the resultant HTML, is extraneous "p" elements would be removed from "li" elements. Anyone who has been relying on that behavior, has been relying on non-idiomatic HTML and should be inconvenienced.
jmccaf 4y ago
My work adopted ReStructured Text and Sphinx for large volume of technical documentation, similar system to AsciiDoc .
- zerocrates 4y ago
  I use reStructuredText some... it's definitely not my favorite. Just... the look of it in text is pretty rough in comparison to other similar formats, and I always find myself having a slightly tough time authoring it correctly (though this is at least partially just because I don't use it often enough to retain familiarity).
pessimizer 4y ago
I wish Asciidoc were less complicated, or at least had an official subset that cuts out most of it and leaves something that can be learned from a single-side of a piece of paper. I'm having trouble figuring out why I shouldn't use CSS if I'm going to use something this complicated and ultimately this close to CSS.
O1111OOO 4y ago
The problem I have with AsciiDoc (AD) and Markdown (MD) is that they are too effective (in the best way)! Follow my reasoning for a moment, please... I was reviewing a command-line MD reader today. I think it was the nth time I've looked it over. It's called glow : https://github.com/charmbracelet/glow https://github.com/charmbracelet/glow I always come to the same conclusion. I don't need it. I don't need to remember to use (yet) another command line program to read MD or perform a very specific (and non-vital) function. The reason is that MD and AD are so very easy to read. They are too effective at their jobs. They aren't like HTML tags that get in the way of the text. You barely even notice MD/AD in most(?) cases. Text plus MD/AD are incredibly easy to read without a 3rd-party program "rendering" the results. Having said that... the only time I got really excited about MD/AD was when there was a post about Textual Markdown : https://news.ycombinator.com/item?id=34028765 https://news.ycombinator.com/item?id=34028765 It wasn't that the "rendered" text looked great (it looked beautiful, btw) but I could see 'Textual Markdown' turning into a command-line, online browser just for MD text! Think about that... I even thought about how great it would be if the GeminiSpace folks : https://en.wikipedia.org/wiki/Gemini_(protocol)?useskin=vector https://en.wikipedia.org/wiki/Gemini_(protocol)?useskin=vect... : embraced MD/AsciiDOC instead of their limited markup language. It's exciting to think of MD/AD making themselves an alternative lightweight tagging system on the web. Exciting to think about a lightweight web in general - no tracking, adware, tons of JS, etc... Exciting to think about a bunch of browsers growing out of this (ie; you don't need billions/yr to support MD/AD browsers) - from full-blown GUIs to, well... "Textual-Markdown". Anyway... MD/AD would be great if it grew beyond offline use. For offline use only... you really don't need rendering. Maybe it helps a bit with really long files but otherwise...
fhennig 4y ago
I see a lot of comments in this thread mentioning that it is only Ruby, but there is asciidoctor.js [1], a JS implementation. I'm using it at my company for the docs, together with Antora. It's the only docs system I have used extensively, but so far I didn't miss anything! We have quite a complex system with different components versioned independently, but it just works! [1] https://docs.asciidoctor.org/asciidoctor.js/latest/ https://docs.asciidoctor.org/asciidoctor.js/latest/
- paradox460 4y ago
  FWIW, the JS implementation is just the Ruby implementation, transpiled with Opal
- xamde 4y ago
  Edit in sublime Text, save, See the browser window on the other monitor (portrait orientation) update, tweak, repeat... That is my workflow for long and short Docs. AsciidoctorJs Chrome Extension is the glue.
jmmv 4y ago
I didn’t finish reading the article yet, but a couple of things so far: * Opening the article with the problem of the line break being a trailing white space is… odd. I have written tons of Markdown and I can count in one hand the number of times I’ve had to do this. Most prose doesn’t have hard line breaks: it has paragraphs, which are easy to represent. * As for list formatting, see this https://jmmv.dev/2022/07/markdown-lists.html https://jmmv.dev/2022/07/markdown-lists.html , which fixes the problem for Markdown. It may not look pretty, but it works consistently AFAICT. In any case, yes, the warts that Markdown has are annoying.
- fluidcruft 4y ago
  I only ever learned that trailing space thing when I stumbled into the ocpoetry subreddit and started participating. Eventually I started using them elsewhere for stylistic effect in comments. But I can't really see using them much in long form prose.
slowmovintarget 4y ago
Worse is better? - Markdown beat Asciidoc - Swagger beat RAML - C++ beat D - more Each of these gained traction over the other, and each had things that made them less perfect than the other. Markdown had vague or missing areas of specification that led to incompatible implementation. Swagger couldn't do everything, or did some things in multiple ways where RAML had a normalized syntax. D theoretically improved on C, and still lives on. Markdown had more users, and more tooling. Swagger had the Swagger UI. C++ had Bjarne Stroustrup and tooling. On the up-side, sometimes these stories come 'round again. Windows beat Mac... But Mac's still here and still gaining traction. Maybe Clojure will be more popular than Go one day. Maybe we'll all chuck YAML for EDN or TOML. It could happen.
- chii 4y ago
  Good enough and simple enough, and get it out early. All of the projects that succeed through the worse is better principle is because they were easier to implement, and thus, easier to ship first and early. They have to be just good enough for their intended purpose, with relatively few competing alternatives at the time. Only after those projects became more popular, do the warts show up, and then newer projects/iterations thought up as a replacement - which, of course don't succeed because the marginal improvements don't cover the costs of replacement.
- aidenn0 4y ago
  At least for video games, the lack of a GC dependency for the standard library made C++ more attractive than D.
  - noobermin 4y ago
    I thought the GC was optional in D, was it not?
    - arunc 4y ago
      Not easy and not out of the box. You have to fight it out.
    - 4y ago
SPBS 4y ago
> One of the most powerful features of Asciidoc is the attributes and blocks system. Asciidoc documents are structured in blocks, which are arbitrary length collections of lines. Lines can be text, attributes, directives, or formatting instructions. One of the most powerful features of Markdown is that it's just text, and you don't need to learn some deep programmer lore in order to use it. Those extra features do come at a cost, such as being to tied to a single Ruby implementation and not having been ported to countless other languages because a Markdown parser is so much easier to write. And Crafting Interpreters was written in Markdown [1], you wouldn't think it because it's so beautifully formatted. Markdown is enough, simplicity wins. [1] https://journal.stuffwithstuff.com/2020/04/05/crafting-crafting-interpreters/ https://journal.stuffwithstuff.com/2020/04/05/crafting-craft...
DemocracyFTW2 4y ago
> Asciidoc fixes this elegantly. Instead of making trailing spaces indicative of a significant break, they make a trailing + character indicate the break. This solves basically every single problem the Markdown implementation has. You can visually scan for the + at the end of a line, you can have syntax formatting that makes it significant, and, going the other way, you don't need special editor features to show you its presence. That's not an elegant solution, this is a stray markup disaster waiting to happen, and in both directions: re-wrap a paragraph (I'm doing it all the freaking time), edit some more so you can't just ctrl-z, and now you've got those plus signs sprinkled throughout your text mixed with non-special plus-signs. Manual line breaks are too infrequently used to warrant such an unconspicuous markup with such a frequently used character IMHO. It's also totally arbitrary and not backed by widespread precedent. Just use <br> for heavens' sake, you can at any time just copy-paste it to reduce the chore, its semantics are among the most published text markup conventions ever, and it's in most situations unique enough to be safely searched-replaced in a document without all the headscratching that /\+(?=\n)/ vs /\+(?!\n)/ entails. Plus, <br> is impervious to reflowing paragraphs. What's not to like?
- dragonwriter 4y ago
  > That's not an elegant solution, this is a stray markup disaster waiting to happen, and in both directions: re-wrap a paragraph (I'm doing it all the freaking time), edit some more so you can't just ctrl-z, and now you've got those plus signs sprinkled throughout your text mixed with non-special plus-signs. Trailing + for breaks is for one-offs exceptions, usually with semantic reasons. If you are manually flowing a paragraph for some reason (mostly, that’s an antipattern, but...), rather than indicating a single special break, where “rewrapping” is a thing that makes sense, then using the [%hardbreaks] directive on the paragraph makes sense; there's also a document-level toggle in the header if you want to do this for a whole document. (And many of the contexts where you'd want hard breaks have their own block type, with other linked formatting changes: literal, listing, source, and verse blocks.)
DemocracyFTW2 4y ago
As a nitpick concerning the style the article is written in, when discussing a markup language of all things, please never write "there's a markup for that" without telling users what that markup looks like. This happens several times throughout the text.
Simran-B 4y ago
I don't like Asciidoc's ordered lists. . Foo . Bar . Baz Markdown is more intuitive to understand, and the idea is that it's human readable even if not rendered. 1. Foo 2. Bar 3. Baz I'm not a fan of using 1. for each bullet point, as that takes away from the "readable source code" paradigm. On the other hand, it avoids a change in indentation if you have ten or more items.
VitalyAnkh 4y ago
I wish org-mode (https://orgmode.org/ https://orgmode.org/) was more popular. It's plain text, but way better than any other competitors.
orwin 4y ago
I think org-mode is better than markdown, and both are better than asciidoc for manpages, Readme and other documentation I'll read on Vi or in a terminal. For the 'real' documentation, asciidoc (with include, I think not every implementation make the work) is generally the best. Because of includes especially, that the salient point makes asciidoc better than Latex (that I prefer generally for everything else).
miragecraft 4y ago
It’s an endless balancing act between easy to write (code-like) and easy to read (text-like). Features like table is the ultimate conundrum - if you want beautiful text based tables like in reStructuredText it becomes very difficult to write and edit unless you use a specialized editor, while Asciidoc’s table syntax is very code-like and is completely unreadable as a tabular table (almost like a simplified HTML markup). Markdown strikes a middle ground where it tries to be readable while being as easy to write by hand as possible. However in practice most people don’t bother to keep the columns aligned by hand so it still becomes quite unreadable, and you still need specialized editor to do align columns automatically if you want to retain readability. You can consider it a good compromise or failing at both tasks (I view it as the latter). Markdown is also wildly inconsistent - why have fenced codeblock feature with info string to set the language, when you can’t have fenced blockquote with info string to set the “cite” attribute? I’m actually quite fond of reStructuredText but without widespread support it’s hard to justify investing into a much less portable format.
subpixel 4y ago
It's also interesting to note that both Markdown and AsciiDoc are implementations that are rooted deeply in rendering end-use artifacts like HTML and pdf. In the engineering and technical writing fields where multiple departments have to align on a method of building documentation and technical content for users, the goal posts are shifting a bit. Many teams need to provide data that an application will parse and render in some way, and HTML is a poor choice for that. At the same time, just sending markup over the wire has serious shortcomings. I see Markdoc (https://markdoc.dev/docs/overview#how-markdoc-works https://markdoc.dev/docs/overview#how-markdoc-works) as an early entrant to the next generation of approaches to this problem: source content --> AST --> render. You _can_ write in Markdown and spit out HTML, but that technique is sort of superseded by all the additional functionality (some of which designed to make Markdown a bit more like Asciidoc).
MilStdJunkie 4y ago
If it's got exposure, complex document requirements will always go for Asciidoc over Markdown. Hell, it's got transclusion and conditionals, Asciidoc satisfies the requirements for most DITA systems. The trick is whether or not people know about Asciidoc, and of course, whether they're allowed to go for a Git+LML stack over a vendor stack. That last one can be a pretty big deal, as it involves swallowing a fair amount of liability. No one wants to spend the extra cash on writers who know how to git, they'd rather get late middle age chair warmers who've been suckling down a TW2 salary their entire professional life. Leadership would rather leave the tech stuff outside the org. The trick here is that most of these XML pubs vendors couldn't give ten strained s##ts for liability, and they disappear on pubs teams with depressing regularity. Usually right before some big contract deliverable. How's your low risk option looking now?

164 points by M911T 4y ago

> 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. Unfortunately, spaces are a "weird" character. They're not visible, unless you turn on the "show invisibles" equivalent in your editor, and even with that enabled, it can be difficult to see them while scanning a document. Also, many editors will remove trailing spaces, causing your break to disappear. Feel free to use a trailing backslash for the same thing. line one\ line two https://spec.commonmark.org/0.30/#hard-line-breaks https://spec.commonmark.org/0.30/#hard-line-breaks

gnutrino 4y ago

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!

adminu 4y ago

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 4y ago
I don't use emacs, so an emacs mode isn't that useful for me.
- bitwize 4y ago
  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 4y ago
  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 https://orgmode.org/install.html
  - maximus-decimus 4y ago
    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 4y ago
      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.
Oreb 4y ago
GitHub’s org-mode support for README files was so broken that I just gave up the last time I tried, about a year ago. Is it better now?

gorgoiler 4y ago

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

hobo_mark 4y ago

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 4y ago
Use AsciiDoctorJ. Under the hood it's JRuby, but as a user you won't really notice, it's just a Java program.
- hobo_mark 4y ago
  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 4y ago
    There's https://github.com/asciidoctor/asciidoctor.js https://github.com/asciidoctor/asciidoctor.js
- baby 4y ago
  You're proposing a Java solution to someone not happy with a Ruby solution, that seems backward.
vmiklos 4y ago
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 4y ago
  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-asciidoctor-diffs.html https://consolelog.gitee.io/docs-asciidoctor/asciidoc-asciid... Markdown has a smaller flavors/implementations ratio!

teknopaul 4y ago

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

zh3 4y ago

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.

pizza234 4y ago
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 4y ago
  You probably have X and Wayland installed (quite why those are required for asciidoc is a question I'll leave for others).
  - pizza234 4y ago
    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.

wmat 4y ago

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 4y ago
Markdown does all of that via Mermaid etc. too. Treating the specified code block as a sort of extensible container.

splix 4y ago

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.

oneng 4y ago

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.

dman 4y ago
Is the documentation publicly available by any chance?
bobbylarrybobby 4y ago
Curious whether you use Antora to build your docs, or something else?

preommr 4y ago

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 4y ago
Not having includes in markdown is a real bummer, though.
- dmitriid 4y ago
  Documentation should have includes and transcludes (?) where you can include a part of a different document that stays in sync with the original doc.
- TheRealPomax 4y ago
  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".
  - fhennig 4y ago
    I find this view a bit simplistic. As a reader I find it much easier to follow if I don't have to piece information together from different documents. Including relevant sections in the correct place will improve the flow of the text a lot. I think the bigger downside is that the include directive doesn't really help you when you're reading the source file, but markdown was explicitly designed to also be pleasant to read "raw". Realistically however, you will render you docs into HTML (or pdf) so that doesn't really matter. I also find includes neat to include code snippets from separate files, so I can run linting and other checks on them independently (and sometimes even run scripts as independent files).

kazinator 4y ago

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.

Freak_NL 4y ago

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 4y ago
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…
- crottypeter 4y ago
  100% this. It might not occur to people in North America that even British English users are inconvenienced when restricted to ASCII only (GBP vs £) and therefore the name implies that this tool is not for us.
kitsunesoba 4y ago
> 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.
MilStdJunkie 4y ago
Yeah, I second this. Why not lightbook or something derived from the DocBook legacy? Things I will never understand, volume XXXIV.

chungy 4y ago

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.

thayne 4y ago
There is also a haskell implementation that can be used with pandoc. I'm not sure how compatible it is.
stock_toaster 4y ago
> And being Ruby, GitHub will use AsciiDoctor to render AsciiDoc files; but without support for includes. ;_; ref: https://github.com/github/markup/issues/1095 https://github.com/github/markup/issues/1095

aidenn0 4y ago

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

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.

matklad 4y ago

If you like AsciiDoctor, another option to take a look at is https://djot.net/ https://djot.net/.

60secs 4y ago

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.

rfdonnelly 4y ago
The table of contents feature is killer. The AsciiDoc docs got an overhaul 2 years ago. I find them to be quite good. What are enumerated values? Do you mean ordered lists?

memorythought 4y ago

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 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/ https://asciidoc-wg.eclipse.org/ bears fruit, the Zulip seems a bit more active recently

dragonwriter 4y ago
> The main problem is, as noted, that it's hard to get this ruby library into whatever platform you want to deploy to There are JVM (via Jruby) and JS (compiled by Opal) versions of Asciidoctor, to the extent that is a problem with the Ruby version.

westernpopular 4y ago

> 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 4y ago
Yes, and that differs from a line break inside a paragraph, which is what the author is discussing.
- westernpopular 4y ago
  Oh I never realized that was the difference, thank you.

trynewideas 4y ago

AsciiDoc/AsciiDoctor are better than DITA, and that's the nicest thing I'll say about them.

amelius 4y ago

Markdown is still a poor man's XML. I'd say one of them is enough.

darekkay 4y ago

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/ https://antora.org/

rfdonnelly 4y ago
Antora is built on top of AsciiDoctor.

baby 4y ago

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 4y ago
[deleted]

lfmunoz4 4y ago

[dead]

2h 4y ago

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 https://github.com/asciidoctor/asciidoctor/issues/1087

fhennig 4y ago
I read the thread, and it is said that by now the implementation cannot be changed without breaking a lot. But there are multiple workarounds and fixes you can apply depending on your situtation. There also seems to be a new HTML renderer where the problem is already fixed. I think this is actually a great example of how dedicated Dan Allen is to the project! He has been following up on the ticket for over 6 years! I have interacted with him briefly on the Antora Zulip Chat a couple of times and he is always very helpful, it's a pleasure.
- 2h 4y ago
  the issue is still open, and for good reason. whatever excuse they may have, the current HTML output for lists is not idiomatic, and their suggestion is essentially to use CSS hacks to fix the problem. sadly the AsciiDoc version with the problem is the one being used by GitHub itself. So until the issue is properly fixed, a new version pushed, and the new version accepted and put into use by GitHub, I am not interested to switch. This could all happen in a week with the proper motivation. I am not sure what the worry is with backward compat. The only difference with the resultant HTML, is extraneous "p" elements would be removed from "li" elements. Anyone who has been relying on that behavior, has been relying on non-idiomatic HTML and should be inconvenienced.

jmccaf 4y ago

My work adopted ReStructured Text and Sphinx for large volume of technical documentation, similar system to AsciiDoc .

zerocrates 4y ago
I use reStructuredText some... it's definitely not my favorite. Just... the look of it in text is pretty rough in comparison to other similar formats, and I always find myself having a slightly tough time authoring it correctly (though this is at least partially just because I don't use it often enough to retain familiarity).

pessimizer 4y ago

I wish Asciidoc were less complicated, or at least had an official subset that cuts out most of it and leaves something that can be learned from a single-side of a piece of paper. I'm having trouble figuring out why I shouldn't use CSS if I'm going to use something this complicated and ultimately this close to CSS.

O1111OOO 4y ago

The problem I have with AsciiDoc (AD) and Markdown (MD) is that they are too effective (in the best way)! Follow my reasoning for a moment, please... I was reviewing a command-line MD reader today. I think it was the nth time I've looked it over. It's called glow : https://github.com/charmbracelet/glow https://github.com/charmbracelet/glow I always come to the same conclusion. I don't need it. I don't need to remember to use (yet) another command line program to read MD or perform a very specific (and non-vital) function. The reason is that MD and AD are so very easy to read. They are too effective at their jobs. They aren't like HTML tags that get in the way of the text. You barely even notice MD/AD in most(?) cases. Text plus MD/AD are incredibly easy to read without a 3rd-party program "rendering" the results. Having said that... the only time I got really excited about MD/AD was when there was a post about Textual Markdown : https://news.ycombinator.com/item?id=34028765 https://news.ycombinator.com/item?id=34028765 It wasn't that the "rendered" text looked great (it looked beautiful, btw) but I could see 'Textual Markdown' turning into a command-line, online browser just for MD text! Think about that... I even thought about how great it would be if the GeminiSpace folks : https://en.wikipedia.org/wiki/Gemini_(protocol)?useskin=vector https://en.wikipedia.org/wiki/Gemini_(protocol)?useskin=vect... : embraced MD/AsciiDOC instead of their limited markup language. It's exciting to think of MD/AD making themselves an alternative lightweight tagging system on the web. Exciting to think about a lightweight web in general - no tracking, adware, tons of JS, etc... Exciting to think about a bunch of browsers growing out of this (ie; you don't need billions/yr to support MD/AD browsers) - from full-blown GUIs to, well... "Textual-Markdown". Anyway... MD/AD would be great if it grew beyond offline use. For offline use only... you really don't need rendering. Maybe it helps a bit with really long files but otherwise...

fhennig 4y ago

I see a lot of comments in this thread mentioning that it is only Ruby, but there is asciidoctor.js [1], a JS implementation. I'm using it at my company for the docs, together with Antora. It's the only docs system I have used extensively, but so far I didn't miss anything! We have quite a complex system with different components versioned independently, but it just works! [1] https://docs.asciidoctor.org/asciidoctor.js/latest/ https://docs.asciidoctor.org/asciidoctor.js/latest/

paradox460 4y ago
FWIW, the JS implementation is just the Ruby implementation, transpiled with Opal
xamde 4y ago
Edit in sublime Text, save, See the browser window on the other monitor (portrait orientation) update, tweak, repeat... That is my workflow for long and short Docs. AsciidoctorJs Chrome Extension is the glue.

jmmv 4y ago

I didn’t finish reading the article yet, but a couple of things so far: * Opening the article with the problem of the line break being a trailing white space is… odd. I have written tons of Markdown and I can count in one hand the number of times I’ve had to do this. Most prose doesn’t have hard line breaks: it has paragraphs, which are easy to represent. * As for list formatting, see this https://jmmv.dev/2022/07/markdown-lists.html https://jmmv.dev/2022/07/markdown-lists.html , which fixes the problem for Markdown. It may not look pretty, but it works consistently AFAICT. In any case, yes, the warts that Markdown has are annoying.

fluidcruft 4y ago
I only ever learned that trailing space thing when I stumbled into the ocpoetry subreddit and started participating. Eventually I started using them elsewhere for stylistic effect in comments. But I can't really see using them much in long form prose.

slowmovintarget 4y ago

Worse is better? - Markdown beat Asciidoc - Swagger beat RAML - C++ beat D - more Each of these gained traction over the other, and each had things that made them less perfect than the other. Markdown had vague or missing areas of specification that led to incompatible implementation. Swagger couldn't do everything, or did some things in multiple ways where RAML had a normalized syntax. D theoretically improved on C, and still lives on. Markdown had more users, and more tooling. Swagger had the Swagger UI. C++ had Bjarne Stroustrup and tooling. On the up-side, sometimes these stories come 'round again. Windows beat Mac... But Mac's still here and still gaining traction. Maybe Clojure will be more popular than Go one day. Maybe we'll all chuck YAML for EDN or TOML. It could happen.

chii 4y ago
Good enough and simple enough, and get it out early. All of the projects that succeed through the worse is better principle is because they were easier to implement, and thus, easier to ship first and early. They have to be just good enough for their intended purpose, with relatively few competing alternatives at the time. Only after those projects became more popular, do the warts show up, and then newer projects/iterations thought up as a replacement - which, of course don't succeed because the marginal improvements don't cover the costs of replacement.
aidenn0 4y ago
At least for video games, the lack of a GC dependency for the standard library made C++ more attractive than D.
- noobermin 4y ago
  I thought the GC was optional in D, was it not?
  - arunc 4y ago
    Not easy and not out of the box. You have to fight it out.
  - 4y ago

SPBS 4y ago

> One of the most powerful features of Asciidoc is the attributes and blocks system. Asciidoc documents are structured in blocks, which are arbitrary length collections of lines. Lines can be text, attributes, directives, or formatting instructions. One of the most powerful features of Markdown is that it's just text, and you don't need to learn some deep programmer lore in order to use it. Those extra features do come at a cost, such as being to tied to a single Ruby implementation and not having been ported to countless other languages because a Markdown parser is so much easier to write. And Crafting Interpreters was written in Markdown [1], you wouldn't think it because it's so beautifully formatted. Markdown is enough, simplicity wins. [1] https://journal.stuffwithstuff.com/2020/04/05/crafting-crafting-interpreters/ https://journal.stuffwithstuff.com/2020/04/05/crafting-craft...

DemocracyFTW2 4y ago

> Asciidoc fixes this elegantly. Instead of making trailing spaces indicative of a significant break, they make a trailing + character indicate the break. This solves basically every single problem the Markdown implementation has. You can visually scan for the + at the end of a line, you can have syntax formatting that makes it significant, and, going the other way, you don't need special editor features to show you its presence. That's not an elegant solution, this is a stray markup disaster waiting to happen, and in both directions: re-wrap a paragraph (I'm doing it all the freaking time), edit some more so you can't just ctrl-z, and now you've got those plus signs sprinkled throughout your text mixed with non-special plus-signs. Manual line breaks are too infrequently used to warrant such an unconspicuous markup with such a frequently used character IMHO. It's also totally arbitrary and not backed by widespread precedent. Just use <br> for heavens' sake, you can at any time just copy-paste it to reduce the chore, its semantics are among the most published text markup conventions ever, and it's in most situations unique enough to be safely searched-replaced in a document without all the headscratching that /\+(?=\n)/ vs /\+(?!\n)/ entails. Plus, <br> is impervious to reflowing paragraphs. What's not to like?

dragonwriter 4y ago
> That's not an elegant solution, this is a stray markup disaster waiting to happen, and in both directions: re-wrap a paragraph (I'm doing it all the freaking time), edit some more so you can't just ctrl-z, and now you've got those plus signs sprinkled throughout your text mixed with non-special plus-signs. Trailing + for breaks is for one-offs exceptions, usually with semantic reasons. If you are manually flowing a paragraph for some reason (mostly, that’s an antipattern, but...), rather than indicating a single special break, where “rewrapping” is a thing that makes sense, then using the [%hardbreaks] directive on the paragraph makes sense; there's also a document-level toggle in the header if you want to do this for a whole document. (And many of the contexts where you'd want hard breaks have their own block type, with other linked formatting changes: literal, listing, source, and verse blocks.)

DemocracyFTW2 4y ago

As a nitpick concerning the style the article is written in, when discussing a markup language of all things, please never write "there's a markup for that" without telling users what that markup looks like. This happens several times throughout the text.

Simran-B 4y ago

I don't like Asciidoc's ordered lists. . Foo . Bar . Baz Markdown is more intuitive to understand, and the idea is that it's human readable even if not rendered. 1. Foo 2. Bar 3. Baz I'm not a fan of using 1. for each bullet point, as that takes away from the "readable source code" paradigm. On the other hand, it avoids a change in indentation if you have ten or more items.

VitalyAnkh 4y ago

I wish org-mode (https://orgmode.org/ https://orgmode.org/) was more popular. It's plain text, but way better than any other competitors.

orwin 4y ago

I think org-mode is better than markdown, and both are better than asciidoc for manpages, Readme and other documentation I'll read on Vi or in a terminal. For the 'real' documentation, asciidoc (with include, I think not every implementation make the work) is generally the best. Because of includes especially, that the salient point makes asciidoc better than Latex (that I prefer generally for everything else).

miragecraft 4y ago

It’s an endless balancing act between easy to write (code-like) and easy to read (text-like). Features like table is the ultimate conundrum - if you want beautiful text based tables like in reStructuredText it becomes very difficult to write and edit unless you use a specialized editor, while Asciidoc’s table syntax is very code-like and is completely unreadable as a tabular table (almost like a simplified HTML markup). Markdown strikes a middle ground where it tries to be readable while being as easy to write by hand as possible. However in practice most people don’t bother to keep the columns aligned by hand so it still becomes quite unreadable, and you still need specialized editor to do align columns automatically if you want to retain readability. You can consider it a good compromise or failing at both tasks (I view it as the latter). Markdown is also wildly inconsistent - why have fenced codeblock feature with info string to set the language, when you can’t have fenced blockquote with info string to set the “cite” attribute? I’m actually quite fond of reStructuredText but without widespread support it’s hard to justify investing into a much less portable format.

subpixel 4y ago

It's also interesting to note that both Markdown and AsciiDoc are implementations that are rooted deeply in rendering end-use artifacts like HTML and pdf. In the engineering and technical writing fields where multiple departments have to align on a method of building documentation and technical content for users, the goal posts are shifting a bit. Many teams need to provide data that an application will parse and render in some way, and HTML is a poor choice for that. At the same time, just sending markup over the wire has serious shortcomings. I see Markdoc (https://markdoc.dev/docs/overview#how-markdoc-works https://markdoc.dev/docs/overview#how-markdoc-works) as an early entrant to the next generation of approaches to this problem: source content --> AST --> render. You _can_ write in Markdown and spit out HTML, but that technique is sort of superseded by all the additional functionality (some of which designed to make Markdown a bit more like Asciidoc).

MilStdJunkie 4y ago

If it's got exposure, complex document requirements will always go for Asciidoc over Markdown. Hell, it's got transclusion and conditionals, Asciidoc satisfies the requirements for most DITA systems. The trick is whether or not people know about Asciidoc, and of course, whether they're allowed to go for a Git+LML stack over a vendor stack. That last one can be a pretty big deal, as it involves swallowing a fair amount of liability. No one wants to spend the extra cash on writers who know how to git, they'd rather get late middle age chair warmers who've been suckling down a TW2 salary their entire professional life. Leadership would rather leave the tech stuff outside the org. The trick here is that most of these XML pubs vendors couldn't give ten strained s##ts for liability, and they disappear on pubs teams with depressing regularity. Usually right before some big contract deliverable. How's your low risk option looking now?