Questions from a novice
Locked
 
|
Hello, I am new to AsciiDoc(tor)(J). I installed a lot of things and tested it, but I still do not understand the concepts. Hopefully I may ask my Questions here:
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? 2) the second chapter also describes installation, now with cocolatey. Why do I need this? 3) does AsciiDoctorJ uses Asciidoctor-libraries? Could I just add extensions writen for Asciidoctor and use them by AsciidoctorJ? 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. 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. Many thanks in advance, Conrad |
|
Welcome to the community! :D
Let's see if I can add some light, point by point. 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. 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. 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. 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. 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. |
|
|
Thank you very much, @abelsromero.
To be honest, I am still confused and very frustrated. But it got a little bit better with your help. (1) "If you want to use Asciidoctorj as a command tool, use cocolatey" -> I use it as CLI but it was sufficient to download asciidoctorj-2.2.0-bin, unpack it und run the bat for each transformation. It run. So where is the disadvantage? (2) "Asciidoc FX uses asciidoctor.js" -> is that correct? "That’s why asciidoctor-pdf is not integrated." -> is that correct? Can I integrate a libarry on my own? (3) Installing Asciidoctor is difficult for me because of gem and proxies. Can I also download an install ist on my own (like AsciidocctorJ)? If no, why can I just download and run AsciidocctorJ without using gem? My understanding ist that AsciidocctorJ just runs Asciidoctor as JRuby in a JVM. (4) Is there an advantage using Asciidoctor instead of AsciidocctorJ? Conrad |
|
|
Using chocolately or any other package manager automates things, for instance when there's a new version, you just ask it to update it and that's it....but other than that, it's a matter of taste. Can't confirm, but reading the doucmentation I understand you can generate PDFs. You can try asking directly in the githob repo. AsciidoctorJ contains the minimal required gems inside the jar hiding it's location and loading. Same applies for "asciidoctorj-pdf" and other "asciidoctorj-*" modules. The goal of the project is using the gem hiding all details. To me, it's really a matter of taste. But there are some things to consider.... Pros for Asciidoctor - It's the most updated version. But it usually only takes a few days between asciidoctor & asciidoctorj releases. - It consumes less hardware resouces, if that's important for you. - Using the core library ensures all work. There's a lot of testing but sometimes (rarely) there are issues on the Java side. Cons for Asciidoctor - Harder to install an isolated environment, but can be mitigated with bundle or rvm. - Can only use Ruby extensions - Asciidoctorj can be used from maven, gradle and other build tools to easy config |
«
Return to Asciidoctor :: Discussion
|
1 view|%1 views
| Free forum by Nabble | Edit this page |