Wiki 语法格式(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个空格, ... 然后一个'*',加上另一个空格 | * 一级条目 * 二级条目 |
| |||||||||||||||||||
排序列表: 三个空格, 一个数字, 一个小数点'.', 加上另外一个空格. 除了数字之外,还可以是其他类型的排序:
| 1. 张三 1. 李四 A. 张三 A. 李四 i. 张三 i. 李四 |
| |||||||||||||||||||
定义表: 三个空格, 一个'$'符号, 需定义词, 冒号, 空格, 解释. | $ 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 | |
| |||||||||||||||||||
WikiWord 链接: 大小写连在一起的多个词(称WikiWords)会自动产生一个链接. 注意 : 如果你想链接不同 TWiki 的链接,可写成 Otherweb.TopicName . (链接文本就是网页的topic名字,只有在WebHome 的时候是web名字) | WebNotify Main.TWikiUsers | WebNotify | |||||||||||||||||||
强制链接: 你可以使用两个方括号来强制生成链接 注意: 在括号包含的文本中可以有空格。topic名会自动按照一定规则生成:把每个词的首字母大写,然后移掉空格。例如: [[text formatting FAQ]] 将会自动连接到topic: TextFormattingFAQ. 你也可用使用链接文本来链接到不同的网页。 注意: 若不想自动强制产生链接,你可以在'[['之前使用'!',例如这样的开头 ![[.... | [[wiki syntax]] [[Main.TWiki users]] 未生成链接: ![[wiki syntax]] | wiki syntax 未生成链接: [[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语法 | |||||||||||||||||||
书签: 你可以在网页内部定义一个书签,然后在其他地方链接它。定义书签的格式:在一行的开头写上: #AnchorName , 书签名必须是一个有效的 WikiWord 。链接书签的格式是: [[MyTopic#MyAnchor]] ,和加*链接*的格式差不多. 如果你是在topic内部链接到同一topic的其他书签,你可以不用写topic的名字。. | [[WikiWord#NotThere]] [[#MyAnchor][Jump]] #MyAnchor To here | WikiWord#NotThere | |||||||||||||||||||
取消链接: 在 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 |
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编辑器中用不带硬回车的自动换行方式保存文本。
- 你可利用这个特征写一些非封闭的三角符号 - 例如大于号 '>'或小于号'<' - 它会自动翻译成相应的符号,和你写相应的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 内部链接
- 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中显示'|'需写成
|
例如:
- 答: 由于'|'是table的单元格分隔符,在table中显示'|'需写成
|test | content | |first| echo | |
你可以得到:
test | content |
first | echo | |
原文地址http://www.stlchina.org/twiki/bin/view.pl/TWiki/TextFormattingRules