nDiki : Markdown

reStructuredText HTML Wiki XML 構造化テキスト Python 文法 Perl LaTeX DocBook GNU 仕様 Perl モジュール コンポーネント 書き方 メール YAML Perl モジュール Docutils CSS YAML Template Toolkit 要求仕様書 WiKicker

■ 定型書式で内容を記述していくのに便利な形式は?

今要求仕様書を LaTeX で書いている。 要求と仕様の組をまとめて longtable で記述しているのだが、 LaTeX らしい繁雑さがあってちょっと効率が悪い。 マクロを定義すればある程度書きやすくなると思うが、それでもそこそこまでな気がする。

文書の中にレコードの並びが書けて、レコードの並びの中に文章が書きやすいそんなフォーマットはないものかなぁ。

• LaTeX + マクロ
  • 整形は綺麗。
  • 記述が繁雑になりがち。\マクロ名とか {} とか。
• DocBook
  • 仕様デカスギ
  • 以前使ってみたことがあるが、手で書くのにはしんどい。
• XML
  • 構造的な情報の表現には良いのだが、手で書くのはしんどい。開きタグも閉じタグも。
  • 普通の章節や、マークアップのルールを考えなければならない(定義するか借りてくるか)。
  • LaTeX等へのコンバータを書く必要あり。
• YAML
  • レコードの並びだけだったら良いが、文書の他の要素を一緒に書くのには適さない。
  • ある程度の構造やボリュームがあると、思ったほど手書きしやすくない。
  • YAML Perl モジュールで痛い目にあっている。

Wiki に慣れきっている自分にとっては Wiki 文法のような感じで記述できて、一部に定型レコードの並びが書けて、そこの整形ルールだけ定義してあげれば LaTeX に変換できるとかそういった感じがのものが欲しい。 定型レコードの部分は RFC822 のヘッダみたいな感じで良くで、値の部分に長めの文章を複数行で書けるものがいい。

構造化テキスト用フォーマット、あるいはWiki フォーマットをアレンジするのがいいかもしれないな。 このあたりのフォーマットは、ソーステキストのままでも充分読み易いことを意識して定義されているので書くのは楽。

• reStructuredText
  • いいらしい。
  • HTML、LaTeX、XML へのコンバータがある。
  • 拡張性も考慮されているらしい。
  • でも Python。
• Markdown
  • reStructuredText よりもソーステキストが読み易いらしい。
  • Perl
  • HTMLへの変換しかない。
• WiKicker (Wiki)
  • かなり書き慣れている。
  • レコードの並びの書き方を考える必要あり。
  • 複数行にまたがる処理を書くのが面倒。
  • 自分で書いているシステムなので中身は何でも知っている。
  • マイナー。

レコード部分とは関係ないけれど reStructuredText や Markdown の「アンダーラインのあるテキストを見出しとする」っていうのはいいな。 普段メールやプレーンテキストでちょっと文書を打つときに使っているスタイルと一緒だ。

要求仕様書用に使うかどうかは別として、要チェック。

• 早速 reStructuredText から LaTeX へのコンバータを書く (2005-11-24)
• reStructuredText いいんじゃない? (2005-11-22)
• Docutils は自分にとっての Python キラーアプリかも (2005-12-01)
• 私的10大ニュース2005 [ comp ] (2005-12-31)
• WiKicker に JSON でのページ出力機能を追加 (2007-04-03)