モチベーション
（ITRON系）TOPPERSカーネルがμITRON仕様書から拡張したために、TOPPERS統合仕様書が作られたのだが、テキストファイルをPDFにしてリリースされているために、検索しづらい状況にあった。またリンクや見出し機能も無いため、仕様書の利用としては必要な時だけに利用することになっていた。
これまでの取り組み
Meika氏が統合仕様書をリッチテキスト化する取り組みが行われていて、1.4、1.5、3.0系の仕様書をリッチテキスト化する作業を行なっている。（頭が下がります）
私自身はDITAを使ったマルチドキュメント化を開発者会議などで提案してきたが、なかなか受け入れられない状況にあった。
「ドキュメント作成システム構築ガイド」との出会い
なかなかうまく進まないなと思う中、漠然とこんなことをしたいと思っていました。
- リッチテキスト・マルチドキュメントできるファイルフォーマットによる記述
- 仕様書のベースフォーマットが変えられないのなら、リライトする手間をなるべく削減する方法を考える
- 変換（リライト）したフォーマットはテキストベース（ワードは要らない子）
- PDFでは目次、リンク機能が欲しい
- htmlフォーマットも出力できるようにしたい
そんな中でたまたま出会ったのが「ドキュメント作成システム構築ガイド」でした。
AsciidocとreStructuredTextでどちらを選ぼうか悩んだのですが、最終的にはDITAで記述するのではという思いがあって、よりライトウェイトな感じのAsciidocを選びました。
本書ではGithubとTravis-CIを使ってドキュメントをGithub Pagesに出力する仕組みが書かれています。
この仕組みを採用させてもらいリッチテキスト化を取り組みました。
実際の作業
統合仕様書はPDFになっているので、そこからテキスト文字だけを抜き出すのは時間だけの問題です。
あとは見出し、API、表、などをタグ付けしてコミットしていくだけです。
とりあえず手元のマシンでAsciidoc-pdfを使って出力しながらタグをどんどん入れ込みます
出力品質は時間をかけるればどんどん上がってきますので集中して作業できました。
TOPPERS活用アイデア・アプリケーション開発コンテストへの応募
こんな作業をしていたのが、ちょうどTOPPERS活用アイデア・アプリケーション開発コンテストの締め切り間際でした。
応募をためらわれる内容・品質ではありましたが、敷居の低い応募もあるんだよ的な意味合いもこめて初応募してみました。
結果、銀賞をいただけました。それなりに需要があるテーマであると思っていただけたのかなと感じています。
その後の効果
Githubは応募して力尽きた感があるのですが、いくつかasciidocを使った効果がでてきたと感じています。
仕事のドキュメントをAsciidocベースに変更した
いままで納品ドキュメントをDITAで書いていたのですが、複数人プロジェクトのPM担当になったのでAsciidocでの作業に移行してもらいました。
最初はMarkdownでやっていたのですが、PDFするツールがWindowsとMacで微妙にかわったり、CSSの有無で簡単なものが見つからなかったので、Asciidocに移行しました。
また同じ時期にTracからGitlabへプロジェクト管理ツールも変えたので、議事録などもAsciidocで書くようにしました。
これでワードファイルを追い出すことに成功しました。パワポやエクセルはそのままですがまあ今の所は良いかなと思っています。
本家からリッチテキスト版がでるようになった
開発者会議でasciidocの話をしたところ、同様にTeXでの統合仕様書作成をされているという話があり、であれば、統合仕様書のテキストデータをAsciidocやTeXに変換するスクリプトを作成するハッカソンを高田先生と行いました。スクリプトは高田先生が書いて私の方が仕様書で必要なタグ情報をフィードバックしながらpdfとhtmlで確認するという作業で進めました。ハッカソンの枠では時間が足りませんでしたがその後、先生がスクリプトを作成されて、ベータ版という形でTOPPERSサイトに上がっています。
私ももう少しお手伝いして正式版として品質を上げていきたいです。
小さく回す もしくは 射撃しつつ前進
何度も聞いた（使い古された）言葉ですが、あらためて実感したということで。
とりあえず、手を動かしてコンテストに応募してみよう！という話でした