[Brainstorming] Designing the perfect FS representation of a wiki

classic Classic list List threaded Threaded
23 messages Options
12
Reply | Threaded
Open this post in threaded view
|

[Brainstorming] Designing the perfect FS representation of a wiki

vmassol
Administrator
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
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Brainstorming] Designing the perfect FS representation of a wiki

Paul Libbrecht-2


Vincent Massol wrote:
> I think a first step is agreeing on the best representation and one we would agree on.
Allow me a process comment: I think that this is the right way to start
yet another representation project, it would be the fifth project. Here,
we want to find something more conclusive, or?

I find it more important that people express their:
- experience
- expectations
- disappointments
...of the current representations of XWiki content and code stores.

Paul
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Brainstorming] Designing the perfect FS representation of a wiki

vmassol
Administrator

> On 27 Aug 2016, at 11:15, Paul Libbrecht <[hidden email]> wrote:
>
>
>
> Vincent Massol wrote:
>> I think a first step is agreeing on the best representation and one we would agree on.
> Allow me a process comment: I think that this is the right way to start
> yet another representation project, it would be the fifth project.

Sure but that’s my right! Why would you be allowed to do that (and even complained when I told you that one option for you would have been to continue the existing XFF work!) and not me? :) lol

Now what you say is not true either. I’m not starting from scratch (contrary to you - I don’t remember seeing a mail from you explaining why the existing solutions did not work for you and with precise details and why you’ve started a new project based on xinclude). I’ve taken xwikifs and tried to build on it.

I’ve taken the time (did you?) to:
- analyze all the solution I’ve found (see my other mails)
- mention the limitation and problems of each (see my other mails)

TBH I’m quite disappointed for your lack of consideration. You started a mail thread and I spent a lot of hours yesterday (and a lot of off work hours too) to catch up on the topic… We just have a different approach. Your approach is NIH (and FTR I’m not against NIH). My approach is to analyze all the work that was already done and see their limitations and what more we’d need.

Now as I mentioned already (did you take the time to read the mails I sent yesterday? :)) I don’t see your solution as a competitor to the other projects. So don’t worry. BTW would be nice if you could answer the proposals I’ve made to try to fix your solution which doesn’t work well enough ATM for round-tripping (basic need of the xwiki dev team).

> Here,
> we want to find something more conclusive, or?

“we”: I don’t know. I speak only for myself.

> I find it more important that people express their:
> - experience
> - expectations
> - disappointments
> ...of the current representations of XWiki content and code stores.

So you clearly haven’t read the mails I sent yesterday because this is exactly what I’ve done…

Now nothing is exclusive. We do need a common agreed FS representation anyway for the future. It doesn’t prevent people from expressing their opinions on the 3 points you mention above.

Thanks
-Vincent

> Paul

_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Brainstorming] Designing the perfect FS representation of a wiki

Guillaume Delhumeau
Paul, your comment makes me think about https://xkcd.com/927/ :)

Now, as far as I can see, all the previous attempts where made by
individuals. Nothing have been really discussed and designed by the whole
team. Which is why I believe this new attempt could be the good one.

Moreover, Vincent is not starting form scratch but on the Fabio's project.
We only need to make some improvements on it.

About my expectations:

* I need a format that gives the same result when I export my content after
having imported it (bijection).
* I would prefer having it respecting the Nested Page hierarchy (ie: no
space concept).
* Easy to edit with whatever text editor. Maybe using a correct suffix to
enable the syntax highlighting easily: for example I usually edit my
content inside a file holding the ".vm" extension so my editor knows I will
write some Velocity code in it.

I never write code from scratch in my file system. But if I had to, I
suppose the hierarchy that Vincent suggests would be too complex. It might
be a problem for the developers who have written XFF and the NodeJs tools
which have code to be imported in XWiki, but does not have output filter
now.

Thanks,


2016-08-27 11:38 GMT+02:00 Vincent Massol <[hidden email]>:

>
> > On 27 Aug 2016, at 11:15, Paul Libbrecht <[hidden email]> wrote:
> >
> >
> >
> > Vincent Massol wrote:
> >> I think a first step is agreeing on the best representation and one we
> would agree on.
> > Allow me a process comment: I think that this is the right way to start
> > yet another representation project, it would be the fifth project.
>
> Sure but that’s my right! Why would you be allowed to do that (and even
> complained when I told you that one option for you would have been to
> continue the existing XFF work!) and not me? :) lol
>
> Now what you say is not true either. I’m not starting from scratch
> (contrary to you - I don’t remember seeing a mail from you explaining why
> the existing solutions did not work for you and with precise details and
> why you’ve started a new project based on xinclude). I’ve taken xwikifs and
> tried to build on it.
>
> I’ve taken the time (did you?) to:
> - analyze all the solution I’ve found (see my other mails)
> - mention the limitation and problems of each (see my other mails)
>
> TBH I’m quite disappointed for your lack of consideration. You started a
> mail thread and I spent a lot of hours yesterday (and a lot of off work
> hours too) to catch up on the topic… We just have a different approach.
> Your approach is NIH (and FTR I’m not against NIH). My approach is to
> analyze all the work that was already done and see their limitations and
> what more we’d need.
>
> Now as I mentioned already (did you take the time to read the mails I sent
> yesterday? :)) I don’t see your solution as a competitor to the other
> projects. So don’t worry. BTW would be nice if you could answer the
> proposals I’ve made to try to fix your solution which doesn’t work well
> enough ATM for round-tripping (basic need of the xwiki dev team).
>
> > Here,
> > we want to find something more conclusive, or?
>
> “we”: I don’t know. I speak only for myself.
>
> > I find it more important that people express their:
> > - experience
> > - expectations
> > - disappointments
> > ...of the current representations of XWiki content and code stores.
>
> So you clearly haven’t read the mails I sent yesterday because this is
> exactly what I’ve done…
>
> Now nothing is exclusive. We do need a common agreed FS representation
> anyway for the future. It doesn’t prevent people from expressing their
> opinions on the 3 points you mention above.
>
> Thanks
> -Vincent
>
> > Paul
>
> _______________________________________________
> devs mailing list
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/devs
>



--
Guillaume Delhumeau ([hidden email])
Research & Development Engineer at XWiki SAS
Committer on the XWiki.org project
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Brainstorming] Designing the perfect FS representation of a wiki

Paul Libbrecht-2
Hello Guillaume,

> Guillaume Delhumeau <mailto:[hidden email]>
> 29 August 2016 at 11:03
> Paul, your comment makes me think about https://xkcd.com/927/ :)
Good point!
Let's drive this quietly indeed.
>
> Now, as far as I can see, all the previous attempts where made by
> individuals. Nothing have been really discussed and designed by the whole
> team. Which is why I believe this new attempt could be the good one.
Agree.
> Moreover, Vincent is not starting form scratch but on the Fabio's project.
On a language that I find largely inferior to the previous one since
it's whitespace dependent as Python is which all developers I met find
very doubtful. But well... that's personal.
> We only need to make some improvements on it.
>
> About my expectations:
>
> * I need a format that gives the same result when I export my content
> after
> having imported it (bijection).
Please clarify here: do you need that for all projects of everyone of
just for the projects you intend to work with?
(that relates to the claim that we can have "source and push" projects
to be different form "source bijection wiki")
> * I would prefer having it respecting the Nested Page hierarchy (ie: no
> space concept).
> * Easy to edit with whatever text editor. Maybe using a correct suffix to
> enable the syntax highlighting easily: for example I usually edit my
> content inside a file holding the ".vm" extension so my editor knows I
> will
> write some Velocity code in it.
+1
I also claim that freedom in the extensions is better.
> I never write code from scratch in my file system. But if I had to, I
> suppose the hierarchy that Vincent suggests would be too complex. It might
> be a problem for the developers who have written XFF and the NodeJs tools
> which have code to be imported in XWiki, but does not have output filter
> now.
So you want freedom in the directory layout?
This might make sense to join to other build systems btw... (e.g. the
package task that includes a JS compilation or some documentation
generation).

Paul
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Brainstorming] Designing the perfect FS representation of a wiki

Guillaume Delhumeau
Hello Paul,

2016-09-02 11:00 GMT+02:00 Paul Libbrecht <[hidden email]>:

> Hello Guillaume,
>
> > Guillaume Delhumeau <mailto:[hidden email]>
> > 29 August 2016 at 11:03
> > Paul, your comment makes me think about https://xkcd.com/927/ :)
> Good point!
> Let's drive this quietly indeed.
> >
> > Now, as far as I can see, all the previous attempts where made by
> > individuals. Nothing have been really discussed and designed by the whole
> > team. Which is why I believe this new attempt could be the good one.
> Agree.
> > Moreover, Vincent is not starting form scratch but on the Fabio's
> project.
> On a language that I find largely inferior to the previous one since
> it's whitespace dependent as Python is which all developers I met find
> very doubtful. But well... that's personal.
> > We only need to make some improvements on it.
> >
> > About my expectations:
> >
> > * I need a format that gives the same result when I export my content
> > after
> > having imported it (bijection).
> Please clarify here: do you need that for all projects of everyone of
> just for the projects you intend to work with?
>

Of course, only on the projects that I work with. And for the projects
where people who think like me will work with. And I can potentially work
on every project that is currently hosted on xwiki-contrib... It's not only
about my usage, but about general best practices that we want to
enforce/encourage.


> (that relates to the claim that we can have "source and push" projects
> to be different form "source bijection wiki")
> > * I would prefer having it respecting the Nested Page hierarchy (ie: no
> > space concept).
> > * Easy to edit with whatever text editor. Maybe using a correct suffix to
> > enable the syntax highlighting easily: for example I usually edit my
> > content inside a file holding the ".vm" extension so my editor knows I
> > will
> > write some Velocity code in it.
> +1
> I also claim that freedom in the extensions is better.
> > I never write code from scratch in my file system. But if I had to, I
> > suppose the hierarchy that Vincent suggests would be too complex. It
> might
> > be a problem for the developers who have written XFF and the NodeJs tools
> > which have code to be imported in XWiki, but does not have output filter
> > now.
> So you want freedom in the directory layout?
>

No. I just hope that the directory structure will not be too difficult to
work with from scratch.


> This might make sense to join to other build systems btw... (e.g. the
> package task that includes a JS compilation or some documentation
> generation).
>
> Paul
> _______________________________________________
> devs mailing list
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/devs
>

Thanks,

--
Guillaume Delhumeau ([hidden email])
Research & Development Engineer at XWiki SAS
Committer on the XWiki.org project
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Brainstorming] Designing the perfect FS representation of a wiki

Fabio Mancinelli-4
In reply to this post by vmassol
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 <[hidden email]> 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
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Brainstorming] Designing the perfect FS representation of a wiki

vmassol
Administrator
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 “&amp;”)

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

_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Brainstorming] Designing the perfect FS representation of a wiki

Paul Libbrecht-2


Vincent Massol wrote:
> 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
Plus at least extract the JS-extensions and CSS-extensions as JS and CSS
files at least or?

And the same holds for velocity and groovy code or?
But here, I cannot find a way that would make it clear that a given
object property or page content is in velocity, groovy, or xxxx.
Is there a way?

Paul

PS: while it seems like there's been rules set so that one shouldn't
fiddle the XML to break XAR parsing, I am really surprised that there's
not been rules defined to avoid gross JS, CSS, velocity, or groovy
errors. Is that true?
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Brainstorming] Designing the perfect FS representation of a wiki

vmassol
Administrator

> On 05 Sep 2016, at 16:13, Paul Libbrecht <[hidden email]> wrote:
>
>
>
> Vincent Massol wrote:
>> 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
> Plus at least extract the JS-extensions and CSS-extensions as JS and CSS
> files at least or?

Yes those are content for me (what I meant by content is doc content + all xproperties of type textarea).

> And the same holds for velocity and groovy code or?
> But here, I cannot find a way that would make it clear that a given
> object property or page content is in velocity, groovy, or xxxx.
> Is there a way?

They’re not in groovy or velocity, they’re in some markup syntax (e.g. XWiki Syntax 2.1).

You’ll need an editor that knows how to understand that syntax if you wish syntax hilighting or autocompletion (same as what xwiki does already with the related extensions! ;)).

> Paul
>
> PS: while it seems like there's been rules set so that one shouldn't
> fiddle the XML to break XAR parsing, I am really surprised that there's
> not been rules defined to avoid gross JS, CSS, velocity, or groovy
> errors. Is that true?

We have automated tests (integration, functional) to verify that something works. If you’re talking manual then the process I’ve listed ensures that it works (ie that it’s been tested at least manually).

There’s no static analysis.

Thanks
-Vincent

_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Brainstorming] Designing the perfect FS representation of a wiki

Paul Libbrecht-2

>>> >> 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
>> > Plus at least extract the JS-extensions and CSS-extensions as JS and CSS
>> > files at least or?
> Yes those are content for me (what I meant by content is doc content + all xproperties of type textarea).
ok, so that's deterministic at least (but sometimes too much?)
Also, how do you determine the extension ? (seems like the object nature
would dictate that...).
>> > And the same holds for velocity and groovy code or?
>> > But here, I cannot find a way that would make it clear that a given
>> > object property or page content is in velocity, groovy, or xxxx.
>> > Is there a way?
> They’re not in groovy or velocity, they’re in some markup syntax (e.g. XWiki Syntax 2.1).
Mmh, here I am really not convinced.
I've seen many pages be only designed to be used using
parseGroovyFromPage. Is this something that is deprecated now?
I've also seen velocity-based content to be the core of the UI of most
applications and be contained in the content of pages.

>From the description you make, the files would not be .vm or .groovy
(actually, there would be none, right?) but using some
wiki-syntax-extension. Right?

To me, it seems like having .vm and .grv or .groovy files is essential.
I would be alone?

Paul
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Brainstorming] Designing the perfect FS representation of a wiki

vmassol
Administrator

> On 05 Sep 2016, at 16:42, Paul Libbrecht <[hidden email]> wrote:
>
>
>>>>>> 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
>>>> Plus at least extract the JS-extensions and CSS-extensions as JS and CSS
>>>> files at least or?
>> Yes those are content for me (what I meant by content is doc content + all xproperties of type textarea).
> ok, so that's deterministic at least (but sometimes too much?)
> Also, how do you determine the extension ? (seems like the object nature
> would dictate that...).
>>>> And the same holds for velocity and groovy code or?
>>>> But here, I cannot find a way that would make it clear that a given
>>>> object property or page content is in velocity, groovy, or xxxx.
>>>> Is there a way?
>> They’re not in groovy or velocity, they’re in some markup syntax (e.g. XWiki Syntax 2.1).
> Mmh, here I am really not convinced.
> I've seen many pages be only designed to be used using
> parseGroovyFromPage. Is this something that is deprecated now?

you’re probably talking about XWiki Syntax 1.0 but even that was wiki markup not groovy (you had to use <% …. %> ).

> I've also seen velocity-based content to be the core of the UI of most
> applications and be contained in the content of pages.

That’s in vm files, not wiki pages.

> From the description you make, the files would not be .vm or .groovy
> (actually, there would be none, right?) but using some
> wiki-syntax-extension. Right?
>
> To me, it seems like having .vm and .grv or .groovy files is essential.
> I would be alone?

Thanks
-Vincent

> Paul
>
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Brainstorming] Designing the perfect FS representation of a wiki

Paul Libbrecht-2

>> I've seen many pages be only designed to be used using
>> > parseGroovyFromPage. Is this something that is deprecated now?
> you’re probably talking about XWiki Syntax 1.0 but even that was wiki markup not groovy (you had to use <% …. %> ).
>
No.
parseGroovyFromPage loads a whole page of groovy and typically gives an
object. That page-content should start with

http://nexus.xwiki.org/nexus/service/local/repositories/public/archive/org/xwiki/platform/xwiki-platform-oldcore/7.4.2/xwiki-platform-oldcore-7.4.2-javadoc.jar/!/com/xpn/xwiki/api/XWiki.html#parseGroovyFromPage(java.lang.String)

and it seems widely used from searching the repositories.
(e.g.
https://github.com/xwiki-contrib/application-l10n/blob/master/src/main/resources/L10NCode/CompareTranslationFile.xml
which calls it on
https://github.com/xwiki-contrib/application-l10n/blob/master/src/main/resources/L10NCode/L10NGroovy.xml)
Should such a source not be as a .groovy file but a .wikipage file??

The <% %> of the XWik syntax 1.0 is for embedding groovy. That's
something else.

>> I've also seen velocity-based content to be the core of the UI of most
>> > applications and be contained in the content of pages.
> That’s in vm files, not wiki pages.
... and is often embedded in macros.
So, in your proposal, any macro code whose biggest part of the code
would be between {{velocity}} and {{/velocity}} (as suggested in most
tutorials) would not be living in a separate file but within a wiki-page
file. Right?

Paul
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Brainstorming] Designing the perfect FS representation of a wiki

vmassol
Administrator

> On 05 Sep 2016, at 17:10, Paul Libbrecht <[hidden email]> wrote:
>
>
>>> I've seen many pages be only designed to be used using
>>>> parseGroovyFromPage. Is this something that is deprecated now?
>> you’re probably talking about XWiki Syntax 1.0 but even that was wiki markup not groovy (you had to use <% …. %> ).
>>
> No.
> parseGroovyFromPage loads a whole page of groovy and typically gives an
> object. That page-content should start with
>
> http://nexus.xwiki.org/nexus/service/local/repositories/public/archive/org/xwiki/platform/xwiki-platform-oldcore/7.4.2/xwiki-platform-oldcore-7.4.2-javadoc.jar/!/com/xpn/xwiki/api/XWiki.html#parseGroovyFromPage(java.lang.String)

This is mostly deprecated. The new canonical way to have groovy in a page is now to use the {{groovy}} macro, and you can {{include}} a page that’s using {{groovy}} if you need to bring it to another page.

Note that in the xwiki core dev we don’t use groovy at all since this requires PR and makes it very fragile and a pain for our users.

> and it seems widely used from searching the repositories.
> (e.g.
> https://github.com/xwiki-contrib/application-l10n/blob/master/src/main/resources/L10NCode/CompareTranslationFile.xml
> which calls it on
> https://github.com/xwiki-contrib/application-l10n/blob/master/src/main/resources/L10NCode/L10NGroovy.xml)

Which is a xwiki/1.0 syntax page btw. IMO it should have been plain/1.0 instead.

> Should such a source not be as a .groovy file but a .wikipage file??

If you’re talking about https://github.com/xwiki-contrib/application-l10n/blob/master/src/main/resources/L10NCode/L10NGroovy.xml it should have a plain/1.0 syntax IMO.

> The <% %> of the XWik syntax 1.0 is for embedding groovy. That's
> something else.
>
>>> I've also seen velocity-based content to be the core of the UI of most
>>>> applications and be contained in the content of pages.
>> That’s in vm files, not wiki pages.
> ... and is often embedded in macros.

Not sure what you mean by vm files embedded in macros. What type of macros are you thinking about and what’s the relationship with wiki pages?

> So, in your proposal, any macro code whose biggest part of the code
> would be between {{velocity}} and {{/velocity}} (as suggested in most
> tutorials) would not be living in a separate file but within a wiki-page
> file. Right?

It’s not my proposal! It’s the way XWiki works right now :)

Thanks
-Vincent

PS: When you say macro, you need to be more specific. We have at least 4 or 5 types of macros (wiki macros, rendering macros in java, velocity macros, radeox macros).

> Paul

_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Brainstorming] Designing the perfect FS representation of a wiki

Paul Libbrecht-2


Vincent Massol wrote:
>> > http://nexus.xwiki.org/nexus/service/local/repositories/public/archive/org/xwiki/platform/xwiki-platform-oldcore/7.4.2/xwiki-platform-oldcore-7.4.2-javadoc.jar/!/com/xpn/xwiki/api/XWiki.html#parseGroovyFromPage(java.lang.String)
> This is mostly deprecated. The new canonical way to have groovy in a page is now to use the {{groovy}} macro, and you can {{include}} a page that’s using {{groovy}} if you need to bring it to another page.
You do not reach such an impact doing that. Far from it!
(e.g. if you want search cursors that fetch from some other data
sources; sure you can do it in Java but the Groovy way is much faster
developed).
> Note that in the xwiki core dev we don’t use groovy at all since this requires PR and makes it very fragile and a pain for our users.
Does this mean that apps don't use it?
Or that you wish the FS representation to not support it in a way that
makes the file source-files?
>> > and it seems widely used from searching the repositories.
>> > (e.g.
>> > https://github.com/xwiki-contrib/application-l10n/blob/master/src/main/resources/L10NCode/CompareTranslationFile.xml
>> > which calls it on
>> > https://github.com/xwiki-contrib/application-l10n/blob/master/src/main/resources/L10NCode/L10NGroovy.xml)
> Which is a xwiki/1.0 syntax page btw. IMO it should have been plain/1.0 instead.
I don't see the point saying that this is a wiki 1.0 syntax (or
plain-text) except for rendering. This page is a "groovy page" meant to
be used by parseGroovyFromPage; it has no value displaying it thus the
syntax can be whatever you want...

If I follow your logic, it should be, within a
file-system-representation, a file with such a name as "content.txt".
Then again... since you have no flexibility of names, you have to hack
things around to make an IDE edit this file and recognize it as a groovy
file.

>velocity ... and is often embedded in macros.

>
> Not sure what you mean by vm files embedded in macros.
Did I say vm files? I said vm fragements.
> What type of macros are you thinking about
the velocity macro.
> and what’s the relationship with wiki pages?
Generally, as far as I know, this is used to generate content.

Here is one of first tutorials...
  http://platform.xwiki.org/xwiki/bin/view/DevGuide/WikiMacroTutorial
The velocity suggested there can be very much bigger and being able to
split it out within a .vm file for you to edit with an IDE (and enjoy
auto-completion, method-analysis, and syntax-coloring) is, I believe, an
essential function of an FS representation.

Paul
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Brainstorming] Designing the perfect FS representation of a wiki

Guillaume Delhumeau
In reply to this post by vmassol
2016-09-05 18:20 GMT+02:00 Vincent Massol <[hidden email]>:

>
> > On 05 Sep 2016, at 17:10, Paul Libbrecht <[hidden email]> wrote:
> >
> >
> >>> I've seen many pages be only designed to be used using
> >>>> parseGroovyFromPage. Is this something that is deprecated now?
> >> you’re probably talking about XWiki Syntax 1.0 but even that was wiki
> markup not groovy (you had to use <% …. %> ).
> >>
> > No.
> > parseGroovyFromPage loads a whole page of groovy and typically gives an
> > object. That page-content should start with
> >
> > http://nexus.xwiki.org/nexus/service/local/repositories/
> public/archive/org/xwiki/platform/xwiki-platform-
> oldcore/7.4.2/xwiki-platform-oldcore-7.4.2-javadoc.jar/!/
> com/xpn/xwiki/api/XWiki.html#parseGroovyFromPage(java.lang.String)
>
> This is mostly deprecated. The new canonical way to have groovy in a page
> is now to use the {{groovy}} macro, and you can {{include}} a page that’s
> using {{groovy}} if you need to bring it to another page.
>
> Note that in the xwiki core dev we don’t use groovy at all since this
> requires PR and makes it very fragile and a pain for our users.
>
> > and it seems widely used from searching the repositories.
> > (e.g.
> > https://github.com/xwiki-contrib/application-l10n/blob/
> master/src/main/resources/L10NCode/CompareTranslationFile.xml
> > which calls it on
> > https://github.com/xwiki-contrib/application-l10n/blob/
> master/src/main/resources/L10NCode/L10NGroovy.xml)
>
> Which is a xwiki/1.0 syntax page btw. IMO it should have been plain/1.0
> instead.
>
> > Should such a source not be as a .groovy file but a .wikipage file??
>
> If you’re talking about https://github.com/xwiki-
> contrib/application-l10n/blob/master/src/main/resources/
> L10NCode/L10NGroovy.xml it should have a plain/1.0 syntax IMO.
>
> > The <% %> of the XWik syntax 1.0 is for embedding groovy. That's
> > something else.
> >
> >>> I've also seen velocity-based content to be the core of the UI of most
> >>>> applications and be contained in the content of pages.
> >> That’s in vm files, not wiki pages.
> > ... and is often embedded in macros.
>
> Not sure what you mean by vm files embedded in macros. What type of macros
> are you thinking about and what’s the relationship with wiki pages?
>

Let me explain with an example.

In an application, most pages contain a {{velocity}} macro in their
content, and their content is fully contained in that macro. Therefore,
even if the content is marked as xwiki/2.1, it would be more practical if
it were considered as velocity.

If the suffix of the file is ".xwiki21", there will be no editor with the
proper syntax highlighting in your computer to edit it. On the contrary, if
the suffix of the file that represents the content is ".vm", you will have
an editor with the syntax highlighting and everything...

So, even if the actual syntax is xwiki/2.1, I would prefer to have a ".vm"
file. But only if that file contains a {{velocity}} macro at the very
beginning.

I don't know how to handle it actually.

If we end up with a ".xwiki21" file, however, I will be able to manually
tell my text editor to consider it as Velocity.

For a page holding groovy macro, it's the same. I would prefer to have a
.groovy instead of a .xwiki21. That's what Paul is saying.

Do you see the use-case now?

Thanks,


>
> > So, in your proposal, any macro code whose biggest part of the code
> > would be between {{velocity}} and {{/velocity}} (as suggested in most
> > tutorials) would not be living in a separate file but within a wiki-page
> > file. Right?
>
> It’s not my proposal! It’s the way XWiki works right now :)
>
> Thanks
> -Vincent
>
> PS: When you say macro, you need to be more specific. We have at least 4
> or 5 types of macros (wiki macros, rendering macros in java, velocity
> macros, radeox macros).
>
> > Paul
>
> _______________________________________________
> devs mailing list
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/devs
>



--
Guillaume Delhumeau ([hidden email])
Research & Development Engineer at XWiki SAS
Committer on the XWiki.org project
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Brainstorming] Designing the perfect FS representation of a wiki

vmassol
Administrator

> On 05 Sep 2016, at 21:26, Guillaume Delhumeau <[hidden email]> wrote:
>
> 2016-09-05 18:20 GMT+02:00 Vincent Massol <[hidden email]>:
>
>>
>>> On 05 Sep 2016, at 17:10, Paul Libbrecht <[hidden email]> wrote:
>>>
>>>
>>>>> I've seen many pages be only designed to be used using
>>>>>> parseGroovyFromPage. Is this something that is deprecated now?
>>>> you’re probably talking about XWiki Syntax 1.0 but even that was wiki
>> markup not groovy (you had to use <% …. %> ).
>>>>
>>> No.
>>> parseGroovyFromPage loads a whole page of groovy and typically gives an
>>> object. That page-content should start with
>>>
>>> http://nexus.xwiki.org/nexus/service/local/repositories/
>> public/archive/org/xwiki/platform/xwiki-platform-
>> oldcore/7.4.2/xwiki-platform-oldcore-7.4.2-javadoc.jar/!/
>> com/xpn/xwiki/api/XWiki.html#parseGroovyFromPage(java.lang.String)
>>
>> This is mostly deprecated. The new canonical way to have groovy in a page
>> is now to use the {{groovy}} macro, and you can {{include}} a page that’s
>> using {{groovy}} if you need to bring it to another page.
>>
>> Note that in the xwiki core dev we don’t use groovy at all since this
>> requires PR and makes it very fragile and a pain for our users.
>>
>>> and it seems widely used from searching the repositories.
>>> (e.g.
>>> https://github.com/xwiki-contrib/application-l10n/blob/
>> master/src/main/resources/L10NCode/CompareTranslationFile.xml
>>> which calls it on
>>> https://github.com/xwiki-contrib/application-l10n/blob/
>> master/src/main/resources/L10NCode/L10NGroovy.xml)
>>
>> Which is a xwiki/1.0 syntax page btw. IMO it should have been plain/1.0
>> instead.
>>
>>> Should such a source not be as a .groovy file but a .wikipage file??
>>
>> If you’re talking about https://github.com/xwiki-
>> contrib/application-l10n/blob/master/src/main/resources/
>> L10NCode/L10NGroovy.xml it should have a plain/1.0 syntax IMO.
>>
>>> The <% %> of the XWik syntax 1.0 is for embedding groovy. That's
>>> something else.
>>>
>>>>> I've also seen velocity-based content to be the core of the UI of most
>>>>>> applications and be contained in the content of pages.
>>>> That’s in vm files, not wiki pages.
>>> ... and is often embedded in macros.
>>
>> Not sure what you mean by vm files embedded in macros. What type of macros
>> are you thinking about and what’s the relationship with wiki pages?
>>
>
> Let me explain with an example.
>
> In an application, most pages contain a {{velocity}} macro in their
> content, and their content is fully contained in that macro. Therefore,
> even if the content is marked as xwiki/2.1, it would be more practical if
> it were considered as velocity.
>
> If the suffix of the file is ".xwiki21", there will be no editor with the
> proper syntax highlighting in your computer to edit it. On the contrary, if
> the suffix of the file that represents the content is ".vm", you will have
> an editor with the syntax highlighting and everything...
>
> So, even if the actual syntax is xwiki/2.1, I would prefer to have a ".vm"
> file. But only if that file contains a {{velocity}} macro at the very
> beginning.
>
> I don't know how to handle it actually.
>
> If we end up with a ".xwiki21" file, however, I will be able to manually
> tell my text editor to consider it as Velocity.
>
> For a page holding groovy macro, it's the same. I would prefer to have a
> .groovy instead of a .xwiki21. That's what Paul is saying.
>
> Do you see the use-case now?

Thanks Guillaume. I had understood this but this is not how it works and I don’t think it’s a good idea to change the rendering model just for the sake of being able to edit outside of XWiki. Or at least that’s a much bigger scope than the one we’ve been discussing in this thread.

Right now wiki pages are written in a given syntax and macros are black boxes that can contain anything (including other syntaxes - imagine using the {{content}} macro for example, etc).

There’s no way that you’ll be able to find an existing IDE/editor on the market that knows this.

For example if you take the following simple example:

{{velocity}}
#set ($a = “b”)
{{/velocity}}

And you edit with an existing velocity editor, you’ll get syntax errors, bad autocompletion and bad syntax coloring because existing velocity editors don’t know about XWiki Syntax 2.1 (i.e. the {{velocity}} and {{/velocity}} parts).

The only solution is to use an XWiki Syntax 2.1 editor and, depending on the macros used, that knows how to delegate syntax highlighting and autocompletion to a specific editor for that content (velocity in this example). But you won’t have this tool in all existing IDEs and it’s a huge work to write that. FTR this is a bit what we started with XEclipse back then and we’re now more going towards a Web IDE.

If Paul (and your) point is to say that we should develop by writing the following then I wouldn't agree since that makes it very unnatural and hard to follow IMO:

{{velocity}}
#parseVelocityFromPage(‘some.other.page’)
{{/velocity}}

(And in some.other.page: #set ($a = “b”))

So I’m not sure where you’re going with this. There’s no good way unless you completely rewrite XWiki’s rendering system (and its syntaxes) and I’m sure you’ll agree this is a bit too much ;)

I was just trying to explain this to Paul in my previous answer.

Maybe you have an idea I haven’t imagined?

Thanks
-Vincent

> Thanks,
>
>
>>
>>> So, in your proposal, any macro code whose biggest part of the code
>>> would be between {{velocity}} and {{/velocity}} (as suggested in most
>>> tutorials) would not be living in a separate file but within a wiki-page
>>> file. Right?
>>
>> It’s not my proposal! It’s the way XWiki works right now :)
>>
>> Thanks
>> -Vincent
>>
>> PS: When you say macro, you need to be more specific. We have at least 4
>> or 5 types of macros (wiki macros, rendering macros in java, velocity
>> macros, radeox macros).
>>
>>> Paul

_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Brainstorming] Designing the perfect FS representation of a wiki

Guillaume Delhumeau
2016-09-05 22:09 GMT+02:00 Vincent Massol <[hidden email]>:

>
> > On 05 Sep 2016, at 21:26, Guillaume Delhumeau <
> [hidden email]> wrote:
> >
> > 2016-09-05 18:20 GMT+02:00 Vincent Massol <[hidden email]>:
> >
> >>
> >>> On 05 Sep 2016, at 17:10, Paul Libbrecht <[hidden email]> wrote:
> >>>
> >>>
> >>>>> I've seen many pages be only designed to be used using
> >>>>>> parseGroovyFromPage. Is this something that is deprecated now?
> >>>> you’re probably talking about XWiki Syntax 1.0 but even that was wiki
> >> markup not groovy (you had to use <% …. %> ).
> >>>>
> >>> No.
> >>> parseGroovyFromPage loads a whole page of groovy and typically gives an
> >>> object. That page-content should start with
> >>>
> >>> http://nexus.xwiki.org/nexus/service/local/repositories/
> >> public/archive/org/xwiki/platform/xwiki-platform-
> >> oldcore/7.4.2/xwiki-platform-oldcore-7.4.2-javadoc.jar/!/
> >> com/xpn/xwiki/api/XWiki.html#parseGroovyFromPage(java.lang.String)
> >>
> >> This is mostly deprecated. The new canonical way to have groovy in a
> page
> >> is now to use the {{groovy}} macro, and you can {{include}} a page
> that’s
> >> using {{groovy}} if you need to bring it to another page.
> >>
> >> Note that in the xwiki core dev we don’t use groovy at all since this
> >> requires PR and makes it very fragile and a pain for our users.
> >>
> >>> and it seems widely used from searching the repositories.
> >>> (e.g.
> >>> https://github.com/xwiki-contrib/application-l10n/blob/
> >> master/src/main/resources/L10NCode/CompareTranslationFile.xml
> >>> which calls it on
> >>> https://github.com/xwiki-contrib/application-l10n/blob/
> >> master/src/main/resources/L10NCode/L10NGroovy.xml)
> >>
> >> Which is a xwiki/1.0 syntax page btw. IMO it should have been plain/1.0
> >> instead.
> >>
> >>> Should such a source not be as a .groovy file but a .wikipage file??
> >>
> >> If you’re talking about https://github.com/xwiki-
> >> contrib/application-l10n/blob/master/src/main/resources/
> >> L10NCode/L10NGroovy.xml it should have a plain/1.0 syntax IMO.
> >>
> >>> The <% %> of the XWik syntax 1.0 is for embedding groovy. That's
> >>> something else.
> >>>
> >>>>> I've also seen velocity-based content to be the core of the UI of
> most
> >>>>>> applications and be contained in the content of pages.
> >>>> That’s in vm files, not wiki pages.
> >>> ... and is often embedded in macros.
> >>
> >> Not sure what you mean by vm files embedded in macros. What type of
> macros
> >> are you thinking about and what’s the relationship with wiki pages?
> >>
> >
> > Let me explain with an example.
> >
> > In an application, most pages contain a {{velocity}} macro in their
> > content, and their content is fully contained in that macro. Therefore,
> > even if the content is marked as xwiki/2.1, it would be more practical if
> > it were considered as velocity.
> >
> > If the suffix of the file is ".xwiki21", there will be no editor with the
> > proper syntax highlighting in your computer to edit it. On the contrary,
> if
> > the suffix of the file that represents the content is ".vm", you will
> have
> > an editor with the syntax highlighting and everything...
> >
> > So, even if the actual syntax is xwiki/2.1, I would prefer to have a
> ".vm"
> > file. But only if that file contains a {{velocity}} macro at the very
> > beginning.
> >
> > I don't know how to handle it actually.
> >
> > If we end up with a ".xwiki21" file, however, I will be able to manually
> > tell my text editor to consider it as Velocity.
> >
> > For a page holding groovy macro, it's the same. I would prefer to have a
> > .groovy instead of a .xwiki21. That's what Paul is saying.
> >
> > Do you see the use-case now?
>
> Thanks Guillaume. I had understood this but this is not how it works and I
> don’t think it’s a good idea to change the rendering model just for the
> sake of being able to edit outside of XWiki. Or at least that’s a much
> bigger scope than the one we’ve been discussing in this thread.
>
> Right now wiki pages are written in a given syntax and macros are black
> boxes that can contain anything (including other syntaxes - imagine using
> the {{content}} macro for example, etc).
>
> There’s no way that you’ll be able to find an existing IDE/editor on the
> market that knows this.
>
> For example if you take the following simple example:
>
> {{velocity}}
> #set ($a = “b”)
> {{/velocity}}
>
> And you edit with an existing velocity editor, you’ll get syntax errors,
> bad autocompletion and bad syntax coloring because existing velocity
> editors don’t know about XWiki Syntax 2.1 (i.e. the {{velocity}} and
> {{/velocity}} parts).
>

This is what happens in practice when you use an extension like "It's all
text" (https://addons.mozilla.org/en-US/firefox/addon/its-all-text/) and
that is not a big deal. This how I work every day.


>
> The only solution is to use an XWiki Syntax 2.1 editor and, depending on
> the macros used, that knows how to delegate syntax highlighting and
> autocompletion to a specific editor for that content (velocity in this
> example). But you won’t have this tool in all existing IDEs and it’s a huge
> work to write that. FTR this is a bit what we started with XEclipse back
> then and we’re now more going towards a Web IDE.
>
> If Paul (and your) point is to say that we should develop by writing the
> following then I wouldn't agree since that makes it very unnatural and hard
> to follow IMO:
>
> {{velocity}}
> #parseVelocityFromPage(‘some.other.page’)
> {{/velocity}}
>
> (And in some.other.page: #set ($a = “b”))
>

No. The Paul's initial proposal was about introducing an @textInclude() in
the XML file that could include any file. The advantage is that the
developer can use whatever suffix she wants.

@textInclude('myContent.vm')
@textInclude('myContent.groovy')
etc...

The drawback is that you cannot have it when you export the page (no
bijection).


>
> So I’m not sure where you’re going with this. There’s no good way unless
> you completely rewrite XWiki’s rendering system (and its syntaxes) and I’m
> sure you’ll agree this is a bit too much ;)
>
> I was just trying to explain this to Paul in my previous answer.
>
> Maybe you have an idea I haven’t imagined?
>
> Thanks
> -Vincent
>
> > Thanks,
> >
> >
> >>
> >>> So, in your proposal, any macro code whose biggest part of the code
> >>> would be between {{velocity}} and {{/velocity}} (as suggested in most
> >>> tutorials) would not be living in a separate file but within a
> wiki-page
> >>> file. Right?
> >>
> >> It’s not my proposal! It’s the way XWiki works right now :)
> >>
> >> Thanks
> >> -Vincent
> >>
> >> PS: When you say macro, you need to be more specific. We have at least 4
> >> or 5 types of macros (wiki macros, rendering macros in java, velocity
> >> macros, radeox macros).
> >>
> >>> Paul
>
> _______________________________________________
> devs mailing list
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/devs
>



--
Guillaume Delhumeau ([hidden email])
Research & Development Engineer at XWiki SAS
Committer on the XWiki.org project
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Brainstorming] Designing the perfect FS representation of a wiki

Paul Libbrecht-2
I think that we are converging to agree that includes and bijection are,
in the current situation, not reconcilable.

Would there not be a possibility to mark the content with something
similar to "comments" (aka "ignorable content") so that the included
parts have a defined filename and a defined extent?

Paul

_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Brainstorming] Designing the perfect FS representation of a wiki

vmassol
Administrator
In reply to this post by Guillaume Delhumeau

> On 05 Sep 2016, at 22:27, Guillaume Delhumeau <[hidden email]> wrote:

[snip]

> The only solution is to use an XWiki Syntax 2.1 editor and, depending on
>> the macros used, that knows how to delegate syntax highlighting and
>> autocompletion to a specific editor for that content (velocity in this
>> example). But you won’t have this tool in all existing IDEs and it’s a huge
>> work to write that. FTR this is a bit what we started with XEclipse back
>> then and we’re now more going towards a Web IDE.
>>
>> If Paul (and your) point is to say that we should develop by writing the
>> following then I wouldn't agree since that makes it very unnatural and hard
>> to follow IMO:
>>
>> {{velocity}}
>> #parseVelocityFromPage(‘some.other.page’)
>> {{/velocity}}
>>
>> (And in some.other.page: #set ($a = “b”))
>>
>
> No. The Paul's initial proposal was about introducing an @textInclude() in
> the XML file that could include any file. The advantage is that the
> developer can use whatever suffix she wants.
>
> @textInclude('myContent.vm')
> @textInclude('myContent.groovy')
> etc...
>
> The drawback is that you cannot have it when you export the page (no
> bijection).

Yes I didn’t mention this option because for me it’s not an option and it”s not going to work:
* As you say there’s no bijection, that’s the main issue
* won’t fully work in some cases. Imagine a Velocity macro wrapping an HTML macro. You can edit with a velocity editor but then you loose the HTML edition or you can edit in an HTML editor but then you loose the velocity syntax.

My feeling is that using a specific editor doesn’t bring that much value compared to editing directly in XWiki (using the syntax hilighiting and autocompletion extensions). For example I also use IntelliJ IDEA to edit the XWiki .vm files (velocity content) and I’ve never felt that it was providing a much greater experience.

And since you need an execution engine anyway to validate that your code works you need to execute it in XWiki anyway so you might as well fully edit in XWiki.

I think what I’m trying to say is that I believe more in the direction of working to improve the syntax hilighting/autocompletion and XWebIDE to provide a better development experience in the future.

Again, what I do find that has value:
* Be able to not have to XML-encode doc content and textarea xproperty content
* Be able to have attachments separate from the XML
* Have those new XAR mojos to fetch and push/deploy.

IMO this is what we should focus on doing in a first version.

Thanks
-Vincent

> So I’m not sure where you’re going with this. There’s no good way unless
>> you completely rewrite XWiki’s rendering system (and its syntaxes) and I’m
>> sure you’ll agree this is a bit too much ;)
>>
>> I was just trying to explain this to Paul in my previous answer.
>>
>> Maybe you have an idea I haven’t imagined?
>>
>> Thanks
>> -Vincent
>>
>>> Thanks,
>>>
>>>
>>>>
>>>>> So, in your proposal, any macro code whose biggest part of the code
>>>>> would be between {{velocity}} and {{/velocity}} (as suggested in most
>>>>> tutorials) would not be living in a separate file but within a
>> wiki-page
>>>>> file. Right?
>>>>
>>>> It’s not my proposal! It’s the way XWiki works right now :)
>>>>
>>>> Thanks
>>>> -Vincent
>>>>
>>>> PS: When you say macro, you need to be more specific. We have at least 4
>>>> or 5 types of macros (wiki macros, rendering macros in java, velocity
>>>> macros, radeox macros).
>>>>
>>>>> Paul

_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
12