Can't include external tagged region using maven plugin

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

Can't include external tagged region using maven plugin

paulc
Hi,

I am trying to document a Maven project using asciidoctor.

I have a src/main/asciidoc folder containing the asciidoctor document source, and am building the documentation using the maven plugin.

The problem is that I can't include code snippets from outside the src/main/asciidoc directory. At the moment I'm trying to include something from the pom.xml in the project root. If I move this file to src/main/asciidoc/pom.xml and then use the following include:

include::pom.xml[tags=example1]

then everything works fine. If I move the file one folder up (src/main/pom.xml) and also update the include:

include::../pom.xml[tags=example1]

then the maven build fails with the following error:

[ERROR] Failed to execute goal org.asciidoctor:asciidoctor-maven-plugin:0.1.4:process-asciidoc (output-html) on project AcmeCorp: Execution output-html of goal org.asciidoctor:asciidoctor-maven-plugin:0.1.4:process-asciidoc failed: (TypeError) can't convert nil into String -> [Help 1]

I tried to set the safe mode to 'unsafe' in the maven plugin configuration attributes just in case it was running in safe mode, but it makes no difference.

Does anyone have any ideas how I can get this working?

Thanks in advance!
Reply | Threaded
Open this post in threaded view
|

Re: Can't include external tagged region using maven plugin

LightGuardjp
Administrator
Known issue, should be fixed in 1.5.0. I don't think we have a fix in AsciidoctorJ just yet, though I could be wrong. 

Sent from Mailbox for iPhone


On Tue, Feb 11, 2014 at 8:11 AM, paulc [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Hi,

I am trying to document a Maven project using asciidoctor.

I have a src/main/asciidoc folder containing the asciidoctor document source, and am building the documentation using the maven plugin.

The problem is that I can't include code snippets from outside the src/main/asciidoc directory. At the moment I'm trying to include something from the pom.xml in the project root. If I move this file to src/main/asciidoc/pom.xml and then use the following include:

include::pom.xml[tags=example1]

then everything works fine. If I move the file one folder up (src/main/pom.xml) and also update the include:

include::../pom.xml[tags=example1]

then the maven build fails with the following error:

[ERROR] Failed to execute goal org.asciidoctor:asciidoctor-maven-plugin:0.1.4:process-asciidoc (output-html) on project AcmeCorp: Execution output-html of goal org.asciidoctor:asciidoctor-maven-plugin:0.1.4:process-asciidoc failed: (TypeError) can't convert nil into String -> [Help 1]

I tried to set the safe mode to 'unsafe' in the maven plugin configuration attributes just in case it was running in safe mode, but it makes no difference.

Does anyone have any ideas how I can get this working?

Thanks in advance!


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Can-t-include-external-tagged-region-using-maven-plugin-tp1424.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Reply | Threaded
Open this post in threaded view
|

Re: Can't include external tagged region using maven plugin

paulc
OK, many thanks for the quick response.
Reply | Threaded
Open this post in threaded view
|

Re: Can't include external tagged region using maven plugin

LightGuardjp
Administrator
Caught me at a good time :)


On Tue, Feb 11, 2014 at 8:41 AM, paulc [via Asciidoctor :: Discussion] <[hidden email]> wrote:
OK, many thanks for the quick response.


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Can-t-include-external-tagged-region-using-maven-plugin-tp1424p1426.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Reply | Threaded
Open this post in threaded view
|

Re: Can't include external tagged region using maven plugin

mojavelinux
Administrator
In reply to this post by paulc

The problem here is that the src/main/asciidoc directory is acting as a jail. You need to set to badeDir config option to the project root and refer to includes from the project root.

To make your includes resolve in any environment, I recommend setting docsdir and srcdir attributes and use those in the include target like:

```
include::{docsdir}/anotherdoc.adoc[]

include::{srcdir}/sourcefile.groovy[]
```

Remember to set these attributes to relative paths in the header of each document so they resolve on GitHub and the browser preview.

As an example:

```
:docsdir: .
:srcdir: ../groovy
```

Reply | Threaded
Open this post in threaded view
|

Re: Can't include external tagged region using maven plugin

mojavelinux
Administrator
In reply to this post by paulc

I am curious about the type conversion error. That shouldn't be leaking through.

Reply | Threaded
Open this post in threaded view
|

Re: Can't include external tagged region using maven plugin

paulc
In reply to this post by mojavelinux
Thanks, I can try that. It's a better workaround than making a copy of all source files that I need under the document folder.  I guess the real fix is either to remove the jail completely in unsafe mode, or provide a way to move the jail further up the tree.

I was trying to use relative paths throughout the documentation, as this is more intuitive, works better with the live preview tools such as the Chrome plugin and makes it easier to refactor whole chunks of the documentation as you can simply move whole directory trees around. Unfortunately it looks like asciidoctor doesn't support that way of working at the moment.

It's probably a little bit off-topic, but is proper support for relative paths planned?
Reply | Threaded
Open this post in threaded view
|

Re: Can't include external tagged region using maven plugin

mojavelinux
Administrator
Paul,

The main issue here is that going into 0.1.4 we didn't have all the requirements on the table, esp those that arise in a build tool environment, and thus didn't account for them all in the implementation. This is something we are trying to get right for 1.5.0. There's be a lot of different discussions about it and I'm currently working getting out a proposal that identifies each use case and how the processor is expected to behave. I'll post that on the list when it's ready.

What makes this issue challenging to solve is that there is no single definition for a "relative path". It all depends on what perspective you have. The expectation of a relative path by one person can be very different than a relative path to another person. The way this problem can be solved is by having enough levers that you can clearly communicate to the processor your expectations independent of a universal definition of "relative".

Case in point, we made a change in 0.1.4 that fixed one person's definition of relative and that broke the behavior in the eyes of a separate group. This is a great opportunity to break new ground with a solution that speaks everyone's language.

-Dan


On Wed, Feb 12, 2014 at 1:50 AM, paulc [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Thanks, I can try that. It's a better workaround than making a copy of all source files that I need under the document folder.  I guess the real fix is either to remove the jail completely in unsafe mode, or provide a way to move the jail further up the tree.

I was trying to use relative paths throughout the documentation, as this is more intuitive, works better with the live preview tools such as the Chrome plugin and makes it easier to refactor whole chunks of the documentation as you can simply move whole directory trees around. Unfortunately it looks like asciidoctor doesn't support that way of working at the moment.

It's probably a little bit off-topic, but is proper support for relative paths planned?


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Can-t-include-external-tagged-region-using-maven-plugin-tp1424p1437.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--