You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lucene.apache.org by "Hoss Man (JIRA)" <ji...@apache.org> on 2017/10/24 01:07:00 UTC
[jira] [Assigned] (SOLR-11531) ref-guide build tool assumptions
missmatch with how "section" level anchor ids are actaully generated in PDF
[ https://issues.apache.org/jira/browse/SOLR-11531?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Hoss Man reassigned SOLR-11531:
-------------------------------
Assignee: Hoss Man
> 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)
> Components: documentation
> Reporter: Hoss Man
> Assignee: Hoss Man
> Attachments: SOLR-11531.patch
>
>
> 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: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org