1

私はドキュメンテーション システム/プラットフォームの構築を担当しています。

主な要件の短いリストを次に示します。

  • ローカライズが容易: これには、すぐに十数か国語をサポートする必要があります。(非技術者が翻訳を追加/更新できることは大きな利点ですが、100% 必要というわけではありません)

  • 出力形式の柔軟性: 最低限、ドキュメントを (全体として、または選択したチャンクで) PDF および HTML として出力する必要があります。Windows ヘルプ ファイルなどのネイティブ フォーマットのボーナス ポイント。

  • 直感的なユーザー インターフェイス (理想的には Web) を介して管理および展開されます。

この種のことをすでにサポートしているシステムを知っているかどうか疑問に思っていますか? 私はこれをゼロから書くことを嫌いませんが、できることなら車輪の再発明はしたくありません。

これまでに私が遭遇した 2 つの主な候補は、DocBookとreSTです。前者は、まあ、吸うという評判を得たようです. 私はどちらにもなじみがありませんが、reST を使えばかなりの部分を達成できると言われています。

他の提案はありますか？これをゼロから構築したほうがよいでしょうか？

4

2 に答える 2

2

DocBook と ReStructuredText は間違いなく 2 つの最大の競合相手ですが、Asciidocはマークアップに関係なく読み取り可能な別の同様のマークアップ言語です。私は個人的には ReStructuredText の方がよく知っています (したがって、ReStructuredText のより大きな支持者でもあります) が、Asciidoc は別のオプションにすぎません。

あなたがこれまでに説明したことを考えると、 ReStructuredText パーサーがあり、ページを PDF にエクスポートできることに基づいて、 MoinMoinが適しているように思えます。ソースを抽出し、必要に応じて他のスタンドアロン ツールで実行できるはずです (ただし、MoinMoin 固有のマークアップを取り除くために、それらを前処理する必要がある場合があります)。

MoinMoin がまさにあなたが必要としているものではない場合、Google はReStructuredText wiki の他の結果をいくつか持っています。

于 2010-05-15T00:22:42.163 に答える
2

従来の技術文書を作成する必要がある場合は、DocBook をお勧めします: ブック、章ごと、セクションごとなどです。考慮すべき主な点は、マークアップ自体、編集ツールチェーン、および公開ツールチェーンの 3 つだと思います。

マークアップ。DocBook XML マークアップは非常に包括的であり、技術書に含まれる可能性のあるほぼすべての側面のサポートが含まれています。これには、相互参照、脚注などの書籍の基本的なものと、プログラム リスト、参照エントリなどのソフトウェア ドキュメント専用のマークアップが含まれます。マークアップへの重要な参照は、DocBook: The Definitive Guide by Norman Walsh and Leonardです。ミュールナー。

コンテンツの言語は、属性を使用して明示的にマークアップできるlangため、ソース ドキュメントにコンテンツを複数の言語で含めることができ、処理段階で目的の言語バージョンを抽出できます。

オーサリング ツール。DocBook ボキャブラリのサイズが非常に大きいため、ある種の「スキーマ対応」エディタがほぼ必須です。優れたエディターは、マークアップ要素の選択を支援し、有効なマークアップを作成できるようにします。まともな XML エディターで十分ですが、ドキュメントの作成者の技術レベルによっては、より使いやすいものを検討することもできます。利用可能な WYSIWYG スタイルのエディターがいくつかあります。(私はXMLMind XML Editorを使用しましたが、とても満足しています。)

公開ツール。DocBook XML マークアップから出力を生成する事実上の標準的な方法は、DocBook XSLスタイルシート配布です。HTML、XSL-FO (PDF 出力用)、HTML ヘルプ、マニュアル ページなど、複数の出力形式をサポートしています。スタイルシートによって生成される出力は、多くのパラメーターによって制御できます。出力を調整する場合、最初に参照するのは、スタイルシートと共に配布されているリファレンス ドキュメントです。

ただし、生成された出力をさらに制御したい場合は、特定の用途に合わせて XSLT スタイルシートをカスタマイズする必要があります。これは、XSLT の経験がない場合は特に、やや困難に思えるかもしれません。ただし、この件に関しては優れた無料の本があります: DocBook XSL: The Complete Guide by Bob Stayton です。

XSL-FO を PDF に変換するには、XSL-FO プロセッサも必要です。無料でオープンソースのApahce FOPがあり、複数の商用オプションがあります。

ほとんどの場合、パブリッシング プロセスは、最終的にはドキュメントのビルド システムのようになります。自動化されたシステム (おそらく Make や Ant などのビルド ツールによって駆動される) が作成され、ドキュメント ソースが XML で取得され、目的の言語で目的の出力形式に変換されます。

要約すると、直線的な本のような詳細な技術文書を作成しようとしている場合、DocBook は適切な選択であると言えます。主な欠点は、マークアップの複雑さです。これは、作成者にとってかなりの学習曲線を提示する可能性があり、特別なオーサリング ツールが必要になる場合があります。また、DocBook XSL スタイルシートからの出力をカスタマイズすると、かなり複雑になる場合があります。

「本のような」ドキュメントよりも「オンラインのような」ドキュメント (ドキュメントのトピックが相互にリンクしている) を作成したい場合は、別の XML ベースの代替手段としてDITAを参照することをお勧めします。私は使用していませんが、XML マークアップからさまざまな出力形式を生成するためのツールチェーンも付属しています。

于 2010-05-16T09:02:52.053 に答える