TWiki 语法格式(TWiki语法教程及TWiki使用技巧)

用TWiki 编辑就和平时直接写文本一样简单 -- 就像写email。如果你喜欢，你可以使用HTML代码，但是并不要求你了解。当你写入一个 WikiWords 时，TWiki会自动链接到相应的主题。TWiki 语法速记让你通过一个简单的译码系统拥有了所有强大的HTML功能。 在你使用 Edit 界面时，本网页可以通过弹出窗口的方式完全展现给用户。

1 TWiki 编辑语法速记

1st paragraph

2nd paragraph

---++ 二级标题

---+++ 三级标题

*Bold*

_Italic_

__Bold italic__

=Fixed font=

==Bold fixed==

_This works_,
_this not _

<verbatim>
class CatAnimal {
  void purr() {
    <code here>
  }
}
</verbatim>

class CatAnimal {
  void purr() {
    <code here>
  }
}

-------

   * 条目

   * 一级条目
      * 二级条目

   1. 张三
   1. 李四

   A. 张三
   A. 李四

   i. 张三
   i. 李四

   $ Winter: 搜索引擎爱好者
   $ qianfeng: 技术爱好者

| *L* | *C* | *R* |
| A2 |  2  |  2 |
| A3 |  3  |  3 |
| 多栏 |||
| A4-6行 | four | four |
|^| five | five |
|^| six | six |

WebNotify

Main.TWikiUsers

[[wiki syntax]]

[[Main.TWiki users]]

未生成链接:
![[wiki syntax]]

[[WikiSyntax][TWiki语法]]

[[http://winterxy.com][Winter实验室]]

[[http://stlchina.org STL中文站]]

[[WikiWord#NotThere]]

[[#MyAnchor][Jump]]

#MyAnchor To here

!SunOS

 <noautolink>
 RedHat &
 SuSE
 </noautolink>

[[mailto:winter@winterxy.com 给Winter发mail]]

[[mailto:winter@winterxy.com?subject=hello 主题是'hello'的mail]]

2 使用 HTML

你可任意的使用任何HTML代码 - 但要提醒的是，你仍需注意一些技术方面的细节。

2.1 HTML 和 TWiki 可用性

• TIP: 作为共同编辑的页面，最好还是不要使用HTML代码，而使用 TWiki 语法来代替 - 这样可以让页面保持整洁而容易编辑。
• 注意: TWiki 支持多种浏览器和系统平台，标准TWiki安装版本兼容HTML5.0和XHTML 1.0 - 你增加的HTML代码，特定的浏览器标签(或者其他的不兼容低版本的补充)都有可能降低兼容性
• 关于使用HTML的建议:
  • 使用 XHTML 1.0 Transitional 语法
  • 不要跨行写一个标签.
  • 删除所有空行。 TWiki会在每个空行上插入 <p /> 段落标签，这样对那些不能插入段落的标签来说，就会引起问题。例如：在table 标签之间就不能使用 <p />

2.2 TWiki 的 HTML 展现

• TWiki 把一些简化符号翻译成 XHTML 1.0 格式显示. 若要拷贝网页的内容，你只需要查看网页源文件，然后保存其内容。
  • 若你需频繁保存为HTML格式，你需要使用插件： TWiki:Plugins/GenHTMLAddon - 它能 "产生一个目录，其中包含所有要发布成HTML格式的TWiki页面，并包含了所有的附件."
• 注意: HTML代码中所有 <...> 标签必须写在同一行，否则这个标签就会被分开.
  • 你可利用这个特征写一些非封闭的三角符号 - 例如大于号 '>'或小于号'<' - 它会自动翻译成相应的符号，和你写相应的HTML代码一样( < ), 如: a < b
  • 如果你在粘贴HTML文本的时候发现了问题，你可以把这些代码放在没有自动换行的文本编辑器检查一下。也可在你的HTML编辑器中用不带硬回车的自动换行方式保存文本。

2.3 TWiki 和 JavaScript

在你的TWiki中，你可以使用 JavaScript. TWiki在显示时可能会干扰 JavaScript 代码，如果你希望避免这种情况，你可使用HTML注释，或者使用 <pre> 标签:

<script type="text/javascript">
<!-- 隐藏的 JavaScript 和 <pre> 来避免 TWiki 显示
... 把你的 JavaScript代码放在这儿...
// 不在隐藏  </pre> 让TWiki正常显示 -->
</script>

3 超链接

不需任何格式就可生成超级链接是TWiki最核心的特征之一，TWiki是通过 TWikiWords^? 来实现此功能的。TWiki在其语法基础上扩展了新的链接规则，并提供了一套灵活的选项。

3.1 内部链接

• GoodStyle 是一个 WikiWord , 并且会链接到本TWiki网站内的 GoodStyle 主题。

• NotExistingYet^? 是一个需要增加的主题。点击后面的 ? 号就会生成新的主题。 (你可以试一试，然后选择 Cancel - 如果你已经生成这个主题了，那么这个例子就不行了!)

3.2 外部链接

• http://..., https://..., ftp://..., gopher://..., news://..., file://..., telnet://... 和 mailto:...@... 都是自动链接的。

• Email 地址，如 name@domain.com 也是自动链接的。

• [[方括号规则]] 可让你方便的生成 non-WikiWord 的链接.
  • 你也可以写成这种形式： [[http://yahoo.com Yahoo 首页]] ，或者一种更方便的形式：雅虎 page ，这样不需要任何描述文本，可以直接生成外部链接.

4 TWiki 变量

变量就是用百分号 % 包围的那些名字，可以任意扩充。

• %TOC% : 自动生成本文内容的目录。此目录是基于每个topic 的heading 定义 - 本文开头就有一个目录例子。

• %WEB% : 当前的web名, 例如，目前的Web是 TWiki.

• %TOPIC% : 当前的topic 名, 例如，本网页的topic是 TextFormattingRules.

• %ATTACHURL% : 当前topic的附件的url. 例如：如果你上传了一个附件，你可以写这种格式 %ATTACHURL%/image.gif 来在文中显示你的文件或者图片链接.

• %INCLUDE{"SomeTopic"}% : 包含其他主题（topic）. 当前的web是默认的web(一个网页显示需要web名和topic名). 例如，你用这种格式可以把 SiteMap 页面包含进来: %INCLUDE{"TWiki.SiteMap"}%

• %CODE{"xxx"}% 和 %ENDCODE% : 以代码的方式显示文本，支持cpp perl php tcl bash等，需要插件TWiki.BeautifierPlugin 支持。例如
  

%CODE{"cpp"}%
#include <stdio.h> 
main () //Here is a comment
{ printf("hello world!");
}
%ENDCODE%

你会得到

#include <stdio.h> 
main () //Here is a comment
{ printf("hello world!");
}

• %SEARCH{"sushi"}% : 内联的搜索功能可以把搜索结果嵌入某个topic中。 FormattedSearch 会告诉你如何使用格式，如果生成基于网页的应用。

• TWikiPreferences 定义了全站范围的变量. 除此之外还有:
  • 换行: 用 %BR% 来另起一行.
  • 文本颜色: 用: %RED% 红色 %ENDCOLOR% 和 %BLUE% 蓝色 %ENDCOLOR% colors 可得到: 红色 和 蓝色 .
  • 图形素材: 用: %H% 帮助, %T% 提示, %X% 警告 可以得到: 帮助, 提示, 警告. 更多的信息请参考 TWikiDocGraphics.

• 还有更多的变量, 可以参考 TWikiVariables.

• 若希望让某个变量失效，在变量之前加上感叹号'!'。例如: !%SOMEVARIABLE% 你会得到: %SOMEVARIABLE%.

5 TWiki插件中的扩展格式

插件为TWiki提供更强大的文本编辑能力，你可以扩展这些功能到其他许多领域。例如，可选的电子表格插件，可以让你利用基本的TWiki表格的语法来生成漂亮的电子表格.

可以选择的插件都列在TWiki.org网站的 插件列表。在目前版本已经安装的插件都列在变量 %PLUGINDESCRIPTIONS% 中:

• BeautifierPlugin (Dakar, $Rev: 14024 (03 Jun 2007) $): Highlights and formats code fragments
• CommentPlugin (Dakar, 11359): Allows users to quickly post comments to a page without an edit/preview/save cycle
• EditTablePlugin (any TWiki, 11646): Edit TWiki tables using edit fields, date pickers and drop down boxes
• InterwikiPlugin (Dakar, $Rev: 11935$): Link ExternalSite:Page text to external sites based on aliases defined in a rules topic
• PreferencesPlugin (Dakar, 9839): Allows editing of preferences using fields predefined in a form
• SlideShowPlugin (Any TWiki, $Rev: 12847$): Create web based presentations based on topics with headings.
• SmiliesPlugin (Dakar, 8154): Render smilies as icons, like  :-) for or  :cool: for :cool:
• SpreadSheetPlugin (any TWiki, 10197): Add spreadsheet calculation like "$SUM( $ABOVE() )" to tables located in TWiki topics.
• TablePlugin (1.020, 12339): Control attributes of tables and sorting of table columns
• TwistyPlugin^? (1.2.0, $Rev: 12154$):

点击当前的插件，可以在 TWikiPreferences 为整个网站设置.

6 常见编辑错误

TWiki语法规则相当简单，很容易上手。但还是有些细节需要小心，以下内容节选自 TextFormattingFAQ:

• 问: 被尖括号 <filename> 括起来的文本不能显示，如何才能显示？
  • 答: 尖括号 '<' 和 '>' 在HTML中有特殊含义，用来定义HTML标签。若想直接显示，则需写成 '<' 代替 '<', 和 '>' 代替 '>'.
    例如: 输入 'prog <filename>' 你会得到 'prog <filename>'.

• 问: 为什么有时候符号 '&' 不能显示？
  • 答: 符号 '&' 在HTML中有特殊的意义，它经常用来表示一些转义字符的开头，例如 '©' 用来表示 © copyright 字符. 若想直接显示 '&' , 则需写成 '&' 代替 '&'.
    例如: 输入 'This & that' 你会得到 'This & that'.

• 问: 如何在table中显示 '|' ？
  • 答: 由于'|'是table的单元格分隔符，在table中显示'|'需写成 | 例如：

|test | content |
|first| echo | |