Zenn
📖

md2review/Re:VIEW-pdfによる最小限の執筆環境構築

2023/10/10に公開
Zenn
連携
review
技術書典
md2review
tech

md2review/Re:VIEW-pdfによる執筆環境構築

本章は技術書典15（オンライン＋オフライン）に向けてゼロベースで実施した実話である。

クイックスタートガイド

本項ではreview-init mybookを実行した後の話を想定する。

  • config.yml
  • catalog.yml（後述）
  • mybook.re

その他の環境はinitで生成されたものをそのまま使用している。

発端

なぜ本を書くだけなのに環境構築で苦しまなければならないのか。
せっかくZennがあるんだからZennで本にすれば良くない？

という誘惑を断ち切るため、オンラインではなくオフラインで製本する事にした。

config.yml

以下だけ変更している。

  • booktitle: 本のタイトル
  • aut: 著者。連名で書く事があるので配列形式と理解
  • toclevel: 目次に掲載する見出しレベル
  • contentdir: CHAPSのファイルを置くディレクトリ

catalog.yml

# コメントは筆者注。

# 前書き
PREDEF:

# 本文
CHAPS:
  - mybook.re
  - mybook2.re
  ...

# 付録
APPENDIX:

# 後書き
POSTDEF:

エラーが起こった際に原因となりやすいのでChatGPTにエラーの対処を問い合わせたくなるが、書式が決まっているので公式を参照されたし。（バージョンの違いもある？ので、公式以外は参照してはならない）

なお、ファイルパスを変更したい場合は以下を確認する。

  • config.yml
    • contentdir: .

よくあるエラーとしてやりがちなものが、CHAPSに指定する内容は「ファイルパス」ではなく「ファイル名」である事に留意する。

mybook.re

contentdirで指定したディレクトリを作成し以下に配置。
本項のタイトルは「mybook.re」としているが、当然変更は可能。config.ymlのCHAPS欄をもう一度見てみよう。

CHAPS:
  - mybook.re
  - mybook2.re

CHAPSに必要なのは順番であって、ファイル名は任意である。

初回のみ実施

以下コマンド等はMacOSでの実施を想定しているが、Windows(WSLは非対象)でもできるはず。ただし本稿で取り扱わないRuby-gem関連のインストール周りが一番の障害になると考えられる。

rubyとgemのインストール

macbook(macOS Sonoma)を使用。

brew install ruby ruby-build gem

なお、brewは以下。

brew --version        
Homebrew 4.1.15
  • 実行環境（後述）
    • ruby --version: ruby 3.2.2
    • gem --version: 3.4.20

md2reviewインストール

gem install md2review  # -gにはしない
md2review --version
1.12.1

これでmd2reviewコマンドが使えるようになる。

Re:Viewをインストールする

  • 実行環境
    • brew install ruby ruby-build
    • gem install review
review version
5.8.0

（任意）VSCodeにRe:View環境を作る

  • そもそも、md2reviewを使う場合は使わない
  • ReViewのビューアーの見え方とPDF出力が一致しないため、結局PDFで確認する必要がある
    • とはいえ、記法ミスなどは確認できるのでmd2reviewの意味がないわけではない

これを踏まえて、環境を作っていく。

(atsushieno氏)Re:VIEWの別タブビューアーの拡張機能を入れる。

https://marketplace.visualstudio.com/items?itemName=atsushieno.language-review

名前: Re:VIEW
ID: atsushieno.language-review
説明: Re:VIEW language Support for Visual Studio Code.
バージョン: 0.7.4
パブリッシャー: atsushieno

執筆するたびに実施

概要だけ言えば「review-init」を実行した場所で以下コマンドを実行する。

md2review README.md > 01_environment.re
# mdをreに変換
review-pdfmaker config.yml   
# book.pdfを生成

作成されたbook.pdfを入稿すれば完了。

md2reviewを使う

md2review mdファイル > reファイル

pandoc2reviewはダメなのか？

公式ではmd2reviewではなくpandoc2reviewを推しているので、特に理由がなければ公式に準ずるべきである。ただし、VSCode拡張機能が対応できていないのでmd2reviewを採用した。

pandoc2reviewは手動改行（後述）に弱いので、改行を使うならまだまだ採用は難しいか。

md2reviewの変換で失敗する場所を対応する

  • マークダウンの改行は＜ｂｒ＞で行うが、Re:VIEWだと＠＜ｂｒ＞｛｝となる。（全角表記としているが正しくは半角）
    • VSCodeなどエディタで一括変換したり、コマンドを拡張して置き換える必要あり

Re:ViewファイルからPDFを作成する

review-pdfmaker config.yml

電子版PDFを作る場合はconfig.ymlのmedia=◯◯を変更する必要がある。

  • トンボ・ノンブル有:
    • texdocumentclass: ["review-jsbook", "media=print,paper=a5"]
  • 電子版:
    • texdocumentclass: ["review-jsbook", "media=ebook,paper=a5"]

検証、使ってみた感想

本項はまさに執筆しながら追記しているため、リアルタイム性が少しでも伝わるように項目に日付を入れる事にした。

[2023/09/11] 技術書典に応募。執筆環境の選定と環境構築

申し込み完了とともに着手。執筆環境の選定から真剣に環境構築にかけた時間はおそらく3日ほどで、Re:VIEWとStarterを比較に時間をかけていた。理由は後述するが、情報が多い分バージョンの違いを意識しなければならない点に苦労した。

[2023/10/10] Re:VIEW Starterを採用しなかった理由

※執筆時点ではRe:VIEW最新版が5.8、StarterがRe:VIEW2.5に対応している事に留意されたい。

よく似ているが、更に使いやすいRe:VIEW Starterがある。ただし、Re:VIEWの最新版に対応していないため、md2reviewを使う場合はこちらも意識する必要がある。

今回はマークダウンで記事を書き、書いた記事を製本するという目的があったためデザイン性(Starter)より利便性(md2review)を優先している。

https://kauplan.org/reviewstarter

[2023/10/10] Re:VIEWを使うにあたって調べた方法

本項は最も参考にならない情報になる可能性が高いため、最初に少し筆者について認識しておいてほしい。

まず、公式リファレンスの情報だけで書けるのはつよつよプログラマー・つよつよエンジニアだけだと割り切った。エンジニア能力としてはその程度のスキル感である。残念ながら当然というか、チュートリアルの内容だけで何をやっているか理解していない。

環境構築についてはほとんどChatGPT頼りで、執筆時は検索ワードに「Re : VIEW」を入れている。ここで重要なのは「ReVIEW」ではなく「Re:View」とコロンを入れている事だ。

https://review-knowledge-ja.readthedocs.io/ja/latest/index.html#

[2023/10/10] マークダウンの改行とRe:VIEWの改行表記が異なる問題への対応

上記の対応でもmd2reviewで変換できないので別の変換方法を使う提案をしているが、そもそも改行を入れなければならないような書き方を避けている。本章の公開先は以下の通り。

  • 無料公開（コンテンツの一部のみ）
    • Qiita,ZennなどWebメディア
  • 有料
    • 製本(技術書典)
    • PDF(技術書典ほか)

公開情報の運用については本項では触れないが、Webメディアで表示させるレイアウトと本誌に印刷するレイアウトは異なる。また、PDFの場合も考えると悩みは尽きない。今回は製本を第一に考えて書く事にしたため、結果は当日になるまで私にも分からない。

[2023/10/10] リンクの扱い

普段Web媒体でしか書いていないのであまり気にならなかったが、書籍だとリンク表記をされてもリンク先が不明のため、参考記事を置いても困るケースが多い。

そこで、本書では各項目の最後にURLを置く事にしている。これはQiitaやZennに投稿すると自動的にカード化してくれるので全くの無駄にはならない事を利用している。

[2023/10/10] ZennとRe:VIEWを連動させる

以下手順に則る必要がある。

  1. 【簡単】FrontMatter（Zenn等のヘッダ情報）を削除
  2. 【簡単】改行タグを差し替え
  3. 【要確認】画像のパスを修正（特にRe:VIEWは外部画像を参照できない）
  4. 【高難度】catalog.ymlに追記する

どうせZennに公開するために「git push」は必須。上記作業をCIで実現する事で解決は可能と考える。ただし画像に外部ファイルなどは使えないため、後述に従う必要がある。

画像パスの課題

画像パスは結論「![キャプションはRe:VIEWで必須](/images/ファイル名)」のルールで書く必要がある。

  • Zennから見ると、「/images以下に置く」というルールがある。
    • 外部ファイルを参照することもできる。
  • Re:VIEWから見ると「画像のファイルパスはconfig.ymlのimagedir(初期値はimages)で指定した場所を参照する」というルールがある。
    • 指定はファイル名のみであるため、別パスや外部ファイルを参照できない

この２つのルールを満たす必要があるため、結論の通りになる。

https://zenn.dev/zenn/articles/deploy-github-images

catalog.ymlに追記

結論から言うと 「辞めた方がいい」事が多い ように思う。スクリプトで自動制御を検討した上で運用コストも考えると、手作業で書き換えた方が圧倒的に早く安全である。

自動化を考える場合は、何行目に追加するとか、ファイル名が変わった場合は更新が必要だとか制御を考える必要がありそうだ。

[2023/1M/DD] 以下、追記予定

Discussion