統合仕様書リッチテキスト化への道のり

TOPPERS Advent Calendar 2020 13 日目の記事です。

統合仕様書誕生のきっかけ（たぶん）

　おそらく真相は最終日に（少し）語ってくれるのではないかと思いますが…
第1世代カーネルと呼ばれるJSPカーネル、FDMPカーネル、FI4カーネル、HRPカーネルの開発当時は統合仕様書はありませんでした。それぞれITRON仕様のμITRON4.0スタンダードプロファイル、フルセット、PX仕様に準拠する実装ですすめていたため、仕様に関する情報はそちらを参照してもらうことにしていました。（ユーザマニュアルなどのドキュメントはありましたが）
　第2世代カーネルはμITRON4.0仕様の実装を行う中で得られた知見をフィードバック¹するためのシリーズとなっています。そのためμITRON4.0仕様、XP仕様の差分のドキュメントを作成するということにはせず²、新しく仕様書を作成しようということで統合仕様書の策定³がすすめられてきました。

リッチテキストの試行

　TOPPERS統合仕様書は2008年にリリースされたR1.0.0から2018年のR3.2.0までの10年間はPDFでした。
プレーンテキストに行番号が振られていましたが 目次、リンクといった機能が無い ものでした。そのため会員によるリッチテキストの試みが行われています。
Meika SugimotoさんによるTOPPERS新世代カーネル統合仕様書リッチテキスト版がTOPPERSのコントリビューテッドソフトウェアとして(R1.4.0, R1.5.0, R3.0.0)が登録されています。

いまではAPIの名前はすぐに出てきますが、当時は仕様書のカーネルAPI機能の各機能に書かれている内容からAPIを見つけるとかリファレンスにあるサービスコール一覧から目的のAPIの引数を見つけるということをしていたため、仕様書の見出し機能はとても欲しい機能でした。
Meikaさんのリッチテキスト化は大変助かりました、そして仕事でも仕様書を使う機会が増えてきて独自で作成する試みがはじまりました。

DITAによる検討

　そのちょっと前、職場でDITAによるドキュメント作成の試行検討が始まりました。
ソフト屋でドキュメント書くならOfficeツールを使わずにテキストベースでPDFやhtmlを作ろうということです。
DockBook⁴やTeXなど検討していたと思いますが、OSSツールもありマルチフォーマットへの出力も可能で技術文章での実績もあるというDITAに狙いをさだめることにしました。
DITA-OTを使った当時の検討は別のブログに残しています。XMLの記述や日本語化に悩みながらも⁵製品のEclipseヘルプドキュメントやPDFなどをSVNのコード管理ツールで扱えることができました。
またDITAのトピック志向を活かしたコンテンツ作成は統合仕様書でも適用できるのではという手ごたえを感じていました。

開発者会議での提案とコメントダメ出し

　前職のメンバーがDITAの紹介をしたのは第10回のTOPPERS開発者会議からだと思います。この前後の議事録や実施内容の記録が無いのですが、会議案内のプログラムから見るとトレーサビリティの取り組みや要求仕様書などドキュメントに関連する議論が活発になっていました。
　そんな中、2012,2013年のTOPPERS開発者会議のメイン議論としてDITAを取りあげてもらうこととなりました。DITAでリッチテキスト化ができないかということで、個人でポーティングガイドラインをDITAでリライトして、PDFとhtmlを作成することができた内容を発表したのですが次のようなコメントをもらいました。

• アイデアやトピック志向はいいが、XMLのタグを記述するのは敷居が高い
• DITAを記述する無償のXMLエディタは無いのか？（当時はoXygenが使えるエディタとしてあったが有償）
• ヘッダ・フッタなどはDITA-OTのカスタマイズが必要だけど、OTに手をいれるのは大変
• 日本語対応など有償のレンダラーを使わないとPDF品質的には公開は難しい

リッチテキスト化には賛成だけど、プレーンテキストでの管理だったためSVNでもドキュメント差分が明確になるため、それを損ねてまでDITAのタグをいれるのはデメリットの方が大きいため保留といという結論となりました。

Asciidocによる統合仕様書のリッチテキスト化と今後

　これらの課題をどうやって解決しようかと悩んでいるうちに世間はwiki⁶などから始まったMarkdownなど軽量マークアップによるドキュメント作成が使われるようになってきました。
XMLのタグを書くよりは可読性もあがるためこれで書いてみようという事で、reStructuredText⁷、AsciiDoc、Re:VIEW、RDocなどを検討しました。第3世代カーネル開発ではruby環境は必須となり、エディタによるプレビューが可能だったりオライリーで使っているなどの実績からAsciiDocをチョイスしました。
Asciidoctorを使って統合仕様書のリライトを行ったところ数日でできたため、TOPPERSコンテストの（すべりこみの）応募にあわせて⁸、AsciidocからGithubPagesへの自動出力などの作業を行って、2016年の開発者会議で再度発表に臨みました。

発表後のハッカソンで仕様書のプレーンテキストの構造から軽量マークアップのタグ付けをするスクリプトを会長に作成してもらうことででき、リッチテキスト版の公開へと進んでいます。

　いまは統合仕様書のhtml化を個人で行っていますが、要望やコメントがあればMLやissueなどでご連絡ください。
その間にも統合仕様書は仕様タグなどコンテンツのボリュームが充実してきました。トレーサビリティの見える化やドキュメント（トピック）の再利用などでDITAの重要性は増していると思います。ドキュメント管理の利便性なども考えながら技術ウォッチをしていきたいです。

1. さらにHRPカーネル開発はJAXAと共同開発もあり、高信頼性OSの仕様書を作成するという(苦い貴重な)経験も大きかったです。 ↩

2. クラリスがFileMakerを止めてBentoに切り替えるなんていう話もありました。 ↩

3. 仕様書のレビューは第6回TOPPERS開発者会議で行われています。 ↩

4. 調査当時トロンフォーラム(旧T-Engineフォーラム）のドキュメントはDocBookで書かれていた(いまはわかりません) ↩

5. XMLやモデリングへの茨の道はここから始まったのかも…。 ↩

6. そういえばBTRON wikiなる記法も前職メンバーが作成したんだった... ↩

7. TECSのドキュメントはSphinxを使用　https://tecs-docs.readthedocs.io/ja/latest/index.html ↩

8. このあたりの話はすでに記事にしてました https://qiita.com/mitsu48/items/adc0c48fa7a60a36d883 ↩