=begin twiki

%TOC{depth="4"}%
%STARTINCLUDE%
---# TWiki Text Formatting

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 a WikiWord. And TWiki shorthand gives you all the power of HTML with a simple coding system that takes no time to learn. It's all laid out below - refer back to this page in a pop-up window from the *Edit* screen.

#TWikiShorthand
---++ TWiki Editing Shorthand

<table border="1" cellpadding="3" cellspacing="1" bgcolor="#000000">
<tr bgcolor="#ffffff">
<td>
 *Formatting Command:*
</td><td>
 *Example: You write:*
</td><td>
 *You get:*
</td>
</tr>
<tr bgcolor="#ffffff">
<td valign="top">
 *Paragraphs:* %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

2nd paragraph
</td>
</tr>
<tr bgcolor="#ffffff">
<td valign="top">
 *Headings:* %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. __Note:__ A Table of Content can be created automatically with the =%<nop>TOC%= variable, see [[#TWikiVariables][TWiki Variables]]. Any heading text after =!!= is excluded from the TOC; for example, write =---+!! text= if you do not want to list a header in the TOC.
</td><td valign="top">
<span style='background : #FFFFCC;'><font color="#990000">
<pre>
<nop>---++ Sushi

<nop>---+++ Maguro
</pre>
</font></span>
</td><td valign="top">
<h2 >Sushi</h2>

<h3 >Maguro</h3>
</td>
</tr>
<tr bgcolor="#ffffff">
<td valign="top">
 *Bold Text:* %BR%
 Words get *bold* by enclosing them in =*= asterisks.
</td><td valign="top">
<span style='background : #FFFFCC;'><font color="#990000">
<pre>
*Bold*
</pre>
</font></span>
</td><td valign="top">
*Bold*
</td>
</tr>
<tr bgcolor="#ffffff">
<td valign="top">
 *Italic Text:* %BR%
 Words get _italic_ by enclosing them in =_= underscores.
</td><td valign="top">
<span style='background : #FFFFCC;'><font color="#990000">
<pre>
_Italic_
</pre>
</font></span>
</td><td valign="top">
_Italic_
</td>
</tr>
<tr bgcolor="#ffffff">
<td valign="top">
 *Bold Italic:* %BR%
 Words get __bold italic__ by enclosing them in =_= double-underscores.
</td><td valign="top">
<span style='background : #FFFFCC;'><font color="#990000">
<pre>
__Bold italic__
</pre>
</font></span>
</td><td valign="top">
__Bold italic__
</td>
</tr>
<tr bgcolor="#ffffff">
<td valign="top">
 *Fixed Font:* %BR%
 Words get shown in =fixed font= by enclosing them in =<nop>=<nop>= equal signs.
</td><td valign="top">
<span style='background : #FFFFCC;'><font color="#990000">
<pre>
=Fixed font=
</pre>
</font></span>
</td><td valign="top">
=Fixed font=
</td>
</tr>
<tr bgcolor="#ffffff">
<td valign="top">
 *Bold Fixed Font:* %BR%
 Words get shown in ==bold fixed font== by enclosing them in ==<nop>== double equal signs.
</td><td valign="top">
<span style='background : #FFFFCC;'><font color="#990000">
<pre>
==Bold fixed==
</pre>
</font></span>
</td><td valign="top">
==Bold fixed==
</td>
</tr>
<tr bgcolor="#ffffff">
<td valign="top">
 __Note:__ Make sure to "stick" the =* _ = <nop>==<nop>= signs to the words, that is, 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">
_This works_,
_this not _
</td>
</tr>
<tr bgcolor="#ffffff">
<td valign="top">
 *Verbatim Mode:* %BR%
 Surround code excerpts and other formatted text with =&lt;verbatim&gt;= and =&lt;/verbatim&gt;= tags. %BR% __Note:__ Use =&lt;pre&gt;= and =&lt;/pre&gt;= tags instead if you want that HTML code is interpreted. %BR% __Note:__ Each tag must be on a line by itself.
</td><td valign="top">
<span style='background : #FFFFCC;'><font color="#990000">
<pre>
&lt;verbatim&gt;
class CatAnimal {
  void purr() {
	 &lt;code here&gt;
  }
}
&lt;/verbatim&gt;
</pre>
</font></span>
</td><td valign="top">
<verbatim>
class CatAnimal {
  void purr() {
	 <code here>
  }
}
</verbatim>
</td>
</tr>
<tr bgcolor="#ffffff">
<td valign="top">
 *Separator:* %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">
-------
</td>
</tr>
<tr bgcolor="#ffffff">
<td valign="top">
 *List Item:* %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">
	* bullet item
</td>
</tr>
<tr bgcolor="#ffffff">
<td valign="top">
 *Nested List Item:* %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">
		* nested stuff
</td>
</tr>
<tr bgcolor="#ffffff">
<td valign="top">
 *Ordered List:* %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">
	1 Sushi
	1 Dim Sum
</td>
</tr>
<tr bgcolor="#ffffff">
<td valign="top">
 *Definition List:* %BR%
 Three spaces, the term, a colon, a space, followed by the definition. %BR%
__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 =&amp;nbsp;= non-breaking-space entity.
</td><td valign="top">
<span style='background : #FFFFCC;'><font color="#990000">
<pre>
	Sushi: Japan
	Dim&amp;nbsp;Sum: S.F.
</pre>
</font></span>
</td><td valign="top">
	Sushi: Japan
	Dim&nbsp;Sum: S.F.
</td>
</tr>
<tr bgcolor="#ffffff">
<td valign="top">
 *Table:* %BR%
 Optional spaces followed by the cells enclosed in vertical bars. %BR%
__Note:__ =| <nop>*bold*<nop> |= cells are rendered as table headers. %BR%
__Note:__ =|&nbsp;&nbsp;spaced&nbsp;&nbsp;|= cells are rendered center aligned. %BR%
__Note:__ =|&nbsp;&nbsp;spaced&nbsp;|= cells are rendered right aligned. %BR%
__Note:__ =| 2 colspan ||= cells are rendered as multi-span columns. %BR%
__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. %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 | next | next |
</pre>
</font></span>
</td><td valign="top">
| *L* | *C* | *R* |
| A2 |  2  |  2 |
| A3 |  3  |  3 |
| multi span |||
| A4 | next | next |
</td>
</tr>
<tr bgcolor="#ffffff">
<td valign="top">
 *WikiWord Links:* %BR%
 <nop>CapitalizedWordsStuckTogether (or WikiWord<nop>s) will produce a link automatically. %BR% __Note:__ In case you want to link to a topic in a different %WIKITOOLNAME% web write =Webname.TopicName=.
</td><td valign="top">
<span style='background : #FFFFCC;'><font color="#990000">
<pre>
WebNotify

Know.ReadmeFirst
</pre>
</font></span>
</td><td valign="top">
WebNotify

Know.ReadmeFirst
</td>
</tr>
<tr bgcolor="#ffffff">
<td valign="top">
#SquareBrackets
 *Forced Links:* %BR%
 You can create a forced internal link by enclosing words in double square brackets.
 %BR% __Note:__  You can also refer to anchors.
</td><td valign="top">
<span style='background : #FFFFCC;'><font color="#990000">
<pre>
[[PodWikiFormatterTWiki]]

[[PodWikiFormatterTWiki#SquareBrackets]]
</pre>
</font></span>
</td><td valign="top">
[[PodWikiFormatterTWiki]]

[[PodWikiFormatterTWiki#SquareBrackets]]
</td>
</tr>
<tr bgcolor="#ffffff">
<td valign="top">
 *Specific Links:* %BR%
 Create a link where you can specify the link text and the link reference separately, using nested square brackets like =[<nop>[reference][text]]=. Internal link references (e.g. WikiWord) and external link references (e.g. http://TWiki.org/) are supported.
 %BR% __Note:__ The same __Forced Links__ rules apply for internal link references.
 %BR% __Note:__ For external link references, you can simply use a space instead of =][= to separate the link URL from the descriptive text.
 %BR% __Note:__ Anchor names can be added as well, like =[<nop>[WebHome#MyAnchor][go home]]= and =[<nop>[http://gnu.org/#Action][GNU Action]]=.
</td><td valign="top">
<span style='background : #FFFFCC;'><font color="#990000">
<pre>
[[PodWikiFormatterTWiki][TWiki Formatter]]

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

[[http://xml.org XML]]
</pre>
</font></span>
</td><td valign="top">
[[PodWikiFormatterTWiki][TWiki Formatter]]

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

[[http://xml.org XML]]
</td>
</tr>
<tr bgcolor="#ffffff">
<td valign="top">
 *Anchors:* %BR%
 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 WikiWord. To __link to__ an anchor name use the =[<nop>[MyTopic#MyAnchor]]= 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">
[[WebHome#NotThere]]

[[#MyAnchor][Jump]]

#MyAnchor To here
</td>
</tr>
<tr bgcolor="#ffffff">
<td valign="top">
 *Prevent a Link:* %BR%
 Prevent a WikiWord from being linked by prepending it with the =&lt;nop&gt;= tag.
</td><td valign="top">
<span style='background : #FFFFCC;'><font color="#990000">
<pre>
&lt;nop&gt;SunOS
</pre>
</font></span>
</td><td valign="top">
<nop>SunOS
</td>
</tr>
<tr bgcolor="#ffffff">
<td valign="top">
 *Disable Links:* %BR%
 You can disable automatic linking of a WikiWord by surrounding text with =&lt;noautolink&gt;= and =&lt;/noautolink&gt;= tags.
 %BR% __Note:__ Each tag must be on a line by itself.
 %BR% __Note:__ This also works for TWiki tables, but only if you add a blank line between the end of the table and the closing =&lt;/noautolink&gt;= tag.
</td><td valign="top">
<span style='background : #FFFFCC;'><font color="#990000">
<verbatim>
 <noautolink>
 RedHat &
 SuSE
 </noautolink>
</verbatim>
</font></span>
</td><td valign="top">
 <noautolink>
 RedHat &
 SuSE
 </noautolink>
</td>
</tr>
<tr bgcolor="#ffffff">
<td valign="top">
*Mailto: Links:* %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 =[<nop>[mailto:user@domain descriptive text]]=.
</td><td valign="top">
<span style='background : #FFFFCC;'><font color="#990000">
<pre>
[[mailto:a@z.com Mail]]

[[mailto:?subject=Hi Hi]]
</pre>
</font></span>
</td><td valign="top">
[[mailto:a@z.com Mail]]

[[mailto:?subject=Hi Hi]]
</td>
</tr>
</table>

---++ Using HTML

You can use just about any HTML tag without a problem - however, there are a few usability and technical considerations to keep in mind:
	* On collaboration pages, it's preferable NOT to use HTML, and to use [[#TWikiShorthand][TWiki shorthand]] instead - this keeps the text uncluttered and easy to edit.
	* %X% *NOTE:* <noautolink>PodWiki</noautolink> is designed to work with a wide range of browsers and computer platforms - adding raw HTML, particularly browser-specific tags (or any other mark-up that doesn't degrade well) will reduce compatibility.
	* <noautolink>PodWiki</noautolink> converts shorthand notation to HTML for display. To copy a fully marked-up page, simply view source in your browser and save the contents.
	* %X% *NOTE:* The opening and closing angle brackets - ==&lt;...&gt;== - of an HTML tag __must be on the same line__, or the tag will be broken.
		* 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, =&amp;lt;=, ex: ==a > b==
		* %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. 

---++ Hyperlinks

Being able to create links without any formatting required is a core wiki feature, made possible with WikiWord<nop>s. A few simple extensions of the syntax  provide a  set of flexible options. 

---+++ Internal Links

	* PodWikiHelp is a WikiWord that links to the <nop>PodWikiHelp topic.

	* 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://...=, =gopher://...=, =news://...=, =file://...=, =telnet://...=
	  and =mailto:...@...= are linked automatically.

	* Email addresses like =name@domain.com= are linked automatically.

	* =[<nop>[Square bracket rules]]= let you easily create [[#SquareBrackets][non-WikiWord links]].
		* You can also write =[<nop>[http://yahoo.com Yahoo home page]]= as an easier way of doing external links with descriptive text for the link, such as [[http://yahoo.com/ Yahoo home page]].


---++ TWiki Variables

Variables are names that are enclosed in percent signs =%= that are expanded on the fly.

	* =%<nop>TOC%= : Automatically generates a table of contents based on headings in a topic - see the top of this page for an example.

	* =%<nop>WEB%= : The current web, is <b>%WEB%</b>.

	* =%<nop>TOPIC%= : The current topic name, is <b>%TOPIC%</b>.

	* =%<nop>ATTACHURL%= :  The attachment URL of the current topic. In TWiki, attachments are made to an individual page, but in <noautolink>PodWiki</noautolink>they are global to the wiki. For <noautolink>PodWiki</noautolink>, this variable is expanded to the value of the configured <noautolink>PodWiki</noautolink>graphics URL prefix, which is currently %ATTACHURL%. Example usage: If you attach (upload) a file you can refer to it as =<b>%<nop>ATTACHURL%/image.gif</b>= to show the URL of the file or the image in your text. Example: %ATTACHURL%/ok.png

	* =%<nop>INCLUDE{"SomeTopic"}%= : Server side include, includes another topic. Example: =<b>%<nop>INCLUDE{"PodWikiAbout"}%</b>=

	* Some standard TWiki preference variables are mapped to <noautolink>PodWiki</noautolink>equivalents:
		* *Line break:* Write =<span style='background : #FFFFCC;'><font color="#990000">%<nop>BR%</font></span>= to start a new line.
		* *Colored text:* Write: =<span style='background : #FFFFCC;'><font color="#990000"> %<nop>RED% Red %<nop>ENDCOLOR% and %<nop>BLUE% blue %<nop>ENDCOLOR% colors</font></span>= to get: %RED% Red %ENDCOLOR% and %BLUE% blue %ENDCOLOR% colors.
		* *Documentation Graphics:* Write: =<span style='background : #FFFFCC;'><font color="#990000"> %<nop>H% Help, %<nop>T% Tip, %<nop>X% Alert</font></span>= to get: %H% Help, %T% Tip, %X% Alert. 

	* Other variables may be available in the wiki; see [[intern:listvars][PodWiki Variables]].


---++ <nop>TWikiPlugin Formatting Extensions

TWiki plugins are not supported under <noautolink>PodWiki</noautolink>. A plugin is called with a code sequenece such as:
<verbatim>
%PLUGINNAME{"Parameter1","Parameter2",...}%
</verbatim>
If such a call is encountered in a page, it will be rendered as plain text.


---++ Common Editing Errors

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

	* The ='&lt;'= and ='&gt;'= characters have a special meaning in HTML, they define HTML tags. You need to escape them, so write ='&amp;lt;'= instead of ='&lt;'=, and ='&amp;gt;'= instead of ='&gt;'=. <br /> Example: Type ='prog &amp;lt;filename&amp;gt;'= to get ='prog &lt;filename&gt;'=.

	* The ='&'= character has a special meaning in HTML, it starts a so called character entity, i.e. ='&amp;copy;'= is the =&copy;= copyright character. You need to escape ='&amp;'= to see it as it is, so write ='&amp;amp;'= instead of ='&amp;'=. <br /> Example: Type ='This &amp;amp; that'= to get ='This &amp; that'=.

=end

