I’ve just checked this FTM as I wanted to see the changes. I noticed the new 1.4 format but there’s no explanation about what it changes in term of structure for the XAR. Is that missing or did I miss something?
And if there’s no structural change, then why a new format version?
Note that you could/should have copied the example int he 1.3 section to keep an example there.
I’d restructure the doc so that everything is versioned since we support several formats. You could have several pages: the main page for the latest version and sub page(s) for older versions.
Since you’re asking about the names, I’d have used <contentVersion> rather than <contentAlias> because what’s indicated is a version.
Some questions:
The doc says " You can see the XML of a document by exporting it and opening the XAR or by using the xpage=xml parameter when on wiki page URL.". I think this is not true anymore, right?
Should the <versions> tag still be there in v1.4 or should it not be specified at all?
<versions> is missing in the doc for xwikidoc.
Couldn’t we have reused the <versions> tag instead of introducing a synonym? If an XWiki supporting v1.3 tries to load a v1.4 XAR then it’ll fail anyway since <versions> won’t be there or be empty, no? Is it to be a bit more safe? Or maybe it won’t be there and thus it won’t fail, it’ll silently ignore the history for the attachment?
I tough about it but I find it not clear enough what this “content version” is about, the most important thing to express IMO is that the content is located somewhere else.
Not sure what you mean. The XML you get with xpage=xml is XAR XML, this did not changed.
The point of incrementing the version is to indicate new stuff have been added but is still part of the specification and it still supported, just not recommended because not great from memory point of view.
No because we want to keep the XML as retro compatible as possible, previous versions of XWiki will simply ignore the tag because they don’t know it and you will simply not have any attachment history.
As you wish, but for me what’s important is to indicate that the content to be used is the one from that version. The concept of content alias is foreign to me, I don’t know what an alias to a content means and I suspect others won’t know either. But the version of the content is simpler to understand IMO.
This part of the doc is there to explain how to understand the “Document XML file” in this section and to explain that it’s the same as the one you get when you get a page’s XML. This is not true anymore. So this needs to be removed or better explain that it’s partially true with some changes for xxx and xxx.
My point is that contentVersion just indicate this is “the version of that content” but it’s not obvious what it really means and that it’s actually a different revision of the attachment. I’m not saying “contentAlias” is perfect but I think the most important for the element name is to express that the content is not here and need to be searched somewhere else, i.e. that this is not a metadata but a link to a different metadata.
I still don’t understand why it’s not true anymore. This documented specification is the specification of the format you have in xpage=xml since xpage=xml use the XAR serializer.
When I use xpage=xml for a wiki page, will I get the new <revisions> tag? If the answer is no then the doc needs to be improved. If the answer is yes then it’s good.
EDIT: I guess you’re saying that the answer is yes. Then indeed it’s good. I didn’t realize that xpage=xml is actually showing the same as the XAR serializer That’s good then.
