こんにちは
Emboxオープンソースプロジェクトの開発者の1人として、プロジェクトが面白いとよく耳にしましたが（最近ではあまりに頻繁に）、ドキュメントがないため使用できません。 私たちは、何らかのドキュメントがあり、いつでも質問に答えることができると答えました。極端な場合は、プロジェクトが開いているので自分で解決しようとすることができますが、これはすべて適合しませんでした。 開発者にとってこの非常に不快なトピックに対処しなければなりませんでした。 しかし、当然のことながら、この記事は、ドキュメントを扱うことが「不快」であるという事実に関するものではありません。 そして、ドキュメント開発プロセスをより快適にした方法について。 実際、多かれ少なかれ大規模なプロジェクトでは、ドキュメントに関連する問題が必ず発生します。
読むのが面倒な人のために、私はすぐにマークダウン形式のドキュメントの開発に着いたと言います。 まあ、詳細に興味がある人、マークダウンの理由、このアプローチの長所と短所は何ですか？
トピックの関連性を正当化することから始めます。 Emboxだけでなくドキュメントの問題もあります。 たとえば、Googleは、テクニカルライターのSeason of Docs向けのGoogle Summer Of Code（GSOC）プログラムの類似版を発表しました。 Kaspersky Lab社は、テクニカルライター向けの会議を開催しています。 そしてParallels社は、ドキュメントの書き方に関する記事をハブで公開しています 。 これはすべて、トピックが重要であり、おそらく注目に値するほどの価値がないことを示しています。
上記の一連の記事はドキュメントの正しい内容を理解していますが、必要に応じてドキュメント、テクノロジーの開発プロセスに焦点を当てたいと思います。 実際、オープンソースプロジェクトの特徴は、開発プロセスの特性としてのオープン性です。 そして、プロジェクトの要件を満たすプロセスを作成したいと考えました。
ドキュメント開発プロセスの歴史への短い余談。
プロジェクトがgooglecodeに配置されたら 。 私たちにはかなりまともなwikiがあり、多くの人はそれを覚えていて、どこにあるかを尋ね、プロジェクトが現在（または別のアクセス可能な場所）にあるgithubに転送するように頼みます。 googlecode wikiは本当に便利でした。 多言語対応で、私の意見では、githubのwikiよりも多くの機能を備えていました。 しかし、googlecode自体とともに、忘却に沈んでしまったのです。 githubの現在のwikiは、プロジェクトに関する運用情報を配信する機能を非常によく実行していますが、このプラットフォームで完全なドキュメントを作成することは非常に困難です。
もちろん、どのオープンソースプロジェクトでも、プロジェクトの本質とイデオロギーを理解するのがはるかに簡単であるため、オンラインですばやくアクセスできるドキュメント（Wikiが果たす役割）とオフラインで利用できる完全なドキュメントの両方が必要です。 さらに、異なるWikiページではなく、単一のドキュメントでオフライン検索を行うこともはるかに簡単です。
おそらく私が知っている最良のオプションはARMドキュメントです。 つまり、すべてのセクションで検索が行われるオンラインドキュメントですが、特定のドキュメントはPDF形式でダウンロードできます。 残念ながら、EmboxはまだARMのレベルに達していません。 したがって、オフラインバージョンを個別に実行する必要がありました。 このために、 Google Docsサービスを使用しました 。 便利な理由は次のとおりです。さまざまな形式でデータをダウンロードし、共同作業を行い、バージョン管理システムが組み込まれています。 オフラインバージョンの開発の目標は全体的なドキュメントを作成することであったため、Wikiから情報の一部を転送し、構造を設定し、いくつかのドキュメントの開発を開始しました。 しかし、すぐに問題が発生しました。 情報は古く、wikiのデータはオフラインドキュメントのデータと一致しませんでした。最も重要なことは、完全なドキュメントを作成できなかったことです。 構造はありましたが、ユーザーから適切なフィードバックを得ることができなかったため、その作成者だけがドキュメントを理解できることがわかりました。 これは確かにサービスの問題ではありませんが、彼らが言うように、事実は明らかです。 この問題に対する別のアプローチを探す必要がありました。
次に、古いwikiからwiki githubにデータを転送しようとしましたが、それでもすぐに問題に遭遇しました。 情報の一部が古くなっている、一部が追加されていない、一部がユーザーフレンドリな形式で表示する方法が明確ではないことがわかりました。 問題の解決策を探し続け、ある時点で、gitリポジトリを使用したTeXでのドキュメントの開発を検討しましたが、これはすでに多すぎることにすぐに気付きました。 このアイデアには影響がありましたが。
私たちはドキュメントから欲しいものを定式化することに決めました。つまり、ドキュメントの開発プロセスから、内容を括弧の外に残します。
- ドキュメントはgitをバージョン管理システムとして使用することになっていたため、テキスト形式で保存する必要があります
- ドキュメントには、オンライン（wiki）バージョンとオフライン（pdfなどの別個のドキュメント）バージョンが必要です。
- オンラインとオフラインのドキュメントは簡単に同期できるはずです。
- ドキュメントは、個別に開発または調査できるセクション（章）で構成する必要がありますが、そこから完全なドキュメントをコンパイルできます。
マークダウンの使用と矛盾する点はなく、すでにwikiで使用されているため興味深いものでした。 もちろん、別の形式を使用してマークダウンに変換することもできます。 しかし、さまざまな種類のコンテンツ（画像、テキスト、書式設定）を追加するために、要件の別のリストをコンパイルした後、マークダウンが現在のすべてのニーズを十分に満たすという結論に達しました。 また、「markdown to pdf」というトピックに関する最初のGoogleは、マークダウンを他の形式に変換するオプションが存在し、非常に人気があることを示しました。
markdown をpdfに変換するいくつかのオプションがありますが、 pandocが最も人気があります。 このユーティリティは、任意のテキスト形式を任意のテキスト形式に変換できます。 また、片持ち式です。 したがって、それは私たちに馴染みがあるだけでなく、さまざまな形式のドキュメントを作成するスクリプトに組み込むこともできます。
ユーティリティを決定し、解決しなければならない次の小さな質問、つまり、単一のドキュメントを作成する方法について考え始めました。個別のマークダウンファイルから取得したさまざまな章のあるpdfファイルは多くありません。 最初の欲求は、ファイルを（さまざまなファイルのテキストをマージするために）目的の順序で単に「保存」することでしたが、はるかに簡単であることが判明しました。pandoc自体はファイルのリストを完全に処理できます。 これにより、コンテンツが交差する可能性のあるさまざまなドキュメントが必要であるという問題を部分的に解決することもできました。 たとえば、3つのドキュメントを生成し、3つすべてに簡単な説明セクションが含まれています。 すべてのドキュメントのpandocのリストにこのファイルをリストするだけです。
ドキュメントの名前が含まれるページなどについても同様の原則を適用します。 各ドキュメントのヘッダーを持つファイルを作成し、pandocのソースリストの最初のファイルとして追加しました。
おそらくご想像のとおり、これ（異なるファイルのリスト）は多言語の問題を解決します。目的の言語でファイルを指定するだけです。
ロシアについてもう少し話しましょう。 PDFを生成するとき、pandocはレンダリング、スペルチェッカーなどのバックエンドとしてlatexを使用します。 デフォルトでは、キリル文字は表示されず、不明な文字に関するエラーが表示されます。 これは非常に簡単に解決され、「バベルロシア語」を指定するだけです。
--- ... header-includes: - \usepackage[russian]{babel} ---
示す方がより正確であることに注意する必要があります
--- ... header-includes: - \usepackage[russian, english]{babel} ---
テキストでlatexコマンドを使用します
\selectlanguage{russian} \foreignlanguage{english}{ English text }
または
\begin{otherlanguage}{english} Text in english \end{otherlanguage}
しかし、ウィキへの可能な転送のために「クリーンな」マークダウンを維持したいので、babelディレクティブは目的に十分であることが判明したため、複雑にすることはせず、そのままにしました。
もちろん、フォーマットされたドキュメントとしてではなく、少なくとも均一に見えるようにしたかったのです。 そして、ここでラテックスは再び助けてくれました。 実際のところ、pandocはラテックスを使用しているため、ラテックステンプレートを指定できます。 これは--templateオプションで簡単に実行できます
pandoc --template=embox_pandoc.latex ...
テンプレートをコンパイルし、すべてのドキュメントを生成するときにテンプレートを指定すると、ほぼ均一なスタイルのドキュメントが得られます。 「多かれ少なかれ」-解決できなかったいくつかの問題があるからです。 たとえば、コードの単一ブロックの形成。 マークダウンでは、単一のコードブロックを指定して、フォーマットされないようにし、構文の強調表示を有効にすることができます。 しかし、1行のブロックのみを作成することができました。 これは、生成されたラテックスコードを見た後に判明しました。
つまり、同じブロックが異なるドキュメントに少し異なって配置される場合がありました。
キリル文字に関連する別のポイント、つまりロシア語の使用。 前述のように、ロシア語を使用するには、ヘッダーにロシア語のbabelを指定するだけで十分であることが判明しました。 しかし、いくつかの奇妙なことに遭遇しました。たとえば、大胆なハイライト表示やその他の奇妙な書式設定はありませんでした。 最初は、ロシア語がテンプレートではなくキャップに設定されているという事実に罪を犯しました。 彼らは問題を研究し始めました。 良い方法では、使用するだけでなく
\usepackage[russian, english]{babel}
フォントも設定します
\usepackage[T1,T2A]{fontenc} \usepackage[utf8]{inputenc}
しかし、これを行ったとしても、状況を修正することはできませんでした。 すべてのフォントセットにすべてのレンダリングオプションが含まれているわけではないことがわかりました。特に、他の形式では太字や斜体などが含まれていません。 問題に対する簡単な解決策はなかったので、私たちは問題を考え、延期するまで延期しました。 さて、クリーンマークダウンを使用する（つまり、latexコマンドを指定しない）ために、両方の言語に共通のテンプレートを作成し、ロシア語に関する指示をヘッダーに入れました。
アプリケーション自体のインターフェースについて少しだけお話します。 私が言ったように、コンソールアプリケーションは個人的に非常に馴染みがあり、スクリプトに簡単にパッケージ化されるためです。 実際、インターフェイスはシンプルで、もちろん多くのオプションを設定できますが、この目的のためには、テンプレート、入力ファイルのリスト、および出力ファイルを指定するだけで十分です。
pandoc --template=embox_pandoc.latex <title file> <list of input markdown files> -o <output file>
インターネットでは、pdf（または別の出力形式）を生成するには、-pdf-engine = xelatexオプションを使用したプロセッサタイプが必要ですが、出力ファイルにpdf拡張子が付いている場合はデフォルトで使用されます。 したがって、これも必要ありませんでした。
ドキュメンテーションをMakefileにまとめるためのスクリプトをパックしました。 そして今、ドキュメントを取得するために必要な環境を設定することができます。
make [en][ru]
結論として、バージョン管理システムに関するいくつかの言葉。 原則は、私たちがすべてに固執しようとすることを複雑にすることではありません（シンプルに保ちます）。 そして、最も簡単な解決策はgithubの別のリポジトリを使用することだったので、そうしました 。 githubを使用することでユーザーのフィードバックが改善されることを願っています。 結局、githubでご存知のように、欠点について話し合い、アイデアや方向性を提供できる問題があります。
このプロセスは、多くの労働者の要請により、最近開始されました！ 「クイックスタート」の英語版とロシア語版、およびロシア 語ユーザーマニュアルの最初のバージョンを作成することができました 。 プロセス自体は私たちにとってより便利であるように見えたので、一般に公開しています。