Proposal#

The MediaWiki syntax for transclusion:

{{pagename}}

is immensely useful in tagging pages for various purposes. I think we should have something similar. We can now do

[{InsertPage page='pagename'}]

but it's a bit complicated to do. Also, transclusion should set certain variables (like $pagename), which the IncludePage plugin does not do at the moment. It's also one of the key features of WikiCreole for image inclusion.

So, the proposal is to define a new syntax which functions as a shorthand for the InsertPage plugin, and enhance InsertPage as well to handle things like image, attachment and random web-page transclusion.

Unfortunately, we're already using the "{{" code for typed text.

How about

<<pagename>>
<<pagename param1=foo param2=bar>>

Though this would clash with WikiCreole plugin syntax.

Discussion#

I don't see an alteration in the transclusion syntax as being so important as fixing the InsertPage (and TranscludePlugin) to properly do transclusions. If I had a firm set of requirements (hint hint) on what was necessary I'd look into fixing the TranscludePlugin. If we really need a shorthand (and I'm far from convinced that we do, i.e., the proposed solutions above aren't any better than the existing plugin syntax IMO) I'd hope we could do it without forcing fundamental changes to our basic parsing.

It's also a really bad idea to use markup characters (<>&'") within a system that is heavily using markup (HTML, XHTML, and XML, frontend and backend). This not only puts heavy requirements on escaping, it really opens up the likelihood of hard-to-track bugs. I just don't see the existing plugin syntax as that onerous. If any new syntax isn't actually any simpler it's likely more confusing to users to create yet another syntax construct. If they learn how to use plugins they'd know how to do transclusions (which aren't that common anyhow).

-- MurrayAltheim


JSPWiki2.6Feature


I'd agree with Murray about the use of '<' and '>' characters -- it might make it problematic for Wysiwyg XHTML editors too, although I'm not completely sure..

--David Au, 28-Feb-2007

It's also quite easy to subclass the existing plugins (either InsertPagePlugin or TranscludePlugin) and take advantage of the relatively new ability to get the plugin command line via Plugin.CMDLINE, parsing it for the page name rather than requiring a parameter, which could reduce the syntax to:

  [{Insert pagename}]
I see this as a much more attractive alternative to any new syntax. I've gone ahead and uploaded an InsertPlugin which does as advertised above. This took all of about fifteen minutes, including upload and documentation time. We'll see if Janne is interested in including it in the core, otherwise I'll include it in the CeryleWikiPlugins package. -- MurrayAltheim


A big issue is that transclusions are so useful that I would rather make them language-independent. That is, not rely on the English word "Insert". The angle brackets were just an example; we have plenty of other options.

@@pagename

or

@@pagename param1=foo param2=bar

(Note that this assumes that transclusion does not happen in the middle of a paragraph.)

--JanneJalkanen, 28-Feb-2007


BTW, the Insert plugin is a good start - I just want to get rid of the word "insert" here :) (partly also because it gets confused with "include" quite a lot.)

--JanneJalkanen, 28-Feb-2007


The reason why transclusions are not common is that they're hard to do. If you look at Wikipedia, you will see that they use transclusions extensively; partly because they can build a lot of useful things around them.

--JanneJalkanen, 28-Feb-2007


Actually, to continue in our earlier trend of using '[' as a link/plugin char, this should work:

[(PageName param1=foo param2=bar)]

--JanneJalkanen, 01-Mar-2007

But why is this new proposed syntax any better than the current syntax? It has the same number of characters, so it seems that it only provides a source of possible confusion. My take on this is that we should probably recommend a normal plugin usage (either InsertPage, TranscludePlugin or InterWikiPlugin) for any transclusions that require parameters (i.e., complexity) but have a very simple shorthand (e.g., "@@pagename") for those that don't, with the latter just calling InsertPage. I personally like "@@pagename" as that shorthand.

--MurrayAltheim, 02-Mar-2007

It does not have the same amount of characters. Compare

[{InsertPage page='Foobar'}]
[(Foobar)]

Same functionality, but a lot less typing. In fact, the MediaWiki {{ }} -standard is pretty nifty, because it's really fast to type.

-- JanneJalkanen

Yes, but the example to compare it with is really

[{Insert Foobar}]  
though I understand your reticence about the English word "Insert" in there. But there's a ton of other English-isms already (e.g., RecentChanges, all other plugins and their parameter names, etc.) so I'm not clear why transclusion syntax is a special case. I'm just wary of a new syntax that looks like plugin syntax but isn't — it just seems ripe for confusion. Any reason not to use "@@pagename" as I suggested? That could even be in the middle of a paragraph (and I think permitting transclusions anywhere, not just on their own line, should be a requirement, much like use of variables). That is, unless we expect transclusions to always be wrapped in a <div>, in which case they probably should be on their own line (as they will be in the generated XHTML).

-- MurrayAltheim


No particular reason. @@pagename should work nicely. You can even do paremeters with @@pagename(param1=foo), if you really want to. This way transclusion becomes essentially an user-definable plugin. The point is not to pass the parameters to the page insertion plugin, but as variables to the page, if you get my meaning.

--JanneJalkanen, 02-Mar-2007


The @@pagename(parm=foo) would be very nice, indeed. IMHO, more usable than the current [{ }] syntax. Why not keep this inline with the plugin syntax. In fact, calling a plugin is like inserting info in the page, the info is just generated on the fly instead of coming from the page repository. Thus @@pagename or @@pluginname would be perfecly compatible. (this would imply that name clashes need to be resolved)

The same similarity could apply to the parameters. When adding parameters, they act as page parameters for the insert included page; or act as plugin parameters for the called plugin. Thus @@pagename(parm1=foo1,parm2=foo2) or @@pluginame(parm1=foo1, parm2=foo2) would be compatible. //However, there is something to look out for: the _body parameter. Plugins can have body content. Such content needs to get a closing bracket; the closing ) may not be the right choice.

@@pluginname(parm1=foo1, parm2=foo2

  some inline content
)
or in standard syntax
[{pluginname parm1=foo1, parm2=foo2

  some inline content
}]
An alternative to the brackets, could be to use a closing /@, only incase of parameters. Thus, @@pagename or @@pagename parm=foo@@ or @@pagename parm=foo/@. (inspired by the %% syntax) This would lead to a better syntax for the _body parameter.
@@pluginname parm1=foo1, parm2=foo2

  some inline content
@@

BTW, would it be allowed to nest the syntax? EG @@pagename(parm1=@@pagename2)

--DF, 03-Mar-2007


Dirk, I'm wary that this idea is getting a lot more complicated than is necessary. We have a reasonable and functional plugin syntax and I see little requirement to merge that with our existing transclusion features (which are supplied by plugins). So to me there's two things at issue: improving the features and or functionality of our existing translusion features (i.e., adding features or fixing bugs or inconsistencies); and creating a simple shorthand for simple transclusions (i.e., entirely a syntax shortcut handled by the parser and likely handing off the actual work to one of the existing plugins).

One of the things I learned over many years of doing standards work was the Pareto principle or "80/20" rule, which (paraphrased) is that 80% of the effort can be accomplished by 20% of the design. So if making things more complicated really only helps out 20% of the people (in my experience, much, much less than that), then it's a hard argument to accept on need, more likely classed as over-engineering. If our wiki users were all geeks, programmers and/or engineers (or people who like complexity for complexity' sake) then great. Otherwise I'm not sure this is such a good idea. My target audience is my Mom (or more generally, people like her), not 24 year old male programmers.

-- MurrayAltheim, 04 Mar 2007


Murray,

Yep, let's first check our Mom's opinion on the new @@syntax. ;-)

You're right on the two issues discussed here: (i) additional features for the current plugins, (ii) improved syntax.

The point I was trying to make, is that we should avoid to introduce additional syntax. If the syntax is ok voor inserting a page, it should be ok for inserting content generated by plugins. Compactness of the syntax is key, also for our Moms.

When sticking to the current syntax, this would mean that [ThisIsALinkToAPage ] and [{ThisIncludesAPageOrPlugin }]. The Insert plugin actually becomes a feature of the engine. This is more consistent for the user.

--DF, 04 Mar 2007


Dirk, I'm not sure I understand. Our current plugin syntax is [{PluginName body}]. Are you suggesting that whenever the PluginName can't be found we assume it is a page reference?

-- MurrayAltheim


Yes. We could decide the opposite (first check the existance of the pagename) but I think giving the plugin priority is better. E.G. [{TableOfContents }] includes the table of contents, [{Sandbox}] includes the page Sandbox.

--DF

I was hoping you hadn't suggested that. I dunno, my first reaction is the hair on the back of my neck rising — it just seems to violate all sorts of ideas regarding the mixing namespaces of plugins and page names, etc. I certainly wouldn't want to implement this myself. The difference between [{Insert pagename}] and [{pagename}] is that one clearly suggests what is actually to happen using a keyword and conforms with other syntax within the wiki, the second mixes the plugin name and page name namespaces and provides no clue as to what is to happen. When one has mixed the namespaces, how does one (a) include a page whose name is also a plugin, or (b) invoke a plugin whose name is also a page name? We give priority of one over the other, but the other alternative then doesn't work.

I really don't see that we gain very much here at the expense of confusion. If the big argument is that "Insert" is in English, that argument can be made about every other plugin in use. Aliases can be made to those plugins if people are really up in arms about the transclusion plugins being in English (somehow as apart from all the rest of the content in English), but I don't see this as any advantage to [{Insert pagename}] (which is very clear as to intent) or @@pagename as a shorthand for that. I'm also unclear as to the need for parameters being passed along with the latter by creating an altogether new syntax; if the user is sophisticated enough to use page parameters they are sophisticated enough to use the plugin syntax, since by the time one adds the parameters the difference between the current and proposed syntax is only a few characters.

There's also the fact that we currently have two different translusion plugins, InsertPage and TranscludePlugin, with another (InterWikiPlugin) in the works. We could try to consolidate all three but my take on this entire conversation is to create a way to do simple transclusions by providing a shorthand for InsertPage, with all other more complicated transclusions handled by the existing plugins. I just don't see any need for a new complicated, alternative plugin syntax, nor any of the suggestions so far really as improvements. I'd simply alter JSPWikiMarkupParser to handle @@pagename as an alias for [{Insert pagename}] and declare victory.

-- MurrayAltheim


I don't think we should mix the namespaces for pages and plugins - it's too brittle. Either someone goes and renames a page or installs a plugin by the same name or creates a page with the same name and it'll all break down. Remember, the page namespace is not under the control of administration.

So, while a cool idea (and I understand the reasoning behind it), I would still rather keep the namespaces separate.

--JanneJalkanen, 05-Mar-2007


So, I just read the entire preceding page after deploying the InsertPlugin into our wiki's to allow [{Insert pagename}]...

I intensely dislike the proposed syntaxes... Ease for our Mom's is not judged by character count! The @@pagename stuff is dumb in my opinion. It's yet another bit of special syntax that our users will have to learn and remember...

Janne your point that Insert is an English word is a valid thing to be addressed. Murray your point that Janne is being <ahem/> selective in his criticism is also valid.

How about this as an alternative... Recent versions of JSPWiki have taken on i18n as a feature; extend this to plugins... Use the existing plugin syntax and allow for translation of the plugin name. This way all plugin names can be given in users native languages: Insert and RecentChanges and so on...

How could this be done is fairly easy (I think) we already go thru the plugin search path trying to load the user specified plugin class, we can add there a step of asking the i18n 'subsystem' to translate the name from Native to English.

Is this at all clear? -JVolkar 7-Apr-2007

--John Volkar, 07-Apr-2007


I'm not too sure whether that's a good idea either, as that'll probably break things like our WYSIWYG editors.

Have you guys taken a serious look at how Wikipedia uses transclusion as an integral part of the system? It's essentially a mixture of tagging and metadata system, which still uses the power of the wiki to do some pretty inventive stuff. It's kinda like allowing your users to define their own very simple plugins without any knowledge of Java coding. That's the kind of ease-of-use I would like to also have in our system.

--JanneJalkanen, 07-Apr-2007

Janne, could you provide a reference to the Wikipedia method you're talking about? Thanks.

-- MurrayAltheim, 10-Apr-2007

It's below in David's comment.


BTW, the current InsertPage syntax would not be changed, so nobody would need to learn anything new, if they didn't want to.

--JanneJalkanen, 07-Apr-2007


I don't know if the idea about translating the plugin names is a good one or not, or if it'll break anything else, but from what I understand, it shouldn't break WYSIWYG editing with FCKeditor though. For instance, if the user had used the InsertPlugin in German: [{Einsatz pagename}], the syntax should still be able to survive the edit/save roundtrips with FCK, since plugin execution is disabled.

I'm not too familiar with MediaWiki's transclusion capabilities, so I found a detailed page about it in their documentation. Haven't completely digested it yet, but I think the parameter substitution feature might be useful, while other things like conditional substitution seem rather complex.

--David Au, 09-Apr-2007

Add new attachment

Only authorized users are allowed to upload new attachments.
« This page (revision-30) was last changed on 10-Apr-2007 09:18 by JanneJalkanen