Gentoo Logo

Gentoo Linux XML ガイド

目次:

1.  GuideXMLの基本方針

GuideXMLの設計目標

このガイドXML構文は軽快で表現に富み、その結果として学習することは容易で、 さらにWebドキュメンテーションの作成に私たちが必要とする特性をすべて提供します。 タグの数は(私たちが必要とする)最小限に抑えられていますこれにより、 ガイドをDocBook XML/SGMLあるいはWebに対応するHTMLのような他のフォーマットに容易に置き換えられます。

このドキュメントのゴールはGuideXMLドキュメントの作成および変換を容易にすることです。

さらなるリソース

もし、Gentooへドキュメントを寄稿しようと計画していたり、GuideXMLをテストしたいと考えているなら、 ドキュメント作成のための助言やコツを集めた Tips and Tricks (訳注:日本語訳) をお読みください。

このドキュメントを読みながらXMLソースをXML sourceみてみても構いませんよ。

2.  GuideXML

基本構造

GuideXMLの構文の勉強を始めましょう。GuideXMLドキュメントの中で使われている冒頭タグから始める事にしましょう:

コード表示 2.1: The initial part of a guide XML document

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header$ -->

<guide link="/doc/en/guide.xml" lang="en">
<title>Gentoo Documentation Guide</title>

<author title="Author">
  <mail link="yourname@gentoo.org">Your Name</mail>
</author>

<abstract>
このガイドは、新しいGentoo GuideXMLの簡易な構文を使用して、
Webドキュメンテーションを構成する方法をあなたに示します。この構文はGentooLinuxドキュメンテーションのための公式フォーマットです。
また、このドキュメントはそれ自身GudeXMLを使用して作成されました。
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>1.0</version>
<date>2004-12-25</date>

一番上の行には、これがXMLドキュメントであると認識されるために必要なタグがあり、そのDTDも指定しています。 <!-- $Header$ --> 行はCVSサーバーにより自動的に変換され、 リビジョン管理に使われますそれに続いて、<guide>タグがありますが、 ガイド・ドキュメント全体は<guide> </guide>のペアで囲まれます。
link 属性はオプションです。ファイル名単独でも機能しますが、ドキュメントルールへの相対パスよりも絶対パスのほうが望ましいです。 これはドキュメントの印刷用バージョンへのリンクと翻訳が最新かどうかのチェックにだけ使われます。 XSLの後方にあるエンジンからXSLスタイルシートには実際のパスが渡されます。 リンク属性はXMLが他の手段により処理される際のフォールバックとしてだけ使われます。
lang属性はドキュメントの言語を指定するために使われます。これは指定された言語での"Note", "Content"などの日付や挿入する文字列のフォーマットに使われます。デフォルトは英語です。

次に、<title>タグがあり、ガイド・ドキュメント全体のタイトルをセットするのに使用されています。

その後、<author>タグに行き当たります。 これらはドキュメントの著者などに関する情報を含んでいます。 各<author>タグにはオプションのtitleエレメントの記述が可能で、著者のドキュメントとの関係(Author、Co-author、Editorなど)を特定するために使用されます。 この例では、著者の名前は<mail>タグという別のタグで囲まれています。 これはこの人のためのメールアドレスを指定するために使用されています。 <mail>タグはオプションであり省略することができます。 そして<author>エレメントはガイド・ドキュメントにつき最低1つ必要です。

さらに、<abstract><version>および<date>などのタグに行き当たります。 これらはドキュメント要約、現行版のバージョンおよび現行版の日付(YYYY-MM-DDフォーマットで)をそれぞれ指定するために使用されています。 日付が正しくない、またはYYYY-MM-DDフォーマットでなければ、表示されるドキュメントにはそのままの形で現れます

この要約に必要なタグ類はガイド・ドキュメントの冒頭になければいけません。 さらに<title><mail> タグは<guide> の直後以外には置くことはできず、 また、一貫性という点では(必ずではありませんが)ドキュメントの内容が書かれる前に、これらのタグ類が現われることが推奨されます。

最後にDocumentation Policyによって求められるCreative Commons - Attribution / Share Alikeライセンスの下でドキュメントを出版するために使用されている<license/>タグあります。

章と節

一旦冒頭のタグが指定されたら、ドキュメントの構造化要素を追加する準備ができています。 ガイド・ドキュメントはいくつかの章に分割されます。また、各章は一つ以上の節を設けることができます。 すべての章および節にはタイトルが1つあります。ここに例として、一つの段落から成る単一の節をもつ章があるものとします。 このXMLを先程抜粋したXMLに追加して、 のファイルの末尾に</guide>をを追加すれば、(最小限の内容ではありますが)有効なガイド・ドキュメントの完成です:

コード表示 2.2: 最小限の例

<chapter>
<title>自分で作成した章</title>
<section>
<title>これは私が書いた節です</title>
<body>

<p>
ここに実際にこの節でのテキスト内容を記述します。
</p>

</body>
</section>
</chapter>

上記では、私は<chapter>要素に子要素である<title>要素を加えて章タイトルを設定しました。 その後、私は<section>要素を加えることにより節を作成しました。<section>要素の内側を見ると、 それが<title>および<body>の2つの子要素を持っていることを理解して頂けると思います。 <title>に目新しいものはありませんが、<body>については、この節の実際のテキスト内容を含んでいます。 <body>要素内で使用できるタグをすぐあとに紹介します。

注意: <guide>要素は必ず少なくとも1つ<chapter>要素を含んでいなければいけません。<chapter> は必ず少なくとも1つ <section>要素を含んでいなければいけません。そして<section>要素は必ず少なくとも1つ<body>要素を含んでいなければいけません。

<body>の例

さてここからは、実際の内容をマークアップする方法を学習しましょう。以下は、<body>要素のためのXMLコードの例です。

コード表示 2.3: body要素の例

<p>
これはひとつの段落です。<path>/etc/passwd</path> はファイルです。<uri>http://forums.gentoo.org</uri> はお気に入りのウェブサイトです。<c>ls</c>と打つのはご自由に。私は<e>本当に</e> 眠いんです。</p>

<pre caption="コードサンプル">
これは出力結果かコードのテキストです。# <i>これはユーザーの入力です</i>

ある部分を選択して強調することで、HTML/XMLをより読みやすくしてください:
<foo><i>bar</i></foo>

<comment>(これはコード・ブロックにインラインの注記を挿入する方法です)</comment>
</pre>

<note>
これは注記です。</note>

<warn>
これは警告です。</warn>

<impo>
これは重要項目です。</impo>

上の<body>要素がどのように表示されるか見てみましょう:

これは一つの段落です。/etc/passwd はファイルです。 http://forums.gentoo.org お気に入りのウェブサイトです。ls と打つのはご自由に私は本当に眠いんです。

コード表示 2.4: コードサンプル

これは出力結果かコードのテキストです。# これはユーザーの入力です

ある部分を選択して強調することで、HTML/XMLをより読みやすくしてください:
<foo>bar</foo>

(これはコード・ブロックにインラインの注記を挿入する方法です)

注意: これは注記です。

警告: これは警告です。

重要: これは重要項目です。

<body> タグ

私たちは前の節で多くの新しいタグを紹介しました。次のことを覚えておいてください。 <p>(段落:パラグラフ)、<pre>(コード・ブロック)、 <note>(訳注:注意)、<warn>(警告)および<impo>(重要)タグはすべてテキストを1以上行含むことができます。 <table><ul><ol><dl> 要素(すぐに説明します)を加えた、これらのタグ以外のものが<body>要素内に最初に現れてはいけません。 また別な事柄として、これらのタグを積み重ねてはいけません。 言いかえると <note>要素を<p>要素の内部に置いてはいけない、ということです。 ご推察のように、<pre>要素はコードの抜粋には都合が良く、その余白を正確に保持します。 <pre>タグにはcaption属性で名称をつけなければいけません:

コード表示 2.5: 名称がついた <pre>

<pre caption="Output of uptime">
# <i>uptime</i>
16:50:47 up 164 days,  2:06,  5 users,  load average: 0.23, 0.20, 0.25
</pre>

題辞

Delegates from the original 13 states formed the Contented Congress. Thomas Jefferson, a Virgin, and Benjamin Franklin were two singers of the Declaration of Independence. Franklin discovered electricity by rubbing two cats backwards and declared, "A horse divided against itself cannot stand." Franklin died in 1790 and is still dead. (訳注: これはジョークですので原文のままにしておきます。)

—Anonymous student

題辞は章にどういった事柄が書かれているのか、章の最初に説明するのに使われます. 題辞は簡単な段落で、署名を含むby属性です

コード表示 2.6: 短い題辞

<p by="Anonymous student">
Delegates from the original 13 states formed the...
</p>

<path>, <c>, <b>, <e>, <sub> and <sup>

<path><c><b><e><sub><sup>要素は<body>タグの<pre>以外のいずれの子要素のなかで使うことができます

<path>要素はディスク上のファイルを参照するテキストを目立たせるために使用されます。これらは絶対パスまたは相対パス、あるいは単なるファイル名で示されます。 この要素は一般的に、標準の段落の中で目立たせるために等幅フォントで表示されます。

<c>要素はコマンドあるいはユーザ入力を目立たせるために使用されます。 <c>については、読み手に何らかの結果を伴う入力が促されていることを警告する方法だと考えてください。 例えば、このドキュメントに表示されたXMLタグはすべて、<c>エレメントで囲まれます。 なぜなら、それらはユーザが入力することができるものを表わすのであって、パスを記載するときには使わないからです。 <c>要素の使用によって、読者がそれらが入力する必要のあるコマンドであると言うことを素早く識別する手助けになるでしょう。 さらに、<c>エレメントは、もともと通常のテキストとは違うフォントで表示されるようになっているわけですから、 ダブルクォートでユーザ入力を囲んだりする必要がほとんどないというわけです。 例えば、"<c>"要素などと書いているような注目のさせかたは必要ないのです。 不必要なダブルクォートの使用の回避はドキュメントをより判読可能しやすくします!

お気づきかもしれませんが、<b> はテキストをボールドにするのに使われます。

<e>は単語か句に強調を適用するために使用されます。 たとえば私は、私はセミコロンの方を多く使うべきだと本当に思います。ご覧のように、このテキストは通常の段落のフォントより目立ちます。これは、あなたの文をキリッと引き締めることをサポートします!

<sub><sup> 要素は下付き文字上付き文字を指定するために使われます。

コード例と色付けの例

コードサンプルの読みさすさを上げるために<pre> ブロックの内側で次のタグが使えます:

<i>
ユーザー入力と表示テキストを区別します
<comment>
後に続くアクションに関連するコメント
<keyword>
コードサンプルのなかで使われている言語でのキーワードを表示します
<ident>
識別子に使われます
<const>
定数に使われます
<stmt>
ステートメントに使われます
<var>
変数に使われます

注意: <pre>内の前後の空白と改行は表示htmlページに現れることを忘れないでください

色付き <pre> ブロックの例:

コード表示 2.7: My first ebuild

# Copyright 1999-2006 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $

DESCRIPTION="Exuberant ctags generates tags files for quick source navigation"
HOMEPAGE="http://ctags.sourceforge.net"
SRC_URI="mirror://sourceforge/ctags/${P}.tar.gz"

LICENSE="GPL-2"
SLOT="0"
KEYWORDS="~mips ~sparc ~x86"
IUSE=""

src_compile() {
    econf --with-posix-regex || die "econf failed"
    emake || die "emake failed"
}

src_install() {
    make DESTDIR="${D}" install || die "install failed"

    dodoc FAQ NEWS README
    dohtml EXTENDING.html ctags.html
}

<mail>および<uri>

私たちはこれまでにいくつか<mail>タグを見てきました。 それはあるテキストを特別のメールアドレスとリンクするために使用され、<mail link="foo@bar.com">Mr. Foo Bar</mail>の形式をとります。もし、メールアドレスを表示するためには、<mail>foo.bar@example.com</mail>と書いてください。これはfoo.bar@example.comと表示されます。

短い形式ではGentoo開発者の名前とメールアドレスを使うのはより簡単になります。 <mail>neysx</mail><mail link="neysx"/>のどちらでもXavier Neysと表示されます。もし開発者のフルネームではないものを使いたい場合は2番目の形式をつかってください。 たとえば開発者のファーストネームの場合: <mail link="neysx">Xavier</mail> は Xavierと表示されます。
もし、開発者の名前に、キーボードで打てない「おかしな」文字が入っている場合に|特に|!役に立ちます。

<uri> タグははインターネット上のファイル/ロケーションを指定するために使用されます。 このタグには二つの使われ方があり、一つめは、例えばhttp://www.gentoo.orgへリンクするこのテキストのように、テキストそのものに実際のURIを表示したい場合です。 このリンクを作成するためには<uri>http://www.gentoo.org</uri>と入力します。 もう一つは、たとえばGentoo Linux ウェブサイトのように、 あるURIを他のテキストに関連づけしたい場合です。 このリンクを作成するためには<uri link="http://www.gentoo.org">Gentoo Lin|!b|ux ウェブサイト</uri>と入力します。 Gentoo Webサイトの他の場所へリンクするのにhttp://www.gentoo.org/を書く必要はありません。 たとえば、documentation main indexへのリンクは、 単純に<uri link="/doc/en/index.xml">documentation main index</uri>としてください。 ディレクトリインデックスにリンクするときには、index.xmlを省略することができます。 つまり <uri link="/doc/en/">documentation main index</uri>と書けます。 最後のスラッシュを残しておくと余計なHTTPリクエストが省けます。

mailto:の場合に<uri> タグをlink 属性とともに使わないでくださいこの場合は、<mail> タグを使ってください。

W3Cの推奨どおり、ここをクリックしてくださいシンドロームは避けてください。

では、ドキュメントに図を挿入する方法を紹介しましょう。 <figure link="mygfx.png" short="私の写真" caption="いつの時も私の大好きな写真"/> link=属性は実際のグラフィックのイメージを指します。short=属性には短い説明(今回は画像にHTMLのalt=属性を付けるために使用されています)やキャプションを指定します。それほど難しくありません:) さらに、私たちは標準のHTMLスタイルのキャプションや境界のないイメージを加えるために<img src="foo.gif"/>タグをサポートします。

ガイドXMLはHTML構文より簡潔な表構文をサポートしています。 表を始めるには、<table>タグを使います。行データを開始するには<tr>タグを使います。 しかしながら、実際の表のデータを挿入するために、HTMLでいうところの<td>タグはサポートしていません。 そのかわり、見出しを入れたい時には<th>を使い、通常の情報ブロックには<ti>を使います。 <ti>を使えるところならば<th>を使うことができます。 <th>エレメントが必ず最初の列になければいけないとうことはありません。

さらに、表のヘッダー(<th>) と表の項目(<ti>) の両方で項目の横、縦、もしくはその両方の幅に関するcolspanrowspan 属性をつけることができます

さらに表のセル (<ti> & <th>) はalign属性で左寄せ、右寄せ、中央寄せが変わります。

このタイトルは4列分の幅です。
このタイトルは6行分です 項目 A1 項目 A2 項目 A3
項目 B1 2x2 ブロックタイトル
項目 C1
項目 D1..D3
項目 E1..F1 項目 E2..E3
項目 F2..F3

リスト

番号付きリストあるいは番号無しリストを作成するためには、 XHTMLスタイルと同じ<ol>, <ul><li>タグを使用してください。 リストは<body><li>タグの内側にだけ置くことができます。 つまりリストの入れ子ができます。XMLを書いていて、HTMLとは異なりlistの要素も含めて、タグを閉じることを忘れないでください

定義リスト(<dl>)もサポートされています定義語タグ(<dt>) も定義データタグ (<dd>) のどちらも段落や警告などの他のブロックレベルタグを受け付けないことに注意してください。 一組の定義リストはつぎのように構成されます:

<dl>
定義リスト(Definition List)タグが含むのは
<dt>
定義語(Definition Term)タグと
<dd>
定義データ(Definition Data)タグのペアです。

次のリストは w3.org から転載したもので、番号付き、番号なしリストを定義リストに含めることができることを示しています。しかし、他の定義リストを含めることはできません

材料:
  • 小麦粉100g
  • 砂糖10g
  • 水1カップ
  • 卵2個
  • 塩、コショウ
作り方:
  1. 乾いている材料をじっくり混ぜてください
  2. 水分のある材料を入れてください
  3. 10分間混ぜてください
  4. 300度で1時間焼いてください
もう一手間:
レシピにレーズンを加えることで一層おいしくなります

ドキュメント内部での参照

ガイドXMLでは、ハイパーリンクを使用して簡単にドキュメントの他の部分への参照ができます。 第1章を指すリンクは<uri link="#doc_chap1">第1章</uri> のように入力して作成できます。 第1章2節を指し示すためには、<uri link="#doc_chap1 _sect2">第1章2節</uri>と入力します。 図1.3を参照するためには、<uri link="#doc_chap1_fig3">図 1.3</uri>と入力します。 また、コードリスト2.2を参照するには、<uri link ="#doc_chap2_pre2">コードリスト2.2</uri>と入力します。

しかしながら、しばしば変更がありこうした"数え方"が使われているガイドではリンク切れを誘発することがあります。 これに対処するために<chapter><section>id属性を使って名前を定義する事ができ、次のようにしてその属性を指します:

コード表示 2.8: id属性の使用

<chapter id="foo">
<title>ここはfooです!</title>
...
<p>
さらなる情報は<uri link="#foo">fooの章</uri>で見つかります。
</p>

免責事項と無効(obsolete)ドキュメント

disclaimer 属性はガイドとハンドブックに適用でき、事前に定めた免責事項をドキュメントの先頭に表示します。 使用可能なdisclaimerは次のとおりです。

  • articles再公開に使われます
  • draft はドキュメントがまだ作業中で公式なものにはなっていないことを意味します
  • oldbook は現在メンテナンスされていない古いハンドブックに使われます
  • obsolete はドキュメントが無効(obosolete)であることを示すため使われます

ドキュメントが無効であるとなった場合、新しいバージョンへのリンクを追加する必要がでてくるかもしれません。 そのときはredirect 属性を使ってください。ユーザーは自動的に新しいページにリダイレクトされるかもしれませんが、 その振る舞いには依存しないでください。

コード表示 2.9: 免責事項の例

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header$ -->

<guide disclaimer="obsolete" redirect="/doc/en/handbook/handbook-x86.xml">
<title>Gentoo x86 Installation Guide</title>

<author title="Author">
...

FAQ

FAQドキュメントは質問とその回答へのリンクのリストから始める必要があります。 しかし、そういったリストを作るのは、時間がかかり、間違いをしやすいものです。 faqindex要素をドキュメントの最初の章で使うことで、このリストを自動的に作ることができます。 この要素は導入テキストを書けるchapterと同じ構造をもっています。 FAQドキュメントの構造は(少なくとも1つの)章に分けられ、章には複数の節があります。 各節にはtitleで指定されbodyに回答が書かれた質問が1つ置かれます。 章ごとに1つの節が1つの質問としてリンクされ表示されます。

FAQそのソース を見てもらえれば、上に書いたことはすぐ分かると思います。

3.  Handbookのフォーマット

Guide 対 Book

Installation Instructions(訳注:日本語訳)のような、量の多いドキュメントについては、 より幅広いフォーマットが求められました。 我々はモジュール形式で複数のページに渡る文書が書けるような、GuideXML互換の強化版を設計しました。

メインファイル

最初の変更は「マスター」ドキュメントの必要性です。 このドキュメントは実際の内容は含みませんが、ここのドキュメントモジュールにリンクを張ります。 文法はGuideXMLとほとんど違いはありません:

コード表示 3.1: book使用の例

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE book SYSTEM "/dtd/book.dtd">
<!-- $Header$ -->

<book>
<title>book使用の例</title>

<author...>
  ...
</author>

<abstract>
  ...
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>...</version>
<date>...</date>

(<guide> タグの代わりに<book>を使う以外に)実際の違いはありません。 個別の<chapter>で始まるのではなく<part>を定めます。これはbookのなかの個別のパートに相当します:

コード表示 3.2: パートの定義

<part>
<title>パート1</title>
<abstract>
  ...
</abstract>

(いくつか章を定める)
</part>

それぞれのパートには<title><abstract>があり、そのパートへのちょっとした導入部になります。

各パートの内部で、個別に<chapter>を定めます。 それぞれの章は独立したドキュメントでなければなりません。 そのため、特別なタグ(<include>)により、個別のドキュメントを読み込めるのは驚くにはあたりません。

コード表示 3.3: 章の定義

<chapter>
<title>第一章</title>

  <include href="path/to/chapter-one.xml"/>

</chapter>

個々の章を定める

個々の章の内容は次のような構造になっています。

コード表示 3.4: 章の構文

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">
<!-- $Header$ -->

<!--  The content of this document is licensed under the CC-BY-SA license -->
<!--  See http://creativecommons.org/licenses/by-sa/2.5 -->

<sections>

<abstract>
  これは第一章のちょっとした説明です</abstract>

<version>...</version>
<date>...</date>

(いくつか<section> と <subsection>を定める)

</sections>

個々の章の内部で <section>(Guideでの<chapter> と同じ) と <subsection>s (Guideでの <section> と同じ)を定めることができます。

個々の章はそれ自身のデータとバージョン要素を持たなければなりません。 すべての章とマスタードキュメントの最新のデータはユーザーがすべてのブックのパートをブラウズするときに表示されます。

4.  ハンドブックの進んだ機能

グローバルな値

ときおり、ハンドブック内のいくつかのパートで同じ値が繰りかえされることがあります。 全体を検索し、置換をしても何か忘れてしまったり、望まない変更をしてしまいがちです。 またさらに、共通する章で使われ、含まれるハンドブックに依存するような値を定義することも有用です。

グローバルな値はハンドブックのマスターファイルで定義でき、含まれる章全体で使うことができます。

グローバルな値を定義するには、<values> 要素をハンドブックのマスターファイルに追加してください。 それぞれの値は<key> 要素のなかで定義され、そのid 属性が値を特定します。 すなわちその値の名前となります。<key>の内容がその値になります。

次の例では、ハンドブックのマスターファイルで3つの値を定義しています:

コード表示 4.1: Define values in a handbook

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE book SYSTEM "/dtd/book.dtd">
<!-- $Header$ -->

<book>
<title>bookの使い方の例</title>

<values>
 <key id="arch">x86</key>
 <key id="min-cd-name">install-x86-minimal-2007.0-r1.iso</key>
 <key id="min-cd-size">57</key>
</values>

<author...>
  ...
</author>

...

定義された値は、ハンドブック全体にわたってインラインの<keyval id="key_id"/> 要素で使うことができます。キーの名前をそのid属性で特定します。例えば、 <keyval id="min-cd-name"/> とすると、例のなかでは "install-x86-minimal-2007.0-r1.iso" と置換されます。

コード表示 4.2: 定義した値を使う

<p>
minimalインストールCDは<c><keyval id="min-cd-name"/></c>と呼ばれ、
たった<keyval id="min-cd-size"/> MB のディスクスペースしtかとりません。 インターネット接続があるとき<e>only</e>だけ、このインストールCDをインストールに使えます</p>

翻訳者を楽にするために、実際の値だけを使う、つまり翻訳の必要がない内容だけを使ってください。 たとえば、min-cd-size の値を 57 MBではなく57 とします。

条件要素

Installation Handbooksのように、ハンドブック毎のわずかな違いがあるものの、 複数の章がいくつかのハンドブックで共有されることがあります。 いくつかのハンドブックには関係のない内容を追加する代わりに、執筆者は次の要素に条件を追加できます。 <section>, <subsection>, <body>, <note>, <impo>, <warn>, <pre>, <p>, <table>, <tr>, <ul>, <ol>, <li>.

条件はXMLが変換されるときに評価されるXPATH 形式でなくてはなりません。もし、条件がのときは要素が実行され、そうでなければ無視されます。 条件は test属性で設定されます。

次の例では、各ハンドブックのマスターファイルでいくつかの条件に対してarch の値が使われています:

コード表示 4.3: 条件要素を使う

<body test="contains('AMD64 x86',func:keyval('arch'))">

<p>
この段落はx86 と AMD64 アーキテクチャの両方に適用される。</p>

<p test="func:keyval('arch')='x86'">
この段落はx86アーキテクチャだけに適用される。</p>

<p test="func:keyval('arch')='AMD64'">
この段落はAMD64アーキテクチャだけに適用される。</p>

<p test="func:keyval('arch')='PPC'">
この段落は表示されません!最初の条件により、body全体はスキップされます。</p>

</body>

<body test="contains('AMD64 PPC64',func:keyval('arch'))">

<p>
この段落はAMD64, PPC64 と PPCアーキテクチャに対して適用されます。なぜなら'AMD64 PPC64'という文字列は'PPC'を含んでいるからです。</p>

<note test="func:keyval('arch')='AMD64' or func:keyval('arch')='PPC64'">
この注意はAMD64とPPC64アーキテクチャに適用されます。</note>

</body>

5.  コーディングスタイル

はじめに

すべてのGentooドキュメントは共同作業であり、たいがい何人かで既存の文書を変更しますので、 コーディングスタイルが必要になります。 コーディングスタイルは二つの節にわかれます。 はじめに内部コーディングに関するもの、つまりどのようにXMLタグを配置するかということです。 二番目に内容に関すること、つまり読者を混乱させないようにする方法です。

どちらも次に説明します。

内部のコーディングスタイル

次のタグを除く全てのガイドXMLタグの後で直ちに改行します。(開始タグ、終了タグともに): <version>, <date>, <title>, <th>, <ti>, <li>, <i>, <e>, <uri>, <path>, <b>, <c>, <comment>, <mail>です。

全ての<body>(開始タグのみ)の後、 全ての<chapter>, <p>, <table>, <author> (の集まり), <pre>, <ul>, <ol>, <warn>, <note>および<impo>(開始タグのみ)の前に 空行を入れます。

折り返しは80文字としてください。ただし<pre>の内部は例外です。どうしても選択肢がない場合のみこのルールから逸脱しても許されます(たとえば、URLが最大文字数を越える場合など)。 執筆者は最初に空白がきたところで必ず折り返してください。 コンソールユーザーに役立つように、<pre>要素の内容を80文字以内に保ってレンダリングされるよう努めるべきです。 (訳注:日本語を使用する場合については、 GentooJP翻訳プロジェクト改行の場所を参考にしてください。)

インデントは禁止されています。ただし例外は親XMLタグが<tr> (<table>から)や <ul>, <ol>, <dl>, <author>という場合のXML構造です。 もしインデントを使う場合には、各インデントは必ずスペース2つ分にしてください。 つまり、タブは禁止でありそれ以上のスペースはダメということです。 さらに、タブはGuideXMLドキュメントのなかでは禁止されています。

折り返しが<ti><th>, <li>, <dd> 構造のなかで発生したばあい、内容にあわせてインデントしなければなりません。

インデントの例です:

コード表示 5.1: インデント例

<table>
<tr>
  <th>Foo</th>
  <th>Bar</th>
</tr>
<tr>
  <ti>これがインデントの一例</ti>
  <ti>
    テキストが80文字以内で書ききれない場合は、
    インデントを許可する親タグならば、インデントを必ず行ってください。
  </ti>
</tr>
</table>

<ul>
  <li>最初のオプション</li>
  <li>2番目のオプション</li>
</ul>

属性 では属性名と"="記号、属性値の間に空白を置かないでください。例です:

コード表示 5.2: 属性

悪い例:     <pre caption = "属性">
良い例:     <pre caption="属性">

外部コーディングスタイル

表内(<table>)およびリスト(<ul><ol>)においては、 複数の文から成る場合以外、ピリオド(".")を使用するべきではありません。 複数の文から成る場合は全ての文をピリオド(あるいはその他の句点)で終了します。

表やリスト内に含まれる全ての文は、大文字で始めるべきです。

コード表示 5.3: ピリオドと大文字

<ul>
  <li>No period</li>
  <li>With period. Multiple sentences, remember?</li>
</ul>

コードリストにはいつも見出し(caption)をつけるべきです。

可能な限りlink属性とともに<uri>を使ってください。言い換えると Gentoo Forums のほうが http://forums.gentoo.orgより優先されます。

When you comment something inside a <pre> construct, use <comment> and parentheses or the comment marker for the language that is being used (# for bash scripts and many other things, // for C code, etc.) Also place the comment before the subject of the comment. <pre>構造のなかで何かコメントをする場合は、<comment>と括弧またはその言語で使われているコメントマーク(bashなら#、C言語なら//など)を使ってください。さらに、コメントの主題の前にコメントを置いてください。

コード表示 5.4: コメントの例

(あなたのユーザ名が仮に"john"であるとします。)
# id john

6.  参考

書いてみましょう

ガイドXMLは、とにかく"すっきりさっぱり"を念頭に作られていますから、 XMLを作成する人は、実際のXML構文の勉強に時間を費すことなくどんどんドキュメントを書いてみることができます。 このガイドが"文学者"というわけではない人たちにとって、質の高いGentoo Linuxドキュメントを書き始めるきっかけになれば幸いです。 もしかしたら、Documentation Development Tips & Tricks(訳注: 日本語訳)にも興味がわくかもしれません。 もし、あなたが支援したい場合(もしくは何かガイドに疑問がある場合)、 どうぞgentoo-doc メーリングリスト へあなたの取り組みたいことをメッセージとして送ってください。 それではどうぞ楽しんでください!



印刷

ページの更新日 2008年 3月 9日

このドキュメントのオリジナルバージョン の更新日は2012年 10月 7日

要約: このガイドは、新しいGentooのGuideXMLの簡易な構文を使用して、Webドキュメンテーションを作成する方法を示します。 この構文はGentooLinuxドキュメンテーションのための公式フォーマットです。 また、このドキュメントはそれ自身ガイドXMLを使用して作成されました。 このガイドは、XMLとHTMLについての基礎的な動作知識を前提としています。

Xavier Neys
Author

Daniel Robbins
Author

John P. Davis
Author

Jorge Paulo
Editor

Sven Vermeulen
Editor

千里
翻訳

Takasi Ota
翻訳

Yasumichi Akahoshi
翻訳

シンドウナオアキ
翻訳

Donate to support our development efforts.

Copyright 2001-2014 Gentoo Foundation, Inc. Questions, Comments? Contact us.