niszetの日記

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

(メモ) ドキュメント楽に作りたいのでMarkdown Preview Enhancedを使い始めた

Atom + Markdown Preview Enhanced で対応できることは対応する。

今までAtomMarkdownを書くときはMarkdown Preview Plusを使っていたのですが、Markdown Preview Enhancedというパッケージがあったのですね。

shd101wyy.github.io

VSCodeの方も試してみましたが、Atomの方が完成度が良い気がします。まぁ、どちらか普段使っている方を使えばよいのかなとは思いますが…。

正直このパッケージだけでやりたいことは大体できる。

もともと、個人的にはMarkdownは使っていたものの(使っているのは主にRmdな気もしますが…)、図表関係に難があって今まで使いきれていませんでした。
図は埋め込めば良いといえば良いのですが、その図をどうやって作るのか?というところで一旦エディタから離れたところで作業するというのが億劫で…

また、Markdown書式でモノを書くことを社内的に布教しようと2年ほど前からしていたのですが、未だ上手くはいっておらず。その原因はやはりエディタがないとテキストファイルだけ見ても名に書いてあるのか良く分からんし記法覚えるのは大変だし、そもそもgit使ってない時点でテキストで書くモチベーションあまりないし、社内文書はwordだし…etcetcみたいなところにあると思っています(IT系ならまぁ難なく、なのでしょうが、それ以外の環境で、プログラム経験全く内容な人を対象に布教するというのはなかなか大変なのです)

しかし、pandocを利用してwordで出力することが出来れば使う人も増えるのではないか、という期待をしています。
まぁ、仮にもし使われなくても自分はword直接触らなくてもコレを使えば良いので損はないし、ということで、ここ2日ほどこれと格闘していました。

実際、客(提案先)としては、中身がどうかは2の次で「使い勝手」や「価値あるか?」…で判断するということですね、何事も提案するときは考えなくてはね…

出来ることについては公式のページに書かれていますが、個人的には中でも以下の点に注目しています。

  • PlantUML の埋め込みが出来ること(フローチャートが描ける)
  • TeXを埋め込めること(CircuiTikZで回路図を入れることが出来る)
  • WaveDromを使えること

他にもコードチャンク埋め込んだり、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をインストールしてください。

github.com

なお、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機能使って表示させるために必要。

こちらの記事を参考にさせていただきました。

scientre.hateblo.jp

LaTeX環境

また、CircuiTikZの使用にはTeX/LaTeX環境が必要となります。PandocではMiTexの方をおススメって書いてあった気がするんですが、W32TeXで良いはずですが、2つのPCに入れて片方動かないという状態で、ちょっとまだ良く分かってませんが…。

Home - MiKTeXorg

ちょっとTeXまわりは個人的に闇しか感じないので、TeXまわりはまた別に記事にします。
なお、MikTex 2.9+ win10はパッケージの追加がうまくできなくなるというバグらしい挙動があるようです(同じような報告が結構出ている…)
…ということもあり、後回しです。

参考

Markdown Preview Enhanced の導入にあたって下記の記事を参考にしました。ありがとうございました。 正直、今日書いたここまでの情報は目新しいことは何もないので下記の記事の方がわかりやすくて良いかと思います。

しかし日本語で情報がまとまっているのはありがたいですね。

qiita.com

qiita.com

qiita.com

ただ、最新の情報をチェックする必要があるので、最終的には公式の情報を見に行く必要はあるのですが。

まだまだ続きがある

前置きを書くだけで時間を使ってしまって、昨日今日で進めた事・ぶつかった問題について全然触れられませんでした。
とりあえずこれで環境が整ったという前提で、次回はmarkdownからpandocを使用してdocxを生成する際に詰まったことを簡単にまとめます。

既知の情報しか書いてないな…

Enjoy!!