[xwiki-devs] [Brainstorming] Designing the perfect FS representation of a wiki

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