• Do not register here on develop.twiki.org, login with your twiki.org account.
• Use View topic Item7848 for generic doc work for TWiki-6.1.1. Use View topic Item7851 for doc work on extensions that are not part of a release. More... Close
• Anything you create or change in standard webs (Main, TWiki, Sandbox etc) will be automatically reverted on every SVN update.
Does this site look broken?. Use the LitterTray web for test cases.

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".

TWikiVariables 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."

The TWikiFuncDotPm 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 TWiki::Func::expandCommonVariables (good) and TWiki::Func::registerTagHandler (not good)

I suggest to:

  • add a new TWiki::Func::registerVariableHandler
  • deprecate and undocument the TWiki::Func::registerTagHandler
  • consitently fix the pod doc "tag" ==> "variable"

Not sure if the term tag is used elsewhere in the doc.

This AppliesTo Engine and Documentation.

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

-- PTh

I'd prefer, if at all possible, renaming through all plugins and TWiki, every instance and deprecating the use of the term variable. 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.

-- MC

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".

My 2c.

-- PTh

This is a discussion we already had, and I changed all instances of tag for variable where I could find them. Unfortunately registerTagHandler 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.

Discarded. CC


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.

-- PTh

while we are both pedantic about consistency, there are a few more quality goals that over-ride it

  1. respect the decision of the release manager (that would be Crawford)
  2. respect the code freeze
  3. 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)

-- SD

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?

-- PTh

Re-opening this since no reply to my note on 13 Oct 2005.

-- PTh

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.

-- SD

Inconsistent use of TAG is fixed in SVN 7385.

-- PTh

ItemTemplate
Summary Inconsistent use of terms TAG and VARIABLE
ReportedBy PeterThoeny
AppliesTo Engine
Component

Priority Normal
CurrentState Closed
WaitingFor

Checkins 7385 7386
Edit | Attach | Watch | Print version | History: r10 < r9 < r8 < r7 < r6 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r10 - 2005-11-09 - PeterThoeny
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2019 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback