[
https://issues.apache.org/jira/browse/SOLR-10655?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16012466#comment-16012466
]
Cassandra Targett commented on SOLR-10655:
------------------------------------------
bq. disagree ... i think that unless asciidoctor issue#2200 has an easy
workaround we should move forward with refactoring this duplicated
documentation into some "snippet" files that can be included in multiple
places. Even if search and replace is much easier with adoc then with cwiki,
it's too easy for someone who doesn't realize the content is duplicated to make
an edit in to only one copy. we can have all the // NOTE: this table is
duplicated in defining-fields.adoc type comments we want, but those may still
be easily overlooked by someone who (for example) knows they need to edit one
cell of a table in field-type-definitions-and-properties.adoc and uses uses
their editor's search feature to jump to the relevant line – never realizing
there is a big ass comment off screen above that table informing them about
another page they may not have ever paid attention to.
Your counter-argument conflates the two use cases I delineated while attempting
to disagree with the first one.
We used this two ways, to be specific:
# We made a list of children pages on one page, then used
excerpt/excerpt-include to include the same list of children on another 2
pages. Essentially, we had 3 pages with the same TOC.
# We made a table on one page and included that table on another page.
My point is that I think the 2nd case is more common use of shared content than
the first. I personally don't think we're going to do the first very often, or
we would have done it already.
That said, the linking problem is still a problem.
> refactor duplicate ref guide content into "snippet" files that can be included
> ------------------------------------------------------------------------------
>
> Key: SOLR-10655
> URL: https://issues.apache.org/jira/browse/SOLR-10655
> Project: Solr
> Issue Type: Sub-task
> Security Level: Public(Default Security Level. Issues are Public)
> Components: documentation
> Reporter: Hoss Man
>
> in cwiki, we were using the "excerpt" and "excerpt-include" macros to mirror
> some content across multiple pages.
> as part of the cwiki->adoc migration, these macros were just evaluated
> durring export, and the content is now duplicated.
> moving forward, we should refactor this duplicated content into "snippet"
> files that can be included in multiple places. A few things we need to be
> careful about when doing this:
> * ensuring anchors and relative links are generated in such a way that they
> are still unique per-section
> * that some convention / page attributes are used such that the
> BuildNavAndPDFBody code doesn't try to include them as "real" pages (or
> errors that they have no parent)
--
This message was sent by Atlassian JIRA
(v6.3.15#6346)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
