Understanding include directive and file path

Imagine a repository like that:

• docs/

  • main.adoc

  • inc/

    • section1.adoc

    • section2.adoc

• src/

  • main/

    • java/

      • Asciidoctor.java

      • Main.java

I am trying to apply the pattern described in the user manual:

Include files relative to a common source directory

:sourcedir: src/main/java

[source,java]
----
include::{sourcedir}/Asciidoctor.java[]
----

Now imagine I want to define sourcedir in main.adoc and in section1.adoc.

In the main.adoc case it will be:

:sourcedir: src/main/java

In the section1.adoc case it will be:

:sourcedir: ../src/main/java

Working like that, allows me to move some content from main.adoc to section1.adoc without having to think about the sourcedir value (initialized correctly in both documents).

This works great when I preview each section file separately or if the main.adoc document do not use sourcedir.

The problems comes when I try to preview/build the main.adoc document (using sourcedir everywhere). My understanding is that the include:: directive works relative to the current Asciidoc file.

This is what is written in the user manual:

Files included in the master (top-level) document are resolved relative to the base directory, which defaults to the directory of the master document unless otherwise specified. Files included inside a file which itself has been included are resolved relative to the current document.

How is this typically solved? I can imagine two solutions:

1/ having an option to tells that all the path are defined relative to the main.doc Asciidoc file or relative to something else (for example to root of my git repository). This would be true for all my documents: in the main.doc file and in the included section files.

2/ having a possibility to redefine the sourcedir variable in the section1.adoc but with a scope equals to this document. Meaning that when the engine is done with importing section1.adoc and comes back in main.doc the value of sourcedir defined in section1.adoc is reverted to the value defined in main.adoc.

I would really appreciate help to understand this. (I have seen other discussion on this mailing list, but I did not understand the solution).

I am ready to share this demo setup if necessary.

Thank you in advance.

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Understanding-include-directive-and-file-path-tp3137.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML