15 Apr
2005
15 Apr
'05
8:51 a.m.
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.