群英汇 Trac 指南

什么是 Trac，参见： TracAbout 。

  1. 维基(wiki) 无处不在
    1. 基本Wiki语法
    2. TracLinks
    3. 宏
    4. 表情符号
  2. 时间线 ── 项目最新改动的一网打尽
  3. 路线图 ── 项目进展一目了然
  4. 源码浏览
  5. Ticket 与工作流
  6. 工具整合
    1. EclipseTracPlugin 插件
    2. Eclipse Mylyn
    3. TracExplorer 实现与 Trac 与 TSVN 整合

本页面提供一个 Trac 的快速入门手册，其中群英汇对 trac 的扩展和改进将做着重指出。

在阅读完本指南后，您也可以参照 trac 本身自带的帮助文档 TracGuide，不过留意其有的内容已被群英汇改进。

维基(wiki) 无处不在

维基是 Trac 实现功能整合背后的奥秘。在 Trac 中维基无处不在：

  • Trac 的项目首页是用 Wiki 技术实现的，人人均可编辑的项目页
  • Trac 中 Wiki 引擎不仅用于项目首页等网面的维护，还被 Trac 的各个模块共享
  • Ticket 的问题描述，支持 Wiki 语法
  • 代码的 commit log，支持 Wiki 语法。不但为在网页中显示代码提交说明有了更多的格式化选项，而且提供了代码提交触发 Ticket 变更的语法支持
  • 提供了对 Trac 中各个元素交互引用的语法。对 Ticket, 代码等 Trac 各个元素的语法扩展，又称为 TracLinks

基本Wiki语法

Trac 的语法参照了 Moin(1.5)，因此和 MoinMoin wiki 旧的语法非常相似，但是由于 MoinMoin 从 1.6 版本开始，采用了更为通用的标准语法，因此导致 Trac 的语法和 MoinMoin 以及绝大多数维基的语法变得有些格格不入。

群英汇对 Trac 的维基语法进行了大规模的改造，增强了和 MoinMoin 维基的兼容性，使得支持目前主流维基的语法，并和 MoinMoin 最新的语法基本相同。这样用户就不必记忆两套不同的语法了。

语法示例 模拟输出 说明
'''加粗''' 加粗
''斜体字'' 斜体字
'''''粗斜体''''' 粗斜体
__下划线__ 下划线
~~删除线~~ 删除线
--(删除线)-- 删除线 (!) 群英汇扩展，与 MoinMoin 兼容
~-字体变小-~ 字体变小 (!) 群英汇扩展，与 MoinMoin 兼容
~+字体变大+~ 字体变大 (!) 群英汇扩展，与 MoinMoin 兼容
a^2^+b^2^=c^2^ a2+b2=c2 上角标
2H,,2,,+O,,2,,=2H,,2,,O 2H2+O2=2H2O 下角标 
= 标题1 =
== 二级标题 =====
===三级标题==

标题1

二级标题

三级标题

(!) 群英汇扩展，标题容错更强
强制换行<<BR>>另一行 强制换行
另一行 		强制换行 
一个换行符
不能分段，会续行。

两个连续的回车，实现换行。

一个换行符 不能分段，会续行。

两个连续的回车，实现换行。

段落 
缩进也会完美呈现。
  前面两个空格
    前面四个空格
    前面四个空格（同等缩进则续行）

缩进也会完美呈现。

前面两个空格

前面四个空格 前面四个空格（同等缩进则续行）

缩进 
----
------
不同粗细的水平分隔线 
 * 无编号列表1（注意*号前后的空格！）
 * 无编号列表2
   1. 编号列表1
     1. 缩进则成为下级编号
   1. 编号列表2
     a. 字母为编号
       A. 大写字母为编号
   1. 编号列表3
     i. 罗马数字编号
       I. 大写罗马数字编号
  • 无编号列表1（注意*号前后的空格！）
  • 无编号列表2
    1. 编号列表1
      1. 缩进则成为下级编号
    2. 编号列表2
      1. 字母为编号
        1. 大写字母为编号
    3. 编号列表3
      1. 罗马数字编号
        1. 大写罗马数字编号
列表 
 名词1:: 相关解释
 名词2:: 相关解释
名词1
相关解释
名词2
相关解释
注意：行首的前导空格以及双冒号后的空格 
>> Someone's original text
> Someone else's reply text
My reply text

Someone's original text

Someone else's reply text

My reply text

引言 
||Cell 1||Cell 2||Cell 3||
||Cell 4||Cell 5||Cell 6||

Cell 1Cell 2Cell 3
Cell 4Cell 5Cell 6

表格
CamelCase 式的自动wiki页面链接

CamelCase 式的自动wiki页面链接

链接 
 * !CamelCase: 前面的叹号取消链接
 * `CamelCase`: 同样可以取消链接
  • CamelCase: 前面的叹号取消链接
  • CamelCase: 同样可以取消链接
取消链接 
 * [[freelink]]
 * [[freelink|Freelink 页面]]
 * [[my freelink]]
 * [[..]]
 * [[..|父页面]]
 * [[../Sibling|兄弟页面]]
 * [[#anchor|指向页内链接]]

自由链接。注意 Wiki 页面名称不能和内置宏名冲突

(!) 群英汇扩展，与 MoinMoin 兼容 

 * [[/newticket|新建Ticket]]
 * [[/|首页]]
 * [[//moinmoin|其它网站]]

<!> 和 MoinMoin 不兼容的链接语法。 MoinMoin 中是子页面含义 

 * http://www.ossxp.com
 * ftp://172.16.0.2/pub
 * tsvn://http://svn.ossxp.com/svn/pysvnmanager/trunk
 协议链接 
 * [[http://www.ossxp.com|群英汇网站]]
 * [[ftp://172.16.0.2/pub|ftp站点]]
 * [[tsvn://http://svn.ossxp.com/svn/pysvnmanager/trunk
   |检出代码]]

自由链接

(!) 群英汇扩展，与 MoinMoin 兼容 

 * <<Image(wiki:WikiFormatting:picture.gif)>>
   (嵌入其它页面附件中图片)
 * <<Image(ticket:1:picture.gif)>>
   (嵌入附加在 ticket 上的图片附件)
 * <<Image(htdocs:picture.gif)>>
   (指向 htdocs 项目目录中静态图片)
 * <<Image(htdocs:../common/trac_logo_mini.png)>>
   (指向 htdocs 公共目录中静态图片)
 * <<Image(source:/trunk/trac/htdocs/trac_logo_mini.png)>>
   (嵌入版本库中的图片文件)
trac_logo_mini.png
(htdocs:../common/trac_logo_mini.png)

<!> 和 MoinMoin 不兼容的嵌入图片语法。MoinMoin 用类似 {{attachment:picture.jpg}} 的语法

{{{'''Wiki''' __not__ works in ~+this block+~.\nNext line.}}} 
'''Wiki''' __not__ works in ~+this block+~.
Next line.
禁用Wiki语法
(!) 群英汇扩展：在单行inline块中，可以用 "\n" 实现换行显示 
{{{
#!html
<div style="text-align: center; 
color: blue; background-color: yellow;">
  HTML Test
</div>
}}}

HTML Test

嵌入 HTML 
{{{
#!div style="border: 1px solid #d7d7d7; 
padding: 0; background-color:lightblue;"
Test text
}}}

Test text

设置DIV样式 
{{{
#!c
int main(int argc, char *argv[])
{
  printf("Hello World
");
  return 0;
}}} 

int main(int argc, char *argv[])
{
  printf("Hello World
");
  return 0;

代码块 
{{{
#!comment
Your comment here
}}} 		注释

Trac Links 是 Trac 特有的链接语法。Trac 的Wiki 引擎，可以通过其特有的链接语法，将 trac 的各个元素整合在一起，像一个黏合剂一样。可以整合的 trac 模块包括：ticket, 报告, 时间线, 版本库, 文件下载, 变更集, 日志, 代码差异, 里程碑, 附件, 搜索, 等等。

链接类别语法示例模拟输出
ticket 
 * #1
 * see #1, #3 and #5
 * #1,3,5
 * #1-4
 * ticket:1
 * [[ticket:1|访问ticket:1]]
 * ticket:1-4
 * ticket:1#comment:3
 * comment:3:ticket:1
报告 
 * {6}
 * report:6
 * [[report:6|所有 Tickets （按里程碑排序，包含关闭的）]]
时间线 
 * timeline:2008-01-29
 * timeline:2008-01-29T15:48
 * timeline:2008-01-29T16:48Z+01
版本库(缺省版本库) 
 * repos:/trunk
 * browser:/trunk
 * source:/trunk/COPYING
 * source:/trunk/COPYING@200
 * source:/trunk/COPYING@200#L25
版本库(其它版本库) 
 * repos:/repo/trunk
 * browser:/repo/trunk
 * source:/repo/trunk/COPYING
 * source:/repo/trunk/COPYING@200
 * source:/repo/trunk/COPYING@200#L25
文件导出(缺省版本库) 
 * export:/trunk/COPYING
 * export:123:/trunk/COPYING
 * export:/trunk/COPYING@123
文件导出(其它版本库) 
 * export:/repo/trunk/COPYING
 * export:123:/repo/trunk/COPYING
 * export:/repo/trunk/COPYING@123
变更集(缺省版本库) 
 * r3
 * [3]
 * changeset:3
 * [3/trunk]
 * changeset:3/trunk
变更集(其它版本库) 
 * [3/repo]
 * changeset:3/repo
 * [3/repo/trunk]
 * changeset:3/repo/trunk
日志(缺省版本库) 
 * r1:3
 * [1:3]
 * [1:3/trunk]
 * [20788,20791:20795/trunk/tools]
 * log:@1:3
 * log:trunk@1:3
 * log:@20788,20791:20795
 * log:/trunk/tools@20788,20791:20795
日志(其它版本库) 
 * [1:3/repo]
 * [1:3/repo/trunk]
 * log:repo@1:3
 * log:repo/trunk@1:3
代码差异 
 * diff:@1:3
 * diff:tags/v1.0/src//tags/v2.0/src
 * diff:trunk/trac@3538//sandbox/vc-refactoring@3539
 * diff:repos/trunk@1:3
里程碑 
 * milestone:"Next Release"
附件 
 * attachment:icon.png
 * [[attachment:icon.png:wiki:TracGuideByOssxp|指定页面的附件]]
 * attachment:freemind_about.png:ticket:18
 * [[attachment:"freemind_about.png:ticket:18"|如果有空格需要加引号]]
搜索 
 * [query:status=new|assigned|reopened&version=1.0
    Active tickets against 1.0]
 * [query:?status=new&status=assigned&status=reopened&group=owner
    Assigned tickets by owner]
Wiki页面 
 * CamelCase
 * wiki:CamelCase
 * wiki:"The whitespace convention"
 * [[..]]
 * [[..|父页面]]
 * [[../Sibling|兄弟页面]]
 * [[#anchor|指向页内链接]]
 * [[/newticket|新建Ticket]]
 * [[/|首页]]
 * [[//HelpCenter/00000_OSSXP|其它网站]]

宏

Trac 原有的宏的语法为 [[宏(参数)]], 该语法是基于老版本的 Moin，和目前大多数Wiki引擎不兼容，也和新版本的 Moin 1.6 之后的版本不兼容。

群英汇仿照 Moin1.6，对 trac 宏的语法进行了改造，现在新的宏的语法为：

  • <<宏>> 或者 <<宏(参数,...)>>

Trac 支持的宏列表

宏帮助示例
<<MiniPage(...)>> 参数中的"\n"字符被替换为换行符，之后用维基语法解析并输出内容。主要用于在不允许换行的表格单元格中输出多行内容。 
<<MiniPage( * list1\n *list2)>>
<<ShowSmileys>> 以表格的形式显示表情符号（例如 ":-)" 显示为 :-) ）。缺省3列显示。 
<<ShowSmileys(4)>>
<<ShowEntities>> 以表格的形式显示 HTML 实体符号（例如 "&sube;" 显示为 ⊆）。缺省3列显示。 
<<ShowEntities(4)>>
<<ShowSymbols>> 以表格的形式显示快捷符号（例如 "(R)" 显示为 ®）。缺省3列显示。 
<<ShowSymbols(4)>>
<<RepositoryIndex>> 显示版本库列表。可以使用 format 参数定制显示输出。缺省以 compact 格式显示，还可以用 list, table 设置为不同显示模式。 
<<RepositoryIndex(format=table)>>
<<TitleIndex>> Wiki 页面列表。参数： 前缀，只显示以此前缀开头的页面 
<<TitleIndex(Trac,format=group,depth=0)>>
<<RecentChanges>>

最新的页面改动。

  • 参数一： 前缀，只显示以此前缀开头页面的修改历史。
  • 参数二：显示的条目数 
<<RecentChanges(Ossxp,5)>>
<<PageOutline>> 显示目录。还可以使用 <<TableOfContents>> 
<<PageOutline>>
<<TableOfContents>> 显示目录。同 <<PageOutline>> 
<<TableOfContents>>
<<Image(...)>> 显示图片 
<<Image(photo.jpg, 120px)>>
<<MacroList>> 显示一个类似本页面的宏帮助列表。 
<<MacroList>>
<<TracIni>> Trac 配置帮助。 
<<TracIni>>
<<TracGuideToc>> 显示一个Trac帮助目录。浮动显示在右侧 
<<TracGuideToc>>
<<TicketQuery>> Ticket查询宏。参见 Trac 的帮助页面 TracQuery 
<<TicketQuery>>
<<TracAdminHelp>> 显示 trac-admin 帮助 
<<TracAdminHelp>>

(!) 可以参考 Trac 本身提供的帮助： WikiMacros

表情符号

(!) 群英汇通过 wikigoodies 插件支持表情符号。可用的表情符号有：

Markup  Display Markup  Display Markup  Display
(!)(!) (./)(./) /!\/!\
:(:( :):) :)):))
:-(:-( :-):-) :-)):-))
:-?:-? :D:D :\:\
:o:o ;);) ;-);-)
<!><!> <:(<:( >:>>:>
B)B) B-)B-) X-(X-(
{!OK}{!OK} {*}{*} {DN}{DN}
{OK}{OK} {P1}{P1} {P2}{P2}
{P3}{P3} {UP}{UP} {X}{X}
{o}{o} {p1}{p1} {p2}{p2}
{p3}{p3} |)|) |-)|-)

时间线 ── 项目最新改动的一网打尽

时间线提供了一个显示近期改动的页面。以日为单位分组，可以显示下列变更事件：

  • Wiki 页面 ── 创建和修改
  • Ticket 事件 ── 创建和修改
  • 源代码修改 ── 代码提交事件
  • 里程碑 ── 里程碑完成

时间线从最近的一次改动开始显示，缺省显示 30 天内（最后一次修改向前推30天）的修改。

  • 变更的起始时间如果空白或者是 *，则表示采用最近一次改动发生的时间 (!) 群英汇扩展： 默认的起始时间是最后一次更新的时间。而trac的原始实现是采用当前时间，可能会导致看不到任何事件。
  • 用户可以自定义显示的日期范围
  • 为了防止对服务器的负担，日期显示范围不能超过配置文件中的预设值。项目的配置文件 trac.ini 中相关设置： 
    [timeline]
default_daysback = 30
max_daysback = 500

时间线的对话框，还提供了多个过滤器设置:

  • 除了对事件的起止时间进行过滤
  • 用户还可以选择只查看四类事件的某一类或者某几类事件
  • 用户还可以选择只查看某个用户发生的事件

路线图 ── 项目进展一目了然

路线图
就是显示一个里程碑列表，每个里程碑都以一个水平条形式显示并标明完成程度。缺省不显示完成的里程碑，可以通过界面上的对话框显示 已经完成的里程碑。
里程碑
是管理员设定的一个名字，用于标识项目的版本或者阶段。在提交 Ticket 时，应该手动指定该 Ticket 属于哪个里程碑。

如何有效使用里程碑?

  1. 如果里程碑一建立就束之高阁，即在创建 ticket 时不设置有效的里程碑，则“里程碑”形同虚设，使用里程碑的效果大打折扣。
  2. 为下一个版本（当前正在开发的版本）设定一个代号，并以该代号创建一个里程碑
    • 如 Debian 的版本代号有 （Woody, Sarge, Etch, Lenny ── 《玩具总动员》中的角色明星）
    • 我们缺省设置了里程碑 “Next Release”，作为缺省的下一个版本代号
  3. 将新建立的里程碑（下一个版本），设置为缺省里程碑。 这样当创建新 Ticket 时，缺省就会选择该里程碑。
  4. 当项目完成后，重新命名里程碑。例如将 “Next Release” 修改为 “Version_2.1”
  5. 标记里程碑为完成，则该里程碑默认不出现在路线图的界面中。
  6. 重复步骤 2─5。

源码浏览

功能列表：

  • 可以提供对多种不同类型的版本控制系统的Web访问界面; 支持： Subversion, Git, Hg, Bazaar 等
  • 一个项目可以同时关联多个版本库；
  • 可以为每个版本库指定缺省字符集；
  • 对于 Subversion 版本库，还可以指定授权配置文件；

(!) 群英汇对版本库浏览所做的主要扩展为：

  • 支持多版本库以及多种类型的版本库（subversion, hg, git），且可以设置库的缺省字符集
  • 可以为每个 subversion 库配置单独的权限控制文件
  • Subversion 授权文件支持最新的语法格式，支持用户组的套用，支持别名，支持 $anonymous, $authenticated 等特殊对象。
  • 配置文件 trac.ini 中关于版本库的配置示例:
    [trac]
...
repository_dir = /svnroot/project1/
repository_type = direct-svnfs
authz_file = /path/to/authz_file
authz_module_name = module_name_1
default_charset = utf-8
direct-svnfs
...

[repositories]
reposname1.dir = /svnroot/project2/
reposname1.type = direct-svnfs
reposname1.authz_file = /path/to/authz_file
reposname1.authz_module_name = module_name_2
reposname1.charset = gbk

reposname2.dir = /hgroot/project2/
reposname2.type = hg

reposname3.dir = /gitroot/project3/.git/
reposname3.type = git

[svn:externals]
1 = svn://server/repos1 http://trac/proj1/browser/$path?rev=$rev
2 = svn://server/repos2 http://trac/proj2/browser/$path?rev=$rev
3 = http://theirserver.org/svn/eng-soft       http://ourserver/viewvc/svn/$path/?pathrev=25914
4 = svn://anotherserver.com/tools_repository  http://ourserver/trac/support/browser/$path?rev=$rev

Ticket 与工作流

Ticket 提供对缺陷(Bugs)和需求的管理。

Ticket 的生命周期，从新ticket (New)，到ticket关闭(closed)。中间经历很多不同的状态，可以对这些状态定义进行修改，以适合本企业自身的工作流。

参见: TracWorkflow

工具整合

EclipseTracPlugin 插件

EclipseTracPlugin 提供在 Eclipse 中编辑 Wiki 页面的功能。参见： http://trac-hacks.org/wiki/EclipseTracPlugin

在 Eclipse 中编辑 Wiki 页面，不必担心数据丢失。因为可以随时本地保存，而本地保存不会提交到服务器，还可以随时预览。当 Wiki 页面编辑完毕后，通过同步操作提交到 trac 服务器。

Eclipse Mylyn

Eclipse Mylyn 提供在 Eclipse 中新建 ticket 和编辑 ticket 的功能。参见： http://wiki.eclipse.org/index.php/Mylyn/User_Guide

在 Eclipse 中管理 ticket：

  • 创建快捷、方便，创建 ticket 无须打开浏览器，因为能够缓存用户名口令，因此无须提供登录信息。
  • 可以在本地为 tickets 设定工作计划，让工作更加有条理。
  • 编辑过程中可以随时保存。保存是在本地进行，编辑满意后，在通过同步上传 trac 服务器。
  • 可获得 ticket 变更的实时通知 ── 定时到服务器中 PULL 最新的 ticket 变更。

TracExplorer 实现与 Trac 与 TSVN 整合

TracExplorer 实现与 TSVN 的整合。在 TSVN 提交代码变更的对话框，可以从 ticket 列表中选择，自动填写到提交说明中。

参考： http://tracexplorer.devjavu.com/