[documentation] a portable asciidoctor with asciidoctorJS

[42sol-eu]

Is anyone aware of a portable asciidoctor.

As I see it from my beginners point of view ruby is very hard to make portable (at least on Windows). I know that a software developer like me is easily able to install the toolchain and use it.

But we want to integrate other engineers and fellow workers who are no command line lovers. ((A great example for our use case would be the app Typora for markdown documentation))
I think that newer editors or IDEs (like Visual Studio Code or IntelliJ) would be a good start point to edit and preview. But the generation of HTML and PDF documents would be the next step.

My first thought was to make asciidoctor into a portable application.
Another thought would be to build on a server system (like gitlab or githubs CI).

Any projects that you know of who implented one of these approaches?

[mojavelinux]

Could you clarify what you mean by "portable Asciidoctor"?

Asciidoctor is available on numerous language runtimes: Asciidoctor => Ruby, Asciidoctor.js => JavaScript / Node / Browser, AsciidoctorJ => Java / JVM.

While I take your point that Ruby (or any of those other runtimes) can be a barrier to beginners, I also know thousands of writers (making up some of the 6.2 million downloads) who have had no prior experience with Ruby, and in some cases tech in general, yet have been able to pick it up and be productive with it. This is where good documentation comes in. Our focus should be to continue to make it as strong as we can (and there's work to do). Technology requires learning, so rather than shy away from it, we need to aim to be better teachers. People can learn.

I think that newer editors or IDEs (like Visual Studio Code or IntelliJ) would be a good start point to edit and preview.

I encourage you to explore the ecosystem more. You'll be delighted to find that there are plugins for almost all the major editors and IDEs, including the ones you listed.

Beyond that, support for AsciiDoc is integrated very broadly. You can preview documents in AsciiDoc on GitHub and GitLab (GitLab being the better of the two experiences), there is a Docker image for Asciidoctor to use in CI / CD, it's integrated into build tools like Maven and Gradle, and almost every major static site generator has AsciiDoc support (namely Antora). So adoption of AsciiDoc is very broad.

Is there something specific you're looking for that you think is missing?

[42sol-eu]

I think one of the challenges is the variety of programming languages. Does every project support the same features?
Are they fully exchangeable?

Is a handwritten macro available in every language port (my best guess would be yes)

As a first reply I would see three major themes:

• A simple WYSIWYG Editors as a low entry point (like Typora) to move a step further where syntax highlighting and preview windows are not enough.

• A good mobile solution (I am planing to use iOS Draft new feature to build a syntax highlighting and maybe generation story)

• most important I would point out the PDF generation. As far as I know the plugins do use the html to pdf version and not asciidoctor-pdf as a solution.

I use PyCharm (or other intelliJ IDEs) or simply the Visual Studio Code with different plugins and the command line or build tasks.

Some weeks ago I worked a bit with the hugo website generator who does a great asciidoc/pandoc integration.

What I really loved about hugo itself was the installation (one exe file, a readme and a license text)

For some one who is already on board or converts from markdown or rst this is all fine.

But we had big troubles to argue with people that are not software developers or that think MS word will solve all problems.

Maybe a good documentation and setup guide is the key solution.
I have to think and experiment with that.

On the other hand (coming back to my original question)
I had good experiences with tools that are self containing and would be able to be moved to another device (my definition of portable). Think of it as a zip archive coming from an usb device or an installer and every necessary packet is inside it.

This is not strictly required from a good tool. Only a resilient and stable pattern.

[ggrossetie]

Hello @42sol-eu

I will try to answer your questions.

I think one of the challenges is the variety of programming languages.

I think it's a great opportunity. Asciidoctor is available on the JVM and in pretty much any JavaScript environment. So it gives us the opportunity to execute Asciidoctor in the browser, in a Java application or in a Ruby web application (like GitHub or GitLab).

Does every project support the same features?
Are they fully exchangeable?

Overall yes but that highly depends on the environment itself (ie. a given environment does not support the same features).
Can you read a file from the disk when using Asciidoctor.js in the browser? Probably not, because the browser won't allow that from security reason.
Can you use a JavaScript template engine in a Ruby program? Again, I don't think it would be easy to execute JavaScript code in a Ruby runtime so you will probably use what's available in your environment (in this case, you might want to use ERB or Haml template engine)/
The same goes for syntax highlighting... you get the point.

But that's not really specific to Asciidoctor. I mean do comrak (a Rust Markdown parser and renderer) support the same features as showdown? Absolutely not, the API is not even close!
On the other hand, the API of Asciidoctor.js, AsciidoctorJ and Asciidoctor only has a few differences (most notably we are using the naming convention of the ecosystem).
For instance:

Ruby

require 'asciidoctor'
Asciidoctor.convert_file 'README.adoc', to_file: true, safe: :safe

JavaScript

const asciidoctor = require('asciidoctor')()
asciidoctor.convertFile('README.adoc', { to_file: true, safe: 'safe' })

Java

Map<String, Object> options = options().toFile(true).safe(SafeMode.SAFE).asMap();
String html = asciidoctor.convertFile(new File("README.adoc"), options);

Is a handwritten macro available in every language port (my best guess would be yes)

If you are writing an extension in Ruby you can compile it to JavaScript using Opal. So you can use it in both Asciidoctor and Asciidoctor.js. And I believe that it's possible to use a Ruby extension in AsciidoctorJ using JRuby.
But again that's not specific to Asciidoctor, it has to do with the runtime. Can I run a polyglot application on a given runtime?

As a first reply I would see three major themes:
A simple WYSIWYG Editors as a low entry point (like Typora) to move a step further where syntax highlighting and preview windows are not enough.
A good mobile solution (I am planing to use iOS Draft new feature to build a syntax highlighting and maybe generation story)

We certainly want good editors based on Asciidoctor but that's also out-of-the-scope of Asciidoctor.
We focus on making the best possible text processor for converting AsciiDoc content to a myriad of output format (HTML5, EPUB, DocBook, PDF)...
We would happily support anyone who want to build such editors but we won't build an editor in Asciidoctor. Just like Typora is not related to CommonMark or any Markdown implementation.

most important I would point out the PDF generation. As far as I know the plugins do use the html to pdf version and not asciidoctor-pdf as a solution.

I'm not sure I quite understand what you mean? Could you please clarify?
Currently you can generate a PDF using https://github.com/asciidoctor/asciidoctor-pdf (Ruby) or using https://github.com/mogztter/asciidoctor-pdf.js (experimental based on Web technologies).

I use PyCharm (or other intelliJ IDEs) or simply the Visual Studio Code with different plugins and the command line or build tasks.

👍

Some weeks ago I worked a bit with the hugo website generator who does a great asciidoc/pandoc integration.
What I really loved about hugo itself was the installation (one exe file, a readme and a license text)

If you like single binary then you should use the Asciidoctor.js binary attached to this release: https://github.com/asciidoctor/asciidoctor.js/releases/tag/v2.0.3
You can download the .exe file and start using the asciidoctor command line right away.

For some one who is already on board or converts from markdown or rst this is all fine.
But we had big troubles to argue with people that are not software developers or that think MS word will solve all problems.

While I agree that a simple AsciiDoc editor would probably ease the transition, the paradigm shift is probably the hardest step in this transition.
When using AsciiDoc there's a clear separation of concerns between the content and the presentation and it can be hard to argue with someone used to do everything in the same tool.

Maybe a good documentation and setup guide is the key solution.
I have to think and experiment with that.

The documentation of Asciidoctor will soon be overhauled and it will be easier to contribute, so feel free to gather feedback to improve the setup/install guide in the documentation.

On the other hand (coming back to my original question)
I had good experiences with tools that are self containing and would be able to be moved to another device (my definition of portable). Think of it as a zip archive coming from an usb device or an installer and every necessary packet is inside it.
This is not strictly required from a good tool. Only a resilient and stable pattern.

You should definitely try the binaries attached to this release: https://github.com/asciidoctor/asciidoctor.js/releases/tag/v2.0.3
They should be portable. If you encounter any issues with them, feel free to open an issue.

[42sol-eu]

Hi Guillaume,

Thanks for your long answer.
I think the discussion goes in the wrong direction.
My goal is to understand the three different engines better and make an educated choice which way to go for my iedas and projects.

I did not ask for cross language portabilities of plugins. I also understand, that you are providing the engines and someone else should look into UI features.

**That is exactly what I am aiming for. ** But it is looks hard to start an application with a dependency of ruby installed.
Do not get me wrong. Nothing against ruby here. Maybe a bit against Java.

If I would take the approach of creating an Editor like Typora (or try to convince the Typora developer to aim for a integration of Asciidoctor) I need a good and solid story or a self containing tool.

Asciidoctor shines with its plugins (not my plugins but yours! Thanks for that) I am thinking of asciidoctor-diagram, asciidoctor-epub and asciidoctor-pdf (maybe not about asciidoctor-bespoke and the other backends)

Lets pick the hardest and greatest asciidoctor-pdf in its ruby implementation.
It is build on prawn and generates stunning pdfs using yaml configuration files.

As far as I read your comment I would loose this library by switching to asciidoctorJs because the asciidoctor-pdf plugin in asciidoctorJs is a differnt thing implemented without prawn. (Might it be a good idea to name different things differently?)

I got that for this plugin. Would it be the same with other plugins? Is there a way how I can evaluate (and document it)?

So this is my aim would a asciidoctor content project look the same for html, epub, docbook and pdf if I switch the engines (ruby, javascript, java)?

I guess yes but to what extend.
If you could give me a hint or the first links for a trail that would really be helpful.

I want to contribute in my range of skills.
Sincerely
Felix

[ggrossetie]

Hi Guillaume,
Thanks for your long answer.
I think the discussion goes in the wrong direction.
My goal is to understand the three different engines better and make an educated choice which way to go for my iedas and projects.

I see...
Indeed it could be a good idea to add a feature matrix table to see at a glance which converters/output format is supported (PDF, EPUB3, reveal.js, HTML, manpage, template...).

Something like that?

Output	Asciidoctor	Asciidoctor.js	AsciidoctorJ
HTML5	✔️	✔️	✔️
DocBook	✔️	✔️ @asciidoctor/docbook-converter	✔️
manpage	✔️	✔️ @asciidoctor/manpage-converter	✔️
reveal.js	✔️	✔️ @asciidoctor/reveal.js	✔️
PDF	✔️	✔️ asciidoctor-pdf	✔️

I did not ask for cross language portabilities of plugins. I also understand, that you are providing the engines and someone else should look into UI features.

👍

**That is exactly what I am aiming for. ** But it is looks hard to start an application with a dependency of ruby installed.
Do not get me wrong. Nothing against ruby here. Maybe a bit against Java.

It depends on your requirements since every implementation has tradeoffs.

If I would take the approach of creating an Editor like Typora (or try to convince the Typora developer to aim for a integration of Asciidoctor)

I'm not really sure in which language Typora is written but it will play a big factor if you want to tightly integrate Asciidoctor in Typora. The other option is to call the binary. I think that's what Hugo is doing (calling the command asciidoctor).

I need a good and solid story or a self containing tool.

As mentioned, Asciidoctor.js is available as a binary so it might give you what you need.

Asciidoctor shines with its plugins (not my plugins but yours! Thanks for that) I am thinking of asciidoctor-diagram, asciidoctor-epub and asciidoctor-pdf (maybe not about asciidoctor-bespoke and the other backends)

💯

Lets pick the hardest and greatest asciidoctor-pdf in its ruby implementation.
It is build on prawn and generates stunning pdfs using yaml configuration files.
As far as I read your comment I would loose this library by switching to asciidoctorJs because the asciidoctor-pdf plugin in asciidoctorJs is a differnt thing implemented without prawn. (Might it be a good idea to name different things differently?)

You're correct.
Asciidoctor (Web) PDF is a PDF converter for AsciiDoc based on web technologies. The current implementation is written in JavaScript but I believe that at some point we will need to provide a Ruby implementation using the same stack.
As stated by Dan, Prawn is a low-level library and as a consequence you basically need to implement a rendering engine. So this approach do not scale very well when you want to create complex layout.

The project is currently named asciidoctor-pdf.js on GitHub. We are using the ".js" extension to make it clear that it's a JavaScript implementation but we might rename it to "asciidoctor-web-pdf.js". Not sure about it yet, this is an open issue.

I got that for this plugin. Would it be the same with other plugins?

Yes some plugins/converters are compatible (and provide the same set of features) between multiple runtimes (Java, JavaScript, Ruby), some others are compatible with only one runtime and some others are compatible with multiple runtimes but not all features are available.

Is there a way how I can evaluate (and document it)?

I guess you will need to explore the (vast) Asciidoctor ecosystem, read the documentation and evaluate.
But as mentioned above it would be great to have an overview table so if you want to do it you have my full support 🤗

So this is my aim would a asciidoctor content project look the same for html, epub, docbook and pdf if I switch the engines (ruby, javascript, java)?

EPUB is not available in Asciidoctor.js and as you've mentioned Asciidctor (Web) PDF is a not a port of Asciidoctor PDF (Ruby) but a new project based on a different technological stack.

I guess yes but to what extend.
If you could give me a hint or the first links for a trail that would really be helpful.

I gave you a few links in the table above, you can also browser the asciidoctor organization on GitHub since official/well established projets are part of the organization.

[ggrossetie]

@42sol-eu Having to explain and search for information over GitHub made me realize that we do a lot of things... but also that it's really hard to get a clear picture of what's available and how things work together... so we definitely need to improve that part.

For reference, I keep a list of all the extensions, that I'm aware of, that are working on Asciidoctor.js: https://asciidoctor-docs.netlify.com/asciidoctor.js/extend/extensions/ecosystem/

Maybe we could start by doing an inventory of what's available in Asciidoctor.js? What do you think?

[42sol-eu]

I love it.
I really think it would help to give a good overview on different levels.

I got lost in the weeds many times.

Like a Hitchhikers Guide To Asciidoctor?

[mojavelinux]

I think this issue is too open ended to be actionable. The one tangible suggestion that seems to come out of it is the table Guillaume showed for what is available per Asciidoctor port. The rest of it just seems to be a plea for Asciidoctor to be something it is not, which is a processor for a single language runtime.

The reason Asciidoctor is available for Ruby, JavaScript, and Java is because many people need to be able to use Asciidoctor without changing their own language runtime. In other words, we had to do it out of necessity. If you have a choice, then the Ruby platform is the right one because it is the foundation...and the documentation already leads new users in that direction. You only need to venture beyond it if you have a need.

[42sol-eu]

thanks for your comment - I agree with you!