Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Absolute paths #10

Open
3 of 5 tasks
johannesloetzsch opened this issue Oct 31, 2024 · 3 comments
Open
3 of 5 tasks

Absolute paths #10

johannesloetzsch opened this issue Oct 31, 2024 · 3 comments

Comments

@johannesloetzsch
Copy link
Contributor

johannesloetzsch commented Oct 31, 2024

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

  • wrote a little prolog tutorial
  • 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.

  • 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.

johannesloetzsch added a commit to johannesloetzsch/prolog-tutorial that referenced this issue Oct 31, 2024
johannesloetzsch added a commit to johannesloetzsch/prolog-tutorial that referenced this issue Oct 31, 2024
johannesloetzsch added a commit to johannesloetzsch/prolog-tutorial that referenced this issue Oct 31, 2024
@aarroyoc
Copy link
Owner

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
Copy link
Contributor Author

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
Copy link
Owner

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants