twiki语法

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

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

 

1 TWiki 编辑语法速记

格式描述 :	例子 : You write:	效果 :
段落 : 一个空行会生成一个新段落 ( 注意空行上不要有空格 ).	1st paragraph   2nd paragraph	1st paragraph 2nd paragraph
大小标题 : 在一行以三个小横线 '-' 开头，后面跟加号 '+' 和相应的标题文字。一个加号 '+' 生成第一级标题 ( 当然是你认为最重要的 ) ，两个加号 '++' 就生成二级标题，以此类推，最多可以有 6 个加号。 注意 : 如果你使用 %TOC% 变量，内容的目录会自动生成，详细可以查看 TWikiVariables ，如果在标题文字前面有 !! ，则 TOC 就不会把这个标题列入目录中去，例如：如果你不希望某个标题列入目录，你就以 ---+!! text 的方式。	---++ 二级标题   ---+++ 三级标题	二级标题 三级标题
粗体字 : 字符要变得 粗 只需要在他们两端加上 * 号 .	*Bold*	Bold
斜体字 : 要把字变成 斜体 只需要在字两端加上 _ 符号 .	_Italic_	Italic
粗斜体字 : 要得到 _ 粗斜体 只需要在字两端加上 __ 符号 .	__Bold italic__	Bold italic
Fixed Font: 要得到 fixed font ，只需要在字符串两端加上 = 符号 .	=Fixed font=	Fixed font
Bold Fixed Font: 要想得到 bold fixed font ，需要在字符两端各加上 == 符号 .	==Bold fixed==	Bold fixed
注意 : 要想达到上述效果，必须在字符串和功能字符 (* _ = _ == 等 ) 之间，没有任何空格。	_This works_, _this not _	This works , _this not _
Verbatim 模式 : 这是逐字模式，在一些代码两端使用 <verbatim> 和 </verbatim> 标签 . 这样使得被包围的所有字符都按照你编辑的样式显示。 注意 : 如果你希望在里面的 HTML 代码仍然能起作用，你可以使用 <pre> 和 </pre> 标签来代替使用 注意 每个标签必须自己单独一行 .	<verbatim> class CatAnimal {   void purr() {      <code here>   } } </verbatim>	class CatAnimal {   void purr() {     <code here>   } }
分割符 : 在一行的开头，用三个连续的 '-' 符号。	-------
列表 : 一行开头是三个空格，加一个 '*' 号，再加一个空格。	* 条目	·         条目
多级列表 : 6 个空格 , 9 个空格 , ... 然后一个 '*' ，加上另一个空格	* 一级条目       * 二级条目	·         一级条目 o    二级条目
排序列表 : 三个空格 , 一个数字 , 一个小数点 '.', 加上另外一个空格 . 除了数字之外，还可以是其他类型的排序 : 类型 风格说明 样例 1. 阿拉伯数字 1, 2, 3, 4... A. 大写字母 A, B, C, D... a. 小写字母 a, b, c, d... I. 大写罗马数字 I, II, III, IV... i. 小写罗马数字 i, ii, iii, iv...	1. 张三    1. 李四      A. 张三    A. 李四      i. 张三    i. 李四	1         张三 2         李四 1         张三 2         李四 1         张三 1         李四
定义表 : 三个空格 , 一个 '$' 符号 , 需定义词 , 冒号 , 空格 , 解释 .	$ Winter: 搜索引擎爱好者    $ qianfeng: 技术爱好者	Winter 一个搜索引擎爱好者，程序员 Qianfeng 技术爱好者
表格 : 可以有任意多行。每行是表格的一行，可以有一个或多个单元格。每个单元格开始和结尾都用 '|' 标示。每行开头的空格都会被忽略。 注意 : • | *bold* | 表头单元格 . • |   center-spaced   | 单元格居中显示 . • |     right-spaced | 单元格右对齐 . • | 2 colspan || 跨栏显示单元格 ( 如 , 单元格中没有文本 ). • |^| 在单元格写入 '^' 符号，会自动把多行的单元格合并。 ( 这个功能需要插件 TablePlugin 支持 ). • 如果在一行之内包含大量文本，你想在编辑的过程中可读性强，你可以用 '/' 作为一行的结束，这样把一行变成多行。 • 表格的单元格会随着浏览器自动折行。	| *L* | *C* | *R* | | A2 |  2  |  2 | | A3 |  3  |  3 | | 多栏 ||| | A4-6 行 | four | four | |^| five | five | |^| six | six |	L C R A2 2 2 A3 3 3 多栏 A4-6 行 four four five five six six
WikiWord 链接 : 大小写连在一起的多个词 ( 称 WikiWords) 会自动产生一个链接 . 注意 : 如果你想链接不同 TWiki 的链接，可写成 Otherweb.TopicName. ( 链接文本就是网页的 topic 名字，只有在 WebHome 的时候是 web 名字 )	WebNotify   Main.TWikiUsers	WebNotify TWikiUsers
强制链接 : 你可以使用两个方括号来强制生成链接 注意 : 在括号包含的文本中可以有空格。 topic 名会自动按照一定规则生成：把每个词的首字母大写，然后移掉空格。例如： [[text formatting FAQ]] 将会自动连接到 topic: TextFormattingFAQ . 你也可用使用链接文本来链接到不同的网页。 注意 : 若不想自动强制产生链接，你可以在 '[[' 之前使用 '!' ，例如这样的开头 ![[....	[[wiki syntax]]   [[Main.TWiki users]]   未生成链接 : ![[wiki syntax]]	wiki syntax Main.TWiki users 未生成链接 : [[wiki syntax]]
特定链接 : 你可以使用嵌套的 '[' 符号生成链接，自己指定链接地址和链接文本。如： [[ 链接地址 ][ 链接文本 ]]. 网页内部链接地址（如 WikiSyntax ) 和外部链接地址 ( 如 http://stlchina.org/ ) 都支持 . 注意 : * 强制链接 * 规则对于内部链接地址同样支持 . 注意 : 对于外部链接，你可以把在链接地址和链接文本之间的 ][ 用一个空格代替 . 注意 : 链接网页内部标签也可做为链接地址的一部分（即可以直接链接到另一网页的某个特定位置 ), 如： [[WebHome#MyAnchor][ 返回主目录 ]] 和 [[http://gnu.org/#Action][GNU Action]].	[[WikiSyntax][TWiki 语法 ]]   [[http://winterxy.com][Winter 实验室 ]]   [[http://stlchina.org STL 中文站 ]]	TWiki 语法 Winter 实验室 STL 中文站
书签 : 你可以在网页内部定义一个书签，然后在其他地方链接它。定义书签的格式：在一行的开头写上： #AnchorName ， 书签名必须是一个有效的 WikiWord 。链接书签的格式是： [[MyTopic#MyAnchor]] ，和加 * 链接 * 的格式差不多 . 如果你是在 topic 内部链接到同一 topic 的其他书签，你可以不用写 topic 的名字。 .	[[WikiWord#NotThere]]   [[#MyAnchor][Jump]]   #MyAnchor To here	WikiWord#NotThere Jump To here
取消链接 : 在 WikiWord 前加上一个 '!' 符号，就可以取消 WikiWord 上的链接 .	!SunOS	SunOS
使链接失效 : 你可以通过在文本的两端使用 <noautolink> 和 </noautolink> 符号，让被包围的文本中的所有自动链接都失效。 注意 : 每个符号应该单独一行 注意 : 这同样适用于 TWiki 表格 , 但是你需要在表格的结尾和 </noautolink> 符号之间增加一空行 ( 现在需要 TablePlugin 插件支持 ).	<noautolink>   RedHat &   SuSE   </noautolink>	RedHat & SuSE
Mailto: 链接 : 使用 'mailto' 链接，你可以增加很多描述性的链接文本，详细的注意行或信息块，或还可让 email 地址不可见。生成 'mailto' 链接的方式： [[mailto:user@domain descriptive text]].	[[mailto:winter@winterxy.com 给 Winter 发 mail]]   [[mailto:winter@winterxy.com?subject=hello 主题是 'hello' 的 mail]]	给 Winter 发 mail 主题是 'hello' 的 mail

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> 标签 :

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

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 支持。例如

%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 定义了全站范围的变量 . 除此之外还有 :

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 中显示 '|' 需写成 &#124; 例如：

|test | content |

|first| echo &#124; |

 

你可以得到：

test	content
first	echo |