none
[openafs-wiki.git] / TWiki / TextFormattingRules.mdwn
1 <div>
2   <ul>
3     <li><a href="#TWiki Text Formatting"> TWiki Text Formatting</a><ul>
4         <li><a href="#TWiki Editing Shorthand"> TWiki Editing Shorthand</a></li>
5         <li><a href="#Using HTML"> Using HTML</a></li>
6         <li><a href="#Hyperlinks"> Hyperlinks</a><ul>
7             <li><a href="#Internal Links"> Internal Links</a></li>
8             <li><a href="#External Links"> External Links</a></li>
9           </ul>
10         </li>
11         <li><a href="#TWiki Variables"> TWiki Variables</a></li>
12         <li><a href="#Common Editing Errors"> Common Editing Errors</a></li>
13         <li><a href="#TWiki Plugins"> TWiki Plugins</a></li>
14       </ul>
15     </li>
16   </ul>
17 </div>
18
19 # <a name="TWiki Text Formatting"></a> TWiki Text Formatting
20
21 Working in TWiki is as easy as typing in text - exactly like email. You don't need to know HTML, though you can use it if you prefer. Links to topics are created automatically when you enter [[WikiWords]]. And TWiki shorthand gives you all the power of HTML with a simple coding system that takes no time to learn. It's all layed out below - refer back to this page in a pop-up window from the **Edit** screen.
22
23 <a name="TWikiShorthand"></a>
24
25 ## <a name="TWiki Editing Shorthand"></a> TWiki Editing Shorthand
26
27 <table bgcolor="#000000" border="0" cellpadding="3" cellspacing="1">
28   <tr bgcolor="#ffffff">
29     <td><strong>Formatting Command:</strong></td>
30     <td><strong>Example: You write:</strong></td>
31     <td><strong>You get:</strong></td>
32   </tr>
33   <tr bgcolor="#ffffff">
34     <td valign="top"><strong>Paragraphs:</strong><br /> Blank lines will create new paragraphs. </td>
35     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
36 1st paragraph
37
38 2nd paragraph
39 </pre> </font></span></td>
40     <td valign="top"> 1st paragraph <p> 2nd paragraph </p>
41     </td>
42   </tr>
43   <tr bgcolor="#ffffff">
44     <td valign="top"><strong>Headings:</strong><br /> At least three dashes at the beginning of a line, followed by plus signs and the heading text. One plus creates a level 1 heading (most important), two pluses a level 2 heading; the maximum is level 6. <strong><em>Note:</em></strong> A Table of Content can be created automatically with the <code>%TOC%</code> variable, see [[Main/TWikiVariables]]. </td>
45     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
46 ---++ Sushi
47
48 ---+++ Maguro
49 </pre> </font></span></td>
50     <td valign="top">
51       <h2>Sushi</h2>
52       <p>
53       </p>
54       <h3>Maguro</h3>
55     </td>
56   </tr>
57   <tr bgcolor="#ffffff">
58     <td valign="top"><strong>Bold Text:</strong><br /> Words get <strong>bold</strong> by enclosing them in <code>*</code> asterisks. </td>
59     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
60 *Bold*
61 </pre> </font></span></td>
62     <td valign="top"><strong>Bold</strong></td>
63   </tr>
64   <tr bgcolor="#ffffff">
65     <td valign="top"><strong>Italic Text:</strong><br /> Words get <em>italic</em> by enclosing them in <code>_</code> underscores. </td>
66     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
67 _Italic_
68 </pre> </font></span></td>
69     <td valign="top"><em>Italic</em></td>
70   </tr>
71   <tr bgcolor="#ffffff">
72     <td valign="top"><strong>Bold Italic:</strong><br /> Words get <em>_bold italic</em> by enclosing them in <code>_</code> double-underscores. </td>
73     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
74 __Bold italic__
75 </pre> </font></span></td>
76     <td valign="top"><strong><em>Bold italic</em></strong></td>
77   </tr>
78   <tr bgcolor="#ffffff">
79     <td valign="top"><strong>Fixed Font:</strong><br /> Words get shown in <code>fixed font</code> by enclosing them in <code>=</code> equal signs. </td>
80     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
81 =Fixed font=
82 </pre> </font></span></td>
83     <td valign="top"><code>Fixed font</code></td>
84   </tr>
85   <tr bgcolor="#ffffff">
86     <td valign="top"><strong>Bold Fixed Font:</strong><br /> Words get shown in <code><b>bold fixed font</b></code> by enclosing them in <code><b></b></code> double equal signs. </td>
87     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
88 ==Bold fixed==
89 </pre> </font></span></td>
90     <td valign="top"><code><b>Bold fixed</b></code></td>
91   </tr>
92   <tr bgcolor="#ffffff">
93     <td valign="top"><strong><em>Note:</em></strong> Make sure to "stick" the <code>* _ = ==</code> signs to the words, e.g. take away spaces. </td>
94     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
95 _This works_,
96 _this not _
97 </pre> </font></span></td>
98     <td valign="top"><em>This works</em>, _this not _ </td>
99   </tr>
100   <tr bgcolor="#ffffff">
101     <td valign="top"><strong>Verbatim Mode:</strong><br /> Surround code excerpts and other formatted text with <code>&lt;verbatim&gt;</code> and <code>&lt;/verbatim&gt;</code> tags. <br /><strong><em>Note:</em></strong> Use <code>&lt;pre&gt;</code> and <code>&lt;/pre&gt;</code> tags instead if you want that HTML code is interpreted. <br /><strong><em>Note:</em></strong> Each tag must be on a line by itself. </td>
102     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
103 &lt;verbatim&gt;
104 class CatAnimal {
105   void purr() {
106          &lt;code here&gt;
107   }
108 }
109 &lt;/verbatim&gt;
110 </pre> </font></span></td>
111     <td valign="top"><pre>
112 class CatAnimal {
113   void purr() {
114     &lt;code here&gt;
115   }
116 }
117 </pre></td>
118   </tr>
119   <tr bgcolor="#ffffff">
120     <td valign="top"><strong>Separator:</strong><br /> At least three dashes at the beginning of a line. </td>
121     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
122 -------
123 </pre> </font></span></td>
124     <td valign="top">
125       <hr />
126     </td>
127   </tr>
128   <tr bgcolor="#ffffff">
129     <td valign="top"><strong>List Item:</strong><br /> Three spaces and an asterisk. </td>
130     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
131         * bullet item
132 </pre> </font></span></td>
133     <td valign="top">
134       <ul>
135         <li> bullet item </li>
136       </ul>
137     </td>
138   </tr>
139   <tr bgcolor="#ffffff">
140     <td valign="top"><strong>Nested List Item:</strong><br /> Six, nine, ... spaces and an asterisk. </td>
141     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
142                 * nested stuff
143 </pre> </font></span></td>
144     <td valign="top">
145       <ul>
146         <li>
147           <ul>
148             <li> nested stuff </li>
149           </ul>
150         </li>
151       </ul>
152     </td>
153   </tr>
154   <tr bgcolor="#ffffff">
155     <td valign="top"><strong>Ordered List:</strong><br /> Three spaces and a number. </td>
156     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
157         1 Sushi
158         1 Dim Sum
159 </pre> </font></span></td>
160     <td valign="top">
161       <ol>
162         <li> Sushi </li>
163         <li> Dim Sum </li>
164       </ol>
165     </td>
166   </tr>
167   <tr bgcolor="#ffffff">
168     <td valign="top"><strong>Definition List:</strong><br /> Three spaces, the term, a colon, a space, followed by the definition. <br /><strong><em>Note:</em></strong> Terms with spaces are not supported. In case you do have a term with more then one word, separate the words with dashes or with the <code>&amp;nbsp;</code> non-breaking-space entity. </td>
169     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
170         Sushi: Japan
171         Dim&amp;nbsp;Sum: S.F.
172 </pre> </font></span></td>
173     <td valign="top">
174       <dl>
175         <dt> Sushi</dt>
176         <dd> Japan </dd>
177         <dt> Dim Sum</dt>
178         <dd> S.F. </dd>
179       </dl>
180     </td>
181   </tr>
182   <tr bgcolor="#ffffff">
183     <td valign="top"><strong>Table:</strong><br /> Optional spaces followed by the cells enclosed in vertical bars. <br /><strong><em>Note:</em></strong> <code>| *bold* |</code> cells are rendered as table headers. <br /><strong><em>Note:</em></strong> <code>|   spaced   |</code> cells are rendered center aligned. <br /><strong><em>Note:</em></strong> <code>|     spaced |</code> cells are rendered right aligned. <br /><strong><em>Note:</em></strong> <code>| 2 colspan ||</code> cells are rendered as multi-span columns. <br /><strong><em>Note:</em></strong> In case you have a long row and you want it to be more readable when you edit the table you can split the row into lines that end with a <code>'\'</code> backslash character. <br />
184     </td>
185     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
186 | *L* | *C* | *R* |
187 | A2 |  2  |  2 |
188 | A3 |  3  |  3 |
189 | multi span |||
190 | A4 \  | next \  | next |
191 </pre> </font></span></td>
192     <td valign="top">
193       <table border="1" cellpadding="0" cellspacing="0">
194         <tr>
195           <th bgcolor="#99CCCC"><strong> L </strong></th>
196           <th bgcolor="#99CCCC"><strong> C </strong></th>
197           <th bgcolor="#99CCCC"><strong> R </strong></th>
198         </tr>
199         <tr>
200           <td> A2 </td>
201           <td align="center"> 2 </td>
202           <td align="right"> 2 </td>
203         </tr>
204         <tr>
205           <td> A3 </td>
206           <td align="center"> 3 </td>
207           <td align="right"> 3 </td>
208         </tr>
209         <tr>
210           <td colspan="3"> multi span </td>
211         </tr>
212         <tr>
213           <td> A4 </td>
214           <td> next </td>
215           <td> next </td>
216         </tr>
217       </table>
218     </td>
219   </tr>
220   <tr bgcolor="#ffffff">
221     <td valign="top"><strong>WikiWord Links:</strong><br /> CapitalizedWordsStuckTogether (or [[Main/WikiWords]]) will produce a link automatically. <br /><strong><em>Note:</em></strong> In case you want to link to a topic in a different %WIKITOOLNAME% web write <code>Webname.TopicName</code>. </td>
222     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
223 WebNotify
224
225 Know.ReadmeFirst
226 </pre> </font></span></td>
227     <td valign="top">[[Main/WebNotify]]<p>[[Know/ReadmeFirst]]</p>
228     </td>
229   </tr>
230   <tr bgcolor="#ffffff">
231     <td valign="top">#SquareBrackets <strong>Forced Links:</strong><br /> You can create a forced internal link by enclosing words in double square brackets. <br /><strong><em>Note:</em></strong> Text within the brackets may contain optional spaces; the topic name is formed by capitalizing the initial letter and by removing the spaces; i.e. <code>[[text formatting FAQ]]</code> links to topic [[Main/TextFormattingFAQ]]. You can also refer to a different web and use anchors. </td>
232     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
233 [[wiki syntax]]
234
235 [[Main.TWiki users]]
236 </pre> </font></span></td>
237     <td valign="top">[[Main/WikiSyntax]]<p>[[Main/TWikiUsers]]</p>
238     </td>
239   </tr>
240   <tr bgcolor="#ffffff">
241     <td valign="top"><strong>Specific Links:</strong><br /> Create a link where you can specify the link text and the link reference separately, using nested square brackets like <code>[[reference][text]]</code>. Internal link references (i.e. [[Main/WikiSyntax]]) and external link references (i.e. <a href="http://TWiki.org/" target="_top">http://TWiki.org/</a>) are supported. The same <strong><em>Forced Links</em></strong> rules apply for internal link references. Anchor names can be added as well, like <code>[[WebHome#MyAnchor][go home]]</code> and <code>[[http://www.yahoo.com/#somewhere][Yahoo!]]</code>. </td>
242     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
243 [[WikiSyntax][syntax]]
244
245 [[http://gnu.org][GNU]]
246 </pre> </font></span></td>
247     <td valign="top">[[Main/WikiSyntax]]<p><a href="http://gnu.org" target="_top">GNU</a></p>
248     </td>
249   </tr>
250   <tr bgcolor="#ffffff">
251     <td valign="top"><strong>Anchors:</strong><br /> You can define a link reference inside a %WIKITOOLNAME% topic (called an anchor name) and link to that. To <strong><em>define</em></strong> an anchor write <code>#AnchorName</code> at the beginning of a line. The anchor name must be a [[Main/WikiWord]]. To <strong><em>link to</em></strong> an anchor name use the <code>[[MyTopic#MyAnchor]]</code> syntax. You can omit the topic name if you want to link within the same topic. </td>
252     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
253 [[WebHome#NotThere]]
254
255 [[#MyAnchor][Jump]]
256
257 #MyAnchor To here
258 </pre> </font></span></td>
259     <td valign="top">[[Main/WebHome#NotThere]]<p>[[Main/WebHome#MyAnchor]]</p>
260       <p><a name="MyAnchor"></a> To here </p>
261     </td>
262   </tr>
263   <tr bgcolor="#ffffff">
264     <td valign="top"><strong>Prevent a Link:</strong><br /> Prevent a [[Main/WikiWord]] from being linked by prepending it with the <code>&lt;nop&gt;</code> tag. </td>
265     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
266 &lt;nop&gt;SunOS
267 </pre> </font></span></td>
268     <td valign="top"> SunOS </td>
269   </tr>
270 </table>
271
272 ## <a name="Using HTML"></a> Using HTML
273
274 You can use just about any HTML tag without a problem - however, to keep in mind:
275
276 - On collaboration pages, it's preferable NOT to use HTML, and to use [[TWiki shorthand|Main/WebHome#TWikiShorthand]] instead - this keeps the text uncluttered and easy to edit.
277   - **_NOTE:_** TWiki converts shorthand notation to XHTML 1.0 for display. To copy a fully marked-up page, simply view source in your browser and save the contents.
278   - **_NOTE:_** The standard installation TWiki is compatible across a wide range of browsers and computer platforms. If this is important to you, remember that using browser-specific tags or any other mark-up that doesn't degrade well will reduce compatibility.
279
280 ## <a name="Hyperlinks"></a> Hyperlinks
281
282 Being able to create links without any formatting required is a core TWiki feature, made possible with [[WikiWords]]. New TWiki linking rules are a simple extension of the syntax that provide a new set of flexible options.
283
284 ### <a name="Internal Links"></a> Internal Links
285
286 - [[GoodStyle]] is a [[WikiWord]] that links to the GoodStyle topic located in the current %WIKITOOLNAME% web.
287
288 - [[NotExistingYet]] is a topic waiting to be written. Create the topic by clicking on the **?**. (Try clicking, but then, **Cancel** - creating the topic would wreck this example!)
289
290 ### <a name="External Links"></a> External Links
291
292 - `http://...`, `https://...`, `ftp://...` and `mailto:...@...` are linked automatically.
293
294 - Email addresses like `name@domain.com` are linked automatically.
295
296 - `[[Square bracket rules]]` let you easily create [[non-WikiWord links|Main/WebHome#SquareBrackets]].
297
298 ## <a name="TWiki Variables"></a> TWiki Variables
299
300 Variables are names that are enclosed in percent signs `%` that are expanded on the fly.
301
302 - `%TOC%` : Automatically generates a table of contents based on headings in a topic - see the top of this page for an example.
303
304 - `%WEB%` : The current web, is **%WEB%**.
305
306 - `%TOPIC%` : The current topic name, is **%TOPIC%**.
307
308 - `%ATTACHURL%` : The attachment URL of the current topic. Example usage: If you attach a file to a topic you can refer to it as <code>**%ATTACHURL%/image.gif**</code> to show the URL of the file or the image in your text.
309
310 - `%INCLUDE{"SomeTopic"}%` : Server side include, includes another topic. The current %WIKITOOLNAME% web is the default web. Example: <code>**%INCLUDE\{"TWiki.TWikiWebsTable"\}%**</code>
311
312 - There are many more variables, see **[[TWikiVariables]]**.
313
314 ## <a name="Common Editing Errors"></a> Common Editing Errors
315
316 TWiki formatting rules are fairly simple to use and quick to type. However, there are some things to watch out for, taken from the [[TextFormattingFAQ]]:
317
318 - **Q:** Text enclosed in angle brackets like `<filename>` is not displayed. How can I show it as it is?
319   - **A:** The `'<'` and `'>'` characters have a special meaning in HTML, they define HTML tags. You need to escape them, so write `'&lt;'` instead of `'<'`, and `'&gt;'` instead of `'>'`. <br /> Example: Type `'prog &lt;filename&gt;'` to get `'prog <filename>'`.
320
321 - **Q:** Why is the `'&'` character sometimes not displayed?
322   - **A:** The `'&'` character has a special meaning in HTML, it starts a so called character entity, i.e. `'&copy;'` is the `©` copyright character. You need to escape `'&'` to see it as it is, so write `'&amp;'` instead of `'&'`. <br /> Example: Type `'This &amp; that'` to get `'This & that'`.
323
324 ## <a name="TWiki Plugins"></a> TWiki Plugins
325
326 Plugins provide additional text formatting capabilities and can extend the functionality of %WIKITOOLNAME% into many other areas. For example, one optional Plugin lets you create a basic spreadsheet in a similar way to tables. Available Plugins are located in the [[Plugins|Main/TWiki:Plugins]] web on TWiki.org. Currently enabled plugins on here:
327
328 - [[SpreadSheetPlugin]] <span>(any TWiki, 10197)</span>:
329 - [[CommentPlugin]] <span>(Dakar, 11359)</span>: Allows users to quickly post comments to a page without an edit/preview/save cycle
330 - [[EditTablePlugin]] <span>(any TWiki, 11646)</span>:
331 - [[InterwikiPlugin]] <span>(Dakar, $Rev: 11935$)</span>:
332 - [[PreferencesPlugin]] <span>(Dakar, 9839)</span>:
333 - [[SlideShowPlugin]] <span>(Any TWiki, $Rev: 12847$)</span>:
334 - [[SmiliesPlugin]] <span>(Dakar, 8154)</span>:
335 - [[TablePlugin]] <span>(1.020, 12339)</span>:
336 - [[TwistyPlugin]] <span>(1.2.0, $Rev: 12154$)</span>:
337
338 Check on current Plugin status and settings for this site in [[TWikiPreferences]].
339
340 -- [[MikeMannix]] - 30 Aug 2001