[jira] [Updated] (SOLR-11531) ref-guide build tool assumptions missmatch with how "section" level anchor ids are actaully generated in PDF

["Hoss Man (JIRA)" <ji...@apache.org>]

     [ 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: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org