the {doc} variable no longer works from the default page template

[duncdrum]

to test
go to exist-db.org's documentation and select documentation > Documentation , or documentation > Get Support
results in 404

tested on local in safari, ff, and chrome… same results

no idea why this is broken, nothing changed compared to earlier versions afaik

[adamretter]

@ljo Is this anything to do with the issues yesterday please?

[ljo]

The URL itself is https://exist-db.org/exist/404.html for Documentation and Get Support, so not sure where this originates from. The other links are good as well as direct documentation links so quite sure it has nothing to do with me adding repo yesterday.

[ljo]

This is now confirmed from two sources a doc app bug. Up to 0.5.0 they all works. 0.6.x is broken.

[duncdrum]

yes on this testserver running documentation 0.5.0 and exist 3.5.0 the links work. Last change to controller.xq was 5 years ago, page.html 3 years ago. However the same links are broken in the fundocs app, so there is the chance that the error lies somewhere else .

[adamretter]

Okay I can't see any issue with this being the Maven build.

Those {doc} brackets are I believe expanded by the Templating module. Ironically that thing is not well documented at all!

I will keep digging in to see what I can find...

First issue eXist-db/dashboard#61

[adamretter]

Second issue:

Okay so I have no idea why but the documentation app seems to try and phone home. When I hit the homepage of the documentation, I see this in exist.log:

2017-12-13 00:01:07,426 [qtp1116462450-80] ERROR (FunError.java [eval]:139) - Not found: (http://exist-db.org/apps/site-utils#NOT_FOUND):Not found 
2017-12-13 00:01:07,429 [qtp1116462450-80] ERROR (FunError.java [eval]:139) - Not found: (http://exist-db.org/apps/site-utils#NOT_FOUND):Not found 
2017-12-13 00:01:07,431 [qtp1116462450-80] ERROR (FunError.java [eval]:139) - Not found: (http://exist-db.org/apps/site-utils#NOT_FOUND):Not found 
2017-12-13 00:01:07,433 [qtp1116462450-80] ERROR (FunError.java [eval]:139) - Not found: (http://exist-db.org/apps/site-utils#NOT_FOUND):Not found 
2017-12-13 00:01:07,437 [qtp1116462450-80] ERROR (FunError.java [eval]:139) - Not found: (http://exist-db.org/apps/site-utils#NOT_FOUND):Not found 
2017-12-13 00:01:07,447 [qtp1116462450-80] ERROR (FunError.java [eval]:139) - Not found: (http://exist-db.org/apps/site-utils#NOT_FOUND):Not found 
2017-12-13 00:01:07,450 [qtp1116462450-80] ERROR (FunError.java [eval]:139) - Not found: (http://exist-db.org/apps/site-utils#NOT_FOUND):Not found 
2017-12-13 00:01:07,452 [qtp1116462450-80] ERROR (FunError.java [eval]:139) - Not found: (http://exist-db.org/apps/site-utils#NOT_FOUND):Not found 
2017-12-13 00:01:07,454 [qtp1116462450-80] ERROR (FunError.java [eval]:139) - Not found: (http://exist-db.org/apps/site-utils#NOT_FOUND):Not found 
2017-12-13 00:01:07,457 [qtp1116462450-80] ERROR (FunError.java [eval]:139) - Not found: (http://exist-db.org/apps/site-utils#NOT_FOUND):Not found 
2017-12-13 00:01:07,459 [qtp1116462450-80] ERROR (FunError.java [eval]:139) - Not found: (http://exist-db.org/apps/site-utils#NOT_FOUND):Not found 
2017-12-13 00:01:07,461 [qtp1116462450-80] ERROR (FunError.java [eval]:139) - Not found: (http://exist-db.org/apps/site-utils#NOT_FOUND):Not found 
2017-12-13 00:01:07,463 [qtp1116462450-80] ERROR (FunError.java [eval]:139) - Not found: (http://exist-db.org/apps/site-utils#NOT_FOUND):Not found 
2017-12-13 00:01:07,465 [qtp1116462450-80] ERROR (FunError.java [eval]:139) - Not found: (http://exist-db.org/apps/site-utils#NOT_FOUND):Not found 
2017-12-13 00:01:07,469 [qtp1116462450-80] ERROR (FunError.java [eval]:139) - Not found: (http://exist-db.org/apps/site-utils#NOT_FOUND):Not found 
2017-12-13 00:01:07,475 [qtp1116462450-80] ERROR (FunError.java [eval]:139) - Not found: (http://exist-db.org/apps/site-utils#NOT_FOUND):Not found 
2017-12-13 00:01:07,501 [qtp1116462450-80] ERROR (FunError.java [eval]:139) - Not found: (http://exist-db.org/apps/site-utils#NOT_FOUND):Not found 
2017-12-13 00:01:07,503 [qtp1116462450-80] ERROR (FunError.java [eval]:139) - Not found: (http://exist-db.org/apps/site-utils#NOT_FOUND):Not found 
2017-12-13 00:01:07,505 [qtp1116462450-80] ERROR (FunError.java [eval]:139) - Not found: (http://exist-db.org/apps/site-utils#NOT_FOUND):Not found 

I wonder if this could have anything to do with URI name changes on exist-db.org that @ljo recently made?

Either way, I have no idea why the Documentation app needs to phone home. It should work offline for sure.

[adamretter]

Okay so it seems the documentation app attempts to use modules called site-utils and app-utils to do some link expansion. e.g.:

import module namespace site="http://exist-db.org/apps/site-utils";

The function site:expand-link($href as xs:string, $base as xs:string) is called with the arguments ("{demo}/index.html", "http://exist-db.org/").

This tries to retrieve the app name for the demo app. But ultimately fails with $site:NOT_FOUND because the demo app is not installed (at least on my machine). See here: https://github.com/eXist-db/shared-resources/blob/master/content/siteutils.xql#L65
This repeats for each app which is linked from the documentation.

So the problem was a total braindead one! Not at all obvious unless you built the documentation app (which I didn't), or you debug the crap out of it.
Basically there are links in src/main/xar-resources/templates/page.html to pages belonging to various other apps.
Those links look like: {doc}/index.html, the crucial thing here is the bit in {} has to match the abbrev name provided in that apps expath-pkg.xml. If it does not match an installed app, then the link defaults to the 404 page. I think this is horrible, surely we should advise users they need to install some missing app rather than scare/frustrate them!

Anyway, when I Mavenized the Documentation app, I changed its abbrev name from the generic doc to exist-documentation. Which is why the documentation apps links to its own pages started breaking (don't even get me started on that!).

Anyway, I fixed the build so that the abbrev names of the linked pages are now templated into pages.html by the Maven build. They are defined once in the <properties> section. This is an improvement on what we had before, but I still feel this existing linking mechanism is quite prone to failure and a bad user experience. Anyway, I will send a PR to fix the immediate problem.

[duncdrum]

@adamretter thanks for the fix

This repeats for each app which is linked from the documentation.

See #158 We now have to go around and apply a similar fix in all those linked apps as well since they use the same mechanism or link back to the documentation app.

(don't even get me started on that!)

au contraire, thats what #156 is all about.

the site:expand-link issue was first reported here #31,

while the fixes are great, they don't solve the underlying issue of the somewhat confused approach that exists between our 'independent' modules

[adamretter]

@duncdrum This PR will fix the issues on Windows - claudius108/kuberam-expath-plugin#4 just need @claudius108 to do a release of that, and then we can bump up our plugin version.

[dizzzz]

I thought I submitted this some time ago... It killed my app too :-/

[duncdrum]

@dizzzz maybe you submitted to another module 😉
waiting for claudius to release the kuberam update, so we don't have to tell people to download yet another custom thing just to build the documentation app locally