[jira] [Updated] (SOLR-15092) Loosen Ref Guide link checking to allow empty anchors in links

["Chris M. Hostetter (Jira)" <ji...@apache.org>]

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

Chris M. Hostetter updated SOLR-15092:
--------------------------------------
    Attachment: SOLR-15092.patch
      Assignee: Chris M. Hostetter
        Status: Open  (was: Open)

the attached patch takes care of relaxing this rule, while still ensuring that if an anchor is used, it must exist in the linked file.

Once this patch is applied, the following perl command can be run to "clean up" any no longer needed anchors that point at the id on the body of each page...
{noformat}
perl -i -ple 's/<<(.*?)\.adoc#\1,/<<$1.adoc#,/g' src/*.adoc
{noformat}
...although in at least one place some manual cleanup needs to be done, because otherwise asciidoctor gets confused by this line in {{language-analysis.adoc}} ...
{noformat}
... Blank lines and lines that begin with "#" are ignored.  See <<resource-loading.adoc#,Resource Loading>> for more information.
{noformat}
...and thinks the {{# ... #}} bit is suppose to be "highlighted" using  html5 {{<mark/>}} tags...
{noformat}
... Blank lines and lines that begin with "<mark>" are ignored.  See <a href="#resource-loading.adoc</mark>">Resource Loading</a> for more information.
{noformat}
...so we'll have to either escape of backtick quote the first {{#}} character in the line.

(I didn't include the modifications made by the perl command in the patch, because we'll want to run that command on each branch given the other content changes between master & branch_8x)

> Loosen Ref Guide link checking to allow empty anchors in links
> --------------------------------------------------------------
>
>                 Key: SOLR-15092
>                 URL: https://issues.apache.org/jira/browse/SOLR-15092
>             Project: Solr
>          Issue Type: Improvement
>      Security Level: Public(Default Security Level. Issues are Public) 
>            Reporter: Cassandra Targett
>            Assignee: Chris M. Hostetter
>            Priority: Major
>         Attachments: SOLR-15092.patch
>
>
> Back when we were publishing the PDF, we needed to be sure to include an explicit section title as an anchor for all inter-document links (such as {{<<page-title.adoc#page-title,Page Title>>}}) because when the entire guide was assembled into a single file the explicit anchor ensured links went to the right spot in the overall Guide.
> Without the PDF, if we want to just link to another page in its entirety and not a sub-section of a page, we can use a shorter syntax with an empty anchor: {{<<page-title.adoc#,Page Title>>}}. I can't find this explicitly documented, but it does construct a correct link (i.e., {{<a href="page-title.html#">Page Title</a>}}).
> However, our link checking will fail this structure because it still assumes we must have a section name in the anchor and won't allow blank anchors. This issue is to loosen that check a bit and update the Ref Guide how-to docs to show it as a possible option.



--
This message was sent by Atlassian Jira
(v8.3.4#803005)

---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@lucene.apache.org
For additional commands, e-mail: issues-help@lucene.apache.org