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 <[email protected]> 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 > [email protected] > http://lists.xwiki.org/mailman/listinfo/devs _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
