In Gedevan-Aleksizde/rmdja: R Markdown Formats for Japanese

長大な技術文書や良質な技術文書を作成するには手間がかかる. しかし時間をかければ良い文書になるわけではない. 無駄な手間を省き, 効率よく快適に文書を作成するべきである.

たとえばこういう経験はないだろうか.

• プログラムの解説のため, 外部サービスでシンタックスハイライトしてもらったテキストをコピーペーストで貼り付ける
• グラフや図解を専用アプリケーションで作成し貼り付ける. 修正のたびに貼り付け直す
• 図表に言及する際に「図 1」「表 2」と番号をタイプし, 参照先へハイパーリンクを指定する
• 本文中で引用した参考文献のリストを巻末にコピーペーストし, 過不足がないか目視で確認
• $\sum_{k=1}^K\int_0^\infty f_k(x) dx$ などといった複雑な数式はプレーンテキストや HTML では表現できないため, 画像を生成して貼り付ける
• 冒頭にかっこいいエピグラフを掲載したいので, 1時間かけて特別に枠やフォントを作成した
• 市販のワードプロセッサで作成した文書を渡したら, レイアウトが崩れて読めないと言われた

本稿は文書作成者をこのような数え切れないブルシットから解放するのが目的である.

R Markdown (rmarkdown) は, R プログラムを埋め込んだ動的なドキュメントから pandoc を利用して PDF や HTML 形式の文書を作成するパッケージであり, 数式, 図表の挿入, シンタックスハイライトされたプログラムなどを簡単な記述で掲載できる. 名前の通り, その基本構文は Markdown である. よって, Markdown と R の知識が最低限あれば (R プログラムが必要ないなら Markdown だけでも) 文書を作成することができる.

bookdown パッケージは rmarkdown をもとに, ページ数の多い文書を作成し, 配布するための機能を拡張したものである. しかし, PDF の出力に関しては欧文を前提としたフォーマットを使用しているため, 日本語の適切な表示 (組版やフォントの埋め込みなど) のできる文書を作成するには高いハードルが存在した.

本稿では, rmarkdown および bookdown で日本語文書を作成する際の設定を容易にしたパッケージ rmdja を利用した日本語技術文書の作成方法を解説する. 現在, 書籍, 論文, プレゼンテーションの体裁での文書を作成するテンプレートが用意されており, このドキュメント自体も rmdja を利用して作成されている.

本稿の目的 {-}

R Markdown の現状と問題意識 {-}

R Markdown を利用した文書作成方法について, すでにそれなりの数と質の日本語資料が存在する. R Markdown でHTMLファイルのみを作成する場合, 日本語であるか欧文であるかはあまり気にする必要はない. HTMLであれば既存の資料でも十分に役に立つ.

• kazutan 『R Markdown再入門』
• kazutan 『R Markdownによるスライド生成』

しかし, PDF を出力する, あるいは HTML と PDF を同時に出力したい, となると, 組版に関して細かな設定が必要になるため難易度は一気に上昇する.

実のところPDFでも日本語を表示する最低限の設定は, YAML フロントマターだけで行える. 例えば Atusy氏が『R Markdown + XeLaTeX で日本語含め好きなフォントを使って PDF を出力する』で紹介しているが, よりシンプルな書き方もできる.

output: pdf_document:
    latex_engine: xelatex
documentclass: bxjsarticle
classoption:
  - xelatex
  - ja=standard
  - jafont=noto

このままでも, とりあえず文字化けすることなく日本語を表示できる. しかし実際に作ってみると, スタイルを調整したり, 画像を埋め込んだりといった細かいカスタマイズが必要になる. すると上記の設定だけではいろいろな障害が立ちはだかり, 文書として整ったものにするのは難しい. このままでは参考文献リストの表示も不自然なままである. だがこれ以上のカスタマイズは Atusy 氏がやっているようにテンプレートを修正することでしか対処できないものもあり, r rmdja::texlogo("LaTeX") に対するそれなりの知識が必要となる.

さらに, 同じソースファイルから HTML と PDF を同時に生成すると, また別種の問題が発生する. HTML と PDF は根本的に規格が違うため, 様々な場合分け処理が必要であり, それは pandoc だけでは対応しきれない.

HTML出力に限らない R Markdown の全般的な情報は, 既に充実した英語の (公式) ドキュメントが多く存在する[^major-docs].

• "Dynamic Documents for R・rmarkdown"
• "bookdown demo"
• "bookdown: Authoring Books and Technical Documents with R Markdown"
• "R Markdown Definiteive Guide"
• "R Markdown Cookbook"[^rmd-cookbook-publish]

[^major-docs]: 基本的なことがらの多くは上記を読めば分かるのでここでは基本機能をダイジェストで伝えた上で, これらの資料に書いてない応用技を紹介する. YAML のオプションの意味についてはソースコードにコメントを書いた. 以下, 単に, BKD と書けば "bookdown: Authoring Books and Technical Documents with R Markdown" [@R-bookdown] を, RDG と書けば "R Markdown: The Definitive GUide" [@rmarkdown2018] を, RCB と書けば "R Markdown Cookbook" [@xie2020Markdown] を指すことにする.

しかしながらこれらを元に1からいろいろな調整を施すのはとても骨が折れるため, rmdja パッケージは日本語文書でHTMLやPDFを同時に生成する場合の定番の処理をフォーマットに内蔵することにした.

rmdja の利点 {-}

従来LaTeXやWord, あるいは他の媒体で文書を作成していたユーザにとっても, 文書の内容から面倒な設定を分離するため, 効率的に執筆できる.

Wordユーザにとっては, 以下のような利点がある[^word-out-of-date].

• 数十, 数百ページの文書を書いてもクラッシュすることがあまりない
• 輪郭のはっきりしたベクタ画像を簡単に貼り付けられる
• 図表の配置や相互参照を手動で書く必要がない
• 読み手の環境に依存してレイアウトが崩れにくいPDFファイルを出力できる

ただし, .docx ファイルの出力はできない. 私が Word を持っておらず, R Markdown や pandoc がサポートしていても動作確認のしようがないため.

jupyter は Python のコードチャンクとその結果を簡単に表示できる文書作成ツールである. 出力オプションの少なさ (たとえば長大なコードもそのまま掲載されてしまう) や, IDE として見ても機能が少ないことからあまり使い勝手がよくなかったが, rmdja では Python スクリプトの埋め込みにもある程度対応している.

r rmdja::texlogo("LaTeX") のユーザー (シンプルなテキストエディタで書いているユーザも, Overleaf や LyX といった強力なエディタを使用しているユーザー) にとっては, r rmdja::texlogo("LaTeX") とほぼ同じ構文で数式を入力でき, かつ操作を大きく簡略化でき, 実験結果などをソースに埋め込むことができ, 外部プログラムからいちいちコピペする必要がなくなる. ただし, なるべく選択肢は広げておきたいが, なんでもありではかえって余計なことをしがちである. よって既に作成した beamer フォーマットと同様に, r rmdja::texlogo("XeLaTeX") および r rmdja::texlogo("LuaLaTeX") のみの対応を想定している. r rmdja::texlogo("pLaTeX") や r rmdja::texlogo("upLaTeX") には対応していない.

これまでも R Markdown を使用してきたユーザにとっては, YAML フロントマターに数十行に渡っていた書いていた日本語表示のための設定の多くがフォーマットのデフォルト値になったため, かなり楽になると思われる.

たとえば,

bookdown::pdf_book:
  toc_depth: 3
  toc_appendix: true
  toc_bib: true
  latex_engine: xelatex
  keep_tex: true
  keep_md: true
  citation_package: natbib
  pandoc_args:
    - '--top-level-division=chapter'
    - '--extract-media'
    - '.'
  template: XXXXX.tex.template'
  dev: "cairo_pdf"
  out_width: "100%"
  out_height: "100%"
  quote_footer: ["\\VA{", "}{}"]
  extra_dependencies: gentombow

のように書いていたものがこうなる.

rmdja::pdf_book_ja:
  keep_tex: true
  keep_md: true
  tombow: true

さらにチャンクオプションを書いたり場合によっては .tex ファイルのテンプレートすら調整する必要もあった. それらも rmdja 内で調整している.

さらに, 作成した文書は PDF 形式で出力することはもちろん, HTML 形式で様々なサイトで掲載でき[^blogdown]たり, 電子書籍ファイルとしても出力可能である. このような多様な出力形式への対応しているソフトウェアはあまり例を見ない.

``{block review-info, type="warning"} ただし, 現時点では出版に堪えうる組版規格を満たす文書を生成するのは大変である. 紙媒体の書籍を作りたい, かつ R や\LaTeX{=latex}Latex`{=html} を未習得であり, これらを習得することに興味がない場合は Re:View の使用を検討してほしい.

## R使用経験のないユーザへ {-}

Rを使わない, あるいはそもそもプログラミングに詳しくない, という人間にもある使用機会がある. たとえばR を普段使わない人間でも `bookdown` で同人技術書を執筆したという事例がある[^bookdown-example]. この事例は主に数式と画像の貼付けのみだから, 数式出力に必要な `r rmdja::texlogo("LaTeX")` の知識があればほとんどのことはできてしまう. そして `rmdja` ではこの事例で言及されている `r rmdja::texlogo("LaTeX")` の設定の多くは自動で制御される. また, 小説などはほぼテキストであり, 最低限のレイアウトさえ用意すれば数式も, あるいは画像の挿入すらいらないことが多い. `rmdja` では縦書き文書をPDFで出力する方法も用意している.

```{block experimental-features, type="important"}
印刷用フォーマットおよび縦書き文書フォーマットは現在実験的な導入段階であり, 表示の一部に不具合が存在する.

[^word-out-of-date]: ただし筆者は数年来 Word を使っていないため, これらのいくつかは既に改善されているかもしれない. [^blogdown]: bookdown 同様に R Markdown で作成した文書をブログ風のフォーマットで出力する blogdown パッケージというものも存在する. [^rmd-cookbook-publish]: 2020/10/19 に書籍としても発売されるらしい.

Gedevan-Aleksizde/rmdja documentation built on Sept. 28, 2021, 2:49 a.m.