[
https://issues.apache.org/jira/browse/SOLR-10655?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16010976#comment-16010976
]
Cassandra Targett edited comment on SOLR-10655 at 5/15/17 5:46 PM:
-------------------------------------------------------------------
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.
The other use case I find more useful, which is to split a page into smaller
bits and use {{include::}} syntax to include the snippet in a broader page. The
way I've thought of it is that there is a sub-dir somewhere that has these
little snippets and we do something like {{include::some-dir/y.adoc[]}}. I'm
wary of that approach, just in terms of document sprawl with lots of possible
contributors - it could get messy.
However, it occurs to me now that there is another approach using {{include::}}
where you mark up a document with tags where you'll want to pull content, and
then in your other document use the same {{include::}} macro but request only
that tagged section, as in {{include::y.adoc\[tags=section1]}}. 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
was (Author: ctargett):
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.
The other use case I find more useful, which is to split a page into smaller
bits and use {{include::}} syntax to include the snippet in a broader page. The
way I've thought of it is that there is a sub-dir somewhere that has these
little snippets and we do something like {{include::some-dir/y.adoc[]}}. I'm
wary of that approach, just in terms of document sprawl with lots of possible
contributors - it could get messy.
However, it occurs to me now that there is another approach using
{{includes::}} where you mark up a document with tags where you'll want to pull
content, and then in your other document use the same {{include::}} macro but
request only that tagged section, as in {{include::y.adoc\[tags=section1]}}.
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
> 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]
