nDiki : Docutils

Docutils

Python で書かれたオープンソースのテキスト処理システム。

関連情報

スポンサード リンク

2005年11月22日 (火)

reStructuredText いいんじゃない?

昨日の続きであるが、reStructuredText がライトなドキュメント書きにはいいんじゃないかという感蝕を得た。

基本的にプレーンテキストのままで十分見られるので、そのままメールに貼りつけられる。

今までは文書を作成する際、メールで草稿をやりとりしたのち内容が固まったら LaTeX のコマンドでマークアップしてコンパイルしてPDF化していた。 これだとちょっと手間であるのだが、最初から reStructuredText 形式で書いていれば、そのまま rst2latex で LaTeX に落とせる。

また必要に応じて rst2html で HTMLに変換してWebサイトに置いておくこともできる。

これらで満足できない場合は Python のコードをいじって変更ということになるが、Python が駄目でも rst2xml でXMLに変換してしまえば他の言語でも reStructuredText のパーサを書かなくても(XMLの処理系を使って)コンバータを書くことができるの比較的楽である。

しかも欲しかったレコードの表現用にフィールドリストというシンタックスがあるではないか。

いいじゃん。

ということで早速今日から使うことにした。

Debian GNU/Linux sid にある Docutils 0.3.9 ではいわゆる全角文字も文字幅を1として扱かう。 このためテーブルなど桁揃えを用いる書式の部分がこのままだと不便である。 画面上では2文字分幅があっても1文字として数えられるため Docutils が通るようにするためには余計な空白などを入れて文字数を調整しなければならないが、そうすると今度は見た目的にずれるので可読性がかなり落ちてしまう。

この問題のためにMatsumoto,Tadashi氏がパッチ

を作成されているので、これを適用。

これでばっちり。

スポンサード リンク
[ 11月22日全て ]

2005年12月1日 (木)

Docutils は自分にとっての Python キラーアプリかも

先日 reStructuredText ベースの要求仕様書ファイルから、LaTeX への変換プログラムを Perl で作成した。rst2xml で変換した XML 文書経由で。

欲しいところだけまずは実装して使ったんだけれど、この先使っていくには細かいところを組んでいく必要がある。やっぱりフルスクラッチするのは面倒だな。

本来は Docutils 用の Writer を作成するのが王道。

しかし Python なんだよね。以前に何度か覚えておこうと思ったんだけれど動機付けが弱かったのかいつも途中でフェードアウト。 しかし今回は明確な目的があるので、もりもりやりそう。

まずは既存の docutils.writers.latex2e.py あたりをコピーしていじって遊んでみるかな。 自分の場合この方法が一番覚えるのが早い。 小学生の時に最初にBASICをいじった時も、既存のゲームのパラメータとか改造から入ったし。

さて、その latex2e.py であるが「documentclass がオプションや設定ファイルで変更できるものの、標準の LaTeX2e 用のもののどれかしか駄目」だったりなど、普通に使うにもちょっといじる必要がありそう(jsbook とか使いたいし)。

一旦自分好みの LaTeX2e Writer を作ってから、それを拡張する形で特定文書毎の Writer を作るのがよさそうだ。

[ 12月1日全て ]

2005年12月7日 (水)

DocutilsreStructuredText から LaTeX への Writer は継承しづらい

この間やっつけでPerl で コンバータをちょっと書いたのだが、やはりここは正攻法で Docutils の Writer として書いておきたい。

Docutils に含まれている LaTeX2e Writer (docutils.writers.latex2e) のクラスを継承してカスタマイズ版を作ればいいかなと着手。 この Writer の生成する TeX ファイルがちょっと好みではないので、継承して自分好みの Writer を書いた上で、それを継承してドメイン毎の Writer を書く事にする。

Python でコードを書いたことはほとんどないのだがそれほど迷う点はない。 素直な言語なのかな。$ とか @ が出てこないのはちょっと寂しい。ブロックをインデントで示すので「閉じ」がなく、ちょっと「スースー」する。 わかる? この気持ち。

Docutils はパースした結果 DOM ライクなツリーができて、これに対して visit / depart 式の visitor を使って処理をしていけるようになっている。 そのあたりはフレームワークがあるし、典型的なパターンなので楽ではある。

ただし、docutils.writers.latex2e のクラスが継承されることを意識されている感じがしないので、メソッドをコピーして書き換えてオーバーライドといった事が必要になる箇所が思ったよりあるのがちょっと気になる。 今後バージョンアップした時に内部も変わる可能性があるだろうし、最終的にはごっそり Writer を作ってしまう方が良さそうだ。

[ 12月7日全て ]

2006年2月7日 (火)

Docutils 0.4 の日本語文字対応はまだまだ駄目

reStructuredText 形式の parse が失敗するようになったと思ったら、Docutils のパッケージが upstream の 0.4 に追従してバージョンが上がっていた。

Release Notes に

Added Japanese and Simplified Chinese language mappings, and support for double-width CJK-characters in tables and section titles.

とあって期待したのだが、試してみたところまだまだ駄目っぽい。

0.3.9 に戻して 以前入れた時と同様 patch をあて、元の環境に戻す。

今後に期待。

[ 2月7日全て ]

2006年2月15日 (水)

ドキュメンテーション大全

開発の現場 Vol.003 効率UP&スキルUP ドキュメンテーション大全

プロジェクトの後半で納品用ドキュメントの整備を始めるのだが、その時はたいがいもう切羽詰りはじめていて構成やら体裁やらマネジメントやらを工夫する余力が無かったりする。 ついつい(次回は改良しようと思っていつも思っている)前回のプロジェクトの手法を踏襲してしまいがちだ。 ともすれば劣化コピーになりかねない。

やはり、忙しくても日頃からの改善は重要である。

最近はアジェンダ議事録開発メモなどを、積極的に WikiSubversion で共有するようにし、その点では以前より改善してきている。

今後はさらに、出荷ドキュメントのレビュープロセスなどを確立し品質を高めていきたいところである。 現状でもチームメンバでのピアデスクチェックやパスアランドを非形式的に行っているのだが、「チェックの程度」やその後の「修正」および「修正の確認」については、まだなんとなくやったかなという具合。この辺りを工夫したい。

先月発売されていて気になっていた「開発現場 Vol.003」に、何かヒントがあるかなと思って買ってみた。

パラパラと見た感じではテクニカルライティングの話はあまりなく、主にソフトウェア開発における中間成果物としてのドキュメントや開発者間ドキュメントをどうとりまとめていくかという話が中心のよう。 Wiki による開発資料のライトな共有など、うちのチームでも進めている話など。

「(最初から)完全なドキュメントを書こうとしない」というのはもっとも。 状況はほとんどの場合変わるし、最初の段階では未確定の部分も多い。 だからといって、いつまでたっても手元で温めていてもしょうがない。

技術的な話では PerlPod を活用しようという話。 Perl 以外の言語のコメント中に Pod 形式でドキュメントを書こうという提案や、Apache で動的に Pod ドキュメントを整形しようという話とか。

テキストフォーマットとしての Pod は =over / =item / =back によるリスト表現など、最近のフォーマットに比べてすごく読み易いわけではないが、たしかに他の言語のコメントに埋め込んでおいて処理するのは、標準の Pod 関連のモジュールでできるな。

自分も Pod でドキュメントを書くけれど、(Perl 以外は) 個人的には reStructuredText にしたいと考えている。 ただ Pod みたいに他のテキストの一部に埋め込んでその部分のみ処理する記法およびツールがが標準の reStructuredText / Docutils には見当らない。 実はどっかにあるのだろうか。


[ 読書ノート ]

[ 2月15日全て ]

2006年3月8日 (水)

Mule-UCS の設定

reStructuredText では表を作る時は文字数で桁揃えして、表セルを表現していく。 ASCII 文字などフォント幅がいわゆる半角幅であるものだけならば、良いのだが全角幅の文字がある場合はちょっと厄介である。

文字数的には1文字なのだが、テキストファイル上では2文字分の幅を取るので見た目上桁が揃わなくなってしまう。 というかそれを忘れて桁を揃えておくと、パーサに怒られる。

このためにパッチがあったり、Docutil 0.4 ではこの対策がほどこされたりしている(不完全であるが)。

さらに厄介なのが Unicode 変換がからむところで、 Emacs + Mule-UCS ではいくつかの(いわゆる)全角文字は UTF-8 で保存すると違う文字に変換されてしまい、これまた Docutils のパーサに、桁があっていないと怒られることになる。

できるだけ全角文字はそのままにしておくということで、以下の設定を追加しておいた。

 (require 'un-define)
 (un-define-change-charset-order
  (append '(ascii japanese-jisx0208)
          unicode-basic-translation-charset-order-list))

またバックスラシュと円記号の方も混乱が少ないように

 (require 'un-supple)
 (un-supple-enable 'windows)

を追加してく。

[ 3月8日全て ]

2010年8月18日 (水)

今日のさえずり: すごいね! サイコキネシスじゃん!

2010年08月18日

  • 09:32 車内子「すごいね! サイコキネシスじゃん!」()
  • 09:33 RT @xnomb: 一松信先生(数学者)の本はわかりやすいなあ。
  • 09:39 一松信先生懐かしいな。キャンパスで立ち止まっているときは、何かの計算をしているんだろうと言われてた気が。
  • 12:06 おにぎり 315円。 (@ セブン-イレブン神田佐久間町店) http://4sq.com/cEfW1k
  • 12:42 ほぼ日手帳2011のカバー、公式サイトでチラ見させている写真は女性向けっぽいのばかりだな。
  • 12:46 もう横綱にしちゃっていいよ。 RT @as_tone: そして今日も「ここ横綱って地名があるんだ!」と言っている人がいる@両国。横網(よこあみ)です…
  • 13:40 缶コーヒー 100円。
  • 14:14 久しぶりに C++ から C# の世界へ。ヘッダファイル書かなくていいの楽だわー。
  • 16:41 RT @rtmjp: 日本語によるRemember The Milkのtwitterアカウントを開設いたしました。最新情報、ブログ投稿、質問の回答などを行います。よろしくお願いします。参考までですが、ブログにも投稿しています。 http://ow.ly/2r9mX
  • 18:15 久しぶりに reStructuredText 使いたくなって Windows XP BOX に Python 3.1.2 と Docutils 0.7 をインストール
  • 18:37 reStructuredText でちょっこし書いて rst2html して Google ドキュメントアップロードしたら、変換できんってはねられた。
  • 20:03 雨降ってきてる。 (@ 秋葉原駅 (Akihabara Station) w/ 12 others) http://4sq.com/68fhHr
  • 20:26 こっちは今降ってない。
  • 21:08 頂き物のゆべし食べた。名前はどこかで聞いたような聞かないような感じだったけど、食べてみたところ多分お初。昔風だな。
  • 21:11 RT @America_Amazon: 友人の家に遊びに行ったらビニール袋に詰められた土が何個も飾ってあって、「何だよ、あれ?」と聞いたら「今まで付き合った女の家の、庭の土を記念に持って帰ってきたんだよ」という高校球児みたいな答えが返ってきた。リア充でも屈折するとキケンな ...
  • 21:23 明日から花輪ばやしだね。
  • 22:02 ぽ、PORTER ほぼ日手帳カバーだと!
  • 22:03 @_kojihiro 岩手のお土産らしいです。
  • 22:06 「手前のポケットはスマートフォンが収まるサイズ。」とか絶対狙い撃ちされてる。 RT @Naney: ぽ、PORTER ほぼ日手帳カバーだと!
[ 8月18日全て ]

About Me

Naney Naney (なにい)です。株式会社ミクシィで SNS 事業の部長をしています。

nDiki1999年1月に始めたコンピュータ日誌を前身とする NaneyWeb 日記(兼パーソナルナレッジベース)です。ちょっとしたノートは nNote にあります。

※内容は個人的見解であり所属組織とは関係ありません。

follow us in feedly

月別インデックス
Process Time: 0.062107s / load averages: 0.35, 0.59, 0.58
nDiki by WATANABE Yoshimasa (Naney, Google profile)
Powered by DiKicker