Feature Proposal: Deprecate the undocumented space delimited Square Bracket link format

Motivation

There is an undocumented format for square bracket links that uses spaces to delimit the URL, anchor and link text. ex.

• [[http://foswiki.org/ Foswiki Web Site]] http://foswiki.org/ Foswiki Web Site
• [[mailto:user@example.com Mail to example user]] mailto:user@example.com Mail to example user

Because space is used as a delimiter, it's not possible to include spaces into the URL or query string. This makes it difficult to make useful mailto: links such as [<nop>[mailto:support@somewhere?Subject=My support request&body=I have a problem with DeprecateUndocumentedSqBracketLinkFormat]]

Description and Documentation

Add a new expert Miscellaneous parameter documented as follows

# **BOOLEAN EXPERT**
# There is an undocumented "Legacy" format for square bracked links that
# is space delimited.  Format is <tt>[[URL Anchor Text]]</tt> where: 
# <ul><li>URL is an explicit URL like http: or mailto:
# <li>Anchor is an optional HTML #anchor and
# <li>Text is free form link text.  
# </ul>This format is incompatible with more modern use such as
# passing subject and body text into a mailto link, and other complex
# query params in html links.
# <br/><br/>
# As of Foswiki 1.1.4, this optional syntax can be disabled to improve
# compatibilty with richer query strings.  Enabling this option to disable
# use of <tt>[[URL Anchor Text]]</tt> style links.  If this option is 
# not enabled, then the user must encode spaces in the URL using "%20"
$Foswiki::cfg{DisableLegacyBracketLinks} = 0;

For 1.1.4, the default for this parameter would be false, For 1.2, default will change to true.

Examples

Impact

Enabling this option will break links that use this undocumented feature.

WhatDoesItAffect:

%WHATDOESITAFFECT%

edit

Implementation

-- Contributors: GeorgeClark - 23 Jun 2011

Discussion

I don't think this is right. The only place spaces are legal in links is in parameter values. "Old style" space delimited links don't support parameters. Therefore:

• If a link contains spaces but does not contain a ?, it is an old-style space-delimited link.
• If a link contains spaces and contains a ?, it must be a parameterised link with one or more parameters containing spaces.

No need for an option, just smarter link parsing.

-- CrawfordCurrie - 23 Jun 2011

We cannot deprecate the old format.

It is already deprecated and has been for years

So what this proposal in reality does is to suggest that the compatibility mode can be disabled to make way for more advanced uses of the square bracket linking.

And that is a really good idea. It would be wrong to take it out for those upgraders that have many old links that work this way. But we are all the way back to TWiki Athens and Beijing (1.0 and 2.0). Already in Cairo (3.0) the old format was deprecated.

So I am 100% supporting that we disable it by default and add an expert setting so those few that need the compatibility can enable it - at the expense that this disables the use of the advanced uses of square brackers.

But deprecate we do not need to. It already is and it has not been documented in neither TWiki nor Foswiki since 2004-2005. And if we start documenting a deprecated feature we are in reality waking a sleeping bear and in reality re-documenting what we wanted to be forgotten.

For the part that Crawford raised concern. It is true that you cannot put spaces in email addresses. But you can put spaces in the parameter text and we should allow that.

If we can let the parser safely see the difference between a space in a parameter and a space in an old URL format then automagic is a better solution than an expert setting. So I understand Crawford's concern.

-- KennethLavrsen - 23 Jun 2011

Crawford's solution appears to work fine. It is a simple change to test if the candidate URL component contains a ?, and if it does, then bail out to a conventional external link without the space delimiter.

So we might still want to have an option to disable the legacy format completely, but it's not necessary to fix Tasks.Item10905. I can't think of any case then where we need to disable the old format, though it might be desirable to allow an undocumented "feature" to disappear in the future 1.2.

-- GeorgeClark - 23 Jun 2011

Is it possible to make a plugin that renders the legacy format? If so, then those wikis with really really old content could use that plugin, which means there is no need for automagical parsing in the core. Instead, Crawford's suggested "smart parsing" logic would move to the plugin.

However, I'm not sure which handler that plugin should use. I'm not even certain there is a suitable one.

-- MichaelTempest - 27 Jun 2011

I don't have a stake in this one - but an observation. It would be useful to log uses of the (any) deprecated format. That would help managers/users find and fix what's going away. Could advertise/configure as an early warning feature to help avoid upgrade surprises. Logging "you are doing this bad thing here" before support is removed is more helpful than "but we told you it was deprecated years ago" when folks upgrade. Surprises (and fear thereof) are a (the?) major reason people don't keep up-to-date. And no, an entry in the README/Release Notes doesn't prevent surprises. Installers read those docs; content owners are a different audience and they need specific "fix this on these topics" guidance, not a generic "if you have something like this anywhere, you'll want to change it before some future release where in might go away." Content owners, like most of us, are interrupt-driven...

The other thing that helps is a fixit script. Except for links synthesized out of IF/QUERY/Search pieces, this would seem an easy candidate for a "run this script over your content before upgrade" script. fixit scripts should have two (maybe three) modes: Identify, Identify&fix, (and maybe Identify and query user to approve each fix). And that seems like no more work (and perhaps less) than a plugin.

These approaches have helped in other situations because they make it possible to actually terminate the deprecation process with removal. Not providing the tools leads to the "it hangs on forever" syndrome where we say something is not supported, but there's legacy code, compatibility plugins, and semi-custom support from developers for reluctant customers. All of which divert resources from higher-payback activities.

Not picking on this item in particular, it's just an example of a more general problem.

-- TimotheLitt - 29 Jun 2011

y, Timothe, I also dream of a 'recommendation' dashboard with on topic hints if deprecated / known suboptimal things are found on a topic. I really should try to make time to write a detailed enough proposal for it - cos that functionality can't come at the expense of normal usage speed.

There are a number of structural dashboards that would be useful :/

-- SvenDowideit - 29 Jun 2011

Please note that Crawford and George managed to find a compatible solution to the problem that maintains the old already deprecated syntax and accomodates the desire to support mailto links with spaces in the parameters.

So the whole purpose of the proposal seems obsolete now.

I suggest we close the proposal as not needed. George has already implemented the improvement as a simple matter of bugfixing.

-- KennethLavrsen - 29 Jun 2011

Changing this proposal to RejectedProposal. Since the old syntax is long since deprecated, and it doesn't really add any value to delete the handing or complicated the configuration, I'm withdrawing the proposal. There doesn't seem to be any way to gracefully withdraw, so rejected by consensus sounds good to me.

-- GeorgeClark - 05 Jul 2011