[
https://issues.apache.org/jira/browse/SOLR-11531?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Hoss Man updated SOLR-11531:
----------------------------
Attachment: SOLR-11531.patch
The attached patch is a starting point that takes care of #1 & #2 ... but the
build currently fails because we have existing {{*.adoc}} files with titles
that don't match...
{noformat}
[java] Building up tree of all known pages
[java]
/home/hossman/lucene/dev/solr/build/solr-ref-guide/content/solrcloud-autoscaling-overview.adoc
has a mismatched title: Overview of SolrCloud Autoscaling =>
overview-of-solrcloud-autoscaling
[java]
/home/hossman/lucene/dev/solr/build/solr-ref-guide/content/the-extended-dismax-query-parser.adoc
has a mismatched title: The Extended DisMax (eDismax) Query Parser =>
the-extended-dismax-edismax-query-parser
[java]
/home/hossman/lucene/dev/solr/build/solr-ref-guide/content/solrcloud-autoscaling-auto-add-replicas.adoc
has a mismatched title: SolrCloud AutoScaling Automatically Adding Replicas =>
solrcloud-autoscaling-automatically-adding-replicas
[java]
/home/hossman/lucene/dev/solr/build/solr-ref-guide/content/how-to-contribute.adoc
has a mismatched title: How to Contribute to Solr Documentation =>
how-to-contribute-to-solr-documentation
[java]
/home/hossman/lucene/dev/solr/build/solr-ref-guide/content/solrcloud-autoscaling-api.adoc
has a mismatched title: Autoscaling API => autoscaling-api
[java]
/home/hossman/lucene/dev/solr/build/solr-ref-guide/content/index.adoc has a
mismatched title: Apache Solr Reference Guide => apache-solr-reference-guide
[java]
/home/hossman/lucene/dev/solr/build/solr-ref-guide/content/solrcloud-autoscaling-policy-preferences.adoc
has a mismatched title: Autoscaling Policy and Preferences =>
autoscaling-policy-and-preferences
[java]
/home/hossman/lucene/dev/solr/build/solr-ref-guide/content/cross-data-center-replication-cdcr.adoc
has a mismatched title: Cross Data Center Replication (CDCR) =>
cross-data-center-replication-cdcr-
{noformat}
...with the patch applied, these missmatches currently cause
{{BuildNavAndPDFBody}} to fail, but even w/o the patch links to the "top" of
these pages/sections currently fail in the PDF.
A few concrete Examples that are easy to "find" in the PDF:
* All links with the text "The Extended DisMax Query Parser" from the sections
generated by query-screen.adoc, query-syntax-and-parsing.adoc, and
searching.adoc
* link text "Overview of Autoscaling in SolrCloud" from
solrcloud-autoscaling.adoc
...I think what would probably make sense is to go ahead and fix all of these
page titles/filenames/shortnames w/o modifying any of the build code, then move
forward with committing the patch (roughly) as is, then seperately remove all
the {{page-shortname}} & {{page-permalink}} attributes frm the source files.
One thing I'm not really sure about in this plan how to deal with
{{index.adoc}} aka "Apache Solr Reference Guide" ?
We can do whatever special casing we want of this in our tools to "allow" it to
have a missmatch between the filename and the page title -- but I don't think
that's a good idea unless we do it in some what that still ensures that any
links back to this page from the body of other pages are actaully validated
properly such that they work in the PDF as well.
Perhaps we should rename it "apache-solr-reference-guide.adoc" and use
.htaccess rules to redirect {{/}} to {{apache-solr-reference-guide.html}} (or
declare it the {{DirectoryIndex}} ?)
> 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
> 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]
