Tags:
create new tag
, view all tags

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:

Keyword Effect Used by
$comma Replaced by a comma (",") %SEARCH%
$month Replaced by the two-digit month of the year %CALC% (FORMATTIME()), %CALENDAR%

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

-- DavidBright - 24 Mar 2005

Impact

WhatDoesItAffect: Vars, Search, Plugins
AffectedExtensions:  
HaveQuickFixFor:  

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

Edit | Attach | Watch | Print version | History: r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r2 - 2005-03-25 - 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.