
AsciiDoc Language Submitted to Eclipse Foundation - sandGorgon
https://projects.eclipse.org/proposals/asciidoc-language
======
kbumsik
AsciiDoc is one of the underrated markup languages when Markdown is dominent.

I know everybody knows markdown and markdown is simple, but I have seen so
many people who ended up with HTML hacks for more "advanced" features like
image size/position, complex tables, and even comments.

I higly recommend trying AsciiDoc to people who needs more features than
Markdown.

Also, it is much more PDF-friendly than Markdown so that you don't need weird
renderer workarounds to print.

~~~
sqldba
Yeah. Everyone uses it because it requires the least effort, but on so many
levels Markdown is such garbage.

From the different code block implementations, to crappy tables, to trying to
indent lists, and so forth.

But it's also the dumbest, lowest common denominator style of text. It's
missing almost anything useful.

That it's popular is an insult to anything of quality.

That's what we have though. I don't feel cosy about a text language under
stewardship either.

~~~
baby
This is because markdown is for simple note taking and is not meant to be
rendered.

It wasn’t so long ago that markdown was praised for its simplicity and it’s
not for nothing that everyone uses it nowadays.

~~~
feanaro
Considering that the original implementation of Markdown was a Markdown to
HTML renderer, your claim that it's not meant to be rendered is a bit suspect.

------
sandGorgon
One of the biggest misses for asciidoc is that it's core libraries are ruby
only. The javascript renderers are autogenerated and unmaintained.

This is also the reason why community uptake for asciidoc has been hard.
Fundamentally we do not have any pastebin or hackmd for asciidoc.. because it
is hard to build for it. Pastebin and hackmd have consistently refused to
include asciidoc.

Momentum exists in the JAMSTACK space. Yet Gatsby and Nextjs play with
markdown variants (MDX?) for markup. There are no asciidoc examples even in
their repos .

Asciidoc is undoubtedly superior to markdown..and more importantly, is a well
defined standard. But unless the core team engages with the ecosystem more,
this is DOA.

~~~
moonchild
Huh? The core/reference implementation was python-only. (Was python2-only for
a while, actually--I helped change that.) Asciidoctor (ruby) is a prominent
implementation, granted, but afaik there are quite a few other implementations
in other languages.

~~~
mbeex
Not so much. And the original Python variant is a) slowly growing old in
features, b) the Python3 variants are unfinished and are missing support. I
don't remember exactly in what respect, but I evaluated things some months ago
and reluctantly installed the ruby gem of AsciiDoctor. I would have prefered a
Python solution very much in my Python-driven environment. Also, a 'pip
install asciidoc' would be very welcome.

~~~
mbeex
> the Python3 variants are unfinished and are missing support.

I stand corrected:

[https://asciidoc.org/CHANGELOG.html](https://asciidoc.org/CHANGELOG.html)
(Version 9.0.0 (2020-06-02))

------
gorgoiler
Dan Allen’s stewardship of AsciiDoctor — the most complete implementation of
AsciiDoc available — is truly inspiring.

The level of documentation available and the amount of work that’s gone into
the software is an enormous effort. Any missing-features or quirks I’ve
googled have usually led to an existing GitHub issue that Dan is working on
himself, with a carefully considered fix in the pipeline or an explanation as
to how to implement the feature using the AsciiDoctor API.

AsciiDoc-the-standard is lucky to have a developer of his temperament and
caliber, for his own work and for the way he encourages contributions from
others.

Thank you Dan and the AsciiDoctor team!

------
timClicks
I'm surprised that no publishers are included in the "Companies and
Organizations" list. Asciidoc is a supported tool for Manning authors and
probably others.

~~~
gauravphoenix
I just recently discovered Asciidot. I was browsing Micronaut's documentation
and was impressed by it- how it allowed code lines/fragments to be annotated.
Did some RE and discovered Asciidot. So far, I am pretty impressed. I hope
more and more tooling will support it.

~~~
derekp7
I love writing documentation in asciidoc (using asciidoctor actually). However
I keep running into certain issues. For example, if a document includes
pictures, and the file path has spaces in it, then you have issues. I believe
you can replace spaces using HTML escapes if your output doc is HTML, however
that falls apart if you want to make a PDF from the same source.

I'm also still trying to wrap my head around the presentation side. You can
use something like style sheets, but it doesn't look like the same style
sheets are compatible with both HTML and PDF output (if memory serves). And if
you want to output to docx format, you can do it, but again the output looks
different.

~~~
pvorb
Another downside is that rendering larger documents to PDF will become
incredibly slow. We have documented a REST API with AsciiDoc via Spring
RestDocs and the build takes like 10 minutes for the PDF only. That doesn't
include generating the snippets with RestDocs, which is rather fast. I suspect
it has to do with AsciiDoctor being written in Ruby.

------
sandGorgon
One of the coolest utilities is to create presentations using asciidoc using
vscode
[https://marketplace.visualstudio.com/items?itemName=flobilos...](https://marketplace.visualstudio.com/items?itemName=flobilosaurus.vscode-
asciidoc-slides)

Uses reveal.js under the hood.

There's also antora, which is a toolchain for technical documentation.

[https://antora.org/](https://antora.org/)

~~~
kimi
We use Dockbooker for technical documentation:
[https://github.com/l3nz/dockbooker](https://github.com/l3nz/dockbooker) and
has been working well for a number of years. Builds PDF, EPUB and chunked-html
very easily.

------
nikolay
Unfortunately, they never implemented the legal extensions I've requested.
There's no good markup for legal documents.

UPDATE: It came out I was a bit unfair as I've submitted the issue to
AsciiDoctor. [0]

[0]:
[https://github.com/asciidoctor/asciidoctor/issues/1316](https://github.com/asciidoctor/asciidoctor/issues/1316)

------
soapdog
It is easier to spot the advantages and disadvantages of AsciiDoc vs Markdown,
but has anyone here weighted AsciiDoc vs Textile?

~~~
acqq
Or
[https://en.wikipedia.org/wiki/ReStructuredText](https://en.wikipedia.org/wiki/ReStructuredText)

"In July 2016 the Linux kernel project decided to transition from DocBook
based documentation to reStructuredText and the Sphinx toolchain.[8]"

[https://www.kernel.org/doc/html/v4.18/doc-
guide/sphinx.html](https://www.kernel.org/doc/html/v4.18/doc-
guide/sphinx.html)

------
beagle3
Is anyone aware of BiDi and-or Asian script support in AsciiDoc (or
reStructuredText or Markdown ...)? I will likely need it in a coming project,
and so far the only markup language that I've verified can properly do non-
european-language layout is (ta dum!) HTML

------
axilmar
We have html, why do we need yet another markup language?

[https://en.wikipedia.org/wiki/Comparison_of_document-
markup_...](https://en.wikipedia.org/wiki/Comparison_of_document-
markup_languages)

So many markup languages...

~~~
sradman
> We have html..

The origins of AsciiDoc is informative. AsciiDoc is a lightweight successor to
the XML DocBook format used originally to write O'Reilly computer
books/manuals. Both DocBook and ePub XML add semantic elements required to
describe book structure.

The Lightweight Markup Languages arose to avoid the tagsoup that is not
author/writer friendly. There is a place for readable/writable content that is
free of GUI editor requirements. I was once told that there is a right tool
for every job.

------
xellisx
One thing missing from a lot of these, is color. I want at least 16 of them.

------
Thorentis
AsciiDoc support in Hugo when?

~~~
wyoh
It's already supported by Hugo.

------
api
Has anyone used Eclipse recently? How does it compare to the Jetbrains stuff?
How about for languages like C++ and Go?

~~~
kbumsik
Your question is like asking about the Apache Webserver in one of unrelated
project hosted by Apache Foundation.

Eclipse Foundation is much larger organization than just the IDE.

