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

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

1 TWiki 编辑语法速记 

2 使用 HTML

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

2.1 HTML 和 TWiki 可用性 

·         TIP: 作为共同编辑的页面，最好还是不要使用HTML代码，而使用 TWiki 语法来代替 - 这样可以让页面保持整洁而容易编辑。

·         注意: TWiki 支持多种浏览器和系统平台，标准TWiki安装版本兼容HTML5.0和XHTML 1.0 - 你增加的HTML代码，特定的浏览器标签(或者其他的不兼容低版本的补充)都有可能降低兼容性

·         关于使用HTML的建议:

o    使用 XHTML 1.0 Transitional 语法

o    不要跨行写一个标签.

o    删除所有空行。 TWiki会在每个空行上插入 <p /> 段落标签，这样对那些不能插入段落的标签来说，就会引起问题。例如：在table 标签之间就不能使用 <p />

2.2 TWiki 的 HTML 展现

·         TWiki 把一些简化符号翻译成 XHTML 1.0 格式显示. 若要拷贝网页的内容，你只需要查看网页源文件，然后保存其内容。

o    若你需频繁保存为HTML格式，你需要使用插件： TWiki:Plugins/GenHTMLAddon - 它能 "产生一个目录，其中包含所有要发布成HTML格式的TWiki页面，并包含了所有的附件."

·         注意: HTML代码中所有 <...> 标签必须写在同一行，否则这个标签就会被分开.

o    你可利用这个特征写一些非封闭的三角符号 - 例如大于号 '>'或小于号'<' - 它会自动翻译成相应的符号，和你写相应的HTML代码一样( &lt; ), 如: a < b

o    如果你在粘贴HTML文本的时候发现了问题，你可以把这些代码放在没有自动换行的文本编辑器检查一下。也可在你的HTML编辑器中用不带硬回车的自动换行方式保存文本。

2.3 TWiki 和 JavaScript

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

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 的链接.

o    你也可以写成这种形式： [[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 支持。例如

你会得到

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

·         TWikiPreferences 定义了全站范围的变量. 除此之外还有:

o    换行: 用 %BR% 来另起一行.

o    文本颜色: 用: %RED% 红色 %ENDCOLOR% 和 %BLUE% 蓝色 %ENDCOLOR% colors 可得到: 红色和 蓝色.

o    图形素材: 用: %H% 帮助, %T% 提示, %X% 警告 可以得到: 帮助, 提示, 警告. 更多的信息请参考 TWikiDocGraphics.

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

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

5 TWiki插件中的扩展格式

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

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

·         SpreadSheetPlugin (any TWiki, $Rev: 17387 (11 Aug 2008) $): Add spreadsheet calculation like "$SUM( $ABOVE() )" to TWiki tables and other topic text

·         BeautifierPlugin (Dakar, $Rev: 0 (06 Jul 2008) $): Highlights and formats code fragments

·         CalendarPlugin (Dakar, $Rev: 0 (23 Sep 2008) $): Show a monthly calendar with highlighted events

·         ChartPlugin (Dakar, $Rev: 0 (05 Jul 2008) $):

·         CommentPlugin (03 Aug 2008, $Rev: 17302 (11 Aug 2008) $): Allows users to quickly post comments to a page without an edit/preview/save cycle

·         EditTablePlugin (4.8.4, $Rev: 17302 (11 Aug 2008) $): Edit TWiki tables using edit fields, date pickers and drop down boxes

·         InterwikiPlugin (03 Aug 2008, $Rev: 14913 (17 Sep 2007) $): Link ExternalSite:Page text to external sites based on aliases defined in a rules topic

·         PreferencesPlugin (TWiki-4.2, $Rev: 15487 (11 Aug 2008) $): Allows editing of preferences using fields predefined in a form

·         SmiliesPlugin (Dakar, $Rev: 16049 (11 Aug 2008) $): Render smilies as icons, like for  :-) or for  :eek:

·         TablePlugin (1.034, $Rev: 17367 (11 Aug 2008) $): Control attributes of tables and sorting of table columns

·         TemplateToolkitPlugin (Dakar, $Rev: 0$): Allow Template Toolkit expansion of topics

·         TinyMCEPlugin: (disabled)

·         TwistyPlugin (1.4.10, $Rev: 15653 (19 Nov 2007) $): Twisty section JavaScript library to open/close content dynamically

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

6 常见编辑错误

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

·         问: 被尖括号 <filename> 括起来的文本不能显示，如何才能显示？

o    答: 尖括号 '<' 和 '>' 在HTML中有特殊含义，用来定义HTML标签。若想直接显示，则需写成 '&lt;' 代替 '<', 和 '&gt;' 代替 '>'.
例如: 输入 'prog &lt;filename&gt;' 你会得到 'prog <filename>'.

·         问: 为什么有时候符号 '&' 不能显示？

o    答: 符号 '&' 在HTML中有特殊的意义，它经常用来表示一些转义字符的开头，例如 '&copy;' 用来表示 © copyright 字符. 若想直接显示 '&' , 则需写成 '&amp;' 代替 '&'.
例如: 输入 'This &amp; that' 你会得到 'This & that'.

·         问: 如何在table中显示 '|' ？

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

你可以得到：