data/TWiki/WikiWord.txt
author Colas Nahaboo <colas@nahaboo.net>
Sat, 26 Jan 2008 15:50:53 +0100
changeset 0 414e01d06fd5
permissions -rw-r--r--
RELEASE 4.2.0 freetown
     1 %META:TOPICINFO{author="TWikiContributor" date="1184734707" format="1.1" version="8"}%
     2 ---+!! What is a !WikiWord?
     3 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 =%HOMETOPIC%= and on saving the page this becomes %HOMETOPIC%. It's as easy as that.
     4 
     5 When you type a !WikiWord, you establish a hyperlink. It's as easy as that.
     6 
     7 !WikiWord linking is easy to use:
     8    * You don't have to know the full path to where the topic is stored - you just type the name
     9    * You don't need to write HTML
    10    * Without HTML, the topic text is easier to read when editing
    11    * Easy linking leads to interesting texts with links placed in context
    12 
    13 !WikiWords are styled like this because:
    14    * It makes Wiki hyperlinks instantly recognizable
    15    * It leads to interesting Wiki topics
    16    * It avoids the need to fiddle with HTML tags
    17    * It avoids over-general topics because at least two words are required
    18 
    19 ---++ Syntax of a !WikiWord
    20 
    21    * Uppercase letter(s)
    22    * Lowercase letter(s) or numbers(s)
    23    * Uppercase letter(s)
    24    * Optional lowercase or uppercase letter(s) or number(s)
    25 
    26 !WikiWord syntax in [[Wikipedia:Extended_Backus_Naur_Form][Extended Backus.Naur form]] (EBNF):
    27 
    28 <verbatim>
    29     wikiWord        = upperLetters , lowerNumLetters , upperLetters , { alphaNum } ;
    30     upperLetters    = upperCase , { upperCase } ;
    31     lowerNumLetters = lowerNum , { lowerNum } ;
    32     alphaNum        = upperCase | lowerCase | digit ;
    33     lowerNum        = lowerCase | digit ;
    34     lowerCase       = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i"
    35                     | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r"
    36                     | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" ;
    37     upperCase       = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I"
    38                     | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R"
    39                     | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z" ;
    40     digit           = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
    41 </verbatim>
    42 
    43 ---++ Good examples of !WikiWords
    44 
    45    * WikiWord
    46    * GoodStyle
    47    * VersionFiveDotThree
    48    * ReleaseVersion5dot3
    49    * AVeryLongWikiTopicNameIsAlsoPossible: wherever an uppercase or lowercase letter is allowed, a group of letters of the same case is allowed
    50    * YearTwoThousand
    51    * Nine2Five: Note that numbers are considered to be lowercase letters in !WikiWords
    52 
    53 ---++ Bad examples of !WikiWords:
    54 
    55    * Web: Name without the uppercase letter(s), lowercase letter(s), uppercase letter(s) sequence
    56    * 5TWiki: Name beginning with a number
    57    * Know-How: Name with dashes in between
    58 
    59 ---++ Variations in linking
    60 
    61 When you write the name of a topic, it becomes a link. There are more ways
    62 
    63    * To write a custom *link label*, use bracket notation: =[<nop>[TWikiAccessControl][access control]]= - this becomes: [[TWikiAccessControl][access control]]
    64    * To link to a topic in *another web*, write: =Sandbox.WebSearch= - this becomes: Sandbox.WebSearch
    65    * To link to a topic in *another subweb* write: =Sandbox.Subweb.WebSearch=.
    66    * To show the web name in the link use bracket notation: =[<nop>[Sandbox.%HOMETOPIC%]]= - this becomes: [[Sandbox.%HOMETOPIC%]]
    67    * To link to a topic on *another Wiki site*, use: =TWiki:Main/WebHome= - this becomes: TWiki:Main/WebHome (sites are defined in the InterwikiPlugin)
    68    * 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: =%SYSTEMWEB%.%HOMETOPIC%#MyAnchor=.
    69    * To link to a header on the *same page*, write a "#" followed by the header text, with spaces replaced by underscores (and =!= removed): =[<nop>[#Good_examples_of_WikiWords]]= becomes: [[#Good_examples_of_WikiWords]]. You can also link to a header on another page: =%SYSTEMWEB%.%HOMETOPIC%#Disclaimer= becomes: %SYSTEMWEB%.%HOMETOPIC%#Disclaimer.
    70 
    71 ---++ Hints
    72    * Insert !WikiWords wherever you can. Rich linking helps to make a Wiki successful.
    73    * 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.
    74    * To stop a !WikiWord from being turned into a hyperlink, insert an exclamation point immediately before the !WikiWord. For example, write =!<nop>SunOS= to get !SunOS.
    75    * Create topics with singular names. Plural <nop>WikiWords are automatically linked to the singular topic, i.e. the link WikiWords links to the topic WikiWord (works only in English).
    76    * Sometimes you have to be creative to find a good <nop>WikiName. Examples:
    77       * To create a topic about the the *Bread Slicer 1.2* product, use =BreadSlicer1dot2= or =BreadSlicer1pt2=, but not =BreadSlicer1.2=.
    78       * Numbers are considered lowercase which makes =Year2K= and =Y2K= !WikiWords but not =Y2000= and =Y2k=.
    79    * Turn acronyms into !WikiWords, i.e. take =FaqIndex= for a "FAQ index" topic.
    80    * It is possible to turn off the auto-linking of !WikiWords and to rely only on the bracket notation. See NOAUTOLINK setting in TWikiPreferences#Default_Web_Preferences.
    81    * %X% When linking to a <nop>%HOMETOPIC% topic _in another web_, the link will be rendered as the name of the web, e.g. =Sandbox.%HOMETOPIC%= becomes Sandbox.%HOMETOPIC%.
    82    * %X% 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.
    83 
    84 __Related Topics:__ WikiSyntax, TextFormattingRules
    85 %STOPINCLUDE%
    86 
    87 -- __Contributors:__ TWiki:Main.PeterThoeny, TWiki:Main.ArthurClemens, TWiki:Main.CrawfordCurrie