[jira] [Updated] (SOLR-11539) autogenerated pdf-main-body.adoc should use explicit anchors for each included page

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

     [ https://issues.apache.org/jira/browse/SOLR-11539?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Hoss Man updated SOLR-11539:
----------------------------
    Attachment: SOLR-11539.patch

Here's a patch which updates BuildNavAndPDFBody to:

* validate that the {{page-shortname}} and {{page-permalink}} of all {{*.adoc}} files is consistent with the basefilename (no files currently fail this check, but it's important to catch future mistakes like this moving forward untill we can eliminate these attributes)
* adds explicit anchors using the {{page-shortname}} before each {{include::}} declaration in the generated {{pdf-main-body.adoc}} file

This should fix all of the broken "section" links mentioned in the parent issue where a page title doesn't "match" the filename/shortname...

{quote}
...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}
...

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


{quote}

...and will mean that moving forward, we should be free to change the "title" of pages all we want w/o breaking any links.

----

I think this patch is good to go, and should probably be backported to branch_7_1 before the 7.1 ref guide ... but it would be good to get more eyeballs on the generate PDF to verify that it doesn't break anything

> autogenerated pdf-main-body.adoc should use explicit anchors for each included page
> -----------------------------------------------------------------------------------
>
>                 Key: SOLR-11539
>                 URL: https://issues.apache.org/jira/browse/SOLR-11539
>             Project: Solr
>          Issue Type: Sub-task
>      Security Level: Public(Default Security Level. Issues are Public) 
>          Components: documentation
>            Reporter: Hoss Man
>            Assignee: Hoss Man
>         Attachments: SOLR-11539.patch
>
>
> see parent task for a discussion of why/how we currently have broken links/anchors in the PDF due to relying on the auto-generated "section" IDs for each included page and how nothing currently enforces that those auto-generated IDs (from the page titles) match the {{page-shortname}} used in the HTML pages where we do link validation.



--
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