Groovy, Velocity, and XWiki syntax processing issues

[Stephen Schaub]

When XWiki renders a document, the interactions between the Groovy, 
Velocity, and Wiki (Radeox?) syntax processing can lead to unexpected and 
undesirable behavior. There have been posts on this list in the past where 
this issue has been discussed. However, I'm not aware that any consensus has 
emerged as to how to deal with these problems.

To summarize, here are a few of the issues that I'm aware of:

* Getting XWiki to render a bit of text without doing any syntax processing 
on it can be difficult. For example, the {pre} ... {/pre} markup turns off 
XWiki syntax processing, but not Groovy processing.

* The # symbol is used both to do numbered lists and is also used for Groovy 
processing. If a user wants to create a numbered list and forgets to put a 
space after the #, he can run into trouble. The following example will cause 
a stack dump:

  #bring coffee
  #include doughnuts

* Code samples on a Wiki page sometimes don't render correctly, due to 
conflicts with Velocity syntax processing. The following C/C++ code sample 
results in a runtime stack dump:

{code}
#include <stdio.h>
...
{code}

* Groovy and Velocity both use $varname syntax. I think I've read some posts 
in the past where this was an issue -- although I can't come up with any 
examples at the moment.

* A usability issue: Most XWiki tags ({table}, {code}, etc.) come in pairs. 
The closing tag has no slash. For example:  {table} ... {table}. However, 
the {pre} tag does have a closing slash: {pre} ... {/pre}. This 
inconsistency is annoying and causes difficulties for new users.

* A significant usability issue for Windows users: Pathnames contain 
backslashes (\). XWiki uses the backslash as an escape character. So 
attempting to put a UNC path like  \\myserver\myshare\mydoc.txt in an XWiki 
document triggers an XWiki runtime exception.  Boy, is that frustrating for 
new XWiki users. The solution is to wrap the path in {pre} .. {/pre}, but 
the error message gives the user no clue what the problem was, much less how 
to correct it.

Here are some proposals for discussion:

1. {pre} ... {/pre} should turn off ALL syntax processing of its contents.
2. {code} ... {code} should turn off ALL syntax processing, except for 
syntax coloring.
3. {pre} should allow {pre} as a closing tag.
4. Consider requiring users to explicitly enable Groovy/Velocity processing 
for selected Wiki documents as needed. In the page editor, provide two 
checkboxes: "Perform Groovy Processing" and "Perform Velocity Processing". 
The user could separately enable either Groovy or Velocity processing, or 
both. People who enable them would presumably be in a better position to 
deal with the kinds of syntax conflicts that would occur.
5. Provide more user-friendly error messages when a Groovy or Velocity 
processing exception occurs. Show the Wiki source line that caused the 
problem.

I haven't opened a JIRA issue for this yet, because I'm not sure how best to 
word it. But I think this is a high-priority issue that should be carefully 
addressed before the 1.0 release. This may be an issue that warrants a page 
on the xwiki.org developer site. I'll be glad to start one if the developers 
desire it -- perhaps here: 
http://www.xwiki.org/xwiki/bin/view/Dev/Discussions

Stephen