Feature Proposals » way to make TWiki-level comments in topics

Motivation

When splitting up a topic into two or more pages, I'd like a convenient way to disable variable settings (to see which ones are needed in which of the new pages). I can do this by (say) changing all of the "Set" keywords to "xSet", but this is inconvenient.

Alternatively, I may have text that I want to hide from external users. I could keep this in a separate (local) file, but that seems inconvenient.

Description and Documentation

AFAICT, TWiki has no direct support for comments. I can use HTML comments (e.g., "<!-- ... -->"), but these don't always have the desired semantics.

Syntax

I don't care much about inline comments, though they might be handy on occasion. Mostly, I want syntax for block-mode comments, eg:

<comment>
... This text will be _completely_ ignored. ...
</comment>

Semantics

The comment text should not be present in the transmitted HTML. So, for example, it should not be accessible via "View Source", etc.

TWiki syntax within the comment text should not be processed at all. This includes, but is not limited to, variable settings.

Examples

Impact

Implementation

-- Contributors: Rich Morin - 2015-12-27

Discussion

TWiki has VarHIDE, would that work?

-- Peter Thoeny - 2015-12-27

Not completely:

"Variables inside HIDE still get expanded because variables execute inside out, e.g. you can't use it to speed up slow variables."

Basically, I don't want any interpretation of the comment.

-- Rich Morin - 2015-12-27

Then a new variable needs to be introduced, such as HIDEDISABLE or the like. This new variable needs to be parsed before other variables so that enclosed variables are not interpreted. Or better a <hidedisable>...</hidedisable> tag? Implementation-wise it would be easier with a new tag since it can done with the same code like <verbatim>.

-- Peter Thoeny - 2015-12-28

Or, call the tag <remove>...</remove>.

-- Peter Thoeny - 2016-01-01

I prefer <comment>...</comment> to <remove>...</remove> because it's common among programming languages to have a part of a code ignored temporarily by making it a comment. You may also leave a comment. Putting a comment in <remove>...</remove> feels unnatural to me.

In any case, a tag for TWiki level comment is a great idea. It would be handy not only for topic splitting but also for debugging.

It would be relatively easy to implement -- as Peter wrote, it would be implemented in a similar manner as <verbatim>...</verbatim> in lib/TWiki/Render.pm. In addition, lib/TWiki/Prefs/Parser.pm needs to be modified.

-- Hideyo Imazu - 2016-01-04

Yes, <comment>...</comment> is more intuitive for programmers. I am concerned though about confusion with the existing %COMMENT{}%. Perhaps <commentout>...</commentout> ?

-- Peter Thoeny - 2016-01-04

You are right. <comment>...</comment> would look related to %COMMENT{}%. Besides, in the past, some HTML browsers seemed to recognized the comment tag.

It's a matter of taste, but how about <ignore>...</ignore> ? The tag name is similar to <remove>...</remove> in nature, but ignore feels more natural to me. commentout is not bad and is safer than ignore -- less likely to conflict with something existing than ignore. If you feel strongly about commentout, I'm fine with that.

-- Hideyo Imazu - 2016-01-04

<ignore>...</ignore> sounds good too.

The WYSIWYG editor needs to be made aware of this new tag.

-- Peter Thoeny - 2016-01-04

It's an implementation detail, but it's better to be handled in TWiki::_processTags() rather than TWiki::Render::getRenderedVersion(). Because you may put a comment inside a variable. e.g.

%SEARCH{
   "^%URLPARAM{"i" default="a"}%" <ignore>A topic name cannot start with a lowercase letter</ignore>
   ...
}%

Hideyo Imazu - 2016-01-05

This was discussed at KampalaReleaseMeeting2016x01x07:

• No committed developer and date set (needs one to be accepted)
• Proposal looks OK, but some have concerns to add another XML-like tag (PTh OK)

-- Peter Thoeny - 2016-01-08