[
https://issues.apache.org/jira/browse/SOLR-11050?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16086174#comment-16086174
]
Cassandra Targett commented on SOLR-11050:
------------------------------------------
I just pushed a number of edits to {{asciidoc-syntax.adoc}} about link
construction, to make it much more clear how to construct such links. I decided
this was needed yesterday while working through the links, because I learned
much more about the differences during the process than I knew before and I
also knew the section was pretty light on info to start with.
bq. Should we add a note to meta-docs/asciidoc-syntax.adoc about the difference
between implicit section achors and explicit ones, and that if you rename a
section heading, you should add an explicit anchor not to break existing
deep-links
I didn't add this. It's already a bit fraught when you try to come up with a
simple answer to the question "How do I make a link to a section of another
page?" - I didn't want to add a decision tree to the equation. My goal in all
of this is to make it simpler for anyone with an ounce of energy to help with
the writing part.
I'm not saying I disagree with a policy of trying to keep links from being
dead, but I think there are some "well, maybe not always..." situations - I
don't want to have to carry around refs to section titles from 15 releases ago
because someone maybe has a bookmark to it. There are cases where we need to
just rename it and fix any incoming references and move on. There are also
other ways to deal with the problem of a dead reference - a helpful 404 page or
actual search, to name a couple - that we should explore, which IMO are beyond
the scope of this cleanup issue.
> Ref Guide: Remove Confluence-style anchor refs & clean up duplicate section
> titles
> ----------------------------------------------------------------------------------
>
> Key: SOLR-11050
> URL: https://issues.apache.org/jira/browse/SOLR-11050
> Project: Solr
> Issue Type: Task
> Security Level: Public(Default Security Level. Issues are Public)
> Components: documentation
> Reporter: Cassandra Targett
> Assignee: Cassandra Targett
> Fix For: 7.0
>
>
> To ensure section and page title uniqueness during conversion, we retained
> Confluence-style anchor references in the new .adoc files, which lead to long
> links and confusion about how to construct a link to another page/section. It
> was always the intention to remove these, but we didn't do it during the
> initial post-conversion cleanup and I neglected to file an issue for it.
> A script for this has been suggested, but that's problematic because many
> section titles are repeated on different pages (like "Input", etc.), and
> someone needs to decide how to modify the section titles to ensure clarity
> and uniqueness at the same time. Otherwise, Ref Guide builds will fail.
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
