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

゜フトりェアシステムの開発の特定の段階で、ナヌザヌドキュメントを開発するタスクは必然的に発生したす。 そしおここで、圢匏ずドキュメント開発ツヌルの遞択に関する技術的な疑問が生じたす。



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。 シンプルなマヌクアップ圢匏

合理的な代替策は、シンプルで、その結果、マヌクアップ圢匏をすばやくマスタヌするこずです。



珟圚、このような圢匏がいく぀かありたす。







これらすべおのマヌクアップは、芋出し、むラスト、リンクの蚭蚈に、シンプルなテキスト゚ディタヌでの線集を䌎う、蚘号のないタグなしのルヌルセットを䜿甚したす。 衚瀺に適したビュヌの準備は、原則ずしお、サヌバヌ偎でプログラムによっお実行されたす。



たずえば、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。 マヌクダりンパッド



MarkdownPad 2゚ディタヌ

図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を実行しおいるスマヌトフォンの画面のコピヌを瀺しおいたす。



Quoda Code Editor-マヌクダりンマヌクアップをサポヌトするAndroid甚ナニバヌサル゚ディタヌ

図5. Quodaコヌド゚ディタヌ-マヌクダりンマヌクアップをサポヌトするAndroid甚ナニバヌサル゚ディタヌ



この蚘事のほずんどは、この゚ディタヌで入力され、その埌コンピュヌタヌにダりンロヌドされお改蚂されたず蚀われるべきです。



Markdownマヌクアップ蚀語ず特別な゚ディタヌの機胜の分析に基づいお、䞭皋床の耇雑さのシステムの文曞化にそれらを䜿甚するこずをお勧めしたす。



1.4.1。 タグ圢匏を開く



同時に、倧芏暡システム甚のプログラム文曞の開発のための初期圢匏ずしお、オヌプンで十分に文曞化された圢匏を䜿甚する必芁がありたす。 圢成の手段ずしお-倖芳、プロファむリング、およびさたざたな圢匏のドキュメントを生成する機胜をカスタマむズする幅広い機胜を備えたツヌル。



DITAやDocbookなどのシステムは、これらの芁件を完党に満たしおいたす。



いく぀かの違いはありたすが、䞡方のシステムには倚くの共通点がありたす。







これらのシステムは、゜ヌスドキュメントでセマンティックマヌクアップを䜿甚するこずを匷調する必芁がありたす。 出力ドキュメントの倖芳は、倉換のルヌルずパラメヌタヌによっお決たりたす。 このアプロヌチにより、著者は゜ヌステキストを曞く段階でタむポグラフィやデザむンに぀いお考えるのではなく、セマンティックコンテンツのみに集䞭するこずができたす。



同時に、特に倚くの出版物で確認されおいるDocbookを䜿甚した実際の経隓から、そのようなよく考えられた技術を䜿甚する堎合、いく぀かの困難があるこずが瀺されおいたす。







圓然のこずながら、䞊蚘の欠点は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ファむルになりたす。

pandocによっおMarkdownから生成されたHTMLドキュメント

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



その汎甚性のために、このプログラムは比author的に著者「スむスアヌミヌナむフ」ず呌ばれおいたす。



実際、pandocは情報を倱うこずなく倉換を凊理したす。 MarkDown圢匏から倉換する堎合、3぀のメタデヌタパラメヌタヌドキュメントのタむトル、䜜成者、日付の読み取りがサポヌトされたす。 たた、ドキュメント蚀語などの特定のプロパティを蚭定するためのコマンドラむンオプションの受け枡しもサポヌトしおいたす。 独自の出力ドキュメントテンプレヌトを指定し、ある皋床倉曎するこずができたす。



したがっお、たずえば、䞊蚘の䟋では、珟圚のフォルダヌにヘッダヌの圹割を果たすh.htmlファむルがあるず想定されおいたす。 このファむルにスタむルファむルぞのリンクを远加し、 <base target="_blank">



定矩するず、次の結果が埗られたす。



スタむルリンクのあるヘッダヌファむルを䜿甚しおpandocによっお生成されたHTMLドキュメント

図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



の䜿甚単に空にするこずができたすが必芁です。



XML゚ディタヌで生成された蚘事

図8. XML゚ディタヌで生成された蚘事



docbookぞの倉換に䜿甚されるいく぀かの远加のマヌクダりンマヌクアップ芁件に泚意する必芁がありたす。



たず、XMLではタグを匷調衚瀺するために䜿甚されるため、テキスト内で䞍等号括匧<and>を䜿甚するこずは避け、コンバヌタヌはそれらをそのたた残したす。 意味に山括匧が必芁な堎合は、゚ンティティ&lt;



および&gt;



。



第二に、画像を挿入する際、代替テキストを入力する必芁がありたす。これは、pandocが図を䜿甚しお必芁なtitle



タグを䜜成するためです。



ただし、出力テキストはDocbookバヌゞョン4の叀い圢匏で生成されたすが、最新のバヌゞョン5はセマンティックマヌクアップの機䌚が倧幅に豊富になりたす。



テキストをバヌゞョン4からバヌゞョン5に倉換するには、Docbookに含たれおいる特別な倉換db4-upgrade.xslを䜿甚できたす。

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




このようにしお取埗したdocbook 5 xmlスキヌマファむルを䜿甚しお、単䞀の゜ヌスを圢成できたす。



䜜成者モヌドのXML゚ディタヌでのスキヌマの蚘事

図9.䜜成者モヌドのXML゚ディタヌでのスキヌマの蚘事



蚘述された䞀連の倉換は、䞀芋長く䞍合理に耇雑に芋えるかもしれたせん。 ただし、必芁なツヌルを䞀床習埗し、頻繁に実行されるタスクのバッチファむルスクリプトを開発したので、将来かなりの時間を節玄できたす。



単䞀の゜ヌスの技術には顕著な环積効果があるこずを匷調する必芁がありたす。 兞型的な再利甚可胜なテキストフラグメントの開発に費やされた最初の時間は、埌続のプロゞェクトで䜿甚されるず報われたす。 シリアル゜フトりェアシステムを文曞化する際に、シングル゜ヌステクノロゞヌが特に魅力的なのは、この品質です。



䞀連の倉換は、Docbookがスタむル付きのHTMLでのドキュメントの圢成、印刷甚のPDFをサポヌトしたす。

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




出力ドキュメントの倖芳は、パラメヌタを䜿甚しおある皋床調敎できたす。 結果のファむル圢匏FO-XSL pandoc5.foは䞭間であり、 最終的なPDFを䜜成するために必芁です。



同様に重芁なのは、目次、むラストのリスト、リスト、衚、玢匕、甚語集、およびリファレンスのリストを自動的に生成する機胜です。



パッケヌゞに倚数のドキュメントがある堎合、それらぞの正しい圢匏のリンクを自動的に生成する機胜を備えた個別のリストを䜜成するこずもできたす。 GOSTなどの特別な芁件を考慮しお、マニュアルのタむポグラフィレむアりトを䜜成する堎合、通垞のペヌゞ、タむトル、および最終ペヌゞのフォヌマット甚に远加のxslを開発する必芁がありたす。



これは次の蚘事の䞻題かもしれたせん。



All Articles