"Namespacing" for plugins?

[Julian Kniephoff]

Just out of curiosity: On this page about TiddlyWiki plugins I read the following:

Plugins that define macros, views or other named entities are expected to prefix the name with their publisher identifier, for example:  tiddlytools.slider.

However, I have yet to see a plugin follow this guideline. Is this still enforced/encouraged?

Just to check whether I even understand this correctly: Let's say I develop a plugin $:/plugins/juliankniephoff/frobnicator which exposes a widget $frobnicate, a macro frob and a filter operator frobnicated, should these be called $juliankniephoff.frobnicate, juliankniephoff.frob and juliankniephoff.frobnicated respectively?
So would I really have to write something like this?:

<$juliankniephoff.frobnicate filter="[juliankniephoff.frobnicated[]] value=<<juliankniephoff.frob>> />

(Of course none of this means anything. I'm just curious about the convention.)

[Tobias Beer]

Hi Julian,

It's the first time I hear of this convention and I'm almost certain no one has been adhering to it.
At least I haven't been, since I wasn't even aware it existed.

It would definitely avoid collisions, especially among plugin authors.

If you look at my plugins, you'll find that many have a good chance for future incompatibilities owed to their generic names...

http://tobibeer.github.io/tw5-plugins

Eventually, rather than the above convention, I think we should have some public listing where authors can register some basic info about their plugins, especially things that may clash, like:

• parsers
• widgets
• filters
• fields
• css classes

I find that to be a more sensible approach which would also make plugins a little more discoverable. Then a dev could verify if their desired name was already used by something else.

This could be a simple github repo where authors are free to make a PR for their plugin listing.

Best wishes,

Tobias.

[Julian Kniephoff]

Hi Tobias

that's good to hear in the sense that I now don't have to feel bad for ignoring that guideline myself.

The GitHub-Repository idea sounds very interesting, even independently of namespacing issues. But in the long run, some kind of namespace system could be very useful. After all, I might really really want to pick a certain name for my widget, for example, even if I find out that it is already taken. ;)

Just a stray idea: Since TiddlyWiki borrows XML syntax (for widgets) already, anyway, something similar to the XML namespace system could maybe work?

I imagine a plugin author would specify a namespace URI (maybe the sourceURL that is already in the plugin.info file?) and then to use the stuff from the frobnicate plugin, you would specify a namespace attribute like

<$frobnicate twns="http://juliankniephoff.com/frobnicate">
Every named entity referred to in here is looked up in my plugin first
</$frobnicate>

Or, if you want to explicitly disambiguate things or be more explicit in general, you could give it a prefix:

<$jk:frobnicate twns:jk="http://juliankniephoff.com/frobnicate">
Every named entity referred to in here with a "jk:" prefix is looked up in my plugin first
</$jk:frobnicate>

As said, just an idea. Such a system would probably require much work very deep within the core of TiddlyWiki. :/

Best wishes,
Julian

P.S.: Sorry for the empty post earlier, I accidentally hit the wrong button ...

[Jeremy Ruston]

> However, I have yet to see a plugin follow this guideline. Is this still enforced/encouraged?

I think I wrote that right back in the beginning of TiddlyWiki5, when it was under development in 2011/12. Trying to learn from the experience of TW Classic, I was consciously trying to implement features that would help the community coalesce.

As it's turned out, I don't think using the author prefix in the widget/macro name is a good approach, because of the inevitable wordiness it brings.

Tobias' idea of a central registry is not bad; if you're interested in setting it up, then I suggest that structuring the registry as tiddlers in the tw5.com wiki, but open to suggestions.

Best wishes

Jeremy

[PMario]

Hi Julian,

On Wednesday, October 12, 2016 at 11:43:27 PM UTC+2, Julian Kniephoff wrote:

Just out of curiosity: On this page about TiddlyWiki plugins I read the following:

Plugins that define macros, views or other named entities are expected to prefix the name with their publisher identifier, for example:  tiddlytools.slider.

However, I have yet to see a plugin follow this guideline. Is this still enforced/encouraged?

It's encouraged for your plugins as in: $:/plugins/juliankniephoff/frobnicator  ... I personally would shorten the author section somehow, to have more characters for the plugins, without everything being too long.
 

... should these be called $juliankniephoff.frobnicate, juliankniephoff.frob and juliankniephoff.frobnicated respectively?

IMO nobody would like this. So for me it's still a "first come / first serve" for widget and macro names. ... BUT ... If you have a nice and short prefix for your calls, it may help in the future. .. I'm thinking about 2 to 3 chars max.

The problem for me is, that getting the names right needs some iterations. So you can go with an
 - alpha version number eg: 0.0.1 first ... So everyone should be OK with name changes. ...
 - Second step beta eg: 0.1.0 ..
 - And if you think you don't change names anymore V 1.0.0.

see: semver.org, which TW tries to use :)
 

(Of course none of this means anything. I'm just curious about the convention.)

Good catch, and nice that you think about naming conventions :)

-mario

[Julian Kniephoff]

On Thursday, October 13, 2016 at 1:17:44 PM UTC+2, Jeremy Ruston wrote:

> However, I have yet to see a plugin follow this guideline. Is this still enforced/encouraged?

I think I wrote that right back in the beginning of TiddlyWiki5, when it was under development in 2011/12. Trying to learn from the experience of TW Classic, I was consciously trying to implement features that would help the community coalesce.

As it's turned out, I don't think using the author prefix in the widget/macro name is a good approach, because of the inevitable wordiness it brings.

Should this note be removed from the page then? Should I create an issue and/or pull request for that? Maybe it could even be replaced by (some of) the advice by Mario?
 

Tobias' idea of a central registry is not bad; if you're interested in setting it up, then I suggest that structuring the registry as tiddlers in the tw5.com wiki, but open to suggestions.

A question regarding such a registry that came to my mind is: How does this interact with the plugin library mechanism? I don't know much about that, yet, but I figure there is at least some overlap between its goals and the goals for such a central repository. Maybe some of that stuff can be repurposed and/or integrated.

Best wishes,
Julian

[Tobias Beer]

Hi Jeremy,

 

Tobias' idea of a central registry is not bad; if you're interested in setting it up, then I suggest that structuring the registry as tiddlers in the tw5.com wiki, but open to suggestions.

While I think it should be easy to cross-reference (via helper macros), I think the full listing should not be part of tiddlywiki.com directly, if only to not overload it with content, however definitely be part of the TW5 repo.

I'd be happy to build a plugin-registry type of wiki somewhat like these two, bit simpler:

• http://customize.tiddlyspace.com
• http://tobibeer.github.io/tw5-plugins

...but of course revolving around plugin metadata only, no full blown documentation, or live examples, just abstracts, perhaps some demo code, categorisartions, and perhaps some way to preview via screenshots, not sure.

This should probably be accessible at:

• http://tiddlywiki.com/plugins

Best wishes,

Tobias.

[Tobias Beer]

Ok so,

however definitely be part of the TW5 repo. 

 

... 

 

This should probably be accessible at:

• http://tiddlywiki.com/plugins

I've expressed that a bit ambiguously.
Of course, I meant being its own repo,
but accessible at the above address,
so under similar supervision whereas I'd want
to be maintaining the master branch.

Best wishes,

Tobias. 

[BJ]

we could have some kind of namespace switching, eg  for widgets, we have when defining widgets

exports.['mywidget']exports.set = SetWidget;

which sets up the name 'mywidget' . If we have the convention to additionally provide another qualified name like this:

exports['bj.mywidget'] exports.set = SetWidget;

so another clashing definition of 'mywidget' could be

exports['anon.mywidget'] exports.set = SetWidget;

then we could have a pragma to 'tell' the parser (the html rule in this case) to override the 'mywidget' with a choosen prefix.
Obviously prefixes should be publish somewhere.

BJ

[BJ]

another sightly different way would be to automatically prepend the plugin name to the widget name to form an alternative name using an api function eg

defineExport('mywidget')

inplace of

exports['mywidget']

where the 'defineExport' would set the addition
exports[pluginname+'mywidget']

and have a pragma to 'focus' the name 'mywidget' to a particular plugin, within a tiddler.

[David Szego]

I hereby nominate Tobias's excellent ` (backtick) macro and <<plugin-docs>> macro as the standard by which we should all wrote our plugin documentation to, and it should be part of the TW core so we can just include the right pluginname-info / pluginname-syntax etc. Tiddlers when we package up our plugins.

All in favour? Go look at his plugins for examples... Fantastic documentation.

[PMario]

Hi David,

On Sunday, October 16, 2016 at 2:03:53 AM UTC+2, David Szego wrote:

I hereby nominate Tobias's excellent ` (backtick) macro and <<plugin-docs>> macro as the standard by which we should all wrote our plugin documentation to, and it should be part of the TW core so we can just include the right pluginname-info / pluginname-syntax etc. Tiddlers when we package up our plugins.

Not everything, that is a good fit for one usecase "documenting plugins", is a good fit for the general purpose core. I think it it good as it is: a plugin.

 ... BUT ...

We definitely need to enhance the mechanism, how plugins can be explored and good plugins can be identified!

just some thoughts.
-mario