Tags:
archive_me1Add my vote for this tag documentation1Add my vote for this tag create new tag
, view all tags

Feature Proposal: Clean up the docs in TWiki.TWikiVariables

This is an offspring of Bugs:Item893, where the suggestion to radically split TWikiVariables got some support, though changes of that kind are no longer an option for DakarRelease.

Motivation

TWikiVariables is way too large, and still does not cover all documentation of the TWiki-=%KEYWORD%=s. In particular, all preferences (which are variables, after all) and all keywords introduced by plugins are missing. New users are having a hard time figuring out what some %KEYWORD% does if they stumble across it in a topic.

Description

Give the user / author a clear reference style manual about all available TWikis variables and functions, with an access to the information as easy as man INCLUDE would be. Group functions according to their usage, and not according to their implementation.

Things written as %KEYWORD{...}% are called "variables", but for many of them the term simply doesn't fit. TWiki has:

  • Simple scalar readonly variables. Examples: %ACTIVATEDPLUGINS%, %SERVERTIME%.
    • Well, they actually aren't readonly. If I want, I can set %GMTIME% in a topic.
  • Variables resembling Perl's hashes. Example: %HTTP{"User-Agent"}%.
  • Preferences which are intended to be set in topics and which are typically evaluated by TWiki. Example: %ATTACHFILESIZELIMIT%, %SKIN%, %ALLOWTOPICCHANGE%. The latter isn't documented in TWikiPreferences, though.
  • Macros, i.e. shortcuts which save some typing. Example: %TOPICURL%. Feel free to rollout your own.
  • Labels defining locations in the topic. Example: %SECTION{"Description"}%, %STOPINCLUDE%
  • Simple functions which operate on user-specified data. Example: %ENCODE{"File Name With Spaces"}%
  • Complex functions which expand to text defined elsewhere. Examples: %INCLUDE%, %SEARCH%.
  • Complex functions which operate on the following text. Example: %TABLE%

Given this variety, much of the text in the introduction to TWikiVariables is somewhere between misleading and plain wrong. Two stunning examples: The subtitle of TWikiVariables says "Special text strings expand on the fly to display user data or system info", and there is no overlap between the variables expanded by %ALL_VARIABLES% and the variables documented in TWikiVariables.

-- HaraldJoerg - 22 Nov 2005

Impact and Available Solutions

Documentation

Like you'd say man INCLUDE if TWiki were a shell, it should be possible to type some incantation like TWiki.TWikiVariablesINCLUDE into the Go box and immediately get the description of the keyword %INCLUDE%. The same would hold for all "variables" provided by plugins, e.g. %TABLE{...}%, hereby removing the different access to docs for the core and for the plugins.

A list of all variables could be obtained by %SEARCH{topic="TWikiVariable*" ...}%, possibly grouped according to the categories listed in the motivation.

Implementation

Implementation is yet to be investigated.

  • A radical split of TWikiVariables into dozens of separate topics would be straightforward, but clobber the TWiki web even more than it already is.
  • A hierarchical web would come in handy, but this feature is optional, and still somewhat experimental in Dakar.
  • ... to be continued ...

Discussion:

Having a heirarchical web for documentation is something I would consider a Good Thing®. But it could also be a hidden web so as not to intrude.

-- AntonAylward - 23 Nov 2005

I'd like to ask that this idea please be given some time - my miniesit implementation has given me some interesting insites - that i don't have together here in Rome - they are on my computer back in zurich

i will be back online in december

-- SvenDowideit - 25 Nov 2005

I think december is still in time for EdinburghRelease wink

-- HaraldJoerg - 25 Nov 2005

ah, yes, i totally forgot about this frown

the crux of the idea is to make the TML spec fully defined in the code, in a structured perl way, so that RegisterTags requires the full documentation to be passed to it.

Thus TWiki would know and be able to verify the params that are legal, contraints and typing on those parameters, and the documentation for each.

Then when you enable/disable functionality in configure, this information can be collated to create a documentation set that is correct and complete for that particular TWiki install. The same thing can happen for Plugins.

This would systemize PluggableDocumentationArchitecture, and make validation, and upgrade of TML possible.

-- SvenDowideit - 21 Feb 2006

Good move to split up the TWikiVariables into one topic per variable!

On variables introduced by topics, this can be extended simply by packaging documentation topics with the Plugin. For example the SpreadSheetPlugin can ship with a TWiki.VarCALC topic that gets picked up automagically if the Plugin is installed. Same for contribs.

-- PeterThoeny - 27 Feb 2006

That was the whole point..... wink

-- CrawfordCurrie - 27 Feb 2006

In this case I do not understand the need for passing the full documentation to the register tag function.

-- PeterThoeny - 27 Feb 2006

I guess it's so the documentation can be generated on the fly. I'm not at all keen on that, because it bloats the image. I think the "one topic per variable" approach works just fine, as the topics will only be created if the module that implements the tag is installed.

Of course there might be several implementations of the same tag available, in which case choosing between them gets tricky....

-- CrawfordCurrie - 27 Feb 2006

Seems like there should be a more effective approach than creating one topic per variable! Some plugins have multiple variables. BlogPlugin (as a random example), has 6 variables. Breaking that out into six separate topics appears to me to be sacreficing usability for the sake of easier code.

How about creating a standardized format for documenting the variable such that they can all be extracted using a search. Being able to further optimize and manipulate the results of that search is another example of why i think we need DynamicDataSets.

-- LynnwoodBrown - 27 Feb 2006

Re Crawford: True. If a TWiki installation has two competing implementations of, say, a login manager defining the variable %USERNAME% installed, then of course only one of them can claim the TWiki.VarUSERNAME topic, and it would better be the one which is enabled (if any), or the user might by slightly confused. Yet, whatever ugly solution comes into mind, there is little to lose if we compare this with today's plugin documentation model: Today two plugins can independently implement the variable %USERNAME%, and a poor user seeking the explanation for that variable would not only have to find the plugin topic(s) containing the variable, but also to consider the sequence of plugin evaluation to get to the right topic.

I think that Codev needs to become a place of arbitration for plugin variables, to avoid as many problems with conflicting variables as possible. If a conflict with e.g. %USERNAME% becomes visible in codev, maybe we need to define another meta-topic TWiki.VarUSERNAME, which in turn contains an intelligent search for all topics beginning with VarUSERNAME, like VarUSERNAMEbyMyVeryStrangeLoginManager. Or maybe we need a better idea wink

Re Lynnwood: I don't think that we're sacrificing usability at this stage. The BlogPlugin is highly encouraged to list all its variables (which it should know pretty well) in its topic. But it is no difference if it does it explicitly, or as %INCLUDE{"VarCITEBLOG"}% etc. Only that soneone stumbling over a %CITEBLOG{}% can get accustomed to look for a topic VarCITEBLOG instead of divining the name of the plugin which defines the variable.

I'd even propose that each of the six variable topics defined by BlogPlugin starts with a line "Defined by BlogPlugin" - outside the %STARTINCLUDE% / %STOPINCLUDE% block (Think of Apache's doc: Every variable in defined by e.g. mod_access explicitly contains a line Module: mod_access, though they are all collected in one large file mod_access.html).

I don't object at all against DynamicDataSets, and if we have them, we can make use of them. However, I think that the priority of a better documentation is high enough to look for a solution even if we don't get DynamicDataSets in EdinburghRelease.

-- HaraldJoerg - 27 Feb 2006

One topic per variable is the right thing. Why? Because then pages like VariablesForDummies can be written and include only the ones that dummies can understand.

-- MeredithLesly - 05 Mar 2006

Why make these pages VarSOMETHING, why not just use the variable name as the page name, e.g. SOMETHING?

Assuming the flow of topics from TWiki.org into SVN now works, what's to stop us refactoring the variables in the TWiki web now?

-- MartinCleaver - 05 Mar 2006

Not to mention that they should be self-documenting

-- MeredithLesly - 13 Apr 2006

DONE though the worm continues to squirm; see OrganizeTWikiVariables

-- CrawfordCurrie - 07 Jul 2006

Edit | Attach | Watch | Print version | History: r16 < r15 < r14 < r13 < r12 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r16 - 2006-07-07 - 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.