Hi All!
I have a problem with asciidoc and I couldn't find any solution searching from the internet, so I try to ask for help here. I have a multi module maven project. In the parent project I have the 'first part' of the asciidoc documentation and each module has its own chapter. Then I have a 'distribution module'; this is the module where the asciidoc will get compiled and works this way: 1) An assembly copies all the asciidoc files and images from all the modules to a staging directory 2) the asciidoc maven plugin compiles the asciidoc files to create the manual (html output) Inside the asciidoc document there is some 'include::' directive in the form of: include::/my/project/parent/distribution/../module1/src/java/my/package/MyClass.java The problem is that the code from MyClass.java does not get included, I see instead somethink like: link:/my/project/parent/distribution/../module1/src/java/my/package/MyClass.java in the generated code. I guess it is related to the 'safe mode', but couldn't find any documentation on how to disable that on the maven plugin. Any help is greatly appreciated! Thanks in advance, Massimiliano |
welcome,
I don't think safe mode may be the cause because it is disabled by default, you can have a look at the code yourself: https://github.com/asciidoctor/asciidoctor-maven-plugin/blob/master/src/main/java/org/asciidoctor/maven/AsciidoctorMojo.java#L143 I think the issue may be related to the path system when using multimodules, keep in mind that each module uses a different baseDir. You can try to set the base path used to search for resources with baseDir, but it should be set in each module accordingly to its relative path to the parent, e.g. "../" to set the base at the parent from a lvl-1-depth module. Have you tried it? Also, just for the sake of testing, have you tried to set absolute paths? |
Thank you abelsromero!
The problem is that the path showed inside the html exists! I mean, in the html I have something like : include::/my/project/parent/distribution/../module1/src/java/my/package/MyClass.java if I do: ls /my/project/parent/distribution/../module1/src/java/my/package/MyClass.java the file exists! And, as you can see, the path is already absolute. All the paths I use are absolute (I use maven to substitute a variable inside each asciidoc file while copying it in the staging directory) Thanks you! Massimiliano |
I have build a test myself to try to reproduce it, basically a multi-module with a parent a 2 child projects (A and B).
Then I include a Java file from A to B (that is the 'include' is in an adoc file in B), I don't have any staging here. Overall absolute paths work fine for me, even when I include some parent browsing (with \..\), on Windows thought (I used cygwin, but the plugin gets Windows' paths anyway :/ ). And a thing that puzzles me is that ocurrence of 'link' you commented, I haven't been able to get that behauviour. The closer I got was removing the ending brackets [], which causes a simple 'include' to appear. When a file is not found I get a warning message in the console and this in the HTML: Unresolved directive in SomeGuide.asciidoc - include::I:\workspace\asciidoctor\asciidoctor-maven-test\sub-project-A\src\main\java\example\FAKE_HelloJava.java[] Seeing that this approach it not helping I'd like to review your case to make sure I understand everything, is that ok for you? · The maven plugin is only configured in the 'distribution' module, is that right? · Although all files are found in several modules, they're rendered from a single folder where they're previously copied. right? · Also, can you elaborte on the 'staging' process? Is just a copy process or somthing else is done? You mentioned some replacements. If the answer to the first two is true and staging only copies and replaces include paths, I would approach the configuration in a diferent way: 1. First, I'd set the baseDir in the distribution module to point to the parent folder with something like this: 2. With that in place you should be able to include files from any project with a relative address, for instance, to include a Java and AsciiDoc file you could do: To ease the configuration and avoid errors you could define some vars for conventional paths: Of course, if your case includes more details and is more complex (which I suspect) this won't help. |
Hi Abelsromero!
Thanks for your help. I created a sample project that you can download from https://db.tt/IVF159Wo that replicates the problem. Just run in the root directory, and then give a look at the generated html files in And you will see the problem. Regards, Massimiliano |
Good news, I could reproduce the issue and you'll laugh at the solution.
After some tests, experiments and a couple of hours I saw you're using the plugin version 1.5.0, with the latests 1.5.2 it works :D Other than that, the test has 2 small typos in `module2.asciidoc` and in the sourceHighlighter tag, check the capital H. And the # characters at the beginning of each file cause an error message to be shown the parsing the last one...weird. BTW, the example is really nice and solves 2 important problems quite nicely: · Documenting a multi-module API on each project while keeping a common part in the parent. · Assembling the documents in a single folder to create a distributable package. For instance, to move the docs into an Apache server. Why don't you upload it to GitHub so we can link it? |
Hi Abelsromero,
shame on me!!! Sorry for that!! Yep you are right. Done. You can find it on https://github.com/ziccardi/asciidoc Thanks a lot for your help! Regards, Massimiliano |
Administrator
|
In reply to this post by abelsromero
> You can find it on https://github.com/ziccardi/asciidoc On Mon, Apr 27, 2015 at 2:40 PM, abelsromero [via Asciidoctor :: Discussion] <[hidden email]> wrote:
This is definitely one of those “recipes” that will surely help a lot of users of the plugin. Perhaps we should add the example to the https://github.com/asciidoctor/asciidoctor-maven-examples repository so that it's easier for people to discover. If there are handy tips that users need to know when graduating from a single module to a multi-module project, perhaps we can put them in the new tips section in the README (https://github.com/asciidoctor/asciidoctor-maven-plugin/pull/157) with a pointer to the example project. This is definitely the type of use case that helps us improve the flexibility in Asciidoctor core. As we become more familiar with the usage, we can make adjustments to core that simplify the configuration and markup. The first step is always having that use case so that we can study it from more angles. Nice work! Cheers, -Dan |
Administrator
|
In reply to this post by doctor0
On Fri, May 1, 2015 at 5:33 AM, doctor0 [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Have you had a chance to update the plugin to 1.5.2? |
In reply to this post by mojavelinux
Regarding adding examples to 'asciidoctor-maven-examples', I'm usually confused about what should be the strategy. Specially in cases like one, which are very interesting but they involve more work on the maven side than in asciidoctor's.
I'm thinking we could extend the introduction to elaborate a bit more and make things easier for anyone who wants to contribute an example and for all of us to decided whether it should be included. What do you think of this (in bold the addition):
|
Administrator
|
Very well said! We could even consider using the README to link to additional examples that are hosted elsewhere (such as in other GitHub repositories). That would allow us to scale up the number of examples without making the repository too large. Maybe this scenario could be our first candidate. That's something we'll have to decide. Cheers, -Dan On Fri, May 1, 2015 at 2:41 PM, abelsromero [via Asciidoctor :: Discussion] <[hidden email]> wrote: Regarding adding examples to 'asciidoctor-maven-examples', I'm usually confused about what should be the strategy. Specially in cases like one, which are very interesting but they involve more work on the maven side than in asciidoctor's. Dan Allen | http://google.com/profiles/dan.j.allen |
Free forum by Nabble | Edit this page |