NPO法人とはという基本的内容から実際のNPO法人設立まで広くお手伝いいたします。これからNPO法人をお考えの方はオススメ。NPO法人とはNon Profit Organizationの略であり、特定非営利活動法人を指します。法人なので当然に登記され、独立した人格として活動ができるようになります。
ここでは、PEAR がサポートする形式でドキュメントを作成する方法について 詳細に説明します。読者としては、すでにパッケージをメンテナンスしている PEAR 開発者および、 これから新しくパッケージを寄与しようと考えている方々を想定しています。
NPO法人とはという基本的内容から実際のNPO法人設立まで広くお手伝いいたします。これからNPO法人をお考えの方はオススメ。NPO法人とはNon Profit Organizationの略であり、特定非営利活動法人を指します。法人なので当然に登記され、独立した人格として活動ができるようになります。
DocBook は XML の方言で、 様々なプロジェクトでドキュメントの管理に使用されています。 オープンソースのプロジェクトでの DocBook の使用例としては、 KDE や PHP のドキュメントがあります。 PEAR においても DocBook を使うこととしました。それにより、 PEAR パッケージの技術文書を作成するための強固な基礎が得られるものと 考えたからです。
DocBook を使うことのトレードオフは、その使用が若干難しいということが 挙げられます。ドキュメントをテストするために、ツールをいくつかインストールする 必要がありますし、（それほど複雑でないにしても）XML の方言を覚える必要が あります。しかし、いったん DocBook の働きに慣れると、 DocBook によるドキュメント作成を楽しめるようになります。
また、DocBook を学ぼうとする人々にとって貴重な情報源である、 Norman Walsh, Leonard Muellner 著、O'Reilly & Associates, Inc. 出版の書籍、 [DocBook: The Definitive Guide] は、 オンラインで 読むことができます。
是非、この書籍の "DocBook Element Reference" の章を読んでください。 すべての 要素について、 どの要素が親になり、また子になることが可能であるかなど、 詳細な情報が記載されています。
DocBook XML は（他の XML ファイルと同様に）通常のテキストエディタで 編集できますが、作成したドキュメントの妥当性を検証するために ソフトを幾つかインストールすると良いでしょう。 必要なソフトウエアとそのインストール方法については、 PHP Documentation HOWTO を参照してください。 ソフトウエアについて以外にも、本文書以上に役に立つ情報が数多く 記されています（第2章は PHP 特有の事項についての情報を扱っているので、 読み飛ばすことができます）。
残念ながら、特定の環境ではソフトウエアのインストールが 難しい場合もありえます。 しかし、ソフトウエアを適切に動作させることが出来ないからといって、 ドキュメントを書かないことの言い訳にはなりません。 2 時間ごとに自動で peardoc を CVS からダウンロードしビルドする、 2 機のテストサーバがあります。 あなたが変更を加えたことによって発生したパースエラーは、 ビルド後のログにて見ることができます。
| http://www.appelsiini.net/~tuupola/php/peardoc2/peardoc.txt (time zone: EET = UTC+2, EEST = UTC+3) |
| http://pear.php-tools.net/peardoc.log (time zone: CET = UTC+1, CEST = UTC+2) |
| http://pear.php-tools.net/peardoc-error.log |
| http://www.appelsiini.net/~tuupola/php/peardoc2/ |
| http://pear.php-tools.net/peardoc/ |
| 警告 |
PEAR の WEB サイトにアップされるマニュアルは、週に一回ビルドされます。 この時、XML の妥当性チェック時にエラーが起きると、ビルドが失敗します。 ビルドが失敗すると、マニュアルが古いバージョンのままとなってしまいます。 ですから、常に テストビルドのログをチェックし、 変更が妥当であることを確認するようにしてください。 また、メインビルドが行われる (日曜 ~12:00 UTC) 直前のコミットは 控えてください。 |
必要なソフトが揃ったら、次に、PEAR の CVS リポジトリから マニュアルの XML ソースを取得する必要があります。
$ cvs -d :pserver:<user>@cvs.php.net:/repository login
[password]
$ cvs co peardoc
|
cvs.php.net のアカウントを持っていない場合は、ユーザ名として cvsread を使用し、 パスワードを聞かれたら、phpfi と入力してください。
上記を実行すると、./peardoc ディレクトリ内に 最新のソースのローカルコピー ("sandbox") が得られます。 あなたが、CVS に詳しく無ければ、オンラインブック "Open Source Development with CVS" を参照すると、必要な情報が得られるでしょう。
作成されたディレクトリ peardoc を見れば概要が 判ると思いますので、ここでは、ディレクトリ構造の完全な詳細については述べません。 パッケージに関する文書を作成する場合には、はじめに peardoc/en/package/ ディレクトリを見ると良いでしょう。 ディレクトリ構造について、その他の質問がある場合は、 文書関連メーリングリスト (documentation list) でたずねてください。
DocBook によるドキュメントの作成について、くどくどと述べる代わりに、 すばやい理解ができるように "参考文献" を幾つか示します。
PEAR の CVS ツリーには DocBook XML のテンプレートが含まれており、 標準的な PEAR ドキュメントの記述構成を示しています。
このテンプレートの簡単な利用法は以下の様になります。 まず、ワーキングディレクトリにコピーして適切にリネームします。 パッケージのプログラムの実装に沿って編集し、 最後に、リポジトリのパッケージのディレクトリにアップロードします。
HTTP_Request は比較的小さいパッケージで、 そのドキュメントは、エンドユーザ向けにパッケージの基本的機能を解説する 複数の文書で構成されています。 各機能の説明にあたっては、少なくとも 1 つのサンプルが示されています。 数個のメソッドしかない小さなパッケージは、この様なタイプのドキュメントを 作成すれば十分です。
XML_Beautifier も比較的小さいパッケージですが、 さまざまなオプションを設定することが可能です。 これらのオプションについては、そのドキュメント中で解説されています。 加えて、(HTTP_Request と異なり) メソッドの API ドキュメントの他にも、いくつものサンプルが示されています。
DB は大規模なパッケージで、 そのドキュメントは、サンプルも含め良くできています。 DB のドキュメントは、peardoc/authoring に示された形式に適切に従っています。上のリンクは、 CVS リポジトリ内の XML ソースへのものですが、 HTML 変換後のもの を調べて見るのも有用でしょう。
上記の例の他にも、ローカルの CVS ツリーの peardoc ディレクトリには、ドキュメントが数多く詰まっています。 特に、peardoc/en/packages/ ディレクトリが参考になるでしょう。 また、CVS モジュールを web で見る こともできます。あなたが、今読んでいるこのファイルの生 XML は こちら です。
ドキュメントの翻訳も重要な仕事です。 未翻訳な言語への翻訳を新たに行うことも歓迎ですし、 新しいドキュメントが加わった際に、それを翻訳することも必要です。 また、翻訳済みのドキュメントについても、英語版に変更が加えられると、 アップデートが必要となります。 翻訳を行う流れは、本マニュアルのリビジョンの追跡 のセクションを参照してください。
本章で、DocBook ドキュメントの作成についてのすべての疑問に答えられては いないかも知れません。質問や何か問題がある場合は、pear-doc@lists.php.net にて、 PEAR ドキュメントチームに気軽に連絡を取ってください。 文書関連メーリングリスト (documentation list) に参加するには、 pear-doc-subscribe@lists.php.net へメールを送ってください。
| 前のページ | ホーム | 次のページ |
| PEAR パッケージ内での色表現 | 上に戻る | 良いドキュメントを書くコツ |
PR NPO法人設立看護師・看護婦・ナース 人材派遣 アルバイト ディレクトリ 会社設立 産業廃棄物収集運搬業許可 風俗営業許可（バー・キャバクラ等）