8 ms·
AsciiDoc Language Submitted to Eclipse Foundation
- kbumsik 6y agoAsciiDoc 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.
- thayne 6y agoAgreed. When I actually started using it, I wondered why Markdown is so prevalent when AsciiDoc is a thing.
- enriquto 6y agoThey are not that different, are they? AsciiDoc looks just like an specific dialect of markdown. Maybe a problem with AsciiDoc is that its name is scary. By the name "ascii" it seems to imply that there is a specific markup for typing non-ascii stuff, instead of simply typing the regular unicode characters (in whatever encoding).
- wirrbel 6y agoPrevalence of Markdown is to a certain extent accidental. It is one of those many markup languages that are easy-enough to reimplement which helped with the spread and I think it was supported on Github early on. Asciidoc is much more complex and so we only have 2 implementations around (a2x, asciidoctor).
- twic 6y agoI think it's an example of a phenomenon where there is a new-ish category of things, and that category is good, and there is one thing in that category that becomes well-known, so even though that thing is not the best in its category, it becomes wildly successful. Git, in the category of DVCS, is another example.
- wirrbel 6y agoThats a very valid comparison I think. (although I'd argue that git's success stems from not pinning down the workflow early on, like competing DVCS did).
- kbumsik 6y ago> Maybe a problem with AsciiDoc is that its name is scary. Exactly. For me the name "ASCII" feels like it is for older UNIX-era system experts. The name might use to be fancy considering its initial version came out in 2002 (before markdown), but it became an unfortunate name.
- deleted 6y ago[deleted]
- mbeex 6y agoNo, problem is the covered complexity. For Markdown I have never resort to any documentation - within its original scope. This is his big advantage and I appreciate this. If you need more, you have almost certainly to look up things. This is true for AsciiDoc as well as for example ReST, the syntax of the former being a bit more appealing to me (just compare simple links for example) . For this reason, I'm using a blogging system (Pelican) that supports all of them (including Pythons Markdown extensions). I'm completely free to apply the best suiting variant to the topics requirements.
- JulianMorrison 6y agoIt feels like they have distinct sweet spots. Markdown is good if you want simplicity that lets you do headings, emphasis and bold, and gets out of your way. I write fiction in Markdown. AsciiDoc is good if you want structured documents. I would use it to write a technical manual.
- harikb 6y agoFor what it is worth, GitHub supports rendering AsciiDoc. You just have to name your files .adoc I instead of .md I do have to mention that sometimes advance features have tripped me and I have to spent some time figuring out why. I am sure the cli tools could use help and get better
- DJHenk 6y agoAgreed. The ease of Markdown, but well structured and complete enough to write a whole book in it. I love it. I've even fantasized about creating a new AsciiDoc mimetype, called AsciiWeb. It would be a subset of AsciiDoc that is relevant for browsing and would sit somewhere in the middle of Gopher or text browsing on one hand and the "normal" HTML/CSS/Javascript on the other. Very easy to create, suitable for minimal document browsing and structured enough that graphical clients can make it pretty and accessible. Oh wel.. one day I'll get to it.
- irq-1 6y agoThis is a great idea. Implemented as a browser plug-in that transforms the AsciiDoc the user would control the document, instead of the server/host. Users could set their own fonts and styles, change accessibility, restructure the content, hide blocks/quotes, overlay other data or links, etc... Changing who controls the content is a feature the web doesn't offer, except to technical people who can F12 to edit.
- zelphirkalt 6y agoOr reStructuredText, or Org-Mode : ) I think there are multiple great alternatives to markdown. Markdown is like the smallest common subset of features, that is never quite satisfying.
- sqldba 6y agoYeah. 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 6y agoThis 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 6y agoConsidering 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.
- deleted 6y ago[deleted]
- chillfox 6y agoMarkdown has a problem with consistency and tables, other than that it is pretty good.
- timClicks 6y agoI'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 6y agoI 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 6y agoI 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 6y agoAnother 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.
- pvorb 6y agoYou aren't referring to this gem, right? ;-) https://github.com/aaronjanse/asciidots https://github.com/aaronjanse/asciidots
- 6y ago
- api 6y agoHas anyone used Eclipse recently? How does it compare to the Jetbrains stuff? How about for languages like C++ and Go?
- kbumsik 6y agoYour 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.
- sandGorgon 6y agoOne 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 6y agoHuh? 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.
- sandGorgon 6y agoI'm talking about where the momentum is. Sure I can use asciidoctor (through docker,etc)..but what I'm really talking about is the adoption in the wider ecosystem. Which needs javascript, tooling, support,etc. Asciidoc as a community has not gone down that path.
- SevereOverfl0w 6y agoYou might be interested in asciidoctor.js and asciidoctorj
- mbeex 6y agoNot 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.
- soapdog 6y agoIt is easier to spot the advantages and disadvantages of AsciiDoc vs Markdown, but has anyone here weighted AsciiDoc vs Textile?
- acqq 6y agoOr 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
- sandGorgon 6y agoOne of the coolest utilities is to create presentations using asciidoc using vscode https://marketplace.visualstudio.com/items?itemName=flobilosaurus.vscode-asciidoc-slides https://marketplace.visualstudio.com/items?itemName=flobilos... Uses reveal.js under the hood. There's also antora, which is a toolchain for technical documentation. https://antora.org/ https://antora.org/
- kimi 6y agoWe 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.
- Thorentis 6y agoAsciiDoc support in Hugo when?
- wyoh 6y agoIt's already supported by Hugo.
- gorgoiler 6y agoDan 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!
- axilmar 6y agoWe have html, why do we need yet another markup language? https://en.wikipedia.org/wiki/Comparison_of_document-markup_languages https://en.wikipedia.org/wiki/Comparison_of_document-markup_... So many markup languages...
- sradman 6y ago> 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.
- beagle3 6y agoIs 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
- xellisx 6y agoOne thing missing from a lot of these, is color. I want at least 16 of them.
- nikolay 6y agoUnfortunately, 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