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

Development
#1

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:

#2

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.

#3

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

#4

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

#5

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

#6

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:

#7

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

#8

+1 for the macro, at the very least because we need a common style for this kind of info and indeed it can be very handy in the future for displaying extension doc based on the version.
Small UI remark I’m not a big fan of the way the list of version is currently displayed: it makes it difficult to read, I would separate more the versions with a space after the comma at least.
Capture d’écran_2020-08-24_17-24-31

#9

definitely. That’s the beauty of it: you change the display layout in one place and all places using it are updated :wink:

#10

Just checked and there’s a space. If not, it means you forgot to put one when using the macro parameters! :slight_smile:

#11

+1 for using the macro. Just a small remark. I inspected the HTML and the content is not marked that well. It should have at least a CSS class on the top most element and it should also include some meta data (using data-* attributes, e.g. the versions). This is useful for styling and for JavaScript processing.

#12

Done.

Example:

versions

HTML (inline):

<span class="badge" data-xwikiorg-versions-since="12.3RC1">12.3RC1+</span>
#13

BTW I’d like that we agree too on whether we want to use RC in the versions or always final versions?

RC is more accurate but final versions look nicer and once the final is released there’s no reason to ever use the RC one.

I have a small preference to not use the RC text.

WDYT?

#14

Done: https://dev.xwiki.org/xwiki/bin/view/Community/DocGuide#HAffectedVersions

#15

I would use RC when specifying the version in the macro parameter but not display it. This way, technical users can still find the real since (either by looking at the source or by inspecting the HTML), while simple users get what they are interested in. BTW, would be good to also have a title attribute with the text “Before …” or “Since …” in case the + or <= are too cryptic.

#16

Very good ideas. I’ve implemented them, see https://www.xwiki.org/xwiki/bin/view/Macros/VersionMacro

#17

And I’ve now implemented a vertical bar to show what text is affected by the version macro, see https://www.xwiki.org/xwiki/bin/view/Macros/VersionMacro