code comments within plugin documentation sections

[FND]

Many plugin authors[1] these days use sections within their plugins'
documentation block[2] to embed CSS code:

/***
!StyleSheet
body {
color: #F00;
}
!Code
***/
//{{{
var name = "StyleSheetFoo";
config.shadowTiddlers[name] = store.getTiddlerText(tiddler.title +
"##StyleSheet");
store.addNotification(name, refreshStyles);
//}}}

Unfortunately, there's a significant flaw to this useful technique: It
doesn't support CSS comments. Adding "/* lorem ipsum */" anywhere in the
StyleSheet section results in a syntax error when the plugin is evaluated.

I can imagine some hacky workarounds - e.g. using fake "//" markers
instead of the valid "/* ... */", removing them with a .replace when
creating the shadow tiddler - but none of those seem very satisfying.

Any clever ideas on how this issue might be resolved?

-- F.

[1] pioneered by Mike and Jeremy, if I recall correctly
[2] http://tiddlywiki.org/wiki/Dev:Comments#Wikified_Contents

[Eric Shulman]

> [1] pioneered by Mike and Jeremy, if I recall correctly

Actually, use of sections to deliver a 'payload' of CSS, HTML, etc.
that is then dynamically loaded as needed, was something that I
developed shortly after sections were first implemented in the core.

Also note that, in addition to directly setting CSS via setStylesheet,
'section payloads' can also be deposited into shadow definitions
during startup processing.

For example, rather than simply loading the CSS payload directly, like
this:

setStylesheet(store.getTiddlerText('MyPlugin##css'),'myPluginStyles');

you could write the following:

config.shadowTiddlers.StyleSheetMyPlugin
=store.getTiddlerText('MyPlugin##css');
var css=store.getRecursiveTiddlerText('StylesheetMyPlugin','',10);
setStylesheet(css,'myPluginStyles');

This code first deposits the payload into a shadow, then retrieves the
shadow content (or content from a customized tiddler of the same name)
to set the actual stylesheet in the browser. The advantage of this
technique is that it allows the user to customize the default CSS to
match the theme used within their document, simply by editing the
shadow so that a 'real' tiddler is created.

During startup, the payload is still deposited into the shadow;
however, because a 'real' tiddler exists, the user-customized CSS will
be applied instead.

enjoy,
-e

[FND]

> Actually, use of sections to deliver a 'payload' of CSS, HTML, etc.
> that is then dynamically loaded as needed, was something that I
> developed shortly after sections were first implemented in the core.

I had a feeling this was an Ericism - my apologies!

> Also note that, in addition to directly setting CSS via setStylesheet,
> 'section payloads' can also be deposited into shadow definitions

I also prefer providing customizable shadow tiddlers (as illustrated in
my original post). However, I generally avoid setStylesheet altogether
and use addNotification with refreshStyles, which nicely encapsulates
the necessary steps.

-- F.