[PHP-doc 28] [draft] appendices/about.xml
Masaki Fujimoto
php-doc@php.gr.jp
Fri, 30 Nov 2001 23:09:33 +0900
ふじもとです。
appendices/about.xmlを和訳してみました。もし問題ないようならcommitしてい
ただけますでしょうか？＞廣川様
# 一応CVSアカウントはリクエストしておきましたが、4.1.0リリース前で皆様お
# 忙しいそうなのでいつになるか... というかんじですね :-)
念のため
http://nx.dip.jp:8080/php/manual/ (html)
http://nx.dip.jp:8080/php/cvs/phpdoc/ja/appendices/about.xml (xml)
にも置いておきました。以下、和訳内容です。誤訳の指摘等ありましたらご指摘
お願いします。
--- appendices/about.xml ---
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!--
TODO: add manual conventions section (eg. how to read
function usage parts, what is fixed width, what is
bold, what is linked
add some tips about combining the versions (online-
offline), and using "http://anymirror.php.net/funcname"
-->
<appendix id="moreabout">
<title>マニュアルについての詳細</title>
<sect1 id="moreabout.formats">
<title>PHPマニュアルのフォーマット</title>
<para>
PHPのマニュアルはいくつかのフォーマットで提供されています。
大まかに言うとフォーマットには2つの種類があります。オンラインで
読むことのできるフォーマットとダウンロード可能なパッケージです。
</para>
<para>
オンラインマニュアルは<ulink url="&url.php;">&url.php;</ulink>
や、いくつかのミラーサイトで読むことができます。このタイプの
フォーマットのマニュアルを快適に読むためには、一番近い場所にある
ミラーサイトを選択すると良いでしょう。オンラインマニュアルの
レイアウトは2種類のうちいずれかを選択できるので、回線速度が
遅い場合や印刷を行いたい場合にはプリンタフレンドリーなものを
選ぶことができます。オンラインマニュアルの主な利点は最新の
マニュアルを<link linkend="moreabout.notes">user notes</link>
付で読むことができることと、ブラウザさえあれば他のソフトウェアを
セットアップする必要がないということです。 逆に不便な点は
常にオンラインでいる必要があること、サーバがダウンしている
間は使用不可能なこと、全文検索が行えない、そして全ページを網羅した
目次が無いことです。
</para>
<para>
PHPマニュアルをダウンロードする場合、私たちが提供する多くの
フォーマットのいずれかを選択することができます。選択肢は
OSやドキュメントを読む方法に依存します。もしこれらの異なった
フォーマットのドキュメントをどのように生成しているかという
ことに興味があるのなら、この付録の<link linkend="moreabout.generate">
各種フォーマットを生成する方法</link>の項まで読み進めて下さい。
</para>
<para>
テキストビューワやブラウザはどんなOSにも有るものなので、
HTMLとテキストファイルはほとんどプラットフォームを問わずに
利用できるフォーマットです。HTMLファイルは様々なOSで
利用できるようにいくつかの圧縮方式で提供されます。
一つのファイルにまとめられたHTMLファイルもしくはテキスト
ファイルは日常での利用においては理想的ではありませんが、
全文検索は容易です。分割されたHTMLを圧縮したバージョンには
2000個以上のファイルが含まれるので注意して下さい。
こうしたファイルから検索を行うにはOSの検索機能、例えば
Windowsなら検索ダイアログを、Unix系システムならgrepを
使用します。このようなツールによる検索は快適とはいえないので
必要なら適宜オンラインでの検索を利用して下さい。
</para>
<para>
PDFもまたクロスプラットフォームなフォーマットです。
このフォーマットは印刷するのに最適ですが、あまりに
多くの資源を必要とするのでこのマニュアルの全ての部分を
印刷するのはお勧めしません。また、マニュアルは日々更新
されているので、印刷を行う前にもう一度よく考えてみて下さい。
PDFを閲覧している場合には全文検索が可能です。ただ、
PDFファイルを読むには<ulink url="&url.adobe.acrobat;">Adobe
Acrobat Reader</ulink>が必要だということに気をつけて
ください。
</para>
<para>
PalmPilotのDOCとiSiloフォーマットは、頻繁に旅行/出張する人や
陸や空を移動中にマニュアルをよんで勉強したい、という人に
とって理想的です。ダウンロードしたフォーマットに対応した
<ulink url="&url.palm.doc;">DOC</ulink>又は<ulink
url="&url.palm.isilo;">iSilo</ulink>リーダをインストールした
Palmを持ち歩くことができます。これはPHPを学ぶのに最適
な方法では有りませんが、いつでもどこでも素早く情報を
得ることができます。
</para>
<para>
最後に、とはいっても少し長くなりますが、Windows HTML
ヘルプバージョンのPHPマニュアルがあります。これは
実際にはある種のHTMLパッケージです。コンパイルされたHTML
バージョン(<acronym>CHM</acronym>として知られています)
の最大の利点は、ビューワが全文検索、検索結果からの検索、
完全な目次、そしてブックマークの機能を提供することです。
また、このフォーマットは主なPHPのIDEと親和性があります。
最も不利な点は現在のところWindows上でしか使えないことです。
また、古いバージョンのWindowsを使用している場合、CHMに
アクセスするにはMicrosoft Internet Explorer 4.0以降が必要です。
CHMクリエータとビューワの開発も行っているVisual Basic for
Linuxプロジェクトはまだ計画中の段階です。もしこの
プロジェクトの進行状況に興味があるなら、<ulink
url="&url.vb4linux;">sourceforge</ulink>のページを
見て下さい。
</para>
</sect1>
<sect1 id="moreabout.notes">
<title>ユーザノートについて</title>
<para>
ユーザノートはPHPマニュアルを読む上で重要となる箇所です。
中には非常に価値のある情報も含まれています。ユーザノート
システムは基本的には、個々の事例や関数や言語構造についての
警告等を追加できるように作られています。
</para>
<para>
ユーザノートはPHPのサイトに表示される前に、何らかの
抑制があるわけではない、ということに注意して下さい。
従って、そこに書かれた内容の質については保証されません。
</para>
<para>
もし、ユーザノートであなたの問題の解決策が見つからなかった場合は
<link linkend="moreabout.more">PHPに関する更なる情報を得るには
</link>を読むをよいでしょう。
</para>
</sect1>
<sect1 id="moreabout.more">
<title>PHPに関する更なる情報を得るには</title>
<para>
このマニュアルは完全なプログラマーズガイドを目指している
わけではありません。もしあなたがプログラミング初心者なら
このマニュアルを読んだだけではPHPを使いこなせるようには
ならないでしょう。簡単なプログラミングを入念に説明している
本の購入を検討したほうがいいかもしれません。こうした本の
一覧は<ulink url="&url.php.books;">&url.php.books;</ulink>
で見つけることができます。PHPマニュアルを印刷したものを
購入することはお勧めしません。なぜならそうしたものは
大抵古くなっているからです。PHPマニュアルは日々更新されている
ことに気をつけてください。
</para>
<para>
もし、あなたが格闘しているのと調度同じ問題を他の人も経験した
ことがあるはずだと考えるなら、メーリングリストを利用することも
できます。メーリングリストはテーマによって多くのグループに
分かれています。あなたがどんなに忙しいときでも、数分で
質問の答えが返ってくるでしょう。<ulink
url="&url.php.support;">&url.php.support;</ulink>
で、メーリングリストに加入することができます。
またサポートページの左側のバーにあるリンクにはIRC
チャンネルがあります。
</para>
<para>
もしメールによる議論が好きではない場合は、<ulink
url="&url.php.links;">&url.php.links;</ulink>のリンクページで
多くのコミュニティサイトを見つけることができます。
</para>
</sect1>
<sect1 id="moreabout.howtohelp">
<title>ドキュメントの改善を手助けするには</title>
<para>
もちろん、あなたはドキュメントを改善する手助けをする
ことができます。これには基本的に2つの方法があります。
</para>
<para>
もし(どの言語でかかれたものでも)マニュアルに間違いを見つけたら
<ulink url="&url.php.bugs;">&url.php.bugs;</ulink>にある
bug systemを使ってその問題を報告して下さい。バグの種別は
"Documentation Problem"にして下さい。こうすれば私たちは
全てのバグに対応し、またどのように解決されたかを監視することが
できます。またフォーマットに関する問題(例えばPDF版のPHPマニュアル
が正しく表示されない等)があればこれも報告して下さい。
助けを呼ぶためにバグ報告を送信してシステムを乱用しないで
下さい。このようなときは前述されているメーリングリストや
コミュニティを利用して下さい。
</para>
<para>
各ページに注釈をつけることで、マニュアルを書いた人よりも
多くの例を読者に提供することができます。ユーザのコメントは
非常に役立つという評判です。この注釈システムを使って
バグレポートを送信しないで下さい。注釈の詳細については、
<link linkend="moreabout.notes">About user notes</link>の
項を読んで下さい。
</para>
</sect1>
<sect1 id="moreabout.generate">
<title>各種フォーマットを生成する方法</title>
<para>
このマニュアルはXMLで書かれていて、<ulink url="&url.docbook.xml;">
DocBook XML DTD</ulink>、<ulink url="&url.dsssl;"><acronym>DSSSL
</acronym></ulink> (Document Style and Semantics Specification
Language)をフォーマットに使用しています。また、実験的に<ulink
url="&url.xslt;"><acronym>XSLT</acronym></ulink> (Extensible
Stylesheet Language Transformations)をメンテナンスとフォーマットに
使用しています。
</para>
<para>
<acronym>XML</acronym>をソースファイルのフォーマットとして
使用することで、一つのソースファイルを管理するだけで、
多くの出力形式を生成することができるようになっています。
<acronym>HTML</acronym>と<acronym>TeX</acronym>版で使用している
ツールは<ulink url="&url.jclark;">James Clark</ulink>に
よって書かれた<ulink url="&url.jade;">Jade</ulink>と、
<ulink url="&url.nwalsh;">Norman Walsh</ulink>によって
書かれた<ulink url="&url.dbstyle;">The Modular DocBook
Stylesheets</ulink>です。Windows HTMLヘルプを作成するためには
<ulink url="&url.winhelp;">Microsoft HTML Help Workshop</ulink>
を使用しています。またちょっとした変換処理やフォーマットの
処理にはもちろんPHPを使っています。
</para>
<para>
様々な言語の、(テキスト形式、シンプルな<acronym>HTML</acronym>形式、
<acronym>PDF</acronym>、PalmPilot DOC、PalmPilot iSilo、
Windows HTML Help等を含む)様々な形式の最新のマニュアルを<ulink
url="&url.php.docs;">&url.php.docs;</ulink>からダウロード
することができます。マニュアルは元となるXMLファイルが変更されると
随時更新されます。
</para>
<para>
このドキュメントの<acronym>XML</acronym>ソースコードのダウンロード
に関する情報は<ulink url="&url.php.cvs;">&url.php.cvs;</ulink>に
あります。ドキュメントは<literal>phpdoc</literal>モジュールに格納
されています。
</para>
</sect1>
</appendix>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
--- ここまで ---
--
藤本 真樹
アストラザスタジオ
fujimoto@studio.co.jp