/
BeginnersStartHere.txt
372 lines (289 loc) · 23.4 KB
/
BeginnersStartHere.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
%META:TOPICINFO{author="ProjectContributor" comment="reprev" date="1428396345" format="1.1" reprev="4" version="1"}%
%META:TOPICPARENT{name="UsersGuide"}%
---+!! %TOPIC%
This is a short introduction to Foswiki.
%SLIDESHOWSTART%
---++!! A short introduction to Foswiki
Use the slideshow navigation buttons on the bottom right of the page
---++ What is a Wiki?
<img align='right' alt='Hula girl' height='111' src='%ATTACHURL%/hula.gif' width='113' />
The basic function of Foswiki is a Wiki (if that helps!)
A Wiki is like a web site, except that you can edit the content in your browser
* "Wiki" is short for "wiki wiki", the Hawaiian for "Quick" (and a perfect excuse for a picture of a cute girl in a hula skirt)
* The idea originates from [[http://www.hyperdictionary.com/computing/hypercard][Macintosh Hypercard]], via [[http://www.c2.com/cgi/wiki?WardCunningham][Ward Cunningham]]
* In Ward's words, Wiki is _"the simplest online database that could possibly work"_
* A Wiki is basically a shared, online, persistent whiteboard
---++ Foswiki Wiki
<img align='right' alt='Whiteboard' height='160' src='%ATTACHURL%/whiteboard.gif' width='240' />
Foswiki implements the Wiki idea of a shared whiteboard
* Anyone can add content<br />... or change what is written<br />... or change the organisation of the content
* Whatever you write is<br />... nicely presented<br />... remembered... and never forgotten
* Write using What-You-See-Is-What-You-Get (WYSIWYG) text editing <br />... or you can use plain text with a simple _topic markup language_ that is quick to learn and easy to remember <br />... or you can use full HTML for complex formatting tasks
Foswiki is _also_ an "application platform" that lets you quickly build and use your own online applications <br />... and can be extended using an open _plugins_ architecture <br /> ... with _hundreds_ of user-contributed extensions already available off-the-shelf
Foswiki is an Open-Source development on http://foswiki.org/
* governed by the Foswiki Association
* many volunteer contributors in many countries
* <u>FOS</u>Wiki = <u>F</u>ree <u>O</u>pen <u>S</u>ource Wiki
---++ Foswiki features
Foswiki builds on the original Wiki concept, and adds features that make it very useful in a business environment.
* *Revision control* of all pages, so a record of changes to every page is kept
<table> <tbody> <tr> <td valign='top'> </td> <td> </td> <td style='background-color: #d0d0d0;'>%BLACK%r6 < r5 < r4 < r3 < r2%ENDCOLOR%</td> </tr> </tbody> </table>
* *Powerful macros* allow _users_ to build and use their own online applications
* *Highly configurable* look and feel, through use of templates and macros
* *Plugins interface* eases
* customisation
* extension
* integration of existing applications
* *Hundreds of extensions* support additional features and integrate third party applications
* download from the [[Foswiki:Extensions][Foswiki Extensions website]]
* *Secure and robust* <p> </p>
---++ Applications of basic Foswiki
Foswiki can be used as:
* A whiteboard
* A document repository
* A collaborative authoring environment
* A notebook / scrapbook
* A chat room <p> </p>
---++ Extended applications
Foswiki-with-extensions can be used:
<img alt='' src='%ATTACHURL%/lego.gif' style='float: right;' />
* for Content Management (CMS) of websites
* for presentation development
* as a Blog
* as a (simple) database
* as a project management system
* for mashups
* as a tracking tool
* (_truth is, we don't really know its limits!_) <p> </p>
---++ Structure of a Foswiki page
Foswiki pages are called _topics_. When they are viewed in the browser, they are _usually_ organised into four parts:
* A header
* A menu
* A body
* A footer <p> </p>
* The header and the footer are generated by the system
* The menu is also generated by the system, but mainly from content provided by you
* The body contains the text of the topic, as entered by you <p> </p> <p> </p> <p> </p>
Foswiki is very configurable, and the look can change. However the essentials will all be there on the page (somewhere!)
---++ The page header
The header of a Foswiki page is generally highlighted, and will usually contain an icon that gives you an idea of where you are, such as a company logo. It will also usually contain:
* A *Search* box that allows you to look for topics or content all over the Foswiki site
* A *Jump* box where you can type in the name of a page you already know. <p> </p> <p> </p> <p> </p> <p> </p>
#HeaderSample
<table border='0' cellpadding='5' cellspacing='0' style='width: 100%; background-color: #aaaaff; font-size: 18px;'> <tbody> <tr> <td valign='middle'>%ATTACHURL%/myco.gif</td> <td align='right' valign='top'>
<form name="jumpForm">
<input id="jumpFormField" type="text" name="topic" value="Jump" size="18" style="color:#888888;" />
</form>
<form name="quickSearchForm" > <input type="text" id="quickSearchBox" name="search" value="Search" size="18" style="color:#888888;" /> </form></td> </tr> </tbody> </table> (this is just an example. *Your* header will look _much_ better :-) )
---++ The menu - part 1
The menu, normally located either on the right or the left side of the content, or sometimes at the top, usually includes a toolbox and a web section.
The Toolbox section usually contains these items
<sticky>
* *Toolbox*
* %ICON{"newtopic"}% Create New Topic - for creating new topics via a menu
* %ICON{"index"}% Index - an alphabetical listing of all topics in the web
* %ICON{"searchtopic"}% Search - leads to a more advanced search page
* %ICON{"changes"}% Changes - shows a list of recently changed topics
* %ICON{"notify"}% Notifications - allows you to subscribe to receiving emails when topics change
* %ICON{"feed"}% RSS Feed
* %ICON{"statistics"}% Statistics - for the activities current web
* %ICON{"wrench"}% Preferences - settings for the current web</sticky>
Often the site administrator simplifies the toolbox, so you may not have all these items in your menu bar.
---++ The menu - part 2
The Webs section lists all the webs that you can access
<sticky>
* *Webs*
* <img alt='' border='0' height='16' src='%ICONURL{web-bg}%' style='background-color: #ffefa6;' width='16' /> <nop>%USERSWEB%
* <img alt='' border='0' height='16' src='%ICONURL{web-bg}%' style='background-color: #aaefa6;' width='16' /> <nop>Myco
* <img alt='' border='0' height='16' src='%ICONURL{web-bg}%' style='background-color: #44efa6;' width='16' /> <nop>Project
* <img alt='' border='0' height='16' src='%ICONURL{web-bg}%' style='background-color: #b9daff;' width='16' /> <nop>%SANDBOXWEB%
* <img alt='' border='0' height='16' src='%ICONURL{web-bg}%' style='background-color: #ffd8aa;' width='16' /> <nop>%SYSTEMWEB%</sticky>
A web is a collection of pages that are related closely together
The %USERSWEB% web contains all the user home pages. The %SYSTEMWEB% web contains documentation for Foswiki and all extensions. The %SANDBOXWEB% web is a playground area.
Your wiki may contain any number of webs, and webs can contain other webs.
---++ The menu - part 3
Besides the Tools and Webs sections it is common to add your own links to important places.
These menu entries can be different from web to web.
<sticky>
* *Myco*
* Important topic
* Company philosophy</sticky>
---++ The page footer
#PageFooter
Near the footer of the page you usually find an action bar which looks similar to this
<table border='0' cellpadding='5' cellspacing='0' style='width: 100%; background-color: #2989bb; color: #ffffff; font-size: 18px;'> <tbody> <tr> <td>Edit | Attach | Print version | History: r2 < r1 | Backlinks | View wiki text | Edit wiki text | More topic actions</td> </tr> </tbody> </table>
* The Edit control takes you to an interactive page where you can change the page content using a [[http://www.tinymce.com/][WYSIWYG]] editor
* The Attach link lets you attach files
* Print version shows the page without any menus or top bars - for printing on paper
* History allows you to see older versions and what changed from version to version
* Backlinks shows which other pages link to this page
* View Wiki Text is for viewing the topic using _topic markup language_
* Edit Wiki Text is for editing the topic using _topic markup language_ in a simple text editor
* More topic actions - takes you to a menu of less-frequently-used features <p> </p>
---++ Editing Pages
* You've read a page, and you disagree with it violently! It says:<br /> _Everyone_ *knows* that =the world= is %BLUE%flat%ENDCOLOR%<br />But you know that it is really an Oblate Spheroid! ;-)
* You've clicked the edit link, and an edit page has appeared.
* Depending on your site configuration, you will probably see a WYSIWYG editor and can start writing right away, just like you would in a text processor.
* But if you clicked on the "Edit Wiki Text" link, what you see doesn't look much like what was on the page before.
=_Everyone_ <nop>*knows* that <nop>=the world= is a %<nop>BLUE%flat%<nop>ENCDCOLOR%=
* Now what? <p> </p>
---++ What's in a page
* The hieroglyphics are what's known as "Topic Markup Language"
* They are a really simple way of telling the browser how you want the page to look
* You don't have to use them
* Foswiki understands pages in plain text just fine.<br /><br /> <code>Actually it is an Oblate Spheroid</code><br /><br /> appears as <br /><br /> Actually it is an Oblate Spheroid
* Or you can just use the WYSIYG editor <p> </p>
---++ The hieroglyphs just make pages prettier
... and easier to read<br /><br />
<code>_Actually_ it is an <nop>*Oblate* <nop>__Spheroid__</code><br /><br /> appears as <br /><br /> _Actually_ it is an *Oblate* __Spheroid__
* A full description of all the formatting can be found in the %SYSTEMWEB%.TopicMarkupLanguage.
* The best thing to do is just to type until you get stuck
* then follow the link on the edit page to the help. <p> </p>
---++ Commonly used formatting
Foswiki 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:
* <nop>---+ indicates a heading. Add more +'s for a deeper heading.
<sticky>
<table border='1' cellpadding='0' cellspacing='1'> <tbody> <tr><th>You type</th><th>You see</th></tr> <tr> <td>%BLACK%<code>---+ This is a heading</code>%ENDCOLOR%</td> <td>
<h1>This is a heading</h1>
</td> </tr> <tr> <td> =---++ And so is this= </td> <td>
<h2>And so is this</h2>
</td> </tr> </tbody> </table></sticky>
* %<nop>TOC% will insert a table of contents <p> </p>
---++ More common formatting
* A blank line gives a paragraph break
* <nop>--- on a line of its own gives a horizontal bar
* Text in stars <nop>*like this* looks *like this*
* Text in underscores <nop>_like this_ looks _like this_
* Text in equals signs <nop>=like this= looks =like this=
* Bulleted lists use three spaces followed by an asterisk (=*=) at the start of the line
* The depth of the bullet is given by the number of spaces, in multiples of three
<sticky>
| *You type* | *You see* |
| %BLACK%<code> * Bullet</code><br /><code> * Sub-bullet</code>%ENDCOLOR% | <ul> <li>%BLACK%Bullet%ENDCOLOR% <ul> <li>%BLACK%Sub-bullet%ENDCOLOR%</li> </ul></li> </ul> |</sticky>
* Numbered lists use a number in place of the =*=. The list is numbered automatically, so you can just use a =1= <p> </p>
---++ Even more.....
* You can create a table using vertical bars:
<verbatim>
| Cat | Feline |
| Bear | Ursine |
| Wolf | Lupine |</verbatim>
* appears as
| Cat | Feline |
| Bear | Ursine |
| Wolf | Lupine |
* %<nop>RED% .... %<nop>ENDCOLOR% will change the colour of the enclosed text. Lots of colours are available (%RED%%<nop>RED%%ENDCOLOR%, %GREEN%%<nop>GREEN%%ENDCOLOR%, %BLUE%%<nop>BLUE%%ENDCOLOR% etc) <p> </p>
---++ Wiki<nop>Words
<img alt='' src='%ATTACHURLPATH%/camel.png' style='width: 200px; float: right;' />
* One special hieroglyph that is *very important* is a WikiWord
* a word that starts with uppercase, then some lowercase, then more uppercase (this is known as <nop>CamelCase)
* This has a special meaning to Foswiki. If it matches the name of another topic, Foswiki will automatically create a link to that page for you.
* If there is no such page, then the word is highlighted differently, LikeThis
* If you click on the word, then Foswiki will invite you to create that page. <p> </p>
* This lets you enter the names of topics you _think_ should exist, but don't yet
* You, or someone else, can always come along later and click on the question mark! <p> </p>
---++ Referencing other pages and URLs
* WikiWords automatically link to the target page
* You can make these links easier to read using square brackets:
* =[<nop>[WikiWords][bumpy words]] appears as [[WikiWords][bumpy words]]=
* An ordinary URL pasted into text will appear as a link - http://www.google.com
* You can also prettify URLs using square brackets:
* =[<nop>[http://www.google.com/][Google]]= appears as [[http://www.google.com/][Google]]
* Use %<nop>SEARCH. This is an interface to a sophisticated search engine that embeds the results of the search in your page. See [[%SYSTEMWEB%.Macros][%SYSTEMWEB%.Macros]] for full details. <p> </p>
---++ More formatting
* There's *lots* more formatting available, see %SYSTEMWEB%.TopicMarkupLanguage
* _If you are an HTML expert, you can even enter raw HTML_!
* *Important* to _disable_ unwanted formatting, use =<nop>=
* =<nop>_word_= appears as <nop>_word_ <p> </p>
---++ Creating new pages
* Alternative ways:
* Click on the question mark after a WikiWord
* Type in the name of the topic in the "Go:" box
* Type in the name of the topic in the URL
* Any time you try to visit a page that doesn't exist, Foswiki will invite you to create it.
* Make sure the names of topics are always WikiWords. <p> </p>
---++ Attachments
* Attachments are files which have been uploaded and attached to a Foswiki topic using the ==[Attach]== link in the toolbar. <p> </p>
#FileAttachmentTable
<div class='foswikiAttachments'>
<table cellpadding='0' cellspacing='0' class='foswikiTable' id='foswikiAttachmentsTable' style='border-width: 1px;'> <tbody> <tr class='foswikiTableEven'><th align='center' class='foswikiFirstCol' style='text-align: center; vertical-align: middle;' valign='middle'>
<a rel="nofollow" href="#FileAttachmentTable">I</a>
</th><th align='center' style='text-align: center; vertical-align: middle;' valign='middle'>
<a rel="nofollow" href="#FileAttachmentTable">Attachment</a>
</th><th align='center' style='text-align: center; vertical-align: middle;' valign='middle'>
<a rel="nofollow" href="#FileAttachmentTable">Action</a>
</th><th align='center' style='text-align: center; vertical-align: middle;' valign='middle'>
<a rel="nofollow" href="#FileAttachmentTable">Size</a>
</th><th align='center' style='text-align: center; vertical-align: middle;' valign='middle'>
<a rel="nofollow" href="#FileAttachmentTable">Date</a>
</th><th align='center' style='text-align: center; vertical-align: middle;' valign='middle'>
<a rel="nofollow" href="#FileAttachmentTable">Who</a></th><th align='center' style='text-align: center; vertical-align: middle;' valign='middle'><a rel="nofollow" href="#FileAttachmentTable">Comment</a></th></tr> <tr class='foswikiTableOdd'> <td align='center' class='foswikiFirstCol' style='text-align: center; vertical-align: top;' valign='top'>%ICON{txt}%</td> <td align='left' style='text-align: left; vertical-align: top;' valign='top'> [[#FileAttachmentTable][Sample.txt]]</td> <td align='left' style='text-align: left; vertical-align: top;' valign='top'> [[#FileAttachmentTable][manage]]</td> <td align='left' style='text-align: center; vertical-align: top;' valign='top'>0.1 K</td> <td align='left' style='text-align: left; vertical-align: top;' valign='top'>22 Jul 2000 - 19:37</td> <td align='left' style='text-align: left; vertical-align: top;' valign='top'> [[#FileAttachmentTable][ProjectContributor]]</td> <td align='left' style='text-align: left; vertical-align: top;' valign='top'>Just a sample</td> </tr> <tr class='foswikiTableOdd'> <td align='center' class='foswikiFirstCol' style='text-align: center; vertical-align: top;' valign='top'>%ICON{gif}%</td> <td align='left' style='text-align: left; vertical-align: top;' valign='top'> [[#FileAttachmentTable][Smile.gif]]</td> <td align='left' style='text-align: left; vertical-align: top;' valign='top'> [[#FileAttachmentTable][manage]]</td> <td align='left' style='text-align: center; vertical-align: top;' valign='top'>0.1 K</td> <td align='left' style='text-align: left; vertical-align: top;' valign='top'>22 Jul 2000 - 19:38</td> <td align='left' style='text-align: left; vertical-align: top;' valign='top'> [[#FileAttachmentTable][ProjectContributor]]</td> <td align='left' style='text-align: left; vertical-align: top;' valign='top'>Smiley face</td> </tr> </tbody> </table>
</div>
_The links in the above table are just for show, and don't really go anywhere_
* Attachments are simply files, in whatever format you want.
* Foswiki recognises some file formats, notably image files (.gif, .jpeg, ...)
* Write =%<nop>ATTACHURL%/myco.gif= to see this: %ATTACHURL%/myco.gif
---++ Wiki Culture
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:
* What can I edit?
* Anything. But it's good etiquette to sign your contributions
* If someone doesn't want you to edit a page, it's up to them to say so, clearly, on the page
* But what if somebody doesn't like my edits?
* In Foswiki, they can always recover the old revision and re-instantiate it if they really want to
* Otherwise they should regard your changes as an opportunity for discussion
* Pages in wiki are (usually) in one of three "modes"
* Document<nop>Mode
* Thread<nop>Mode
* Structured<nop>Mode
Foswiki doesn't automatically distinguish between these modes; they are purely semantic.
---++ That's fine for the internet, but...
People often say that wiki culture isn't appropriate in a corporate setting. Ignore them! Sharing information helps any company work more efficiently. However, there may be genuine security concerns, so:
* Viewing/editing topics can be restricted to any indvidual, or group of individuals
* Foswiki can be integrated with corporate single-sign-on solutions
---++ Document<nop>Mode
* A page in Document<nop>Mode usually comprises a contribution which is written in the third person and left unsigned.
* The piece of text is community property
* It may have multiple and changing authors as it is updated to reflect the community consensus.
---++ Thread<nop>Mode
* Thread mode is a form of discussion where the community holds a conversation
* The discussion usually starts out with a statement, at the top of the page, that is subsequently discussed
* The page may be periodically "refactored" (edited) to remove some of the comments
* As long as the comment is accurately reflected in what replaces it, nobody usually minds.
* Remember to always maintain a complete list of contributors, though!
You may see a comment box on a page in Thread<nop>Mode 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" ;-)
* Thread<nop>Mode is rather like an e-mail thread
* Except that new comments are usually added to the end
* Thread<nop>Mode pages often get refactored into Document<nop>Mode
---++ Structured<nop>Mode
* A page in Structured<nop>Mode follows some predefined structure for example
* An agenda
* A set of meeting minutes
* A requirement description.
* Pages in Structured<nop>Mode will usually have rules governing how they are edited.
---++ Contributed features
Basic Foswiki is rich with features, but is enriched even further by optional extension modules that may (or may not!) be installed in your Foswiki. These are usually classified as __skins__ (modules that change the look-and-feel), __plugins__ (modules that enhance functionality), __wiki applications__ (sets of topics that implement an application) or __contribs__ (modules that customise foswiki at a deep level).
When Foswiki is first installed, it comes with a default set of extensions pre-installed; you can see the list by visiting the %SYSTEMWEB%.InstalledPlugins page.
There are a huge number of other extensions available from http://foswiki.org/Extensions
---++ Getting more information
Foswiki has been worked on for over fifteen years, and there's
a lot of it. It can be daunting at first, so don't try to learn the whole
thing in one go. The best way to start is to use it, and when you need to do
something new, browse this web or look for examples online.
If you get stuck, you can refer to the http://foswiki.org/Support web, which has a wealth of online resources, or join the friendly Foswiki IRC channel at irc://irc.freenode.net/foswiki
---++ Credits and Acknowledgements
* This training was developed by Foswiki:Main.CrawfordCurrie on behalf of [[http://www.oxamer.com/][Oxamer]], one of the companies in the [[http://www.ogt.co.uk/][Oxford Gene Technology]] group.
* Valuable contributions were also received from the Foswiki Open Source community; special mentions go to:
* Foswiki:Main.WalterMundt
* Foswiki:Main.SvenDowideit
* The latest version of this presentation is available at Foswiki:%WEB%.%TOPIC%
%SLIDESHOWEND%
__Related topics:__ WelcomeGuest, WikiCulture, TwentyMinuteTutorial, TopicsAndWebs
%META:FILEATTACHMENT{name="myco.gif" attachment="myco.gif" attr="h" comment="" date="1428396345" size="1834" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="whiteboard.gif" attachment="whiteboard.gif" attr="h" comment="" date="1428396345" size="13471" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="SAP_logo.gif" attachment="SAP_logo.gif" attr="h" comment="" date="1428396345" size="2711" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="Motorola_logo.gif" attachment="Motorola_logo.gif" attr="h" comment="" date="1428396345" size="2394" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="lego.gif" attachment="lego.gif" attr="h" comment="" date="1428396345" size="4084" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="hula.gif" attachment="hula.gif" attr="h" comment="" date="1428396345" size="8780" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="EpicGames_logo.gif" attachment="EpicGames_logo.gif" attr="h" comment="" date="1428396345" size="2270" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="Disney_logo.gif" attachment="Disney_logo.gif" attr="h" comment="" date="1428396345" size="1506" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="BT_logo.gif" attachment="BT_logo.gif" attr="h" comment="" date="1428396345" size="1687" user="ProjectContributor" version="1"}%
%META:FILEATTACHMENT{name="camel.png" attachment="camel.png" attr="h" comment="" date="1428396345" size="1687" user="ProjectContributor" version="1"}%