Content
View differences
Updated by Carsten Klein over 9 years ago
The goal of this feature request is to establish a new and more capable notation format for wiki macros.
As discussed with Oliver Guenther the other day, the current syntax has some problems that need to be addressed first prior to implementing new features such as
- \#\#24283
and also for making the implementation of such features both more easier and more performant.
## Current Limitations
### AngularJS / Wiki macro syntax clash
The current wiki macro syntax is similar to the syntax used for AngularJS macro expressions.
**AngularJS**
<macro class="foo"></macro>
**Wiki Macro Syntax**
<macro class="toc"></macro>
This basically means that all such macros and whenever they could not be evaluated on the server due to a typo or even a missing macro, need to be escaped so that AngularJS in the front end will not itself try to expand such macros. This
leads to a currently implemented work around that will replace all occurrences of the double curly brace at the beginning of a macro with an AngularJS expression that will then reinsert the double curly braces during rendering on the client.
The downside of that work around is, that one cannot use AngularJS macro expressions anymore as these will always be escaped, limiting our future requirements which might require the use of AngularJS macro expressions.
E.g.
<macro class="macro"></macro>
will be replaced by something like
{{root.DOUBLE_CURLY_BRACE}}macro}}
which will then be interpreted by AngularJS and expanded again to the following
<macro class="macro"></macro>
These additional processing steps are redundant and could be eliminated by introducing a different macro syntax, both giving a slight performance increase and also better readable and more maintainable code in the back end.
### Recursive macro processing
\#24283 introduces additional blocks of character data being passed to the macro for internal processing by the macro. This leads to some edge cases where macros that allow wiki syntax in their parameter will require recursive parsing of the syntax tree.
E.g.
{{macro
**Markup**
<macro class="macro1"></macro>
}}
While part of this has already been solved, it is still not sufficient and prone to error.
### Macro Parameterization
While the current syntax allows the user to pass additional parameters to a macro, this scheme does become unreadable/unmaintainable as soon as multiple parameters needs to be passed to the macro as all parameters need to be noted on the same line, e.g.
<macro class="macro"></macro>
The first issue here is that all parameters need to be passed on the same line, not allowing the user to add additional line breaks. Second, one cannot include **comma** in the parameters as this will break the parser. Third, having to use escape syntax for line breaks is counter intuitive and leads to unreadable markup.
## New Syntax Proposal
<PREFIX:NAME [param|param="..."]*>
<![CDATA[ ... ]]>
</PREFIX:NAME>
or the short form if no additional CDATA needs to be passed
<PREFIX:NAME [param|param="..."]*/>
The new syntax proposal is based on a (X)HTML notation for the wiki macros.
So instead of the old
<macro class="toc"></macro>
one must use
<opf:toc/>
instead.
While this may seem to be overkill for simpler macros, it definitely has its benefits when it comes to recursive macro processing and also with macros requiring multiple parameters. For the latter, it will help make the wiki markup more readable and maintainable by the author. And it will also help clean up code of the parser, making it more simple.
However, and since we need to remain backwards compatible, an additional pre processing step needs to be introduced, that will translate all existing macro calls to the new format prior to actually processing the wiki markup.
### XML NS Prefixes
We will introduce support for XML NS Prefixes so that wiki macro authors can reuse existing macro names by prefixing these using a different XML NS Prefix.
E.g.
<opf:toc/>
<my:toc/>
While **opf:toc** would refer to the built-in table of contents macro, **my:toc** would refer to a table of contents macro that is provided by a third party.
These XML NS Prefixes will be established during runtime macro registration.
#### Reserved Prefixes
The following XML NS Prefixes will be reserved
- **opf** - reserved to the Open Project Foundation
## Required Changes to the Text Formatting / Wiki Parser
TBD
## Required Changes to the Wiki Macro API
TBD
## Macros with only Positional Parameters or Mixed Positional and Named Parameters
The new approach relies on named parameters only. It has no support for unnamed and purely positional parameters. Extra care must be taken for such macros during both the pre-processing stage and when invoking these macros. A simple wrapper for such macros could be devised that will hide away the underlying implementation while during the pre-processing stage, all positional parameters will be assigned a name such as **param0** through **param<N>**.
## Migrating Existing Wiki Pages
TBD
As discussed with Oliver Guenther the other day, the current syntax has some problems that need to be addressed first prior to implementing new features such as
- \#\#24283
and also for making the implementation of such features both more easier and more performant.
## Current Limitations
### AngularJS / Wiki macro syntax clash
The current wiki macro syntax is similar to the syntax used for AngularJS macro expressions.
**AngularJS**
<macro class="foo"></macro>
**Wiki Macro Syntax**
<macro class="toc"></macro>
This basically means that all such macros and whenever they could not be evaluated on the server due to a typo or even a missing macro, need to be escaped so that AngularJS in the front end will not itself try to expand such macros. This
leads to a currently implemented work around that will replace all occurrences of the double curly brace at the beginning of a macro with an AngularJS expression that will then reinsert the double curly braces during rendering on the client.
The downside of that work around is, that one cannot use AngularJS macro expressions anymore as these will always be escaped, limiting our future requirements which might require the use of AngularJS macro expressions.
E.g.
<macro class="macro"></macro>
will be replaced by something like
{{root.DOUBLE_CURLY_BRACE}}macro}}
which will then be interpreted by AngularJS and expanded again to the following
<macro class="macro"></macro>
These additional processing steps are redundant and could be eliminated by introducing a different macro syntax, both giving a slight performance increase and also better readable and more maintainable code in the back end.
### Recursive macro processing
\#24283 introduces additional blocks of character data being passed to the macro for internal processing by the macro. This leads to some edge cases where macros that allow wiki syntax in their parameter will require recursive parsing of the syntax tree.
E.g.
{{macro
**Markup**
<macro class="macro1"></macro>
}}
While part of this has already been solved, it is still not sufficient and prone to error.
### Macro Parameterization
While the current syntax allows the user to pass additional parameters to a macro, this scheme does become unreadable/unmaintainable as soon as multiple parameters needs to be passed to the macro as all parameters need to be noted on the same line, e.g.
<macro class="macro"></macro>
The first issue here is that all parameters need to be passed on the same line, not allowing the user to add additional line breaks. Second, one cannot include **comma** in the parameters as this will break the parser. Third, having to use escape syntax for line breaks is counter intuitive and leads to unreadable markup.
## New Syntax Proposal
<PREFIX:NAME [param|param="..."]*>
<![CDATA[ ... ]]>
</PREFIX:NAME>
or the short form if no additional CDATA needs to be passed
<PREFIX:NAME [param|param="..."]*/>
The new syntax proposal is based on a (X)HTML notation for the wiki macros.
So instead of the old
<macro class="toc"></macro>
one must use
<opf:toc/>
instead.
While this may seem to be overkill for simpler macros, it definitely has its benefits when it comes to recursive macro processing and also with macros requiring multiple parameters. For the latter, it will help make the wiki markup more readable and maintainable by the author. And it will also help clean up code of the parser, making it more simple.
However, and since we need to remain backwards compatible, an additional pre processing step needs to be introduced, that will translate all existing macro calls to the new format prior to actually processing the wiki markup.
### XML NS Prefixes
We will introduce support for XML NS Prefixes so that wiki macro authors can reuse existing macro names by prefixing these using a different XML NS Prefix.
E.g.
<opf:toc/>
<my:toc/>
While **opf:toc** would refer to the built-in table of contents macro, **my:toc** would refer to a table of contents macro that is provided by a third party.
These XML NS Prefixes will be established during runtime macro registration.
#### Reserved Prefixes
The following XML NS Prefixes will be reserved
- **opf** - reserved to the Open Project Foundation
## Required Changes to the Text Formatting / Wiki Parser
TBD
## Required Changes to the Wiki Macro API
TBD
## Macros with only Positional Parameters or Mixed Positional and Named Parameters
The new approach relies on named parameters only. It has no support for unnamed and purely positional parameters. Extra care must be taken for such macros during both the pre-processing stage and when invoking these macros. A simple wrapper for such macros could be devised that will hide away the underlying implementation while during the pre-processing stage, all positional parameters will be assigned a name such as **param0** through **param<N>**.
## Migrating Existing Wiki Pages
TBD