Zenn
Open7

DITAのトピックは原稿形式

#
dita
hidarumahidaruma

出発点となる疑問

Lightweight DITAのHDITAはHTML5で記述する。ところで、原稿群をDITA処理系へ通して最終出力される形式にはHTML（界隈ではWebHelpと呼ぶこともある）もある。このとき、基本的には各ページ（HTMLファイル）は原稿でのトピック粒度が維持されたファイルとなる。ではこのデカツールを通した変換に意味はあるのか。

hidarumahidaruma

フルセットHTMLは難しい

執筆形式；直接人間が書くフォーマットに求められるのは、ここでは記述の容易さと見通しの良さであるとする。

編集形式；執筆形式と出力形式の中間形式であり、保存形式を兼ねることがあるフォーマットとする。機械処理がそれなりに定型的に可能で、かつ、人間が読もう弄ろうと思えば可能ではあるくらい。

扨、HTML（LS）の語彙は下手なXML応用文書のそれよりも多い。WAI-ARIAなどを考慮して記述するとなると執筆形式としては複雑にすぎる。一方で、閲覧手段含め普及した形式であるから、様々な執筆形式からの変換によってこれを得ることで、便宜的に中間形式として使うことが考えられる。

HDITAはHTML5そのものではなく、XDITAをある程度反映可能なHTMLサブセットである。見出しタグに使えるのは<h2>までであるし、<kbd>のような「そんなの使えたんだ」と思うようなタグは使えない。

DITAでは、ドキュメント全体のセクショニング構造の責務はマップが負う。ドキュメント階層構造由来のリンクも同様である。トピックではそのトピックのコンテンツ内容に集中することができる。「このリンクは<nav>だっけ<menu>だっけ単なる<a>だっけ」などといったことをトピック執筆時に持ち込む必要はないわけだ。

また、トピックのコンテンツは最終出力でその形のままでないこともある。マップでの調整には、トピック内容を結合・分割するための@chunkや、トピックタイトルを変更する<topichead>といったものがある。

hidarumahidaruma

@chunkはDITA 2.0のものを使おう

トピック内容を結合・分割するための@chunk

トピックは完結性の高さを基準に管理されるコンテンツ単位である。ページ組版のときは縦に並べられていくだけなのであまり気にならないが、別ページに出力されると文章量の差であったり、前置き用のトピックと本題のトピックが分割されて座りが悪いことがある。

ところで、先にこのように書いた。

このとき、基本的には各ページ（HTMLファイル）は原稿でのトピック粒度が維持されたファイルとなる。

基本的にはとしたのはそれに沿わない場合もあるからである。具体的にはchunk属性への指定でHTML（他、トピック毎にファイルが出力される系統）の出力粒度を制御できる。この出力時の制御というのは他にもコンテンツ参照などで大いに活用するもので、逆に、編集形式のときにトピックではなく文書全体としての完成形に拘ってはいけない。

TODO chunkの使い方と例

hidarumahidaruma

マップ側でトピックタイトルに干渉する<topichead>

管理形式であるトピックはタイトルも十分に説明的であることが望ましい。たとえば、「XSL-FOのdeclarations構造」というトピックは単体として十分に説明的だ。多分。しかし、マップによって「XSL-FOの構造」の下位トピックとして収まるときに、このタイトルは冗長である。上の階層で「XSL-FOの構造」についてであることが分かるからだ。

  • XSL-FOの構造
    • XSL-FOのdeclarations構造

この場合、先のトピックのタイトルとしては「declarations」だけでもよいだろう。これはマップによる配置の都合であるから、マップで制御できると嬉しい。それをしてくれるのがtopicheadである。

<topichead >
  <topicmeta>
    <navtitle>declarations</navtitle>
  </topicmeta>
  <topicref href="fo_declarations.dita"/>
</topichead>
hidarumahidaruma

トピックグループ・集合

topicrefはネスト可能で、これはマップで階層構造を示す。とはいえ、トピック間の関係は常に階層であるわけではない。木構造上で階層関係にない関係は、topicgroupとtopicsetでそれを示す。

再利用 with topicset topicsetref

トピックごとにファイルは分けられコンテンツは完結するとはいっても、実運用上はトピック群をまとめて引き回したいということもある。その場合はマップ上でtopicsetを記述し、複数のtopicrefをまとめる。再利用が前提であるから、参照のために@idを設定する必要がある。

トピックグループ

topicgroupは複数のトピックに共通処理を挟むために使う。例示にあるのは@audienceや@linkingをまとめて指定するものだ。

topicgroupは共通処理を記述する関係上topicmetaが書けるが、トピックそのものではないのでnavtitleは書いても無視されるべきとなっている。

hidarumahidaruma

内容的にはトピック内の話、conrefやkeyrefの話なんかもrefを飛ばした方がよさそう？

hidarumahidaruma

トピック内コンテンツの再利用

トピックが原稿であって、出力と必ずしも同一視すべきでない理由は、マップ側の調整のほか、再利用戦略の柔軟性にも関わってくるからだ、形式上にトピックの形をとるということについては、マップにkeydefをまとめた形式上のマップを作るような関係と類似する。

関連資料の記事で挙げられているように、トピックをそのままtopicrefでマップに突っこむとトピックタイトルなどもひっついてくる。トピックのコンテンツだけが欲しい場合、body下にdivでも置いてこれをコンテンツ参照の対象にすればよい。「トピック単位の再利用だからtopicrefで引っぱってきてマップで加工」という思考であると「トピックタイトルが邪魔だからスタイルシートで何とかしよう」という考えに陥ってしまう。

先に共通の注意(note@type="caution")などをまとめた形式上のトピックの話などをすべきか。

関連資料