4 ms·

I would caution anyone against using AsciiDoc. I really want to like AsciiDoc, but it has glaring issues for many years, that the developers seem to have no int

by 2h 4y ago

I would caution anyone against using AsciiDoc. I really want to like AsciiDoc, but it has glaring issues for many years, that the developers seem to have no interest in fixing: https://github.com/asciidoctor/asciidoctor/issues/1087 https://github.com/asciidoctor/asciidoctor/issues/1087

terrorOf 4y ago
[dead]
gouggoug 4y ago
What other glaring issues can you think of up the top of your head that you caution against using asciidoc? The one GitHub issue linked seems like quite a nitpick. Been using it for years, and I haven’t run into any issue thy would make me want to use anything else.
- matijsvzuijlen 4y ago
  The format itself has several warts, like the ancestor list continuation syntax, or whether or not to add a backslash if you want a literal asterisk. The implementation lacks checking, so for example if you have some text between square brackets, it will often just get dropped even if the contents is not valid as an attribute list.
  - aidenn0 4y ago
    AsciiDoctor now has an unambiguous way to insert an asterisk. The original Python implementation does not.
    - aidenn0 4y ago
      I was on my phone when I posted the above, so couldn't easily look up the exact way it's: {asterisk}
- recfab 4y ago
  I'm not sure I would caution against AsciiDoc, but I stopped using it personally due to lack of support, and Markdown (of various flavors) being good enough for the use cases I cared about at the time. There isn't much tooling. The community is small. The spec effort seems to have stagnated. AsciiDoctor and related projects seem to move at the speed of what Dan Allen decides is most worth his time. That said, I've been wanting to do more long form writing, and AsciiDoc is lovely for that, so I may pick it up again for that.
Symbiote 4y ago
At work I have about 500k words of AsciiDoctor source, and everyone (developers + document authors) is pleased with it. That looks like a minor issue in GitHub's stylesheet, not really an AsciiDoctor problem.
- 2h 4y ago
  > That looks like a minor issue in GitHub's stylesheet, not really an AsciiDoctor problem. AsciiDoctor is adding p elements in places where it should not. GitHub could work around this error with CSS, but they have not done so, nor should they. It's a simple issue to fix, just emit the bare li elements.
toastal 4y ago
https://github.com/jirutka/asciidoctor-html5s https://github.com/jirutka/asciidoctor-html5s The HTML alternate back-end fixes a lot of these issues and chooses semantic elements for a more modern age (while Asciidoctor is actively overhauling its output I believe). The issue visually can be solved with CSS as-is (remove the padding or margin from li > p:only-child), but Microsoft GitHub treats its AsciiDoc rendering as a second-class citizen despite it objectively having more/better features for documentation than Markdown. The negligence becomes apparent when you look at the way GitHub syntax fork (“flavor”) handles admonitions; not only does it overload, overcomplicate, and ruin the semantics of the blockquote, but the CSS styling that makes them look nice was never ported to admonitions for reStructuredText and AsciiDoc despite these formats having the feature natively to the syntax (no fork required) since forever.
- 2h 4y ago
  > Asciidoctor is actively overhauling its output I believe It's been 9 years. That is not actively by any definition of the word.

by 2h 4y ago

terrorOf 4y ago

[dead]

gouggoug 4y ago

What other glaring issues can you think of up the top of your head that you caution against using asciidoc? The one GitHub issue linked seems like quite a nitpick. Been using it for years, and I haven’t run into any issue thy would make me want to use anything else.

matijsvzuijlen 4y ago
The format itself has several warts, like the ancestor list continuation syntax, or whether or not to add a backslash if you want a literal asterisk. The implementation lacks checking, so for example if you have some text between square brackets, it will often just get dropped even if the contents is not valid as an attribute list.
- aidenn0 4y ago
  AsciiDoctor now has an unambiguous way to insert an asterisk. The original Python implementation does not.
  - aidenn0 4y ago
    I was on my phone when I posted the above, so couldn't easily look up the exact way it's: {asterisk}
recfab 4y ago
I'm not sure I would caution against AsciiDoc, but I stopped using it personally due to lack of support, and Markdown (of various flavors) being good enough for the use cases I cared about at the time. There isn't much tooling. The community is small. The spec effort seems to have stagnated. AsciiDoctor and related projects seem to move at the speed of what Dan Allen decides is most worth his time. That said, I've been wanting to do more long form writing, and AsciiDoc is lovely for that, so I may pick it up again for that.

Symbiote 4y ago

At work I have about 500k words of AsciiDoctor source, and everyone (developers + document authors) is pleased with it. That looks like a minor issue in GitHub's stylesheet, not really an AsciiDoctor problem.

2h 4y ago
> That looks like a minor issue in GitHub's stylesheet, not really an AsciiDoctor problem. AsciiDoctor is adding p elements in places where it should not. GitHub could work around this error with CSS, but they have not done so, nor should they. It's a simple issue to fix, just emit the bare li elements.

toastal 4y ago

https://github.com/jirutka/asciidoctor-html5s https://github.com/jirutka/asciidoctor-html5s The HTML alternate back-end fixes a lot of these issues and chooses semantic elements for a more modern age (while Asciidoctor is actively overhauling its output I believe). The issue visually can be solved with CSS as-is (remove the padding or margin from li > p:only-child), but Microsoft GitHub treats its AsciiDoc rendering as a second-class citizen despite it objectively having more/better features for documentation than Markdown. The negligence becomes apparent when you look at the way GitHub syntax fork (“flavor”) handles admonitions; not only does it overload, overcomplicate, and ruin the semantics of the blockquote, but the CSS styling that makes them look nice was never ported to admonitions for reStructuredText and AsciiDoc despite these formats having the feature natively to the syntax (no fork required) since forever.

2h 4y ago
> Asciidoctor is actively overhauling its output I believe It's been 9 years. That is not actively by any definition of the word.