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?
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.
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.
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 |cellsIt'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.
Linebreak restriction removed from Creole 0.3.
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:
- <a> tag has no "alt" attribute in HTML, http://www.w3.org/TR/html4/struct/links.html#edef-A, and never ever had, http://www.rfc-editor.org/rfc/rfc1866.txt
- the solution you prose seems to be pretty unpredictable in behavior
- the solution you propose is not compatible with any wiki out there
- what's wrong with the current solution? what exactly are you trying to fix?
- the regular expression for URLs exactly as they are defined in the RFCs is a little complicated, http://foad.org/~abigail/Perl/url2.html, and hardly usable, http://foad.org/~abigail/Perl/url3.html
-- 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 :
- I have one existing wiki page called Foo. [[Foo|Bar]] would generate Bar.
- I have one existing wiki page called Bar. [[Foo|Bar]] would generate Foo.
- 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:
- Creole "support" of implicit links
- The order of the text and the target (should we care?)
- The markup itself "[" "]" and the field delimiter pipe "|". (I think we have a consensus on that point).
- 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