Comments
Description
Transcript
オンライン・ドキュメントの 拡張
オンライン・ドキュメントの 拡張 Version 5.1 2006-03-14 InterSystems Corporation 1 Memorial Drive Cambridge MA 02142 www.intersystems.com オンライン・ドキュメントの拡張 Caché Version 5.1 2006-03-14 Copyright © 2006 InterSystems Corporation. All rights reserved. このドキュメントは、 Sun Microsystems、RenderX Inc.、 アドビ システムズ および ワールドワイド・ウェブ・コンソーシアム （www.w3c.org）のツールと情報を使用して、 Adobe Portable Document Format (PDF)で作成およびフォーマットされました。 主要ドキュメント開発ツールは、InterSystemsが構築したCaché と Javaを使用した特別目的のXML処理アプリケーションで す。 Caché 製品とロゴは InterSystems Corporation の登録商標です。 Ensemble 製品とロゴは InterSystems Corporation の登録商標です。 InterSystems という名前とロゴは InterSystems Corporation の登録商標です このドキュメントは、インターシステムズ社(住所：One Memorial Drive, Cambridge, MA 02142)あるいはその子会社が所有す る企業秘密および秘密情報を含んでおり、インターシステムズ社の製品を稼動および維持するためにのみ提供される。こ の発行物のいかなる部分も他の目的のために使用してはならない。また、インターシステムズ社の書面による事前の同意 がない限り、本発行物を、いかなる形式、いかなる手段で、その全てまたは一部を、再発行、複製、開示、送付、検索可能 なシステムへの保存、あるいは人またはコンピュータ言語への翻訳はしてはならない。 かかるプログラムと関連ドキュメントについて書かれているインターシステムズ社の標準ライセンス契約に記載されている 範囲を除き、ここに記載された本ドキュメントとソフトウェアプルグラムの複製、使用、廃棄は禁じられている。インターシス テムズ社は、ソフトウェアライセンス契約に記載されている事項以外にかかるソフトウェアプログラムに関する説明と保証を するものではない。さらに、かかるソフトウェアに関する、あるいはかかるソフトウェアの使用から起こるいかなる損失、損害 に対するインターシステムズ社の責任は、ソフトウェアライセンス契約にある事項に制限される。 前述は、そのコンピュータソフトウェアの使用およびそれによって起こるインターシステムズ社の責任の範囲、制限に関する 一般的な概略である。完全な参照情報は、インターシステムズ社の標準ライセンス契約に記され、そのコピーは要望によっ て入手することができる。 インターシステムズ社は、本ドキュメントにある誤りに対する責任を放棄する。また、インターシステムズ社は、独自の裁量 にて事前通知なしに、本ドキュメントに記載された製品および実行に対する代替と変更を行う権利を有する。 Caché および InterSystems Caché、Caché SQL、 Caché ObjectScript および Caché Object は、インターシステムズ社の 商標です。 ここで使われている他の全てのブランドまたは製品名は、各社および各組織の商標または登録商標です。 インターシステムズ社の製品に関するサポートやご質問は、以下にお問い合わせください： InterSystems ワールドワイド カスタマサポート Tel: +1 617 621-0700 Fax: +1 617 374-9391 Email: [email protected] 目次 1 はじめに .................................................................................................................. 1 1.1 標準 DocBook について .................................................................................... 2 1.2 Caché オンライン・ドキュメントの使用法 ................................................................. 2 1.2.1 DocBook メニュー .................................................................................... 3 2 Caché DocBook アプリケーション ................................................................................. 5 2.1 DocBook データ･モデル .................................................................................... 6 2.2 Caché DocBook クラス ....................................................................................... 6 2.3 ドキュメントのデータベースの問い合わせ .............................................................. 8 2.4 ドキュメントのコンテンツの表現 ............................................................................ 8 2.5 実装仕様 ........................................................................................................ 9 2.5.1 検索パス ................................................................................................ 9 2.5.2 サポート対象の要素 ............................................................................... 10 2.5.3 コンテンツ・サイズの制限 ......................................................................... 12 3 DocBook データベースへの新規のコンテンツの追加 ..................................................... 13 3.1 ナレッジ･ベースに項目を追加 ........................................................................... 13 3.1.1 データベースへの新規ドキュメントのロード ................................................. 14 3.2 DocBook の追加機能 ...................................................................................... 14 3.2.1 セクション .............................................................................................. 14 3.2.2 リスト .................................................................................................... 15 3.2.3 プログラム･リスト ..................................................................................... 15 3.2.4 テーブル .............................................................................................. 16 3.2.5 インライン要素 ....................................................................................... 17 3.3 DocBook ドキュメントのトラブル･シューティング .................................................... 18 3.3.1 DocBook SAX パーサー・エラー・メッセージの解釈 ...................................... 19 3.3.2 DocBookParser トレース能力を有効にする ................................................. 20 オンライン・ドキュメントの拡張 iii 図一覧 Caché DocBook ........................................................................................................... 1 Caché DocBook アーキテクチャ ..................................................................................... 5 iv オンライン・ドキュメントの拡張 テーブル一覧 一般的なインライン DocBook 要素 ................................................................................ 17 オンライン・ドキュメントの拡張 v 1 はじめに Caché DocBook は、(Caché を使用して構築された) XML データベース･アプリケーションであり、 Web ブラウザを通じて提供されるオンライン･ドキュメントです。システム内のすべてのコンテンツの ソースは DocBook に基づきます。 DocBook は、技術的なドキュメントを表記するための XML ベー スの標準です。Caché の DocBook システムは、(このドキュメントも含め) Caché のマニュアルを提供 するために使用します。 Caché DocBook Caché DocBook アプリケーションの主な特徴は、以下の通りです。 • スタイルシートにより管理されたレイアウトと外観を備え、HTML でドキュメント化された統一され た表示形式 • 技術的なドキュメントの標準 DocBook を使用して、XML ベースの統一されたコンテンツ・モデ ル • ドキュメント・セット全体に渡る、完全なテキスト検索やインデックス機能 • プログラム･リストが自動的に構文を確認するため、正しいサンプル構文を保証 オンライン・ドキュメントの拡張 1 はじめに • SQL を使用して問い合わせが可能なドキュメント･コンポーネントのオブジェクト･データベース • Caché ナレッジ・ベース (データベース内の一連の項目) に独自の項目を追加することにより、 ユーザによるプロダクト･ドキュメントの拡張が可能 1.1 標準 DocBook について 標準 DocBook は、技術ドキュメントの XML ベースのマークアップ言語を定義します。 Caché DocBook は、標準 DocBook の v4.0 バージョンに基づいています。Caché のインストールに は、DocBook v4.0 XML DTD のコピーも含まれます。 標準 DocBook の詳細は、以下を参照してください。 • DocBook-The Definitive Guide ： Norman Walsh、Leonard Muellner 著、O'Reilly & Associates 出版 1999 • OASIS (Organization for the Advancement of Structured Information Standards) の Web サイ ト ：www.oasis-open.org • DocBook の Web サイト ：http://www.docbook.org/ 1.2 Caché オンライン・ドキュメントの使用法 Caché オンライン･ドキュメントは、2 つの形式で使用できます。 • オンライン — ローカル Caché サーバが稼動中の場合、ドキュメントは、 “DOCBOOK” ネーム スペースにインストールされており、そこで動作する Caché DocBook アプリケーションにより提 供されます。 • オフライン — ローカル Caché サーバが稼動していない場合、ドキュメントは (DocBook データ ベースから事前に生成された) 静的な HTML ファイルから提供されます。 ローカルのオンライン DocBook アプリケーションの URL は、以下の通りです。 http://localhost:port_number/csp/docbook/DocBook.csp ここで、port_number は Caché サーバが構成されているポート番号です。既定は 8972 です。 オンライン･ドキュメントにアクセスするには、Caché キューブ・メニューの [ドキュメント] コマンドか Caché スタジオの [ヘルプ] メニューを使用します。 2 オンライン・ドキュメントの拡張 Caché オンライン・ドキュメントの使用法 1.2.1 DocBook メニュー DocBook アプリケーションのすべてのページには、一連のメニューの選択肢を含む共通のバナー が表示されます。これらの選択肢は以下の通りです。 Previous (戻る) (左向きの矢印)前のドキュメントに戻ります (ブック内の前の章や、参照内の前のリファレン ス・ページなど)。前の項目がない場合は、表示されません。 Next (次へ) (右向きの矢印)次のドキュメントに移動します (ブック内の次の章や、参照内の次のリファレ ンス・ページなど)。次の項目がない場合は、表示されません。 Home (ホーム) ドキュメントのホーム･ページに移動します。 Contents (コンテンツ) 現在のドキュメントのコンテンツの表へ移動します。 Index (インデックス) オンライン･ドキュメントのマスタ･インデックスに移動します。 Search (検索) オンライン･ドキュメントのマスタ検索ページに移動します。 Find (検索) [Find] フィールドに単語を記入し、 “Enter” キーを押すと、指定された単語に対する検索 ページへ移動します。 Go to (移動) ドロップ･ダウン･リスト [Go To] (有効であれば) には、現在のドキュメントのセクションのタイ トル･リストが含まれます。そのうちの 1 つを選択すると、そのセクションに直接移動します。 オンライン・ドキュメントの拡張 3 2 Caché DocBook アプリケーション Caché DocBook アプリケーションは、Caché インストールの一部としてインストールされているデータ ベース (DOCBOOK) から構成されます。DOCBOOK データベースには、アプリケーションが実行 できるコードや、一連の永続オブジェクトとして保存されている Caché プロダクト･ドキュメントが含ま れます。 Caché インストールには、静的な HTML ドキュメントも含まれます。この静的なドキュメントは、DOCBOOK データベースのコンテンツの一部を示したものであり、Caché サーバがオフラインの際に使 用するためのものです。 Caché DocBook のアーキテクチャは、下図の通りです。 Caché DocBook アーキテクチャ オンライン・ドキュメントの拡張 5 Caché DocBook アプリケーション 2.1 DocBook データ･モデル 標準 DocBook は、多数の XML 要素を定義します。 これは、以下のように大きく 3 つに分類する ことができます。 1. ブロック要素 — これらの要素は、データのツリーとして表示されるコンテンツを区切ります。ブ ロック要素には、パラグラフ、セクション、章、ブックなどがあります。 2. インライン要素 — これらの要素は、特別な意味を持つブロック内でテキストを区切り、それに応 じて表示します。インライン要素には、クラス名、メソッド名、ファイル名、リンク、イメージなどがあ ります。 3. メタ情報要素 — これらの要素は、表示されるコンテンツ以外の部分のコンポーネントに関する 追加情報を区切ります。メタ情報には、その文書の著作者の情報などが含まれます。 Caché DocBook アプリケーション内で、これらの要素は以下のように処理されます。 1. ブロック要素は、永続データ･クラスとして表されます。サポートされているすべてのブロック要素 に対し、同じ名前の対応する永続クラスが ( “DocBook” パッケージ内に) あります。これらのク ラスはすべて、共通のスーパークラスである block から派生します。 2. インライン要素は、残りのコンテンツと同様にデータベースに保存されます。Caché DocBook が コンテンツを HTML として扱う場合、すべてのインライン要素は HTML マークアップに変換さ れます。特に、サポートされている各インライン要素は、HTML の <SPAN CLASS="inline"> タ グに置き換わります。ここで inline はインライン要素の名前です。Caché DocBook HTML スタイ ル･シートは、これらのさまざまな要素がユーザのブラウザ上でどのように表されるかを定義しま す。 3. メタ情報は、さまざまなブロック要素クラスのリテラル、または埋め込みオブジェクト・プロパティと して表されます。 2.2 Caché DocBook クラス サポートされているほとんどの DocBook ブロック要素に対し、DocBook データベース内に対応する 永続クラスがあります。これらのサブクラスは、DocBook.block から直接派生する、コンテナとコンポー ネントというさらに単純なブロックに分化します。コンテナは、DocBook.container クラスから派生し、 1 つ以上の子ブロックを含むことができます。 コンポーネントは、ブック (章や付録など) の一部を表 す特別なコンテナで、DocBook.component クラスから派生します。 データ要素を表す DocBook クラスのクラス階層は、以下の通りです。 • %Library.Persistent 6 オンライン・ドキュメントの拡張 Caché DocBook クラス - DocBook.block • DocBook.container - DocBook.abstract, ….answer, ….book, ….caution - DocBook.component • - • DocBook.example, ….figure, ….formalpara, ….glossdef, ….glossentry, ….glosslist, ….important, ….itemizedlist, ….listitem, ….note, ….orderedlist, ….para, ….qandadiv, ….qandaentry, ….qandaset, ….question, ….refdescriptor, ….refnamediv, ….refsect1, ….refsect2, ….refsect3, ….refsynopsisdiv, ….sect1, ….sect2, ….sect3, ….sect4, ….set, ….tip, ….warning DocBook.informaltable - - DocBook.appendix, ….article, ….chapter, ….glossary, ….part, ….partintro, ….preface, ….refentry, ….reference DocBook.table • DocBook.literallayout • DocBook.programlisting, ….refname, ….refpurpose, ….synopsis DocBook.remark すべての DocBook.block オブジェクトには、(少なくとも) 以下のプロパティが含まれます。 id ブロックの一意の識別子 (大文字と小文字を区別しません) 。これは、オリジ ナルの XML ソース･ファイルで定義されているか、あるいはブロックがデータ ベースに追加されたときに割り当てられます。このフィールドに対する SQL エ イリアスは、blockid です。 content このブロックのコンテンツ (テキスト) container このブロックが属する container オブジェクトへの参照 (必要に応じて) component このブロックが属する component オブジェクト (章など) への参照 (必要に応 じて) book このブロックが属する book オブジェクトへの参照 blockpos コンテナ内におけるこの block の通常の位置。これは、そのコンテンツを確実 に正しい順番で表すために使用します。 container クラスは block を拡張し、子ブロック (含まれるブロック) や title などの別のプロパティに 対するサポートを追加します。 オンライン・ドキュメントの拡張 7 Caché DocBook アプリケーション 2.3 ドキュメントのデータベースの問い合わせ Caché DocBook データベースの主な特長の 1 つに、標準 SQL を使用してすべてのデータへ問い 合わせることができる点があります。この機能は、表示するほとんどすべての内容を単純な SQL 文 を使用して訳すことができるため、アプリケーションの開発を大幅に簡略化することができます。 例えば、DocBook の ID が割り当てられた特定の block オブジェクトのコンテンツを見るには、以下 を実行します。 SELECT content FROM DocBook.block WHERE blockid = 'A456' Caché はSQL からの継承をサポートしているため、特定のコンポーネントの検索を簡単に制限でき ます。例えば、さまざまな programlisting ブロックにある、すべての “Hello, World!” を見つけるに は、以下を実行します。 SELECT ID FROM DocBook.programlisting WHERE content [ 'Hello, World!' book に属するすべての chapter オブジェクトのタイトルを見つけるには、以下を実行します。 SELECT title FROM DocBook.chapter WHERE book->blockid = 'GDOC' ORDER BY blockpos 2.4 ドキュメントのコンテンツの表現 Caché DocBook アプリケーションは、Caché Server Page (CSP) 技術を使用して、Web ブラウザで見 ることができる HTML にコンテンツを表します。Caché では、そのようなコンテンツの提供する、既定 の HTTP サーバをインストールします (したがって、ドキュメントを見るために Web ブラウザは必要 ありません)。 Caché DocBook アプリケーションには、(中央の DocBook.UI.StdPage を経由して) %CSP.Page クラ スから派生した CSP クラスが数個含まれ、これらがブラウザにコンテンツを供給します。これらのクラ スの中で最も重要なものは、DocBook.UI.Page クラスで、ドキュメントの供給の大部分を担います。 DocBook.UI.Page は、以下を実行します。 1. 共通の DocBook メニューとスタイル･シートを提供します。 2. 要求されているコンポーネントを (URL パラメータ、KEY を使用して) 検知し、データベース内 から対応するオブジェクトを見つけます。 8 オンライン・ドキュメントの拡張 実装仕様 3. あてはまるオブジェクトを見つけた場合、これをインスタンス化しその HTMLRender メソッドを呼 び出します。その結果、そのコンテンツとその子オブジェクトのコンテンツを HTML として表示 します。 DocBook.UI.Page クラス以外にも、検索やインデックス、あるいはその他のページを表示するための クラスがあります。 完全な書き込みクラス階層は、以下のようになっています。 • %CSP.Page - DocBook.UI.FrameSet - DocBook.UI.IndexFrame - DocBook.UI.StdPage • DocBook.UI.Comments, ….ErrorLog, ….FileManager, ….Index, ….Librarian, ….LinkChecker, ….Load, ….Page, ….Search, ….SearchBM 2.5 実装仕様 Caché DocBook アプリケーションの現在のバージョンでは、以下の特定の事項に注意してください。 2.5.1 検索パス DocBook アプリケーションでは、class や Utils の多くのメソッドは、SET、books、ディレクトリ全体な どの様々なコンポーネントをロードします。これらは、オペレーションのソースの場所を指定する引数 を受け取ります。従来のバージョンでは、ドキュメント化されていないグローバル ^DocBook.Config("SOURCE") が呼び出し側から何も送信されない場合、このディレクトリに既定の 設定を使用していました。これにより "既定" が設定され、ドキュメントのロードのたびに同じ (通常 は) 長いパス名を何度も入力する手間がなくなります。 しかしこの方法はあまりに限定されており、特に複数のサード・パーティ・ソースからドキュメントをロー ドする場合に不都合でした。現在では、より一般的な機能が利用できます。 新しい方法は、多くの OS やプログラミング・システムで利用できる機能である検索パスに類似して います。オブジェクト (この場合は XML ドキュメント・ソース) の位置を確定する際に、システムのユー ザは検索パスを使用して、表示する位置リストを指定できます。リストの使用により、この位置を 1 番 目として次はここ、3 番目はこの位置などの位置の順序も表すことができます。 グローバル ^DocBook.Config("SOURCE") は位置を指定するためにすでに使用されていたので、 その構造は 3 番目の添え字を含むために標準化されていました。^DocBook.Config("SOURCE", X) の値は、現在でもディレクトリ・パス名です。各値は、ドキュメント・ソース・マテリアルの検索時に検 オンライン・ドキュメントの拡張 9 Caché DocBook アプリケーション 索される位置を指定します。つまりそれぞれのディレクトリが、ドキュメントの潜在的な XML ソースと して "従来の" ^DocBook.Config("SOURCE") 値のように処理されるということです。呼び出される DocBook 関数によっては、最初の検索結果が使用されたり、検索されたすべての項目が使用され ることもあります。例えば、##class(DocBook.Utils).LoadBook(bookname) は前者で、 ##class(DocBook.Utils).LoadSets() は後者です。 3 番目の添え字の値と形式の範囲は、未指定のままです。ユーザは、添え字に対して有効な任意 の値を選択することができます。これにより、ユーザは手動で検索順序を指定できます。ディレクトリ 間の順序付けは、与えられた照合の添え字の順序で決定されます。例えば、3 つの項目に順序を 付けるには、以下のいずれかの順序になります。 • 1, 2, 3 • "A", "B", "C" • "A", "AA", "AAA" • "I", "II", "IV" • 2.7182818285, 3.1415926535, 8.5397342225 • "E", "PI", "PI x E" • 1, "II", "Part-C" 項目が持つ順序で混乱した場合は、以下のメソッド呼び出しが、使用される順序で利用できる検索 ディレクトリを表示します。 znspace "DOCBOOK" do ##class(DocBook.Utils).ShowSearchDirs() また、ユーザは小規模な ObjectScript ルーチンで値を繰り返すことでこれを解決するか、システム 管理ポータルで、DocBook データベースの [グローバル・データ] ページ ([[ホーム]→[グローバ ル]→[グローバル・データ]]) を使用してグローバル自体に格納されている値を表示することができ ます。 この標準化の使用をサポートするため、新規のクラスが DocBook アプリケーション SearchUtils に 追加されました。これは主に、検索リストの管理し、ディレクトリやファイルの名前が要求されたパター ンに適合するリストを検索するために使用されています。 2.5.2 サポート対象の要素 多数の DocBook 要素の中で、一部サポートされていないものもあります。Caché ドキュメントを表す ために必要なコンポーネントのクラスのみが装備されています。同様に、メタ情報要素の完全な (大 容量の) セットはサポートしていません。 現在サポートされている DocBook タグのリストは、以下の通りです。 10 オンライン・ドキュメントの拡張 実装仕様 インデッ クス サポートされている “Index” で始まるタグ A abstract, anchor, answer, appendix, application, article B book, bookinfo C caution, chapter, citation, citetitle, classname, colspec, command D E emphasis, entry, envar, errorcode, errorname, example F figure, filename, firstterm, formalpara, function G glossary, glossdef, glossentry, glosslist, glosssee, glossterm, graphic, guibutton, guiicon, guilabel, guimenu, guimenuitem, guisubmenu H I important, indexterm, informaltable, inlinegraphic, itemizedlist J K keycap, keycode L link, listitem, literal, literallayout M methodname N note O orderedlist P para, part, partintro, preface, primary, productname, programlisting, prompt, property Q qandadiv, qandaentry, qandaset, question, quote R refdescriptor, refentry, refentrytitle, reference, refmeta, refname, refnamediv, refpurpose, refsect1, refsect2, refsect3, refsect4, refsynopsisdiv, remark, row S secondary, sect1, sect2, sect3, sect4, see, seealso, set, subscript, subtitle, superscript, synopsis, systemitem T table, tbody, term, tertiary, tgroup, thead, tip, title, type U ulink, userinput V varname W warning X Y オンライン・ドキュメントの拡張 11 Caché DocBook アプリケーション インデッ クス サポートされている “Index” で始まるタグ Z DocBook.DocBookParser クラスは、前のリストにはない要素タグを含むファイルのロードを試みる場 合、アサーション違反エラーを出力します。 2.5.3 コンテンツ・サイズの制限 特定の block オブジェクトの content プロパティは、32,000 文字以上を含むことができません。 12 オンライン・ドキュメントの拡張 3 DocBook データベースへの新規のコン テンツの追加 3.1 ナレッジ･ベースに項目を追加 DocBook データベース内に含まれるさまざまな book オブジェクト以外にも、多数の外部 article オ ブジェクトがあります。これらの article オブジェクトには、さまざまなトピックに関する情報が含まれて おり、Caché ナレッジ･ベースと併せて一覧表示されます (すべての article オブジェクトを title で並 び替えた一覧を表示する、単純なクエリもあります)。 単純なテキスト･エディタ (あるいは、高性能 XML エディタ) を使用して、ご使用の Caché インストー ルに知識や覚書など技術的な情報を簡単に追加することができます。以下は、非常に単純な項目 を定義する XML ドキュメントです。 <?xml version="1.0" ?> <!DOCTYPE article PUBLIC "-//Arbortext//DTD DocBook XML V4.0//EN" "c:\cachesys\csp\docbook\doctypes\docbook\docbookx.dtd"> <article id="UMFA_MyFirstArticle"> <title>My First Article</title> <subtitle>This document contains my first article.</subtitle> <para>This is my first article.</para> </article> このドキュメントには、以下が含まれます。 1. XML ヘッダ 2. このドキュメントに、記事と DTD ファイルの位置が含まれていることを示す DTD 仕様 3. 項目の内容を区切る “article” 要素。この項目の ID は、データベース全体で一意である必 要があります。ユーザが作成した項目には “U” から始まるタイトルを付けることをお勧めして オンライン・ドキュメントの拡張 13 DocBook データベースへの新規のコンテンツの追加 います。 Caché DocBook ユーティリティの規約にしたがい、ユーザはファイルにこのドキュメン トを保存するときにプライマリ・コンポーネントの ID と同じ名前を使用してください。 4. 項目の内容を表すタイトルとサブタイトル 5. 項目のコンテンツを含む <para> (パラグラフ)。通常、実際の文書は、1 つ以上のパラグラフを 持ちます。 3.1.1 データベースへの新規ドキュメントのロード データベースへ新規のドキュメントをロードするには、以下を実行します。 1. 前のセクションで説明されている項目などの新規 XML ドキュメントを作成します。 2. (Caché キューブ･メニューから) Caché ターミナルを起動します。 3. 以下を実行して、DocBook データベースが属する DOCBOOK ネームスペースに切り替えま す。 ZN "DOCBOOK" 4. その XML ドキュメントのパスと名前を使用して、DocBook.Utils クラスの Load メソッドを呼び出 します。 Do ##class(DocBook.Utils).Load("\mydocs\article.xml") 5. 新規のドキュメントが記事である場合、これは DocBook ナレッジ･ベース のページから見ること ができます。 3.2 DocBook の追加機能 文書の本体部分で DocBook 要素を活用して、さらに魅力的な文書を作成できます。 3.2.1 セクション <sect1>、<sect2>、<sect3>、<sect4> の要素を使用して、セクションやサブセクションを指定できま す。これらは、正しく入れ子にする必要があります。 14 オンライン・ドキュメントの拡張 DocBook の追加機能 <?xml version="1.0" ?> <article id="UMFA_MyFirstArticle"> <title>My First Article</title> <subtitle>This document contains my first article.</subtitle> <para>This is my first article.</para> <sect1> <title>This is Section 1</title> <sect2> <title>This is SubSection 1-A</title> <para>Text</para> </sect2> </sect1> <sect1> <title>This is Section 2</title> <sect2> <title>This is SubSection 2-A</title> <para>Text</para> </sect2> </sect1> </article> 3.2.2 リスト 番号付きリストを作成するには、以下を実行します。 <orderedlist> <listitem><para>Item</para></listitem> <listitem><para>Another Item</para></listitem> </orderedlist> 番号なし (箇条書き) のリストを作成するには、以下を実行します。 <itemizedlist> <listitem><para>Item</para></listitem> <listitem><para>Another Item</para></listitem> </itemizedlist> <listitem> 要素の中には、必ず <para> (あるいはその他のブロック) 要素を置く必要があります。必 要に応じて <listitem> 内に複数のブロックを置くこともできます。 3.2.3 プログラム･リスト コード・リストを表示するには、プログラム･リスト･ブロックを使用します (<para> 要素と同様に使用し ます)。 <programlisting> Write "Hello"</programlisting> Caché DocBook アプリケーションは、これをコード･リストとして表示します。さらに、Caché DocBook アプリケーションで構文を確認したり、lang 属性を設定してこれをカラー表示することができます。 <programlisting lang="COS"> Write "Hello"</programlisting> 通常、Caché ObjectScript の例では、正しい構文であるためには各行の先頭に空白文字を置く必 要があります。 オンライン・ドキュメントの拡張 15 DocBook データベースへの新規のコンテンツの追加 利用できる言語値は以下の通りです。 lang 言語 BAS Caché Basic CLS Caché クラス定義 CLS!MEMBER Caché クラス定義のメンバ (プロパティ、メソッドなど) COS Caché ObjectScript CSP CSP テキスト HTML HTML テキスト JAVA 完全な Java クラス定義 JAVA!METHODBODY Java コードの行 NONE 例で構文チェックが行われないことを示します。これは、ポ イントを示すためにマテリアルがエラーを持つこと、または プログラム・ユニットとして不完全であることを示すために 使用されます。 SQL SQL 文 XML XML XML!FRAGMENT 適格であるが、完全ではない XML 注釈: 例えば、 <programlisting lang="NONE"> lang 属性をまったく省略するのではなく、構文チェックを行わない例をマークするために、 (これらの効果が同じだとしても) 上記のコードを使用することをお勧めします。lang="NONE" を使用すると、ドキュメントがプログラム的に操作されるときに、情報が明示的に提供されま す。 3.2.4 テーブル DocBook は CALS というテーブル定義を使用します。詳細は、標準 DocBook を参照してください。 Caché DocBook アプリケーションは、この単純なテーブル･モデルをサポートします。 これらは以下 のように、<table> あるいは <informaltable> 要素のいずれかを (タイトルなしで) 使用して区切りま す。 16 オンライン・ドキュメントの拡張 DocBook の追加機能 <informaltable> <tgroup cols="2"> <colspec colnum="1" colname="Parameter" /> <colspec colnum="2" colname="Description" /> <tbody> <row> <entry colname="Parameter">X</entry> <entry colname="Description">The X location.</entry> </row> <row> <entry colname="Parameter">Y</entry> <entry colname="Description">The Y location.</entry> </row> </tbody> </tgroup> </informaltable> 3.2.5 インライン要素 さまざまなインライン要素の 1 つを使用して、パラグラフ内の単語や節を強調して表示することがで きます。これらのうち最も一般的なものは以下の通りです。 一般的なインライン DocBook 要素 要素 説明 例 メモ <classname> クラス名 %CSP.Page クラス <classname> に Caché ライ ブラリ･クラスの名前が含ま れる場合、Caché DocBook は自動的にクラス･ドキュメン トへリンクします。 <command> プログラム名、ある いは他のオペレー ティング･システム･ コマンド名 UNIX の rm コマン ド <emphasis> 強調テキスト これは 非常に 重 要です。 <filename> ファイルの名前 CACHE.DAT ファイ ル <function> 関数名 Write コマンドを使 用します。 <guibutton> GUI アプリケーショ ン内のボタン OK ボタンをクリック します。 Caché ドキュメントは、プログ ラミング言語のコマンドと関 数の両方で <function> を使 用します。 オンライン・ドキュメントの拡張 17 DocBook データベースへの新規のコンテンツの追加 要素 説明 例 <guilabel> GUI アプリケーショ ン内のラベル これを 名前 フィー ルドに入力します。 <guimenu> GUI プログラム内の メニュー ファイル メニュー内 で使用可能です。 <guimenuitem> メニューの項目 このメニューから 保存 コマンドを使 用します。 <methodname> オブジェクト･メソッド あるいはクラス･メ ソッドの名前 Print メソッド <property> プロパティ名 Name プロパティ <quote> インラインの引用符 このドキュメントは “簡単に” 理解で きます。 <superscript> 上付き文字 ab <systemitem> インラインのセキュ リティ関連の項目 DocBook にアクセ スするには メモ %DB_DOCBOOK : Read が必要です。 <varname> 変数、あるいは引数 の名前 count は反復回数 を指定します。 <userinput> ユーザの入力 コマンド行から Hang 100 を入力 してください。 3.3 DocBook ドキュメントのトラブル･シューティング DocBook DTD は非常に精密です。ご使用の DocBook ドキュメントが有効でなければ、Caché XML (SAX) バリデタから長いエラー･メッセージが生成されます。これらのエラー･メッセージには、エラー が発生したオリジナルのソース･ファイルの行番号や列のオフセットが含まれます。 18 オンライン・ドキュメントの拡張 DocBook ドキュメントのトラブル･シューティング 3.3.1 DocBook SAX パーサー・エラー・メッセージの解釈 生成された情報の種類を示すため、有効な XML ドキュメントはタグ <AnErroneousTag SomeAttribute="AValue"> を挿入して修正されました。ドキュメントをデータベースにロードする試みは失敗 し、ターミナルで以下のエラー・メッセージが表示されます。 注釈: 各エラー・メッセージは当初は 1 行で表示されていましたが、読みやすくするため、メッセー ジが改行されるようになりました。 エラー出力は以下の通りです。 SAX Error (a document could not be loaded): Unknown element 'AnErroneousTag' in A:\Parser\Example\source.xml at line 357 offset 16 SAX Error (a document could not be loaded): Attribute 'SomeAttribute' is not declared for element 'AnErroneousTag' in A:\Parser\Example\source.xml at line 357 offset 31 DocBook Parser Assertion Failure: Unsupported tag: <AnErroneousTag> at line 357 offset 40 SAX Fatal Error (a document could not be loaded): Expected end of tag 'AnErroneousTag' in A:\Parser\Example\source.xml at line 359 offset 7 ERROR #6301: SAX XML Parser Error: Expected end of tag 'AnErroneousTag' in A:\Parser\Example\source.xml at line 359 offset 7 この 1 つのエラーによってログに複数のメッセージが生成されましたが、これは珍しいことではありま せん。XML ドキュメントの形式は、そのドキュメント・タイプ (この場合は DocBook DTD) によって厳 密に指定されています。ドキュメントを無効にするエラーは、DTD 内の複数の制約と衝突することが よくあります。各制約にエラーと位置に関する情報を記述したレポートを発行します。 簡単に説明すると、このタグは 1 行に 1 つだけ配置されていました。したがって、行内のすべての 位置は、位置が 1 であることを示すオープニング "<" に関連しています。 このタグの後には、行に 単独で存在する "</para>" が続きます。このローカル構成から、これらのエラーは発生した順に報 告されます。 • タグは、DocBook.DTD の一部ではありません。タグ名は知られており、タグ名と属性名の間の 空白が到達したときに処理されます。 • タグが認識されていないので、属性名は DTD で定義されません。パーサーは、属性名のスキャ ン完了後にタグを認識します。 • タグとそのすべての属性値がスキャンされたら、そのデータは、認識済みのタグでないことを報 告する DocBookParser インスタンスに渡されます。 オンライン・ドキュメントの拡張 19 DocBook データベースへの新規のコンテンツの追加 • 最後の 2 行は、スキャナが "</para>" を収集し、オープニング要素 <AnErroneousTag SomeAttribute="AValue"> が他のクロージング要素が見付かる前に適切に閉じられていないこ とを決定したときに生成されます。 エラー・メッセージで報告された位置は、エラーが検出された場所であることに注意してください。実 際には、エラーが発生した場所ではないことがあるからです。 element タグの終わりがないというエ ラーは、かなり後方でしか検出されないことがありますが、これは閉じる要素に続くマークアップが要 素自体で論理的に許可されているからです。 DocBook DTD やドキュメントの対象の構造の作業に関する知識は、この誤りのクラスを素早く認識 するために重要です。 3.3.2 DocBookParser トレース能力を有効にする DocBookParser クラスのこのバージョンは、ドキュメントの解析中に何が発生したかをターミナル・ロ グに情報をトレースするように拡張されています。 トレースは、グローバル ^DocBook.Config("TRACE") をゼロでない値を設定することで有効にする ことができます。値は、いずれのアクションがトレース出力を生成するかを示す、ビット・マスクとして 解釈されます。ビット値とそれに関連するアクションは以下の通りです。 ビット値 対応するアクション 1 開始要素 <StartElement> の発生をトレースします 2 終了要素 </StartElement> の発生をトレースします 4 エンティティが認識されるときに情報を生成します 8 ユーザがエンティティのスキャンが完了するときを示します 16 解析中に無視されるマークアップやテキスト情報を表示します 32 ブロック要素コンテンツに対してスキャンされたテキストを示します 64 特定の内部オペレーション中に、進行バーを表示します したがって、^DocBook.Config("TRACE") の 23 という値は、開始要素 (1)、終了要素 (2)、検索され たエンティティ (4)、および無視 (16) されたドキュメントのすべてのマテリアルに対するトレース出力 を示します。 20 オンライン・ドキュメントの拡張