TWiki 语法格式 (TWiki 语法教程及 TWiki 使用技巧 )
Winter 翻译 用 TWiki 编辑就和平时直接写文本一样简单 -- 就像写 email 。如果你喜欢,你可以使用 HTML 代码,但是并不要求你了解。当你写入一个 WikiWords 时, TWiki 会自动链接到相应的主题。 TWiki 语法速记让你通过一个简单的译码系统拥有了所有强大的 HTML 功能。 在你使用 Edit 界面时,本网页可以通过弹出窗口的方式完全展现给用户。
1 TWiki 编辑语法速记
格式描述 : | 例子 : You write: | 效果 : | |||||||||||||||||||
段落 : | 1st paragraph
2nd paragraph
| 1st paragraph 2nd paragraph | |||||||||||||||||||
大小标题 : | ---++ 二级标题
---+++ 三级标题
| 二级标题 三级标题 | |||||||||||||||||||
粗体字 : | *Bold*
| Bold | |||||||||||||||||||
斜体字 : | _Italic_
| Italic | |||||||||||||||||||
粗斜体字 : | __Bold italic__
| Bold italic | |||||||||||||||||||
Fixed Font: | =Fixed font=
| Fixed font | |||||||||||||||||||
Bold Fixed Font: | ==Bold fixed==
| Bold fixed | |||||||||||||||||||
注意 : 要想达到上述效果,必须在字符串和功能字符 (* _ = _ == 等 ) 之间,没有任何空格。 | _This works_, _this not _
| This works , | |||||||||||||||||||
Verbatim 模式 : | <verbatim> class CatAnimal { void purr() { <code here> } } </verbatim>
|
class CatAnimal { void purr() { <code here> } }
| |||||||||||||||||||
分割符 : | -------
|
| |||||||||||||||||||
列表 : | * 条目
| · 条目
| |||||||||||||||||||
多级列表 : | * 一级条目 * 二级条目
| · 一级条目 o 二级条目
| |||||||||||||||||||
排序列表 :
| 1. 张三 1. 李四
A. 张三 A. 李四
i. 张三 i. 李四
| 1 张三 2 李四 1 张三 2 李四 1 张三 1 李四
| |||||||||||||||||||
定义表 : | $ Winter: 搜索引擎爱好者 $ qianfeng: 技术爱好者
| Winter 一个搜索引擎爱好者,程序员 Qianfeng 技术爱好者
| |||||||||||||||||||
表格 : | | *L* | *C* | *R* | | A2 | 2 | 2 | | A3 | 3 | 3 | | 多栏 ||| | A4-6 行 | four | four | |^| five | five | |^| six | six |
|
| |||||||||||||||||||
WikiWord 链接 : | WebNotify
Main.TWikiUsers
| ||||||||||||||||||||
强制链接 : | [[wiki syntax]]
[[Main.TWiki users]]
未生成链接 : ![[wiki syntax]]
| 未生成链接 : [[wiki syntax]] | |||||||||||||||||||
特定链接 : | [[WikiSyntax][TWiki 语法 ]]
[[http://winterxy.com][Winter 实验室 ]]
[[http://stlchina.org STL 中文站 ]]
| ||||||||||||||||||||
书签 : | [[WikiWord#NotThere]]
[[#MyAnchor][Jump]]
#MyAnchor To here
| To here | |||||||||||||||||||
取消链接 : | !SunOS
| SunOS | |||||||||||||||||||
使链接失效 : | <noautolink> RedHat & SuSE </noautolink>
| RedHat & SuSE | |||||||||||||||||||
Mailto: 链接 : | [[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 的建议 :
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 代码一样 ( < ), 如 : 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 标签。若想直接显示,则需写成 '<' 代替 '<', 和 '>' 代替 '>'.
例如 : 输入 'prog <filename>' 你会得到 'prog <filename>'.
· 问 : 为什么有时候符号 '&' 不能显示?
o
答 : 符号 '&' 在 HTML 中有特殊的意义,它经常用来表示一些转义字符的开头,例如 '©' 用来表示 © copyright 字符 . 若想直接显示 '&' , 则需写成 '&' 代替 '&'.
例如 : 输入 'This & that' 你会得到 'This & that'.
· 问 : 如何在 table 中显示 '|' ?
o 答 : 由于 '|' 是 table 的单元格分隔符,在 table 中显示 '|' 需写成 | 例如:
|test | content |
|first| echo | |
你可以得到:
test | content |
first | echo | |