Uploaded image for project: 'Solr'
  1. Solr
  2. SOLR-11531

ref-guide build tool assumptions missmatch with how "section" level anchor ids are actaully generated in PDF



    • Bug
    • Status: Closed
    • Major
    • Resolution: Fixed
    • None
    • 7.2, 8.0
    • documentation
    • None


      About a month ago, cassandra noticed some problems with a few links 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 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)...

      1. 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
      2. 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
      3. remove all (no longer useful) page-shortname & page-permalink attributes from all *.adoc files


        1. SOLR-11531.patch
          11 kB
          Chris M. Hostetter



            hossman Chris M. Hostetter
            hossman Chris M. Hostetter
            0 Vote for this issue
            1 Start watching this issue