Markdown記法を使いこなしたい

最近、公私ともにプロジェクト管理にredmineを使うことが増えてきた。
redmineは、便利なツールだが気になるのが、記述に使っているtextile記法。以前は、tracやpukiWikiを使っていたこともあり、なにかツールを替える都度に新しい記法を覚えるは面倒くさい。ましてや、最近はプログラムでhtmlタグを書くのも色々と簡易的な記法が増えてきて、それはそれで便利だがちょっと、もう少し統一してもらっても良いような気がする。
また、昔からExcelやdocでドキュメントを作ることも嫌いだった。やむを得ず作る時もあるのだが、普段使いではない。textで書いて置けば検索が楽だし、ポータビリティも良いではないか。
なにが、言いたいのか。つまり、一つの記法で全てに対応出来ないだろうかと言うことだ。
表:アプリケーション毎に異なる記法

| case     | style     |
|----------|-----------|
| redmine  | textile   |
| sphinx   | markdown  |
| trac     | trac      |
| pukiWiki | hatena    |

方針として できる限りmarkdownで書く。pandoc コマンドで様々な形式に変換する。 とした。

• テキストファイル(生)を見た時に、普通の人が一番判りやすそうなのは、markdown形式だと感じたので、これを基準にする。
• pandocコマンドは、各OS向けにインストーラがそろっているし、変換のバリエーションが多く、導入しやすそう。

pandocの本家サイトはここ
pandocをインストールしてみた。早速、テストしてみる。

Markdown記法で書かれたサンプル

各書式の記述は、いろいろと方言があるようだ。本家の説明が一番良いだろう。

本家の各書式説明
markdownの文法
Markdown記法は結構、書き方が乱暴でもなんとかなりそうな感じ。h1タグはh1.や#でも良いし。
ex)samle.txt

今日行うべきテスト
===============

準備すること
----------
#. テスト要件のヒアリング
#. テストデータの作成
#. テストケースの作成

テスト環境
---------
* ユニットテスト
* 統合テスト
* 自動化スクリプト

### 気になること ###

テスト  備考
------ ----- 
テスト１ テストサンプル
テスト２ テストサンプル
テスト３ テストサンプル

<pre>

    | file | ----- lan ------- | server | ------ (wifi) -------- | client | 

</pre>

html, textile, rst 形式に変換する

markdown形式のファイルをhtmlに変更する。

$ pandoc sample.txt -s -t html -o samle.html
// -s standalone オプション header情報とかつけてくれる。
// -f (from)元の形式 defaultは、markdown形式か？あるいは自動判別か？
// -t (to)変換先の形式
// -o (out)出力先ファイル

redmineとかで利用するためにtextile形式に変換したり、sphinxで利用するためにrst (reStructured Text)に変換したりする。

$ pandoc sample.txt -t textile -o sample.textile
$ pandoc sample.txt -t rst -o sample.rst

おまけ:: S5形式でプレゼンテーションスライドを作成する

S5とは、A Simple Standards-Based Slide Show System で、要するに htmlとjavascript,cssで作成されたhtmlドキュメントだ
S5の本家サイト

$ pandoc sample.txt -s -i -t s5 slide.html
// -i list itemを順番に表示させてくれる

プレゼンテーションファイルは上記の通りで変換出来るが、補助スクリプト(javascriptとかcssとかテンプレート)を入手しなくてはならない。

1. 上記のs5本家からS5本体をダウンロード
2. 解凍して、最初の階層にあるuiフォルダを上記のslideファイルと同じディレクトリにコピーする
3. ディレクトリ名は、s5に変える （あるいはslide.htmlの中の指定フォルダをいじる)

これで、プレゼンテーションが完成。上記のファイルをプレゼンテーション
なんか、最後の図とか表示されないし、使い方をもう少し研究しなければならないが

---

課題が残った

ここまで来ると、何でもやりたかったのだが、色々制約や勉強しなければならないことが多い。

• pdfツールも同梱(markdown2pdf)が、日本語は通らないらしい
• texも使えるが、TeXはすっかり忘れてしまった
• epubも出来るらしい (いや、これは形式の問題より内容を充実させないと哀しい電子書籍になってしまう)
• 画像の扱いについて研究しなければ
• markdown形式では、inline htmlでのtable形式がダメのようだが....
• サンプルの記述がおかしいかったので、修正 (2012/5/27)