FTR, on the topic of XML vs YAML, I don’t care that much. What I do care about is that: * all content can be written in separate files as plain text (using whatever editor we want) * to have validation of the syntax for the metadata (for example so that the build fails when you add “&” in a title metadata instead of “&”) Now, I don’t see much the usage of writing wiki pages from scratch (as opposed to writing them in an xwiki and exporting them). The typical use case for me is the following: * Develop the pages in the wiki and verify they work * Define a list of pages or space(s) that makes up an app in the pom.xml (as a configuration parameter of the xwiki XAR plugin), using regexes * Call the mvn xar:fetch mojo to export the pages from the live wiki into the source tree and perform xar:format automatically on them * commit in the SCM * when there are some simple bugs to fix or some content to change or an attachment to update, change directly in the sources and validate by deploying them in a running xwiki: mvn xar:deploy * if it works, commit, otherwise, fix the problems in the running wiki and then call mvn xar:fetch For this use case, it doesn’t matter much in what language the metadata is written in. So I guess what I’m saying is that for me what would help the most the current workflow used by the xwiki core dev team is: * the introduction of the xar:fetch and xar:deploy mojos * the validation (to help prevent mistakes) * the extraction of the attachments as standard files on the file system so that they can be replaced easily Thanks -Vincent
On 05 Sep 2016, at 12:13, Fabio Mancinelli <fabio.mancinelli@xwiki.com> wrote:
Hi,
just a little thought about YAML... Paul is right in saying that this format is a bit fragile. During the previous months I have been working with Ansible which uses YAML and indeed it has some quirks.
It's indeed very sensible to spacing: if you don't align correctly stuff you might have parsing errors, for example
- foo: 1 bar: 2
If you use some characters like ':' in the values you must be careful to quote the whole string otherwise you have a parse error:
title: Practical XWiki: A disciplined approach to knowledge management
this won't parse and must be written like:
title: "Practical XWiki: A disciplined approach to knowledge management"
On the other hand I find YAML quite good for easily describing structured data in a readable way. I think It's being used by major devops tools (Ansible, Salt, etc.) because of this reason.
----
Going back to FS formats, when I wrote xwikifs what was a real pain was to have class info in the objects subtree for every object type that was present in the page. This is because in the XAR format the <object> element contains a <class> subelement that basically describes the fields of the class used by the object (which is possibly declared in another page which also have its own description).
This was the biggest problem for me (because it would lead to code duplication with class descriptions).
For the rest I am a bit agnostic about the actual structure we will choose, but I agree with Vincent that the result should follow the convention over configuration approach.
I also like the fact that we can write content using isolated files with the good file extensions for its type (that's why I introduced the reference "->" operator in my proposal)
Thanks, Fabio
On Fri, Aug 26, 2016 at 9:07 PM, Vincent Massol <vincent@massol.net> wrote:
Hi devs,
There’s been several individual attemps at representing xwiki in a FS (see http://markmail.org/message/vxq2dyfzuvc5gt3a): * Caleb’s nodejs tool: https://github.com/xwiki-contrib/xwiki-tools-node * Fabio’s xwikifs: https://github.com/fmancinelli/xwikifs * Jean’s XFF: https://github.com/xwiki-contrib/api-xff * Paul’s XInclude extension to the XAR plugin: http://jira.xwiki.org/browse/XWIKI-13643
I think a first step is agreeing on the best representation and one we would agree on. I’ve based the proposal below on the format started by xwikifs since it’s for me the closest to the perfect format.
a <— nested page |_ b <— nested page |_ c <— nested page |_ content.<any extension, e.g. xwiki21> <— doc content |_ content.<language, e.g. fr>.<any extension, e.g. xwiki21> <— doc content translated |_ meta.yml <— doc metadata |_ meta.<language, e.g. fr>.yml <— doc metadata for translation |_ class.yml <— class definition |_ objects <— xobjects |_ d |_ e |_ f <— location of xclass |_ <object number, e.g 0> |_ <property id1>.yml |_ <property idN>.yml |_ <property idN>.content.<any extension, e.g. xwiki21> <— for externalizing property content, e.g. textarea
Notes:
* YAML is really the easiest to read and write and the most concise (parsing is easy but there’s also SnakeYaml). Example: JSON: { “title” : “my title”, “syntax” : “xwiki/2.1" } YAML: title: my title syntax: xwiki/2.1
* The extension is free so that we can use a value that represents the syntax of the content so that tools and IDE use the correct editor * For “objects” there could be some collision with a page name. So we would offer a property for the Maven plugin to override that default value with something else in case it’s necessary for a given project (but it’s unlikely that a page will be named “objects” anyway so this property wouldn’t be used often). * For the xclass of the xobject, I’m hesitating but I’ve put a directory hierarchy for the issue of limitation of file name under windows. If we use a single directory named after the reference, it might go beyond 255 chars more easily. We need to decide what we prefer. It could even be possible to support both representation with a maven property for the Maven plugin. * meta.yml for an xobject will also contain the class definition. Note that if we think it’s important, we could separate it and introduce an additional class.yml file but I don’t see the value right now.
Differences with xwikifs * Extension names * No reference syntax. I’ve defined fixed name for the various pieces so a reference syntax doesn’t seem required but I’d like to know Fabio’s POV since he may have had some ideas I haven’t understood. * No classinfo (see above, class info is inside meta.yml)
Let’s start with this and iterate!
WDYT? What have I forgotten?
Thanks -Vincent
_______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs