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="#"Gotchas" when Editing Text"> "Gotchas" when Editing Text</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="TWiki Editing Shorthand"></a> TWiki Editing Shorthand
  24
  25 <table bgcolor="#000000" border="0" cellpadding="3" cellspacing="1">
  26   <tr bgcolor="#ffffff">
  27     <td><strong>Formatting Command:</strong></td>
  28     <td><strong>Example: You write:</strong></td>
  29     <td><strong>You get:</strong></td>
  30   </tr>
  31   <tr bgcolor="#ffffff">
  32     <td valign="top"><strong>Paragraphs:</strong><br /> Blank lines will create new paragraphs. </td>
  33     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
  34 1st paragraph
  35
  36 2nd paragraph
  37 </pre> </font></span></td>
  38     <td valign="top"> 1st paragraph <p> 2nd paragraph </p>
  39     </td>
  40   </tr>
  41   <tr bgcolor="#ffffff">
  42     <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>
  43     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
  44 ---++ Sushi
  45
  46 ---+++ Maguro
  47 </pre> </font></span></td>
  48     <td valign="top">
  49       <h2>Sushi</h2>
  50       <p>
  51       </p>
  52       <h3>Maguro</h3>
  53     </td>
  54   </tr>
  55   <tr bgcolor="#ffffff">
  56     <td valign="top"><strong>Bold Text:</strong><br /> Words get <strong>bold</strong> by enclosing them in <code>*</code> asterisks. </td>
  57     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
  58 *Bold*
  59 </pre> </font></span></td>
  60     <td valign="top"><strong>Bold</strong></td>
  61   </tr>
  62   <tr bgcolor="#ffffff">
  63     <td valign="top"><strong>Italic Text:</strong><br /> Words get <em>italic</em> by enclosing them in <code>_</code> underscores. </td>
  64     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
  65 _Italic_
  66 </pre> </font></span></td>
  67     <td valign="top"><em>Italic</em></td>
  68   </tr>
  69   <tr bgcolor="#ffffff">
  70     <td valign="top"><strong>Bold Italic:</strong><br /> Words get <em>_bold italic</em> by enclosing them in <code>_</code> double-underscores. </td>
  71     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
  72 __Bold italic__
  73 </pre> </font></span></td>
  74     <td valign="top"><strong><em>Bold italic</em></strong></td>
  75   </tr>
  76   <tr bgcolor="#ffffff">
  77     <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>
  78     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
  79 =Fixed font=
  80 </pre> </font></span></td>
  81     <td valign="top"><code>Fixed font</code></td>
  82   </tr>
  83   <tr bgcolor="#ffffff">
  84     <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>
  85     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
  86 ==Bold fixed==
  87 </pre> </font></span></td>
  88     <td valign="top"><code><b>Bold fixed</b></code></td>
  89   </tr>
  90   <tr bgcolor="#ffffff">
  91     <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>
  92     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
  93 _This works_,
  94 _this not _
  95 </pre> </font></span></td>
  96     <td valign="top"><em>This works</em>, _this not _ </td>
  97   </tr>
  98   <tr bgcolor="#ffffff">
  99     <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>
 100     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
 101 &lt;verbatim&gt;
 102 class CatAnimal {
 103   void purr() {
 104          &lt;code here&gt;
 105   }
 106 }
 107 &lt;/verbatim&gt;
 108 </pre> </font></span></td>
 109     <td valign="top"><pre>
 110 class CatAnimal {
 111   void purr() {
 112     &lt;code here&gt;
 113   }
 114 }
 115 </pre></td>
 116   </tr>
 117   <tr bgcolor="#ffffff">
 118     <td valign="top"><strong>Separator:</strong><br /> At least three dashes at the beginning of a line. </td>
 119     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
 120 -------
 121 </pre> </font></span></td>
 122     <td valign="top">
 123       <hr />
 124     </td>
 125   </tr>
 126   <tr bgcolor="#ffffff">
 127     <td valign="top"><strong>List Item:</strong><br /> Three spaces and an asterisk. </td>
 128     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
 129         * bullet item
 130 </pre> </font></span></td>
 131     <td valign="top">
 132       <ul>
 133         <li> bullet item </li>
 134       </ul>
 135     </td>
 136   </tr>
 137   <tr bgcolor="#ffffff">
 138     <td valign="top"><strong>Nested List Item:</strong><br /> Six, nine, ... spaces and an asterisk. </td>
 139     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
 140                 * nested stuff
 141 </pre> </font></span></td>
 142     <td valign="top">
 143       <ul>
 144         <li>
 145           <ul>
 146             <li> nested stuff </li>
 147           </ul>
 148         </li>
 149       </ul>
 150     </td>
 151   </tr>
 152   <tr bgcolor="#ffffff">
 153     <td valign="top"><strong>Ordered List:</strong><br /> Three spaces and a number. </td>
 154     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
 155         1 Sushi
 156         1 Dim Sum
 157 </pre> </font></span></td>
 158     <td valign="top">
 159       <ol>
 160         <li> Sushi </li>
 161         <li> Dim Sum </li>
 162       </ol>
 163     </td>
 164   </tr>
 165   <tr bgcolor="#ffffff">
 166     <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>
 167     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
 168         Sushi: Japan
 169         Dim&amp;nbsp;Sum: S.F.
 170 </pre> </font></span></td>
 171     <td valign="top">
 172       <dl>
 173         <dt> Sushi</dt>
 174         <dd> Japan </dd>
 175         <dt> Dim Sum</dt>
 176         <dd> S.F. </dd>
 177       </dl>
 178     </td>
 179   </tr>
 180   <tr bgcolor="#ffffff">
 181     <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 />
 182     </td>
 183     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
 184 | *L* | *C* | *R* |
 185 | A2 |  2  |  2 |
 186 | A3 |  3  |  3 |
 187 | multi span |||
 188 | A4 \  | next \  | next |
 189 </pre> </font></span></td>
 190     <td valign="top">
 191       <table border="1" cellpadding="0" cellspacing="0">
 192         <tr>
 193           <th bgcolor="#99CCCC"><strong> L </strong></th>
 194           <th bgcolor="#99CCCC"><strong> C </strong></th>
 195           <th bgcolor="#99CCCC"><strong> R </strong></th>
 196         </tr>
 197         <tr>
 198           <td> A2 </td>
 199           <td align="center"> 2 </td>
 200           <td align="right"> 2 </td>
 201         </tr>
 202         <tr>
 203           <td> A3 </td>
 204           <td align="center"> 3 </td>
 205           <td align="right"> 3 </td>
 206         </tr>
 207         <tr>
 208           <td colspan="3"> multi span </td>
 209         </tr>
 210         <tr>
 211           <td> A4 </td>
 212           <td> next </td>
 213           <td> next </td>
 214         </tr>
 215       </table>
 216     </td>
 217   </tr>
 218   <tr bgcolor="#ffffff">
 219     <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>
 220     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
 221 WebNotify
 222
 223 Know.ReadmeFirst
 224 </pre> </font></span></td>
 225     <td valign="top">[[Main/WebNotify]]<p>[[Know/ReadmeFirst]]</p>
 226     </td>
 227   </tr>
 228   <tr bgcolor="#ffffff">
 229     <td valign="top"><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>
 230     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
 231 [[wiki syntax]]
 232
 233 [[Main.TWiki users]]
 234 </pre> </font></span></td>
 235     <td valign="top">[[Main/WikiSyntax]]<p>[[Main/TWikiUsers]]</p>
 236     </td>
 237   </tr>
 238   <tr bgcolor="#ffffff">
 239     <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>
 240     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
 241 [[WikiSyntax][syntax]]
 242
 243 [[http://gnu.org][GNU]]
 244 </pre> </font></span></td>
 245     <td valign="top">[[Main/WikiSyntax]]<p><a href="http://gnu.org" target="_top">GNU</a></p>
 246     </td>
 247   </tr>
 248   <tr bgcolor="#ffffff">
 249     <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>
 250     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
 251 [[WebHome#NotThere]]
 252
 253 [[#MyAnchor][Jump]]
 254
 255 #MyAnchor To here
 256 </pre> </font></span></td>
 257     <td valign="top">[[Main/WebHome#NotThere]]<p>[[Main/WebHome#MyAnchor]]</p>
 258       <p><a name="MyAnchor"></a> To here </p>
 259     </td>
 260   </tr>
 261   <tr bgcolor="#ffffff">
 262     <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>
 263     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
 264 &lt;nop&gt;SunOS
 265 </pre> </font></span></td>
 266     <td valign="top"> SunOS </td>
 267   </tr>
 268 </table>
 269
 270 ## <a name="Using HTML"></a> Using HTML
 271
 272 Most HTML tags will work, but it's almost always preferable not to use HTML, so that the markup remains easy for everyone to edit.
 273
 274 ## <a name="Hyperlinks"></a> Hyperlinks
 275
 276 Being able to create links without any formatting required is a core TWiki feature, made possible using [[WikiNames]]. With the latest version of TWiki linking rules, a simple extension of the syntax provides an new set of flexible linking options.
 277
 278 ### <a name="Internal Links"></a> Internal Links
 279
 280 - [[GoodStyle]] is a [[WikiWord]] that links to the GoodStyle topic located in the current %WIKITOOLNAME% web.
 281 - [[NotExistingYet]] is a topic waiting to be written. You could create that topic by clicking on the question mark. (Do not create that topic; you would wreck this example!)
 282
 283 ### <a name="External Links"></a> External Links
 284
 285 - `http://...`, `https://...`, `ftp://...` and `mailto:...@...` are linked automatically.
 286 - Email addresses like `name@domain.com` are linked automatically.
 287
 288 ## <a name="TWiki Variables"></a> TWiki Variables
 289
 290 Variables are names that are enclosed in percent signs; they get expanded on the fly.
 291
 292 - `%TOC%` : The table of content, is based on headings in a topic.
 293 - `%WEB%` : The current web, is **%WEB%** .
 294 - `%TOPIC%` : The current topic name, is **%TOPIC%** .
 295 - `%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.
 296 - `%INCLUDE{"SomeTopic"}%` : Server side include, includes another topic. The current %WIKITOOLNAME% web is the default web. Example: <code>**%INCLUDE\{"TWiki.TWikiWebsTable"\}%**</code>
 297 - There are many more variables, see [[TWikiVariables]].
 298
 299 ## <a name="&quot;Gotchas&quot; when Editing Text"></a> "Gotchas" when Editing Text
 300
 301 The formatting rules are fairly simple to use and fast to type. However, there are some things to watch out for:
 302
 303 - **Q:** Text enclosed in angle brackets like `<filename>` is not displayed. How can I show it as it is?
 304   - **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>'`.
 305
 306 - **Q:** Why is the `'&'` character sometimes not displayed?
 307   - **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'`.
 308
 309 - See more [[TextFormattingFAQs]]
 310
 311 ## <a name="TWiki Plugins"></a> TWiki Plugins
 312
 313 Plugins provide additional text formatting rules and can extend the functionality of %WIKITOOLNAME% into many other areas. Available Plugins are located in the [[Plugins|Main/TWiki:Plugins]] web. Currently enabled plugins on this site are:
 314
 315 - [[SpreadSheetPlugin]] <span>(any TWiki, 10197)</span>:
 316 - [[CommentPlugin]] <span>(Dakar, 11359)</span>: Allows users to quickly post comments to a page without an edit/preview/save cycle
 317 - [[EditTablePlugin]] <span>(any TWiki, 11646)</span>:
 318 - [[InterwikiPlugin]] <span>(Dakar, $Rev: 11935$)</span>:
 319 - [[PreferencesPlugin]] <span>(Dakar, 9839)</span>:
 320 - [[SlideShowPlugin]] <span>(Any TWiki, $Rev: 12847$)</span>:
 321 - [[SmiliesPlugin]] <span>(Dakar, 8154)</span>:
 322 - [[TablePlugin]] <span>(1.020, 12339)</span>:
 323 - [[TwistyPlugin]] <span>(1.2.0, $Rev: 12154$)</span>:
 324
 325 Check on current Plugin status and settings for this site in [[TWikiPreferences]].
 326
 327 -- [[MikeMannix]] - 30 Aug 2001