Bug #6590
closedhttps://www.saxonica.com/html/documentation10/extensibility/dotnetextensions/instance-methods.net.html links to "Converting Arguments to .NET Extension Functions" giving 404
100%
Description
The .NET extensions documentation of Saxon 10 in https://www.saxonica.com/html/documentation10/extensibility/dotnetextensions/instance-methods.net.html in the TOC links to "Converting Arguments to .NET Extension Functions" as https://www.saxonica.com/html/documentation10/extensibility/dotnetextensions/converting-args.net which gives a 404.
The same happens on the 9.9 "branch" of the documentation where https://www.saxonica.com/html/documentation9.9/extensibility/dotnetextensions/converting-args.net linked from https://www.saxonica.com/html/documentation9.9/extensibility/dotnetextensions/index.html gives a 404.
Updated by Debbie Lockett 29 days ago
- Assignee set to Debbie Lockett
Thanks for reporting this Martin. The problem seems to be with section ids containing '.'. As well as the example provided, I can find a couple of other cases too. I'll look at getting it fixed...
Updated by Debbie Lockett 28 days ago
- Status changed from New to In Progress
More specifically, this is a problem for sections which have an id containing '.', and which also contain subsections.
In general, HTML documentation links in the generated HTML docs will look like:
-
https://www.saxonica.com/html/documentationX/section/subsection/page.html
for sections which do not contain subsections -
https://www.saxonica.com/html/documentationX/section/subsection
for sections which contain subsections, and then we rely on a server redirect to add '/index.html' to the URI, and find the right page
This redirect is defined in indexed.js:
// Ends with something that doesn't have an extension, add /index.html
if (request.uri.match(/^.*\/[^\/\.]+$/)) {
return {
statusCode: 301,
statusDescription: 'Found',
headers: {
'location': { value: request.uri + '/index.html' }
}
};
}
So the problem is that if subsection
contains a '.', then this is itself recognised as an extension, and the redirect to add '/index.html' is not applied.
I think the easiest fix is to add a specific redirect for URIs ending '.net'. It looks like extensibility/dotnetextensions/converting-args.net
is the only section affected by this bug, but this is found in the HTML docs for Saxon 10 and earlier (so also 9.9, 9.8, 9.7...). So although I could update the stylesheets for generating the HTML docs to explicitly add the "/index.html" to URIs as required, we don't really want to have to regenerate all of those.
In general, it would be good to avoid '.' in section ids in the documentation, to prevent a recurrence of this issue. Note that the extensibility/dotnetextensions
section (and in particular the problematic extensibility/dotnetextensions/converting-args.net
) was removed from the docs from Saxon 11. I have searched for ids containing '.' in the Saxon 12 docs, and the remaining list is:
- schema-processing/extensions11/saxon.message
- schema-processing/extensions11/saxon.order-unique
- schema-processing/extensions11/saxon.separator
- schema-processing/extensions11/saxon.flags
- schema-processing/extensions11/saxon.param
Note that none of these currently cause a problem, because these sections do not contain subsections. But I'm thinking I might rename these on the main branch, and add a check that no ids contain '.'.
Updated by Debbie Lockett 28 days ago
I've committed a change (and opened a pull request) to fix this in indexes.js in the static-saxonica-com
repo:
Update indexes.js to handle URIs ending '.net'. The docs contain sections with such a name, where this is not intended as an extension; and we should still be redirecting to index.html.
Updated by Debbie Lockett 27 days ago
The changes committed to static-saxonica-com
have now been deployed, so the bug in the online HTML documentation is fixed.
I'm keeping this issue open while I still work on other follow up improvements as mentioned in #note-2.
Updated by Debbie Lockett 27 days ago
- Status changed from In Progress to Closed
- % Done changed from 0 to 100
Further improvements committed on the main branch only:
- Add a check in
to-static/s-viewer_app.xsl
for section ids that contain '.', and output a message warning if any are found (other than the changes sections which have ids like "v9.9"). - Rename the
schema-processing/extensions11
subsections which contained '.' (and update existing links). - Update the
f:index-fix
function (in theto-static/s-body.xsl
stylesheet) to explicitly add '/index.html' to the paths used for links, rather than relying on the redirect (which fixes a potential issue when using fragments to link to subsections of a page). - Other tidying up in the
s-viewer_app.xsl
stylesheet.
And I'm now marking this closed.
Please register to edit this issue