%TOC\{depth="4"\}% %STARTINCLUDE% # Appendix C: Text Formatting Rules 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. ## TWiki Editing Shorthand

Formatting Command: Example: You write: You get:

Paragraphs:
Blank lines will create new paragraphs.

1st paragraph

2nd paragraph

1st paragraph

2nd paragraph

Headings:
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. Note: A Table of Content can be created automatically with the %TOC% variable, see TWiki Variables?.

---++ Sushi

---+++ Maguro

Sushi

Maguro

Bold Text:
Words get bold by enclosing them in * asterisks.

*Bold*

Bold

Italic Text:
Words get italic by enclosing them in _ underscores.

_Italic_

Italic

Bold Italic:
Words get _bold italic by enclosing them in _ double-underscores.

__Bold italic__

Bold italic

Fixed Font:
Words get shown in fixed font by enclosing them in = equal signs.

=Fixed font=

Fixed font

Bold Fixed Font:
Words get shown in bold fixed font by enclosing them in double equal signs.

==Bold fixed==

Bold fixed

Note: Make sure to "stick" the * _ = == signs to the words, e.g. take away spaces.

_This works_,
_this not _

This works, _this not _

Verbatim Mode:
Surround code excerpts and other formatted text with <verbatim> and </verbatim> tags.
Note: Use <pre> and </pre> tags instead if you want that HTML code is interpreted.
Note: Each tag must be on a line by itself.

&lt;verbatim&gt;
class CatAnimal {
  void purr() {
    &lt;code here&gt;
  }
}
&lt;/verbatim&gt;

class CatAnimal {
  void purr() {
    &lt;code here&gt;
  }
}

Separator:
At least three dashes at the beginning of a line.

-------

List Item:
Three spaces and an asterisk.

   * bullet item

bullet item

Nested List Item:
Six, nine, ... spaces and an asterisk.

      * nested stuff

- nested stuff

Ordered List:
Three spaces and a number.

   1 Sushi
   1 Dim Sum

Sushi
Dim Sum

Definition List:
Three spaces, the term, a colon, a space, followed by the definition.
Note: 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 &nbsp; non-breaking-space entity.

   Sushi: Japan
   Dim&amp;nbsp;Sum: S.F.

Sushi: Japan
Dim Sum: S.F.

Table:
Optional spaces followed by the cells enclosed in vertical bars.
Note: | *bold* | cells are rendered as table headers.
Note: | spaced | cells are rendered center aligned.
Note: | spaced | cells are rendered right aligned.
Note: | 2 colspan || cells are rendered as multi-span columns.
Note: 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 '\' backslash character.

| *L* | *C* | *R* |
| A2 |  2  |  2 |
| A3 |  3  |  3 |
| multi span |||
| A4 \
  | next \
  | next |

L	C	R
A2	2	2
A3	3	3
multi span
A4	next	next

WikiWord Links:
CapitalizedWordsStuckTogether (or Wiki Words?) will produce a link automatically.
Note: In case you want to link to a topic in a different %WIKITOOLNAME% web write Webname.TopicName.

WebNotify

Know.ReadmeFirst

Web Notify?

Readme First?

Forced Links:
You can create a forced internal link by enclosing words in double square brackets.
Note: 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. [[text formatting FAQ]] links to topic Text Formatting FAQ?. You can also refer to a different web and use anchors.

[[wiki syntax]]

[[%MAINWEB%.TWiki users]]

wiki syntax?

%MAINWEB%.TWiki users?

Specific Links:
Create a link where you can specify the link text and the link reference separately, using nested square brackets like [[reference][text]]. Internal link references (i.e. Wiki Syntax?) and external link references (i.e. http://TWiki.org/) are supported. The same Forced Links rules apply for internal link references. Anchor names can be added as well, like [[WebHome#MyAnchor][go home]] and [[http://www.yahoo.com/#somewhere][Yahoo!]].

[[WikiSyntax][syntax]]

[[http://gnu.org][GNU]]

syntax?

GNU

Anchors:
You can define a link reference inside a %WIKITOOLNAME% topic (called an anchor name) and link to that. To define an anchor write #AnchorName at the beginning of a line. The anchor name must be a Wiki Word?. To link to an anchor name use the [[MyTopic#MyAnchor]] syntax. You can omit the topic name if you want to link within the same topic.

[[WebHome#NotThere]]

[[#MyAnchor][Jump]]

#MyAnchor To here

Web Home#Not There?

Jump

To here

Prevent a Link:
Prevent a Wiki Word? from being linked by prepending it with the <nop> tag.

&lt;nop&gt;SunOS

SunOS

## Using HTML You can use just about any HTML tag without a problem - however, to keep in mind: * On collaboration pages, it's preferable NOT to use HTML, and to use TWiki shorthand instead - this keeps the text uncluttered and easy to edit. * **_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. * **_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. ## Hyperlinks 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. ### Internal Links * [[GoodStyle]] is a [[WikiWord]] that links to the GoodStyle topic located in the current %WIKITOOLNAME% web. * [[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!) ### External Links * `http://...`, `https://...`, `ftp://...` and `mailto:...@...` are linked automatically. * Email addresses like `name@domain.com` are linked automatically. * [[Square bracket rules]] let you easily create non-WikiWord links. ## TWiki Variables Variables are names that are enclosed in percent signs `%` that are expanded on the fly. * %TOC% : Automatically generates a table of contents based on headings in a topic - see the top of this page for an example. * %WEB% : The current web, is **%WEB%**. * %TOPIC% : The current topic name, is **%TOPIC%**. * %ATTACHURL% : The attachment URL of the current topic. Example usage: If you attach a file to a topic you can refer to it as **%ATTACHURL%/image.gif** to show the URL of the file or the image in your text. * %INCLUDE\{"SomeTopic"\}% : Server side include, includes another topic. The current %WIKITOOLNAME% web is the default web. Example: **%INCLUDE\{"%TWIKIWEB%.TWikiWebsTable"\}%** * There are many more variables, see **[[TWikiVariables]]**. ## Common Editing Errors 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]]: * **Q:** Text enclosed in angle brackets like `` 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 `'<'` instead of `'<'`, and `'>'` instead of `'>'`.
Example: Type `'prog <filename>'` to get `'prog '`. * **Q:** Why is the `'&'` character sometimes not displayed? * **A:** The `'&'` character has a special meaning in HTML, it starts a so called character entity, ex: `'©'` is the `©` copyright character. You need to escape `'&'` to see it as it is, so write `'&'` instead of `'&'`.
Example: Type `'This & that'` to get `'This & that'`. ## TWiki Plugins 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 [[TWikiPlugins]] web on TWiki.org. Currently enabled plugins on here: %PLUGINDESCRIPTIONS% Check on current Plugin status and settings for this site in [[TWikiPreferences]]. -- [[MikeMannix]] - 02 Oct 2001