Absolute paths

[johannesloetzsch]

Till now DocLog uses absolute paths and can only be served directly in a webroot.

For now I use some workarounds, but I want suggest some changes for a clean solution…

The issue occurred to me, when I

• [x] wrote a little prolog tutorial
• [x] set up a continues integration and continues deployment job

The page is served at https://johannesloetzsch.github.io/prolog-tutorial/ Being in a directory instead of the webroot turned out to be a problem with DocLog.

Till now DocLog creates absolute links to the webroot.

• [x] I fixed the static absolute links to be relative links instead. This first commit should not have any unintended side effects, so I would suggest to merge it.

• [ ] There is one more tiny fix, but since I am not sure about the intentions in the original code, please review it first before applying it.

• [ ] Than there remains a last piece to solve: While all other files are in the same directory, the learn-pages are in a subdirectory. The fixes above work well when navigating from any page except a learn page (index and lib modules are ok). When navigating from a learning page, the relative link would require an additional ../

There are several solutions we could apply and I would like to hear your opinion abut it before putting some effort into it:

Solution 1

The probably most clean solution would be adding the ../ depending on from which page the link is used. Advantage: we keep a flexible directory structure but still no additional configuration effort is required.

However I consider it the most complex of the suggested solutions. Links not only occur in main.pl, but also at base.html and doclog.js. We would probably decide about adding ../ to html-files at build time in prolog and for js-files during runtime is js.

We would need to consider the case of deeper nested directories. It could happen for library modules in subdirectories or lern-pages in subdirectories (btw something what would be helpful for bigger projects, but not possible at the moment; might be worth a separate issue)…

Solution 2

We could add a config option defining the baseUrl that is prefixed before every link. It could default to the webroot / (so default behavior is the same as now). For cases where the docs should be served from a directory, the config option could be set by the user and the issue is solved.

Drawback:

• Configuration by the user is required
• The same build is not working for different directories (local test build vs productive build); separate configs would be required

Solution 3

A simple but effective hack would be placing all pages at the same directory level. We could move index and lib into a separate subdirectory. ../ would than work for all pages. A new index.html would be required to forward to the actual index (in the directory).

Drawback: We get a bit inflexible for the directory structure.

For now I use a simple hotfix, a special case of Solution 3: I put all output files in the same flat directory. No ../ is required at all. However I think this should not be the long term solution for upstream, since learn-pages and lib-modules with the same name can conflict.

[aarroyoc]

I think Option 2 is actually a nice compromise. I don't think it's too bad having to specify the baseUrl (many web frameworks also require it) and it doesn't complicate the code too much

[johannesloetzsch]

I think Option 2 is actually a nice compromise. I don't think it's too bad having to specify the baseUrl (many web frameworks also require it) and it doesn't complicate the code too much

Ok, would work fine for me :)

[aarroyoc]

I've added a base_url/1 option which is available on the latest code. It should fix this issue