(メモ) ドキュメント楽に作りたいのでMarkdown Preview Enhancedを使い始めた
Atom + Markdown Preview Enhanced で対応できることは対応する。
今までAtomでMarkdownを書くときはMarkdown Preview Plusを使っていたのですが、Markdown Preview Enhancedというパッケージがあったのですね。
VSCodeの方も試してみましたが、Atomの方が完成度が良い気がします。まぁ、どちらか普段使っている方を使えばよいのかなとは思いますが…。
正直このパッケージだけでやりたいことは大体できる。
もともと、個人的にはMarkdownは使っていたものの（使っているのは主にRmdな気もしますが…）、図表関係に難があって今まで使いきれていませんでした。
図は埋め込めば良いといえば良いのですが、その図をどうやって作るのか？というところで一旦エディタから離れたところで作業するというのが億劫で…
また、Markdown書式でモノを書くことを社内的に布教しようと2年ほど前からしていたのですが、未だ上手くはいっておらず。その原因はやはりエディタがないとテキストファイルだけ見ても名に書いてあるのか良く分からんし記法覚えるのは大変だし、そもそもgit使ってない時点でテキストで書くモチベーションあまりないし、社内文書はwordだし…etcetcみたいなところにあると思っています（IT系ならまぁ難なく、なのでしょうが、それ以外の環境で、プログラム経験全く内容な人を対象に布教するというのはなかなか大変なのです）
しかし、pandocを利用してwordで出力することが出来れば使う人も増えるのではないか、という期待をしています。
まぁ、仮にもし使われなくても自分はword直接触らなくてもコレを使えば良いので損はないし、ということで、ここ2日ほどこれと格闘していました。
実際、客（提案先）としては、中身がどうかは2の次で「使い勝手」や「価値あるか？」…で判断するということですね、何事も提案するときは考えなくてはね…
出来ることについては公式のページに書かれていますが、個人的には中でも以下の点に注目しています。
他にもコードチャンク埋め込んだり、importで別ファイル管理出来たり…という点も見逃せないですが。 一応、それぞれの項目に関連するリンクも貼っておきますね。
PlantUML
UMLをテキストで書くために作られた（らしい）言語。フローチャートをはじめとして、色々なものが描けます。
UMLはかじった程度にしか知らないのですが、シーケンス図は他部署とのやり取りについて時系列にまとめるときに重宝しました（本来の使い方とは違うのかもしれませんが、職場ではUML使わないですので…）
plantuml.com
回路設計的には状態遷移図の方が重宝しますかね。アクティビティ図はそのままフローチャートですが、ちょっと見づらくなるんですよね…
同様な機能のmermaidでも良いので（こちらも同様にMPEで使用可能）、見やすい方で描くのかなぁ
CircuiTikZ
TeX/LaTeX で電気/電子回路の回路図を描くことができるパッケージ。 github.com
これもモチベーションとしてはそれなりに大きいです。RMarkdownの場合、html系とpdf系が別になっている（？）ためにこのパッケージを使えないでいました。
最悪、ここから図を作れさえすればあとは通常のMarkdownで良いわけですから、pdf2svgなどで図に変換出来れば…（回路図は大概別に描いてあるので、最悪これは使えなくても良いのですが．．．）
WaveDrom
ディジタルの波形や簡単な回路図を描くことができる。専用のエディタもあるが、Markdown Preview Enhancedでは.jsファイルを使用してMarkdownに埋め込んでいる WaveDrom - Digital timing diagram everywhere
これもかなり期待。こちらはjsなのでリアルタイムプレビューが可能です。
これ、昔（今も？）筑波大の武内先生が作られていたタイミングチャート清書サービスと同じような図が描けます。
ソフトウェア/タイミングチャート清書サービス - 武内＠筑波大
と思ったら、WaveDromについて言及されていました（最近更新されたのかな…？）
必要なツール類などを揃える
自分が今やりたいことはほとんどできそうです。ただ、現時点で色々と課題があるため今後の記録のために書いておきます。
なお、このパッケージは機能の多さもすごいですが、更新頻度も多いため、ネット上にある情報があっという間に古くなる可能性が大です
検索等でこのページにたどり着いてしまった方は現状については公式のページから情報を得るようにしてみてください。
私の作業環境・バージョン (主なものだけ)
win10 64bit + ATOM Version 1.23.2 (記事執筆時点最新)
Markdown Preview Enhanced 0.15.2(同上)
pandoc 2.1
Microsoft Word 2016
pandocについて
先日、pandoc 2.1がリリースされました。このパッケージを使う分では私が2日試した範囲では特にpandocに起因した問題は起きていません。
逆に1.Xでは動作しませんでしたので、pandoc 2.1をインストールしてください。
なお、Markdown Preview Enhanced ではpandocのpathを個別に指定することも可能です（ATOMのパッケージ->設定から、真ん中付近のPandoc Options: Pathで指定。日本語化していない時はPackage -> Settings、 かな？）
必要となる環境が色々ある。
さて、最終的にwordに出力するだけであれば上記環境だけで事足りるはずですが図はまた別に色々と環境整備が必要です。
下記それぞれPathを通しておく必要がありますね。
Graphviz
pumlの図を入れる場合には追加で下記が必要です。
特に考えずに最新のものを使用しましょう。
Graphviz - Graph Visualization Software
ImageMagick
こちらも図をexportするために必要。こちらも黙って最新版を使いましょう。
www.imagemagick.org
pdf2svg
CircuiTikZなどのLaTeXの記述をPreview機能使って表示させるために必要。
こちらの記事を参考にさせていただきました。
LaTeX環境
また、CircuiTikZの使用にはTeX/LaTeX環境が必要となります。PandocではMiTexの方をおススメって書いてあった気がするんですが、W32TeXで良いはずですが、2つのPCに入れて片方動かないという状態で、ちょっとまだ良く分かってませんが…。
ちょっとTeXまわりは個人的に闇しか感じないので、TeXまわりはまた別に記事にします。
なお、MikTex 2.9+ win10はパッケージの追加がうまくできなくなるというバグらしい挙動があるようです（同じような報告が結構出ている…）
…ということもあり、後回しです。
参考
Markdown Preview Enhanced の導入にあたって下記の記事を参考にしました。ありがとうございました。 正直、今日書いたここまでの情報は目新しいことは何もないので下記の記事の方がわかりやすくて良いかと思います。
しかし日本語で情報がまとまっているのはありがたいですね。
ただ、最新の情報をチェックする必要があるので、最終的には公式の情報を見に行く必要はあるのですが。
まだまだ続きがある
前置きを書くだけで時間を使ってしまって、昨日今日で進めた事・ぶつかった問題について全然触れられませんでした。
とりあえずこれで環境が整ったという前提で、次回はmarkdownからpandocを使用してdocxを生成する際に詰まったことを簡単にまとめます。
既知の情報しか書いてないな…
Enjoy!!
追記
この記事をメンテしたい気持ちはあるものの、はてなブログは記事メンテするにはちょっと向いていないですね…。
一応、このあたりも含めてR MarkdownからWord文書を作るという内容で技術書典向けに書いたのですが、中身は実質Pandoc本ではあるので参考になるかもしれません。ということで宣伝も兼ねてリンクを貼っておきます。
