DocBookを使用したドキュメントの開発

私たちのプロジェクトでは、原則に従って、技術文書のメンテナンスが開発者の肩に完全にかかっているということが起こりました。プロジェクトコードを変更し、文書を更新しました。 ドキュメント自体は、VCSでソースコードとともに保存されたWordドキュメントのコレクションでした。 開発組織へのこのアプローチは長い間存在していましたが、数年前に、MS Office以外のツールを使用してプロジェクトドキュメントを維持する可能性を考慮することにしました。





これにはいくつかの理由がありました。

• 最初の、そしておそらく最も重要なものは、ファイルを一緒に編集するときの頻繁な競合です。
• 2番目の理由は、多くのドキュメントがありますが、それらはすべて類似した構造を持ち、コンテンツの点で多くの点で重複していることです（プロジェクトのアーキテクチャのため）。 そして、真のプログラマーとして、私たちはテキストの「複製」に満足していませんでした。
• そして最後に、設計スタイルとの永遠の闘争。

これらの問題はすべて互いに重なり合っており、文書を更新するというあまり愛されていないプロセスであり、厳しさという点では耐え難い罰です。 達成感のある数時間の執筆の後、あなたはSVNの変更を「記入」しようとし、誰かがあなたより速いか、単に作業を始める前に更新するのを忘れたという悲しいニュースを受け取ります。 いずれにせよ、これは煙の中断を少し延期する必要があることを意味しました。 テキストに加えて、かなりうらやましい規則性で、何らかの理由で「壊れた」デザインスタイルに注意を払う必要がありました（たとえば、リストの番号付けは最初から始まり、それが続く場所まで）。 さらに、そのような「内訳」がすべて簡単に解消されるわけではなく、Wordが何らかの独自の生活を送っているように思われ、デザインの要望について気にしません。



したがって、MS Wordに代わる方法は、次の基準を満たすことでした。

1. ドキュメント保存用のテキスト形式-VCSでの作業に便利です。
2. ドキュメントのデザインと様式化の幅広い可能性をサポートします。
3. 最終ドキュメントをフラグメントに分解する機能-再利用。
4. 最終ドキュメントをさまざまな形式で公開する機能。

長い検索の結果、要件を満たすソリューションがそれほど多くないことがわかりました。DITAとDocBookです。 DITAはすぐに「強力」で移行が困難に思えましたが、DocBookでは停止することにしました。 一般的に、代替ソリューションの検索は非常に段階的でしたが、「そのように生きることはできません」とDocBookへの完全な移行に気付く前に、1日以上が経過し、その時点で手にあったものについて多くの実験が行われました。 まず、WordML形式でドキュメントを保存しようとしました。これにより、変更のマージに関する問題がある程度解決されました。現在、マージは常に競合で終わるわけではありませんが、マークアップでの競合の手動解決は非常に不快でした。 また、ドキュメントをフラグメントに分割して、競合の変更の可能性を減らし、それらを再利用しようとしました。 アイデアは非常に失敗しました。 私たちの意見では、彼はすべての問題を排除すべきだったので、徐々に試行錯誤を繰り返して、DocBookに完全に切り替えることにしました。

DocBookとは何ですか？

突然、誰かが知らなかった場合、 DocBookはドキュメントを記述するための標準であり、コンテンツを標準化する以外には何の役にも立ちません。 さらに、この標準は非常に古く、多くの理由が何らかの理由ですでに廃止されていると考えられています。



DocBook形式でのドキュメントの記述は、HTMLでの作業と非常に似ています。独自のタグとその使用ルールのみが使用されます。

<book> <chapter> <title>First Chapter</title> <para>Hello world!</para> </chapter> </book>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

この例は、「Hello Word！」というテキストを含む段落を含む「First Chapter」というタイトルの1つの章で構成される本の説明を示しています。 タグの完全なリストとそのアプリケーションの例は、プロジェクトWebサイトwww.docbook.orgにあります。 私自身は、コンテンツを記述するためのタグのセットは非常に（非常に非常に）大きいですが、日常業務では約20を使用していることに注意してください。

DocBookドキュメントの変換

DocBookドキュメントを読み取りまたは印刷に適した形式にするためには、トランスフォーマー（または複数のトランスフォーマーのコンベヤー）を使用する必要があります。トランスフォーマーは、ドキュメントの内容および通常はデザインスタイルに基づいて、最終的なドキュメントを形成します。











DocBook -xslは通常、変換に使用されます（ただし、よりエキゾチックな方法があります）。 箱から出して、すでにいくつかのドキュメント形式をサポートしています-html、xsl-fo、マンページなど。別のプレゼンテーション形式が必要な場合は、変換の連鎖を続けることができます。 したがって、PDFのドキュメントを取得するには、通常、次のスキームを使用します。











そして、ここから楽しみが始まります。 デフォルトでDocBook-xslに実装されたスタイルを使用すると、通常の外観のドキュメントを取得できますが、通常はカスタマイズが必要です。



docbook-xslスタイルの開発者はこの機会を引き受け、このための特別なメカニズムを実装しました。

• サポートされている各形式のドキュメントを作成するための最も一般的なパラメーターは、個別のparam.xslファイルに含まれており、それぞれに多少詳細な説明があります。
• カスタムパターンを作成するための特別なパターンがあります。
• その後の再定義のために、デフォルトで特別な空のテンプレートが存在します。

ほとんどの場合、ドキュメントの形成プロセスを制御するために、他のすべての変換パラメーターの微調整がすでに実行されている、いわゆる「ドライバー」と呼ばれる独自のXSLルートスタイルが開発されています。 DocBook-xslの最終フォーマットはそれぞれ独自のテンプレートセットで表されるため、各テンプレートの「ドライバー」は個別に記述する必要があります。 たとえば、2つの最終的なドキュメントプレゼンテーション形式（xsl-foとhtmlhelp）を使用しているため、2つの「ドライバー」と2組の再定義されたスタイルがあります。

xsltおよびfoプロセッサーの選択

DocBook-xslを使用するには、xsltバージョン1.0をサポートするxsltプロセッサが必要です。 （バージョン2.0にはdocbook-xslの実装がありますが、どれだけ安定しているのかわかりません）。 現在、多種多様なプラットフォーム用の多くの実用的なソリューションがあります-したがって、これに問題はないはずです。 プロジェクトでは、古いバージョンはSaxon 9.1.0.8Jですが、EXSLT拡張機能の最後の無料のフリーウェアサポートは完全に削除され（ドキュメントプロファイリングに必要）、スタイルに付属する構文強調表示をサポートするためのサクソン拡張機能は確実ではなかったため、プロジェクトではサクソンを使用します新しいもので動作します。



xsl-foからドキュメントを生成するには、foプロセッサーが必要です。 ここで事態は少し悪くなっています-稼働中のプロセッサーから、私は個人的に2つのFOP（オープンソース）とXEP（RenderX XEPエンジン-少し有料）を試しました。 プロセッサにはさらにいくつかの作業がありますが、私は個人的にそれらで作業しようとしたことがなく、それらについて何も言うことができません。



FOPの主なプラスは無料ですが、マイナスもあります-箱から出して、ロシア語をサポートしていません。 初めて彼に会ったとき、キリル文字を使うことはできませんでした。 奇妙なことに、これに関する多くの記事がインターネット上にありますが、それらはすべて非常に古かった（必要なフォントでFOPを再構築することが提案されていた）か、望ましい結果を達成できないエラーが含まれていました。 結局、すべてが非常にシンプルであることが判明しましたが、私たちの選択はすでにXEPにかかっていました。 XEPは、インストール直後にキリル文字で正常に機能し、原則として追加の構成は必要ありませんが、費用は400ドルです-デスクトップバージョンです。 レンダリングの品質の違いを判断することはできませんが、ご自身の関心のために比較することができます（この例では、両方のfoプロセッサーによって収集されたファイルがあります）。

カスタマイズスタイル

スタイルを高品質に設定するには、xsl変換言語と最終ドキュメントのマークアップ言語を少し知っている必要があります。 残念ながら、DocBookへの移行時にチームにはそのような能力がなかったため、セットアップには十分な時間がかかりました-特にFO形式の場合。 これに関する情報が掲載されているサイトはインターネット上に多数ありますが（特に私の意見では「 DocBook XSL：完全ガイド 」）、完全な画像をすぐに取得することは非常に困難です。 そのため、「100回聞くよりも1回見る方が良い」という原則に基づいて行動することにし、xsl-foのスタイルの例（プロジェクトで使用しているものとほぼ同じ）をこの記事のソーステキストと構成済みのFOPと共に準備しました。



私がやめたいのは、最初は混乱する可能性がある唯一のポイントは、ドキュメントのフォントと言語を設定することです。 デフォルトでは、キリル文字をサポートしないフォントはxsl-foに含まれており、これらのパラメーターをオーバーライドしたり間違えたりしない場合（指定されたフォントで動作するようにfoプロセッサーが構成されていることを確認する必要があります）、foプロセッサーから読み取り不能な出力を取得する可能性が高くなりますドキュメント。 文書の言語は、本の要素（章、本など）の名前の定型句の作成に影響します。 原則として、これらのパラメータのみを設定すると、すでに「正しい」ドキュメントを取得できます。 また、ほとんどの場合、ドキュメントの表紙の外観を変更したいという要望があります。 これは、docbook-xslで特別に準備されたテンプレートを使用して実行できます。 これを行うには、ファイル「/fo/titlepage.templates.xml」のバージョンを定義し、xsltプロセッサとテンプレート「/fo/titlepage.templates.xsl」を使用して、「ドライバー」に接続するためのカスタマイズされたデザインスタイルを取得する必要があります。 場合によっては、組み込みの構成メカニズムでは十分ではないため、ドライバーで元のdocbook-xslスタイルを明示的に再定義する必要があります。

おわりに

DocBookへの完全な移行には多くの時間がかかりました。 第一に、彼にすでに書かれた文書を持参する必要がありました。 ここでは、AntiWordなどのさまざまなユーティリティを試しましたが、アーティファクトの数が多いため、手動で行うことにしました（アーティファクトは、元のドキュメントのフォーマットエラーと翻訳スクリプトの特性の両方のために取得されました）。 また、独自のデザインスタイルを開発し、ドキュメントを開発するための環境を検索する（結果として、NotePad ++で解決しました）および環境設定に時間がかかりました。 簡単な作業のように見えましたが、実装されたとき、常にいくつかの問題に遭遇しました。 残念ながら、DocBookにはあまり情報がなく、ロシア語のセグメントについて話すと、事実上まったくありません。 しかし、最終的には満足しました。



私たちのチームがDocBookで技術文書を管理するように切り替えてから1年以上が経過しましたが、他のオプションは考えられなくなりました。 DocBookに切り替えることで達成したかったすべて-私たちは達成しました：

• 彼らは、GitFlowを使用している場合でも、VCSで作業しているときのドキュメントの矛盾を忘れていました（記事の冒頭と同じ注意：変更を加えた-ドキュメントに反映）。
• 異なるドキュメント内の同じテキストの重複をほぼ完全に取り除きました。 DocBookプロファイリングのおかげで、ドキュメントの柔軟性が向上し、ドキュメンテーションの作成が退屈になりませんでした。 元の文書の非常に複雑な分解により、文書のナビゲーションとその後の編集が非常に複雑になるため、これが比例の主な意味です。
• Wordで文書をフォーマットする方法をほとんど忘れていました。または、単にフォーマットする方法を忘れていました。 現在、ドキュメントの開発は、ドキュメントのテキストを書くだけです。
• 全体的なソフトウェア開発プロセスへの統合という点での創造性の大きな範囲。

当然、長所に加えて、欠点もあります。

• 現時点で最も差し迫った問題は、会社の他の部門とのやり取りです。 明らかな理由により、私たちのチームだけがDocBookに切り替え、他の人はすべてMS Wordを使用し、データを交換する必要がある場合は、手動で行う必要があります。 幸いなことに、これは非常にまれであり、通常は数段落のテキストに限定されます。
• 特に、ドキュメントの書式設定に非標準のDocBookアプローチを実装する複雑さは、多くの場合、横向きで複数のページを拡張する必要がありますが、それを行う方法を（残念ながら）まだ学習していないため、この瞬間を何らかの方法でバイパスする必要があります。 しかし、私はこれができることを100％確信しており、したがって、この問題の未解決の性質は、緊急性の低い必要性によって説明できます。 たとえば、ドキュメントに数式を挿入する必要がある場合、MathMLを台無しにするのに正午もかかりませんでした。

また、この記事の目的は、オフィスプログラムで技術文書を作成している読者に、より適切なツールがあることを伝えることです。 しばらくの間DocBookやDITAを検討している人にとって、移行を後押ししてヒントを与えることは、開始するのが最も難しい部分です！ また、他のチームがどのアプローチを採用し、その実装の経験を聞くのも非常に興味深いでしょう。



参照：

• http://docbook.sourceforge.net/
• DocBook XSL：完全ガイド
  
  
• http://www.docbook.ru/
  
  

例：

• https://github.com/