(anonymous guest) (logged out)

Copyright (C) by the contributors. Some rights reserved, license BY-SA.

Sponsored by the Wiki Symposium and the Nuveon GmbH.

 
This is version . It is not the current version, and thus it cannot be edited.
[Back to current version]   [Restore this version]

I just edited wikiohana.net an realized how hard the current order of "link first, description last" is to read in wikitext:

This Wisdom is taken from [[Ward Cunningham's]] [[http://www.c2.com/doc/wikisym/WikiSym2006.pdf|Presentation at the Wikisym 06]]
vs.
This Wisdom is taken from [[Ward Cunningham's]] [[Presentation at the Wikisym 06|http://www.c2.com/doc/wikisym/WikiSym2006.pdf]]

For people that read from left to right the last one is much better. Most or all of the western world I guess. What's the earth population percentage of people reading from right to left? I have no clue. Are the Chinese reading from right to left? hebrew does. Anyway...

What about changing this? -> from descr to [descr|link] in case left to right readers are the majority?

--Christoph 6-Sep-2006

I think we should have "nothing new" and therefore stick to the current convention.

What about whitespace around the pipe when renaming links? I think it should not be allowed. Thus: [[page|name]] and not [[page | name]], for all variants of links. What do you think?

-- AlexSchroeder

I'll accept the pipe - however, I see less clear precedent for putting the page title before the link text.

In general, 25 wikis on WikiMatrix support labeled links:

Page Title, Link Text Link Text, Page Title Both
16 8 1

Although I'll admit the bulk of the precedent (including both MediaWiki and TWiki) use the page title followed by the link text, I think this at least shows that there's a debate. (By the way, Confluence is among the wikis that give link text followed by the page title.)

Again, I tend to favor the idea of using the syntax:

 [[Text | Target Page]] 

I think it more closely imitates the intuitive thought process of a link; the text links to the page, so the target of the link is secondary information to the text of the link.

--Eric Astor

I use JSPWiki primarily at work and I tend to always want to put the link first (because I want to link to something) and then describe what it means. I also remember Janne Jalkanen saying that he would change that order if he had the chance now and at the time he was just blindly following PhpWiki syntax. In any case, twice as many engines use PageTitle, then Description, including MediaWiki, so I still think we should stick to this order. Also, if for some reason you cut and paste in HTML, you can just ditch the extra stuff around it to make the link instead of also having to also change the order in the wiki syntax.

--Chuck Smith

I'm also used to do [ url | text ] . Maybe it's a habit from html, or from the wiki engines I use most. Anyways, if you don't want to break your train of thought, the put the link text only, and then insert the links when you finish the article. I found this way the most comfortable. Or just use local names. -- RadomirDopieralski, 2006-09-07

I also lik the desription first notation, because it's much easier to read and understand. You first get what it's about and then the technical details (url/page/etc.). I also what to submit another syntax based on this. Please use the symbol greater then (>) instead of the pipe. First because it makes the order clearer.

[[this description is linked to>this page]]
Second because it is easier to use links with description in tables (if supported) without having to escape the pipe, as it is necessary in some engines. I think it could also be easier to implement then.
|a table |with [[a link>to a page]] |and other |cells
It's also easier to read then.

-- JörgGottschling, 2006-16-06

I'm against the introduction of such new markup.

I also think that the wording "Links should not be allowed to contain a linebreak" should be changed. What's the benefit of not allowing it? I see a benefit in not requiring this feature, but forbidding this features is useless crippling. I'm not planning on removing this features from my implementation, for example.

-- AlexSchroeder

Linebreak restriction removed from Creole 0.3.

--Chuck Smith

The spec should do the difference between an implicit and an explicit link instead of an internal and external one.

An implicit link is a fully compliant URI in the text as defined by RFC3986 - no non-RFC3986 schemes allowed. The URI must be complete - no relative-ref (see Appendix A of the RFC).

Example: By going to http://www.wikicreole.org, you will see[...]

(Should Creole eliminate implicit links altogether?)

An explicit link is made of a destination and an optional description (or the other way around?) enclosed between two square brackets. These two parts are separated by a pipe character.

The destination (target) can be the title of a page, an InterWiki link (InterWiki standardization effort), or a fully RFC3986-compliant URI-reference.

The description part in a link could mean different things depending on the order:

  • [[Hyperlinked Text|Target]] i.e. Hyperlink Text
  • [[Target|Alternate Text]] i.e. <a href="Target" title="Alternate Text">Target</a>

In my experience, the former would work pretty well with external links and the latter with internal ones.

So, my suggestion is this:

[[Hyperlinked Text|Target|Alternate Text]]
with the text and alternate text part optional. If there is a possible ambiguity, resolve it as [[Text|Target]]. Ex.:

1. I have one existing wiki page called Foo.
   [[Foo|Bar]] would generate <a href="Foo" title="Bar">Foo</a>

2. I have one existing wiki page called Bar.
   [[Foo|Bar]] would generate <a href="Bar">Foo</a>

3. I have two existing wiki pages: Foo and Bar.
   [[Foo|Bar]] would generate <a href="Bar">Foo</a>

Note: The rendering could be completely different depending on the implementation. Alternate text could be presented like hyperlinked text if none is present...

In the first example, a problem arises when someone creates a page called "Bar" afterward... The rendering will change for the one in example 3.

Also, how would I say in Creole something like: <a href="Foo" title="Bar">Foo</a> if I have two existing wiki pages : Foo and Bar. The easiest solution is to write empty parts: [[|Foo|Bar]].

Another possible solution is to "escape" one part or the other with quotes ("") - or another markup - to explicitly define the text or alt text (don't like that one).

Finally, with the special syntax of InterWiki links and URIs, there should not be any ambiguity, only possible misleading from potentially mischievious users. Ex.:

[[http://www.google.com|http://www.myphishingsite.com]]

Just thinking aloud... Any ideas? Do I make sense?

-- EricChartre, 2007-01-01

Oh! and BTW, if the URI are compliant to RFC3986, and internal/InterWiki links do not contain spaces, it would be possible to use a space as a delimiter instead of a pipe.

If a target does contain spaces, it must be enclosed between quotes.

-- EricChartre, 2007-01-01

Should Creole accept IRIs (RFC3987) instead of URIs?

-- EricChartre, 2007-01-01

I don't want to bring you down, but:

-- RadomirDopieralski, 2006-01-02

Sorry Radomir. I made a couple of mistakes indeed and I could have been more concise and to the point (should not have put any rendering suggestions). Also, forget about that whole title/alternate text thing, that is not what I meant. I just want to make the order less relevant.

My points are:

  • Explicit vs implicit links
  • Implicit links are not showed in the Links page as they are on the Creole 0.3 page...
  • Even if it breaks the "Extensible by omission" principle a little, should Creole standardize the different syntaxes of targets (especially for implicit links) so that nothing breaks when exchanging Wiki texts?
    • Internal target
    • InterWiki target
    • URI (RFC3986)?
  • If the spec does not make the syntax of targets more formal, I think it could generate collisions with the chosen markup and delimiter, whatever they are.
  • When you look at WikiMatrix internal/external links comparisons, the meaning of the description part of the link changes somewhat between internal and external links and the position (order) of the description in the link. If Creole accepts any order, it could generate ambiguous situations but make the order less relevant. So let's try again :
  1. I have one existing wiki page called Foo. [[Foo|Bar]] would generate Bar.
  2. I have one existing wiki page called Bar. [[Foo|Bar]] would generate Foo.
  3. I have two existing wiki pages: Foo and Bar. [[Foo|Bar]] would generate Foo (hyperlinked text is the first part of the link by default).

The questions are:

  • How could Creole make the third example less ambiguous if the order is not relevant?
  • In the first example, a problem arises when someone creates a page called "Bar" afterward... The rendering will change for the one in example 3. Is that OK?
  • What if the markup/delimiter is part of the Text or Target? (That's a recurrent question for any markup)

So, IMHO, we have a couple of things to settle:

  1. Creole "support" of implicit links
  2. The order of the text and the target (should we care?)
  3. The markup itself "[" "]" and the field delimiter pipe "|". (I think we have a consensus on that point).
  4. How formal the syntax of the target should be

-- EricChartre, 2007-01-02

Thank you for your clarification, I think I understand it better now. Personally I'm still somewhat charmed by the (mentioned before here) approach you suggested recently -- defininng only the absolute minimum we really need for interoperability and disambiguing things, and leave as much detail as possible to the implementers.

On the other hand, I agree that the details you mentioned can be problematic and thus should be defined. We can take the following approach:

For URLs in text (without any markup), use somewhat generous matching algorithm, for example a regexp like \w+//:\S[^,.:;?!|'")\]\}\s]. Obviously, this is not correct implementation -- it won't match legitimate urls ending with a comma or dot and such, and it will match more url-like things that are really defined. But it follows the usus. People often put commas or periods or other punctuation right after the ulrs in the text. At the same time, sane URLs rarely even use these characters (except the dot), not to mention ending with them -- you can always use the [[...]] markup to force them.

For the URLs in links (with the [[...]] markup), I'd say that anything that matches '^\w+:' is an URL (external link), while anything else is a page name (some wikis can also check the validity of the page names and refuse to parse malformed links, of course).

The text and target order problem is in my opinion impossible to solve without introducing a totally new markup for links (so that it doesn't collide with existing ones). As you noticed, your approach can change the links of an existing document -- it may be an old and established wiki page, and the change can make it say something totally different than before, and the change won't even appear in the recent changes. That pretty much breaks peer review -- one of the most fundamental mechanisms in wikis.

The used order has an additional advantage -- since the "|" character is forbidden both in URLs, and in most wiki page names, you don't need any kind of escaping, and you can freely use additional pipe characters in the link text. It would be impossible the other way around.

What do you think, is it enough? -- RadomirDopieralski, 2006-01-02

One thing that '^\w+:' would limit is mailto:, (think news: too) links. -- JaredWilliams, 2006-01-02


Questions#

First I wondered why the creolemarkup-wiki doesn't follow it's own rules - but now I think it's maybe not possible to develop a new standard and use it at the same time. Is this the reason? -- For example: To set an external link the markup is very uncommon --Daniel Brüßler ( info-danielbruessler-de )
[the link-name|http://www.the-url.org]

Welcome Daniel to Creole Wiki! Indeed, the Creole parser for JSPwiki is being developed, but slowly. In the mean time, we try the markup on a number of Wikis using Engines that already have (at least partial) Creole support. Obviously, having to convert all the pages every time there is a change in spec would be very uncomfortable. For now, we must bear with the non-standard syntax this wiki engine uses, and get even more motivated by it, so that our children don't have to suffer the same!

-- RadomirDopieralski, 2006-01-06


The link syntax, particularly relative order of text and link, is one of the biggest issues needing to be resolved for reconciliation with the Crossmark draft spec. My current recommendation is that we follow the PmWiki usage, which is also similar to PukiWiki and Netcipia except for choice of delimiter.

Specifically, the favored link syntax should be [[text of link -> link]]. For compatibility with the majority of Wiki usage, especially MediaWiki, we can also support [[link|text of link]]. Minimalist or purist subsets of Creole can omit this alternate syntax. Chuck Smith, above, has indicated a preference for this alternate syntax, so it would give him extra user freedom too, at the expense of slightly more parser complexity and the potential confusion of readers seeing both syntaxes.

Ivan, the first author of Crossmark, feels strongly that putting the text first is more natural, and that the link-first syntax is an artifact of a poorly thought-out wiki implementation. The current Crossmark draft follows the JSPWiki convention, and, as discussed extensively above, it's very confusing, especially people used to other wikis. Ivan has expressed a definite willingness to change the syntax, and has been considering the PmWiki style anyway.

Because it's used by PmWiki, it's NotNew. I believe it also satisfies the goals of ReadableMarkup and EasyToLearn, because -> has the intuitive meaning of "go to," visually resembles the presentation of external links on many wikis, and telegraphs which way is which, something that has been poisoned for pipe given that there seems to be a 1/3, 2/3 split among wiki engines.

-- Raph Levien, 2007-01-11

For the record, I said above that I wanted the link to be first and then the description. Anyway, if others like it, I could be convinced that using -> is a very clean and intuitive link syntax. I'm curious to hear opinions of other Creole participants.

-- ChuckSmith, 2007-Jan-12

I feel strongly that putting the title first and link second is more natural, and far more readable than link first, title second, which is pretty much an artifact of how HTML works. However, whether the delimiter is "|" or "->" does not matter to me much. The latter is clearer, though considerably slower to type, since it seems to in practice require spaces around itself.

-- Janne Jalkanen, 2007-Jan-14.

Just a loose suggestion -- if we are going to use an additional link markup, why don't we tacle the InternationalizationConcerns (phew, now I know why they type i18n)?

Another option would be to not define the markup for links with different link text for internal pages -- in external links the order can be detected. But that's rather dodging the problem, and it would cause problems when actually using it...

Another possibility -- only have special markup for the link text?

But in general, this is a very broad topic... How should we tackle it? Should we at all? -- RadomirDopieralski, 2007-01-15

I changed a little the advantages and disadvantages, still fail to see:

  • How one of the markup is "intuitive" and the other is not. What does "intuitive" mean at all?
  • How the "->" markup is better for international keyboards?
  • How the order of link/description is obvious? I initially thought it's [[link -> description]].
  • How does it work with right-to-left scripts?

By the way, as I see it, the problem is only with the internal links with different link text -- the address in an external link can be easily detected, and there is no description in simple internal links:

  • [[http://some.external/link]]
  • [[http://some.external/link|external link]], [[external link|http://some.external/link]]
  • [[some internal link]]
  • [[some internal link|internal link]] <-- here is the problem

On solution that is keyboard-friendly and conflict-less is:

  • http://some.external/link
  • http://some.external/link(external link), (external link)http://some.external/link
  • ((some internal link))
  • (internal link(some internal link)), ((some internal link)internal link)

but I think it's too exotic :)

-- RadomirDopieralski, 2007-01-16

On the main page for this proposal, Chuck Smith lists "really confusing on right-to-left languages like Hebrew." I'd like to hear from real Hebrew or Arabic speakers with Wiki experience (my codeveloper on Ghestalt is Israeli, so I can ask him), but as far as I can tell, this assertion is simply wrong.

Here's what both link styles look like in your browser:

אירופה היא אוסף של [[חצי אי|חצאי איים]] מחוברים.

אירופה היא אוסף של [[חצאי איים -> חצי אי]] מחוברים.

And the result should look something like this:

אירופה היא אוסף של חצאי איים מחוברים.

In both cases, the text to be rendered is two 4-character words, and the target is a three character and a two character word. If anything, the arrow is considerably less confusing, because it always points at the link.

-- RaphLevien, 2006-01-16

And then they want to link to an English language resource (maybe also with a Hebrew description), which way should the arrow point then? But yes, I'd also like to hear from someone from Israel. I would be against allowing arrows in both directions, because I think that would just add to the confusion.

-- ChuckSmith, 2006-Jan-17

Reversing -> should lead to >-, which is very confusing.

-- MicheleTomaiuolo, 2007-01-17

We really, really need someone with Bidi experience to enlighten us. But the arrow is reversed in presentation. The string is ' -> ', and I did not change my link regex in any way to accommodate rtl languages. Bidi is inherently confusing, and this arrow reversal was new to me, but the goal here is not to add to existing confusion.

The examples above were all-Hebrew, but I did some poking around into links with a URL target, which of course needs to be a LTR span because it's in ASCII. Basically, as long as the primary direction is marked as "rtl" (this is an attribute of the top-level html tag, and can be overridden through an inheritance mechanism), it looks pretty good. The arrow points to the left, and the URL appears to the left of it, exactly as in the all-Hebrew example.

If the direction in the HTML is left as LTR (as is the case on this wiki), then the all-Hebrew links are still fine, but the mixed-direction ones are a total hash. This is definitely true for both alternates, and imho the hash is equally undecipherable in both cases. But again, I think this is an issue for HTML-based Bidi applications in general, and not something that's within our scope to try to fix. I did note that both Mac TextEdit and (Carbon) Emacs did a much better job in these cases, presumably because they use a heuristic to determine the text direction rather than relying on HTML markup. Thus, messing with this stuff in an editor is a viable option. I also observed that ASCII link targets within sentences are exceedingly rare. Link targets within sentences are overwhelmingly Hebrew, and when ASCII link targets occur, they seem to stand alone, for example as a bullet item. I do not know if this tendency is influenced by Bidi glitches, or is a matter of style, but in either case it would seem to keep the incidence of hideously confusing Bidi mixing to a minimum.

Therefore, my assertion that the arrow is less confusing stands.

People who want to experiment with the proposed link syntax are welcome to use the Ghestalt sandbox. You'll have to create an account to get edit permissions (otherwise, I fear, the site would be overrun by spam), but Creotians are more than welcome.

-- RaphLevien, 2007-01-17

Add new attachment

Only authorized users are allowed to upload new attachments.

« This particular version was published on 17-Jan-2007 18:13 by RaphLevien.