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