111–120 of 124 posts
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.
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…
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.
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) 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).
Earlier quoted context omitted.
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 mark…
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…
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…
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.
On the other hand, if you're documenting an end product with complex print output, hundreds of (slightly) different configurations, and need transclusion, partial transclusion, conditionals - to say nothing of wacky tables and olists- you end up with a giant pile of Markdown customization. It's easier to just use Asciidoc off the shelf, not to mention that you get DocBook interoperability, which lets you transform to all sorts of weird old formats.
But that complex use case often comes with dollars attached for big proprietary solutions. Asciidoc is a an open standard in a space that usually has vendor solutions.
Earlier quoted context omitted.
That assumes you are writing only HTML. With Asciidoctor, we produce decent-looking PDF documentation as well as HTML.
That’s a good point. I wrote an introduction to CS course in Asciidoctor. The pure Ruby prawn stuff for rendering PNGs into PDFs, which is done bit by bit, ended up being too slow for me. I had hacks for doing fast proof-copies with low resolution images, but it ends up being much easier rendering the source into HTML and the HTML into PDF. Faster, but also requires a lot of learning about CSS page breaking which I’m…
Asciidoctor-pdf:: this is the Ruby prawn-based thing, it's the current official path, but SVG and images can choke it. Complex customization means extensions, and that has its own overhead.
FOPUB aka docbook-xsl:: this is built in to the AsciidocFX dedicated editor, and uses the DocBook-XSL pipeline. Yeah, I know, it's XSL, but since DocBook has such a long tail there's a huge amount of customization that's possible, along with some docbook-only features like better indices, list of figures, etc. It's also very capable of chewing through thousand page books if it's in its own environment. But again, XSL.
asciidoctor-web-pdf:: this is the semi-experimental web based PDF tool, based on Paged.js, that uses the CMM Paged Media Module Level 3 (CMM PMM L3). I think this is built in to Antora now. This has the best promise, in my opinion, but it's still pretty raw, again, in my opinion. Bring your JS and your CSS hat. Chews through some huge amounts of memory . . ah wait, they fixed that.
After these you have DBLATEX, which uses DocBook->LaTeX as its typesetting, and you have the Haskell thing, and the wiki-2-PDF converter that's default in Visual Studio Code Asciidoctor extension. There's a few others that have largely stalled, like the packt build system for docx, but they're interesting. I still use the packt thing.
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?
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 na…
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 read…
There are JVM (via Jruby) and JS (compiled by Opal) versions of Asciidoctor, to the extent that is a problem with the Ruby version.