15 Apr
2005
15 Apr
'05
10:05 a.m.
Hi,
I agree this is an important discussion. I've added radeox, velocity and
groovy (and also xwiki plugins) to see how these different way of
extending XWiki would work.
What I found is that velocity has the worst syntax since it pleases
neither the most advanced users (which will prefer groovy for coding)
and neither the basic users which are not familiar with # and
parenthesis. But velocity is the most flexible for creating the extensions.
How does extending work:
1/ Groovy
* Only allowed for admin because there is no security manager.
* Not possible to create functions in one document and reuse them in another
* Not possible to pass context from one document to another so no way to
use an includeMacros as a "function".
* Can be tested inline
2/ Radeox
* Need to write java to extend
* Once the parameters are chosen no way to change it
* Need a release to deploy
* Cannot be tested inline
3/ Velocity
* can be included in documents and context is passed around (allows to
use includeMacros as a "function")
* small bug to fix to reuse a function in one document in another (first
execution fails)
* can be tested inline
* Can be deployed as a general macro (in /templates/macros.vm)
* Can be easily modified by other users to suit specific needs
4/ XWiki Plugins
* Need a release to deploy
For me velocity really has the best flexibility, until we do something
really more powerfull with Groovy (but there is lot of work).
Now there is an issue with syntax, but nothing that cannot be solved.
Why not write a first parser that will look for specific tags and
transform them from radeox to velocity.
There would be a config file editable from the wiki to give the way it
works. Basically it is a definition of the velocity functions available
and the parameter names and position:
includeTopic=name
anchor=name
toc=
image=name,width,height
This would mean
{image:filename|50|50} or {image:name=filename|width=50|height=50}or
{image:width=50|height=50|name=filename.jpg} would be all converted to
#image("filename.jpg" "50" "50")
and
{image:filename} would be converted to #image("filename.jpg" ""
"")
We could have the same in the future for Groovy and this way would be
kept completely independent of the way macros are actually implemented.
This would give a unique syntax with a powerfull extension method, close
to the best of both worlds.
What do you think ?
Ludovic
Jiri Luzny a écrit :
Hi,
I would like to start a discussion about a concept of future extending
of XWiki syntax. I already had a short email conversation with Ludovic
about this topic and I would like to know your opinion.
There are some missing things in XWiki syntax that prevent us to have
XWiki documents as the standard documentation form in the department I
work. I would like to extend the syntax with features such as Table of
Content, cross-references (smarter linking inside one document),
headers and footers, bookmarks in PDF output etc...
There are currently two approaches how it can be done in XWiki:
1. to extend it using Radeox macros
2. to use Velocity macros and variables for it
Here are a couple of examples how a document writer would then use
each variant:
Table Of Content:
1. {toc}
2. #toc() or ${doc.getToc()}
Anchor:
1. {anchor|anchor_name}
2. #anchoe(anchor_name)
Link to internal anchor:
1. [#anchor_name]
2. [${doc.fullname}#anchor_name]
Include other document:
1. {icludePage:page_name}
2. #includeTopic("page_name")
Ludovic tends to prefer the Velocity approach due its easier way of
integrating and deploying, however I personally have a little problem
with adding such basic, pure document related tags as Velocity macros.
The biggest issue I see is the mixing of those two approaches without
a clear separation of purpose. Most of our end-users like a Project
Managers, Requirements Analysts and Testers are not skilled
programmers and they treat XWiki as a Word editor for web based
knowledge collaboration. It is now confusing and hard to explain to
them why sometimes they should use {macro} and sometimes #macro() (I'm
not even talking about explaining what ${doc.fullname} means ;-)).
Both snipsnap and confluence using only radeox macros which is not
that flexible as XWiki velocity macros but it is a consistent for both
end-user and developer extending it. On the other hand, Velocity
macros (together with Groovy) are excellent for *programming* of
documents, adding fancy staff to it like the Blog macros, IM macros
etc..
I would personally vote for using Radeox macros for the basic document
editing and formatting capabilities and Velocity for the more advanced
stuff.
Jiri.
------------------------------------------------------------------------
--
You receive this message as a subscriber of the xwiki-dev(a)objectweb.org mailing list.
To unsubscribe: mailto:xwiki-dev-unsubscribe@objectweb.org
For general help: mailto:sympa@objectweb.org?subject=help
ObjectWeb mailing lists service home page: http://www.objectweb.org/wws
--
Ludovic Dubost
XPertNet: http://www.xpertnet.fr/
Blog: http://www.ludovic.org/blog/
XWiki: http://www.xwiki.com
Skype: ldubost AIM: nvludo Yahoo: ludovic