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="#TWikiPlugin Formatting Extension"> TWikiPlugin Formatting Extensions</a></li>
  16       </ul>
  17     </li>
  18   </ul>
  19 </div>
  20
  21 # <a name="TWiki Text Formatting"></a> TWiki Text Formatting
  22
  23 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.
  24
  25 <a name="TWikiShorthand"></a>
  26
  27 ## <a name="TWiki Editing Shorthand"></a> TWiki Editing Shorthand
  28
  29 <table bgcolor="#000000" border="0" cellpadding="3" cellspacing="1">
  30   <tr bgcolor="#ffffff">
  31     <td><strong>Formatting Command:</strong></td>
  32     <td><strong>Example: You write:</strong></td>
  33     <td><strong>You get:</strong></td>
  34   </tr>
  35   <tr bgcolor="#ffffff">
  36     <td valign="top"><strong>Paragraphs:</strong><br /> Blank lines will create new paragraphs. </td>
  37     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
  38 1st paragraph
  39
  40 2nd paragraph
  41 </pre> </font></span></td>
  42     <td valign="top"> 1st paragraph <p> 2nd paragraph </p>
  43     </td>
  44   </tr>
  45   <tr bgcolor="#ffffff">
  46     <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>
  47     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
  48 ---++ Sushi
  49
  50 ---+++ Maguro
  51 </pre> </font></span></td>
  52     <td valign="top">
  53       <h2>Sushi</h2>
  54       <p>
  55       </p>
  56       <h3>Maguro</h3>
  57     </td>
  58   </tr>
  59   <tr bgcolor="#ffffff">
  60     <td valign="top"><strong>Bold Text:</strong><br /> Words get <strong>bold</strong> by enclosing them in <code>*</code> asterisks. </td>
  61     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
  62 *Bold*
  63 </pre> </font></span></td>
  64     <td valign="top"><strong>Bold</strong></td>
  65   </tr>
  66   <tr bgcolor="#ffffff">
  67     <td valign="top"><strong>Italic Text:</strong><br /> Words get <em>italic</em> by enclosing them in <code>_</code> underscores. </td>
  68     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
  69 _Italic_
  70 </pre> </font></span></td>
  71     <td valign="top"><em>Italic</em></td>
  72   </tr>
  73   <tr bgcolor="#ffffff">
  74     <td valign="top"><strong>Bold Italic:</strong><br /> Words get <em>_bold italic</em> by enclosing them in <code>_</code> double-underscores. </td>
  75     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
  76 __Bold italic__
  77 </pre> </font></span></td>
  78     <td valign="top"><strong><em>Bold italic</em></strong></td>
  79   </tr>
  80   <tr bgcolor="#ffffff">
  81     <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>
  82     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
  83 =Fixed font=
  84 </pre> </font></span></td>
  85     <td valign="top"><code>Fixed font</code></td>
  86   </tr>
  87   <tr bgcolor="#ffffff">
  88     <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>
  89     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
  90 ==Bold fixed==
  91 </pre> </font></span></td>
  92     <td valign="top"><code><b>Bold fixed</b></code></td>
  93   </tr>
  94   <tr bgcolor="#ffffff">
  95     <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>
  96     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
  97 _This works_,
  98 _this not _
  99 </pre> </font></span></td>
 100     <td valign="top"><em>This works</em>, _this not _ </td>
 101   </tr>
 102   <tr bgcolor="#ffffff">
 103     <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>
 104     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
 105 &lt;verbatim&gt;
 106 class CatAnimal {
 107   void purr() {
 108          &lt;code here&gt;
 109   }
 110 }
 111 &lt;/verbatim&gt;
 112 </pre> </font></span></td>
 113     <td valign="top"><pre>
 114 class CatAnimal {
 115   void purr() {
 116     &lt;code here&gt;
 117   }
 118 }
 119 </pre></td>
 120   </tr>
 121   <tr bgcolor="#ffffff">
 122     <td valign="top"><strong>Separator:</strong><br /> At least three dashes at the beginning of a line. </td>
 123     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
 124 -------
 125 </pre> </font></span></td>
 126     <td valign="top">
 127       <hr />
 128     </td>
 129   </tr>
 130   <tr bgcolor="#ffffff">
 131     <td valign="top"><strong>List Item:</strong><br /> Three spaces and an asterisk. </td>
 132     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
 133         * bullet item
 134 </pre> </font></span></td>
 135     <td valign="top">
 136       <ul>
 137         <li> bullet item </li>
 138       </ul>
 139     </td>
 140   </tr>
 141   <tr bgcolor="#ffffff">
 142     <td valign="top"><strong>Nested List Item:</strong><br /> Six, nine, ... spaces and an asterisk. </td>
 143     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
 144                 * nested stuff
 145 </pre> </font></span></td>
 146     <td valign="top">
 147       <ul>
 148         <li>
 149           <ul>
 150             <li> nested stuff </li>
 151           </ul>
 152         </li>
 153       </ul>
 154     </td>
 155   </tr>
 156   <tr bgcolor="#ffffff">
 157     <td valign="top"><strong>Ordered List:</strong><br /> Three spaces and a number. </td>
 158     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
 159         1 Sushi
 160         1 Dim Sum
 161 </pre> </font></span></td>
 162     <td valign="top">
 163       <ol>
 164         <li> Sushi </li>
 165         <li> Dim Sum </li>
 166       </ol>
 167     </td>
 168   </tr>
 169   <tr bgcolor="#ffffff">
 170     <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>
 171     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
 172         Sushi: Japan
 173         Dim&amp;nbsp;Sum: S.F.
 174 </pre> </font></span></td>
 175     <td valign="top">
 176       <dl>
 177         <dt> Sushi</dt>
 178         <dd> Japan </dd>
 179         <dt> Dim Sum</dt>
 180         <dd> S.F. </dd>
 181       </dl>
 182     </td>
 183   </tr>
 184   <tr bgcolor="#ffffff">
 185     <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 />
 186     </td>
 187     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
 188 | *L* | *C* | *R* |
 189 | A2 |  2  |  2 |
 190 | A3 |  3  |  3 |
 191 | multi span |||
 192 | A4 \  | next \  | next |
 193 </pre> </font></span></td>
 194     <td valign="top">
 195       <table border="1" cellpadding="0" cellspacing="0">
 196         <tr>
 197           <th bgcolor="#99CCCC"><strong> L </strong></th>
 198           <th bgcolor="#99CCCC"><strong> C </strong></th>
 199           <th bgcolor="#99CCCC"><strong> R </strong></th>
 200         </tr>
 201         <tr>
 202           <td> A2 </td>
 203           <td align="center"> 2 </td>
 204           <td align="right"> 2 </td>
 205         </tr>
 206         <tr>
 207           <td> A3 </td>
 208           <td align="center"> 3 </td>
 209           <td align="right"> 3 </td>
 210         </tr>
 211         <tr>
 212           <td colspan="3"> multi span </td>
 213         </tr>
 214         <tr>
 215           <td> A4 </td>
 216           <td> next </td>
 217           <td> next </td>
 218         </tr>
 219       </table>
 220     </td>
 221   </tr>
 222   <tr bgcolor="#ffffff">
 223     <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>
 224     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
 225 WebNotify
 226
 227 Know.ReadmeFirst
 228 </pre> </font></span></td>
 229     <td valign="top">[[Main/WebNotify]]<p>[[Know/ReadmeFirst]]</p>
 230     </td>
 231   </tr>
 232   <tr bgcolor="#ffffff">
 233     <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>
 234     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
 235 [[wiki syntax]]
 236
 237 [[Main.TWiki users]]
 238 </pre> </font></span></td>
 239     <td valign="top">[[Main/WikiSyntax]]<p>[[Main/TWikiUsers]]</p>
 240     </td>
 241   </tr>
 242   <tr bgcolor="#ffffff">
 243     <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>
 244     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
 245 [[WikiSyntax][syntax]]
 246
 247 [[http://gnu.org][GNU]]
 248 </pre> </font></span></td>
 249     <td valign="top">[[Main/WikiSyntax]]<p><a href="http://gnu.org" target="_top">GNU</a></p>
 250     </td>
 251   </tr>
 252   <tr bgcolor="#ffffff">
 253     <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>
 254     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
 255 [[WebHome#NotThere]]
 256
 257 [[#MyAnchor][Jump]]
 258
 259 #MyAnchor To here
 260 </pre> </font></span></td>
 261     <td valign="top">[[Main/WebHome#NotThere]]<p>[[Main/WebHome#MyAnchor]]</p>
 262       <p><a name="MyAnchor"></a> To here </p>
 263     </td>
 264   </tr>
 265   <tr bgcolor="#ffffff">
 266     <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>
 267     <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
 268 &lt;nop&gt;SunOS
 269 </pre> </font></span></td>
 270     <td valign="top"> SunOS </td>
 271   </tr>
 272 </table>
 273
 274 ## <a name="Using HTML"></a> Using HTML
 275
 276 You can use just about any HTML tag without a problem - however, there are a few usability and technical considerations to keep in mind.
 277
 278 ### <a name="HTML and TWiki Usability"></a> HTML and TWiki Usability
 279
 280 - 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.
 281 - %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.
 282
 283 ### <a name="TWiki HTML Rendering"></a> TWiki HTML Rendering
 284
 285 - 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.
 286   - %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."
 287 - %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.
 288   - 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>
 289   - %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.
 290
 291 ## <a name="Hyperlinks"></a> Hyperlinks
 292
 293 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.
 294
 295 ### <a name="Internal Links"></a> Internal Links
 296
 297 - [[GoodStyle]] is a [[WikiWord]] that links to the GoodStyle topic located in the current %WIKITOOLNAME% web.
 298
 299 - [[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!)
 300
 301 ### <a name="External Links"></a> External Links
 302
 303 - `http://...`, `https://...`, `ftp://...` and `mailto:...@...` are linked automatically.
 304
 305 - Email addresses like `name@domain.com` are linked automatically.
 306
 307 - `[[Square bracket rules]]` let you easily create [[non-WikiWord links|Main/WebHome#SquareBrackets]].
 308
 309 ## <a name="TWikiPlugin Formatting Extension"></a><a name="_TWikiPlugin Formatting Extensio"></a> TWikiPlugin Formatting Extensions
 310
 311 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.
 312
 313 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%`:
 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]] - 02 Dec 2001