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><ul>
6             <li><a href="#HTML and TWiki Usability"> HTML and TWiki Usability</a></li>
7             <li><a href="#TWiki HTML Rendering"> TWiki HTML Rendering</a></li>
8           </ul>
9         </li>
10         <li><a href="#Hyperlinks"> Hyperlinks</a><ul>
11             <li><a href="#Internal Links"> Internal Links</a></li>
12             <li><a href="#External Links"> External Links</a></li>
13           </ul>
14         </li>
15         <li><a href="#TWiki Variables"> TWiki Variables</a></li>
16         <li><a href="#TWikiPlugin Formatting Extension"> TWikiPlugin Formatting Extensions</a></li>
17         <li><a href="#Common Editing Errors"> Common Editing Errors</a></li>
18       </ul>
19     </li>
20   </ul>
21 </div>
22
23 # <a name="TWiki Text Formatting"></a> TWiki Text Formatting
24
25 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.
26
27 <a name="TWikiShorthand"></a>
28
29 ## <a name="TWiki Editing Shorthand"></a> TWiki Editing Shorthand
30
31 <table bgcolor="#000000" border="1" cellpadding="3" cellspacing="1">
32   <tr bgcolor="#ffffff">
33     <td><strong>Formatting Command:</strong></td>
34     <td><strong>Example: You write:</strong></td>
35     <td><strong>You get:</strong></td>
36   </tr>
37   <tr bgcolor="#ffffff">
38     <td valign="top"><strong>Paragraphs:</strong> %BR% Blank lines will create new paragraphs. </td>
39     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
40 1st paragraph
41
42 2nd paragraph
43 </pre> </font></span></td>
44     <td valign="top"> 1st paragraph <p> 2nd paragraph </p>
45     </td>
46   </tr>
47   <tr bgcolor="#ffffff">
48     <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]]. Any heading text after <code>!!</code> is excluded from the TOC; for example, write <code>---+!! text</code> if you do not want to list a header in the TOC. </td>
49     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
50 ---++ Sushi
51
52 ---+++ Maguro
53 </pre> </font></span></td>
54     <td valign="top">
55       <h2>Sushi</h2>
56       <p>
57       </p>
58       <h3>Maguro</h3>
59     </td>
60   </tr>
61   <tr bgcolor="#ffffff">
62     <td valign="top"><strong>Bold Text:</strong> %BR% Words get <strong>bold</strong> by enclosing them in <code>*</code> asterisks. </td>
63     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
64 *Bold*
65 </pre> </font></span></td>
66     <td valign="top"><strong>Bold</strong></td>
67   </tr>
68   <tr bgcolor="#ffffff">
69     <td valign="top"><strong>Italic Text:</strong> %BR% Words get <em>italic</em> by enclosing them in <code>_</code> underscores. </td>
70     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
71 _Italic_
72 </pre> </font></span></td>
73     <td valign="top"><em>Italic</em></td>
74   </tr>
75   <tr bgcolor="#ffffff">
76     <td valign="top"><strong>Bold Italic:</strong> %BR% Words get <em>_bold italic</em> by enclosing them in <code>_</code> double-underscores. </td>
77     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
78 __Bold italic__
79 </pre> </font></span></td>
80     <td valign="top"><strong><em>Bold italic</em></strong></td>
81   </tr>
82   <tr bgcolor="#ffffff">
83     <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>
84     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
85 =Fixed font=
86 </pre> </font></span></td>
87     <td valign="top"><code>Fixed font</code></td>
88   </tr>
89   <tr bgcolor="#ffffff">
90     <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>
91     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
92 ==Bold fixed==
93 </pre> </font></span></td>
94     <td valign="top"><code><b>Bold fixed</b></code></td>
95   </tr>
96   <tr bgcolor="#ffffff">
97     <td valign="top"><strong><em>Note:</em></strong> Make sure to "stick" the <code>* _ = ==</code> signs to the words, that is, take away spaces. </td>
98     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
99 _This works_,
100 _this not _
101 </pre> </font></span></td>
102     <td valign="top"><em>This works</em>, _this not _ </td>
103   </tr>
104   <tr bgcolor="#ffffff">
105     <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>
106     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
107 &lt;verbatim&gt;
108 class CatAnimal {
109   void purr() {
110          &lt;code here&gt;
111   }
112 }
113 &lt;/verbatim&gt;
114 </pre> </font></span></td>
115     <td valign="top"><pre>
116 class CatAnimal {
117   void purr() {
118     &lt;code here&gt;
119   }
120 }
121 </pre></td>
122   </tr>
123   <tr bgcolor="#ffffff">
124     <td valign="top"><strong>Separator:</strong> %BR% At least three dashes at the beginning of a line. </td>
125     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
126 -------
127 </pre> </font></span></td>
128     <td valign="top">
129       <hr />
130     </td>
131   </tr>
132   <tr bgcolor="#ffffff">
133     <td valign="top"><strong>List Item:</strong> %BR% Three spaces and an asterisk. </td>
134     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
135         * bullet item
136 </pre> </font></span></td>
137     <td valign="top">
138       <ul>
139         <li> bullet item </li>
140       </ul>
141     </td>
142   </tr>
143   <tr bgcolor="#ffffff">
144     <td valign="top"><strong>Nested List Item:</strong> %BR% Six, nine, ... spaces and an asterisk. </td>
145     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
146                 * nested stuff
147 </pre> </font></span></td>
148     <td valign="top">
149       <ul>
150         <li>
151           <ul>
152             <li> nested stuff </li>
153           </ul>
154         </li>
155       </ul>
156     </td>
157   </tr>
158   <tr bgcolor="#ffffff">
159     <td valign="top"><strong>Ordered List:</strong> %BR% Three spaces and a number. </td>
160     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
161         1 Sushi
162         1 Dim Sum
163 </pre> </font></span></td>
164     <td valign="top">
165       <ol>
166         <li> Sushi </li>
167         <li> Dim Sum </li>
168       </ol>
169     </td>
170   </tr>
171   <tr bgcolor="#ffffff">
172     <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>
173     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
174         Sushi: Japan
175         Dim&amp;nbsp;Sum: S.F.
176 </pre> </font></span></td>
177     <td valign="top">
178       <dl>
179         <dt> Sushi</dt>
180         <dd> Japan </dd>
181         <dt> Dim Sum</dt>
182         <dd> S.F. </dd>
183       </dl>
184     </td>
185   </tr>
186   <tr bgcolor="#ffffff">
187     <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% </td>
188     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
189 | *L* | *C* | *R* |
190 | A2 |  2  |  2 |
191 | A3 |  3  |  3 |
192 | multi span |||
193 | A4 | next | next |
194 </pre> </font></span></td>
195     <td valign="top">
196       <table border="1" cellpadding="0" cellspacing="0">
197         <tr>
198           <th bgcolor="#99CCCC"><strong> L </strong></th>
199           <th bgcolor="#99CCCC"><strong> C </strong></th>
200           <th bgcolor="#99CCCC"><strong> R </strong></th>
201         </tr>
202         <tr>
203           <td> A2 </td>
204           <td align="center"> 2 </td>
205           <td align="right"> 2 </td>
206         </tr>
207         <tr>
208           <td> A3 </td>
209           <td align="center"> 3 </td>
210           <td align="right"> 3 </td>
211         </tr>
212         <tr>
213           <td colspan="3"> multi span </td>
214         </tr>
215         <tr>
216           <td> A4 </td>
217           <td> next </td>
218           <td> next </td>
219         </tr>
220       </table>
221     </td>
222   </tr>
223   <tr bgcolor="#ffffff">
224     <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>
225     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
226 WebNotify
227
228 Know.ReadmeFirst
229 </pre> </font></span></td>
230     <td valign="top">[[Main/WebNotify]]<p>[[Know/ReadmeFirst]]</p>
231     </td>
232   </tr>
233   <tr bgcolor="#ffffff">
234     <td valign="top"><a name="SquareBrackets"></a> <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; for example, <code>[[text formatting FAQ]]</code> links to topic [[Main/TextFormattingFAQ]]. You can also refer to a different web and use anchors. </td>
235     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
236 [[wiki syntax]]
237
238 [[Main.TWiki users]]
239 </pre> </font></span></td>
240     <td valign="top">[[Main/WikiSyntax]]<p>[[Main/TWikiUsers]]</p>
241     </td>
242   </tr>
243   <tr bgcolor="#ffffff">
244     <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 (e.g. [[Main/WikiSyntax]]) and external link references (e.g. <a href="http://TWiki.org/" target="_top">http://TWiki.org/</a>) are supported. %BR% <strong><em>Note:</em></strong> The same <strong><em>Forced Links</em></strong> rules apply for internal link references. %BR% <strong><em>Note:</em></strong> For external link references, you can simply use a space instead of <code>][</code> to separate the link URL from the descriptive text. %BR% <strong><em>Note:</em></strong> Anchor names can be added as well, like <code>[[WebHome#MyAnchor][go home]]</code> and <code>[[http://gnu.org/#Action][GNU Action]]</code>. </td>
245     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
246 [[WikiSyntax][syntax]]
247
248 [[http://gnu.org][GNU]]
249
250 [[http://xml.org XML]]
251 </pre> </font></span></td>
252     <td valign="top">[[Main/WikiSyntax]]<p><a href="http://gnu.org" target="_top">GNU</a></p>
253       <p><a href="http://xml.org" target="_top">XML</a></p>
254     </td>
255   </tr>
256   <tr bgcolor="#ffffff">
257     <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>
258     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
259 [[WebHome#NotThere]]
260
261 [[#MyAnchor][Jump]]
262
263 #MyAnchor To here
264 </pre> </font></span></td>
265     <td valign="top">[[Main/WebHome#NotThere]]<p>[[Main/WebHome#MyAnchor]]</p>
266       <p><a name="MyAnchor"></a> To here </p>
267     </td>
268   </tr>
269   <tr bgcolor="#ffffff">
270     <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>
271     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
272 &lt;nop&gt;SunOS
273 </pre> </font></span></td>
274     <td valign="top"> SunOS </td>
275   </tr>
276   <tr bgcolor="#ffffff">
277     <td valign="top"><strong>Disable Links:</strong> %BR% You can disable automatic linking of [[Main/WikiWords]] by surrounding text with <code>&lt;noautolink&gt;</code> and <code>&lt;/noautolink&gt;</code> tags. %BR% <strong><em>Note:</em></strong> Each tag must be on a line by itself. %BR% <strong><em>Note:</em></strong> This also works for TWiki tables, but only if you add a blank line between the end of the table and the closing <code>&lt;/noautolink&gt;</code> tag (known issue of the [[Main/TablePlugin]]). </td>
278     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
279  &lt;noautolink&gt;
280  RedHat &amp;
281  SuSE
282  &lt;/noautolink&gt;
283 </pre> </font></span></td>
284     <td valign="top"> RedHat &amp; SuSE </td>
285   </tr>
286   <tr bgcolor="#ffffff">
287     <td valign="top"><strong>Mailto: Links:</strong> %BR% To create 'mailto:' links that have more descriptive link text, specify subject lines or message bodies, or omit the email address, you can write <code>[[mailto:user@domain descriptive text]]</code>. </td>
288     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
289 [[mailto:a@z.com Mail]]
290
291 [[mailto:?subject=Hi Hi]]
292 </pre> </font></span></td>
293     <td valign="top"><a href="mailto:a@z.com">Mail</a><p><a href="mailto:?subject=Hi">Hi</a></p>
294     </td>
295   </tr>
296 </table>
297
298 ## <a name="Using HTML"></a> Using HTML
299
300 You can use just about any HTML tag without a problem - however, there are a few usability and technical considerations to keep in mind.
301
302 ### <a name="HTML and TWiki Usability"></a> HTML and TWiki Usability
303
304 - 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.
305 - %X% **NOTE:** TWiki is designed to work with a wide range of browsers and computer platforms, holding to HTML 3.2 compatibility in the standard installation - adding raw HTML, particularly browser-specific tags (or any other mark-up that doesn't degrade well) will reduce compatibility.
306
307 ### <a name="TWiki HTML Rendering"></a> TWiki HTML Rendering
308
309 - 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.
310   - %T% If you need to save HTML frequently, you may want to check out TWiki:Plugins/GenHTMLAddon - it will "generate a directory containing rendered versions of a set of TWiki pages together with any attached files."
311 - %X% **NOTE:** The opening and closing angle brackets - <code>**&lt;...&gt;**</code> - of an HTML tag **_must be on the same line_**, or the tag will be broken.
312   - This feature allows you to enter an unclosed angle bracket - as a greater than or less than symbol - and have it automatically rendered as if you had entered its HTML character, `&lt;`, ex: <code>**a &gt; b**</code>
313   - %T% If you're pasting in preformatted HTML text and notice problems, check the file in a text processor with no text wrap. Also, save without hard line breaks on text wrap, in your HTML editing program.
314
315 ## <a name="Hyperlinks"></a> Hyperlinks
316
317 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.
318
319 ### <a name="Internal Links"></a> Internal Links
320
321 - [[GoodStyle]] is a [[WikiWord]] that links to the GoodStyle topic located in the current %WIKITOOLNAME% web.
322
323 - [[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!)
324
325 ### <a name="External Links"></a> External Links
326
327 - `http://...`, `https://...`, `ftp://...` and `mailto:...@...` are linked automatically.
328
329 - Email addresses like `name@domain.com` are linked automatically.
330
331 - `[[Square bracket rules]]` let you easily create [[non-WikiWord links|Main/WebHome#SquareBrackets]].
332   - You can also write `[[http://yahoo.com Yahoo home page]]` as an easier way of doing external links with descriptive text for the link, such as [Yahoo home page](http://yahoo.com/).
333
334 ## <a name="TWiki Variables"></a> TWiki Variables
335
336 Variables are names that are enclosed in percent signs `%` that are expanded on the fly.
337
338 - `%TOC%` : Automatically generates a table of contents based on headings in a topic - see the top of this page for an example.
339
340 - `%WEB%` : The current web, is **%WEB%**.
341
342 - `%TOPIC%` : The current topic name, is **%TOPIC%**.
343
344 - `%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.
345
346 - `%INCLUDE{"SomeTopic"}%` : Server side include, includes another topic. The current %WIKITOOLNAME% web is the default web. Example: <code>**%INCLUDE\{"TWiki.SiteMap"\}%**</code>
347
348 - `%SEARCH{"sushi"}%` : Inline search showing the search result embedded in a topic. [[FormattedSearch]] gives you control over formatting, used to create web-based applications.
349
350 - [[TWikiPreferences]] defines site-wide variables. Among others:
351   - **Line break:** Write <code><span><font>%BR%</font></span></code> to start a new line.
352   - **Colored text:** Write: <code><span><font> %RED% Red %ENDCOLOR% and %BLUE% blue %ENDCOLOR% colors</font></span></code> to get: %RED% Red %ENDCOLOR% and %BLUE% blue %ENDCOLOR% colors.
353   - **Documentation Graphics:** Write: <code><span><font> %H% Help, %T% Tip, %X% Alert</font></span></code> to get: %H% Help, %T% Tip, %X% Alert. For more info see [[TWikiDocGraphics]].
354
355 - There are many more variables, see **[[TWikiVariables]]**.
356
357 ## <a name="TWikiPlugin Formatting Extension"></a><a name="_TWikiPlugin Formatting Extensio"></a> TWikiPlugin Formatting Extensions
358
359 Plugins provide additional text formatting capabilities and can extend the functionality of %WIKITOOLNAME% into many other areas. For example, the optional [SpreadSheetPlugin](http://twiki.org/cgi-bin/view/Plugins/SpreadSheetPlugin) lets you create a spreadsheet with the same basic notation used in TWiki tables.
360
361 Available Plugins are located in the [Plugins](http://twiki.org/cgi-bin/view/Plugins) web on TWiki.org. Currently enabled plugins on this TWiki installation, as listed by `%PLUGINDESCRIPTIONS%`:
362
363 - [[SpreadSheetPlugin]] <span>(any TWiki, 10197)</span>:
364 - [[CommentPlugin]] <span>(Dakar, 11359)</span>: Allows users to quickly post comments to a page without an edit/preview/save cycle
365 - [[EditTablePlugin]] <span>(any TWiki, 11646)</span>:
366 - [[InterwikiPlugin]] <span>(Dakar, $Rev: 11935$)</span>:
367 - [[PreferencesPlugin]] <span>(Dakar, 9839)</span>:
368 - [[SlideShowPlugin]] <span>(Any TWiki, $Rev: 12847$)</span>:
369 - [[SmiliesPlugin]] <span>(Dakar, 8154)</span>:
370 - [[TablePlugin]] <span>(1.020, 12339)</span>:
371 - [[TwistyPlugin]] <span>(1.2.0, $Rev: 12154$)</span>:
372
373 Check on current Plugin status and settings for this site in [[TWikiPreferences]].
374
375 ## <a name="Common Editing Errors"></a> Common Editing Errors
376
377 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]]:
378
379 - **Q:** Text enclosed in angle brackets like `<filename>` is not displayed. How can I show it as it is?
380   - **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>'`.
381
382 - **Q:** Why is the `'&'` character sometimes not displayed?
383   - **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'`.
384
385 -- [[MikeMannix]] - 02 Dec 2001 <br /> -- [[PeterThoeny]] - 01 Feb 2003