Details
-
Bug
-
Status: Closed
-
Major
-
Resolution: Fixed
-
None
-
None
Description
About a month ago, cassandra noticed some problems with a few links in the ref-guide PDF which confused both of us. Working through it to try and understand what was going on – and why the existigg custom link-checking we do of the html-site version of the guide wasn't adequate for spotting these kinds of problems – I realized a few gaps in the rules our build tools are enforcing...
- the link checker, sidebar builder, & jekyll templates all have various degrees of implicit/explicit assumptions that the page-shortname will match the filename for each *.adoc file
- but nothing actaully enforces this as people edit pages & their titles
- the jekyll templates use the page-shortname to create the <body id="???" .../> attribute, and the link checker depends on that for validation of links – but on the PDF side of things, the normal asciidoctor rules for auto generated ids from section headings is what determines the anchor for each (page) header.
- so even though our (html based) link checker may be happy, mismatches between page titles and page-shortnames cause broken links in the PDF
Furthermore: the entire page-shortname and page-permalink variables in all of our *.adoc files arn't really neccessary – they are a convention I introduced early on in the process of building our the sidebar & next/pre link generation logic, but are error prone if/when people rename files.
We Should (and I intend to)...
- eliminate our dependency on page-shortname & page-permalink attributes from all of our templates and nav-building code and use implicitly generate values (from the filenames) instead
- beef up our nav-building and link-checking code to verify that the "page title" for each page matches to the filename – so we can be confident the per-page header anchors in our generated PDF are consistent with teh per-page header anchors in our generated HTML
- remove all (no longer useful) page-shortname & page-permalink attributes from all *.adoc files
Attachments
Attachments
There are no Sub-Tasks for this issue.