Extensions/Help

OOo はヘルプの要求があったときに jar ファイルから xhp ファイルを取り出し、help ディレクトリにある main_transform.xsl スタイルシートによる XSLT で html ファイルに変換したものをヘルプビューアに表示します。CSS には言語ディレクトリ中にある表示に対応したものが利用されます (デフォルトでは default.css)。

xhp ファイルは XML ファイルフォーマットにより記述されています。フォーマットは次の文章に記載があります。

また、Developer's Guide に拡張機能ヘルプの節があります。

http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/Extensions/Help_Content

多数のファイルが必要に見えますが実際に作成する必要があるのは、jar ファイルに含まれている xhp ファイルのみです。(OOo 2.4 では拡張機能ヘルプによるツリー表示がサポートされていません。3.0 で対応される予定です i83624。また、全文検索もサポートされておらず 3.0 で予定されています i85426。)

xhp ファイル以外のファイルは拡張機能ヘルプが拡張機能マネージャによりインストールされるときに自動的に生成されます。

ファイル配置

拡張機能パッケージ中でヘルプファイルは MIME-TYPE/manifest.xml ファイル中で指定したディレクトリに配置します。多くの場合 help 以下に配置されます。

ヘルプファイルは言語コードを名前に持つディレクトリに言語ごとに入れます。さらに、その言語ごとのディレクトリに拡張機能 ID (description.xml ファイル中の identifier 要素で指定したもの) を名前に持つディレクトリを入れます。そして、そのディレクトリ中に xhp ファイルを入れます。

ツリー用の .tree ファイルは拡張機能 id のあるディレクトリに入れます。

次のファイル配置では拡張機能 id は mytools.mri です。

xhp ファイルを入れておくディレクトリにサブディレクトリを作成してさらに xhp ファイルを入れることもできます。

manifest.xml

拡張機能ヘルプのファイルタイプは application/vnd.sun.star.help、パスはディレクトリで指定します。

<?xml version="1.0" encoding="UTF-8"?>
<manifest:manifest>
 <manifest:file-entry manifest:full-path="help" 
 manifest:media-type="application/vnd.sun.star.help"/>
</manifest:manifest>

索引への登録

ヘルプビューアの索引ページに表示されるエントリーを作成します。

索引への項目の登録は bookmarks タグを利用します。branch を index に設定します。そして、登録したい項目を bookmark_value に指定します。

<bookmark xml-lang="ja" branch="index" id="bm_idindex">
<bookmark_value>MRI</bookmark_value>
</bookmark>

この例では MRI という項目が追加されます。

次のようにセミコロンを利用するとサブ項目 SUB が TOP 項目のサブ項目として作成されます。

<bookmark_value>TOP;SUB</bookmark_value>

特定のモジュールの索引に登録されるようにするには id に接尾語を付けます。テキストドキュメントのみに表示されるようにするには _swriter をつなげます。

id="bm_idindex_swriter"

これは複数のモジュールに対しても可能です。

ツリー

一覧ツリーへの登録

ツリーへの登録は 3.0 でサポートされる予定です。

下記のようなファイルを作成してヘルプファイルの言語ごとのディレクトリに入れます (拡張機能 Id と同じ名前のディレクトリのあるディレクトリ内)。

help.tree

<?xml version="1.0" encoding="UTF-8"?>
<tree_view version="28-Jun-2008">
  <help_section application="mytools" id="ifac1e66" title="MRI - UNO Component Introspection Tool ">
    <topic id="mytools/mytools.mri/index.xhp">MRI ヘルプ</topic>
    <node id="wa0b048d" title="全てのページ">
      <topic id="mytools/mytools.mri/index.xhp">トップページ</topic>
      <topic id="mytools/mytools.mri/Configuration.xhp">設定</topic>
    </node>
  </help_section>
</tree_view>

検索

拡張ヘルプ中の全文検索は 3.1 から利用できます。インデックスは自動的に作成されます。

モジュールリスト

ヘルプビューアの左上にあるモジュールリストへの登録はサポートされていませんし、サポートされる予定もありません。

詳細ヒント

詳細ヒントオプションを有効にしているときやヘルプ - ヒント機能 (Shift + F1) を利用したときに表示されるツールチップの項目を作成します。

詳細ヒントはコマンド実行の URL またはダイアログコントロールの URL ヘルプ (HelpURL プロパティ) に関連付けます。そのため、ダイアログやメニューの項目、ツールバーのボタンなどのコマンド URL は URL ヘルプが必要です。

詳細ヒント項目の作成設定には ahelp タグを使用します。コントロールなどと関連付けるためにコマンド URL を hid に hid/コマンド URL (または URL ヘルプ) の形式で指定します。ヘルプを普通に閲覧したときに表示されるかどうかは visibility に表示 visible または非表示 hidden を指定します。

<ahelp hid="hid/mytools.Mri:edit_type" visibility="visible">
オブジェクトの型です</ahelp>

詳細ヒントを正しく表示させるには、同じページに bookmark が必要です。

<bookmark xml-lang="en-US" id="bm_123i3" branch="hid/mytools.Mri:edit_type"/>

画像

拡張ヘルプへの画像の挿入は 3.1 でサポートされる予定です i83627。

image タグの src 属性に画像の URI を設定します。

<image id="image_0123" src="ext.id/images/icon.png"></image>

src="ext_id/../../../images/icon.png" などのような指定も可能。

既存のヘルプで使用されている画像は OOo インストールディレクトリの share/config/images.zip ファイルに含まれています。

たとえば、警告マークは次のような URL で指定します (paragraph role="warning" で表示されるもの)。

vnd.sun.star.pkg://
file:%2F%2F%2FC:%2Fusr%2Flocal%2FOOo%2FOOo2.4%2Fshare%2Fconfig%2Fimages.zip
/res/helpimg/warning.png

ヒント

電球マークが表示されるヒントは paragraph に role="tip" を指定します。

<paragraph role="tip" id="par_idlsejof" xml-lang="ja">something hints</paragraph>

注釈

画鋲マークが表示される注釈は paragarph に role="note" を指定します。

<paragraph role="note" id="par_idsejose" xml-lang="ja">notices</paragraph>

警告

エクスクラメーションマークが表示される警告は paragraph に role="warning" を指定します。

<paragraph role="warning" id="par_idselfne" xml-lang="ja">WARNING</paragraph>

段落

段落は paragraph に role="paragraph" を指定します。

見出し

見出しは paragraph に role="heading" を指定、見出しレベルは level="1" として数値で指定します。見出しレベルは 1-6 が利用できます。

<paragraph role="heading" id="hd_idhaosel" xml-lang="ja">Heading</paragraph>

コード

コードを表示する場合は paragraph に role="code" を指定します。これは p タグに変換されますが pre では無いため whitespace が圧縮されて表示されるため見難い表示になります。一応、CSS では等幅フォントが指定されています。

<paragraph role="code" id="par_idxlsel" xml-lang="ja">code</paragraph>

<list type="unordered" bullet="disc">
 <listitem>
  <paragraph role="paragraph" id="par_idmtl0001" xml-lang="ja">Lv1 リスト１</paragraph>
 </listitem>
 <listitem><paragraph role="paragraph" id="par_idx2cb349f" xml-lang="ja">Lv1a１</paragraph>
  <list type="unordered" bullet="circle">
   <listitem>
    <paragraph role="paragraph" id="par_ida3c51a8f" xml-lang="ja">Lv2</paragraph>
   </listitem>
  </list>
 </listitem>
</list>

<list type="ordered" format="1">
 <listitem>
  <paragraph role="paragraph" id="par_idj8593cc2" xml-lang="ja">Lv1</paragraph>
 </listitem>
 <listitem>
  <paragraph role="paragraph" id="par_idv78840d8" xml-lang="ja">Lv1a</paragraph>
  <list type="ordered" format="i">
   <listitem>
    <paragraph role="paragraph" id="par_idzc4024c1" xml-lang="ja">Lv2</paragraph>
   </listitem>
 </listitem>
</list>

表

表は table タグで作成します。行を tablerow で、セルを tablecell で作成します。

(rowspan および colspan は変換されません。)

<table id="tab_idta492e5a">
 <tablerow>
  <tablecell>
   <paragraph role="paragraph" id="par_idhf4c3f39" xml-lang="ja">language</paragraph>
  </tablecell>
  <tablecell>
   <paragraph role="paragraph" id="par_idb2b0188c" xml-lang="ja">localization</paragraph>
  </tablecell>
 </tablerow>
 <tablerow>
  <tablecell>
   <paragraph role="paragraph" id="par_idd73a1ca2" xml-lang="ja">en</paragraph>
  </tablecell>
  <tablecell>
   <paragraph role="paragraph" id="par_ida82aefd1" xml-lang="ja">en-US</paragraph>
  </tablecell>
 </tablerow>
</table>

リンク

他のヘルプページや外部へのリンクは link タグで行います。リンク先は href に、リンク名は name に指定します。

同じ拡張機能ヘルプへのリンクは次のように指定します。mytools.Test は拡張機能 ID です。

<link href="mytools.Test/sub1.xhp" name="link to">...</link>

拡張機能ヘルプ内のページから既存のヘルプページへのリンクも行えます。

<link href="text/module/dir/page.xhp#anchor" name="">...</link>

ブックマーク、セクション、段落へのアンカーが利用できることになっていますが、実際には段落の id がアンカーに変換されないためブックマークまたはセクションにしかアンカーを使ったリンクはできません。また、variable タグでもアンカーが生成されます。

埋め込み

3.x でサポートされる予定 i86430。

強調

emph タグで強調が行えます。emph タグは表示時に strong に変換されます。そのほかの斜体などは利用できません。

改行

br タグ。

Extensions/Help

Menu

Search

recent(15)

拡張機能ヘルプ

概要