[
https://issues.apache.org/jira/browse/SOLR-10655?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16012647#comment-16012647
]
Hoss Man commented on SOLR-10655:
---------------------------------
bq. Your counter-argument conflates the two use cases I delineated while
attempting to disagree with the first one.
Yeah -- sorry, i distracted myself and never circled back to the point i
originally set out to make ... which was that in general i think we should do
whatever we can to eliminate any dup content.
Even if we don't expect to do #1 very often, all of the places we do both #2
*AND* #1 should be refactored in some way (not neccessarily the same way, if
there were hypothetical better options for each niche) to eliminate
duplication. just like my example of someone jumping straight to a single row
in a table and not noticing a comment that the entire table is duplicated --
someone might also go edit a list of collection based pages on
{{using-the-solr-administration-user-interface.adoc}} and maybe they notice the
comment that the entire list is duplicated on
{{collection-specific-tools.adoc}} - but maybe they overlook/missunderstand
that it's *ALSO* duplicated on {{core-specific-tools.adoc}}
hence my summation (intended for both #1 and #2 type usecasees)...
bq. ... i'd much rather someone opening a file to edit it find an
{{include::snippet/foo.adoc}} they didn't expect -- drawing attention to the
fact that the content is re-used in multiple places -- then find the content
they expect, but overlook that it's duplicated in multiple places
> 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]
