path: root/TWiki/TextFormattingRules.mdwn

%TOC\{depth="4"\}% %STARTINCLUDE%

# <a name="TWiki_Text_Formatting"> TWiki Text Formatting </a>

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.

## <a name="TWiki_Editing_Shorthand"> TWiki Editing Shorthand </a>

<table bgcolor="#000000" border="0" cellpadding="3" cellspacing="1">
  <tr bgcolor="#ffffff">
    <td><strong>Formatting Command:</strong></td>
    <td><strong>Example: You write:</strong></td>
    <td><strong>You get:</strong></td>
  </tr>
  <tr bgcolor="#ffffff">
    <td valign="top"><strong>Paragraphs:</strong><br /> Blank lines will create new paragraphs. </td>
    <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
1st paragraph

2nd paragraph
</pre> </font></span></td>
    <td valign="top"> 1st paragraph <p> 2nd paragraph </p>
    </td>
  </tr>
  <tr bgcolor="#ffffff">
    <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>%<nop>TOC%</nop></code> variable, see <span style="background:"><font color="">TWiki Variables</font></span><a href="http://LOCATION/TWikiVariables">?</a>. </td>
    <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
<nop>---++ Sushi

<nop>---+++ Maguro
</nop></nop></pre> </font></span></td>
    <td valign="top">
      <h2>Sushi</h2>
      <p>
      </p>
      <h3>Maguro</h3>
    </td>
  </tr>
  <tr bgcolor="#ffffff">
    <td valign="top"><strong>Bold Text:</strong><br /> Words get <strong>bold</strong> by enclosing them in <code>*</code> asterisks. </td>
    <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
*Bold*
</pre> </font></span></td>
    <td valign="top"><strong>Bold</strong></td>
  </tr>
  <tr bgcolor="#ffffff">
    <td valign="top"><strong>Italic Text:</strong><br /> Words get <em>italic</em> by enclosing them in <code>_</code> underscores. </td>
    <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
_Italic_
</pre> </font></span></td>
    <td valign="top"><em>Italic</em></td>
  </tr>
  <tr bgcolor="#ffffff">
    <td valign="top"><strong>Bold Italic:</strong><br /> Words get <em>_bold italic</em> by enclosing them in <code>_</code> double-underscores. </td>
    <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
__Bold italic__
</pre> </font></span></td>
    <td valign="top"><strong><em>Bold italic</em></strong></td>
  </tr>
  <tr bgcolor="#ffffff">
    <td valign="top"><strong>Fixed Font:</strong><br /> Words get shown in <code>fixed font</code> by enclosing them in <code><nop>=<nop></nop></nop></code> equal signs. </td>
    <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
=Fixed font=
</pre> </font></span></td>
    <td valign="top"><code>Fixed font</code></td>
  </tr>
  <tr bgcolor="#ffffff">
    <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><nop></nop></b></code> double equal signs. </td>
    <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
==Bold fixed==
</pre> </font></span></td>
    <td valign="top"><code><b>Bold fixed</b></code></td>
  </tr>
  <tr bgcolor="#ffffff">
    <td valign="top"><strong><em>Note:</em></strong> Make sure to "stick" the <code>* _ = <nop>==<nop></nop></nop></code> signs to the words, e.g. take away spaces. </td>
    <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
_This works_,
_this not _
</pre> </font></span></td>
    <td valign="top"><em>This works</em>, _this not _ </td>
  </tr>
  <tr bgcolor="#ffffff">
    <td valign="top"><strong>Verbatim Mode:</strong><br /> Surround code excerpts and other formatted text with <code>&amp;lt;verbatim&amp;gt;</code> and <code>&amp;lt;/verbatim&amp;gt;</code> tags. <br /><strong><em>Note:</em></strong> Use <code>&amp;lt;pre&amp;gt;</code> and <code>&amp;lt;/pre&amp;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>
    <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
&amp;lt;verbatim&amp;gt;
class CatAnimal {
  void purr() {
    &amp;lt;code here&amp;gt;
  }
}
&amp;lt;/verbatim&amp;gt;
</pre> </font></span></td>
    <td valign="top"><pre>
class CatAnimal {
  void purr() {
    &amp;lt;code here&amp;gt;
  }
}
</pre></td>
  </tr>
  <tr bgcolor="#ffffff">
    <td valign="top"><strong>Separator:</strong><br /> At least three dashes at the beginning of a line. </td>
    <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
-------
</pre> </font></span></td>
    <td valign="top">
      <hr />
    </td>
  </tr>
  <tr bgcolor="#ffffff">
    <td valign="top"><strong>List Item:</strong><br /> Three spaces and an asterisk. </td>
    <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
   * bullet item
</pre> </font></span></td>
    <td valign="top">
      <ul>
        <li> bullet item </li>
      </ul>
    </td>
  </tr>
  <tr bgcolor="#ffffff">
    <td valign="top"><strong>Nested List Item:</strong><br /> Six, nine, ... spaces and an asterisk. </td>
    <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
      * nested stuff
</pre> </font></span></td>
    <td valign="top">
      <ul>
        <li>
          <ul>
            <li> nested stuff </li>
          </ul>
        </li>
      </ul>
    </td>
  </tr>
  <tr bgcolor="#ffffff">
    <td valign="top"><strong>Ordered List:</strong><br /> Three spaces and a number. </td>
    <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
   1 Sushi
   1 Dim Sum
</pre> </font></span></td>
    <td valign="top">
      <ol>
        <li> Sushi </li>
        <li> Dim Sum </li>
      </ol>
    </td>
  </tr>
  <tr bgcolor="#ffffff">
    <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;amp;nbsp;</code> non-breaking-space entity. </td>
    <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
   Sushi: Japan
   Dim&amp;amp;nbsp;Sum: S.F.
</pre> </font></span></td>
    <td valign="top">
      <dl>
        <dt> Sushi</dt>
        <dd> Japan </dd>
        <dt> Dim Sum</dt>
        <dd> S.F. </dd>
      </dl>
    </td>
  </tr>
  <tr bgcolor="#ffffff">
    <td valign="top"><strong>Table:</strong><br /> Optional spaces followed by the cells enclosed in vertical bars. <br /><strong><em>Note:</em></strong> <code>| <nop>*bold*<nop> |</nop></nop></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>
    <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
| *L* | *C* | *R* |
| A2 |  2  |  2 |
| A3 |  3  |  3 |
| multi span |||
| A4 \<nop>
  | next \<nop>
  | next |
</nop></nop></pre> </font></span></td>
    <td valign="top">
      <table border="1" cellpadding="1" cellspacing="0">
        <tr>
          <th bgcolor="#99CCCC"><strong>L</strong></th>
          <th bgcolor="#99CCCC"><strong>C</strong></th>
          <th bgcolor="#99CCCC"><strong>R</strong></th>
        </tr>
        <tr>
          <td> A2 </td>
          <td align="center"> 2 </td>
          <td align="right"> 2 </td>
        </tr>
        <tr>
          <td> A3 </td>
          <td align="center"> 3 </td>
          <td align="right"> 3 </td>
        </tr>
        <tr>
          <td colspan="3"> multi span </td>
        </tr>
        <tr>
          <td> A4 </td>
          <td> next </td>
          <td> next </td>
        </tr>
      </table>
    </td>
  </tr>
  <tr bgcolor="#ffffff">
    <td valign="top"><strong><nop>WikiWord Links:</nop></strong><br /><nop>CapitalizedWordsStuckTogether (or <span style="background:"><font color="">Wiki Words</font></span><a href="http://LOCATION/WikiWords">?</a>) 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>. </nop></td>
    <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
WebNotify

Know.ReadmeFirst
</pre> </font></span></td>
    <td valign="top"><span style="background:"><font color="">Web Notify</font></span><a href="http://LOCATION/WebNotify">?</a><p><span style="background:"><font color="">Readme First</font></span><a href="http://LOCATIONKnow/ReadmeFirst">?</a></p>
    </td>
  </tr>
  <tr bgcolor="#ffffff">
    <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>[<nop>[text formatting FAQ]]</nop></code> links to topic <span style="background:"><font color="">Text Formatting FAQ</font></span><a href="http://LOCATION/TextFormattingFAQ">?</a>. You can also refer to a different web and use anchors. </td>
    <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
[[wiki syntax]]

[[%MAINWEB%.TWiki users]]
</pre> </font></span></td>
    <td valign="top"><span style="background:"><font color="">wiki syntax</font></span><a href="http://LOCATION/WikiSyntax">?</a><p><span style="background:"><font color="">%MAINWEB%.TWiki users</font></span><a href="http://LOCATION/MAINWEBTWikiUsers">?</a></p>
    </td>
  </tr>
  <tr bgcolor="#ffffff">
    <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>[<nop>[reference][text]]</nop></code>. Internal link references (i.e. <span style="background:"><font color="">Wiki Syntax</font></span><a href="http://LOCATION/WikiSyntax">?</a>) 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>[<nop>[WebHome#MyAnchor][go home]]</nop></code> and <code>[<nop>[http://www.yahoo.com/#somewhere][Yahoo!]]</nop></code>. </td>
    <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
[[WikiSyntax][syntax]]

[[http://gnu.org][GNU]]
</pre> </font></span></td>
    <td valign="top"><span style="background:"><font color="">syntax</font></span><a href="http://LOCATION/WikiSyntax">?</a><p><a href="http://gnu.org" target="_top">GNU</a></p>
    </td>
  </tr>
  <tr bgcolor="#ffffff">
    <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 <span style="background:"><font color="">Wiki Word</font></span><a href="http://LOCATION/WikiWord">?</a>. To <strong><em>link to</em></strong> an anchor name use the <code>[<nop>[MyTopic#MyAnchor]]</nop></code> syntax. You can omit the topic name if you want to link within the same topic. </td>
    <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
[[WebHome#NotThere]]

[[#MyAnchor][Jump]]

#MyAnchor To here
</pre> </font></span></td>
    <td valign="top"><span style="background:"><font color="">Web Home#Not There</font></span><a href="http://LOCATION/WebHome">?</a><p> Jump </p>
      <p><a name="MyAnchor"></a> To here </p>
    </td>
  </tr>
  <tr bgcolor="#ffffff">
    <td valign="top"><strong>Prevent a Link:</strong><br /> Prevent a <span style="background:"><font color="">Wiki Word</font></span><a href="http://LOCATION/WikiWord">?</a> from being linked by prepending it with the <code>&amp;lt;nop&amp;gt;</code> tag. </td>
    <td valign="top"><span style="background: #FFFFCC"><font color="#990000"> <pre>
&amp;lt;nop&amp;gt;SunOS
</pre> </font></span></td>
    <td valign="top"><nop>SunOS </nop></td>
  </tr>
</table>

## <a name="Using_HTML"> </a> Using HTML

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.

## <a name="Hyperlinks"> Hyperlinks </a>

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.

### <a name="Internal_Links"> Internal Links </a>

* [[GoodStyle]] is a [[WikiWord]] that links to the GoodStyle topic located in the current %WIKITOOLNAME% web.
* [[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!)

### <a name="External_Links"> External Links </a>

* `http://...`, `https://...`, `ftp://...` and `mailto:...@...` are linked automatically.
* Email addresses like `name@domain.com` are linked automatically.

## <a name="TWiki_Variables"> TWiki Variables </a>

Variables are names that are enclosed in percent signs; they get expanded on the fly.

* <code>%TOC%</code> : The table of content, is based on headings in a topic.
* <code>%WEB%</code> : The current web, is **%WEB%** .
* <code>%TOPIC%</code> : The current topic name, is **%TOPIC%** .
* <code>%ATTACHURL%</code> : 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.
* <code>%INCLUDE\{"SomeTopic"\}%</code> : Server side include, includes another topic. The current %WIKITOOLNAME% web is the default web. Example: <code>**%INCLUDE\{"%TWIKIWEB%.TWikiWebsTable"\}%**</code>
* There are many more variables, see [[TWikiVariables]].

## <a name="_Gotchas_when_Editing_Text"> "Gotchas" when Editing Text </a>

The formatting rules are fairly simple to use and fast to type. However, there are some things to watch out for:

* **Q:** Text enclosed in angle brackets like `<filename>` is not displayed. How can I show it as it is?
  * **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>'`.

* **Q:** Why is the `'&'` character sometimes not displayed?
  * **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'`.

* See more [[TextFormattingFAQs]]

## <a name="TWiki_Plugins"> TWiki Plugins </a>

Plugins provide additional text formatting rules and can extend the functionality of %WIKITOOLNAME% into many other areas. Available Plugins are located in the [[TWikiPlugins]] web. Currently enabled plugins on this site are:

%PLUGINDESCRIPTIONS%

Check on current Plugin status and settings for this site in [[TWikiPreferences]].

-- [[MikeMannix]] - 30 Aug 2001