Python人が愛してやまないReStructuredTextという構造化テキストがあります。

Djangoのドキュメントや、PythonのPEPと呼ばれるプロポーザルドキュメント等、様々な用途に利用されています。Pythonの人は原稿を書くときにも好んでReStructuredTextを使うようです。

構造化テキストは、簡単に言えばWiki記法、はてな記法のようなものです。ReStructuredTextはそのままテキストで見てもわかりやすいように考慮された記法です（非常にPythonらしい記法です）。

ReStructuredTextで作成したドキュメントは、Docutilsというライブラリを使ってコンパイルできます。Django用に作成するアプリケーションにソースコードドキュメントとしてReStructuredTextで書くと、Adminでドキュメントとして参照できたりしますので、Docutilsはぜひインストールしておいてください。

ReStructuredTextはDjangoのAdminやフラットページで利用するのは非常に便利なのですが、書いている最中にある程度の出来上がりや構文エラーがないかどうかを確認する際に少し面倒があります。
通常はコマンドラインからdocutils付属のスクリプトに「構造化テキストを保存しているファイル名」と「出力するHTMLファイル名」を渡してコンパイルをしなければいけません。
しかも、出力されたファイルをブラウザで開かなければなりません。

今まではMarkdownという別の構造化テキストをプレビューできる機能付きのSmultronというエディタのソースコードを、mopemopeさんがクイックハックし、ReStructuredTextに対応させたものを利用していました。

Smultonは、複数のファイルを一つのウィンドウで扱える便利なエディタですが、行数が増えるに従って微妙に行番号の位置がずれていくといった問題が私の環境では発生していました。

TextMateが日本語をうまく扱えないこともあって、簡単なテキストやブログのエントリはCotEditorという日本人が作っているエディタを普段使っています。このCotEditorはAppleScript以外にもPerlやRuby、Pythonのスクリプトを実行できますし、ウィンドウを半透明にできたりもします。

以下は、CotEditorからdocutilsを操ってプレビューさせるスクリプトです。rest_preview.@r.pyというファイル名で ~/Library/Application\ Support/CotEditor/ScriptMenu/ の下に置きます。@rという名前が含まれているので、コマンド＋rキーでショートカットできます。

#!/usr/bin/python

# %%%{CotEditorXInput=AllText}%%%

import os

HOME_DIR = os.environ['HOME']
if not HOME_DIR:
    HOME_DIR = '/var/tmp'

output_file = os.path.join(HOME_DIR, 'cot_rest.html')
css_file = os.path.join(HOME_DIR, 'Dropbox', 'basic.css')
extra_settings = None
if os.path.isfile(css_file):
    extra_settings = dict(
            stylesheet_path=css_file,
        )

try:
    import locale
    locale.setlocale(locale.LC_ALL, '')
except:
    pass

from docutils.core import publish_cmdline, default_description

description = ('Generates (X)HTML documents from standalone reStructuredText '
               'sources.  ' + default_description)

res = publish_cmdline(
            writer_name='html',
            description=description,
            settings_overrides=extra_settings
        )

file = open(output_file, 'wr')
file.write(res)
file.close()

import commands

commands.getstatusoutput('open %s' % (output_file, ))

CotEditorはどんな文字コードで編集されていても、UTF-8に変換してスクリプトに渡してしまうそうなので、あくまでもプレビューとして使ってください。

さて、デザイン勉強会について書くか！

ここひと月半程、同僚と業外のサービスを作っていました。今週末にはα版がオープンできそうです。
例のあれに応募する訳ですが、数年前から構想のあったものをやっと作りました。期限があるというのはいいことです。

結局想定していたものはほとんどが失われ、全く違うものが作り上がりました。内容の割に時間がかかったのは作りつつ仕様がドンドン変わっていったのと、コードを書く同僚が前から作っているフレームワークを大幅に書き換えていったからです。

今回私はガワの作成と、そのフレームワークにケチをつける係でした(＋ほんの少しドキュメントを書いています)。
そのフレームワークは概要のドキュメントしかないので、使えるのは世界に多分2人。。

Djangoを使わなかったのは、コードを書くのがPHPのフレームワークを作っている同僚だったのと、PHPのほうがチープにスタートできる(年間ドメイン代も入れて3000円程度で動かせる)ためです(私の借りているVPSは月3000円。しかもスイスはネットワークが遠い)。チープなので、一部悲しい動作をしている部分もあります。
なにはともあれ、ちょっと落ち着きそう。

PyConにてAdrianがDjango本について発表した模様。
djangoprojectのblogにもエントリーが。

この本が凄いのは、オープンソースライセンスでも配布するし、かつオープンソースらしくいろいろな人を巻き込んで仕上げていくとのこと。コントリビュートってやつですな。
すでに数チャプタ書き上げているそうなので、完成したら忙しくなりそう（だれが？）。
もちろん、出版されるようなので紙ベースの物も手に入ります。

Yasushi MasudaさんのところにDjangoのi18nドキュメントが（日本のZope情報より）！

私のところにリンクされている物の内、チュートリアルは第一版（２００５年８月頃のバージョンがつく前のDjangoに基づく）です。

Djangoのi18nに関しては、i18nのメーリングリストがあります。

翻訳の力が分散してしまうともったいないのでまずは、l10n（お！？）のwikiに名前を追加して、強調してやりたいなぁ、とか思ったりして。

i18nの現状
i18nメーリングリストではドキュメントの翻訳を諦めている状態のようです。
理由はDjango本体のドキュメントが更新される頻度が非常に速いからです。
なので、いまやるとしたら本体のreSTに併せてあるていど準備をしておくということなのかなと思っています。

バージョン1が出るあたりで一気に翻訳をしようということで、おそらく翻訳した物は本体(djangoproject.com）に配置できるのではないかと推測されます。

追記

mopemopeさんの指摘を受けてi18nのログを見てみた所、上記のような（ドキュメントの補運訳をするといった）情報はありませんでした。
どこから思いこんでしまったのか。
Masudaさん、大変申し訳ありませんでした。

しかしながらそれであればなおのこと、日本語化されたドキュメントへの入り口があった方がいいのではないかと思った次第ですが、それはYasushi Masudaさんのところが最適ではないかと再び。
sourceforgeにcvsとサイトをホストしてもらうっていうのも手かなと思いましたが、mod_pythonが動かないようなので一石二鳥はあきらめました。

しかし、この「いい加減・早とちり」は何とかしないと破滅するな。。。

むやみにtracのwikiを使っていましたが、djangoの本家ドキュメントもreSTで書かれていることもあり、今後の超訳のことも考えてreSTで書き直すことにしました。昨年の夏はWebを見て、wikiに翻訳しつつ、超訳をしていたので大変でした。reSTからreSTは楽々。

tracもreST使えるようですが、どうせ書くのは一人だし、コンテンツの管理はやはりPloneだろうということで。

とりあえず第一弾はDjangoのインストールドキュメント。思いっきりフランクな訳にしてみました。

元の文書はこんな物ではありません。

PythonWorkshop03でのDjangoセッションも、きっと今頃終わっていることでしょう。

ということで、当日使ったkeynoteの資料をQuickTime化したもの(...mov.zip)を公開します。

うまくいっているといいなぁ。

使用してみた感じ
　・構造を書けば良いので、ドキュメント類には適している模様
　・xmlなのでhtmlやpdfの複数フォーマットへ変換が可能
　・LaTex経由でpdfにするには、DocBookの他にLaTeXの知識が必要
　・fo経由ではapache-foのバージョンが現在0.2であるため、殆ど機能がNotImplementedで使い物にならない

LaTeX経由でpdfにする際のメモ
　・xmlからLaTeXに変換するためのxslはdb2latexを使用した
　・db2latexで変換をすると、DocBookのprogramlistingがVerbatimになるので、変換後verbatimに全置換するかxslの該当部分を修正する必要が有る
　・verbatimは段落を「入力されたまま」に表示するLaTeXのコマンドだが、使い勝手はいまいち。pythonのドキュメント用マクロ等を参考に修正した方が良い
　・xslを実行する環境はいろいろ有るが、OSXであればxsltprocが手軽。殿環境でも使用可能なJavaではsaxonが一番うまくいった(xsltprocより良い)。XALANではうまくいかなかった。
　・Windows／OSXでLaTeX環境を揃える場合は、LATEX 2ε美文書作成入門を購入するのが良い。CDに必要な物が殆ど入っていて、インストーラもついている。LaTexの解説も手に入る（せっかくだから下のリンクで買ってください^o^;）。

ドキュメントを何で書こうか迷いつつも、目次の自動生成に惹かれてWORDでとりあえず書きだしてみたけれど、あまりの日本語文章（というか英語でも問題だと思うが）の体裁の弱さ（改行幅ってどうやって微調整するの？）に辟易。
探してみると、どうやら世の中のドキュメントはDocBookかLaTexで記述されている模様。
いまさらLaTexを覚えて、テキストエディタでえっこら書くのもなんなので、XMLで書けるDocBookをEclipse上でXMLBuddyを使用して書いてみる。
DocBook(XML) → FO → PDF という流れで（当然HTML等にも変換できる）、オッケー！と思った。が、FO → PDF という流れをきちんとできそうなツールがApache FOPしか見つからない。まぁ、antでばしっと自動化できるし、いいじゃん。とかも思った。本当はpythonあたりからテロっと簡単にできるんじゃな いかと期待したんだけど。
ためしにある程度書いてみて、おらっ！とPDFを生成してみたんだけど、でるはでるは「Not Implemented Yet」のメッセージメッセージメッセージ。。。Apache FOPのバージョンは0.20です。だめです。出来上がりを見ても、日本語はまったく美しく出力されない。。
しかたなく、LaTexです（でもマックの美しいフォントが使える）。
OSXでは、finkでのんびりとインストールが必要。
WindowsはXPのSP2がいけないのか、Windowsインストーラ(textinst753.exeってやつ）が動かなくて四苦八苦。
結局ファイル名をinstall.exeとかにしたら動いた。なんじゃ、WindowsXP SP2は。