-
Notifications
You must be signed in to change notification settings - Fork 15
Technical details
With Milestone 1.3.0 respectively Issue 169 you will find all temporary generated files based on your eclipse project at
${tempFolder}/asciidoctor-editor-temp/project_${projectName}${projectHashCode}/
The base directory is used by asciidoctor to have a central ankerpoint to resolve pathes for includes, images, diagrams etc. On a normal document the base directory is simply the directory where the main asciidoc file resides and which does include all others.
So far so good, but the Asciidoctor Editor must show also included pages which are NOT inside base folder but normally on a deeper level. So we got following problem:
-
Trying to define the asciidoctor file parent as the base dir will work fine on includes, which have relative pathes from the current file, but fail on images, because they use a relative path from base dir and are defined for rendering the
main asciidoc file. -
On the other side: Trying to determine base directory and use it works well with images and diagrams but NOT with includes…
With Issue 114 a hidden temporary editor file was introduced which is setup in temporary folder and includes the wanted origin page on resolved base directory. So it works well for images and includes.
The temporary editor file is outside eclipse project. Asciidoctor is executed to render this file, but with base dir pointing to eclipse project!
The temporary file contains just another include which includes the real wanted editor file but from base dir root location!
For example we open "includer.adoc" inside editor
/home/you/workspace/doc-project/
main.adoc
subfolder1/
includer.adoc
subfolder2/
included-by-includer.adoc
images/
my-image.png
This will result in a temporary editor file which does contain
// origin :/home/you/workspace/doc-project/subfolder1/includer.adoc // editor :-$someId // basedir:/home/you/workspace/doc-project/ include::subfolder1/includer.adoc[]
For what is this good for?
This simulates a main document starting from base dir with correct pathes to look for. So relative pathes and also image dir are working correctly (see path problem )
-
base dir directory where asciidoctor will start looking for resources it is still inside eclipse project but on in temporary project!
-
includes: include resolution is done starting at base dir and than from location of rendered file.
This is necessary for HTML output. Generated HTML output is inside temp folder. To show images etc. the temp folder must contain these too.
There are problems with browsers to show images from other file locations (security issues). There is currently also Issue 175 to handle this for css files in same way because of problems in preview by firefox
Asciidoctor editor does need to resolve correct basedir to work correctly.
With Version 1.3.0 the editor will resolve for each project the base directory by simply inspecting the current opened editor file and - if not in cache - resolve the base directory by going upwards until no longer an .adoc file is found in parent folder. At this position the editor will handle this as the new base directory inside this project.
Normally this does work well when you have a designated folder where al your main asciidoc files are settled for an eclipse project. But if you have splittered your .adoc files around in one project the editor has problems to determine base folder and will fallback to treat those files as if they would be inside the calculated base folder (which still works most times, but shows up some problems with includes or missing images etc.).
If you want to reset the base folder just open the wanted file in editor and just do a refresh operation. This will reset cached values and recalculate the base directory!