(no commit message)
[openafs-wiki.git] / TWiki / ATasteOfTWiki.mdwn
1 This is a short introductory training course for TWiki beginners.
2
3 <a name="StartPresentation"></a> <span>[[Main/WebHome?slideshow=on;skin=print#GoSlide1]]</span>
4
5 ## <a name="Slide 1: A Taste of TWiki"></a> Slide 1: A Taste of TWiki
6
7 <img src="http://www.dementia.org/twiki//view/hula.gif" width="113" height="111" alt="Hula girl" /> The basic function of TWiki is a Wiki (if that helps!)
8
9 A Wiki is like a web site, except that you can edit the content in your browser
10
11 - "Wiki" is short for "wiki wiki", the Hawaiian for "Quick"
12 - The idea originates from [Macintosh Hypercard](http://www.hyperdictionary.com/computing/hypercard), via [Ward Cunningham](http://www.c2.com/cgi/wiki?WardCunningham)
13 - In Ward's words, Wiki is _"the simplest online database that could possibly work"_
14 - A Wiki is basically a shared, online, persistent whiteboard
15
16 ## <a name="Slide 2: TWiki Wiki"></a> Slide 2: TWiki Wiki
17
18 <img src="http://www.dementia.org/twiki//view/whiteboard.gif" width="240" height="160" alt="Whiteboard" /> TWiki implements the basic Wiki idea of a shared whiteboard
19
20 - Anyone can add content<br />... or change what is written<br />... or change the organisation of the content
21 - Whatever what you write is<br />... nicely presented<br />... remembered... and never forgotten
22
23 TWiki also acts as an "application platform" to integrate a number of other functions.
24
25 TWiki is an Open-Source development on [TWiki.org](http://twiki.org/)
26
27 - led by TWiki:Main.PeterThoeny
28 - with over 100 regular contributors in many countries
29
30 ## <a name="Slide 3: Where is it used?"></a> Slide 3: Where is it used?
31
32 TWiki is mainly used in commercial environments, often on corporate intranets
33
34 - Examples: Disney, British Telecom, SAP, Wind River, Motorola, [Epic Games](http://udn.epicgames.com/Main/WebHome)<br /><table cellspacing="20">
35   <tr>
36     <td><img alt="Disney logo" height="31" src="http://www.dementia.org/twiki//view/Disney_logo.gif" width="80" /></td>
37     <td><img alt="British Telecom logo" height="41" src="http://www.dementia.org/twiki//view/BT_logo.gif" width="80" /></td>
38     <td><img alt="SAP logo" height="40" src="http://www.dementia.org/twiki//view/SAP_logo.gif" width="80" /></td>
39     <td><img alt="Motorola logo" height="65" src="http://www.dementia.org/twiki//view/Motorola_logo.gif" width="80" /></td>
40     <td><img alt="Epic Games logo" height="65" src="http://www.dementia.org/twiki//view/EpicGames_logo.gif" width="80" /></td>
41   </tr>
42 </table>
43
44 A number of public Wiki sites also use TWiki
45
46 - Examples: <br /><https://twiki.cern.ch/twiki/bin/view/><br /><http://csci.mrs.umn.edu/twiki/view>
47
48 ## <a name="Slide 4: TWiki Features"></a> Slide 4: TWiki Features
49
50 TWiki builds on the original Wiki concept and adds a number of features that make it very useful in a business environment.
51
52 - TWiki pages are fully revision controlled, so a record of every change to every page is kept <table border="0" cellpadding="3" cellspacing="0">
53   <tr>
54     <td bgcolor="#D0D0D0"><font color="black" size="-1">r6 <a>&lt;</a> r5 <a>&lt;</a> r4</font></td>
55   </tr>
56 </table>
57 - The look-and-feel is highly configurable, through use of templates
58
59 <table width="100%">
60   <tr>
61     <td valign="top">
62       <ul>
63         <li> A "plugins" interface eases <ul>
64             <li> customisation </li>
65             <li> extension </li>
66             <li> application integration </li>
67           </ul>
68         </li>
69       </ul>
70     </td>
71     <td align="right"><img alt="" src="http://www.dementia.org/twiki//view/lego.gif" /></td>
72   </tr>
73 </table>
74
75 ## <a name="Slide 5: Applications of basic T"></a> Slide 5: Applications of basic TWiki
76
77 Basic TWiki can be used as:
78
79 - A whiteboard
80 - A document repository
81 - A collaborative authoring environment
82 - A notebook / scrapbook
83 - A chat room
84
85 ## <a name="Slide 6: Extended applications"></a> Slide 6: Extended applications
86
87 TWiki-with-extensions has been used as:
88
89 - A Content Management System (CMS) for websites
90 - A presentation development tool
91 - A Blog
92 - A database
93 - A project management system
94 - A tracking tool
95 - (_truth is, we don't really know its limits!_)
96
97 ## <a name="Slide 7: Structure of a TWiki pa"></a> Slide 7: Structure of a TWiki page
98
99 TWiki pages are usually organised into three parts:
100
101 - A header
102 - A body
103 - A footer
104
105 - The header and the footer are generated by the system
106 - The body contains the text of the page, as entered by you
107
108 TWiki is very configurable, and the look can change. However the essentials will all be there on the page (somewhere!)
109
110 ## <a name="Slide 8: The Page Header"></a> Slide 8: The Page Header
111
112 The header of a TWiki page is generally highlighted in colour, and will usually contain an icon that gives you an idea of where you are, such as a company logo.
113
114 <table bgcolor="white" border="0" cellpadding="3" cellspacing="0" width="90%">
115   <tr>
116     <td bgcolor="#D0D0D0" rowspan="2" valign="top" width="1%"><img alt="TWiki home" border="0" height="63" src="http://www.dementia.org/twiki//view/myco.gif" width="62" /></td>
117     <td><font size="+0"> MyCo.MyTopic </font></td>
118     <td align="right"><font color="black" size="-1">Webs:<br /><a href="non">Myco</a> | <a href="non">Main</a> | <a href="non">TWiki</a> | <a href="non">Sandbox</a></font></td>
119   </tr>
120   <tr bgcolor="#D0D0D0">
121     <td colspan="2"><font color="black" size="-1">[[Main/WebChanges]] | [[Main/WebIndex]] | [[Main/WebSearch]] | Go <input name="topic" size="16" type="text" /></font></td>
122   </tr>
123 </table>
124
125 It will also usually contain a number of 'links' that you can click on. You will generally see:
126
127 - [[Changes|Main/WebChanges]] - gives you a list of recent changes
128 - [[Index|Main/WebIndex]] - gives you a full index
129 - [[Search|Main/WebSearch]] - takes you to a search page, where you can search all the text
130 - Go <input name="topic" size="16" type="text" />
131  - lets you type in the name of a page you already know
132
133 ## <a name="Slide 9: The Page Header ... con"></a> Slide 9: The Page Header ... continued
134
135 <table bgcolor="white" border="0" cellpadding="3" cellspacing="0" width="90%">
136   <tr>
137     <td bgcolor="#D0D0D0" rowspan="2" valign="top" width="1%"><img alt="TWiki home" border="0" height="63" src="http://www.dementia.org/twiki//view/myco.gif" width="62" /></td>
138     <td><font size="+0"> MyCo.MyTopic </font></td>
139     <td align="right"><font color="black" size="-1">Webs:<br /><a href="non">Myco</a> | <a href="non">Main</a> | <a href="non">TWiki</a> | <a href="non">Sandbox</a></font></td>
140   </tr>
141   <tr bgcolor="#D0D0D0">
142     <td colspan="2"><font color="black" size="-1">[[Main/WebChanges]] | [[Main/WebIndex]] | [[Main/WebSearch]] | Go <input name="topic" size="16" type="text" /></font></td>
143   </tr>
144 </table>
145
146 You may also see in the header (usually at the top right) a list of the TWiki "webs". A web is a collection of pages that are related closely together
147
148 - For example, we might have a web called "Enemies", where we keep all we know about our enemies, and another called "Friends"
149 - There's usually a safe play web called something like "Sandbox" or "Scratch", where you can create pages just to try things out
150 - And some admin areas, like "%USERSWEB%" and "%SYSTEMWEB%"
151
152 ## <a name="Slide 10: The Page Footer"></a> Slide 10: The Page Footer
153
154 The footer of the page is also highlighted in colour, and is usually where you will find the links that let you change the content.
155
156 <table bgcolor="white" border="0" cellpadding="3" cellspacing="0" width="90%">
157   <tr bgcolor="#D0D0D0">
158     <td colspan="2" valign="top"><font color="black" size="-1"> <a href="none"><b>Edit</b></a> | <a href="none">Attach</a> | <a href="none">Diffs</a> | r2 <a href="none">&gt;</a> r1 | <a href="none">More</a> </font></td>
159   </tr>
160   <tr>
161     <td valign="top"><font color="black" size="-1">Revision r1.2 - 13 Feb 2004 - 09:09 GMT - <a href="none">TWikiPresenter</a> </font></td>
162     <td valign="top" width="40%"><font size="-2">%WEBCOPYRIGHT% </font></td>
163   </tr>
164 </table>
165
166 - The [Edit]() link takes you to an interactive page where you can change the page content
167 - The [Attach]() link lets you attach files
168 - The other links invoke other, more complex, functions, mainly to do with revision tracking - they can safely be ignored for now
169
170 ## <a name="Slide 11: Editing Pages"></a> Slide 11: Editing Pages
171
172 - You've read a page, and you disagree with it violently! It says:<br />_Everyone_ **knows** that `the world` is an <font><u>OblateSpheroid</u></font><br />But you know for a fact it is flat! ;-)
173 - You've clicked the edit link, and an edit page has appeared. But it doesn't look much like what was on the page before - it's full of strange hieroglyphics!
174
175 `_Everyone_ *knows* that =the world= is an OblateSpheroid`
176
177 - Now what?
178
179 ## <a name="Slide 12: What&#39;s in a page"></a> Slide 12: What's in a page
180
181 - The hieroglyphics are what's known as "TWiki Markup" or "formatting"
182 - They are a really simple way of telling the browser how you want the page to look
183 - You don't have to use them
184   - TWiki understands pages in plain text just fine.<br /><br />`Actually it is perfectly and absolutely flat`<br /><br /> appears as <br /><br /> Actually it is perfectly and absolutely flat
185
186 ## <a name="Slide 13: Formatting just makes"></a><a name="Slide 13: Formatting just makes "></a> Slide 13: Formatting just makes pages prettier
187
188 ... and easier to read<br /><br />`_Actually_ it is *perfectly* and __absolutely__ flat`<br /><br /> appears as <br /><br />_Actually_ it is **perfectly** and **_absolutely_** flat
189
190 - A full description of all the formatting can be found in the %SYSTEMWEB%.TextFormattingRules and %SYSTEMWEB%.TextFormattingFAQ
191 - The best thing to do is just to type until you get stuck
192   - then follow the link on the edit page to the help.
193
194 ## <a name="Slide 14: Commonly used formatti"></a> Slide 14: Commonly used formatting
195
196 TWiki understands pages in plain text just fine, but you can %RED% **_jazz_** %ENDCOLOR%%GREEN% _them_ %ENDCOLOR%%BLUE% **up** %ENDCOLOR% using some simple formatting shortcuts. Here are some of the more commonly used ones:
197
198 - ---+ indicates a heading. Add more +'s for a deeper heading. <table border="1" cellpadding="0" cellspacing="0">
199   <tr>
200     <th bgcolor="#99CCCC"><strong> You type </strong></th>
201     <th bgcolor="#99CCCC"><strong> You see </strong></th>
202   </tr>
203   <tr>
204     <td> %BLACK%<code>---+ This is a heading</code>%ENDCOLOR% </td>
205     <td>
206       <h1>%BLACK%This is a heading%ENDCOLOR%</h1>
207     </td>
208   </tr>
209   <tr>
210     <td> %BLACK%<code>---++ And so is this</code>%ENDCOLOR% </td>
211     <td>
212       <h2>%BLACK%And so is this%ENDCOLOR%</h2>
213     </td>
214   </tr>
215 </table>
216 - %TOC% will insert a table of contents<br />
217
218 ## <a name="Slide 15: More common formatting"></a> Slide 15: More common formatting
219
220 - A blank line gives a paragraph break<br />
221 - --- on a line of its own gives a horizontal bar
222 - Text in stars \*like this\* looks **like this**<br />
223 - Text in underscores \_like this\_ looks _like this_<br />
224 - Text in equals signs =like this= looks `like this`<br />
225 - Bulleted lists use three spaces followed by an asterisk (`*`) at the start of the line
226   - The depth of the bullet is given by the number of spaces, in multiples of three
227
228 <table border="1" cellpadding="0" cellspacing="0">
229   <tr>
230     <th bgcolor="#99CCCC"><strong> You type </strong></th>
231     <th bgcolor="#99CCCC"><strong> You see </strong></th>
232   </tr>
233   <tr>
234     <td><font color="black"><code>   * Bullet</code><br /><code>      * Sub-bullet</code></font></td>
235     <td>
236       <ul>
237         <li><font color="black">Bullet</font><ul>
238             <li><font color="black">Sub-bullet</font></li>
239           </ul>
240         </li>
241       </ul>
242     </td>
243   </tr>
244 </table>
245
246 - Numbered lists use a number in place of the `*`. The list is numbered automatically, so you can just use a `1`
247
248 ## <a name="Slide 16: Even more....."></a> Slide 16: Even more.....
249
250 - You can create a table using vertical bars:
251
252          | Cat | Feline |
253          | Bear | Ursine |
254          | Wolf | Lupine |
255
256 - appears as <table border="1" cellpadding="0" cellspacing="0">
257   <tr>
258     <td><font color="black">Cat</font></td>
259     <td><font color="black">Feline</font></td>
260   </tr>
261   <tr>
262     <td><font color="black">Bear</font></td>
263     <td><font color="black">Ursine</font></td>
264   </tr>
265   <tr>
266     <td><font color="black">Wolf</font></td>
267     <td><font color="black">Lupine</font></td>
268   </tr>
269 </table>
270 - %RED% .... %ENDCOLOR% will change the colour of the enclosed text. Lots of colours are available (%RED%%RED%%ENDCOLOR%, %GREEN%%GREEN%%ENDCOLOR%, %BLUE%%BLUE%%ENDCOLOR% etc)
271
272 ## <a name="Slide 17: &lt;a href=">WikiWords</a>"&gt; Slide 17: WikiWords
273
274 - One special hieroglyph that is **very important** is a [[BumpyWord]]
275   - a word that starts with uppercase, then some lowercase, then more uppercase (a.k.a CamelCase)
276 - This has a special meaning to TWiki; if it matches the name of another topic, TWiki will automatically create a link to that page for you.
277 - If there is no such page, then the word is highlighted and a question mark is put after the word, [[LikeThis]]
278 - If you click on the question mark, then TWiki will invite you to create that page.
279
280 - This lets you enter the names of topics you _think_ should exist, but don't yet
281   - You, or someone else, can always come along later and click on the question mark!
282
283 ## <a name="Slide 18: Referencing other page"></a> Slide 18: Referencing other pages and URLs
284
285 - [[BumpyWords]] automatically link to the target page
286   - You can make these links easier to read using square brackets:
287     - <code>\[[BumpyWords]\[bumpy words]] appears as [[bumpy words|Main/BumpyWords]]</code>
288 - An ordinary URL pasted into text will appear as a link - <http://www.google.com>
289   - You can also prettify URLs using square brackets:
290     - `[[http://www.google.com/][Google]]` appears as [Google](http://www.google.com/)
291 - Use %SEARCH. This is an interface to a sophisticated search engine that embeds the results of the search in your page. See %SYSTEMWEB%.TWikiVariables for full details.
292
293 ## <a name="Slide 19: More formatting"></a> Slide 19: More formatting
294
295 - There's **lots** more formatting available, see %SYSTEMWEB%.TextFormattingRules and %SYSTEMWEB%.TextFormattingFAQ
296 - _If you are a real masochist, you can even enter raw HTML tags!_
297 - **Important** to _disable_ unwanted formatting, use `<nop>`
298   - `<nop>_word_` appears as \_word\_
299
300 ## <a name="Slide 20: Creating new pages"></a> Slide 20: Creating new pages
301
302 - Alternative ways:
303   - Click on the question mark after a [[BumpyWord]]
304   - Type in the name of the topic in the "Go:" box
305   - Type in the name of the topic in the URL
306 - Any time you try to visit a page that doesn't exist, TWiki will invite you to create it.
307 - Make sure the names of topics are always [[BumpyWords]].
308
309 ## <a name="Slide 21: Attachments"></a> Slide 21: Attachments
310
311 - Attachments are files which have been uploaded and attached to a TWiki page using the 'Attach' function in the footer.
312
313 <table bgcolor="white" border="0" cellpadding="1" cellspacing="2">
314   <tr>
315     <th align="center" bgcolor="#0c2577" valign="top"><a href="none"><font color="#FFFF99">Attachment</font> <img alt="sort" border="0" src="http://TWiki.org/p/pub/TWiki/TablePlugin/diamond.gif" /></a></th>
316     <th align="center" bgcolor="#0c2577" valign="top"><a href="none"><font color="#FFFF99"> Action</font></a></th>
317     <th align="center" bgcolor="#0c2577" valign="top"><a href="none"><font color="#FFFF99"> Size</font></a></th>
318     <th align="center" bgcolor="#0c2577" valign="top"><a href="none"><font color="#FFFF99"> Date</font></a></th>
319     <th align="center" bgcolor="#0c2577" valign="top"><a href="none"><font color="#FFFF99"> Who</font></a></th>
320     <th align="center" bgcolor="#0c2577" valign="top"><a href="none"><font color="#FFFF99"> Comment</font></a></th>
321   </tr>
322   <tr>
323     <td bgcolor="#F8F8F8" valign="top"><img align="top" alt="" border="0" height="16" src="http://TWiki.org/p/pub/icn/zip.gif" width="16" /> <font color="black"><a href="none">myco.gif</a></font></td>
324     <td align="center" bgcolor="#F8F8F8" valign="top"><font color="black"><a href="none">manage</a></font></td>
325     <td align="right" bgcolor="#F8F8F8" valign="top"><font color="black"> 9.6 K </font></td>
326     <td bgcolor="#F8F8F8" valign="top"><font color="black"> 13 Feb 2004 - 18:41 </font></td>
327     <td bgcolor="#F8F8F8" valign="top"><font color="black"> <a href="none">MushroomMagicMan</a> </font></td>
328     <td bgcolor="#F8F8F8" valign="top"><font color="black">Attached image file </font></td>
329   </tr>
330 </table>
331
332 - Attachments are simply files, in whatever format you want.
333 - TWiki recognises some file formats, notably image files (.gif)
334   - Write `%ATTACHURL%/myco.gif` to see this: ![myco.gif](http://www.dementia.org/twiki//view/myco.gif)
335
336 ## <a name="Slide 22: Wiki Culture"></a> Slide 22: Wiki Culture
337
338 Enough about mechanics; how is a wiki actually _used_ ? Well, that's really up to you, but there are a number of tricks that the wiki community has developed for collaborative writing that work pretty well:
339
340 - What can I edit?
341   - Anything. But it's good etiquette to sign your contributions
342   - If someone doesn't want you to edit a page, it's up to them to say so, clearly, on the page
343 - But what if somebody doesn't like my edits?
344   - In TWiki, they can always recover the old revision and re-instantiate it if they really want to
345   - Otherwise they should regard your changes as an opportunity for discussion
346 - Pages in wiki are (usually) in one of three "modes"
347   - DocumentMode
348   - ThreadMode
349   - StructuredMode
350
351 TWiki doesn't automatically distinguish between these modes; they are purely semantic.
352
353 ## <a name="Slide 23: &lt;a href=">DocumentMode</a>"&gt; Slide 23: DocumentMode
354
355 - A page in DocumentMode usually comprises a contribution which is written in the third person and left unsigned.
356 - The piece of text is community property
357   - It may have multiple and changing authors as it is updated to reflect the community consensus.
358
359 ## <a name="Slide 24: &lt;a href=">ThreadMode</a>"&gt; Slide 24: ThreadMode
360
361 - Thread mode is a form of discussion where the community holds a conversation
362 - The discussion usually starts out with a statement, at the top of the page, that is subsequently discussed
363 - The page may be periodically "refactored" (edited) to remove some of the comments
364   - As long as the comment is accurately reflected in what replaces it, nobody usually minds.
365   - Remember to always maintain a complete list of contributors, though!
366
367 You may see a comment box on a page in ThreadMode that makes it easy to quickly add your inputs. Typing in a comment and adding it to a page this way is known as "blogging" ;-)
368
369 - ThreadMode is rather like an e-mail thread
370   - Except that new comments are usually added to the end
371 - ThreadMode pages often get refactored into DocumentMode
372
373 ## <a name="Slide 25: &lt;a href=">StructuredMode</a>"&gt; Slide 25: StructuredMode
374
375 - A page in StructuredMode follows some predefined structure for example
376   - An agenda
377   - A set of meeting minutes
378   - A requirement description.
379 - Pages in StructuredMode will usually have rules governing how they are edited.
380
381 ## <a name="Slide 26: Other Wiki tricks - Ca"></a> Slide 26: Other Wiki tricks - Categories
382
383 - A Wiki trick for grouping pages together
384 - Example: to group together a set of pages all relating to the weather:
385   1. Create a page called 'CategoryWeather'
386   2. Put a SEARCH that contains the word 'CategoryWeather' into it
387     - `%SEARCH{"CategoryWeather" nosearch="on" nosummary="on"}%`
388   3. Put the [[BumpyWord]] 'CategoryWeather' on all the pages relating to the weather<br />(usually at the bottom, below a horizontal bar)
389
390 ## <a name="Slide 27: Contributed features"></a> Slide 27: Contributed features
391
392 Basic TWiki is rich with features, but is enriched even further by the addition of optional plug-in modules that may (or may not!) be installed in your TWiki. These are classified as either **_skins_** (modules that change the look-and-feel) and **_plugins_** (modules that enhance functionality).
393
394 Here's a brief description of some of the more common plugins, together with the tags you might expect to see in topics if they are used. You can find out more by visiting the plugin pages.
395
396 - ActionTrackerPlugin: Support **action tags** in topics, with **automatic notification** of action statuses `%ACTION...`
397 - CalendarPlugin: Show a **monthly calendar** with highlighted events `%CALENDAR...%`
398 - CommentPlugin: Support **rapid entry of short comments** (also known as **blogging**) `%COMMENT...`
399 - ChartPlugin: Create PNG or GIF **charts to visualize data in TWiki tables** `%CHART...`
400 - EditTablePlugin: Edit TWiki tables using **edit fields and drop down boxes** `%EDITTABLE...`
401 - InterwikiPlugin: Define **shortcuts** for links to **common external sites**
402
403 ## <a name="Slide 28: More plugins"></a> Slide 28: More plugins
404
405 - RenderListPlugin: Render **bullet lists in a variety of formats** `%RENDERLIST...`
406 - SlideShowPlugin: **Create web based presentations** based on topics with headings `%SLIDESHOWSTART...`
407 - SpreadSheetPlugin: Add **spreadsheet calculations** like "$SUM( $ABOVE() )" to tables located in TWiki topics `%CALC...`
408 - TablePlugin: Control **presentation and sorting of tables** `%TABLE...`
409 - TWikiDrawPlugin: Add **quick sketches** to pages `%DRAWING...`
410
411 The following plugins are installed on this TWiki: [[SpreadSheetPlugin]], [[CommentPlugin]], [[EditTablePlugin]], [[InterwikiPlugin]], [[PreferencesPlugin]], [[SlideShowPlugin]], [[SmiliesPlugin]], [[TablePlugin]], [[TwistyPlugin]]
412
413 There are many other plugins, see <http://TWiki.org/cgi-bin/view/Plugins>
414
415 ## <a name="Slide 29: Credits and Acknowledg"></a> Slide 29: Credits and Acknowledgements
416
417 - This training was developed by TWiki:Main.CrawfordCurrie on behalf of [Oxamer](http://www.oxamer.com/), one of the companies in the [Oxford Gene Technology](http://www.ogt.co.uk/) group.
418 - Valuable contributions were also received from the TWiki Open Source community; special mentions go to:
419   - TWiki:Main.WalterMundt
420   - TWiki:Main.SvenDowideit
421 - The latest version of this presentation is available at TWiki:%WEB%.%TOPIC%, where you can also provide feedback
422
423 **_Related topics:_** [[WelcomeGuest]], [[TWikiTutorial]], [[ATasteOfTWikiTemplate]]