もう6年前の自分のコードを読んでいたのですがどうにもわからない点が出てきてしまいました.
それはtopicの上位にrequired-cleanupがあるがごときのコーディングが存在することです.おぼろげな記憶をたどってみたのですが、確かに何かお客様から指摘されて直したような気がします.しかし今考えてみるにどうにも納得がゆきません.何故ならrequired-cleanupはいろいろなところに書けるのですが、topicの上位に書ける様な文書モデルは存在しないように見えるからです.
言語リファレンス-基本要素-レガシー要素-required-cleanup
3.1.7.1 required-cleanup
実際の処理も
"Processors must strip this element from output by default. The content of <required-cleanup> is not considered to be verified data."
というProcessing notes:に従ってテンプレートはrequired-cleanupを無視しているだけです.
<xsl:template match="*[contains(@class, ' topic/required-cleanup ')]">
<!-- Ignore! -->
</xsl:template>
そこで、まさかと思って次のようなデータを作って試してみました.
[sample.dotamap]
<map>
<title>DITA Topic Map</title>
<topicref href="topic1.xml" format="dita"/>
</map>
[topic1.xml]
<required-cleanup>
<topic id="topic_o2k_y2n_b4">
<title>Topic title</title>
<body>
<p>Topic paragraph</p>
</body>
</topic>
</required-cleanup>
現時点のstableのDITA-OT1.8.4でビルドしてみると、このデータでエラーなしでPDFが作れてしまいました.びっくりして中間ファイルを見てみると概略次のような構造になっていました.
<dita-merge xmlns:ditaarch="http://dita.oasis-open.org/architecture/2005/">
<map>
<topicref format="dita" href="#unique_1" type="topic"/>
</map>
<required-cleanup>
<topic id="unique_1">
...
</topic>
</required-cleanup>
</dita-merge>
ちゃんとDITA-OTはtopicをrequired-cleanupの扱いにするオーサリングに対応しているようです.つまり6年前のコードはやはりちゃんと裏があってのことだったのです.
しかしこの場合、map/topicrefからはtopicがポイントされているので、required-cleanupはスタイルシートには見えません.なので無視するような処理はできないです.でもよくお客さんもこんなオーサリングテクニックを知っていて使ったものです.
やはり何年も前に書いたコードは、その時点では納期に間に合わせるようにやら、お客様からの障害報告に早く対応するように必死になって書いているのですが、あとからメンテナンスするのにはやはり苦労します.たぶん別の方にメンテナンスを頼むようになったとしたら簡単には理解はできなかったでしょう.
今後はもう少しコメントをまめに書こうと思います.コメントは「何をしているか?」ではなくて「何故そうしているか?」が大切ですね.