Posted by abelsromero on Jan 19, 2020; 8:02pm
URL: https://discuss.asciidoctor.org/Questions-from-a-novice-tp7496p7497.html

Welcome to the community! :D

Let's see if I can add some light, point by point.

Conrad wrote

1) https://asciidoctor.org/docs/asciidoctorj/ describes the installation. I can download the jar and run in. Everything works as described. I even got extensions to work. I just added the extensions to the classpath. So, why do I Need to use Maven as decribed in the documentation?

AsciidoctorJ is the core tool for when you need to integrate Asciidoctor in a tool or do some very customized process. Most use cases are covered with Maven (or Gradle or other build tools), these help you manage the whole build process in a more declaratibe way without having to write code. These tools help managing configuration, sources & resources processing, dependency download & installation, and even packaging.

Conrad wrote

2) the second chapter also describes installation, now with cocolatey. Why do I need this?

It's to automate the installation if you want to use Asciidoctorj as a command tool. In Linux and MacOS you can also use sdkman for the same purpouse. If you want to use the Ruby library, you can use "gem install" for installation.

Conrad wrote

3) does AsciiDoctorJ uses Asciidoctor-libraries? Could I just add extensions writen for Asciidoctor and use them by AsciidoctorJ?

If by "Asciidoctor-libraries" you mean the Ruby core library, the answer is YES. AsciidoctorJ in fact runs the same code using JRuby. You can use most of Ruby extensions (configurable using the maven-plugin) without issues.
Btw, you can also use asciidoctor.js which is transpiled into JS using Opal if you are more familiar with JS environments.

Conrad wrote

4) I like AsciidocFX. Does this tool uses ist own Asciidoctor-implementation? I also read that Opal is used to compile AsciiDoctor.  So what does that mean? Can I use these implementations within AsciidocFX, e.g. the pdf-generator.

AsciidocFX (I assume) comes with an embedded version of Asciidoctor, that the one used for the preview and conversion features provided by it. But that doesn't mean you can use AsciidocFX only for editing and then use another tool/version to do the final build. For example I am Java developer, so I use IntelliJ for editing and then convert using the maven or gradle plugin. For other projects I use vscode and build with antora.
Opal (https://github.com/opal/opal) is a tool to convert Ruby code to JavaScript. That's how the JS version of Asciidoctor is baked.
In short, when a new version of asciidoctor (Ruby library) is released, both the AsciidoctorJ and asciidoctor.js libraries are updated with it. The first uses jRuby to run it, the seconds, just uses a (semi)automatic JS conversion. Note that they follow a different versioning models, in their respective docs you can find the version of asciidoctor they come from.

Conrad wrote

5) AsciidocFX does not generate a TOC for pdf. Can I fix that with another genartor (like I can "bind" Amazons ebook-generator for epub.

Sure! Keep in mind the preview and final document may differ depending on the editing and building tool/configuration. It can be dauting at first, but once you get used to it, it's not a problem, you can even get used to writting in plain text which removes many distractions imho.

Do not hesitate if you have question.
----

Finally, if you let us know a bit more about your use case and background we can offer some additional advice. From personal experience, Asciidoctor has many tools and can be intimidating at first.