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

91–100 of 124 posts

Re: I wish Asciidoc was more popular

#91

Post by gorgoiler »

thayne wrote: post #90
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.

Yeah, it was just an example really. Going down this route of argument, do you need to move from markdown to asciidoc for admonitions, or do you really just need a good stylesheet? I would argue that the markup helper and the styling can — and usually do — end up being separate from each other.

Re: I wish Asciidoc was more popular

#92

Post by atomicnature »

invalidname wrote: post #87
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 th…

I've written a ~300 page book in MD using book-template [1], and I must say, it was a wonderful experience. I did 1 chapter = 1 file. It had tables, images, etc with a nice TOC along with references and appendix. All the basics for writing a book work just fine with md, I'd say. Here is the output (in pdf, epub, html) for you to judge [2]

[1] https://github.com/alessandrocucci/book-template

[2] https://turnoverbook.com/

Re: I wish Asciidoc was more popular

#93

Post by gorgoiler »

Symbiote wrote: post #56
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…

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 sure a PDF engine would just do automatically for me. Alas, no budget for Prince CSS was available.

Re: I wish Asciidoc was more popular

#94

Post by invalidname »

atomicnature wrote: post #92
invalidname wrote: post #87

Earlier quoted context omitted.

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

I've written a ~300 page book in MD using book-template [1], and I must say, it was a wonderful experience. I did 1 chapter = 1 file. It had tables, images, etc with a nice TOC along with references and appendix. All the basics for writing a book work just fine with md, I'd say. Here is the output (in pdf, epub, html) for you to judge [2] [1] https://github.com/alessandrocucci/book-template [2] https://turnoverbook.c…

How did you do code callouts? Admonitions etc.?

From my experience you need to use custom syntax for those which means tooling doesn't work well. (grammar, spelling, style etc.).

O'Reilly and Manning standardized on asciidoc.

Re: I wish Asciidoc was more popular

#95

Post by atomicnature »

invalidname wrote: post #94
atomicnature wrote: post #92

Earlier quoted context omitted.

I've written a ~300 page book in MD using book-template [1], and I must say, it was a wonderful experience. I did 1 chapter = 1 file. It had tables, images, etc with a nice TOC along with references and appendix. All the basics for writing a book work just fine with md, I'd say. Here is the output (in pdf, epub, html) for you to judge [2] [1] https://github.com/alessandrocucci/book-template [2] https://turnoverbook.c…

How did you do code callouts? Admonitions etc.? From my experience you need to use custom syntax for those which means tooling doesn't work well. (grammar, spelling, style etc.). O'Reilly and Manning standardized on asciidoc.

For extending markdown capabilities, there are many plugins/filters. Example [1].

I remember using extensions/filters for citations, etc.

Ultimately it is just some custom tooling around pandoc; so whatever you can do in pandoc, you can get done in the book.

[1] - https://github.com/chdemko/pandoc-latex-admonition

[2] - https://pandoc.org/

Re: I wish Asciidoc was more popular

#96

Post by noobermin »

aidenn0 wrote: post #88
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.

I thought the GC was optional in D, was it not?

Re: I wish Asciidoc was more popular

#97

Post by thayne »

teknopaul wrote: post #15
ethanwillis wrote: post #12

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…

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.

> What ever your tool does defines it

What if you have multiple tools that use different flavors of markdown? Even if you don't ever use multiple tools on the same input, you have to remember which syntax is allowed by which tool.

Re: I wish Asciidoc was more popular

#98

Post by arunc »

noobermin wrote: post #96
aidenn0 wrote: post #88

Earlier quoted context omitted.

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

I thought the GC was optional in D, was it not?

Not easy and not out of the box. You have to fight it out.

Re: I wish Asciidoc was more popular

#99

Post by SPBS »

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

Post reply on HN