Right now if we want to avoid duplication of content between wiki pages, the solution is to create a hidden page that is then included (or displayed) from the other pages.
However, for smallish content (let’s say one sentence or a few sentences for example), it has drawbacks:
it feels overkill to create a page just for that,
even if the page is hidden, it’s artificial.
those who view hidden pages will see it and it’ll feel awkward.
So I’d like to brainstorm about how we could solve this and here’s an idea below.
Modify the {{include}} macro to allow specifying a small part of a given page. Right now the include macro supports including either the whole page or a section of it.
Introduce a new macro to define a small part of a page. We’d need to find a good name but for example {{excerpt id="..."}}...reusable content...{{/excerpt}}.
Example:
Definition: Hello world... {{except id="xxx"}}blah blah{{/excerpt}} more content...
Easy to define a reusable piece of content without creating a new page.
Easy to reuse and consistent with the goal of the include macro.
Should be easy to implement (same level of difficulty as including a section: we just need to look for MacroMarkerBlocks with a macro id of excerpt and a given id parameter.
You don’t really need a special macro IMO, the include macro could allow targeting any block by id. So you could do something like (%id="..."%)...reusable content...(%%) for example (as a bonus, this content can also be targeted through a URL anchor).
I think it’s missing semantics (intent). It would be a bit hard, when you read a page to understand that the part inside the parameters is meant to be some content reused somewhere else. Thus someone could remove it, or make modifications without thinking about where it’s used.
One way around this would be to use a more explicit parameter name such as reuse/excerpt (but it’d remove the linking ability)
I could be wrong but I think it would be more costly performance-wise. We’ll need to iterate through all blocks to find if a block has a parameter with a given name (vs looking for all MacroMarkerBlock with an excerpt macro id).
While I do support the idea of reusing content instead of duplicating work, I think that either of the suggested approaches (using hidden pages, using the include macro / another macro) aren’t ideal.
Regardless of the macro name, I think it would make it harder to edit pages.
If you edit the source-of-truth page, you’d always need to check if the content within pages that use content from the source-of-truth page, still make sense. Depending on the wording, they may need to be edited as well.
Or, if you edit a page which has a lot of include macros, the person editing would have to keep in mind the context for each instance of the macro on the page.
In my opinion, the best approach would be to have a page, or a section of a page, that would be the main source of truth for a certain piece of information, and in all other pages where you feel the need to repeat that content, to just mention the feature / item / whatever, and link to it.
e.g.:
instead of this:
Lorem ipsum {{include...}}. Dolor amet {{include...}} sit.
do this:
Lorem ipsum [concept](https://link-to-concept.com). Dolor amet [feature](https://link-to-feature.com) sit.
Used MD syntax for the links. It’s just an example to get the point across.
However, it’s the same as saying that when coding in Java, you should always introduce a public method (the equivalent of a non-hidden page) to share code between methods. We know it’s not always the case.
The topic here was about small content to share. There are 2 issues with this type of content:
There are cases when the content cannot be put in a public page because it doesn’t make sense by itself, it requires some context and that context is defined in the pages doing the include. And doing a refactoring wouldn’t work well (either you hit problem 1) or you don’t have the time to redesign the whole thing). An example for point 2) is https://www.xwiki.org/xwiki/bin/view/XS/XWikiStandardFlavor/User/ViewPage/ChangeSyntax/ConvertSyntax/ (hidden page ATM)
I doubt the difference is really noticeable (and it’s actually probably the opposite most of the time). Keep in mind that you always need to iterate over all blocks, it’s just that that then the way to identify the block is different:
Why limit it to these 2 types of blocks? Why couldn’t we include a table for example? Ofc the user can always wrap a table in a GroupBlock but it’s a bit more work and a bit less nice.
The reason it’s a bit more costly is the parameter check on all blocks all the time whereas there are very few macro blocks in a page. But I agree that it’s probably small.
We can have more blocks, yes (and table is fine too), I just meant that “id” could have specific meaning on some other blocks which won’t end up in HTML (for most macros you cannot even set it, for example).
Hello, I’m supporting the idea, but I’m not sure how the suggested proposal may improve the situation. For example, the page Administration Application could be used to introduce this as a test case or in a better approach. Currently, some information from this page is re-displayed in the Administrator Guide space.
Additionally, I’ve noticed another issue related to the duplication of attached images in XWiki website. Recently, while modifying the XWiki org documentation, I noticed that some pages are using the same images, but from separate locations and under different names.