[
https://issues.apache.org/jira/browse/SOLR-10655?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16011629#comment-16011629
]
Hoss Man commented on SOLR-10655:
---------------------------------
bq. For a lot of our content, this may be a simpler approach. The syntax for
using tags like this is explained in:
http://asciidoctor.org/docs/user-manual/#include-partial
the "include tagged portion" does look like a perfect fit for what we were
using in cwiki -- and i agree that model of including a tagged portion of
another file is probably a better fit for what we want to do, because in all
the cases i can think of one page should really "own" the content, and it's
just a matter of other pages "citing" that content.
but in practice it seems to have bugs that will break links between the 2 pages
-- which seems like a deal breaker, since we explicitly draw attention to this
relationship in our pages (and i don't think we should stop doing that)...
https://github.com/asciidoctor/asciidoctor/issues/2200
I'm attaching a patch that tries to use the
{{include::foo.adoc\[tags=some_excerpt\]}} syntax in all places that currently
have a "TODO SOLR-10655" related comment -- see nocommits in the patch and the
ultimate build failure messages from {{ant build-site}} because of the our
automatic link checking.
bq. I personally split this problem into two separate use cases - first, we
used excerpt to save having to remember where we were maintaining a list of
related pages...like a copied TOC. This use case doesn't actually interest me
that much going forward, because I think it's a one-off that we are unlikely to
repeat. With better global find/replace at our disposal now, the task of
maintaining those pages is 1000x easier even if it doesn't reside in a single
place.
I 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.
(I would much rather use the "include tag" syntax then having these one off
snippet files, but given the viable options 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)
----
bq. ensuring anchors and relative links are generated in such a way that they
are still unique per-section
Note for future, there are easy ways to deal with this as long as the included
file _expects_ to be included in multiple places and explicitly declares all
it's anchors -- and our existing link checker code should automatically ensure
that's never problematic if someone forgets...
http://asciidoctor.org/docs/user-manual/#include-multiple
bq. 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)
FYI: I looked into this and confirmed that BuildNavAndPDFBody (currently) only
looks at "top level" {{src/*.adoc}} files, nothing in subdirectories -- so we
could easily start organizing "snippet" type files in whatever subdirs we want
w/o needing any code changes)
> 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]
