There are almost as many ways to make links on a wiki as there are wiki engines. Since one of the raisons d'être of this wiki engine is to experiment with such things, it follows that we need a discussion page.

First off, some history. I started out wanting everything about this wiki to be as close as possible to Ward’s wiki, because, once I (thought I) understood the whys and wherefores of that wiki, many of its seemingly odd features (such as CamelCase linking) made sense. Taken as whole, not each feature separately and out of context, the design has an appealing simplicity and elegance.

There are, however, features I miss (in Ward’s wiki), and since link-making is one of the most important aspects of a wiki, I wanted several methods available.

Linking methods

CamelCase

The classic, and simplest, is CamelCase linking. You write two or more capitalized words, smashed together, and you get a link. Whatever other linking methods are available this kind of linking shouts “classic” wiki. That can be a bad thing, and in fact the Wikipedia people turned off CamelCase linking after the first year or so, I think in part because they wanted Wikipedia to look like a “normal” web site and not like a wiki.

In the presence of inter map and interwiki linking, keeping CamelCase linking on this wiki is a given. Sort of.

Bare URIs

This, with CamelCase, are the only two methods available on Ward’s wiki. You write out a full URI, like

  http://freebsd.org/handbook/

and the wiki engine converts this to

  <a href="http://freebsd.org/handbook/">http://freebsd.org/handbook/</a>

thereby creating a link that looks like this: http://freebsd.org/handbook/. It looks a bit ugly, but it’s very general.

If the URI referenced an image (a link with file extension gif, jpg, jpeg, or png) the wiki engine creates an “inline image” link to display the image; thus,

  [[img http://www.freebsd.org/gifs/dae_up3.gif beastie!]]

produces the following HTML

  <img src="http://www.freebsd.org/gifs/dae_up3.gif" alt="beastie!">

and, rendered, it looks like this: beastie!

(I don’t like this method of matching images. It violates my principles, since I don’t want to see file extensions in URIs. I put the code in the wiki to make this example work, but I’d like to discover another way to do this.)

(BTW: I changed the link markup so that an alt text (beastie!) is required. This is to conform with the XHTML standard.)

It sounds worse than it is. Generally it involves a bit of markup syntax. At this point we depart from what was implemented on Ward’s wiki, and there are many different ways to proceed.

I’ve adopted, temporarily, the following method: Typing

  [[http://freebsd.org/handbook/]]

creates a link that looks just like the bare URI example above, and it generates the same HTML markup. It looks like this: http://freebsd.org/handbook/

We could call this the unnamed link style. Then there are named links: You write them like this:

  [[http://freebsd.org/handbook/ How to understand and use FreeBSD]]

This would generate the following HTML:

  <a href="http://freebsd.org/handbook/">How to understand and use FreeBSD</a>

and render like this: How to understand and use FreeBSD.

Write this:

  [[mailto:johndoe@example.com email me]]

It renders as email me. The email address (“johndoe@example.com”) is encoded in a way that should help foil spambots. The link text (“email me”) is necessary, and should be something other than your email address!

I used to have what I call “extended links” available but I turned them off because they get in the way of too many other constructs. An extended link is like a CamelCase link in needing no “extra” syntax; it simply uses a different pattern structure. Instead of two or more capitalized words, it was two or more words (upper- or lowercase) joined by underscores (_).

You don’t really need this, and it’s not general enough in any case: it still doesn’t give you a way to make links to pages with single-word titles.

I think a better idea is to have a second type of forced link for intra-wiki links. One possible syntax is to enclose the word in single brackets, thus:

  a link to a boring [dog] page.

This links to a page called “dog”.

Having opened the can of worms, I’m going to go away for awhile. ;-)

Yeah, the extended links thing was not good. One thing I actually like about the yaws wiki is the deprecation of CamelCase and the use of ~.

 ~Pagename

or

 ~PageName

work equally well. I don’t necessarily want to use two or more names for every page.

I do like the forced link idea. I’ll take some of the worms and go fishing. ;-)

BTW, I wasn’t done yet. I had to go and see a movie. ;-)

The yaws wiki’s use of ~ is a version of “forced linking”. Instead of having the engine recognize certain structures (eg, CamelCase wiki words) and automagically create a link for you (which sometimes you want to avoid, so you have to introduce a mechanism to do that), you always make links explicit.

Unfortunately, the yaws approach doesn’t let you bracket the link text, so you’re limited to single words, CamelCase, or perhaps c_style_words. Even though I don’t necessarily like have to type the brackets, I think that bracketing is the right idea.

This is the approach taken by Wikipedia. Amusingly, they do in-wiki links like this:

  [[another wiki page]]

and general Web-wide URIs like this:

  [URI some link text]

which is the opposite of what we’re doing here. Regardless of the number of brackets, there is a lot of wisdom in their method.

Once nice thing about the Wikipedia way is that they take the link text “another wiki page”, capitalize the first letter, and convert spaces to underscores, so the page that it links to is called Another_wiki_page. This way you can use the link to start a sentence

  [[Another wiki page]] that talks about linking is ...

and it will reference the same page as

  I found [[another wiki page]] that talks about linking.

If any of the words that make up the link are proper nouns, their capitalization is left alone. To reiterate: the first word is capitalized; the others are left as-is.

This matches too my preference for rendering titles, which is more British than American. Where the American writes Link Format Notes, the Briton writes Link format notes, which is much quieter, and preferable typographically, as it’s much easier to scan a line of (mostly) lowercase than a line mixing upper- and lower. The initial capital also makes a nice marker.

You’ll note that I’ve used the latter style in this page’s headings (and in all the other pages I’ve written on this wiki ;-), and you’ll also note that the wiki engine, following Ward’s wiki, renders page titles the ugly American way. The Wikipedia way, of capitalizing the first letter and leaving all other letters alone, would let us generate lovely British-style page titles.

One last note about this kind of linking is that it allows seamless use of suffix forms. For example,

  [[bus]]es, [[train]]s, and [[tram]]s

would render as buses, trains, and trams. Making explicit the boundary between the link words and the suffix makes using singular and plural forms of a page easy, and it also renders unnecessary the occasional sabotage necessary when using automagic CamelCase wiki word links.

I like the Wikipedia way, a lot. I wonder: could we get away with using single brackets for wiki links and double brackets for outside URIs? It would save a lot of typing.

As a new devotee of functional languages I find I like rather “quiet” notation. f x instead of f(x), etc. For this reason I would lean toward using single brackets for wiki links if we can “get away” with it.

There are two link types, both rather special-purpose, that I would like to make easy: linking to books and to RFCs.

ISBN links look like any of the following:

  ISBN 1234567890
  ISBN 1-234-56789-0
  ISBN 123456789X
  ISBN 1-234-56789-X

RFC links are even simpler:

  RFC 822

RFC links generate a reference to the text document at ietf.org. ISBNs are more complicated. We want to offer a lot of choices to the reader (I am again following Wikipedia’s lead here). Ideally what I’d like to do is this: link to a wiki page that consists of inter wiki-like links, and that gets rendered by adding the ISBN number to all the links. So you could have Amazon, Powell’s and a bunch of local libraries in your books page. When you follow an ISBN link, it would render your books page with the ISBN filled in.

For an ISBN you could create a link to http://isbn.nu/. For example, the ISBN for SICP is 0-262-01077-1. Just use http://isbn.nu/0-262-01077-1 as the URL. --Michael Pruemm

Well, yes and no. What I get from isbn.nu isn’t configurable, and it seems to be mostly about buying books, which isn’t the only thing I want to use ISBN finder for. I would link to Amazon for the reviews, to Powell’s to buy, and to my local libraries for the cheapskate in me. In order to be able to “do things my way” I would probably have to have my own links page.

And I think there is more power in the template page idea than I have yet fathomed.

Lastly, there are a few more oddities in the markup, two of which add search forms to a page is it is being rendered, and the last timestamps a page as it being saved.

  [namesearch]

generates a form that can be used to search for pages whose names match the entered string (really regular expression).

  [textsearch]

generates a form that can be used to search the contents of pages for strings matching the entered string (really regular expression).

  [now]

creates a timestamp (“2005 January 29 14:17”) as the file is being saved. This is useful for change logs and so on.

  [flickr]

creates a flickr “badge” – a group of thumbnails linking back to their originals on flickr. There is more to this; see flickr markup for the gory details. It’s super cool!