Tracマクロによる仕事に使える厳選マクロと使い方

サイクロンは Trac Wiki による文書作成機能があります。Trac や TracLightning で利用可能な Trac マクロもそのまま利用する事が可能です。
プロジェクトチームの情報共有のために Wiki を活用されているチームもそうでないチームも、Trac マクロを利用する事でプロジェクト運営がぐっと楽になります。
ここでは、仕事に使える厳選マクロとしてご紹介したいと思います。

目次の作成・・・PageOutline マクロ。見出しから目次を自動生成するマクロ
最近の変更一覧・・・RecentChanges マクロ。最近更新された Wiki ページを一覧表示するマクロ
チケット一覧・・・TicketQuery マクロ。チケット一覧を様々な条件で一覧表示するマクロ
Wikiページ一覧・・・TitleIndex マクロ。Wikiページを様々な条件で一覧表示するマクロ
プロジェクト内リンク・・・マイルストーンやリポジトリ、チケット、チェンジセットへの簡単リンク

1. 見出しから目次を生成するマクロ(PageOutline)

TracWikiは文書を作成する上で必要最小限の機能を備えています。ワープロソフトをつかって文書を作成するよりもずっと早く文書を作成することができます。「PageOutline」マクロは作成した文書構造から自動で目次を作成するマクロです。

実際の文書をみたほうが理解しやすいと思います。

[[PageOutline()]]
= ciklone スタートアップガイド =
== 1. はじめに ==
=== 1.1 導入 ===
ciklone(サイクロン) ソフトウェアエンジニアのための、Webベースバグ管理システムです。 本資料では、チーム開発、バグ管理、バージョン管理をキーワードとして、ciklone(サイクロン)をあなたのプロジェクトでうまく導入するための説明をしています。

これまでの経験で、バグ管理、バージョン管理を使ったことがある方もそうでない方も、これからのソフトウェア開発に役立つと考えられる内容にまとめております。
…
=== 1.2 バグ管理の必要性 ===
組込みシステムエンジニアやWebアプリケーションエンジニア、多くのソフトウェア開発に携わる開発者達。 製品開発やシステム開発の現場で「バグ管理」はどのように行っているでしょうか。

ページの目次が自動生成されます。目次はページ内リンクになっているのでクリックすると目的の見出しまでジャンプできます。
Wikiの目次を生成するためには文書に以下のマクロを記述するだけです。

 [[PageOutline()]]

さらに詳しい使い方は、「Wikiマクロを活用する」をご覧ください。

2. 最近更新された Wiki ページを一覧表示するマクロ(RecentChanges)

プロジェクトチームで情報共有する場合やチームのポータルサイトとして Wiki を活用している場合、最近更新された Wiki ページの一覧を表示しておくとよいでしょう。タイムラインと異なり、Wiki だけのページを条件付きで表示することができます。

使い方

 [RecentChanges(tc,5)]]

RecentChanges に引数があります。最初の引数は、「tc」という Wiki の階層ページの下にあるWikiを表示することを意味しています。すべての Wiki ページを指定する場合、最初の引数は何も書きません。

 [RecentChanges(,5)]]

2つめの引数は、最近更新されたページの数です。「5」は過去更新されたページを5個リンクにする、ということを指定しています。タイムラインのように過去の時間に関係なく、最近更新されたページ数を一覧表します。

3. 様々な条件でチケットをレポートするマクロ(TicketQuery)

Trac にはチケットを表示する強力なレポート機能があります。そのレポート機能を Wiki マクロで実現することができます。
使い方によっては、

毎日の作業日報や週報をマクロで簡単に生成
議事録の課題リストやタスクリストを自動生成
自分の作業メモや「やることリスト」パーソナルページ
チームの作業一覧ページ

など、使い方によって毎日の開発作業を効率的にしてくれます。

基本的な使い方「新規開発プロジェクトの自分の担当チケットを一覧表示する」

基本形式：[[TicketQuery(条件式,表示形式,ソート条件)]]

[[TicketQuery(status!=closed&owner=$USER,table,order=serverity)]]

サンプル条件の説明

条件式(第1引数)…チケット属性の英字名を指定します。「=」(同じ)、「!=」(同じではない)が指定可能です。複数の条件は「&」で連結可能です。
表示形式…チケット一覧の表示形式を指定します。表示形式は4種類(list,compact,count,table)があります。
ソート条件…一覧表示されたチケットのソート条件を指定します。「order=」のあとにチケット属性の英字名を指定します。(id,version,status,serverity) サンプルでは優先度でソートしています。

TicketQuery の条件式はクエリ言語といわれる高機能なマクロが利用可能です。上で示した例はよく使う簡単な例ですが
さらに詳しい解説はサイクロンのマニュアルをご確認ください。(https://[あなたのサブドメイン].ciklone.com/-/wiki/TracQuery)

4. 様々な条件で Wiki ページを表示するマクロ(TitleIndex)

単純に Wiki ページの一覧表を作成することができます。特定のカテゴリの Wiki や関連する文書の Wiki ページを埋め込むことができます。
使い方は

 - コンパクトに表示
  [[TitleIndex(tc/Meeting/,format=compact)]]
 - 標準
  [[TitleIndex(tc/Meeting/)]]

5. マイルストーンやチケットにアクセスするためのリンク機能

サイクロンのプロジェクト管理機能で利用している各機能は簡単にリンクを作成することができます。TracLinksと呼ばれるリンク機能は、

ソースコードのコミットメッセージ
Wikiページ
チケット、レポート、マイルストーンでの説明記述箇所

で利用することが可能です。また、プロジェクト内のテキストフィールド内でも利用できます。

Wiki ページ
CamelCase, wiki:CamelCase
親ページ
[..]
チケット
#1, ticket:1
チケットのコメント
comment:1:ticket:2
レポート
{1}, report:1
チェンジセット
r1, [1], changeset:1, (特定パス配下) [1/trunk], changeset:1/trunk
リビジョンログ
r1:3, [1:3], log:@1:3, log:trunk@1:3, [2:5/trunk]
diff
diff:@1:3, diff:tags/trac-0.9.2/wiki-default//tags/trac-0.9.3/wiki-default または diff:trunk/trac@3538//sandbox/vc-refactoring@3539
マイルストーン
milestone:1.0
添付ファイル
attachment:example.tgz (現在のページへの添付ファイル), attachment:attachment.1073.diff:ticket:944 (他のリソースへの添付ファイル)
リポジトリのファイル
source:trunk/COPYING
特定リビジョンのリポジトリのファイル
source:/trunk/COPYING@200
リポジトリのファイルの特定行
source:/trunk/COPYING@200#L25

さらに詳しい解説はサイクロン内のマニュアルを参照してください。（https://[あなたのURL].ciklone.com/-/wiki/TracLinks）
このように少しの学習でとても便利な機能が利用可能です。
ぜひ、ご活用ください。