Tags:
create new tag
view all tags
ALERT! NOTE: This is a DistributionDocument.
  • Please help maintain high quality documentation: This is a wiki, please fix the documentation if you find errors or incomplete content.
  • Put questions and suggestions concerning the documentation of this topic in the comments section below.
  • Use the Support web for problems you are having using TWiki.
  • Use the Sandbox web to evaluate & test TWiki.

What is TWiki?
A leading open source enterprise wiki and web application platform used by 50,000 small businesses, many Fortune 500 companies, and millions of people.
MOVED TO... Learn more.

What is a WikiWord?

A WikiWord consists of two or more words with initial capitals, run together. WikiWords are topic names. A TWiki topic name always has a fixed format: two or more words with initial capitals, run together. Like the name of the current topic: WikiWord. When you type the name of a topic, you create a link to that topic. You type WebHome and on saving the page this becomes WebHome. It's as easy as that.

When you type a WikiWord, you establish a hyperlink. It's as easy as that.

WikiWord linking is easy to use:

  • You don't have to know the full path to where the topic is stored - you just type the name
  • You don't need to write HTML
  • Without HTML, the topic text is easier to read when editing
  • Easy linking leads to interesting texts with links placed in context

WikiWords are styled like this because:

  • It makes Wiki hyperlinks instantly recognizable
  • It leads to interesting Wiki topics
  • It avoids the need to fiddle with HTML tags
  • It avoids over-general topics because at least two words are required

Syntax of a WikiWord

  • Uppercase letter(s)
  • Lowercase letter(s) or numbers(s)
  • Uppercase letter(s)
  • Optional lowercase or uppercase letter(s) or number(s)

WikiWord syntax in Extended Backus-Naur form (EBNF):

    wikiWord        = upperLetters , lowerNumLetters , upperLetters , { alphaNum } ;
    upperLetters    = upperCase , { upperCase } ;
    lowerNumLetters = lowerNum , { lowerNum } ;
    alphaNum        = upperCase | lowerCase | digit ;
    lowerNum        = lowerCase | digit ;
    lowerCase       = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i"
                    | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r"
                    | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" ;
    upperCase       = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I"
                    | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R"
                    | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z" ;
    digit           = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;

Good examples of WikiWords

Bad examples of WikiWords:

  • Web: Name without the uppercase letter(s), lowercase letter(s), uppercase letter(s) sequence
  • 5TWiki: Name beginning with a number
  • Know-How: Name with dashes in between

Variations in linking

When you write the name of a topic, it becomes a link. There are more ways:

  • To write a custom link label, use bracket notation: [[TWikiAccessControl][access control]] - this becomes: access control
  • To link to a topic in another web, write: Sandbox.WebSearch - this becomes: WebSearch
  • To link to a topic in another subweb write: Sandbox.Subweb.WebSearch.
  • To show the web name in the link use bracket notation: [[Sandbox.WebHome]] - this becomes: Sandbox.WebHome
  • To link to a topic on another Wiki site, use: TWiki:Main/WebHome - this becomes: TWiki:Main/WebHome (sites are defined in the InterwikiPlugin)
  • To link to a part on the same page, write a "#" followed by the name of an anchor. The anchor is a "#" followed by a name which must be a WikiName. Example #MyAnchor. You can also link to an anchor on another page: TWiki06x01.WebHome#MyAnchor.
  • To link to a header on the same page, write a "#" followed by the header text, with spaces replaced by underscores (and ! removed): [[#Good_examples_of_WikiWords]] becomes: #Good_examples_of_WikiWords. You can also link to a header on another page: TWiki06x01.WebHome#Disclaimer becomes: TWiki06x01.

Hints

  • Insert WikiWords wherever you can. Rich linking helps to make a Wiki successful.
  • Be specific. All topics in a web share one name space. For example, instead of FunctionalSpec write BreadSlicerFunctionalSpec because other projects might also have a functional spec topic.
  • To stop a WikiWord from being turned into a hyperlink, insert an exclamation point immediately before the WikiWord. For example, write !SunOS to get SunOS.
  • Create topics with singular names. Plural WikiWords are automatically linked to the singular topic, i.e. the link WikiWords links to the topic WikiWord (works only in English).
  • Sometimes you have to be creative to find a good WikiName. Examples:
    • To create a topic about the the Bread Slicer 1.2 product, use BreadSlicer1dot2 or BreadSlicer1pt2, but not BreadSlicer1.2.
    • Numbers are considered lowercase which makes Year2K and Y2K WikiWords but not Y2000 and Y2k.
  • Turn acronyms into WikiWords, i.e. take FaqIndex for a "FAQ index" topic.
  • It is possible to turn off the auto-linking of WikiWords and to rely only on the bracket notation. See NOAUTOLINK setting in TWikiPreferences.
  • ALERT! When linking to a WebHome topic in another web, the link will be rendered as the name of the web, e.g. Sandbox.WebHome becomes Sandbox.
  • ALERT! Dots (.) are used as seperators between webs, subwebs, and topics. It is not possible to use dots in topic names. TWiki does not attempt to guess if a dot could be part of a topic name.

Related topics: WikiSyntax, WikiNotation, TextFormattingRules, TWikiEditingShorthand, TWikiRenderingShortcut, TWikiShorthand

-- Contributors: TWiki:Main.PeterThoeny, TWiki:Main.ArthurClemens, TWiki:Main.CrawfordCurrie



Comments & Questions about this Distribution Document Topic

Peter,

This isn't true in my experience: A topic is usually presented in the singular. Plural WikiWords are automatically linked to the singular topic, i.e. the link WikiWords links to the topic WikiWord.

-- GrantBow - 17 Jan 2003

It is not always the case with the TWiki docs. I changed the text to read "recommended".

-- PeterThoeny - 18 Jan 2003

Wow, I ran an experiment on HurdWiki:Main/GrantBow and found that a singular topic IS linked via the plural link, but a plural topic is not linked via a singular link. I never knew this "feature" existed! I would have named MANY topics differently if I knew about this. Amazing, I'm glad I know now.

-- GrantBow - 18 Jan 2003

Very Nice ...

-- OvidiuTroasca - 15 Apr 2003

Is there a guide anywhere as to what variants of WikiWords people have made?

For instance, I want a topic called Lecture23May2003 (or just 23May2003); I think corrupting this to "LecTure23May2003" or similar would be counter-intuitive to everyone.

I remember seeing somewhere that people had changed the definition of WikiWords, it would be useful to have them linked to, or have a guide linked from here.

-- MartinCleaver - 25 May 2003

Finally I realised why my MailnotifyCgiScript wasn't working - I had defined a group called Ft04t2a7Group, which wasn't a WikiWord. It is now - I'll let you know of any problems...

-bash-2.05b$ diff TWiki.pm TWiki.pm~
97c97
<       $upperAlpha $lowerAlpha $mixedAlpha $mixedAlphaNum $lowerAlphaNum $upperAlphaNum $numeric
---
>       $upperAlpha $lowerAlpha $mixedAlpha $mixedAlphaNum $lowerAlphaNum $numeric
464d463
<     $upperAlphaNum = "${upperAlpha}${numeric}";
471c470
<     $wikiWordRegex = qr/[$upperAlpha]+[$lowerAlpha]+[$upperAlphaNum]+[$mixedAlphaNum]*/;
---
>     $wikiWordRegex = qr/[$upperAlpha]+[$lowerAlpha]+[$upperAlpha]+[$mixedAlphaNum]*/;

PS. This change also allows WikiWords such as Lecture4 and Birthday5Sep1972. Nice.

-- MartinCleaver - 07 Jun 2003

If you have a topic in singular but refer to it in plural, then TWiki still creates the link. Reversely, if you have a topic in plural but refer to it in singular, then TWiki does not create a link. Isn't this inconsistent? One way to solve this would be, when I save a new topic, then if it ends in a lowercase "s", then save the topic without that lowercase "s"! This may cause some topics that should have had the "s" to also miss it, but since TWiki always recognizes plural links to singular topics, this is not a problem. Comments??

  • I agree, Torben, this would be a good thing. -- MartinCleaver - 07 Jun 2003

-- TorbenGB - 28 May 2003

Over on WikiLearn, I have pages named both Wikilearn.WebTopicEditTemplate and Wikilearn.WebTopicEditTemplates (mainly as a memory aid — it is easy to remember that I have my extra template stuff in a page with just the s added at the end). Would your proposal allow that?

Do you really mean create the link? Hmm, after reading it again, I think you mean follow the link, but I made these comments already so I'll leave them here:

In following a link, I think it makes sense to, if the link is to the plural but it is not there, look for the singular and go there (if it exists). And, I have no problem with the reverse: if the link is to the singular but it is not there, look for the plural and go there (if it exists).

But, as far as creating a link, I think TWiki should create whatever the writer of the link specifies (singular or plural).

-- RandyKramer - 28 May 2003

But if creating page with plural will disable link to singular name, maybe it will be decent when creating a page at least warn user (and allow to create singular link), because s/he might expect autolinking. We do warn for non-WikiWord link already. Make Twiki intuitive, not quirky. Use RuleOne.

-- PeterMasiar - 28 May 2003

Yes, I agree that a warning would be good!

-- RandyKramer - 27 Jun 2003

Since this is a documentation page, I think three other things should be covered (or mentioned):

  • (maybe) Point out that this is the definition of a WikiWord on TWiki, other wikis may use slightly different definitions. (And hence, maybe we should move this page to TWikiWord?)

  • That you can force a link with the double square bracket syntax (and include a link to the page that describes it).

  • That some punctuation (at least "_", and maybe some others) is acceptable in a TWiki word, maybe with some exceptions. (I mention such as I think I ran into some of them — I have a clearer memory that even though the use of a WikiWord for a web name is deprecated, it actually works to some degree (I can't recall what the problems were — IIRC, I could create such a web, store pages in it, and so forth, but some things (maybe searches??) did not work.)

Aside, although perhaps I should have just added documentation for the above, I thought an appropriate first step is to propose it and see if there are major objections. Plus, as you can see, I don't have all the necessary information, but, in the wiki way, if no one thinks this is a bad idea, and no one else makes an attempt at adding these points, I'll make an attempt next time I come across this page.

-- RandyKramer - 26 Oct 2003

Akin to a Microsoft SmartTag

-- MartinCleaver - 04 Dec 2003

I made some drastic changes to the introduction text.

I have also added #Variations_in_linking. It is not entirely on topic, but on the other hand why not here?

-- ArthurClemens - 18 Apr 2005

Perhaps it should be recommended that people not create a new topic that differs from an existing topic by having or not having an 's' on the end? Then adding and removing a trailing 's' could be done reasonably.

-- BradMace - 16 Oct 2005

I was recently surprised that ALLUPPERCASEWORDS are automatically linked if the page exists - but are not linked if the page does not exist.

I decided to summarize what I know about this sort of thing in TWikiLinkTypes.

-- AndyGlew - 31 Mar 2006

I moved the new topics to the Sandbox web. At this time, only developers can create new DistributionDocuments. Contributing docs changes is not very efficient at this time, you'd need to file a bug in Bugs:WebHome for each change. This will be fixed once DakarDocumentationModelIsBroken is resolved.

-- PeterThoeny - 31 Mar 2006

Sorry about that. I created TWikiLinkTypes2. I suppose that you will want to move that somewhere, too.

-- AndyGlew - 01 Apr 2006

Although I admit confusion. DistributionDocuments does not mention TWikiLinkTypes - so why move the tests? Do you want any topic in the TWiki web to be a DistributionDocument, or just those listed in DistributionDocuments?

-- AndyGlew - 01 Apr 2006

I moved the second TWikiLinkTypes to Sandbox.TWikiLinkTypes2.

We have three types of docs here in the TWiki web: DistributionDocuments, SupplementalDocuments and HistoricalDocuments. All are relevant as documentation for admins and end users. Test topics should go to the Sandbox web, this keeps the TWiki web tidy.

-- PeterThoeny - 01 Apr 2006

I finally found the Preference Option that should also be listed here. NOAUTOLINK - DisablingWikiWords

-- JadeCravy - 03 Apr 2006

Well, I think that the TWikiLinkTypes topic I created here, that you (PeterThoeny) moved, had value not as a test, but as documentation - because I could not find some parts of it documented. E.g. I could not find the ALLUPPERCASEACRONYM linking stuff documented - still haven't, although now I know that you call it ACRONYMS I might be able to.

So, I disagree, and I think that you have thrown something useful away. But it's your baby.

-- AndyGlew - 04 Apr 2006

In case y'all don't understand: I've been writing a number of scripts, eventually plugins, that parse the link structure of a wiki web. First I tried adapting other folks tools... but then I learned that all such tools that I tried used ad-hoc regexp parsing, and basically dd not understand all of the link structure. Then I tried intercepting TWiki's own link parsing - better, but a few surprising issues (that's how I found out about ACRONYMS). Finally, I rolled my own.

None of these approaches is satisfactory.

Anyway... I wrote what is now TWikiLinkTypes partially as a test, yes, but really mainly as documentation for the various types of links.

Because, I repeat, THIS WAS DOCUMENTED NOWHERE ELSE!!!!! At least nowhere ese in a single place.

-- AndyGlew - 04 Apr 2006

Andy, maybe you should try to contribute your work about the several link types by incorporating it in a testcase (e.g. http://develop.twiki.org/~develop/cgi-bin/view/TestCases/TestCaseAutoWikiWordRendering)

-- FranzJosefSilli - 04 Apr 2006

But they aren't tests. They are documentation!

(Except insofar as all tests are documentation.)

-- AndyGlew - 04 Apr 2006

What I wrote in what is now TWikiLinkTypes is a nicely formatted table that shows examples of most, if not all, of the various link types - what you type, what you see if the page exists, what you see if the page doesn't exist.

Nicely formatted table - that's documentation.

A test would have the expected values.

-- AndyGlew - 04 Apr 2006

Xactly. wink

-- FranzJosefSilli - 04 Apr 2006

Franz, I love tests. (I love XP.) But tests are not documentation. All documentation examples should be extractable as tests; but not all test cases are useful, human readable, documentation.

-- AndyGlew - 06 Apr 2006

If the explanation of a WikiWord in the first paragraph is correct, and I think it is, then you should delete the second paragraph ("When you type a WikiWord, you establish a hyperlink. It's as easy as that. "). This second paragraph is incorrect and repetitive.

-- RogerGrainger - 17 May 2008

In the examples of bad WikiWords, "Web" is given as one example of a bad WikiWord. The reason it's bad is not the one given; the reason "Web" is a bad WikiWord is that a WikiWord must contain at least two words but "Web" is only one word.

-- RogerGrainger - 17 May 2008

Can anyone tell me why ALLUPPERCASE topicnames are automatically linked, while other variations of non-wikiwords aren't? And is there a way to get around this?

-- WilliamMorgan - 2011-05-27

Please ask support questions in the Support web. You can turn off auto-linking, see NOAUTOLINK in TWikiPreferences

-- PeterThoeny - 2011-05-27

Please use the Support forum if you have questions about TWiki features. This comment section is about the documentation of this topic.

Also see: Codev.WikiWordDiscuss

Edit | Attach | Watch | Print version | History: r78 < r77 < r76 < r75 < r74 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r78 - 2011-11-01 - PeterThoeny
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.