Feature Proposal: Let's make an ENDINCLUDE to be consistent with ENDSECTION

Motivation

One of the first things I noticed coming to Foswiki were apparently arbitrary inconsistencies like this. It's an easy thing to fix, yet makes working with sections/includes slightly more annoying for newbies.

I have now trained 5 others at my workplace in writing Foswiki "wiki-apps", all have backgrounds in or at least exposure to other kinds of computer programming/templating, and it would be nice during this training to focus on the concepts behind wiki-apps instead of all the exceptions.

Description and Documentation

• Create a new ENDINCLUDE macro which will be documented as the recommended equivalent of the existing STOPINCLUDE.
• Create a new STOPSECTION macro equivalent of ENDSECTION.
• Document ENDINCLUDE and ENDSECTION fully
• Document STOPINCLUDE and STOPSECTION as one liner texts say that are an alias for ENDINCLUDE and ENDSECTION
• Adjust all shipped core docs to only use the END form everywhere in examples

Examples

Before:

%STARTINCLUDE%
Some text
%STOPINCLUDE%

After:

%STARTINCLUDE%
Some text
%ENDINCLUDE%

Impact

WhatDoesItAffect:

%WHATDOESITAFFECT%

edit

Implementation

-- Contributors: PaulHarvey - 01 May 2011

Discussion

Adding %ENDINCLUDE OK

Deprecating STOPINCLUDE not OK. I know and acknowledge that deprecating something does not mean removing NOW but it is a signal that eventually it will be removed and I am violently against that. People have used this is 100000s of topics in some wikiapps and it is unacceptable to put a task on an admin to replace this in so many places. This is not an API that affects a few plugins that can be modified by programmers. We are dealing with end user syntax here and it is unacceptable to disrespect the effort our users have put into creating content for up to 11 years.

We can ADD ENDINCLUDE and keep STOPINCLUDE as an alias we will never remove. We can document the STOPINCLUDE as old and recommend ENDINCLUDE instead. But I want a promiss that STOPINCLUDE will never be removed from the code.

We do not save any whales by deprecating and the word deprecate creates worry and fear among users. I know myself how worried I got when things got deprecated earlier and I have spent quite a lot of time hacking .txt files when careless developers made non-compatible changes in plugins.

So adding ENDINCLUDE is OK as it helps end users remembering the macro names as the naming becomes consistant.

But I do not want to see the word deprecate in the documentation. Word like old and not recommended are OK combined with a note in the release note that the old macro remains in the code as an alias.

The code overhead of matching both is microscopic. And any argument of "cruft" is religion and not fact based.

Experience has shown that earlier deprecated core TML syntax or macroes has to remain forever. The only thing I ask for is to avoid the word deprecate in the documentation and release notes.

My added concern will be removed when I have acknowledge from the proposer that we can avoid the D word in the docu

-- KennethLavrsen - 02 May 2011

I too like the idea of adding synonyms so that those that thing START-STOP and those that think START-END can both be happy forevermore.

so I'm suggesting that we add ENDINCLUDE and STOPSECTION - that way we cover both types of people.

-- SvenDowideit - 03 May 2011

Good points. I've updated the proposal. I think Kenneth's concerns are addressed.

-- PaulHarvey - 03 May 2011

Yes. My concerns are addressed. I will rename the topic so there is no mistake.

I propose that if the ENDXXXX is preferred over STOPXXXX then we make the VarSTOPXXXXX topic so it simply says "Alias for ENDXXXXXX". By not using the D-word we avoid making existing users concerned. And by making this short version it becomes very clear that the ENDXXXXX is the "real" macro name and the other is just an alias. This way people will use the END form and we can change ALL document to only use the ENDXXXXX macros in all examples.

I would not make an undocumented alias. Both STOP macros should be documented but as one liners and all core documentation walked through to adjust all examples

I have changed the proposal above to reflect this.

-- KennethLavrsen - 03 May 2011

I concur, I'd prefer to have a VarTopic foreach macro, otherwise users have no idea what some things might be.

-- SvenDowideit - 03 May 2011

Good points again. Thanks to both of you (sometimes things which are really really obvious, do escape me

-- PaulHarvey - 04 May 2011