Linuxのツールを使って本格的なドキュメントを作成する

ドキュメントの作成は、ソフトウェア開発における必要悪である。Linuxには、FrameMaker、RoboHelp、WebWorks Publisherのような標準的なWindowsのツールこそないが、テクニカル・ライターが仕事をするうえで必要な環境は整っている。Linuxのユーザは、フリー/オープンソース・ソフトウェア(FOSS)とプロプライエタリなソフトウェアの両方を含む、数々のドキュメント作成ツールを利用できる。それらのツールは、どれもテクニカル・ライターが本格的なドキュメントを作成し、発行するのに十分な機能を備えている。

DocBook Projectはアプリケーションではないが、おそらくLinuxのテクニカル・ライティングの総本山と言えるだろう。DocBookは、ソフトウェアやハードウェアのマニュアル作成用に特に設計されたXMLの変種である。DocBookを使うと、PDFやPostScript(印刷用)、HTML、HTMLヘルプ、JavaHelpをはじめ、複数の形式でドキュメントを出力することができる。また、内容がほぼ同じで、対象のユーザやオペレーティング・システムだけが異なる複数のドキュメントを作成することもできる。これにより、すべての情報を複数のドキュメントに分けずに、1つのファイルに格納することが可能になる。

DocBookファイルはXMLなので、好みのXMLエディタやテキスト・エディタで編集できる。EmacsにpsgmlxパッケージやnXMLパッケージを組み込んで使用するライターもいれば、Vimとこちらこちらのようなスクリプトを組み合わせて使用するライターもいる。VimをDocBookエディタとして使用する方法は、チュートリアルで説明されている。EclipseベースのXMLエディタVexや、Javaで書かれたWYSIWYGエディタのXMLmind XML Editor(XXE)も優れたDocBookエディタである。

DocBookの出力を得るには、XSLプロセッサを使ってファイルにXSLスタイルシートを適用する。スタイルシートによって出力形式が決まり、XSLプロセッサによって単調な処理が実行される。多くの形式では、一般的なSaxonやxsltprocなどのXSLプロセッサを使うことができる。PDF、PostScript、またはRTFファイルを作成する場合は、まずドキュメントをXSLプロセッサにかけてから、XSL Formatting Objects(XSL-FO)プロセッサにかける。XSL-FOプロセッサには、フリーのFormatting Objects Processor(FOP)や商用のRenderX XEP Engineなどがある。FOPとXEPは、どちらもコマンドライン・ツールである。GUIを使いたい場合は、XMLmind FO Converter(XFC)を検討するとよい。これはXSLプロセッサとXSL-FOプロセッサをポイントアンドクリック・パッケージに統合したものである。

DITA

ここ数年にわたり、Oasis Darwin Information Typing Architecture(DITA)が多くのテクニカル・ライターの注目を集めるようになり、DocBookのマーケット・シェアを浸食しつつある。 従来の本/章/節という形式をベースにする代わりに、DITAは個別のトピックを作成し、それらを組み合わせて各種のドキュメントやさまざまな配布形式で再利用できるように作られている。DITAは、ほぼすべての種類のドキュメントの作成に利用できるが、Webコンテンツ、オンライン・ヘルプ、コンピュータベースのトレーニング、サポート技術情報、およびFAQの作成に最も適している。

DITAはXMLベースなので、好みのテキスト・エディタやXMLエディタを使ってDITAドキュメントを作成できる。さまざまな編集ツールがDITAをサポートしており、かつLinux上で動作する。私の好みのテキスト・エディタはEmacsとpsgmlxの組み合わせで、これをDocBookで使用している。XXEもDITAをサポートしているが、現在のバージョンではDITAドキュメントを他の形式に変換できない。また、XXEはDITA conref 属性(他のDITA要素への参照を保存してコンテンツを再利用するしくみ)をサポートしていない。

現在のところ、LinuxでDITAドキュメントをより利用しやすい形式に変換する唯一の方法は、DITA Open Toolkit for Linuxを使うことである。Open Toolkitは使いやすく、DITAコンテンツをHTML、XHTML、PDF、Eclipse Help、またはRTFに変換することができる。

オンライン・ヘルプ

世の中には、マニュアルを読むことはおろか、目を通すことさえ嫌がり、F1キーを押してヘルプを参照する方法を好む人々がいる。Linuxのヘルプ・オーサリング・ツールは、Windowsのオーサリング・ツールにはかなわないものの、オンライン・ヘルプの作成に役立つ強力なツールがいくつか存在する。

広く利用されているQuickHelpアプリケーションは、グラフィカルなヘルプ・オーサリング・ツールで、ヘルプ・トピックを簡単に記述して書式を設定することができる。また、トピックを編集し、ナビゲーション、索引、それに簡単な検索エンジンまで備えた見栄えのするヘルプ・システムを作り上げることもできる。ただし人によっては、QuickHelpが有料であることが短所となるだろう。

JavaHelpは、Javaで書かれたソフトウェアのオンライン・ヘルプを提供するように作られている。JavaHelpは強力で柔軟なシステムであり、LinuxにはJavaHelpシステムを作成するためのいくつかのオーサリング・ツールが用意されている。たとえば、JHelpDevとJHelp Builderは、いずれもJavaHelpシステムに必要なヘルプ・トピックとすべての関連ファイルを作成できるグラフィカルな環境を備えている。DocBook XMLでもJavaHelpを出力することができる。

HelpSetMakerは、グラフィカルなヘルプ・オーサリング・アプリケーションで、HTML、JavaHelpシステム、またはLaTeXで組版できるドキュメントを出力することができる。インタフェースでヘルプ・トピックを入力するだけで済み、画像やハイパーリングを追加することもできる。HelpSetMakerに対する私の主な不満は、インタフェースがあまり直感的でないことだ。使い方を会得するまでに、かなりの時間をかけてオンライン・ヘルプを参照する必要がある。

複数のオペレーティング・システムを対象にヘルプを作成する必要がある場合は、WebHelpを検討するとよい。WebHelpは、オンライン・ヘルプやドキュメントをWebブラウザで提供する手段である。WebHelp形式(HTMLとJavaおよびJavaScriptの組み合わせ)は、AdobeのMacromedia RoboHelpによって普及したが、WebHelpという用語は多くの場合、ブラウザベースのオンライン・ヘルプ・システム全体を表すために使われる。通常、テクニカル・ライターはRoboHelp、AuthorITMadCap Flareなどのツールを使ってWebHelp風のシステムを作成する。RoboHelpにはLinuxバージョンはないが、DocBookスタイルシートで基本的なWebHelpシステムを生成することができる。スタイルシートの使い方については、こちらの簡単なチュートリアルを参照してほしい。

ワード・プロセッサ

私はドキュメントを書くときにワード・プロセッサを使うことはめったにない。ワード・プロセッサは、巨大で複雑なドキュメントを扱うのに最適なツールではないからである。しかし、リリース・ノート、ホワイト・ペーパー、技術的なマーケティング資料など、たいていテクニカル・ライターが作成せざるを得ない短いドキュメントには、ワード・プロセッサが適している。

Linuxで最も強力なワード・プロセッサは、OpenOffice.org WriterとSoftMaker TextMakerである。これらの堅牢なワード・プロセッサは、優れたグラフィック処理機能、柔軟なテンプレート、しっかりしたインポート・フィルタ、および追加のソフトウェアなしにPDFファイルを生成する機能を備えている。私はこれらのワード・プロセッサでたくさんの短いドキュメントを書いてきたが、特に不満な点はない。

FOSS純粋主義の現場では、クローズドソース・ソフトウェアであるTextMakerを使うことにためらいがあるかもしれない。適切なFOSSの代替品と言えるのがAbiWordである。AbiWordはTextMakerと同レベルとは言い難いものの、価格は魅力的である。それに短いドキュメントであれば、AbiWordは十分に機能を果たす。

ワード・プロセッサを使って何かを書くときは、テンプレートの作成に時間をかけ、テンプレートのスタイルをテキストに適用して、すべてのドキュメントで一貫した外観が保たれるようにする。

開発者ドキュメント

ソフトウェア開発者にとって、コードのドキュメント作成は重労働である。実際、あらゆるテクニカル・ライティング作業の中で、おそらく最もつらい仕事だろう。

幸い、ソース・コードのドキュメントを生成してくれる優れたアプリケーションが数多く存在する。たとえば、Doxygen、DOC++、ROBODocNatural Docsなどがある。これらのツールでは、C/C++、Java、Perl、IDLをはじめとする複数のプログラミング言語から複数の形式のドキュメントを生成できる。

ソース・コードのドキュメント作成ツールは、すべての作業を肩代わりしてくれるわけではない。アプリケーションを正しく動作させるために、開発者はコードにコメントを付ける必要がある。また、ライターはツールの出力に情報や例を追加する必要がある。それでも、これらのツールを使うとコードのドキュメント作成が非常に容易になる。

その他のツール

テクニカル・ライティングの仕事は、書くことだけにとどまらない。ドキュメントの作成では、グラフィックや図を扱うことや、画面の画像を取り込むことも必要になる。

画像を編集する必要がある場合は、おそらくGIMPがLinuxの最良のツールと言えるだろう。GIMPは強力な画像編集機能を備えているだけでなく、アプリケーション・ウィンドウの例が必要なときには画面の取り込みを行うこともできる。検討すべきもう1つのアプリケーションがKritaで、これはKOfficeスイートに含まれる画像エディタである。

XVは、画像を操作し、スクリーンショットを取り込むための小さくて便利なツールである。XVのインタフェースは美しいとは言えないが、処理をすばやく簡単にこなしてくれる。

画面の取り込み(場合によってはそれ以上のこと)ができるユーティリティには、ほかにImageMagickKSnapshot、xwd(X Window System dumpユーティリティ)などがある。GNOMEでは、[System]メニューの下の[Take Screenshot]コマンドを使うか、Alt+PrintScreenキーを押してスクリーンショットを保存できる。

図やフローチャートの処理に適したLinuxアプリケーションとしては、Sodipodi、Dia、Kivioなどがある。どのアプリケーションも、あらゆる種類の図を作成できる強力で柔軟なツールを備えている。また、よく使われる多くのグラフィック形式でファイルをエクスポートすることができる。

この記事で紹介したソフトウェアは、主要なLinuxテクニカル・ライティング・ツールのごく一部に過ぎない。数多くのドキュメント・プロセッサ、マークアップ言語、その他のツールが人知れず宝の山に埋もれている。ひょっとしたら、その中からあなたのドキュメント作成のニーズを満たすツールが見つかるかもしれない。

原文