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