実務に使うプレーンテキスト→Microsoft Word変換、あるいはPandocを使い始めた話
SIerのお仕事で、設計書を書いたりするときに、Microsoft Office Wordのdocxファイルを使うことがあります。
そんな中でも、ドキュメントのフォーマットがある程度自由にできる場合に*1、Wordで直接書くのをやめて、プレーンテキスト(Markdown)で書いて、Pandocというツールでdocxファイルに変換するようにしてみた、という話です。
動機
何故Wordに直接書くのを止めるのか、という話はいくらでも先例がありそうですが、個人的には以下のあたりが大きいです。
- Git等のバージョン管理ツールを使うので、差分が取りやすい形式がよい
- Wordの入力機能が時々お節介でうざったい、いちいち設定で無効化するのも面倒
- GUIであちこちクリックしながら入力したくない、Emacs(またはあなたの好きなエディタ)を使いたい
Pandocについて
Pandocは Haskell で書かれたライブラリおよびコマンドラインツールであり、 あるマークアップ形式で書かれた文書を別の形式へ変換するものです。
対応している入力・出力形式は多岐に渡ります。
環境構築
今回やってみた環境は以下です。
ワードに関しては省略、Pandocに関してもインストーラのmsiファイルをダウンロード、実行して、指示に従うだけなので簡単です。
文書のつくりかた
Markdown記法でテキストファイルを書く
ここを見ている皆さん方には馴染みかもしれませんが、概要はMarkdown - Wikipediaあたりを参照してください。また、Pandocでの拡張に関してはユーザーズガイドの「Pandocによる拡張Markdown」のあたりを見ましょう。
例えばこんな感じに。*2
% ○○システム 基本設計書 % ××社 % 2015年1月 # 文書概要 この文書では、○○システムの各機能の基本的な設計を記述する。 # 開発環境 開発に用いるソフトウェアは主に以下である。 | 分類 | 名称 | 説明 | |:-------|:--------|:-------| | OS | Windows 7 | 開発マシンのオペレーティングシステム | | IDE | Visual Studio 2012 | プログラムの記述等を行う統合開発環境 | | DB | SQL Server 2012 Developer Edition | 開発時に使用するデータベース | # 機能設計 ## ログイン ### 概要 ユーザーのログイン認証を行い、成功した場合はメニュー画面に遷移する。 ### 画面イメージ  ### イベント #### ログインボタンクリック ログインボタンがクリックされた場合の処理は以下とする。 - 入力チェックを行う - ログイン認証を行う - メモリ内にログイン情報を保持する - メニュー画面に遷移する
このようなファイルを作って、基本設計書.md等として保存します。文字コードはUTF-8, 改行コードはLFです。*3
そして、コマンドラインから次のコマンドを実行します。実行ディレクトリは保存したファイルのあるディレクトリとします。
pandoc 基本設計書.md -o 基本設計書.docx
すると、同一フォルダに基本設計書.docxが出力されていて、Wordで開くとなにやら良い感じに整った出力がされています。
コマンドは何度も実行することになるので、バッチファイル化して同じフォルダに保存しておくと、ダブルクリックだけで実行できて良いでしょう。*4
テンプレートファイルの指定
しかし、このままではまだ今ひとつに見えます。そこで、文書の書式を予め設定したファイルを作っておいて、それを基にPandocにファイルを作成させることにします。
テンプレートファイルを取得する
次のコマンドで生成されます。
pandoc --print-default-data-file reference.docx > reference.docx
コマンドを実行したフォルダにreference.docxが生成されています。
テンプレートを指定して出力する
reference.docxファイルを、変換したい元のファイル(基本設計書.md)と同じディレクトリに置いた場合、次のコマンドを実行します。
pandoc 基本設計書.md --reference-docx=reference.docx -o 基本設計書.docx
すると、reference.docxファイルに加えたスタイルの変更が、出力されるファイル(基本設計書.docx)にも反映されます。
テンプレートファイルの改善
個人的に設定すると良さそうに感じたのは以下です。
ヘッダ・フッタ・ページ番号
- ページの上部や下部を右クリックして編集します。
- ページ番号は
現在ページ / 総ページ数形式 - ドキュメント情報の「ドキュメントタイトル」も問題なく反映されます。
見出しスタイル
- 見出しに番号を付けます。
- 参考: Word2010：1、1-1、1-1-1のアウトライン番号を設定するには？ - 教えて！HELPDESK
- アウトライン -> 新しいアウトラインの定義 -> レベルと対応付ける見出しスタイル なんて気づかないですよね普通……
- 参考: Word2010：1、1-1、1-1-1のアウトライン番号を設定するには？ - 教えて！HELPDESK
- 特定レベルの見出し(例えば見出し1のみ)の直前に改ページを設定します。
- ホーム -> スタイル -> 見出し1を右クリック -> 変更 -> 「スタイルの変更」内の書式 -> 段落 -> 改ページと改行 -> 「段落前で改ページする」にチェック
- 好みですが、左インデントは0にしてしまった方が見やすい気がします。
その他
色や段落の間隔等も適宜調整してしまいましょう。このあたりはもはやPandocに無関係なWordのテクニックです。
結果
だいぶ使えそうな気がしてきませんか？
課題
- 表(table)のデフォルトのスタイルの設定がどこかよくわかりません。Wordスキルが足りません。
- 目次の自動生成は、多分無理です。最終的に必要になったら手作業でWordを操作して自動生成させる方針になると思います。
不具合？
どうにも上手く行かないところがあってissueを投げました。つらいです。*5 比較的新しいソフトウェアで、開発も活発に行われているようなので、罠を踏んでもきっと何とかなります、多分。
といったところで今回は以上です。
