Hoss Man created SOLR-11531:
-------------------------------
Summary: ref-guide build tool assumptions missmatch with how
"section" level anchor ids are actaully generated in PDF
Key: SOLR-11531
URL: https://issues.apache.org/jira/browse/SOLR-11531
Project: Solr
Issue Type: Bug
Security Level: Public (Default Security Level. Issues are Public)
Reporter: Hoss Man
About a month ago, cassandra noticed [some problems with a few
links|https://git-wip-us.apache.org/repos/asf?p=lucene-solr.git;h=9beafb612fa22b747b8728d7d954ea6e2bd37844]
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|http://asciidoctor.org/docs/user-manual/#auto-generated-ids] 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
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
