foozy@708: \chapter{Customising the output of Mercurial}
foozy@708: \label{chap:template}
foozy@708: 
foozy@708: Mercurial は、
foozy@708: 情報表示の体裁を制御する強力な仕組みを提供しています。
foozy@708: この仕組みはテンプレートに基づいており、
foozy@708: テンプレートを使用することで、
foozy@708: 単発のコマンド出力の固有化も、
foozy@708: Mercurial 組み込みのウェブインタフェースの見かけ全体のカスタマイズもできます。
foozy@708: 
foozy@708: \section{Using precanned output styles}
foozy@708: \label{sec:style}
foozy@708: 
foozy@708: Mercurial には即使用できる出力「様式」の幾つかが同梱されています。
foozy@708: 「様式」とは、
foozy@708: 誰かによって書かれて、
foozy@708: Mercurial が探し出せる何処かにインストールされた、
foozy@708: 事前に用意されたテンプレートのことです。
foozy@708: 
foozy@708: Mercurial に同梱された「様式」を見る前に、
foozy@708: Mercurial の標準的な出力を見てみましょう。
foozy@708: 
foozy@708: \interaction{template.simple.normal}
foozy@708: 
foozy@708: この出力は有益ではありますが、
foozy@708: チェンジセット毎に５行という多くの表示領域が必要です
foozy@708: \texttt{compact} 様式は、
foozy@708: 表題等を省くことで、
foozy@708: この出力を３行に低減します。
foozy@708: 
foozy@708: \interaction{template.simple.compact}
foozy@708: 
foozy@708: \texttt{changelog} 様式からは、
foozy@708: Mercurial のテンプレートエンジンの持つ表現力を垣間見ることができます。
foozy@708: この様式は、
foozy@708: GNU プロジェクトの 
foozy@708: changelog ガイドライン\cite{web:changelog}に沿った出力を行います。
foozy@708: 
foozy@708: \interaction{template.simple.changelog}
foozy@708: 
foozy@708: Mercurial の既定出力様式が
foozy@708: \texttt{default} という名前であることを知っても驚くほどのことは無いでしょう。
foozy@708: 
foozy@708: \subsection{Setting a default style}
foozy@708: 
foozy@708: 好みの様式の名前を \hgrc\ ファイルで指定することで、
foozy@708: Mercurial がコマンド実行の際に使用する出力様式を変える事ができます。
foozy@708: 
foozy@708: \begin{codesample2}
foozy@708:   [ui]
foozy@708:   style = compact
foozy@708: \end{codesample2}
foozy@708: 
foozy@708: 自分自身で様式を定義した場合、
foozy@708: 自分の様式ファイルへのパスを指定する方法と、
foozy@708: 自分の様式ファイルを Mercurial が探し出せる場所へコピーする方法
foozy@708: （一般には Mercurial がインストールされたディレクトリ直下の
foozy@708: \texttt{templates} ディレクトリ）のどちらででも、
foozy@708: 自分の様式ファイルを使うことができます。
foozy@708: 
foozy@708: \section{Commands that support styles and templates}
foozy@708: 
foozy@708: ``\texttt{log}的な'' 全ての Mercurial コマンドに対して、
foozy@708: 様式やテンプレートを適用できます。
foozy@708: 例えば、\hgcmd{incoming}、\hgcmd{log}、\hgcmd{outgoing}
foozy@708: および \hgcmd{tip} がそうです\footnote{訳注:
foozy@708: Mercurial 0.9.5 版時点では、これ以外に
foozy@708: \hgcmd{heads} および \hgcmd{parents} 
foozy@708: がテンプレートをサポートしています。}。
foozy@708: 
foozy@708: 筆者がこのマニュアルを執筆している時点では、
foozy@708: 様式やテンプレートに対応しているコマンドは、
foozy@708: それ程多くありません。
foozy@708: しかし、対応済みのコマンドは、
foozy@708: 出力のカスタマイズが必要性が非常に高いコマンド群でしたので、
foozy@708: Mercurial ユーザのコミュニティからは、
foozy@708: 他のコマンドにおける様式やテンプレートへの対応の要望は、
foozy@708: 今のところあまりありません。
foozy@708: 
foozy@708: \section{The basics of templating}
foozy@708: 
foozy@708: Mercurial で言うテンプレートとは、
foozy@708: 大雑把に言うなら一片のテキストです。
foozy@708: 決して変更されない部分がある一方で、
foozy@708: 必要に応じて\emph{展開}や新たなテキストでの置換が実施されます。
foozy@708: 
foozy@708: 詳細を説明する前に、
foozy@708: Mercurial の通常出力の簡単な例をもう一度見てみましょう。
foozy@708: 
foozy@708: \interaction{template.simple.normal}
foozy@708: 
foozy@708: それでは、
foozy@708: 出力を変えるためのテンプレートを指定して、
foozy@708: 同じコマンドを実行してみましょう。
foozy@708: 
foozy@708: \interaction{template.simple.simplest}
foozy@708: 
foozy@708: 上記の例は、可能な限り最も簡単なテンプレートとして、
foozy@708: チェンジセット毎に表示される静的なテキストを指定するだけの例です。
foozy@708: \hgcmd{log} コマンドに対する
foozy@708: \hgopt{log}{--template} オプション指定は、
foozy@708: チェンジセット毎の表示の際に使用するテンプレートとして、
foozy@708: 指定されたテキストを使用することを Mercurial に指示します。
foozy@708: 
foozy@708: 上記のテンプレート文字列は、``\Verb+\n+'' で終了している点に注意してください。
foozy@708: これは\emph{エスケープシーケンス}と呼ばれるもので、
foozy@708: 個々のテンプレート要素の終端で改行を表示することを
foozy@708: Mercurial に指示します。
foozy@708: この改行を省略した場合、
foozy@708: Mercurial は個々の出力要素を単一行で出力します。
foozy@708: エスケープシーケンスに関する詳細は、
foozy@708: \ref{sec:template:escape}~節を参照してください。
foozy@708: 
foozy@708: 常に固定された文字列を表示するテンプレートは、あまり有用とは言えませんので、
foozy@708: もう少し複雑なものに挑戦してみましょう。
foozy@708: 
foozy@708: \interaction{template.simple.simplesub}
foozy@708: 
foozy@708: ご覧の通り、
foozy@708: テンプレート中の ``\Verb+{desc}+'' 文字列は、
foozy@708: チェンジセット毎のログメッセージで置換されて出力されます。
foozy@708: 波括弧（``\texttt{\{}'' 及び ``\texttt{\}}''）
foozy@708: で囲まれたテキストが検出された際には、
foozy@708: どんなテキストが囲まれていた場合でも常に、
foozy@708: 括弧およびテキスト部分の展開が Mercurial により試みられます。
foozy@708: 波括弧そのものを表示したい場合は、
foozy@708: \ref{sec:template:escape}~節で述べる方法で、
foozy@708: 波括弧をエスケープしなければなりません。
foozy@708: 
foozy@708: \section{Common template keywords}
foozy@708: \label{sec:template:keyword}
foozy@708: 
foozy@708: 以下のキーワードを使用することで、
foozy@708: すぐにでも簡単なテンプレートを書くことができます。
foozy@708: 
foozy@708: \begin{description}
foozy@708: 
foozy@708: \item[\tplkword{author}] 文字列。
foozy@708:   チェンジセットの作成者。
foozy@708:   チェンジセット作成後は変更されません。
foozy@708: 
foozy@708: \item[\tplkword{branches}] 文字列。
foozy@708:   チェンジセットがコミットされたブランチの名前。
foozy@708:   ブランチ名が \texttt{default} の場合は空です。
foozy@708: 
foozy@708: \item[\tplkword{date}] 日付情報。
foozy@708:   チェンジセットがコミットされた日時。
foozy@708:   この値は可読性が\emph{ありません}ので、
foozy@708:   適切に文字列化するフィルタに渡す必要があります。
foozy@708:   フィルタに関する詳細は\ref{sec:template:filter}~節を参照してください。
foozy@708:   日時は数値の対として表されます。
foozy@708:   最初の数値は Unix UTC タイムスタンプ（1970 年 1 月 1 日からの経過秒）で、
foozy@708:   ２つ目の数値はコミットの際の UTC からのタイムゾーンオフセット秒数です。
foozy@708: 
foozy@708: \item[\tplkword{desc}] 文字列。
foozy@708:   チェンジセットのログメッセージ。
foozy@708: 
foozy@708: \item[\tplkword{files}] 文字列リスト。
foozy@708:   当該チェンジセットで変更・追加ないし削除された全てのファイル。
foozy@708: 
foozy@708: \item[\tplkword{file\_adds}] 文字列リスト。
foozy@708:   当該チェンジセットで追加されたファイル。
foozy@708: 
foozy@708: \item[\tplkword{file\_dels}] 文字列リスト。
foozy@708:   当該チェンジセットで削除されたファイル。
foozy@708: 
foozy@708: \item[\tplkword{node}] 文字列。
foozy@708:   チェンジセット識別用ハッシュ値を４０文字の１６進数文字列化したもの。
foozy@708: 
foozy@708: \item[\tplkword{parents}] 文字列リスト。
foozy@708:   チェンジセットの親。
foozy@708: 
foozy@708: \item[\tplkword{rev}] 整数値。
foozy@708:   リポジトリローカルなチェンジセットのリビジョン番号。
foozy@708: 
foozy@708: \item[\tplkword{tags}] 文字列リスト。
foozy@708:   当該チェンジセットに関連付けられたタグ。
foozy@708: 
foozy@708: \end{description}
foozy@708: 
foozy@708: 幾つか実験してみることで、
foozy@708: これらのキーワードを使用した際に期待される動作を見ることができます。
foozy@708: 図~\ref{fig:template:keywords}を参照してください。
foozy@708: 
foozy@708: \begin{figure}
foozy@708:   \interaction{template.simple.keywords}
foozy@708:   \caption{Template keywords in use}
foozy@708:   \label{fig:template:keywords}
foozy@708: \end{figure}
foozy@708: 
foozy@708: 前述したように、
foozy@708: \tplkword{date} キーワードは可読性のある出力を生成しませんので、
foozy@708: 特別扱いする必要があります。
foozy@708: そのためには \emph{filter} を使う必要がありますが、
foozy@708: 詳細は \ref{sec:template:filter}~節を参照してください。
foozy@708: 
foozy@708: \interaction{template.simple.datekeyword}
foozy@708: 
foozy@708: \section{Escape sequences}
foozy@708: \label{sec:template:escape}
foozy@708: 
foozy@708: Mercurial のテンプレートエンジンは、
foozy@708: 最も広く使われている文字列エスケープシーケンスを認識します。
foozy@708: バックスラッシュ（``\Verb+\+''）を検知した際には、
foozy@708: それに続く文字を見て、
foozy@708: それら２つの文字を以下に示すような単独の文字に置換します。
foozy@708: 
foozy@708: \begin{description}
foozy@708: \item[\Verb+\textbackslash\textbackslash+] バックスラッシュ（``\Verb+\+''）
foozy@708:   ／ASCII~134。
foozy@708: \item[\Verb+\textbackslash n+] 改行／ASCII~12.
foozy@708: \item[\Verb+\textbackslash r+] 行頭／ASCII~15.
foozy@708: \item[\Verb+\textbackslash t+] タブ／ASCII~11.
foozy@708: \item[\Verb+\textbackslash v+] 垂直タブ／ASCII~13.
foozy@708: \item[\Verb+\textbackslash \{+] 開き波括弧（``\Verb+{+''）／ASCII~173.
foozy@708: \item[\Verb+\textbackslash \}+] 閉じ波括弧（``\Verb+}+''）／ASCII~175.
foozy@708: \end{description}
foozy@708: 
foozy@708: 上記のように、
foozy@708: ``\Verb+\+''、``\Verb+{+'' ないし ``\Verb+{+'' 
foozy@708: そのものを含むテンプレートを使用したい場合、
foozy@708: これらはエスケープされなければなりません。
foozy@708: 
foozy@708: \section{Filtering keywords to change their results}
foozy@708: \label{sec:template:filter}
foozy@708: 
foozy@708: テンプレート展開における結果のうちの幾つかは、
foozy@708: 直ちに使えるほど簡便なものではありません。
foozy@708: Mercurial は、
foozy@708: キーワードの展開結果を変更するために、
foozy@708: 任意の\emph{フィルタ}の連鎖を指定することを求めてきます。
foozy@708: 上記の実行例において既に、
foozy@708: 一般的なフィルタである \tplkwfilt{date}{isodate} を、
foozy@708: 日付を読めるようにするために使用しています。
foozy@708: 
foozy@708: Mercurial がサポートする最も一般的に使用されるフィルタのリストを、
foozy@708: 以下に示します。
foozy@708: 任意のテキストに適用できるフィルタもあれば、
foozy@708: 特定の状況下でのみ適用可能なものもあります。
foozy@708: 個々のフィルタの説明は、名前に続いて利用可能な状況を提示し、
foozy@708: それに効果の説明が続く形式となっています。
foozy@708: 
foozy@708: \begin{description}
foozy@708: \item[\tplfilter{addbreaks}] 任意のテキストに適用可能。
foozy@708:   XHTML の ``\Verb+<br/>+'' タグを、最終行を除く各行の末尾に付与します。
foozy@708:   例えば ``\Verb+foo\nbar+'' は ``\Verb+foo<br/>\nbar+'' となります。
foozy@708: 
foozy@708: \item[\tplkwfilt{date}{age}] \tplkword{date} キーワードに適用可能。
foozy@708:   現在時刻に対する日付の年齢を描画します。
foozy@708:   ``\Verb+10 minutes+'' のような文字列を生成します。
foozy@708: 
foozy@708: \item[\tplfilter{basename}] 任意のテキストに適用可能ですが、
foozy@708:   \tplkword{files} キーワードやその相対値に対して適用するのが最も有用です。
foozy@708:   テキストをパスとして扱い、そのベースネームを返します。
foozy@708:   例えば ``\Verb+foo/bar/baz+'' は ``\Verb+baz+'' となります。
foozy@708: 
foozy@708: \item[\tplkwfilt{date}{date}] \tplkword{date} キーワードに適用可能。
foozy@708:   Unix の \tplkword{date} コマンドと同等のフォーマットで日付を描画しますが、
foozy@708:   タイムゾーンを含みます。
foozy@708:   ``\Verb+Mon Sep 04 15:13:13 2006 -0700+'' のような文字列を生成します。
foozy@708: 
foozy@708: \item[\tplkwfilt{author}{domain}] 任意のテキストに適用可能ですが、
foozy@708:   \tplkword{author} キーワードに対して適用するのが最も有用です。
foozy@708:   電子メールアドレスと思しき最初の文字列を見つけ出し、
foozy@708:   ドメイン部分のみを取り出します。
foozy@708:   例えば ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' は
foozy@708:   ``\Verb+serpentine.com+'' となります。
foozy@708: 
foozy@708: \item[\tplkwfilt{author}{email}] 任意のテキストに適用可能ですが、
foozy@708:   \tplkword{author} キーワードに対して適用するのが最も有用です。
foozy@708:   電子メールアドレスと思しき最初の文字列を見つけ出します。
foozy@708:   例えば ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' は
foozy@708:   ``\Verb+bos@serpentine.com+'' となります。
foozy@708: 
foozy@708: \item[\tplfilter{escape}] 任意のテキストに適用可能。
foozy@708:   XML/XHTML の特殊文字である
foozy@708:   ``\Verb+&+''、``\Verb+<+'' および ``\Verb+>+'' を、
foozy@708:   XML の実体参照形式で置き換えます。
foozy@708: 
foozy@708: \item[\tplfilter{fill68}] 任意のテキストに適用可能。
foozy@708:   テキストを 68 桁に収まるように行を折り返します。
foozy@708:   \tplfilter{tabindent} フィルタ実施後も 
foozy@708:   80 桁の固定フォント幅の画面に収めたい場合、
foozy@708:   \tplfilter{tabindent} フィルタに渡す前のテキストに適用するのが良いでしょう。
foozy@708: 
foozy@708: \item[\tplfilter{fill76}] 任意のテキストに適用可能。
foozy@708:   76 桁に収まるように行を折り返します。
foozy@708: 
foozy@708: \item[\tplfilter{firstline}] 任意のテキストに適用可能。
foozy@708:   テキストの最初の行を、改行等を含まない形式で取り出します。
foozy@708: 
foozy@708: \item[\tplkwfilt{date}{hgdate}] \tplkword{date} キーワードに適用可能。
foozy@708:   可読性のある数値の組として日付を描画します。
foozy@708:   ``\Verb+1157407993 25200+'' のような文字列を生成します。
foozy@708: 
foozy@708: \item[\tplkwfilt{date}{isodate}] \tplkword{date} キーワードに適用可能。
foozy@708:   ISO~8601 形式の文字列として日付を描画します。
foozy@708:   ``\Verb+2006-09-04 15:13:13 -0700+'' のような文字列を生成します。
foozy@708: 
foozy@708: \item[\tplfilter{obfuscate}] 任意のテキストに適用可能ですが、
foozy@708:   \tplkword{author} キーワードに対して適用するのが最も有用です。
foozy@708:   入力テキストに対応する XML 実体参照シーケンスを生成します。
foozy@708:   典型的な電子メールアドレス収集を行うスパムボット
foozy@708:   （spambot）に対する対抗策の１つとして利用可能です。
foozy@708: 
foozy@708: \item[\tplkwfilt{author}{person}] 任意の文字列に適用可能ですが、
foozy@708:   \tplkword{author} キーワードに対して適用するのが最も有用です。
foozy@708:   電子メールアドレスより前の部分を取り出します。
foozy@708:   例えば ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' は
foozy@708:   ``\Verb+Bryan O'Sullivan+'' となります。
foozy@708: 
foozy@708: \item[\tplkwfilt{date}{rfc822date}] \tplkword{date} キーワードに適用可能。
foozy@708:   電子メールヘッダと同じ形式で日付を描画します。
foozy@708:   ``\Verb+Mon, 04 Sep 2006 15:13:13 -0700+'' のような文字列を生成します。
foozy@708: 
foozy@708: \item[\tplkwfilt{node}{short}] チェンジセットハッシュ値に適用可能です。
foozy@708:   チェンジセットハッシュの短縮形式、即ち 12 桁の 16 進文字列を生成します。
foozy@708: 
foozy@708: \item[\tplkwfilt{date}{shortdate}] \tplkword{date} キーワードに適用可能。
foozy@708:   年月日形式で日付を描画します。
foozy@708:   ``\Verb+2006-09-04+'' のような文字列を生成します。
foozy@708: 
foozy@708: \item[\tplfilter{strip}] 任意のテキストに適用可能。
foozy@708:   冒頭ならびに末尾の空白文字を全て除外します。
foozy@708: 
foozy@708: \item[\tplfilter{tabindent}] 任意のテキストに適用可能。
foozy@708:   最初の行を除く全ての行がタブ文字で始まるようにします。
foozy@708: 
foozy@708: \item[\tplfilter{urlescape}] 任意のテキストに適用可能。
foozy@708:   URL 解析の際に``特殊文字''とされる文字をエスケープします。
foozy@708:   例えば \Verb+foo bar+ は \Verb+foo%20bar+ になります。
foozy@708: 
foozy@708: \item[\tplkwfilt{author}{user}] 任意の文字列に適用可能ですが、
foozy@708:   \tplkword{author} キーワードに対して適用するのが最も有用です。
foozy@708:   電子メールアドレスから``ユーザ''部分を取り出します。
foozy@708:   例えば ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' は
foozy@708:   ``\Verb+bos+'' となります。
foozy@708: 
foozy@708: \end{description}
foozy@708: 
foozy@708: \begin{figure}
foozy@708:   \interaction{template.simple.manyfilters}
foozy@708:   \caption{Template filters in action}
foozy@708:   \label{fig:template:filters}
foozy@708: \end{figure}
foozy@708: 
foozy@708: \begin{note}
foozy@708:   適用対象外のデータに対してフィルタの適用を試みた場合、
foozy@708:   Mercurial は実行に失敗して Python の例外を表示します。
foozy@708:   例えば、\tplkword{desc} キーワードに
foozy@708:   \tplkwfilt{date}{isodate} フィルタを適用するのはよろしくありません。
foozy@708: \end{note}
foozy@708: 
foozy@708: \subsection{Combining filters}
foozy@708: 
foozy@708: 所定の形式での出力を得るために、
foozy@708: 簡単にフィルタを組み合わせることができます。
foozy@708: 以下の例では、ログメッセージの冒頭・末尾の空白を除外し、
foozy@708: 68 桁に収まるように改行した後で、
foozy@708: さらに８文字分（タブ文字が慣習的に８文字として扱われる
foozy@708: Unix 的な環境では）の字下げが、
foozy@708: フィルタ連鎖により実施されます。
foozy@708: 
foozy@708: \interaction{template.simple.combine}
foozy@708: 
foozy@708: テンプレートにおける``\Verb+\t+''（タブ文字）の利用は、
foozy@708: 最初の行の強制的な字下げを行うためのものであることに注意してください。
foozy@708: \tplkword{tabindent} が最初の行\emph{以外の}全ての行を字下げするために、
foozy@708: このタブ文字が必要です。
foozy@708: 
foozy@708: 連鎖におけるフィルタの順序が重要である点に留意してください。
foozy@708: 最初のフィルタがキーワードの置換結果に適用され、
foozy@708: ２つ目のフィルタが最初のフィルタの適用結果に適用される、
foozy@708: という具合です。
foozy@708: 例えば、
foozy@708: \Verb+fill68|tabindent+ という記述は
foozy@708: \Verb+tabindent|fill68+ とは全く違った結果となります。
foozy@708: 
foozy@708: \section{From templates to styles}
foozy@708: 
foozy@708: コマンド行でのテンプレート指定は、
foozy@708: 手早く簡単に出力を整形する手段を提供します。
foozy@708: しかし、テンプレートは冗長に成りがちですから、
foozy@708: テンプレートに名前付けできれば便利になります。
foozy@708: 様式（sytle）ファイルは、名前が付けられ、
foozy@708: ファイルに保存されたテンプレートのことです。
foozy@708: 
foozy@708: それ以上に、
foozy@708: コマンド行での \hgopt{log}{--template} オプション使用では引き出せなかった
foozy@708: Mercurial のテンプレートエンジンの能力を、
foozy@708: 様式ファイルを用いることで引き出すことができます。
foozy@708: 
foozy@708: \subsection{The simplest of style files}
foozy@708: 
foozy@708: 以下に示す簡単な様式ファイルは、
foozy@708: １行だけのものです。
foozy@708: 
foozy@708: \interaction{template.simple.rev}
foozy@708: 
foozy@708: この様式記述は、
foozy@708: ``チェンジセットを表示する際には、
foozy@708: 右辺のテキストをテンプレートとして使用せよ''
foozy@708: と Mercurial に指示します。
foozy@708: 
foozy@708: \subsection{Style file syntax}
foozy@708: 
foozy@708: 様式ファイルの文法は簡単です。
foozy@708: 
foozy@708: \begin{itemize}
foozy@708: \item ファイルは一行づつ処理されます。
foozy@708: 
foozy@708: \item 行頭および行末の空白は無視されます。
foozy@708: 
foozy@708: \item 空行は読み飛ばされます。
foozy@708: 
foozy@708: \item ``\texttt{\#}'' ないし ``\texttt{;}'' のいずれかで始まる行は、
foozy@708:   行全体がコメントとみなされ、空行と同様に読み飛ばされます。
foozy@708: 
foozy@708: \item 行はキーワードで開始されます。
foozy@708:   キーワードは英字ないし下線（underscore）で開始され、
foozy@708:   任意個数の英数字ないし下線が続きます
foozy@708:   （正規表現で書くなら、
foozy@708:   キーワードは ``\Verb+[A-Za-z_][A-Za-z0-9_]*+.'' 
foozy@708:   に合致しなければなりません）。
foozy@708: 
foozy@708: \item キーワードに続く要素は文字 ``\texttt{=}'' でなければなりませんが、
foozy@708:   前後に任意個の空白文字があっても構いません。
foozy@708: 
foozy@708: \item 行の残り部分が引用符（シングルクォートないしダブルクォート）
foozy@708:   で囲まれている場合、
foozy@708:   その部分はテンプレートの本体とみなされます。
foozy@708: 
foozy@708: \item 行の乗り部分が引用符で囲まれて\emph{いない}場合、
foozy@708:   その部分は、
foozy@708:   テンプレート本体を内容として持つファイルのファイル名とみなされます。
foozy@708: 
foozy@708: \end{itemize}
foozy@708: 
foozy@708: \section{Style files by example}
foozy@708: 
foozy@708: 様式ファイルの記述を説明するために、
foozy@708: 幾つかの例を示します。
foozy@708: 様式ファイル一式を通して読むよりも、
foozy@708: 非所に簡単な例から始めて、
foozy@708: 幾つかの複雑な例を通し読みすることで、
foozy@708: 通常の様式ファイル作成手順を示そうと思います。
foozy@708: 
foozy@708: \subsection{Identifying mistakes in style files}
foozy@708: 
foozy@708: 様式ファイル中に問題があった場合、
foozy@708: Mercurial はそっけないエラーメッセージを表示しますが、
foozy@708: 意味するところがわかってしまえば、
foozy@708: そのメッセージは非常に有用です。
foozy@708: 
foozy@708: \interaction{template.svnstyle.syntax.input}
foozy@708: 
foozy@708: \filename{broken.style} は、
foozy@708: \texttt{changeset} キーワードを定義しようとしているものの、
foozy@708: その内容が記述されていない点に注目してください。
foozy@708: このような様式ファイルが指定された場合、
foozy@708: Mercurial は即座にメッセージを表示します。
foozy@708: 
foozy@708: \interaction{template.svnstyle.syntax.error}
foozy@708: 
foozy@708: このメッセージは威圧的に見えますが、
foozy@708: 読み解くのはそれほど難しくありません。
foozy@708: 
foozy@708: \begin{itemize}
foozy@708: \item 最初の要素は、単に Mercurial が``実行をあきらめました''
foozy@708:   と通知しています。
foozy@708:   \begin{codesample4}
foozy@708:     \textbf{abort:} broken.style:1: parse error
foozy@708:   \end{codesample4}
foozy@708: 
foozy@708: \item 次の要素は、エラーの要因が格納された様式ファイルの名前です。
foozy@708:   \begin{codesample4}
foozy@708:     abort: \textbf{broken.style}:1: parse error
foozy@708:   \end{codesample4}
foozy@708: 
foozy@708: \item ファイル名の次は、エラーが発生した行番号になります。
foozy@708:   \begin{codesample4}
foozy@708:     abort: broken.style:\textbf{1}: parse error
foozy@708:   \end{codesample4}
foozy@708: 
foozy@708: \item 最後に、問題の説明が記述されます。
foozy@708:   \begin{codesample4}
foozy@708:     abort: broken.style:1: \textbf{parse error}
foozy@708:   \end{codesample4}
foozy@708:   問題の説明は（この例のように）常に明確であるとは限りませんが、
foozy@708:   暗号めいたものであったとしても、
foozy@708:   様式ファイル中の問題となる行を目視確認して間違いを見つける上では、
foozy@708:   殆どの場合は取るに足らない説明です。
foozy@708: 
foozy@708: \end{itemize}
foozy@708: 
foozy@708: \subsection{Uniquely identifying a repository}
foozy@708: 
foozy@708: 短い文字列を識別子として
foozy@708: Mercurial リポジトリを``概ね一意に''識別\footnote{訳注:
foozy@708: ここで言う「リポジトリの識別」は、
foozy@708: むしろ「プロジェクトの識別」に近いニュアンスと思われます。
foozy@708: }したい場合、
foozy@708: リポジトリの最初のリビジョンを使用するのが良いでしょう。
foozy@708: 
foozy@708: \interaction{template.svnstyle.id} 
foozy@708: 
foozy@708: この値は一意であることが保証されていませんが、
foozy@708: それでも多くの場合において有用です。
foozy@708: 
foozy@708: \begin{itemize}
foozy@708: \item 完全に空のリポジトリではリビジョン~0が存在しないため、
foozy@708:   この方法は機能しません。
foozy@708: 
foozy@708: \item 以前は別々だった複数のリポジトリをマージしたものと、
foozy@708:   マージ前のリポジトリを併用している場合
foozy@708:   （このような事態は非常に稀ではありますが）、
foozy@708:   それらのリポジトリの間では、
foozy@708:   この方法による識別は機能しません。
foozy@708: 
foozy@708: \end{itemize}
foozy@708: 
foozy@708: リポジトリ識別子の利用例を以下に示します。
foozy@708: 
foozy@708: \begin{itemize}
foozy@708: \item サーバ上のリポジトリを管理しているデータベースでの、
foozy@708:   テーブルにおけるキーとしての使用
foozy@708: 
foozy@708: \item \{\emph{リポジトリ識別子}, \emph{リビジョン識別子}\} 
foozy@708:   というタプルの一部としての使用。
foozy@708:   ビルドや他の自動化された処理を実施する際に、
foozy@708:   このタプル情報を保存しておくことで、
foozy@708:   後に処理を``再現''することが可能です。
foozy@708: 
foozy@708: \end{itemize}
foozy@708: 
foozy@708: \subsection{Mimicking Subversion's output}
foozy@708: 
foozy@708: 例えば Subversion のような、
foozy@708: 他の構成管理ツールのデフォルト出力形式をまねてみましょう。
foozy@708: 
foozy@708: \interaction{template.svnstyle.short}
foozy@708: 
foozy@708: Subversion の出力様式はかなり単純ですので、
foozy@708: 出力内容をファイルに保存し、
foozy@708: 出力テキスト中で Subversion により（動的に）生成される部分を、
foozy@708: 展開されるテンプレート値\footnote{訳注： キーワードのこと？
foozy@708: }で置き換えるのは容易でしょう。
foozy@708: 
foozy@708: \interaction{template.svnstyle.template}
foozy@708: 
foozy@708: このテンプレートによる出力が、
foozy@708: Subversion により生成される出力様式から逸脱する場合\footnote{
foozy@708: 訳注： ``a few small ways'' よりは ``a few small point'' で、
foozy@708: 「逸脱する箇所」の方が良くないか？}が幾つかあります。
foozy@708: 
foozy@708: \begin{itemize}
foozy@708: \item Subversion は、``可読性のある''日付
foozy@708:   （上記の出力例における ``\texttt{Wed, 27 Sep 2006}''）
foozy@708:   を丸括弧の中に表示します。
foozy@708:   Mercurial のテンプレートエンジンは、
foozy@708:   時刻とタイムゾーンの無いこの形式で日付を表示する手段を提供していません。
foozy@708: 
foozy@708: \item テンプレート末尾に
foozy@708:   ``\texttt{-}''文字を一杯に使った行の表示を配置することで
foozy@708:   Subversion の``分離''線をまねています。
foozy@708:   Subversion の出力に似せるため、
foozy@708:   出力の最初の分離線表示には、
foozy@708:   テンプレートエンジンの
foozy@708:   \tplkword{header} キーワードを使用しています（後述します）。\footnote{
foozy@708:   訳注：これは deviate な点ではない気が… }
foozy@708: 
foozy@708: \item Subversion の出力は、
foozy@708:   ヘッダ部にコミットメッセージの行数が表示されます。
foozy@708:   Mercurial ではこれに相当する情報を表示することができません。
foozy@708:   処理対象となるデータの行数を数え上げるフィルタを、
foozy@708:   テンプレートエンジンが現時点では提供していないためです。
foozy@708: 
foozy@708: \end{itemize}
foozy@708: 
foozy@708: Subversion の出力例を元に、
foozy@708: 上記テンプレートのようなキーワード・フィルタへの置き換えを行う作業は、
foozy@708: せいぜいが１〜２分で済む作業です。
foozy@708: 様式ファイルは、単にこのテンプレートを参照すれば良いのです。
foozy@708: 
foozy@708: \interaction{template.svnstyle.style}
foozy@708: 
foozy@708: テンプレートファイルテキストを様式ファイルで直接設定するには、
foozy@708: 引用符で囲み、改行文字を ``\texttt{\\n}'' で置き換えれば良いのですが、
foozy@708: 様式ファイルを非常に読み難くしてしまいます。
foozy@708: テンプレートを様式ファイルに直接記述するか、
foozy@708: テンプレートファイルに記述したものを様式ファイルから参照するかを決める際には、
foozy@708: 可読性を基準とするのが良いでしょう。
foozy@708: 様式ファイルの大きさや複雑さが高まる場合は、
foozy@708: テンプレートテキストを記述するのではなく、
foozy@708: 外部ファイルに出してしまいましょう。
foozy@708: 
foozy@708: %%% Local Variables: 
foozy@708: %%% mode: latex
foozy@708: %%% TeX-master: "00book"
foozy@708: %%% End: