[xwiki-devs] [SUMMARY] Re: [Discussion] Designing the new Rendering/Parsing component/API

[Mikhail Kotelnikov]

Hi! Excuse me please for the late response...

On 9/26/07, Vincent Massol <vincent at massol.net> wrote:
>
> Hi xwiki devs,
> This is a summary of the decisions so far and the remaining questions.
> This is also the outcome of my discussion of today with Mikhail on skype.
> 1) We'll be able to import all syntaxes.
>

Yes


2) An XWiki instance will use a single syntax at a time. Once the database
> is created using that syntax it won't be possible to change it (except by
> doing an export and reimport).
>
> We also need to decide what syntax we use by default OOB. I propose we use
> the current xwiki syntax for some time and then switch to the Wikimodel one
> (Common Syntax) later on.
>

 I have no choice - I have to vote for the "CommonSyntax" :-)


3) All pages will be able to be exported to any syntax. Some elements have
> no equivalent in other syntaxes and when this happens a warning will be
> displayed and the elements in question ignored.
>

Yes. You can loose data only when you *export* your data from the
CommonSyntax, not when you *import* it. The WikiModel/CommonSyntax support a
super-set of elements defined in other wikis.

BTW: I think that it would be useful to involve Max Völkel (http://xam.de/)
in the discussion about wiki imports/exports. Max is one of authors of the
Semantic Media WIki. He proposed a Wiki Interchange Format (WIF) <
http://eyaloren.org/pubs/semwiki2006-wif.pdf> which covers the topic. At
least it would be useful to know his opinion.


4) Mikhail has agreed to modify wikiModel to add macro block
recognition.Thesyntax isn't fully defined yet but it'll be something
like:
>
> {xxx param1=value1 param2=value2}
> ...
> {/xxx}
>
> (param1='value value' and param1="value value" will also be supported)
>
> This means we'll be able to have a common syntax for xwiki's macros and
> also for groovy code:
>
> {groovy}
> ...
> {/groovy}
>
> And also for HTML blocks:
>
> {html}
> ...
> {/html}
>

It is already done and committed. You can use "embedded" macro blocks like
{xxx param1=value1 param2="long value 2" param3='this is a parameter 3'}
   ... {yyy} ... {/yyy} ...
{/xxx}

Even embedded elements with the same names are possible:
{xxx}
   ...
     {xxx}
       ... {yyy} ... {/yyy} ...
     {/xxx}
   ...
{/xxx}


5) We need to decide if we want:
>
> A) No velocity block but document properties/metadata to tell xwiki to
> render the page using velocity. A user putting velocity code in a page will
> have to check a box somewhere to say that this is a velocity page.
>
> Pros:
> * Slightly easier to enter velocity code
>
> Cons:
> * Exception case compared to groovy, macros, etc
> * User must not forget to check the checkbox saying the page contains
> velocity code
>
> OR
>
> B) Velocity blocks same as what exists for groovy/macros/html, namely:
>
> {velocity}
> ... velocity code with wiki syntax allowed
> {/velocity}
>
> Note1: For B) we would allow putting wiki syntax inside the velocity
> block. Technically we'll apply the velocity rendering and then re-apply
> wikimodel on the result.
> Note2: For backward compatibility we can have a config flag (
> xwiki.compatibility = 1) that automatically adds the {velocity}{/velocity}
> marker around the whole page. The only downside is that it'll be as slow as
> it currently is (actually it'll be faster since wikimodel is going to be
> faster than radeox)
>
> Pros:
> * Speed. Since we know the blocks that use velocity we can cache all the
> wiki syntax not inside the velocity/macros/groovy blocks which will speed up
> considerably the rendering of pages
> * Consistency with macros and groovy blocks.
>
> My preferences goes to B) and I'm proposing to use that.
>

My +1 for B)


6) Mikhail is going to add support for recognizing XML tags in the wikimodel
> parser so that onOpenXmlTag()/onCloseXmlTag() events are called in
> listeners). This is needed for point 7 below.
>

Hmm... Yes, I said that I'll do it. Technically it is simple (simpler than
to add "macro" blocks). But conceptually it breaks everything.
Explanations: Imagine that the listener already has the onOpenXmlTag(String
name, WikiParameters params)/onCloseXmlTag(String name) methods.
Then the text:
----------------------
<table>...

This is a content of the table

...</table>
----------------------

will be reported as following:
----------------------
- onBeginParagraph
- onOpenXmlTag: => "table"
- onEndParagraph

- onBeginParagraph
- onWord/onSpace => "This is a content of the table"
- onEndParagraph

- onBeginParagraph
- onCloseXmlTag: => "table"
- onEndParagraph
----------------------

It means that the calls onOpenXmlTag/onCloseXmlTag  will cross the borders
of multiple wiki paragraphs. And this is a BIG problem.
It means that we have to chose one of the following:
(A) Report HTML tags "as is" inside of wiki structural elements; In the
example above opening and closing "table" tags are reported in two separate
wiki paragraphs.
  pro: It is the simplest solution.
  con: if somebody want to treat these elements and create a well formed
document then it is up to the him/her to do it by hands and to ignore
non-appropriate structural wiki elements;
(B) Ignore wiki formatting inside of XML tags. In the example above all wiki
paragraphs will be skipped and only HTML "table" tags will be taken into
account; in this case WikiModel can not guaranties that each opening element
was really closed.
  pro: It is doable.
  con: a) It breaks completely the idea of the WikiModel - to give access to
a well-formed structure of wiki documents; b) the grammar will be bigger; c)
It is not so simple to implement
(C) Add some HTML tags as markup elements for the CommonSyntax. In this case
each '<table>...</table>' tag pair will be interpreted in the same way as
normal wiki tables. The same for "ol/ul/li/dd/dl/dt/p/span/div/..."
elements.
 pro: you can mix your wiki and HTML markup with the same meaning and all of
them will be reported in the same way to the listeners.
 con: a) the grammar will be bigger; b) I have to do much more additional
validations of documents by hand to guarantee that the document is
well-formed; c) the parsing will be much slower (as the consequence of a and
b); d) it is much more  difficult to implement; e) the number of possible
HTML elements have to be fixed in advance