Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Markdown's Big Brother: Say Hello to AsciiDoc

git-tower.com

Post reply on HN
Print view View original

51–60 of 65 posts

Re: Markdown's Big Brother: Say Hello to AsciiDoc

#51

Post by CrimsonRain »

andrewl-hn wrote: post #14

We’ve used AsciiDoc for some of our documentation and for generating slide decks. It is obviously a nice system but over time our frustration with it grew. Every other piece of software we have uses Markdown: GitHub, work chat, chats of open source projects we work with, things like StackOverflow, HackMD, personal note taking apps, the list goes on and on. Every new person joining our team had to adjust to AsciiDoc j…

Adoc is too cumbersome and the tooling around it are always subpar; sometimes unusable. It also is trying to be somewhat of a replacement of html and is really bad at it.

Markdown + html or simply Hugo is way better.

Re: Markdown's Big Brother: Say Hello to AsciiDoc

#52

Post by CrimsonRain »

ffaser5gxlsll wrote: post #20
andrewl-hn wrote: post #14

We’ve used AsciiDoc for some of our documentation and for generating slide decks. It is obviously a nice system but over time our frustration with it grew. Every other piece of software we have uses Markdown: GitHub, work chat, chats of open source projects we work with, things like StackOverflow, HackMD, personal note taking apps, the list goes on and on. Every new person joining our team had to adjust to AsciiDoc j…

The frustration for me is then which "flavored" version of markdown you're now using, because the evolution seems to always be "MD is simple and popular" until gets extended with subtle differences. Those subtle semi-random differences in flavors get tiring really fast.

What's the frustration about? Basic things are same everywhere.

If you need complex things, you already have enough skills to figure that out. Also there's almost always a help button around that lists what it supports.

Re: Markdown's Big Brother: Say Hello to AsciiDoc

#53

Post by alp1n3_eth »

Tooling for asciidoc (last time I used it) was super sparse and next to unusable. There was primarily one underlying engine everyone relied on to do cross-filetype generations, and the available editors was pretty bad as well. Of the few free ones, the recommended list was like:

- JetBrains Plugin - VSCode Plugin

I wanted to like it, but doing anything was a bit of a pain. If I need that level of structure, I'd rather work with something like Typst. Otherwise Markdown works fine.

Re: Markdown's Big Brother: Say Hello to AsciiDoc

#54

Post by mdaniel »

ognyankulev wrote: post #3

I was hoping Eclipse AsciiDoc would already deliver stable spec, TCK and (new) reference implementation: https://asciidoc-wg.eclipse.org/projects/

I was expecting it to be Yet Another Eclipse Abandonware but https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-la... has commits from 5 hours ago, and https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-tc... was 10 months ago, which isn't nothing. But yikes they are not doing themselves any discoverability favors by having almost every meaningful looking link on https://projects.eclipse.org/projects/asciidoc.asciidoc-lang point to itself

Re: Markdown's Big Brother: Say Hello to AsciiDoc

#55

Post by replete »

kimi wrote: post #13

My company uses Asciidoc for documentation - for almost 20 years now - and it's really good. Now with Antora you can make searchable docs, and with Asciidoctor you can create most diagrams right within the text. We target HTML/PDF/Epub and it works really well. So you get a result that is Word-quality, but separates presentation and content, and is easy to keep under version control.

Do you also use it for company docs, policies etc, or only for software documentation? Would love to see the back of Word.

Re: Markdown's Big Brother: Say Hello to AsciiDoc

#56

Post by bcantrill »

sausagefeet wrote: post #9

I've been using AsciiDoc since Oxide did a podcast on their RFDs and I love it. I find it so much saner than Markdown, and it covers more usecases. I wish there were more implementations but asciidoctor works great. Hugo also supports AsciiDoc.

That's awesome to hear! For other folks, our discussion is at [0] -- in which I learn that AsciiDoc is nowhere near as ubiquitous as I thought it to be. (But optimistic that that's starting to change, especially given the article!)

[0] https://oxide-and-friends.transistor.fm/episodes/rfds-the-ba...

Re: Markdown's Big Brother: Say Hello to AsciiDoc

#57

Post by everforward »

pindab0ter wrote: post #17
xeonmc wrote: post #15

Earlier quoted context omitted.

Ruby.

What do you mean? Is Ruby helping or preventing AsciiDoc from becoming more widespread?

I think preventing. I don't think Ruby is a bad language, but I've never worked anywhere it was a first or even second class language. I like AsciiDoc, but it's a hard sell to convince people to manage an entire other language toolchain used for nothing but AsciiDoc. I don't think the distro packaged it, or maybe not a recent enough version, but I could be wrong.

It's already hard enough to get people to switch documentation formats, needing to manage another language for it is just a bridge too far everywhere I've worked. It would be an easier sell if it were statically compiled, or at least in an interpreted language we already used (Python or JS most places).

Re: Markdown's Big Brother: Say Hello to AsciiDoc

#58

Post by red_admiral »

drdec wrote: post #47
red_admiral wrote: post #21

> If you’ve been relying on Markdown and occasionally fighting its quirks, AsciiDoc might be the structured, fully-featured alternative you didn’t know you needed. No, I'm afraid it's the format I know I don't need. At least not for the kind of things I usually use markdown for. Readme files, technical documentation, moderately complex websites with templating and rendering engines - markdown works just fine. Sometim…

I have used asciidoc when I needed to generate PDFs for documentation. You don't need any paid tools if you don't want them, I used a text editor and the terminal and source control. I don't understand the hostility toward someone offering a product. It's fine that you don't need it, that doesn't mean someone else won't.

My worldview is there's a big market for WYSIWYG editors, and a big "market" for FOSS editors and tools, but not too much in between for simple text editing.

I can't think of many scenarios where someone does care about the backing format or explicitly wants to write raw asciidoc, but doesn't want to just use asciidoctor or other free CLI tools.

Re: Markdown's Big Brother: Say Hello to AsciiDoc

#59

Post by Symbiote »

L3viathan wrote: post #36
Tomte wrote: post #8

Earlier quoted context omitted.

AsciiDoc is even older than Markdown.

Only technically. By that name, yes, but much of Markdown was "discovered" rather than invented, having been used in email/newsgroups/... for a long time.

Those parts apply equally to both languages.

Re: Markdown's Big Brother: Say Hello to AsciiDoc

#60

Post by citrin_ru »

CrimsonRain wrote: post #52
ffaser5gxlsll wrote: post #20

Earlier quoted context omitted.

The frustration for me is then which "flavored" version of markdown you're now using, because the evolution seems to always be "MD is simple and popular" until gets extended with subtle differences. Those subtle semi-random differences in flavors get tiring really fast.

What's the frustration about? Basic things are same everywhere. If you need complex things, you already have enough skills to figure that out. Also there's almost always a help button around that lists what it supports.

For me the frustration is that you cannot learn markdown once and use it in different places - for non-trivial things you always have to use a reference for a particular flavor.
Post reply on HN