Tags:
create new tag
, view all tags

Feature Proposal: HTML is HTML, and TWiki is TWiki

Motivation

TWiki is too confusing. People with a background in documentation, especially HTML or XML-based, are sometimes startled by things which are processed by TWiki but are no TWiki variables. Documentation of these tag-like thingies is not where one would look for them.

Description and Documentation

Replace all pseudo-HTML elements of TWiki (e.g. <verbatim>) by "real" TWiki syntax (e.g. %VERBATIM%)

Examples

<verbatim> Verbatim text <verbatim>
<literal>Literal Text</literal>
<noautolink>FlexFrame</noautolink>
<render>   * List item</render>variables
<nop>

Impact

WhatDoesItAffect: Rendering, Vars
A better question is: "what does it not affect?"

Implementation

Maybe simple cases are as easy as

   * Set VERBATIM = <verbatim>
   * Set ENDVERBATIM = </verbatim>
%VERBATIM%
This is not a TWikiLink, nor is that a %TWIKIVAR%.
%ENDVERBATIM%

I didn't try, and I don't trust these things which may break XHTML well-formedness.

In addition, it is too clumsy and is creating too much variables. As soon as the tags want attributes (like XML tags can have) the preferences approach will fail.

Thinking about the taxonomy of these things (and some TWiki variables as well), and comparing toLaTeX or XML, I found that they somehow resemble LaTeX's environments or XML's processing instructions. They are commands for the formatter, not content. %STARTSECTION{...}% would be a TWiki variable in a similar category.

In both LaTeX and XML, their processing instructions / environments are syntactically similar to their other language constructs:

  • LaTeX has environments like \begin{minipage} ... \end{minipage}, like its other \command{attribute} syntax, where TWiki's Plugins.RecursiveRenderPlugin says XML-like <render> ... </render>.
  • XML accepts tag-like <?dbfo ... ?> where it can trigger a Docbook formatter to do special things e.g. to tables when creating PDF, comparable to TWiki's formatting attributes in %TABLE{...}%.

Note, by the way, that TWiki has quite a couple of implicit "environments". Simply look at the rendering code, which takes some effort to determine the borders:

  • TWiki's table environment starts implicitly with something that looks like a table row (maybe preceded by a %TABLE{...}% or %EDITTABLE{...}% variable, and ends with, well, something that does not look like a table row. No chance for a nested table with that.
  • TWiki's list environments starts with three spaces (or a tab, historically), a number, asterisk or dollar, and again ends with a line which looks like it wouldn't belong to a list.

There may be some pitfalls because this approach might blur the distinction between variable expansion and formatting even further than it is today.

Syntax Alternatives

I recall a heavy discussion in IRC about STARTFOO vs. BEGINFOO or ENDBAR vs. STOPBAR, and TWiki seems to have accumulated all of them in the past. Recalling LaTeX once more, I started to think about another idea - just given as examples here:

%START{"verbatim"}%
   Verbatim Text, regardless of %TWIKIVARS% or <xml /> elements
%END{"verbatim"}%
%START{"noautolink"}%
   CamelCase happens to occur everywhere these days.
%END{"noautolink"}%
%START{"section" name="why not"}%
   Not much uglier than the current =%<nop>STARTSECTION%= variable.
%END{"section"}%

| An implicit table |  %START{render}%
   * This would be a list
   * within a table element
%END{render}% |

Documentation of all of these would begin in TWiki.VarSTART, which is a good thing since many of these types of blocks may share attributes with equal meaning (e.g. name), and it is a bad thing since we do not really have a pluggable documentation architecture where a plugin like RecursiveRenderPlugin could deliver documentation for %START{"render"}%. A subroutine for %START{"blue"}% could, unlike a preference variable, detect whether a <font ...> tag is appropriate, or whether it should be a <div ...> instead.

Another option would be to have separate variables for every environment. This would allow to avoid the negationism: Instead of <noautolink>...</noautolink> one could write %AUTOLINK{off}%...%AUTOLINK{on}% This is a good thing because every environment would have its specific documentation topic, and a bad thing since syntax and semantics of attributes will soon diverge.

-- Contributors: HaraldJoerg - 29 Jun 2007

Discussion

Yep, absolutely agreed about the bastardised XML tags. Fortunately all browsers and HTML parsers (though not RSS) seem to be tolerant to unrecognised tags. However I have also always felt deeply uncomfortable about <verbatim>.

Technical issues

One potential problem here is the same one that always plagues TML; order of evaluation. The "simple case" example you give above, which does a * Set VERBATIM = <verbatim> won't actually work, because by their nature, verbatim and literal blocks have to be protected from any further TML interpretation as early as possible. What you have written is effectively:
 * Set VERBATIM =
<verbatim>
 * Set ENDVERBATIM =
</verbatim>
which is not what you intended. A possible advantage of the bastardised TML syntax is that it can be recognised and removed from the text very early in the TML rendering process. A START/END SECTION type of tag would also require as-early-as-possible evaluation, with the added burden that (unlike the XML-style tags) the syntax isn't recognisable using a simple RE. I don't think this problem is insurmountable, however.

Right now structural sections are only "parsed" during INCLUDE and template topic instantiation, and there has always been a strong argument that we should move section processing into the general tag parser. Aside from anything else, I have wanted something like %IFSECTION{"..."}%  ... %ELSESECTION% ... %ENDIFSECTION% for ages, and it would have to be addressed at the same point in the TML cycle as the proposed verbatim and literal tags. I have avoided doing this refactor in the past because TWiki has subtle and extremely complex semantics, that depend heavily on the order of evaluation during rendering.

This takes us to an approach where there are two types of TWiki tag; inline tags (the existing type) and structural tags, such as STARTSECTION..ENDSECTION, IFSECTION..ENDIFSECTION, VERBATIM..ENDVERBATIM etc. From a technical perspective, rules for parsing structural tags have to be quite different to the simplistic inside-out-left-right rule that governs tag expansion at the moment, and this IMHO represents the major technical challenge. However the appeal of being able to let plugin authors declare structural tags is considerable.

Usability Issues

What impacts would this have on end users?
  1. Potential changes to the semantics of verbatim blocks
    • Addressed by deprecating, but not removing, the existing tags
  2. Plugins use <verbatim>
    • There are probably some, but any properly maintained plugin will use the handler interfaces that already manage verbatim removal. Plugins that don't use these interfaces can be rated accordingly.
  3. Clumsy syntax
    • <verbatim> is actually quite terse and easy to type; whatever replaces it must also be simple.

-- Main.CrawfordCurrie - 30 Jun 2007

ChangeProposalForm
TopicClassification FeatureRequest
TopicSummary HTML is HTML, and TWiki is TWiki
CurrentState UnderInvestigation
CommittedDeveloper

ReasonForDecision None
DateOfCommitment

ConcernRaisedBy

BugTracking

OutstandingIssues Awfully many!
RelatedTopics

InterestedParties

ProposedFor

TWikiContributors

Edit | Attach | Watch | Print version | History: r3 < r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r3 - 2007-06-30 - CrawfordCurrie
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.