Including a file using an absolute path under Windows 1.5.0

Using an absolute path with the include macro under Linux works as expected and includes the target files contents. Specifying an absolute path on Windows fails to include target files contents and renders a hyperlink to the include file instead.

Not sure if this is a bug or I am missing some key configuration know how?

Environment:

Windows:

• Asciidoctor 1.5.0
• ruby 2.0.0p481 (2014-05-08) [x64-mingw32]

and

• Asciidoctor 1.5.0
• jruby 1.7.13 (1.9.3p392) 2014-06-24 43f133c on Java HotSpot(TM) 64-Bit Server VM 1.7.0_65-b19 [Windows Vista-amd64]

Linux:

• Asciidoctor 1.5.0
• ruby 1.8.7 (2011-06-30 patchlevel 352) [x86_64-linux]

Test setup:

Create two files in the same folder

test.adoc (Windows version)

include::C:\sample.adoc[]
include::C:/sample.adoc[]
include::sample.adoc[]

test.adoc (Linux version)

include::/sample.adoc[]

sample.adoc

this text was included from another file

Test:

Compile test.adoc under both Windows and Linux using the respective test.adoc file and the appropriate absolute path for your test folder.

asciidoctor test.adoc

Expected result:

Linux = Successfully includes
Windows = Fails to include, instead shows hyperlink to file

Welcome richard,

I don't think you're missing anything. I've been able to replicate this using the maven plugin but with some slight different behauviour. However, in my opinon it seems a bug related to how Ruby parses the string of the path, making it think it is not a file but an external link.

The difference in my case is that `include::C:/sample.adoc[]`works fine.

As a workarround, I would try to avoid using absolute paths and use relative instead. But if you need to, maybe using an URI format would be the more cross-platform solution.
http://asciidoctor.org/docs/user-manual/#include-content-from-a-uri
Both this options worked for me:

include::file://localhost/c:/sample.adoc[]

include::file:///c:/sample.adoc[]

Note that you need to set the 'allow-uri-read' attribute.

Thanks abelsromero for taking the time to replicate this and give such a detailed response. Really appreciate it.

As a result of your answer I've been able to resolve our problem. However not as might be expected.

The following is for anyone else who experiences similar problems:

Background:

Firstly, despite providing a command line example using MRI Ruby we are in fact a Java shop who have been building an in house documentation system that utilises AsciidoctorJ. I provided a command line example because after removing layer after layer of our own 'gaff' the same issue was present in the 'pure' command line, MRI Ruby version. This seemed the most suitable way to make an enquiry that would be universally clear and reproducible.

Solution

Based on your confidence that the URI examples you provided worked I tried a number of things before coming to a solution that worked for us. I did not manage to get the command line Ruby example working but was able to get things working via the AsciidoctorJ API which is good enough for us. Under AsciidoctorJ the solution was:

Attributes attributes = new Attributes();
.....
attributes.setAllowUriRead(true);    //Solution
....
Options options = new Options();
....
asciidoctor.renderFile(file, options);

Method:

• Tried 'include::file:///c:/sample.adoc[]' using command line Asciidoctor but it did not work for me, even setting the :allow-uri-read: attribute as the the documentation suggested.
• Then discovered an answer by Dan Allen to this question http://discuss.asciidoctor.org/Content-not-included-allow-uri-read-amp-unsafe-td1602.html that explained that the :allow-uri-include: attribute could not be used like a regular attribute but must be specified at the 'options' level.
• This still did not work for me using command line Asciidoctor ie 'asciidoctor -a allow-uri-read test.adoc'
• I decided to try my luck with AsciidoctorJ and specified 'attributes.setAllowUriRead(true)' as this was at the 'options' level and to my surprise it worked. Not only that but I did not have to provide paths in the correct URI syntax.

Hopefully my day of experimentation and abelsromero's good advice will help others who face a similar situation.