Page Source for PodWikiFormatterTWiki
=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 =<verbatim>=
and =</verbatim>= tags. %BR% __Note:__ Use =<pre>= and
=</pre>= 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> <verbatim> class CatAnimal {
void purr() {
<code here>
} } </verbatim> </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 = = non-breaking-space entity. </td><td
valign="top"> <span style='background : #FFFFCC;'><font
color="#990000"> <pre>
Sushi: Japan
Dim Sum: S.F. </pre> </font></span>
</td><td valign="top">
Sushi: Japan
Dim 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:__
=| spaced |= cells are rendered
center aligned. %BR% __Note:__ =| spaced |=
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
=<nop>= tag. </td><td valign="top"> <span
style='background : #FFFFCC;'><font color="#990000">
<pre> <nop>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 =<noautolink>= and =</noautolink>= 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
=</noautolink>= 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 - ==<...>==
- 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, =<=, 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 ='<'= and ='>'= characters have a special meaning in HTML,
they define HTML tags. You need to escape them, so write ='<'=
instead of ='<'=, and ='>'= instead of ='>'=. <br />
Example: Type ='prog <filename>'= to get ='prog
<filename>'=.
* The ='&'= character has a special meaning in HTML, it starts a so
called character entity, i.e. ='©'= is the =©= copyright
character. You need to escape ='&'= to see it as it is, so write
='&'= instead of ='&'=. <br /> Example: Type ='This
& that'= to get ='This & that'=.
=end
=cut