Documentation Proposal: Documentation of all keywords used in string substiutions is needed

Motivation

I was working on implementing date formatting in the CalendarPlugin, allowing the user to specify whether they want the date to be like 3 Mar, or March 3, or whatever. But what keywords to use? It seemed reasonable to be consistent with something else, so I thought I would use the same keywords that the SpreadSheetPlugin uses in its FORMATTIME() function. But that got me to thinking that it would be nice to have some central place where I could look to see what $keyword substitutions where already used (and where). Having central documentation of these keywords would tend to prevent the same keyword from being used in different ways and from a proliferation of different keywords used for the same purpose.

Description

This documentation would show every $keyword that is used in text substitutions by any plugin, or built-in, function. It would also show what function(s) use that substitution and what the meaning of the substitution. Something like the following:

Hopefully, we could arrive at some way that this documentation would be automatically generated.

-- DavidBright - 24 Mar 2005

Impact

Documentation

Documentation in progress, before it is merged into the TWiki web.

Implementation

Any comments on how the documentation is written or could be improved

Discussion

Unfortunately documentation (valuable as it is) will not prevent clashes. It is also silly for everyone to implement this differently. The sensible way to address this problem would be to centralise support for the header, format, and footer parameters. I went some way towards creating an abstract base class for this in the FormQueryPlugin (TWiki::Plugins::FormQueryPlugin::TableFormat) though a better job could/should be done (maybe as a Contrib?)

-- CrawfordCurrie - 25 Mar 2005