Blocks And Inconsistent TML

This topic tries to give the overview of syntax used in TWiki Core and in many of the Plugins for surrounding a section.

It is not really meant to be a discussion. More an overview or background topic to help the discussion in other Codev topics and some bugs items as well.

What this topic shows is

• The Core both uses more than one syntax
  • STARTINCLUDE - STOPINCLUDE
  • STARTSECTION - ENDSECTION
  • COLOURNAME - ENDCOLOR
  • <verbatim> - </verbatim>
  • <noautolink> - </noautolink>

• The default plugins uses both START/STOP and START/END syntax
• The many other plugins uses both START/STOP and START/END syntax
• Very few plugins have invented their own syntax like xml look-alike tags or even more special syntax
• STOPSOMETHING is not significantly more popular than ENDSOMETHING

So what does that tell us?

• The rule currently is that there is really no rule.
• We cannot possibly deprecate normal syntax used by everyone like verbatim, noautolink etc. They will have to live on forever because otherwise we will prevent existing TWiki users from ever upgrading TWiki.
• We should not deprecate other core syntax if the only reason is to make everything consistant. It will be a pain to everyone and harm more than it helps.
• We cannot possibly duplicate all the occurances of END as STOP without also including plugins.
• If we follow the proposal that some variables should work both with STOP and END to help users so they do not have to look up in the documentation, then that must mean that all that kind of TWikiVariables surrounding a block must work with STOP and END. This becomes a ridiculous mess. And doing it only partly is for sure going to be even more confusing to the users.

What does KennethLavrsen think we should do?

• In core/default plugins - nothing to the existing. No deprecation of syntax. No duplicate syntax. Decisions were made after long discussions. Let us stick to it and just recognize that TWiki TML is not 100% consistent.
• In core/default plugins - agree that future features uses START and STOP based on the fact that END is not language wise the correct antonym to START. It is START vs STOP and BEGIN vs END. And that was for future new features only.
• In plugins. Leave it to the plugin authors. If they all start changing their syntax now - it will be a real mess for many users using the plugins. I would leave it as is.
• There are only very few plugins that uses syntax that is not TWikiVariables with START/STOP or START/END but instead uses xml look alike. Here I would make those 2-3 plugins so they also use the TWikiVariable syntax and I would leave a compatibility mode which can be configured on for old installs and off for new.

Below I walk through what I have found of different ways to tag around a block or section - after hours of searching. And please note - Kenneth does not recommend to change everything as shown in the rest of this topic. On the contrary. The purpose is to show that it makes little sense to even try.

The proposal - always use %STARTSOMETHING% ... %STOPSOMETHING%

The following is a walkthrough of core code and many many plugins. I may have missed a few but I tried to find all those that uses a syntax to surround a block of text.

Opening/closing keywords in TML

Sections in Core

Currently defined as (for plugins using section see plugins later in this topic)

%STARTSECTION% ... %ENDSECTION%

if we also want the STOP syntax we would need to also understand

%STARTSECTION% ... %STOPSECTION%

Colours - defined in TWikiVariables but to the user they are TML

Currently defined as

%COLORNAME% ... %ENDCOLOR%

if we also want the STOP syntax we would need to also understand

%COLORNAME% ... %STOPCOLOR%

Include - core

Currently defined as

%STARTINCLUDE ... %STOPINCLUDE%

but if we let the above work with END so should this which would mean we would have to also understand.

%STARTINCLUDE ... %ENDINCLUDE%

AttachContent (a new plugin suggested used for e.g. user defined CSS)

The TWiki:Plugins.AttachContentPlugin uses

%STARTATTACH{"filename"}% ... %ENDATTACH%

This would have to be changed to also accept

%STARTATTACH{"filename"}% ... %STOPATTACH%

SlideShowPlugin (a default plugin)

Currently defined as

%SLIDESHOWSTART% ... %SLIDESHOWEND%

This would have to be changed to also accept

%STARTSLIDESHOW% ... %STOPSLIDESHOW%

TWistyPlugin (now a default plugin)

Currently defined as something similar to the colours in core.

%TWISTYTOGGLE{}% ... %ENDTWISTYTOGGLE%

and

%TWISTY{showlink="Show..." hidelink="Hide"}%
...
%ENDTWISTY%

This would have to be extended to also understand

%STARTTWISTYTOGGLE{}% ... %STOPTWISTYTOGGLE%

and

%STARTTWISTY{showlink="Show..." hidelink="Hide"}%
...
%STOPTWISTY%

AliasPlugin

Currently defined as

%STARTALIASAREA% ... %STOPALIASAREA%

but poor users. If so many of the other plugins and core tags understand END and you are used to that isn't that sad? Let us make the plugin also understand

%STARTALIASAREA% ... %ENDALIASAREA%

BibtexPlugin

Uses today start and stop.

%STARTBIBTEX{<attributes>}% ... %STOPBIBTEX% 

shouldn't we give the poor users the choice of

%STARTBIBTEX{<attributes>}% ... %ENDBIBTEX% 

FilterPlugin

Uses start and stop

%STARTSUBST{...}% ... %STOPSUBST%
%STARTEXTRACT{...}% ... %STOPEXTRACT%

should we be kind and add in addition

%STARTSUBST{...}% ... %ENDSUBST%
%STARTEXTRACT{...}% ... %ENDEXTRACT%

HideInEditModePlugin

Back to using END.

%STARTHIDDEN% ... %ENDHIDDEN%

which according to the new world order must be understanding

%STARTHIDDEN% ... %STOPHIDDEN%,

PublishContrib and PublishWebPlugin

Back to START STOP

%STARTPUBLISH% ... %STOPPUBLISH% 

which should be extended to also understand

%STARTPUBLISH% ... %ENDPUBLISH%

SnibPlugin

No beginning without an ENDing.

%STARTSNIB{ALLOWVIEW="Main.IanBygrave" ALT="I love fluffy kittens!!!"} 
My plans for world domination: 
Buy a white cat, 
%ENDSNIB%

which should be changed to

...
%STOPSNIB%

Opening/closing keywords in HTML like syntax

Verbatim - core

Currently defined as

<verbatim> and </verbatim>

If we go through changing everything consequently this should in addition also work as

%STARTVERBATIM% ... %STOPVERBATIM%

Autolink

Currently defined as

<autolink> and </autolink>

If we go through changing everything consequently this should in addition also work as

%STARTAUTOLINK% ... %STOPAUTOLINK%

MultiEditPlugin

uses

<section> and </section>

as already discussed that should perhaps be

%STARTSECTION{type="edit"...}% ... %STOPSECTION{type="edit"...}% 
 

as well as

%STARTSECTION{type="edit"...}% ... %ENDSECTION{type="edit"...}% 

or should it actually use the core defined sections?

SectionalEditPlugin

Uses very unique to TML tags like

<sectionbreak/>
<editsections/>
<sectionedit> ... </sectionedit>

which should be changed to real TML

%SECTIONBREAK%
%EDITSECTIONS%
%STARTSECTION{type="edit"...}% ... %ENDSECTION{type="edit"...}%
or
%STARTSECTIONEDIT% ... %STOPSECTIONEDIT%
and maybe ín addition
%STARTSECTIONEDIT% ... %ENDSECTIONEDIT% or
%STARTSECTION{type="edit"...}% ... %STOPSECTION{type="edit"...}%

"Here document" like syntax

Action tracker

Not a core tag or default plugin but since some think we need to harmonize the plugins as well then let us pull the sleeves up and go to work.

%ACTION.. tag uses a perl nerdiness today

% ACTION{ who="LittleOysters" due="2 Jan 1884" state="open" }% <<EOF
The time has come, the walrus said
EOF

The action tracker tag could, of course, be more consistent as follows

%STARTACTION{ who="LittleOysters" due="2 Jan 1884" state="open" }%
The time has come, the walrus said
%STOPACTION%

Multiple sections bracketed by keywords

IfDefinedPlugin

Another interesting set of variations is exemplified in IfDefinedPlugin, which resurrects the spirit of some really old programming languages (as well as shells):

%IFDEFINEDTHEN{"test" [action="view,edit,preview,..."]?}% 
  <then content> 
[%ELSIFDEFINED{...}% 
  <elsif content>]* 
[%ELSEDEFINED%
  <else content>]?
%FIDEFINED%

Note yet another block ending construct...

Unique syntax inventions

GenPDFAddOn

Oh dear. New syntax

<!-- PDFSTART --> .. <!-- PDFSTOP --> 

That should have to be extended to

%STARTPDF% .. %STOPPDF%

EndNotePlugin

A new syntax

{{ note text }}

Wow. And already discussed on the EndNotePluginDev. Topic. Ready for a new holy war.

You know what the alternative should be by now.

RecursiveRenderPlugin

Also uses the very unique xml type tags and yet another new invention ~macro and ~~

<render> ... </render>
~macro ... ~~

Again changing to TML

%STARTRENDER% ... %STOPRENDER%
%STARTRENDERMACRO% ... %STOPRENDERMACRO%

or for the first some may suggest

%STARTSECTION{type="render"...}% ... %STOPSECTION{type="edit"...}%
%STARTSECTION{type="render"...}% ... %ENDSECTION{type="render"...}%

Again I want to repeat. KennethLavrsen does not propose that we change all of this. It will be a totally messy, confusing, performance killing, silly thing to do.

As I made this overview I became convinced that it is best not to change things like ENDSECTION to also work with STOPSECTION. Since we cannot do such thing consistantly - we'd better not do it partly - and confuse our users even more. To them this is just one of hundreds of TWikiVariables.

-- Contributors: KennethLavrsen, ThomasWeigert - 29 Oct 2006

Discussion

Ken, thanks. This is a great summary.

Reading all this makes me cry... I have spent much of my earlier life in language design and have been through the many ups and downs of religious wars over syntax leading several language standardizations. (I am still active in UML standardization - responsible for the common behavior and internal structure portion of the language - as well as SDL.)

But that experience has taught me that a good syntax makes using a language easy; a bad syntax makes it very hard. Backwards compatability is way overrated as a value, in my experience. Usability is usually underrated.

-- ThomasWeigert - 30 Oct 2006

In the refactoring Thomas added pre and literal. They are not TML defined. They are normal HTML and has nothing to do with TWiki as such since TWiki will pass on any HTML anyway. We could add a lot of html tags like <p> .. </p>, <li> .. </li> etc etc but that distorts the original purpose of this topic which was to give an overview of what TWiki and its plugins has defined.

-- KennethLavrsen - 30 Oct 2006

I added pre and literal because there is special code in TWiki core (see TWiki/Render.pm) to deal with these. My assumption is that if they are manipulated in some way by twiki, then the tags are TWiki tags, whether they have meaning outside of TWiki or not...

-- ThomasWeigert - 30 Oct 2006