• Do not register here on develop.twiki.org, login with your twiki.org account.
• Use View topic Item7700 for generic doc work for TWiki-6.0.2. Use View topic Item7703 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.

ALSO RENAME STARTTEMPLATEONLY/STOPTEMPLATEONLY AND STARTINCLUDE/STOPINCLUDE consistently (was Item1464)

As documented in TWikiVariables#VarSECTION, the purpose of SECTION and ENDSECTION is to define named sections that can be included with %INCLUDE{ "Topic" section="name" }%.

SECTION and ENDSECTION are basically just a special case of STARTINCLUDE and STOPTINCLUDE, the only difference is that the latter ones do not have a name. So, %STARTINCLUDE{"myname"}% and %STOPINCLUDE{"myname"}% should replace %SECTION{"myname"}% and %ENDSECTION{"myname"}%, respectively.

One small change in %STARTINCLUDE{param}% is needed. Currently it means, "if param does not expand to a non-zero integer, then nothing will be included". This can be made much more intuitive and explicit with a suppress="1" parameter.

There is another reason, consistency: Removing SECTION and ENDSECTION makes STARTTEMPLATEONLY and STOPTEMPLATEONLY consistent with STARTINCLUDE and STOPTINCLUDE.

Dakar is not released yet, so it is good timing to remove excessive fat from TWiki.

Now is the last chance to remove these variables without going through the deprecation process since these variables have not been in a production release yet.

-- SP

I think the SECTION..ENDSECTION came from a plugin, didn't it? I seem to recall the syntax and semantics being chosen to maintain compatibility with that plugin. Though I agree - the semantics and syntax of STARTSECTION, STARTTEMPLATONLY and STARTINCLUDE should all be consistent.

CC

Admitted this is all very inconsistent. But I'd really like SECTION...ENDSECTION just as a matter of taste. This is consistent with TWISTY...ENDTWISTY btw. Though there are plugins that use START...STOP also, but also some that do BEGIN....END. Whatever. If you go for consistency then there's a lot more...

Anyway, another solution to the consistency thingy here would be to deprecate/replace STARTINCLUDE...STOPINCLUDE with SECTION{"default"} .... ENDSECTION{"default"} and name STARTTEMPLATEONLY...STOPTEMPLATEONLY to TEMPLATEONLY...ENDTEMPLATEONLY or TEMPLATENOP...ENDTEMPLATENOP or TMPL:NOP...TMPL:PON.

MD

I don't care how the tag is named. What I DO care is that the tag denotes a section of the topic and not only a "section to be included in another topic". With the current that, SECTION can be overloaded so it can be used for sectional INCLUDEs and sectional Edits.

I can action over this item, but I need an "agreement" over the final sintax.

There are the following proposed options:

  • STARTINCLUDE{"section"} - STOPINCLUDE{"section"}
  • STARTSECTION{"section"} - ENDSECTION{"section"}
  • STARTSECTION{"section"} - STOPSECTION{"section"}

If there is going to be any change, I vote for the second.

RA

ALSO RENAME STARTTEMPLATEONLY/STOPTEMPLATEONLY AND STARTINCLUDE/STOPINCLUDE CONSISTENTLY

Note: SECTION{"default"} cannot replace STARTINCLUDE..STOPINCLUDE. The semantics are different. STARTINCUDE/STOPIINCLUDE only includes what is in the smallest volume between the first STARTINCLUDE and the nearest STOPINCLUDE after it. Everything else is ignored, including other STARTINCLUDE tags.

It seems to me that there are two requirements for section markers. The first is to identify unique individual sections (e.g. "section1") and the second is to identify generic sections e.g. "templateonly" or "include". It's important to distinguish these two semantics. So I propose:

%STARTBLOCK{"type"}%
%ENDBLOCK{"type"}%
Need to support at least templateonly and include. (verbatim and noautolink can follow later). Importantly there can be as many blocks of the same type as necessary in a topic. The full existing STARTINCLUDE semantic is highly restrictive and ignoring it is very unlikely to break anything, so I propose we do that - ignore it. Note that compatibility can mostly be maintained using:
   * Set STARTINCLUDE = %STARTBLOCK{"include"}%
   * Set STOPINCLUDE = %ENDBLOCK{"include"}%
STARTBLOCK{"templateonly"} is new in Dakar so doesn't need compatibility support.

%STARTSECTION{"name"}%
%ENDSECTION{"name"}%
name can only occur once in any given topic.

CC

there can be as many blocks of the same type as necessary in a topic

This would solve the problem of documentation topics that must have the TOC above the topic title, because the current STARTINCLUDE can only be once. I am in favor.

For STARTSECTION, perhaps

%STARTBLOCK{"type" name="name of section"}%
%ENDBLOCK{"type" name="name of section"}%
is possible? Where %STARTBLOCK{name="name of section"}% is equal to %STARTBLOCK{"include" name="name of section"}% ?

AC


  1. Would this factoring to a single STARTBLOCK/ENDBLOCK simplify and generalize (and hopefully reduce the volume of and hence the compile time) of the code and improve responsiveness?
    • It would certainly simplify, but is unikely to make a measurable difference in speed. CC
  2. What is the impact on the existing topics and applications (e.g. BlogPlugin)?

-- AJA

We are so short before the release, lets just make a small simplification without deprecating additional variables that have been used up to Cairo. So please let's not change STARTINCLUDE and STOPINCLUDE.

IMHO the sematic difference of STARTINCLUDE / STOPINCLUDE vs STARTINCLUDE{name} / STOPINCLUDE{name} is just a documentation question. In fact, since it is documented in the same place, the semantic difference can be made very obvious in the docs.

-- PTh

DBCachePlugin and BlogPlugin needed to be patched accordingly. But this will be a straight-forward patch as both don't have to maintain backwards compatibility and there's no real semantic change. Anyway, I'd vote not to change anything at all anymore and defer this item.

MD

SVN 8512

CC

This is fantastic, better than expected. Thanks a bunch, CC.

- Hope you'll be OK, MD smile

-- SP

Thanks Crawford for implementing this so quickly.

I took some time to improve the docs for START/ENDBLOCK and START/ENDSECTION; I tried my best to reduce confusion.

But I find the docs and spec still confusing for users. We have now three variables STARTINCLUDE, STARTBLOCK and STARTSECTION that sound very similar, but have different semantic meanings and different meanings of nameless parameter!

I am reopening this, although very late in the game. Here is a small spec change that will reduce the confusion. It is also a small (and safe) code change:

  • Remove STARTBLOCK and fold into STARTSECTION
  • Remove ENDBLOCK and fold into ENDSECTION
  • The old STARTBLOCK{"templateonly"} changes to STARTSECTION{type="templateonly"}
  • The old STARTBLOCK{"include"} changes to STARTSECTION{type="include"}
    • Same for ENDBLOCK{}
  • An unnamed STARTSECTION{""} is OK and means STARTSECTION{"_DEFAULT"}

This will not affect STARTSECTION and ENDSECTION (no change in spec).

(Actually, I really think it would be better to fold STARTSECTION and STOPSECTION into STARTINCLUDE and STOPINCLUDE, but this is too late in the game now)

-- PTh

The reason I separated them was simple; it's a lot less code (and therefore a lot less risk at this late stage). Folding all blocks into STARTINCLUDE is not an option. The STARTINCLUDE semantic is too restrictive, and folding all these together would be hopelessly confusing. STARTINCLUDE should be considered to be about to be deprecated, and should not be extended.

A basic confusion is created by the above spec. What does STARTSECTION{"xxx" type="tempateonly"} mean?

Arthur's proposal above is a lot better; All sections are typed, so we have:

STARTSECTION{"type" name="name"}

"type" is one of "section" (generic container) "include" (include block) or "templateonly" (template only block). If "type" is not given, it defaults to "section".

The name parameter is optional, though obviously has to be provided on named sections for them to be useful.

There is an implicit assumption here that containers can be nested or overlapped. So

%STARTSECTION{name="one"}%
%STARTSECTION{name="two"}%
%ENDSECTION{name="one"}%
%ENDSECTION{name="two"}%
is legal. My gut tells me that is storing up trouble for the future.

Any complaints, be quick. Be very, very quick!

CC

OK, I was outvoted two to one so the default parameter is the section name. I was forced to do what I had been trying to avoid, and parse section tags properly. At least that means there are clear-cut rules for sections now.

SVN 8559

CC

Named include blocks are rather pointless right now. How about collecting all include blocks of a given name. See TestTopic41. Rather than including the first test1 and the first test2 section on a plain %INCLUDE (w/o a section argument) we could have either ignore the name completely and extract all blocks regardless of their name or make named includes meaningful by extracting the named blocks all together which is quite usefull as a means to get a named slice of a topic. So the only remaining difference between including blocks of type "include" and of type "section" would be if only one or all blocks are extracted. The "section" argument of the INCLUDE tag should be renamed to "name" then. s

MD

ItemTemplate
Summary Remove SECTION in favor of START/STOPINCLUDE
ReportedBy TWiki:Main.SteffenPoulsen
Codebase

SVN Range Sun, 22 Jan 2006 build 8439
AppliesTo Engine
Component

Priority Urgent
CurrentState Closed
WaitingFor

Checkins 8511 8512 8557 8559 8561 8562 8563
Edit | Attach | Watch | Print version | History: r18 < r17 < r16 < r15 < r14 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r18 - 2006-01-27 - MichaelDaum
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2018 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback