ahus1
commented
2 years ago Thanks for asking this question on the issue tracker.
In the setup you describe above, I assume you open the folder openEHR as the project in IntelliJ. If not, I recommend you should, as this allows you adding a .asciidoctorconfig file in the openEHR folder.
That file should contain the following contents:
// avoid errors for the include by setting a default; asciidoctorconfigdir is only set when using it as a prefix
ifndef::asciidoctorconfigdir[:asciidoctorconfigdir: .]
:pub_home: {asciidoctorconfigdir}
:work_root: {asciidoctorconfigdir}
:ref_dir: {asciidoctorconfigdir}/specifications-AA_GLOBAL
:base_dir: {asciidoctorconfigdir}/specifications-BASE
:stylesdir: https://specifications.openehr.org/styles
// re-use attributes from other places
include::{asciidoctorconfigdir}/specifications-AA_GLOBAL/docs/boilerplate/global_vars.adoc[]Still, this won't render any images in the preview. To make that work, the image macros need to use a relative path to point to the image. {uml_diagrams_uri}/AM-aom2.archetype.svg will resolve to UML/diagrams/AM-aom2.archetype.svg, so it is missing a ../ to find the image. To fix that, you can used the imagesdir attribute and set it in an .asciidoctorconfig file in the same folder as the master.adoc file:
:imagesdir: ../Unfortunately this will only fix images in that folder; I see that there are a lot of images in different folders, also the AA_GLOBAL structure. As only one imagesdir can be defined, this will never work for all folders. As the imagesdir is a relative path, you'd need to define it in every folder where there is AsciiDoc content that references images.
I'm working on a change that in the next version of the AsciiDoc plugin, you can use a file-URL, so a setting like the following would work:
:imagesdir: file:///{asciidoctorconfigdir}/docsIn the case of this document, you could even set uml_diagrams_uri to such a value, and not set imagesdir -- this would allow you to have different file types in different folders.
Please let me know if you think this goes into the right direction although it might not yet be the full solution in your scenario.
wolandscat
Observed vs. expected behavior
Background: we have a collection of standards, each is an Asciidoctor multi-file book, and the books for various 'components' are in multiple GitHub repos, one for each component. The files in the books use many variables that come from files within .adoc files in one special component repo. All this works fine with Asciidoctor 2.x (for some years), Ubuntu 22.
In each component Git repo, the documents are in directories below a /doc directory.
I have IntelliJ IDEA 2021.2.2 (Ultimate), with the AsciiDoc plug-in 0.36.19. Installation of plug-in appears to be fine, diagram module downloaded, basic functionality as documented by this project.
If I open the /docs directory in IntelliJ, and then navigate to a master.adoc document in one of the /docs/xxx subdirs, the plugin makes a pretty good attempt at processing all the includes (of chapters, and below chapters, of smaller files). It's correctly processing at least some variables.
Variables that would normally be passed to asciidoctor on the command line are in a new file /docs/.asciidoctorconfig, created according to plug-in documentation. This is being read, because I can see some of the variable substitutions are working.
The main problem is that image paths containing Asciidoc attributes are not being processed correctly. (Image rendering does appear to be working because some image paths are external URLs, and they resolve to SVGs that do display in the previewer).
Example: the following line is how we commonly include a UML diagram (an SVG file).
The attribute uml_diagrams_uri is defined to have the value
UML/diagramsin a file that is included by master.adoc.If I send the output to FireFox instead of the internal browser, and then inspect the img path, I see this:
<img src="image?file=%2Fhome%2Fthomas%2FopenEHR-specifications%2Fspecifications-AM%2Fdocs%2FAOM2%2FUML%2Fdiagrams%2FAM-aom2.archetype.svg&mac=lJGABj9KNIyoSiSrBUcY5W+JrtQAr7OILhAYaCkTm/A=&hash=none">However, if I use asciidoctor on the command line, (via our scripts), the same image has the following HTML
<img src="UML/diagrams/AM-aom2.archetype.svg" alt="AM aom2.archetype">The Asciidoc plugin appears to be prepending a root path to the relative path that is defined in the Asciidoc source, as well as doing other things I don't understand.
The other main problem is that if I click on any chapter file (i.e. a file included by master.adoc), only the text is rendered - anything depending on vars coming from master.adoc doesn't work. This could be faked by more .asciidcotorconfig files I guess but that's far from optimal, and likely to be too much trouble to be worthwhile. A better solution would be some special variable telling the plug-in that files with name master.adoc (or whatever name) are book files, and to look for them in the directory of any other .adoc file in order to obtain all the attributes and inclusions.
Although the above directory / file structures may sound a bit complex, they are common in multi-document publishing, as is the use of multi-level inclusion of files containing variables and so on.
I think if the plug-in can succeed at rendering these files, it can do anything. I'm sure the problem reported here is not complex to fix.
Steps to reproduce
Hopefully the above gives an idea of the problem. Since all the documents are open source, you could reproduce using the following steps.
Contents of
/docs/.asciidoctorconfig; replace<root>with /absolute/path/to/openEHR dir created above.Environment
Ubuntu 22 (20 will be fine) Plugin Version: 0.36.19 IntelliJ Details: IntelliJ IDEA 2021.2.2 (Ultimate)