プログラムのドキュメント

ソフトウェアシステムの開発の特定の段階で、ユーザードキュメントを開発するタスクは必然的に発生します。 そしてここで、形式とドキュメント開発ツールの選択に関する技術的な疑問が生じます。

1.1。 出力形式

最終的な形式の選択では、ターゲットオペレーティングシステムが独自の要求を行うため、通常は問題はありません。 したがって、たとえば、Windowsプログラムの場合、これはCHMのコンパイル済みヘルプ形式であり、LinuxおよびBSDシステムの場合は人間です。 オンラインヘルプのすべてのオンラインシステムに共通の形式はhtml、および印刷-pdfです。

プログラム（chmまたはman）での配布、サイトへの投稿（html）、および印刷（pdf）のために、いくつかの形式のドキュメントが必要な場合、状況は複雑です。 同時に、さまざまな形式のドキュメントの内容が多少異なる場合があります。 たとえば、ビデオクリップをオンラインドキュメントに含めることは理にかなっています。印刷版では、ビデオクリップへのqrcodeリンクで補足される可能性のある静的画像に置き換える必要があります。 さらに、ドキュメントのコンテンツは、ユーザーのカテゴリ、バージョン、バンドル、およびその他の要因によって異なる場合があります。

1.2。 ソース形式

特別に作成されたプログラムを使用する必要があることは明らかであるにもかかわらず、ここではすべてがそれほど単純ではありません。

アプローチは、ターゲットオペレーティングシステムによって異なります。

1.2.1。 独自のソース形式

したがって、Windows用のコンパイル済みヘルプをchm形式で作成するには、特別な無料のHTML Help Workshopコンパイラを使用することをお勧めします。 この場合、ソーステキストはhtml形式で準備する必要があり（エディターは配信に含まれません）、目次ファイルは特定の形式にする必要があります。 印刷されたマニュアルを作成する手段は提供されていません。

もちろん、 ヘルプを作成するための特別なプログラム（ Robohelp 、 Help＆Manual 、 HelpScribbleなど）は、高レベルのサービスを提供し、さまざまな形式の出力ドキュメントを生成し、ある程度コンテンツをプロファイリングすることもできます。

ただし、次の欠点があります。

1. まず、これらのシステムはすべて商用であり、使用するジョブの数によってライセンスされています。
2. 第二に、彼らが使用する内部形式は独自のものであり、販売されているもの以外のソフトウェアではサポートされていません。 もちろん、ファイルをプロジェクトにインポートする機会が与えられますが、プロジェクトをさらに処理するのに適したオープン形式にエクスポートすることはできません。 XMLが内部形式（ヘルプやマニュアルなど）として使用されている場合でも、そのスキームは閉じたままであり、いかなる方法でも文書化されていません。
3. 第三に、出力ドキュメントの外観を変更する機能は、たとえばGOSTの要件に従ってドキュメントを生成するには不十分です。
4. 第4に、可能であれば、これらのプログラムでチームワークを編成することは非常に困難です。

1.2.2。 シンプルなマークアップ形式
合理的な代替策は、シンプルで、その結果、マークアップ形式をすばやくマスターすることです。

現在、このような形式がいくつかあります。

• ASCIIdocは 、Linux（BSD）システムで事実上使用されています。
• Wikiは、さまざまな種類の百科事典で使用されており、共通名を付けています。
• MarkDownは、いわば多目的のドキュメント形式です。

これらすべてのマークアップは、見出し、イラスト、リンクの設計に、シンプルなテキストエディターでの編集を伴う、記号のないタグなしのルールセットを使用します。 表示に適したビューの準備は、原則として、サーバー側でプログラムによって実行されます。

たとえば、WikipediaはWiki形式を「オンザフライ」でHTMLに変換します。 Gitシステムのhttp://github.orgのWebポータルは、Markdownマークアップでドキュメントをブラウザーで読み取り可能な形式で表示することもできます。

1.3。 編集者

ソーステキストを作成および編集するにはメモ帳の機能で十分であるという事実にもかかわらず、スペルチェックやマークアップの強調表示などの一部のサービス機能は、ライターにとって非常に便利です。

記事http://www.ixbt.com/soft/markdown-online-2.shtmlは、マークダウン構文をサポートするオンラインエディターの概要、およびhttp://www.ixbt.com/soft/markdown-online-3を提供します。 .shtmlは、デフォルトのマークダウン形式をサポートする5つのデスクトップエディターの概要を提供します。

そのようなエディターの1つがMarkdownPadです。

1.3.1。 マークダウンパッド

図1. MarkdownPad 2エディター

スクリーンショットからわかるように、MarkdownPad 2エディターは編集されたファイルのライブプレビューをサポートし、ソーステキストとレンダリング結果の同期スクロールをサポートします。

Windows 8にインストールする場合、プレビューを利用できない場合があります。


図2.レポートプレビューシステムのクラッシュ

http://markdownpad.com/faq.html#livepreview-directxの開発者によると、これは、 Awesomium 1.6.6 SDKをWebレンダリングするために特定のSDKをインストールする必要があるためです。

エディターは、構文の強調表示、 1つの言語（ロシア語を含む）の構文チェック、HTMLへのエクスポート、PDF形式（有料版のみ）をサポートしています。 つまり、MarkdownPad 2は、他の特別なエディターと同様に、テクニカルライターに適しています。 ユーザーがさまざまな形式のファイルを編集する必要がある場合は、マークダウンマークアップを使用してテキストを編集するためにエディターを適合させることができます。

1.3.2。 メモ帳++

これらの要件を適切に満たすエディターは、 Notepad ++と見なすことができます。 多くの言語のスペルチェックは、特別なプラグインを使用してサポートされています。 さらに、 複数の言語でのテキスト検証が同時にサポートされています。


図3.メモ帳++エディター
マークアップ規則は単純ですが、テキストの作成者が構文の強調表示を使用する方が便利です。 Notepad ++に関しては、Notepad ++プロジェクトのMarkdown Syntax Highlightingがこれに役立ちます。これは、本質的に、Markdownユーザー言語構成ファイルです。 インストール後、エディターのテキストは次のようになります。


図4.マークダウンマークアップ要素を強調表示したメモ帳++エディター

1.4。 割り当て

マークダウンをサポートするエディターがモバイルプラットフォームにも存在することは注目に値します。 この図は、 Quoda Code Editorを実行しているスマートフォンの画面のコピーを示しています。


図5. Quodaコードエディター-マークダウンマークアップをサポートするAndroid用ユニバーサルエディター

この記事のほとんどは、このエディターで入力され、その後コンピューターにダウンロードされて改訂されたと言われるべきです。

Markdownマークアップ言語と特別なエディターの機能の分析に基づいて、中程度の複雑さのシステムの文書化にそれらを使用することをお勧めします。

1.4.1。 タグ形式を開く

同時に、大規模システム用のプログラム文書の開発のための初期形式として、オープンで十分に文書化された形式を使用する必要があります。 形成の手段として-外観、プロファイリング、およびさまざまな形式のドキュメントを生成する機能をカスタマイズする幅広い機能を備えたツール。

DITAやDocbookなどのシステムは、これらの要件を完全に満たしています。

いくつかの違いはありますが、両方のシステムには多くの共通点があります。

• ドキュメント化された（スキーマ化された）XMLをソース形式として使用します。これにより、編集用の検証機能を備えた任意のXMLエディターを使用できます。
• ほぼすべてのxslコンバーターxslproc 、 xalan 、 saxonなどを使用して、結果の形式のいずれかに変換できます。
• pdfドキュメントを取得するには、中間xsl-fo形式が使用されます。この形式から、foプロセッサ（ Apache FOPやXEPなど ）を使用してpdfが既に形成されています。
• 多数の変換パラメーターを使用して、外観とプロファイリングをカスタマイズし、必要に応じてカスタムxslテンプレートを追加します。

これらのシステムは、ソースドキュメントでセマンティックマークアップを使用することを強調する必要があります。 出力ドキュメントの外観は、変換のルールとパラメーターによって決まります。 このアプローチにより、著者はソーステキストを書く段階でタイポグラフィやデザインについて考えるのではなく、セマンティックコンテンツのみに集中することができます。

同時に、特に多くの出版物で確認されているDocbookを使用した実際の経験から、そのようなよく考えられた技術を使用する場合、いくつかの困難があることが示されています。

• 特定のスキームのXML形式でソースコードを作成するには、テクニカルライターが特別なエディターで作業する必要があります。
• Docbookをサポートする優れたXMLエディター -市販の高価な製品（ oXygen XMLエディター 、 Altova XMLSpy XMLエディターなど ）。
• 豊富なXMLマークアップ機能は、より複雑な形式を必要とします。 たとえば、Docbookマークアップに署名付きのイラストをテキストに挿入するには、4つのネストされたタグを使用する必要があります。

当然のことながら、上記の欠点はXMLベースの単一ソーステクノロジーの広範な使用を妨げます。

オフラインドキュメントまたは印刷ドキュメントの準備にタグなし形式を使用する場合は、変換ユーティリティを使用する必要があります。 多くのコンバーターの中で、pandocプログラムには特別な注意が必要です。

1.5。 Pandoc変換ユーティリティ

Pandocは、さまざまなマークアップのテキストを多数の出力形式に変換できるコマンドインターフェイスを備えたクロスプラットフォームプログラムです。

したがって、たとえば、pandocを使用して、ASCIIdoc、Wiki、MarkdownマークアップのソースドキュメントをHTMLに変換できます。 LaTexをインストールすると、PDFを入手できるようになります。

したがって、たとえば、 この記事のソーステキストをhtml形式に変換するには、次のコマンドを使用します。

 pandoc -f markdown pandoc.md -t html -o pandoc.html -H h.html

結果は、完成したhtmlファイルになります。

図6. pandocによってMarkdownから生成されたHTMLドキュメント

その汎用性のために、このプログラムは比author的に著者「スイスアーミーナイフ」と呼ばれています。

実際、pandocは情報を失うことなく変換を処理します。 MarkDown形式から変換する場合、3つのメタデータパラメーター（ドキュメントのタイトル、作成者、日付）の読み取りがサポートされます。 また、ドキュメント言語などの特定のプロパティを設定するためのコマンドラインオプションの受け渡しもサポートしています。 独自の出力ドキュメントテンプレートを指定し、ある程度変更することができます。

したがって、たとえば、上記の例では、現在のフォルダーにヘッダーの役割を果たすh.htmlファイルがあると想定されています。 このファイルにスタイルファイルへのリンクを追加し、 <base target="_blank">定義すると、次の結果が得られます。


図7.スタイルリンクのあるヘッダーファイルを使用してpandocによって生成されたHTMLドキュメント

この例からわかるように、ヘッダーは独自のスタイルを取得しており、外部ブラウザーの新しいタブで外部リンクが開き始めました。

上記のフォーマットの機能により、Markdownマークアップを使用して比較的小さなソフトウェアシステムを文書化することが正当化されます。その設計にはGOST要件がなく、Gitシステムで広く使用されていることが証明されています。

大規模で複雑なドキュメントを含む大規模システムの場合、その作成には単一のソースシステムDocbookの使用が見られます。 プロジェクトの規模がすぐに表示されない場合もあります。

1.6。 Docbook

XMLソースファイルの作成の複雑さは、Markdownソースコードを使用してDocbookに変換することで克服できます。 この変換は、pandocユーティリティでサポートされています。 だからチーム

 pandoc -f markdown pandoc.md -t docbook -o pandoc4.xml -H h.xml    

結果のファイルを作成します 。

メタタグの適切な処理と記事の作成には、ヘッダーファイルh.xmlの使用（単に空にすることができます）が必要です。


図8. XMLエディターで生成された記事

docbookへの変換に使用されるいくつかの追加のマークダウンマークアップ要件に注意する必要があります。

まず、XMLではタグを強調表示するために使用されるため、テキスト内で不等号括弧（<and>）を使用することは避け、コンバーターはそれらをそのまま残します。 意味に山括弧が必要な場合は、エンティティ< および> 。

第二に、画像を挿入する際、代替テキストを入力する必要があります。これは、pandocが図を使用して必要なtitleタグを作成するためです。

ただし、出力テキストはDocbookバージョン4の古い形式で生成されますが、最新のバージョン5はセマンティックマークアップの機会が大幅に豊富になります。

テキストをバージョン4からバージョン5に変換するには、Docbookに含まれている特別な変換db4-upgrade.xslを使用できます。

 xsltproc -o pandoc5.xml db4-upgrade.xsl pandoc4.xml 

このようにして取得したdocbook 5 xmlスキーマファイルを使用して、単一のソースを形成できます。


図9.作成者モードのXMLエディターでのスキーマの記事

記述された一連の変換は、一見長く不合理に複雑に見えるかもしれません。 ただし、必要なツールを一度習得し、頻繁に実行されるタスクのバッチファイル（スクリプト）を開発したので、将来かなりの時間を節約できます。

単一のソースの技術には顕著な累積効果があることを強調する必要があります。 典型的な再利用可能なテキストフラグメントの開発に費やされた最初の時間は、後続のプロジェクトで使用されると報われます。 シリアルソフトウェアシステムを文書化する際に、シングルソーステクノロジーが特に魅力的なのは、この品質です。

一連の変換は、Docbookがスタイル付きのHTMLでのドキュメントの形成、印刷用のPDFをサポートします。

 xsltproc -o pandoc5.fo c：\ <DocbookXSLへのパス> \ fo \ docbook.xsl pandoc5.xml

出力ドキュメントの外観は、パラメータを使用してある程度調整できます。 結果のファイル形式FO-XSL pandoc5.foは中間であり、 最終的なPDFを作成するために必要です。

同様に重要なのは、目次、イラストのリスト、リスト、表、索引、用語集、およびリファレンスのリストを自動的に生成する機能です。

パッケージに多数のドキュメントがある場合、それらへの正しい形式のリンクを自動的に生成する機能を備えた個別のリストを作成することもできます。 GOSTなどの特別な要件を考慮して、マニュアルのタイポグラフィレイアウトを作成する場合、通常のページ、タイトル、および最終ページのフォーマット用に追加のxslを開発する必要があります。

これは次の記事の主題かもしれません。