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

81–90 of 124 posts

Re: I wish Asciidoc was more popular

#81

Post by stock_toaster »

chungy wrote: post #34

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

> And being Ruby, GitHub will use AsciiDoctor to render AsciiDoc files;

but without support for includes. ;_;

ref: https://github.com/github/markup/issues/1095

Re: I wish Asciidoc was more popular

#82

Post by jmmv »

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

Re: I wish Asciidoc was more popular

#83

Post by bad_username »

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…

Markdown parsing inside html is hit and miss. Obsidian won't do it, for example.

Re: I wish Asciidoc was more popular

#84

Post by fluidcruft »

jmmv wrote: post #82

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

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.

Re: I wish Asciidoc was more popular

#85

Post by slowmovintarget »

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.

Re: I wish Asciidoc was more popular

#86

Post by chii »

slowmovintarget wrote: post #85

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

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.

Re: I wish Asciidoc was more popular

#87

Post by invalidname »

preommr wrote: post #21

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.

I wrote a couple of books in asciidoc. MD might work for a web comment but if you want to write something sophisticated like a book you need more. E.g.

TIP: my tip

Super helpful when you're writing a book. My blog provider uses MD and I no longer have these handy popups or cool sidebars. I won't even get into tables etc.

Include is a bit problematic but having a way to have 1 chapter = 1 file is wonderful. You can then package the whole book with a file that lists the includes. Very convenient.

Re: I wish Asciidoc was more popular

#88

Post by aidenn0 »

slowmovintarget wrote: post #85

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

At least for video games, the lack of a GC dependency for the standard library made C++ more attractive than D.

Re: I wish Asciidoc was more popular

#89

Post by deafpolygon »

slowmovintarget wrote: post #85

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

> But Mac's still here and still gaining traction.

They've been on a ever-so-slight decline (~ -3%) since the 2020's. On the other hand, Windows is stabilizing it's slow decline.

Re: I wish Asciidoc was more popular

#90

Post by thayne »

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…

If you want an admonition that looks good, and not just a red box, you'll need a bit more css than that. And probably need to include an inline icon.

Oh, and github strips out style tags, so it doesn't work there.

Post reply on HN