Feature Proposal: Add a hide option to STARTSECTION

Motivation

Sometimes you create a section on the same page as you want to display it. To hide it, you must put it inside html comments, or inside a hidden verbatim block (class="foswikiHidden"). But it is not satisfactory, because the content is duplicated on the page.

This proposal is to optionally remove the INCLUDE definition from the generated text.

Description and Documentation

• Add an option definition="hidden" to remove the section contents from view. The section will not be shown when the base topic is viewed or INCLUDEd; the intent is that the section will be hidden unless explicitly called for.

Examples

%STARTSECTION{"blo" definition="hidden"}%
contents
%ENDSECTION{"blo"}%

Impact

WhatDoesItAffect:

%WHATDOESITAFFECT%

edit

Implementation

-- Contributors: ArthurClemens - 27 Nov 2009, PaulHarvey - 04 Apr 2011

Discussion

Can't be UnderConstruction yet, because it hasn't been accepted, so changed state to UnderInvestigation.

I've wanted this in the past myself. I'm struggling to find a reason not to do it.

See VarSTARTSECTION for other parameters to SECTION.

-- CrawfordCurrie - 27 Nov 2009

As with HereDocumentSyntaxForMacros, InlineTopicContentAsMeta, ContentAccessSyntax and SearchBySection, it would be great if we could unify all these things into a common markup, that:

• Provides the needs demanded by each proposal.
• Allows sections to be addressable parts of a topic.
• Would hopefully be possible to use special named section markup instead of/as well as META:FIELDs - sections should be searchable/extractable/comparable.
• More thoughts ... I will revisit this proposal later.

I have no objection and I would use this feature myself, but it would be highly desirable to solve all these requirements into a more elegant solution.

-- PaulHarvey - 28 Nov 2009

Thinking over the uses that I have seen - I would like to change the syntax, and add another option.

%STARTSECTION{"blo" show="hide"}%
contents
%ENDSECTION{"blo"}%

and the verbatim use for function Sections:

%STARTSECTION{"blo" show="verbatim"}%
contents
%ENDSECTION{"blo"}%

-- SvenDowideit - 30 Nov 2009

How about display=hidden and display=verbatim.

-- MichaelDaum - 30 Nov 2009

My first thought as well, but there's a danger of "display" being misinterpreted as meaning the same as "display" in CSS - which it very much doesn't.

I confess I don't find show very intention-revealing. You are trying to control the presentation of the content, but only in the topic where it is defined. It's not a general "show" control, which would reasonably be expected to control how it is shown when the section is included. Perhaps a more intention-revealing name would be wheredefined, so you have wheredefined="shown" (a NOP), wheredefined="hidden" and wheredefined="verbatim"?

-- CrawfordCurrie - 30 Nov 2009

yes. I really don't care what the parameter is called, I just want more than just hidden=on, and like Crawford points out, its a darned difficult setting to name usefully - wheredefined isn't more intention revealing - but i've got nothing better

Where defined suggests the value is more of a declarative meta datum, not an instruction

still, as we're arguing about naming details, does that mean the feature i suggest has aggreement?

-- SvenDowideit - 01 Dec 2009

To have a display as verbatim, do you mean to have it styled inside a pre like verbatim does?

On naming, I suggest:

• displaydefinition="hidden"
• displaydefinition="verbatim"

-- ArthurClemens - 01 Dec 2009

yup, styled inside a pre

happy with your suggestion wrt naming too

-- SvenDowideit - 01 Dec 2009

Yes, I'm happy with the concept and yes, I'm happy with Arthur's suggestion for a name.

-- CrawfordCurrie - 04 Dec 2009

What about render for the parameter name? (on,off,0,1,verbatim,etc.)

• We must distinguish between the section contents and the macro contents. This request is to hide or change how you see the macro, not the section contents (that may be displayed in a different topic). render seems to be about the section contents. -- ArthurClemens - 15 Jan 2010

-- WillNorris - 15 Jan 2010

I have been looking at the code. In Foswiki.pm we have parseSections, but that is only called with an INCLUDE in the topic, which we may not have.

Then we might 'fill in' macro STARTSECTION in a new pm Macros/STARTSECTION.pm. But for a large part this would duplicate the code in parseSections, because we still need to deal with nested and unnamed and improperly closed sections.

Could be perhaps unify this by move the parsing to Macros/STARTSECTION.pm and add the sections to the topic object?

-- ArthurClemens - 16 Jan 2010

Unfortunately I got stuck in the code. A second pair of eyes would help.

-- ArthurClemens - 05 Apr 2010

It would be terrific if sections were addressable via the TOM. One day they could even be queried, perhaps? Anyway, I think incorporating sections into the TOM would be the best path forward. I'm new to TOM internals but will keep sections in mind.

-- PaulHarvey - 05 Apr 2010

Reading the proposal again I don't see a clear spec, and that what has been proposed may be ambiguous. First displaydefinition is quite long for a parameter name. how about display only. Next, does display=hidden mean it is still delivered to the client with only a display:none css property? Or does it mean "remove from markup completeley", which would be a lot more useful than just hiding the fragment.

-- MichaelDaum - 03 Feb 2011

This is no CSS hack. I guess the very first intro paragraph could have made this more clear.

You already proposed display over displaydefinition in 2009. I don't like either (but as the proposal has already been accepted without objection, I would prefer to implement displaydefinition unless a better idea comes along and we reset the clock).

-- PaulHarvey - 03 Feb 2011

I have updated the first paragraph: "This proposal is to optionally remove the INCLUDE definition from the generated text."

-- ArthurClemens - 03 Feb 2011

Well I do prefer display over displaydefinition, and I am sure that other users prefer to keep it short as well. Not sure why the extra ...definition makes it any better.

I can't see the reason why we shouldn't change this. The code isn't even written. Once this is out into the wild we can't change it back.

-- MichaelDaum - 03 Feb 2011

I am not hung up on displaydefinition, I am fine with display. People savvy enough with CSS will be able to work this out.

-- ArthurClemens - 03 Feb 2011

Why not use something completely different like expose as synonym for display/show. Just my 2c. -- Happy implementing!

-- FranzJosefGigler - 03 Feb 2011

expose is an interesting idea. But I'd like to have one more go at agreeing to a 'display'-named param The whole reason we didn't go with display (apparently) is that we didn't want it to be confused with CSS property.

I am honestly indifferent to what the parameter name is, I am more concerned with the quality of the code behind it. But I don't like short-circuiting the feature proposal process, we should have sorted this out in 2010.

Let's pick a new name and reset the clock. I had favoured something like inhibit="on" but perhaps display="remove" would please Michael for having a sensible parameter name, and Crawford to make it different enough from the CSS property of the same name.

-- PaulHarvey - 03 Feb 2011

Short circuiting is okay sometimes as long as the orignial intend of the proppsal that was accepted remains the same.

-- MichaelDaum - 04 Feb 2011

I am not indifferent to the name, as we have inherited far too many macros parameters that are badly thought out, and have ended up requiring ugly workarounds such as nonoise to try and make them useable.

Consider what we are trying to say. The goal is to control the TML rendering of the section, such that it is rendered where the section is explicitly included, but not where it is defined. Five points to consider:

1. There may be other operations which you may want to perform only at the site of the definition.
2. Whatever parameter name is used should be re-usable for other macros that also require the concept of elision when the topic containing the definition is rendered.
3. The parameter should ideally be reflexive; instead of just thinking "how do we hide this in the base topic", think also about "how do we show this in a non-base topic".
4. This is a difficult and rarely used concept. A parameter name that conflicts with more obvious concepts should be avoided, and a wordy name is not such a big problem.
5. Double negation is bad ( noshow="off" )

Some ideas that come from this train of thought:

elide="basedefinition"

render="included"

hidewhen="inbase"

renderwhen="defined,included"

show="definitiononly"

show="exportedonly"

-- CrawfordCurrie - 04 Feb 2011

Please, KISS. Most of these proposals are hard to understand for non-native english speakers, also conceptually. Something like display="off/verbatim/inline" should be just fine.

-- MichaelDaum - 04 Feb 2011

Think harder, Michael. display is not fine. Anyone would immediately assume that would suppress the display of the section anywhere it is used - exactly like it would mean in CSS. The whole point of this discussion is for us - the experts - to think about these sorts of problems so the end users don't have to. Consistency and clarity.

-- CrawfordCurrie - 04 Feb 2011

I had a bogus commit date. That's been reset to today. I've also changed the proposal. I'm not interested in providing decoration function at this point, because a simple "verbatim" isn't enough of a spec (we need class="tml" to be useful), so somebody else can address that in the near future. Arthur's original proposal was for displaydefinition="hidden" and I didn't really have a problem with that.

It's been changed to definition="hidden". Michael, is this okay for you? Crawford, is this okay with you?

I'm running out of ideas on how to make everybody happy. Which is interesting, because this proposal was already accepted

-- PaulHarvey - 05 Feb 2011

Paul, I can live with it. No beauty, not quite intuitive but what can I say more.

Crawford, display=off is fine because it is intention reveling and short. Users don't care how a piece of information is hidden from them. Most don't know css. Most never were aware that a verbatim-hidden section was still delivered to them.

-- MichaelDaum - 05 Feb 2011

definition=hidden is fine. display=off is not, as it says the wrong things to me, and I am at least slightly representative of users.

-- CrawfordCurrie - 06 Feb 2011

Item10316 is probably not the task for this proposal - it is multi purposed, probably 2.0 features.

-- GeorgeClark - 23 Feb 2012

See SectionalTransforms.

-- KipLubliner - 19 Mar 2012

I'd like to see this get implemented. (I just got bitten by using HTML comments. :-/) BTW, please make sure that %TOC% (etc) honor the hiding.

-- RichMorin - 27 Feb 2013

This seems to be stalled for 1.2. I've removed the Item10316 reference, as that is focused on performance of of the %INCLUDE macro.

I'd really like to see this get done though, but I guess it needs to get deferred to 2.0.

-- GeorgeClark - 02 Apr 2014

Changed to Parked, needs a developer to adopt.

-- GeorgeClark - 19 Nov 2015

Changing this proposal back to under investigation. It was originally accepted, but restarting the clock with the below suggestion.

I've looked into this in conjunction with AddMarkupToExcludeContentFromRendering. I'm not particularly thrilled with the definition="hidden" argument. I'm thinking that there should be a common argument to both the *SECTION macro and the INCLUDE macro:

• INCLUDE{... render="hidden"} would hide the included section, but still process macros in the section.
• STARTSECTION{... render="hidden"} would hide the section in-line, but also still processing macros in the section.

The documentation would clearly state that the render option only applies to the content of the section in-line, and to use the equivalent field on the INCLUDE macro to apply it when a section is included.

This would allow future extension to other rendering controls; noautolink. noemail. pre ...

Macro-expansion control equivalent to <verbatim> would be more complicated to do using *SECTION macros, The would have to "flush" the macro stack until encountering the end of the section.

-- GeorgeClark - 12 Feb 2018

I like the additions to this proposal.

Does a render="default", render="on", render="off" make sense? If so, which render argument has got higher precedence: the one from the INCLUDE or the one on the SECTION?

-- MichaelDaum - 12 Feb 2018

As far as on/off/default... I envision render growing to be a list of options, somewhat ike CrawfordCurrie suggested in the AddMarkupToExcludeContentFromRendering for a <feature tag. render="hidden" or render="noTML,noautolink". We could use a syntax with on/off options, but that starts to get complex. render="hidden=off,TML=on,autolink=off" ...

There are no compatibility issues with the SECTION macros, as these have no parameters today. But if we want parity with the INCLUDE macro, then we have to be concerned with colliding with an existing parameterized INCLUDE.

There is no precedence. render= would be "local" to the expansion of that specific macro (or macro block) itself. It would never carry across to another macro. So:

• render= on INCLUDE would control how the content expanded by the INCLUDE macro is rendered. It would NOT look at any render definition on the section itself.
• render= on the *SECTION macro would only apply to the in-line rendering of the START/END block inline in that particular topic.

We would have to be especially clear with this to avoid any confusion of what applies when. I f you do want some way to define the default rendering of a section, that would be applied when the INCLUDE is executed, we should name it something like *SECTION{defaultrender= ...} But for now I see that as out-of-scope for this proposal. That would involve complications in the _parseSection code.

The one area where this is a bit ambiguous would be how to handle the section= urlparam on the view script. If my URL is bin/view/Web/Topic?section=foobar:

• Is this treated as an in-line expansion, and honor the STARTSECTION render option
• Or is it an "include" of the section which ignores the render option.

I was completely surprised about that queryparam - I had never encountered it before. I think for best compatibility, we should treat it as an include, and NOT honor any render settings. Otherwise we would break existing uses.

Actually that's probably a good way to look at the render= in general. If INCLUDE actually honored the *SECTION render= options, then changing an include to hide it for example would change every place it was previously used. That would be a bad side-effect.

-- GeorgeClark - 12 Feb 2018

One other note. Tasks.Item5700 and Tasks.Item2319 both address a somewhat related issue. The INCLUDE raw= and literal= options only apply to external web pages. I think that adding the "render=" option for topic type includes would possibly address these tasks, at least partially.

-- GeorgeClark - 12 Feb 2018

I've run into an implementation problem. I've got STARTSECTION working great for topics. Unfortunately it's not going to work when sections are included unless we redesign Foswiki::parseSections. I think a simpler solution is to use a different macro. Maybe %STARTRENDER / %ENDRENDER?

The issue is that _parseSections removes all flavors of all SECTION tags. So there is no way to include a topic which itself contains a hidden section. There s no SECTION tag remaining for the macro processor to expand into the <!-- --> markers.

-- GeorgeClark - 16 Feb 2018

Commenting is disabled while not logged in