Place for discussion, refinement, and specification of the wicked linking syntax.

Currently (as 12/19/2005), wicked linking is very simple; anything within double-parentheses becomes a link, according to the linking algorithm implemented in wicked's filter module.  If there is a match, the link will resolve; if there is not, the link will create a new item.  This is nice and straightforward, but has some concrete drawbacks:

1. If the algorithm happens to choose an item that the user does not actually want to use as the link target, there's no way to override.
2. Unresolved links will create an item of the same type as the source content, i.e. a Page that supports wicked linking would create additional Page objects, while an Image that supports wicked linking (in the description, perhaps) would create additional Image objects.  It may be desirable to be able to explicitly override this.
3. It is currently impossible to separate the matched text from the text that is displayed on the page.  It would be nice to be able to have a link such as "My thoughts on the recent developments with regard to the wicked project" actually link to (or generate) an object named "recent-wicked-thoughts", for example.

For the purposes of this page, we'll use curly braces "{}" instead of parentheses "()" to denote wicked links, in order to prevent the links from actually resolving.  (Perhaps we need a way to explicitly negate links when we want to?)

All of these problems could be solved via a rich client-side (i.e. DHTML) interface to wicked link management, and it is our intent to provide such an interface.  However, we don't want to force people to use javascript in order to use wicked to the fullest... there will probably always be clients that won't support the richer interface, and power users will want to be able to do the linking quickly, w/o having to resort to navigating an interface when they already know what they are trying to do.

The reasonable step, then, is to extend the wicked linking syntax to support the uses listed above.  However, it is very important that the default wicked linking behaviour continue to work exactly as it does currently; we do not want to introduce complexity for the simplest cases, and we don't want to force people to master the advanced linking techniques before they can get started.  Also, the rich client interface for managing the links should actually generate the correct wicked link source, so that people using the rich interface can learn from this how to generate the links themselves if they should choose.

A proposal for meeting requirements number 2 and 3 involves using the colon character ":" to separate the item being linked from the text to display, and another from the type of object to create.  The colon is a good character to choose, because its use within URLs is restricted such that an item's name will never contain one.  The following examples show how this would work:

{{this link:The link of which I am speaking}}

This would display the link as the text "The link of which I am speaking", but the link resolution algorithm would be applied to the text "this link".  If a new page were created using this link, it's id would be "this-link".

{{create image::Image}}

This would display the link as the text "create image", which would create an image object named "create-image" if an object matching that link chunk did not already exist.  (If such an object did exist, the link would resolve to that item regardless of its type.)

{{create image:Create an image here:Image}}

This would display the link as the text "Create an image here", which would create an image object named "create-image" if an object matching that link chunk did not already exist.

TODO:  Figure out how to handle explicit linking, i.e. pegging the links to specific pieces of content.

Discussion

Please enable discussion on this topic. In the meantime, a proposal from a wicked fan:

I suggest that the default wicked syntax use brackets:  [[ link ]]. I personally think it looks cleaner, but more importantly, the user does not have to use Shift-character, as required for ( or { or : on american keyboards.

Also, for #1 could we not follow the unix approach and use an escape character before the link?  so if we want the literal, non-interpretted double bracket, we we type \[[blah]]  and if we're embedding links in windows paths (and therefore using the backslash), we just escape the escape... \\[[   --MartinM

Thanks for your ideas.  For the first option, we actually deliberately chose the parentheses over the square brackets.  You're right that they don't need the shift key on american keyboards.  However, the square brackets are very hard to find on many international keyboards.  And we want to make things easy for folks from all over the world.  :-)

For your other suggestion, I think you're misunderstanding the problem.  You're talking about when something shouldn't be a wicked link at all.  The problem I'm presenting, however, is when there are two possible matches to a wicked link, and the default algorithm selects the one you don't want.  --ra

I think your solutions to problems 2 and 3 would work very well, since this is similar to how other wiki systems work. For problem 1, why not use the same solution again? You could add the search path of the intended target separated by another colon into the wicked link. However, this obviously negates the requirement to define the type of object to create, since you won't actually be creating a new object when following the link. A link may then look like this:

    {{wales:Land of my fathers::/countries/eu/gb}}

This would only look for documents with an id of wales in the location /countries/eu/gb

--emzo