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

[dcnorris]

I've tried to use base_url/1, but still end up with nav links to file:///arithmetic.pl, file:///assoc.pl, etc.

Here is my doclog.config.pl file, e.g.

project_name("Scryer Prolog").
readme_file("INDEX.dj").
source_folder("/home/david/_build/doclog/scryer-prolog").
source_lib_folder("src/lib").
output_folder("/home/david/_build/doclog/test-output").
websource("https://github.com/mthom/scryer-prolog/tree/master/src/lib").
omit(["ops_and_meta_predicates.pl", "tabling"]).
learn_pages_source_folder("learn").
learn_pages_categories(["First steps", "Tutorials"]).
learn_pages([
		   page("Let's play Brisca", "Tutorials", "lets-play-brisca.dj"),
		   page("Test page", "First steps", "test-page.dj")
]).
copy_file("logo/scryer.png", "scryer.png").
copy_file("learn/Spanish_deck_Fournier.jpg", "learn/Spanish_deck_Fournier.jpg").
copy_file("learn/brisca-interactive.png", "learn/brisca-interactive.png").
base_url("file:///home/david/_build/doclog/test-output/").
%base_url("/").

Here's a snippet of index.html:

	<h4>Libraries</h4>
	<ul class="navlist">
  
    
    <li><a href="/arithmetic.html">arithmetic</a></li>
    
  
    
    <li><a href="/assoc.html">assoc</a></li>