Start using {{version}} macro when documenting parts related to some versions of XWiki

Hi devs,

Right now we have the following problems when we document stuff related to a version of xwiki:

  • Homogeneity: sometimes we use “Since 12.3”, some times “XWiki 12.3”, some times something else.
  • Being clear about where it starts and where it ends. We only specify where it starts but not the end which makes it ambiguous.
  • We cannot easily change the styling/L&F across the whole wiki to improve it.

Thus the proposal is to use the new {{version}} macro I have added at https://www.xwiki.org/xwiki/bin/view/Macros/VersionMacro

I’ve tested it on https://www.xwiki.org/xwiki/bin/view/Documentation/UserGuide/Features/PageEditing so you can review it.

What I’d like to do in the future is to be able to indicate visually the extent of the content affected by a version and to display the Since or Before in the gutter or on hover.

Usage:

Note: This macro works only standalone (and not inline) voluntarily. This is to allow displaying the versions in the gutter for example, which wouldn't be possible if used inline.

{{version since='11.10.5,12.5'}}
New feature...
{{/version}}

{{version before='11.10.5,12.5'}}
New feature...
{{/version}}

WDYT?

Related:

Once agreed, I’ll also update https://dev.xwiki.org/xwiki/bin/view/Community/DocGuide which is currently missing the concept of versioning doc parts.

I don’t understand how the new macro fixes this.

Because the documented content is inside the macro (as macro conten), so you have the end of the macro defining the end.

Maybe you’re referring to not the usage but the display, in which case it’s:

I understood that that but it’s not very useful to someone reading the documentation :slight_smile:

OK so it does not fix it :slight_smile:

Not fully but it fixes the hardest and most important part which is the data definition.