Live data from Hacker News

I wish Asciidoc was more popular

pdx.su

121–124 of 124 posts

Re: I wish Asciidoc was more popular

#121

> 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…

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

Re: I wish Asciidoc was more popular

#122
post #20

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.

Curious whether you use Antora to build your docs, or something else?

Re: I wish Asciidoc was more popular

#123

Earlier quoted context omitted.

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…

Key word is "few", which is why AsciiDoc is so frustrating to work with. Not on account of it's own shortcoming, but because so little activity is going on in the community to push it forward or to drive further support. For example, if GitHub fully supported AsciiDoc, you'd see a lot more people considering it. But it's just not worth the headache to them, apparently.

I have to fully agree with you unfortunately :\

Re: I wish Asciidoc was more popular

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