5 Sep
2016
5 Sep
'16
12:13 p.m.
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(a)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(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs