[
https://issues.apache.org/jira/browse/SOLR-11531?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16217331#comment-16217331
]
Hoss Man commented on SOLR-11531:
---------------------------------
2 thoughts occurred to me last night...
# we can/should break this up into smaller sub-tasks that can be committed
individually
# it _might_ be possible to fix the pdf generation to use *explicitly* declared
anchors for each "page section" using the {{page-shortname}} (and later just
the base filename) rather then requiring that the file names match the
asciidoctor auto-generated ID equivilents for the filenames
I've been experimenting with #2 this morning and i think it works -- i'll open
a sub-task for that ASAP, and we can worry about eliminating the need for
explicitly declaring {{page-shortname}} in a distinct sub-task.
> 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: [email protected]
For additional commands, e-mail: [email protected]
