Hypothesis

This morning Sven pointed me at a technique I hadn't been aware of; viz the use of * Set to provide what appear to be local settings inside included sections. At it's most basic, something like this:

%STARTSECTION{"memepickme"}%
memepickme(%PARONE%)
   * Set LOCAL1 = %IF{"defined PARONE" then="%PARONE%" else="NOT DEFINED"}%
LOCAL1 is %LOCAL1%
%ENDSECTION{"memepickme"}%

• before INCLUDELOCAL1 globally is NOT DEFINED

%INCLUDE{"UseOfSetInsideIncludedSections" section="memepickme" PARONE="PASS"}% expands to:

memepickme(PASS)

• Set LOCAL1 = PASS

LOCAL1 is PASS

• after INCLUDE LOCAL1 globally is NOT DEFINED

I was frankly surprised by this; I didn't think something like this should work, so I started researching why it does (appear to) work.

Findings

The first time I tried to do this I tried it without the <verbatim> block around the SECTION. It didn't work, the verbatim is required.

Finding 1: Any SECTION used this way must be wrapped in verbatim tags.

The second thing I tried was to establish if this really is defining a local variable. The obvious way to test this is to do it twice:

<verbatim>
%STARTSECTION{"memepickme2"}%
memepickme(%PARONE%,%PARTWO%)
   * Set LOCAL = %IF{"defined PARONE" then="%PARONE%" else="NOT DEFINED"}%
LOCAL is %LOCAL%
%ENDSECTION{"memepickme2"}%
</verbatim>

<verbatim>
%STARTSECTION{"ohnonotagain"}%
ohnonotagain(%PARONE%,%PARTWO%)
   * Set LOCAL = %IF{"defined PARTWO" then="%PARTWO%" else="NOT DEFINED"}%
LOCAL is %LOCAL%
%ENDSECTION{"ohnonotagain"}%
</verbatim>

• before INCLUDE LOCAL globally is NOT DEFINED

%INCLUDE{"UseOfSetInsideIncludedSections" section="memepickme2" PARONE="ONE" PARTWO="TWO"}% expands to

memepickme(ONE,TWO)

• Set LOCAL = ONE

LOCAL is TWO

• after first INCLUDE LOCAL globally is NOT DEFINED

%INCLUDE{"UseOfSetInsideIncludedSections" section="ohnonotagain" PARONE="THREE" PARTWO="FOUR"}% expands to

ohnonotagain(THREE,FOUR)

• Set LOCAL = FOUR

LOCAL is FOUR

• after secondINCLUDE LOCAL globally is NOT DEFINED

So it's clearly not a local variable, in the sense of a setting that is local to a section definition. In fact it looks as if it depends on the * Set being evaluated when the topic is read (unsurprising I guess) so the second * Set always wins.

So the second caveat is:

Finding 2: you can't use the same preference name in two SECTIONs in the same topic.

That rather suggests that the * Set doesn't have to be inside the SECTION; so the next thing I tried was:

<verbatim>
   * Set NOTREALLYLOCAL = %IF{"defined PARONE" then="%PARONE%" else="NOT DEFINED"}%
%STARTSECTION{"itwisnaeme"}%
memepickme(%PARONE%) => NOTREALLYLOCAL is %NOTREALLYLOCAL%
%ENDSECTION{"itwisnaeme"}%
</verbatim>

%INCLUDE{"UseOfSetInsideIncludedSections" section="itwisnaeme" PARONE="PASS"}% expands to memepickme(PASS) => NOTREALLYLOCAL is PASS

That works so long as the SECTION is in the same topic as the INCLUDE (the topic include itself) but fails if the SECTION is included from another topic (the typical case)

Finding 3: the * Set must be within the SECTION for generality.

See UseOfSetInsideIncludedSectionsTranscluded for the same examples using sections transcluded from another topic (this topic).

Please feel free to add comments / more findings

-- CrawfordCurrie - 18 Apr 2012

adding more weird ideas - sadly this will require many topics to explore - and then we should make them all into unit tests

-- SvenDowideit - 18 Apr 2012