Top > Extensions > Help

拡張機能ヘルプ Edit

OOo 2.4 から拡張機能のヘルプを OOo のヘルプビューアで見られるようになりました。

ダイアログコントロールやメニューに対してヘルプのページを関連付けてやることでヒントによる拡張ツールチップや F1 キーでの該当するヘルプページを開くことができます。

拡張機能により拡張機能ヘルプをインストールした場合、ヘルプに反映されるようにするには一度 OpenOffice.org を再起動する必要があります。

help-1.png

概要 Edit

OOo のヘルプファイルは OOo のインストールディレクトリにある help ディレクトリに言語ごとに入れられています。

さらに、モジュール (swriter, scalc など) ごとに分割されています。それぞれのモジュールには次のような拡張子を持つファイルがあり、それぞれ次のような内容のデータを保持しています。

  • .jar: xhp ヘルプファイルを含むアーカイブ
  • .idx: 検索用インデックス
  • .cfg: XSLT 時などの設定
  • .tree: ツリー表示用
  • .db: lookup table データベース(?)
  • .ht: ヒントでの拡張ツールチップテキスト
  • .key: hid のエントリー

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

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

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

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

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

ファイル配置 Edit

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

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

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

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

tree.png

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

manifest.xml Edit

拡張機能ヘルプのファイルタイプは 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>

索引への登録 Edit

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

索引への項目の登録は 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"

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

ツリー Edit

一覧ツリーへの登録

ツリーへの登録は 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>

検索 Edit

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

モジュールリスト Edit

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

詳細ヒント Edit

詳細ヒントオプションを有効にしているときやヘルプ - ヒント機能 (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>

ahelp 内では書式、改行、variable、リンクは利用できません。

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

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

画像 Edit

拡張ヘルプへの画像の挿入は 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

ヒント Edit

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

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

注釈 Edit

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

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

警告 Edit

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

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

段落 Edit

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

見出し Edit

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

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

コード Edit

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

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

リスト Edit

リストは list タグで作成します。

番号なしリストは list タグに type="unordered" を指定します。

番号付きリストは list タグに type="ordered" を指定します。

(どちらも format は変換されません。)

リストの項目は listitem で作成します。

<list type="unordered" bullet="disc">
 <listitem>
  <paragraph role="paragraph" id="par_idmtl0001" xml-lang="ja">Lv1 リスト1</paragraph>
 </listitem>
 <listitem><paragraph role="paragraph" id="par_idx2cb349f" xml-lang="ja">Lv1a1</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>

Edit

表は 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>

リンク Edit

他のヘルプページや外部へのリンクは 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 タグでもアンカーが生成されます。

埋め込み Edit

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

強調 Edit

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

改行 Edit

br タグ。


Attach file: filehelp-1.png 568 download [Information] filetree.png 557 download [Information]

Reload   New Lower page making Edit Freeze Diff Upload Copy Rename   Front page List of pages Search Recent changes Backup   Help   RSS of recent changes