2021-06-19

ライティング環境を見直す2021春夏

※ 2023年に思い出しながら書いてます。

Google Driveベースの作業が多くなってきたので環境を見直したい

問題意識:OmniGraffle起点だけだと弱い

  • 2019年に重い腰をあげて PlantUML を使い始めたが、概念図を描くにはやはり OmniGraffle であーでもないこーでもないするのが便利
  • 一方で OmniGraffle スタートだと画像とドキュメントを取り出してドキュメント化するのが手間で、ついそのまま PDF にしちゃいがち
  • ただ見せるだけならそれでもいいけど、再利用性は間違いなく落ちるし、OmniGraffle が必要なほど複雑でない図で伝えたいだけの場合も増えてきた

手法:まずVS CodeのMarkdown拡張を知る

文書を起点にするならそういう記法を使うのもアリか。もう少しこれまでよりも自然言語ライティング自体を加速させるような取り組みをしたい。1

Markdown Preview Enhanced - Visual Studio Marketplace

  • Google Drive だけでなく日記の更新や薄い本みたいなある程度の分量のドキュメントを書きやすくはしておきたい
  • Markdown Preview Enhancement という拡張を知る
    • PlantUML も拡張でレンダーできる
    • esa などでも Markdown の中に埋め込めるのは知っていたけど、esa 限定だと面白くないと思っていた
  • Markdown はそんなに記述力ない(割と簡単に HTML 生書きに陥る)のがネックけど、内容によっては割と耐えられるかも?

課題:Google Drive へどうやって持っていくか

書くだけなら Google Drive よりまともなエディタで書ける方がありがたい。一方で Google Docs は Markdown エディタではないので、Markdown で書いたものをどうにかして Google Docs の形式に変換しないとそのままでは普通の人には見慣れない記号にまみれた無愛想なドキュメントになってしまう。

ネック

  • 画像。PlantUML で描いたとしてそれをラスタ画像として取り出せないと Google Docs へ添付できない
  • Google Docs は Markdown 記法に直接対応はしていないのでなんらかの変換が必要

変換方法

とりあえず見つけた方法。

※ ご存知の通り無駄が多いです。

  1. Asciidoc ← Markdown ( kramdoc / kramdown の機能 )
  2. DocBook ← Asciidoc ( asciidoctor の機能 )
  3. bocx ←DocBook ( Pandoc の機能 )
  4. Google Docs ← docx ( Google Drive の機能 )

PlantUML を書いて PlantUML をそのまま変換して画像を出力できる方法は知っていたが、一連の流れの中で書けると嬉しいと思い、試行錯誤してみる。この過程で気づきがいろいろある。

Markdown Preview Enhancement の中で Pandoc を呼べるが、Markdown + PlantUML → Pandoc → docx を直接実行すると PlantUML 画像内の日本語が化けるなど、拡張内の各ツールの設定が練れていない。

一方で Asciidoctor は面白い。

Asciidoctorよいかも

Asciidoc も名前だけは以前から知っていたが、特段 Asciidoc を使うメリットは感じていなかった。表現力は Markdown より上なんだろうけど、やはり Markdown は利用できるシーンが非常に多いため、あえて普段使いに Asciidoc を使う理由を見つけるのは難しい。

そんななか、上の docx 生成で Pandoc に繋ぐ際に asciidoc を経由する方法もあるなと思い、手を出してみたら思いのほか手応えを感じる。

AsciiDoc - Visual Studio Marketplace

  • 拡張が Asciidoctor2 本家からリリースされていて安心
  • Markdown ではサポートされていない画像埋め込みの機能が記法自体にある
  • asciidoctor + asciidoctor-diagram で変換するとそのまま画像を取り出すことができる
  • Pandoc で直接処理するよりも Asciidoctor 経由で処理した方が docx 変換もスムーズ
  • asciidoctor 自体で ePub や PDF 生成の機能を持っており、最初から AsciiDoc で書いておけば HTML 以外に出力にも向いている

docx 変換については以下の sh スクリプトを用意した。

asciidoctorとasciidoctor-diagramとpandocを使ってasciidocからdocxを作る

OOXML の template を作るのはある程度コツが要る割に期待した仕上がりまで持っていくのはかなり大変なので、ある程度までになってます…。

今のところ微妙?

Markdown で書き始めるのはよいが、その後ラスタ画像を作るのはやはり億劫。それでも画像作成の機会と Markdown スタートでの環境の書きやすさのどちらがマシかというとやはり後者の方に軍配が上がる。

面倒は面倒。特に PNG 出力が思ったより解像度が悪いので、いったん SVG にしてから PNG に変換する部分でかなりの手間を要する。

もう一つ、docx ( OOXML ) 変換向けのテンプレートを頑張って作ったが、これなら Google Docs のデフォルトスタイルに合わせつつ margin とか文字サイズの設定だけすればだいたい満足なのでは?という感じがしている。

すると asciidoctor + asciidoctor-diagram は画像の取り出しのためだけに使う、みたいな感じになっていて手間の割に嬉しみが少ない。

図のない Google Docs を Markdown から一手間(行頭の記号の入力に応じて変換が走るので)掛けて作る、みたいな運用がほとんどになっている。

  1. これまではコード、仕様、設計が主で日本語ドキュメントはスライドが中心と思いねぇ 

  2. Asciidoctor は Asciidoc 処理系の一つで恐らく最もアクティブに開発されている。 

About

例によって個人のなんちゃらです