The official term for %SOMETHING% is "variable", not "tag". The term tag is more commonly used by programmers and HTML coders, but most end users are more familiar with the term "variable".
defines a variable as: "Special text strings expand on the fly to display user data or system info", and "TWikiVariables are text strings - %VARIABLE% - that expand into content whenever a page is rendered for viewing. VARIABLES are replaced by data, either user-entered or automatically generated by TWiki (like the date, or the current username). There are predefined variables, and Preference variables that you can configure. You can also define custom variables, with new names and values."
mixes both terms together. This is confusing. Unfortuantely it is not just a documentation question, new function names use the term "tag". So we have now
I suggest to:
- add a new
- deprecate and undocument the
- consitently fix the pod doc "tag" ==> "variable"
Not sure if the term tag is used elsewhere in the doc.
This is a typical case where a tech-writer could offload the developers with the details like using consistent terminologies and authoring content in line with the TWiki:TWiki.TWikiDocsStyleGuide
I'd prefer, if at all possible, renaming through all plugins and TWiki, every instance and deprecating the use of the term
. Its too narrow a term for the use we put it too.
Tag is more general and better includes outputs that depend on inputs, i.e. functions. Variables are not functions. In fact, ideally I'd call them functions, or something similar.
Just my 2c.
Martin, for the sake of argument, picture yourself as marketing manager Mike who has never seen raw html and has no programming experience. Now re-read the definition of variable stated above. From Mike's perspective, TWiki is like a word processor where he can put the marketing material. Just text and images. Now he is wondering if he can automate some stuff. "Oh, I can use variables to include another page, nice! Oh, I can create text on the fly with a SEARCH! Oh, I can create a table of content automatically!"
From this perspective the term variable might be a bit less narrow than "tag".
This is a discussion we already had, and I changed all instances of tag for variable where I could find them. Unfortunately
was already committed at that time, but I felt we should be able to survive. The sort of people who write plugins should be able to make the connection, especially given the clear documentation of the handler. I really don't think it is worth the risk at this stage to change a function name that may impact an unknown number of plugins.
Reopening it for three reasons:
- TWik.TWikiFuncDotPm has around 30 instances of "tag"
- I do not see any danger in adding
TWiki::Func::registerVariableHandler that does simply call
TWiki::Func::registerTagHandler. (registerTagHandler can be retired and undocumented but should be retained)
- Other TWiki topics should be scanned for "tag" vs "variable"
Consistency is one aspect of quality. My simple goal here is to provide high quality docs.
while we are both pedantic about consistency, there are a few more quality goals that over-ride it
- respect the decision of the release manager (that would be Crawford)
- respect the code freeze
- don't hold up the release, without one, there is no quality at all.
as you can see from the rdiff history bug, every change as flow on effects, all of which we are trying to avoid (and one of them, is demoralising the people that have done so much work, by moving the goal posts)
I am respecting the code freeze. Any spec change should go through the CCRB
, and then pass the "Peter test".
I am working several hours a day for the last few weeks, trying to help get the release out as soon as possible with the quality our customers expect. Just for the records.
OK, since it is that late in the game, we can simply keep the function name as is, and fix the docs (30 instances in TWik.TWikiFuncDotPm and possible more in other topics). That does not introduce side-effects. OK?
Re-opening this since no reply to my note on 13 Oct 2005.
re-discarding as insufficiently important to keep comming up. If you want to make it happen, do it. I don't see it important enough for me to do it, CC obviously discarded it for the smae reason. I don't really have time to keep re-examining somthing like this.
Like all issues, if you think its important, and no-one else does, then you
have to do it, or realise that it is
unimportant - thats OSS for you.
Inconsistent use of TAG is fixed in SVN 7385.