markdown記法によるWord文書などの作成

2019年 3月13日(水)

[更新情報]

 3月2日に公開したものを更新しました。

  1. 送るメニューの登録・消去の機能を各コマンドに持たせました。
    ファイル名として半角 ‘/’ を指定すると、送るメニューの登録・消去を行います。
  2. makeHTML または usePandoc でhtmlを生成する場合、半角のID属性を付加するようにしました。ID付加の処理を受け持つ AddHeadingID.vbs を同梱。gawk.exe が必要。

 送るメニューの登録・消去を行う SetSendTo.vbs が今回は含まれていません。

 代わりに DeleteSendTo.vbs を同梱しています。

 これは、関連の送るメニューを一括して消去するためのコマンドです。

 makeDOCXを起動してから、ファイル名を入力する場面で
半角の ‘/’ を入力してエンターキーをたたくと
makeDOCX が送るメニューに登録されます。

 既に登録されているときは、それが消去されます。

 ‘/’ の代わりに ‘sendto’ の6文字でもかまいません。

 この機能は、makeDOCX, makeHTML, makePPTX, usePandoc, copyTable, AddHeadingID に共通です。

 usePandoc, copyTable, AddHeadingID の解説は別サイトにしました。

 makeDOCXなどの関連コマンド を参照してください。

 なお、Wordを起動せずにほぼ同じ処理を行うための usepandoc.py(pythonスクリプト)を作りました。

 よかったら pandocとpythonの組み合わせによるWord文書の作成をご覧ください。

目次へ戻る

    

[はじめに]

 仕事で必須ツールといえる Word, Excel ですが、
GUIが苦手な私は、別の方法で切り抜けています。

 それが markdown記法でテキストファイルを作り、
そのファイルをWord文書に変換するという方法です。

 markdown記法は見出し、箇条書き、表などを
単純な文字の書き込みだけで表現できます。

 しかも html(MarkUp記法)よりもずっと手軽に書けます。

 結果、かなり時間の節約になっています。

 以下でそのノウハウについて記します。

(html, PowerPointへの変換も取り上げます。)

目次へ戻る

    

1. とりあえず試すには

 以下の作業は Windows環境下で、Word2007以降があることを前提とします。

 動作確認は、Windows7 + Office2010, Windows10 + Office2016 で行いました。

a. ファイルのダウンロード、解凍、コピー

 まず次の2つのファイルをダウンロードして解凍します。

 前者を解凍すると makeDOCX.vbs などが出てきます。

 後者からは pandoc.exe などが出てきます。

 pandoc.exe, pandoc-citeproc.exe の二つを makeDOCX.vbs と同じフォルダにコピーします。

 これで準備完了。

b. makeDOCX の実行

 makeDOCX.vbs を実行します。

 explorerで makeDOCX.vbs に焦点を当ててエンターキーを押せば実行できます。

 するとファイル名の入力を促す場面になるので
test.txt と入力してエンターキーをたたきます。

 しばらくすると「タターン」のような音がなり、処理終了。

 Wordファイルの test.docx が作成されているはずです。

 これで「お試し」が終了。

 他に log.txt というファイルもできていて、処理の記録メモが書かれています。

 ファイル名の入力ではワイルドカードも使えます。

目次へ戻る

    

2. 処理の概略

 変換処理の中核を担うのは pandoc.exe です。

 pandocの使い方の詳細は Pandoc ユーザーズガイド 日本語版 - Japanese Pandoc User’s Association を参照してください。

 makeDOCXは、変換処理の事前準備と事後の処理を含む全体を調整します。

 makeDOCXが行うのは下の 3ステップ。

  1. 事前の準備: 指定されたファイルの文字コードを Shift_JIS → utf-8 に変換。
  2. 変換処理: utf-8のファイルをpandoc.exeによってWordファイルに変換。
    返還後 utf-8のファイルは削除。
  3. 事後の処理: Wordを自動操作してファイルに変更を加える。

 pandocは、markdownのテキストファイルを Word, html, PowerPoint など
様々なファイルに変換する機能を持っています。

 ただし、扱える文字コードは utf-8 です。

 それに対して、日本語版Windowsでは Shift_JIS が標準です。

 そこで、makeDOCX では Shift_JIS → utf-8 の変換を行います。

 また、pandocにはWordファイルの細かな調整を行う機能がありません。

 ページサイズが欧米標準の letterサイズで、A4よりちょっとだけ幅が広いです。

 表には罫線がつきません。

 フッターにページ番号をつけるといった処理もありません。

 ということで、makeDOCXではWordを自動操作してその辺の変更・調整を行います。

目次へ戻る

    

3. markdown記法の基礎の基礎

 markdown記法は文書を書くときのルールです。

 詳細は他のWebを参照していただくとして、
私が気に留めている基礎的ルールを記します。

(1) 段落(パラグラフ)

 htmlと同じで、markdownでも改行は基本的に無視されます。

 改行して段落を替えたつもりでも改行になりません。

 そこで、段落の後には空白行を置きます。それで改行されます。

 エディタで書いていると、なんだか間延びした感じになります。

 慣れるまで空白行挿入を忘れがちなので注意が必要です。

 なお、段落を替えずに改行したいときは、行末に半角スペースを二つ置きます。

 するとWordでいう「行区切り」、htmlでは <br /> になります。

(2) 特別の役割を持つ半角の *, -, \ に注意

 文章中に半角の *, -, \ を文字として書くときは要注意。

 これらを文字として書き込むときは、それぞれ
‘\*’, ‘\-’, ‘\\’ のように2文字で表現します。

 ‘\’ は特別の役割を無効にする前置文字です。

a. ‘*’ の役割

 ‘*’ で囲むと、囲まれた文字が強調文字(斜体)になります。

 ‘**’ の二重のアスタリスクで囲むと、より強調される形(太字)になります。

b. ‘-’ の役割

 ‘--’ の2文字が短いダッシュ記号になり、
 ‘---’ の3文字が通常のダッシュ記号になります。

 ダッシュ記号は横棒の記号で「バー」とよぶこともあります。

(3) 見出し

 行頭に半角の ‘#’ を書いておくとその行が見出しになります。

 本文より文字が大きくなったり太字になったりします。

 ‘#’ が一つだと一番大きな見出し1、
二つなら次に大きな見出し2です。三つだと見出し3。

 本文部分は明朝体・12ポイントですが、
見出し1と見出し2はゴシック体・16ポイント・太字になります。

 見出し3が14ポイントとなり、見出し4以下は12ポイントです。

 見出しは、目次を自動生成するときに拾い上げられます。

 その際、見出し1、見出し2、…… の区別が意味を持ちます。

(4) 箇条書き

 行頭に *, -, + のいずれかを置いた行を何行か書くと
それが箇条書きになります。

 ‘*’ などの行頭のマークの後には半角スペースを2つ置きます。

 箇条書きの場合、行と行の間に空白行は置きません。

 行頭のマークはビュレット記号(中黒)、あるいは短いダッシュ記号になります。

 番号付きの箇条書きにするときは
‘1.’, ‘(1)’, ‘I.’, ‘a.’, ‘A.’ などを置きます。

 小文字ローマ数字の ‘i.’ の場合、事後のWordの処理で①, ②などの丸囲み数字に変更されます。

 箇条書きのどの行頭を ‘1.’ とした場合であっても、
ちゃんと 1., 2., 3. など適切な順序番号になります。

 半角スペース4個またはタブコードを行頭に置いて、
入れ子構造(インデントづけ)にすることもできます。

---- markdown記述ここから
*  果物
    i.  リンゴ
    i.  バナナ
    i.  みかん
*  野菜
    a.  大根
    a.  キャベツ
    a.  ごぼう
---- markdown記述ここまで

 上のmarkdown原稿が下のようになります。

(5) 表の作成

 データをカンマで区切るcsv形式は Excelで読み込むことができますが、
カンマの代わりに半角の縦棒 ‘|’ を書くと markdownの表になります。

 表の前と後には空白行を置きます。

 表の表題(table caption)を書くときは、
表の最後の行として、半角の ‘:’ と半角スペースを置いてから書きます。

 変換後はその表題が表よりも前に配置されます。

---- markdownの記述ここから
品名|購入先|価格
:--|:-:|--:
ショルダーバッグ|Aスーパー|15,000
スーツ|Bデパート|100,000
ゴミ袋|Cショップ|350
: 買物の記録
---- markdownの記述ここまで

 上記のmarkdown原稿を表にすると下のとおり。

買物の記録
品名 購入先 価格
ショルダーバッグ Aスーパー 15,000
スーツ Bデパート 100,000
ゴミ袋 Cショップ 350

 表の 1行目と2行目の間にある記述

:--|:-:|--:

 上記はセル内の文字の配置を指定するものです。

 この行がないと表にならないので注意してください。

(6) 画像の挿入

 画像として扱えるファイル形式は png, jpg などです。

 画像を挿入するための基本的なmarkdown記述は下のとおり。

![放物線](parabola.png)

 先頭は感嘆符で、角括弧の中には画像のタイトルとか注釈を書き、
そのあとの普通の括弧の中には画像ファイル名を書きます。

 上のように書くと「放物線」が画像のキャプションとなり、
画像の後に書き出されます。

 キャプションが書き出されるのは画像が一つの独立した段落になっている場合です。

 画像が段落の中で文章と一緒になっていると
インライン画像ということでキャプションは現れません。

 画像がページ内におさまらない場合はページが替わります。

 インライン画像の場合、画像の前にある文章のところからページが替わります。

 画像挿入の記述 ![……](……) があっても、
肝心の画像データ(png, jpgなど)がなければ挿入されません。

 そのとき、pandocは警告メッセージを出しますが、
そのメッセージは log.txt に書き出されます。

(7) 冒頭にタイトルなどを書く場合

 文書の冒頭にタイトル、著者、日付を書くときは
ファイルの最初に半角の ‘%’ とスペースで始まる行を置きます。

% 食品ロスの実態とその解決策について
% 斎藤一郎,鈴木次郎,田中三郎
% 2019年 2月11日
  [空白行]
# はじめに
  [空白行]
…………

 タイトルは 18ポイント・太字、著者と日付は本文と同じ 12ポイントになります。

 三つとも配置が中央揃えに調整されます。

 タイトルだけを指定するなら ‘%’ の行を1行だけ書きます。

 タイトルと著者なら 2行ですが、タイトルと日付のときは下の 3行にします。

% 食品ロスの実態とその解決策について
%
% 2019年 2月11日

 これら ‘%’ で始まる行は、なくてもかまいません。

 ただ、後述の htmlへの変換のときは、タイトルだけでも書くことをお勧めします。

(8) ハイパーリンク

 Webでは他のページにリンクをはることがよくあります。

 その場合、次のように記述します。

[foo page](http://www.foo.or.jp/)

 前の方で角括弧を、その後で普通の括弧を書きます。

 画像挿入の記述から、先頭の ‘!’ を除いた形です。

 この記述がWordでもハイパーリンクを生成します。

 Word文書中のハイパーリンクの箇所にカーソルがある状態で、
コンテキストメニュー(右クリックメニュー)の
「ハイパーリンクを開く」を選択するとブラウザが起動します。

 同じ文書内のリンクの張り方については、手抜きですみませんが省略。pandocの解説サイトを参照してください。

目次へ戻る

    

4. html, PowerPointへの変換

 makeDOCXの他に makeHTML, makePPTX というコマンドもあります。

 それぞれ html, PowerPoint に変換するコマンドです。

 makeDOCXの場合は pandoc で変換した後に Wordの自動操作で変更を加えますが、
html, PowerPoint の場合は pandocで変換したらそれで終了です。

 markdownでの原稿の書き方は、makeDOCXの場合と同じです。

 htmlに変換するときは、‘%’ で始まるタイトルを書くことをお勧めします。

 それがないと pandocが警告メッセージを出力します。

 警告メッセージは、log.txt に記録されます。

 それから、PowerPointに変換する場合、
タイトル、著者、日付のうちの「著者」が
「サブタイトル」の位置づけになります。

 タイトル、サブタイトル、日付が最初の1枚のスライドになり、
それ以降は、見出し(‘#’ で始まる行)が替わるごとに別のスライドになります。

ご注意(視覚障碍者向け)

 pandocで作成したpptxファイルをPowerPointで開いて、
表示させるだけでなく編集・修正しようとすると、
画面読み上げソフト PC-Talkerの場合、エラーが発生するケースがあります。
(Windows10用のPC-Talkerでは大丈夫な感じですが、Windows7用でエラーになるような気がします。)

 画面読み上げソフトNVDAではそうしたトラブルを経験しません。

 不思議なことに、NVDAの下でpptxファイルを開いて中身を確認してから閉じたとします(上書き保存するわけではない)。で、その同じpptxファイルをPC-Talkerの下で開くと、今度はエラーが発生しません。

 ともあれ PC-Talkerユーザーはご注意ください。

目次へ戻る

    

5. pandoc用のオプション

 pandocには多数のオプションがあります。

 そのうち私が特に気に留めているものを記します。

(1) 原稿中にオプションを書き込む

 まず、オプションの書き方ですが……

 pandoc用のmarkdownの原稿では下の行が覚書のメモとして無視されます(返還後の文書には表面に出てきません)。

<!-- ……… -->

 これは html のコメントの書き方です。

 このコメントの形で pandoc用のオプションを書き入れることができます。

<!-- pandoc --toc --mathml -->

 上のように書いておくと --toc および --mathml を指定することになります。

 <!-- は、前に空白を置かず必ず行頭から書いてください。

 tocは目次の生成、mathmlは数式の記述を有効にするオプションです。

 このコメント形式のオプションは、ファイル中のどこに書いてもかまいません。

 ただし、% で始まるタイトルなどの記述よりは後ろに書きます。

 なお、このオプションの指定方法は、makeDOCX, makeHTML, makePPTX だけで有効な方法です。pandoc利用全般について適用できる方法ではありません。

(2) 目次の生成

 --toc を指定すると目次が生成されます。

 見出し1~3が拾われて目次に盛り込まれます。

 見出し1だけを目次に盛り込みたいときは
--toc-depth=1 というオプションを合わせて指定します。

 見出し1, 見出し2を拾うなら数字を 2 にします。

 Wordの場合、目次にページ番号も付きます。

 pandocは、letterサイズのときのページ番号をつけますが、
Wordの自動操作においてページ番号の付け直しをやるので、
他のサイズにしたとしても正しい番号になるはずです。

(3) 数式の記述

 数式は、半角のドル記号を二重にした ‘$$’ で囲みます。

 数式の記述形式は LaTeX の形式です。

 たとえば \frac{1}{2} が分数の2分の1を表現します。

 ただし、--mathml を指定しないと数式として正しく扱われません。

 htmlに変換する場合はこのオプションを必ず指定します。

 Wordに変換するときはなくても大丈夫そうですが、つけておくのが無難かも。

 実は、数式については --mathml ではないオプションもいろいろあります。

 また、ドル記号を二重にせず ‘$’ で囲む書き方もあります(書く際のルールが増えるのでややこしいですが)。

 詳細は pandocの解説サイトを参照してください。

---- markdown記述ここから
% 数式の記述
<!-- pandoc --mathml -->
  [空白行]
*分数の計算*: 1/2 + 1/3 = (3+2)/6 = 5/6
  [空白行]
$$ \frac{1}{2} + \frac{1}{3} = \frac{3 + 2}{6} = \frac{5}{6} $$
---- markdown記述ここまで

目次へ戻る

    

6. Word文書を調整するためのオプション

 makeDOCXは、pandocで変換した後にWordを自動操作して変更を加えます。

 どんな変更を加えるかを示しつつ、変更の在り方をコントロールする方法を記します。

(1) ページのサイズに関する調整

 pandocが生成するのは letterサイズですが、それをA4サイズに変更します。

 デフォルトで「A4 縦長 40行 35桁」になります。

 <!-- PageSize=A5 --> という 1行を書いておけば
A5サイズに変更できます。

 makeDOCXで指定できるサイズは次のとおり。

 B4, A4, B5, A5, HG(ハガキのサイズ)

 横長にしたいときは A4L のようにアルファベットのエルを付けます。

 横長を意味する landscape の頭文字のつもり。

: <!-- PageSize=B5L -->

(2) ページ番号

 各ページのフッターに 1/5 とか 4/5 のようなページ番号をつけます。

 「該当ページの番号、スラッシュ記号、総ページ数」の形式で
中央揃えでページ番号が付けられます。

 つけない場合は PageNumber=no を指定します。

 PageNumber=yes だとページ番号が付きます。

 yes, no は小文字で書いてください。

 ハガキ印刷用文書だとページ番号が不要です。

 また、後で自分なりにページ番号をデザインしたいときも番号がない方がやりやすいとおもいます。

: <!-- PageNumber=no PageSize=HG -->

 上のように複数のWord用オプションを 1行にまとめて書くことができます。

 ただし、pandoc用のオプションとは混在させないでください。

(3) 数値を指定するフォントサイズ、文字数、行数、段組数

 数値を指定するオプションには次のものがあります。

  1. FontSize: 標準フォントサイズ。指定しないと12ポイント。
    FontSize=10.5 のように指定。
  2. CharsLine: 1行あたりの文字数。指定できない数値を書くとエラーになる。
  3. LinesPage: 1ページあたりの行数。指定できない数値を書くとエラーになる。
  4. TextColumns: 段組みの数。TextColumns=2 とすれば2段組みになる。

 文字数と行数は、ページサイズや標準フォントサイズによって
指定可能な値が変化します。

 可能な値でない場合、makeDOCXがエラーメッセージを出して処理が中断されます。

 そのときは Wordが起動したままになってしまうので手作業で終了させてください。

(4) 表に関する調整

 以下に掲げる表の調整は、文書中に複数の表がある場合、
すべての表に一括して適用されます。

a. 罫線

 pandocで生成される表では、1行目と 2行目の間に罫線が引かれます。
でも、それ以外の罫線はありません。

 そこで、外枠を二重線、内側を普通の実線にします。

<!-- TableBorder=no -->

 上の行がファイル中にあると、罫線は引かれません。

b. 中央揃え

 表がページ内の左右バランスにおいて中央に位置するよう調整します。

 表にキャプションがあるときは、それも中央揃えにします。

<!-- TableCenter=no -->

 上の行があると、中央揃えにはなりません。

c. 1行目を均等割り付け

 表の 1行目の各セルの文字配置を均等割り付けにします。

 TableRow1=no を書いておくと、均等割り付けになりません。

(5) 画像の中央揃え

 画像をページ内の左右バランスにおいて中央揃えにします。

 画像のキャプションがあるときは、それも中央揃えにします。

 ただし、画像が独立した段落(パラグラフ)でない場合、
たとえば、文章と一緒になって段落を構成している場合は
中央揃えになりません。

 ImageCenter=no を指定すると、画像を中央揃えにしません。

(6) Word自動操作の抑制

 pandocの処理結果そのままを得たいときは WordRemake=no を指定します。

 これがあると Wordの自動操作は行われません。

 結果として、Wordに関するオプションが書かれていても、それらは生かされません。

(7) Word用オプション一覧

 Word用オプションをそのデフォルト値とともに記します。

目次へ戻る

    

7. 補足事項

 ワイルドカードを使ったファイル名の指定、
pandocのデータディレクトリの意味合いなどについて補足します。

(1) ファイル名の指定方法

 makeDOCXを実行するとファイル名を入力する場面になります。

 その際、*.txt のようにワイルドカードを使うことができます。

 *.txt の場合、カレントフォルダにある拡張子 .txt のファイルすべてが対象となり、実際 makeDOCXで複数のファイルが処理されます。

 これは makeHTML, makePPTX でも同様です。

 それから、makeDOCXなどはコマンドプロンプトにおいて実行できます。

 C:\> のような表示が出ているところで

makeDOCX word*.txt  [エンターキー]

 上のように入力すると、該当のファイルが処理されます。

(2) サブフォルダpandocに入っているもの

 use_markdown.zipを解凍すると pandoc というサブフォルダが出てきます。

 その下には reference.docx というファイル、
それから templates というフォルダがあります。

 reference.docx は、Wordファイルを作成するときに pandocが参照するスタイル定義ファイルです。

 これは、pandocが用意しているデフォルトのものに少し変更を加えたものです。

 見出しが青色に設定されているのを色なしにするなどの変更です。

 必要に応じて好みの形に修正してください。

 templates というサブフォルダには template01.html があります。

 これはデフォルトのテンプレートに次の手を加えたものです。

 template01.html を利用するときは、markdownの原稿に下の行を書き加えてください。

<!-- pandoc --template=template01.html -->

 pandocにはデータディレクトリというのがあり、そこに reference.docx などがあるものと仮定されます。

 本来のデータディレクトリは C:\Users\Taro\AppData\Roaming\pandoc のようなディレクトリです(Taroはユーザー名の例)。

 makeDOCXなどではこれを直下の pandoc というサブフォルダに変更しています(--data-dir オプションで変更)。

 pandocをフルに活用する場合は、このデータディレクトリがいろいろ関わってくるので念頭に置いてください。

(3) 終了時の音について

 視覚障碍者の私には makeDOCXの処理が終了したかどうか分かりにくいので音をならすようにしました。

 C:\Windows\Media の下にあるwavファイルを再生しているだけです。

 正常終了のときは「タターン」のような音、
エラーのときは「ガリガリ」のような耳ざわりな音です。

 VBscript内にある次の行を書き換えることで別の音に変更できます。

normalSound = "C:\Windows\Media\tada.wav"  ' 正常終了のときの音
errorSound = "C:\Windows\Media\ringout.wav"  ' エラー終了のときの音

 wma, mp3 の再生も可能です。

 存在しないファイル名にすれば音はなりません。

(4) 他のファイル形式の出力

 pandocは様々な形式のファイルを出力できます。

 rtf, epub, odt, tex 等々。

 makeDOCXなどを利用したとき、pandocのオプションとして出力ファイル名を指定すると、指定されたファイルが書き出されます。

<!-- pandoc -o test.rtf -->

 原稿中に上の行があると、DOCX, HTML, PPTX ではなく RTFファイルが出力されます。

 あまりお勧めはしませんが、そんなことも可能であることを補足しておきます。

 rtf, odtなどの生成は、一度 DOCX を作成し、
それをWordで読み込んだ上で好みの形式で保存する方が
整った文書になるのでは?とおもいます。

 いろいろな形式のファイルを生成したい場合は、
pandocを直接 使うことをお勧めします。

(5) pandocのバージョン

 「とりあえず試すには」でリンクをはってある pandoc は、
pandoc ver 2.6 32bit版です。

 2019年2月現在で最新版だとおもいます。

 pandocは、ときどきバージョンアップされるので Webで検索すれば
もっと新しいバージョンがみつかるかもしれません。

 また、32bit版でなく 64bit版もあります。

 64bit版を使いたい方もWebを検索してみてください。


 以上で makeDOCXの説明は終わりです。

 ここに掲げたmarkdownの解説は、ごくごく一部です。

 pandocの機能についてもほとんど説明していないといっていいかもしれません。

 上付き・下付き文字、脚注、引用等にはふれませんでした。

 あるいは、表の書き方を1種類しか紹介しませんでしたが、実は 4種類あります。

 一つのセルに複数の行を組み入れたい場合は、紹介したのとは別の書き方を使います。

 興味を持たれた方は pandocの解説サイトや markdown関連サイトを参照してみてください。

Copyright (C) T. Yoshiizumi, 2019 All rights reserved.