niszetの日記

アナログCMOS系雑用エンジニアが頑張る備忘録系日記

(1/15 追記) Markdown Preview Enhanced+pandocでdocxを出力する際のあれこれ(あるいはスタイル対応表)

背景

さて、前回の記事 niszet.hatenablog.com

niszet.hatenablog.com

の続きになります。

markdownはテキストファイルで書ける点が良いところですが、残念ながら現職ではそのメリットを活かす機会はこなそうです(まずgit使用してないからね…) そこで、「自分はmarkdownで書くが提出する際にpandocにてwordに変換してからリリース」という方法でなんとかしようという魂胆です。

なお、下記は書きかけ…というか、markdownを実際に変換して生成したdocxを眺めて調べた範囲で出来る分としては一旦closeです。が、対応関係が不明なものが結構あって、これはpandocのソースを読んでどれがどのスタイルになっているかを確認しないと手間がかかりすぎるな…という感じになっています。

もしお気づきの点があればご連絡…なくていいや、どこかにまとめてください…

なお、公式のマニュアルはこちら(英語)です。

Pandoc - Pandoc User’s Guide

reference.docxを準備する

さて、markdownからword文書への変換自体はpandocを使うことで出来るのですが、wordを出力する際、やはり気になるのはその書式です(正確には提出先の方が気にされますね)

公式のマニュアルにもスタイルを指定することが出来る点については触れられています。しかし、細かい内容、特にmarkdownのどの部分がどの書式(スタイル)に対応するのか?という点については公式以外含めて検索してもわかりませんでしたので(例によって)自分向けにまとめておこうという点が本記事のモチベーションとなります。

また、出来上がったword文書を一つ一つ、イチイチ手で修正していたらmarkdownで書くメリットが全然ないわけでして。そのため、あらかじめreference.docxという名前で書式のテンプレートを作っておき、そのスタイル情報を使用してdocxを生成させるのがpandocを使用したmarkdownからwordドキュメントファイル生成手順としては鉄板だと思います(同様の内容は検索すると沢山出てきます)

テンプレートとなるファイルの場所は --data-dir=DIRECTORY でDIRECTORYに指定したディレクトリにある、--reference-doc=FILE のFILEで指定したファイルになりますが、デフォルトでは C:\Users\USERNAME\AppData\Roaming\pandoc となるそうです。これはpandoc --versionで確認でき、私(niszet)の場合は

C:\Users\niszet>pandoc --version

pandoc 2.1
Compiled with pandoc-types 1.17.3, texmath 0.10.1, skylighting 0.5.1
Default user data directory: C:\Users\niszet\AppData\Roaming\pandoc
Copyright (C) 2006-2018 John MacFarlane
Web:  http://pandoc.org
This is free software; see the source for copying conditions.
There is no warranty, not even for merchantability or fitness
for a particular purpose.

でした。例と一致していますね。ここにreference.docxという名前でテンプレートとするファイルを置けばよいです。

なお、後述するように書式だけを使用するため、文書内部に文字や図が含まれていても問題ありません。ただし、秘伝のタレのようにして引き継がれたドキュメントの場合は使えないかもしれません(実際に過去使えなかった事があるため)

なお、reference.docxの元になるファイルは下記コマンドで生成できますが、

pandoc --print-default-data-file reference.docx > custom-reference.docx

生成されたcuston-reference.docxの中には書式を設定できるスタイルが一覧で書かれています。

f:id:niszet:20180112231450p:plain

公式のマニュアルには下記について書式の設定が出来る、とあります

For best results, do not make changes to this file other than modifying the styles used by pandoc: [paragraph] Normal, Body Text, First Paragraph, Compact, Title, Subtitle, Author, Date, Abstract, Bibliography, Heading 1, Heading 2, Heading 3, Heading 4, Heading 5, Heading 6, Heading 7, Heading 8, Heading 9, Block Text, Footnote Text, Definition Term, Definition, Caption, Table Caption, Image Caption, Figure, Captioned Figure, TOC Heading; [character] Default Paragraph Font, Body Text Char, Verbatim Char, Footnote Reference, Hyperlink; [table] Table.

後述の通り、実は生成されたスタイルはこれだけじゃないんですが…。

markdown中のどの記述がwordのどのスタイルに対応しているのか確認する

まずは先に生成した(custom-)reference.docxについて、設定されているスタイルを調べてみます。

こちらの記事を参考に、ファイル - オプション - 詳細設定から「下書き表示およびアウトライン表示でのスタイル名表示領域」を適当に設定(下記記事では20mm)します。 ciao.aoten.jp

すると、ツールバーの[表示]-[下書き]で表示するとreference.docxは下記のように表示されます。

f:id:niszet:20180114213916p:plain

これで各行に使われているスタイルの確認が容易になるはずです。ただし、文中にスタイルが変更されている箇所については正しく見ることが出来ません。
スタイルの確認はツールバーのホームで、スタイルとなっているところが選択されて表示されるのでわかるのですが、ここに表示されていないものは右下のマークを押して表示されていないスタイルも表示する必要があります(下図の見出し6の右下ね)

f:id:niszet:20180114214410p:plain

これで、今選択しているplot(iris)と書いている部分がSource Codeのスタイルであることがわかりますね。

なお、このスタイルの表示、アクティブになったスタイルにスクロールしてくれないので、ハイライトされている項目を自分で探す必要があります。面倒くさい。
word嫌いなのはこういうところだよ…

一覧(暫定)

気を取り直して現時点でわかっている範囲の対応表です。ご参考程度に。

[paragraph] Normal (1/15追記)

日本語wordだと「標準」スタイル。基本的にすべてのスタイルはこの標準スタイルを継承しているため、このスタイルを変更するとすべてのスタイルが変更されてしまうため、注意。
ただ、素の設定のままだと行間が1行になっていてすごい間延びしたスタイルになります。固定にするか、最小値で入れておくと良いと思います。
自分はフォントをMeiryo にしていますが、この場合はptをフォントのサイズx1.5くらいにしておくとまぁまぁ良い感じに文字が詰まります。

[paragraph] Body Text

日本語名は本文。基準スタイルは標準。次の行は本文。普通に文章を書いていくとこのスタイルが使用されるので、スタイルを変更するなら標準ではなくてこちらかな?

[paragraph] First Paragraph

日本語名は不明。見出し直後に*などでリスト化せずにそのまま文章を書き始めるとこの書式が設定される。基準スタイルは本文。次の段落は本文スタイルとなる。字下げなどに使うか?

[paragraph] Compact

日本語名だと行間詰め?

[paragraph] Title

日本語名だと表題。Markdown Preview Plusの場合、YAMLヘッダ中に記載することでTitleを生成できる。この点についてはいずれ別の記事に書きます。

[paragraph] Subtitle

日本語名だと副題。Markdown Preview Plusの場合、YAMLヘッダ中に記載することでSubtitleを生成できる。この点についてはいずれ別の記事に書きます。

[paragraph] Author

日本語スタイル名は不明。Markdown Preview Plusの場合、YAMLヘッダ中に記載することでAutherを生成できる。この点についてはいずれ別の記事に書きます。

[paragraph] Date

日本語スタイル名は不明。Markdown Preview Plusの場合、YAMLヘッダ中に記載することでDateを生成できる。この点についてはいずれ別の記事に書きます。

[paragraph] Abstract

Abstractを書いた場合に領域に設定される。Markdown Preview Plusの場合、YAMLヘッダ中に記載することでAbstractを生成できる。この点についてはいずれ別の記事に書きます。

[paragraph] Bibliography

参考文献に当たるスタイルだと思いますが、よくわかりません。保留。

[paragraph] Heading 1- 9

日本語名だと見出し1, 見出し2, ... のスタイル。markdownでは #, ##, ... に対応する。

[paragraph] Block Text

日本語名だとブロック。基準は本文。次の段落は本文。> で始まる行がこのスタイルとなる。基準スタイルは本文、次の段落も本文。

[paragraph] Footnote Text

[paragraph] Definition Term

現時点で生成する方法不明

[paragraph] Definition

現時点で生成する方法不明

[paragraph] Caption

現時点で生成する方法不明

[paragraph] Table Caption

現時点で生成する方法不明

[paragraph] Image Caption

現時点で生成する方法不明

[paragraph] Figure

現時点で生成する方法不明

[paragraph] Captioned Figure

現時点で生成する方法不明

[paragraph] TOC Heading

pandoc実行時に--tocをつけることで目次を入れることが出来るが、目次の見出し、目次1, 目次2, ... と目次作成に使用された見出しの階層関係に対応してスタイルがそれぞれ与えられる。

[character] Default Paragraph Font

現時点で生成する方法不明

[character] Body Text Char

現時点で生成する方法不明

[character] Verbatim Char

本文中に...のようにしてback tickで囲った部分はこの書式となる。

[character] Footnote Reference

現時点で生成する方法不明

[character] Hyperlink

日本語名もハイパーリンク。基準にするスタイルは図表番号(文字)

[table] Table.

現時点で生成する方法不明

例に含まれていないが実際には生成されるスタイル

ソースコード ...

これはSource Codeというスタイルになります。 生成したreference.docxにはこのスタイルは含まれていませんが、新たにこの名前のスタイルを追加しておいてdocxを生成するとこのスタイルが使用されるようでした。
reference.docxを不必要に修正するのはあまり推奨されないとは思うのですが、とはいえ書式気になるし…。

なお、このブロック、変数名や=、数字などそれぞれの文字に対して別々のスタイルが使われているようです。このあたりから生成物でチェックすることに限界を感じたので、現時点でのチェックは終了、pandocの中身を確認して対応表を作ることにします(いつ完成するかはわからない)

TOCをつけるにはYAMLヘッダを変更する

なお、MPEでTOCを有効にするにはYAMLヘッダ部分を下記のようにすると出ます。

---
title: "Markdown to Docx by MPE/pandoc2.1"
author:  niszet
date: Jan 13, 2018
output:
  custom_document:
    path: ./test.docx
    toc: true
---

本当はプラグインのsettingのpandoc optionでいけるはずなんですがうまく動かず。同様にyamlヘッダ部分に下記を追加しても無効でした。tocのtitleの設定も効かない。

    pandoc-args: [
      "--toc-depth", "6"
    ]

バグかなーって思うのですが、ちょっと自信ないのでissueとかはまだあげてないですが…。まぁ、mdが生成できれば自分でpandocに流し込めばいいからいいかなー

リストのスタイル (2018/01/15追記)

これはまた別の話ですが、wordではスタイルにリストを紐づけることが出来ませんね?(たぶん。)
pandocのソースをチラ見した感じで、このインデントが固定値になっているっぽいです。そのため、現状ではスタイルを定義したりしてリストのインデント深さを変更することは通常の使い方であれば難しいのだと認識しています。生成後に処理するのでVBAでやるのかなぁ…
ただ、reference.docxにリストを定義しておくと、その設定は引き継がれるようです。そのため、生成したdocxを開いて、自分で定義したリストのスタイルを反映させることで対応は一応できるのかな、と思っています。TOCを入れた場合、開くと確認ダイアログも出てしまいますし、まぁdocx大量生成する機会はそうそうないでしょう、ということで、ここは諦めてボタンポチポチしましょう。

reference.docx が互換モードで開かれる(2018/01/15追記)

これもよくわかりませんが、上の方に書いた方法で生成したreference.docxは互換モードで開かれるようです。
このまま使い続けることも出来ると思いますが、一応変換した方が無難かな。ファイル->情報から 互換モードと書かれた文字の近くの、変換ボタン(アイコン)を押して変換しましょう。確認ダイアログが出ますが、OKを押して変換しましょう。なんか今テーブルが動いたような…?
細かい差分を把握していないのですが、互換モードと通常のdocxだとどうも見栄えが微妙に変わるようです。なので、スタイルを設定する前に変換しておいた方が良いでしょうね。

Rで出来ませんか…?

MPEと同じことをRmdでもやりたいと思っています。が、knitまわりの理解がまだまだなので…。
これでreproducibleなドキュメント生成環境に出来るのか?というと微妙ですが…。まずはMPE使いこなしてからかな。Rmdはまだpandoc1.x系で動いてますので、移行が終わったころに本気出せるように今からコツコツと調べておきましょう。