create new tag
, view all tags

Include should (but doesn't) include the stuff in settings

From my reading of the code, nothing in settings is included in a topic. This is a serious problem since

   * Set FOO = Bar

should work the same whether it's in the topic text or the settings area.

-- Contributors: MeredithLesly


I realise that there are issues regarding %STARTINCLUDE% and %STOPINCLUDE%, and don't know what the right answer is there

-- MeredithLesly - 13 Jul 2006

Hmmm. An interesting point. I think the original idea of settings was that they should apply when the topic containing them is being viewed. Certainly that's how access controls are interpreted. The access controls on an included topic are indeed used to determine if that topic can be included; but those access controls cannot then apply to the including topic, for obvious reasons (example; a topic includes two other topics with conflicting access controls. example: included topic expresses weaker access controls than including topic).

As for other variables; all I can say is "it has always worked that way", so it can't be classed as a bug, you are requesting a spec change. I have modified your entry in Bugs:Item2622 web accordingly.

  • pros: lets you import variable settings by including topics, which would be neat in some circumstances
  • cons: major change to spec

-- CrawfordCurrie - 13 Jul 2006

And what happens if ACL is inline and two topics are included? Same problem, yes? Or is the ACL stripped out of the included text?

-- MeredithLesly - 13 Jul 2006

poke poke It's called a misfeature.

-- MeredithLesly - 13 Jul 2006

The misfeature here is having ACLs in-line in the topic text.

I think this change makes sense, with the caveat that access controls should not work any differently to the way they do now (ACLs in included text are ignored, as they should be. ACLs only apply tot he topic they are defined in). However I fear it may impact TWikiApplications (only a gut feel; I have no proof, nor any TWikiApplications it will impact).

Here's an example of how it could be used:

  1. Define a topic "SearchForHair" with an HTML form which includes a dropdown "Style". The dropdown includes a bunch of other topic names - say "MulletCut", "SlapHead", "CombOver", "HedgeHog". Each of these topics sets a series of common attributes e.g "MulletCut" might define:
    • Set FRONT = short
    • Set SIDES = short
    • Set BACK = long
  2. These variables could then be used to control a search for hairstyles that meet the criteria for a mullet.
This is really just another way of doing forms, but it's one that may have advantages for some TWikiApplications.

-- CrawfordCurrie - 14 Jul 2006

To have %INCLUDE{}% include settings as well, please create a new attribute, which defaults to off. There are applications which rely on the fact that topic preferences are taken from the BASETOPIC only. From my own installation: I am using %INCLUDE{}% to extract "release" documents from "draft" topics. Discarding %COMMENT{}% endnotes and the like is done with %STARTINCLUDE%/%STOPINCLUDE%, but we also allow draft notes at arbitrary places within the topic if enclosed between %DRAFTONLY% and %ENDDRAFTONLY%. This only works because we can let the preferences have different values depending on whether the topic is included or not (and no, we can't achieve that with %IF{}%).

-- HaraldJoerg - 14 Jul 2006

Um, how do you deal with someone embedding a setting in the middle of an included part, Harald?

-- MeredithLesly - 15 Jul 2006

Apart from local rendering shortcuts there's little point in doing that. In all the topics which have been created by other users, I have not found one single * Set.

There are occasions where an %INCLUDE{}% with settings would come in handy, so I can see a benefit in the enhancement. But it does not justify just changing the general behaviour.

-- HaraldJoerg - 15 Jul 2006

It's so nice to keep hearing that all of our users are like yours, Harald.

It's not true of my project. But, hey, it's not a corporation hiding behind a firewall, it's only a Harvard University project being used by underprivileged students. So who cares?

-- MeredithLesly - 15 Jul 2006

Soon the project and the underprivileged students are moving to something better and faster than TWiki. But could you tell us what is true of them at the moment? In the pursuit of learning more on our (even if previous) user base?

-- SteffenPoulsen - 16 Jul 2006

I only support this if it is done with compatibility in mind. That is, include can include the settings, but only with a new flag such as inheritsettings="on" (with default set to "off" as Harald pointed out.)

-- PeterThoeny - 18 Jul 2006

On careful reflection, I think this is significant risk, and of marginal benefit. I need a lot more convincing, probably involving a killer app that can't be done any other way.


  1. Allows you to include settings from another topic
  1. Marginal benefit. There are other ways to skin that bear.
  2. Implies significant code and doc changes.
  3. Another "mode" on INCLUDE.

-- CrawfordCurrie - 18 Jul 2006

This proposal was dismissed a bit fast. This is clear now from the discussions in DocumentedDefaultParameterValuesForInclude, CanonicalTWikiVariables.

Even though the discussion in those topics is not 100% what was proposed in the above.

I remember when I read this in July that I thought Meredith wanted to include the META defined settings and settings defined anywhere in the included topic. Also outside the included section.

And that would be pretty hard to both code, document and control security wise. And I did not support that idea either.

But allowing settings in the included section is a valid request.

And something I personally is being hit by in many situations when I..

  • Include sections in topics that contain an often used TWiki Application. Here I often have to put the Set statements in WebPreferences to make the TWiki Variable work when I include them. That gives horrible namespace problems.
  • Include topics in TWiki presentations. And again and again find myself copying the entire topic source into my presentation because when I include the topic the variable set in the includED topic are not working.
  • Often we want to use some advanced macro text defined in a few TWiki Variables and then use this in 100s of topics. And then it is nice to have a simple include that contains these so you only have to edit this common text ONE place. But you cannot. So again the only way out is to add more and more to WebPreferences. And to give more and more users access to WebPreferences. Horrible.

If the community is not willing to support this then we have to revisit the DocumentedDefaultParameterValuesForInclude (in a simpler variation) which is an attempt to work around this issue.

-- KennethLavrsen - 19 Nov 2006

To be honest, I am not sure whether and when variables in include should be evaluated. You have the following options:

  • All variables in included topics are evaluated before inclusion in the scope of the complete included topic (even if only a portion is included).
  • Only those variables in included topics that are in sections that are included are evaluated before inclusion in the scope of the included section.
  • Only those variables in included topics that are in sections that are included are evaluated after inclusion together with the rest of the resultant topic.
And you have to make a decision whether meta data in the included topic is implicitly included or not, again there are options:
  • Meta data in the included topic is not considered.
  • Meta data in the included topic is applied to the included section.
  • Meta data in the included topic becomes part of the resultant topic and is merged with the meta data of the resultant topic.
  • Meta data in the included topic becomes part of the resultant topic and overrides the meta data of the resultant topic where they conflict.

Basically we need to come to a conclusion of the algebra of topic inclusion. Currently the situation is the following:

  1. pre-rendering handler is not applied to included topics
  2. only access permissions of the included topic are considered, not the other meta data
  3. only the included section is evaluated
  4. the included section is evaluated in the context of the included topic.

-- ThomasWeigert - 19 Nov 2006

By the way, the statement at the very top, that access control of an included topic is not honored, is incorrect. The included topic is checked whether access is permitted.

  • I removed the incorrect statement -- PTh

-- ThomasWeigert - 19 Nov 2006

Ken, do I understand you right in that the primary use case is that you want to have the possibility of preparing a file containing a set of variable definitions or configurations which are then included in other topics.

I believe as a consequence you would then suggest that the included variables should override the variables in the target topic? Ditto for included meta data? Included topic specific preferences?

There are two conflicting lines of thought applicable here: one is the "principle of least surprise". When I make a topic I should have the final say about what the characteristics of this topic are (e.g., access control, variable definitions) and should not be overridden by a topic I did not write, but just include. The other principles are those of "information hiding" and "abstraction". It should be possible to push data not relevant to the content of topic but important for rendering into a subroutine that is invoked and does its job.

-- ThomasWeigert - 19 Nov 2006

One other comment. I often use topic templates to do what I think you are trying to achieve, which is customizing a topic by including TWikiApplications in the topic. This is also one reason why I am pushing for rendering certain pre and postambles with the topic text, to allow these included applications to affect the topic text (see discussion elsewhere).

-- ThomasWeigert - 19 Nov 2006

Kenneth brings a valid use case, best explained with an example:

  1. I create a table and have repetitive elements in it, such as a speadsheet formula
  2. Because of that I define a topic setting, named i.e. CALCSUBTOTAL
  3. This works fine in the topic
  4. Now, some else includes that topic (or just the table via named section) into another topic
  5. The topic setting is no longer evaluated

From a "don't make me think" angle, the person who includes another topic or section would expect that it just works. Same for the person who created the incuded topic.

Thomas listed possible specs. May be the "only those variables in included topics that are in sections that are included are evaluated before inclusion in the scope of the included section" is the most logical one? There is also a performance question. The spec can be tweaked a bit in favor of performance.

-- PeterThoeny - 19 Nov 2006

Thomas has provided what I think is an excellent summary on the dilemma when he wrote about the "two conflicting lines of thought". I think the only way to satisfy both lines is an extra operand - or maybe an extra TWiki function. If we look at a comparable situation in TemplateToolkit, we find it has [% INCLUDE %] (which works as TWiki's %INCLUDE% does today) and it has [% PROCESS %]. The latter is identical to [% INCLUDE %], only that variables set in the included template keep in effect in the including template as well.

However, there is a significant difference in how TemplateToolkit and TWiki work with regard to variable assignments:

  • In TT, if you retrieve its value before you assign a value to it, you get an empty string. Like in a programming language, and like in TWiki's SpreadsheetPlugin.
  • In TWiki, regardless of where you define a variable in a topic, it is evaluated throughout the whole topic. Like with "local variables" in a buffer of Emacs, which usually are written at the end of a file.
Thomas' specification as quoted by Peter may be logical (especially for programmers), but it is more TT-like than TWiki-like. TWiki users may have the habit to write all settings in one place, regardless of named sections, because they know that TWiki works like that.

So, writing a spec which defines that the position of a variable setting in a topic matters if and only if a topic is included gives me a headache rather than a "don't make me think"-feeling.

-- HaraldJoerg - 20 Nov 2006

Edit | Attach | Watch | Print version | History: r16 < r15 < r14 < r13 < r12 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r16 - 2006-11-20 - HaraldJoerg
  • 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-2018 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.