diff --git a/Gemfile.lock b/Gemfile.lock index 59c5a94..f1fa400 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,21 +1,43 @@ GEM remote: https://rubygems.org/ specs: - review (2.3.0) + concurrent-ruby (1.2.2) + image_size (3.3.0) + mime-types (3.4.1) + mime-types-data (~> 3.2015) + mime-types-data (3.2023.0218.1) + pandoc2review (1.4.0) + unicode-eaw + pastel (0.8.0) + tty-color (~> 0.5) + playwright-ruby-client (1.35.0) + concurrent-ruby (>= 1.1.6) + mime-types (>= 3.0) + playwright-runner (1.2.0) + playwright-ruby-client (~> 1.0) + rake (13.0.6) + review (5.8.0) + image_size + rexml rouge rubyzip - review-peg (0.2.2) - rouge (2.2.0) - rubyzip (1.2.1) - sass (3.4.25) + tty-logger + rexml (3.2.5) + rouge (4.1.2) + rubyzip (2.3.2) + tty-color (0.6.0) + tty-logger (0.6.0) + pastel (~> 0.8) + unicode-eaw (2.2.0) PLATFORMS ruby DEPENDENCIES - review (= 2.3.0) - review-peg (= 0.2.2) - sass (= 3.4.25) + pandoc2review + playwright-runner + rake + review (= 5.8.0) BUNDLED WITH 1.15.3 diff --git a/articles/catalog.yml b/articles/catalog.yml index 3a9b4f4..af87ca9 100644 --- a/articles/catalog.yml +++ b/articles/catalog.yml @@ -1,5 +1,6 @@ PREDEF: - preface.re + CHAPS: - writing-book.re - planning-book.re @@ -10,6 +11,7 @@ CHAPS: - review-introduction.re - configure.re - build.re + APPENDIX: - tips.re diff --git a/articles/images/setup/install-language-review.png b/articles/images/setup/install-language-review.png deleted file mode 100644 index e987a88..0000000 Binary files a/articles/images/setup/install-language-review.png and /dev/null differ diff --git a/articles/images/setup/language-review-grammar1.png b/articles/images/setup/language-review-grammar1.png deleted file mode 100644 index 47a59a2..0000000 Binary files a/articles/images/setup/language-review-grammar1.png and /dev/null differ diff --git a/articles/images/setup/language-review-grammar2.png b/articles/images/setup/language-review-grammar2.png deleted file mode 100644 index 1845ad3..0000000 Binary files a/articles/images/setup/language-review-grammar2.png and /dev/null differ diff --git a/articles/images/setup/language-review-sample.png b/articles/images/setup/language-review-sample.png deleted file mode 100644 index 8d13ccf..0000000 Binary files a/articles/images/setup/language-review-sample.png and /dev/null differ diff --git a/articles/images/setup/vscode-language-review-sample1.png b/articles/images/setup/vscode-language-review-sample1.png new file mode 100644 index 0000000..6e0f84e Binary files /dev/null and b/articles/images/setup/vscode-language-review-sample1.png differ diff --git a/articles/images/setup/vscode-language-review-sample2.png b/articles/images/setup/vscode-language-review-sample2.png new file mode 100644 index 0000000..2b3b703 Binary files /dev/null and b/articles/images/setup/vscode-language-review-sample2.png differ diff --git a/articles/images/setup/vscode_extensions.png b/articles/images/setup/vscode_extensions.png new file mode 100644 index 0000000..ee21fc0 Binary files /dev/null and b/articles/images/setup/vscode_extensions.png differ diff --git a/articles/setup.re b/articles/setup.re index a21f29f..7c12012 100644 --- a/articles/setup.re +++ b/articles/setup.re @@ -1,211 +1,186 @@ ={setup} Re:VIEWでの執筆環境を整える -#@# NOTE author:vvakame +#@# NOTE author:mhidaka -まずはRe:VIEWで執筆するための環境を整えましょう。 +本章ではRe:VIEWで執筆するための環境を整えましょう。 -TechBoosterでは、GitHubが提供するエディタであるAtom@{atom}と追加パッケージであるlanguage-review@{language-review}を使って執筆しています。 -そしてGitHubなどにpushする前に、Ruby版のRe:VIEW@{review}を使ってHTMLやPDFの生成チェックを行う運用になっています。 +TechBoosterの著者陣は、もれなく全員がRe:VIEW記法で執筆するスタイルです。 +慣れないうちはエラーに遭遇したり、やり方に迷ったりしているので、CI/CD環境があってこそ運用できているといえます。 +Re:VIEW記法は、馴染みがないものなので覚えるのはちょっと面倒ですね。書籍作りを支えるものなので表現したい内容を優先し、手を動かしながら学びノウハウを貯めてください。 -生成チェックは、language-reviewがreview.js@{review.js}というJavaScriptによるRe:VIEWの移植版を使っているために必要な作業です。 -review.jsは現在のところ、PDFを生成することなどができませんし、文章の解釈もRuby版と厳密には一致しません。 +2023年11月現在では、Microsoftが開発提供するエディタVisual Studio Codeと@{Extensions,拡張機能}のvscode-language-reviewを利用することが一般的です。 -本書執筆時点での各ツールのバージョンは次のとおりです。 + * @{https://code.visualstudio.com/} + * @{https://github.com/atsushieno/vscode-language-review} -#@# TODO 入稿前にここのバージョンを再確認すること +いきなりRe:VIEWで書き始めるのはハードルが高いなと感じた場合はMarkdownで書いたあとにRe:VIEWファイルに変換する手法をおすすめします。 +しかしMarkdownで執筆する場合は、図表の細やかな調整やリストへの参照など本らしい表現に対応するMarkdown記法がありません。 +慣れるにしたがってRe:VIEWファイル上で、最終調整することも多くなるのでRe:VIEWファイルでの執筆・編集を前提にセットアップ手順を知っておきましょう。 - * Atom v1.18.0 - * language-review 0.15.3 - * Re:VIEW 2.3.0 +本書執筆時点での検証済みのバージョンは次のとおりです。 -//footnote[atom][@{https://atom.io/}] -//footnote[language-review][@{https://atom.io/packages/language-review}] -//footnote[review][@{https://github.com/kmuto/review}] -//footnote[review.js][@{https://github.com/vvakame/review.js}] +#@# TODO 入稿前にここのバージョンを再確認すること -== Atomとlanguage-reviewのセットアップ + * Visual Studio Code October 2023 (version 1.84) + * vscode-language-review v0.7.4 + * Re:VIEW 5.8.0 -#@# NOTE author:vvakame +== Visual Studio CodeとExtensionsのセットアップ -Atomエディタをインストールします。完了後、Atomを立ち上げ、設定からlanguage-reviewをインストールします（@{install-language-review}）。 +Visual Studio Codeをダウンロードしてインストールします。Visual Studio Codeを起動し、Extensionsを表示します。 +メニューから@{基本設定 > Extensions}または@{表示 > Extensions}どちらからで表示できます。 -#@# Mac OS XであればAtomを起動した後、メニューのAtom > Install Shell Commandsを選ぶと@{/usr/local/bin/}に@{apm}コマンドがインストールされるので、ターミナルから@{apm install language-review}を実行でもOKです。 -#@# vv: https://github.com/atom/atom/issues/7570 この辺のIssueにワイの新MBP引っかかってるんだけど他の人の環境だとどうなのかわからない… +サイドバーの上部にマーケットの検索ウインドウがあるので検索ワード「Language Review」と入力してvscode-language-reviewを探してください（@{vscode_extensions}）。 -//image[install-language-review][language-reviewをインストールする]{ +//image[vscode_extensions][vscode-language-reviewをインストールする]{ //} -次に適当な名前の@{.re}ファイル（例: test.re）を作ります。 +画面のインストールボタンを押せば完了です。 +vscode-language-reviewは、Visual Studio Code上で、Re:VIEW記法を使いやすくする便利な拡張機能を持っています。 -作成後、このファイルをAtomで開きます。 -デフォルトの編集モードはRe:VIEW以外になっているため、クリックして@{atom-tips}Re:VIEWに切り替えます（@{language-review-grammar1}、@{language-review-grammar2}@{atom-images-disclaimer}）。 -#@# vv TODO この辺新規の環境でどうなるか再確認したさがある…（新PCでこの操作必要だった記憶がないけど無意識にやってるかもしれないしわからん） + * Liveプレビュー + * シンタックスハイライト + * アウトライン表示とコードジャンプ + * Re:VIEW記法のチェックと警告、参照先入力支援 + * 文章の校正支援 -//image[language-review-grammar1][モード切り替え前]{ -//} -//image[language-review-grammar2][このように切り替えるのだ]{ +@{vscode-language-review-sample1}はRe:VIEW記法でかかれた@{.re}ファイルを +開いたものです。見出しや箇条書き、ハイパーリンクなどRe:VIEW記法部分をシンタックスハイライト機能でわかりやすく表示します。 + +//image[vscode-language-review-sample1][シンタックスハイライト機能]{ //} -パッケージのインストール時に、依存する別パッケージ（linter）のインストールも行っています。 -動作がおかしい気がする場合、Atomを完全に終了させてから起動しなおしてみてください。 +Visual Studio Codeの画面右上部の@{Show preview}ボタンがあります。 +Show preview（@{vscode-language-review-sample2}）はRe:VIEWでのシンタックスがどのように働いているかをプレビューできます。 -#@# また、人柱用ですがMac OS X環境ではAtomのインストールからlanguage-reviewの導入までを行うインストールスクリプトを用意してあります。 +//image[vscode-language-review-sample2][便利なプレビュー機能]{ +//} -#@# //cmd{ -#@# curl -L https://github.com/vvakame/language-review/raw/master/install.sh | bash -#@# //} +正確にはHTMLでのプレビューですので実際の紙面とはレイアウトが違います@{scale-note}。 +Re:VIEW記法のミスがないかの確認用と考えてください。 -language-reviewは、Atomを通じてさまざまな便利な機能を提供します。 -よく使うのは次のとおりです。 +//footnote[scale-note][差分は文章の折り返し位置がわかりやすいです。そのほかの例としてはRe:VIEWにはimageという画像表示のためのブロック命令がありますが、オプションパラメータ@{scale}のサイズ指定は最終出力のフォーマットや判型で見栄が異なります] - * シンタックスハイライト - * 文法ミスの警告 - * 文章の校正支援 - * HTMLプレビュー - * Re:VIEWの記法一覧 - * アウトライン表示とジャンプ +TechBoosterではVisul Studio Codeとvscode-language-review拡張機能で執筆し、 +LiveプレビューでエラーチェックしてGitHubのリポジトリにpush、CIでPDFを確認するというワークフローを運用しています。 -@{language-review-sample}がサンプルです。 +=={install_review} Re:VIEW image for Dockerのセットアップ -//image[language-review-sample][language-reviewの画面サンプル]{ -//} +Docker上でRe:VIEWを動かすための手順を解説します。Dockerはコンテナ型仮想化技術のプラットフォームです。 +Re:VIEW image for Dockerは最新のRe:VIEWをどの環境でも安定して使えるコンテナイメージで、vvakameが公開、メンテナンスしています。 -//footnote[atom-tips][Mac OS Xの場合、Command+Shift+Pでコマンドパレットが開くのでgrammarなどそれっぽいワードを投げ込むとマウスなしで操作できます] -//footnote[atom-images-disclaimer][プラグインの導入状態やAtomのバージョンによって、画像どおりの見た目じゃない場合のほうが多いはずです] +本書執筆時点での検証済みのバージョンは次のとおりです。 -=={install_review} Re:VIEWをインストールする +#@# TODO 入稿前にここのバージョンを再確認すること -#@# NOTE author:vvakame + * macOS Sonoma + * Docker Desktop Version 4.25.0 (126437) -次に、Ruby版Re:VIEWをインストールします。 -これはPDFやEPUBの生成などの最終出力を行うのに必要です。 +Re:VIEWツールそのものはRuby言語で書かれており、macOS、Windows、LinuxどのOSでも動作します。 +ただしRubyのバージョンやPDFを出力するLaTeXを構築する手順がプラットフォームごとに微妙に異なるので、 +Re:VIEWの環境構築でトラブルに遭遇した場合の解決は困難を極めました。 -RubyとRubyGemsは、すでに利用可能な環境になっているものとして解説します。 -インストールは単に次のコマンド@{experimental-review}を実行するだけです（Rubyのインストール方法次第ではsudoが必要となる場合もあります）。 +Re:VIEWの環境を仮想化できたことで現在は多くの書籍がRe:VIEW image for Dockerを使って作られています。 -//cmd{ -$ gem install review -//} +Docker Desktopを次のURLからダウンロードしてインストールします。 -これだけです。 -詳しい使い方は@{review-introduction}で解説します。 + * @{https://www.docker.com/} -とりあえず試してみたい場合、次のコマンドを実行してください。 +Windowsの場合の手順は次のURLで詳しく触れられています。 -//cmd{ -$ review-init sample -$ cd sample + * @{https://github.com/vvakame/docker-review/blob/master/doc/windows-review.md} -# もしrakeコマンドがまだ入っていなかったら（sudoが必要な場合もある） -$ gem install rake +2023年11月現在、Docker Desktopのライセンスは有償と無償どちらも存在しています。無償のパーソナルプランから試してみてください。パーソナルプランでは個人開発者の利用、教育目的、非商用のオープンソースプロジェクトでの利用を想定しており、これらに加えてFAQには小規模なビジネス向け（従業員 250名未満、かつ収益 1 千万ドル未満）に対しても無償提供を継続すると記載@{docker-faq}があります。 -# 各種ビルド HTML & PDF & EPUB -$ rake html_all -$ rake clean pdf -$ rake clean epub -//} +//footnote[docker-faq][@{https://matsuand.github.io/docs.docker.jp.onthefly/desktop/faqs/#do-i-need-to-pay-to-use-docker-desktop}] -このコマンドではHTML、PDF、EPUB形式でサンプルをそれぞれ出力しています。 +Dockerのインストールが完了したあとはRe:VIEW image for Dockerをダウンロードします。 -//footnote[experimental-review][review-pegという実験的パッケージがありますが熱心なRe:VIEW信者でない限り通常のreviewを使えばよいでしょう] +//cmd{ +docker pull vvakame/review:5.8 +//} -===[column] Ruby導入の手引き Mac OS X、Linux編 +コマンドは@{5.8}を指定しています。Re:VIEW image for DockerでサポートしているRe:VIEWは5.3〜5.8です。 -Macの場合、何もしなくてもデフォルトでRubyが導入されています。 -この状態だとgem installを実行するときにsudoが必要になります。 -またデフォルトのRubyのバージョンは若干古いため、最新のものを入れたほうがよいでしょう。 + * @{https://github.com/vvakame/docker-review} -システムのデフォルトのままだと、破壊的（かもしれない）操作をするのが怖いですし、イザというときにリセットすることもやりにくいです。 +===[column] 取得済みイメージの確認方法 -万一のときに@{rm -rf ~/.rbenv}すればよい環境を作っておくと、精神的安らぎが得られます。 +次のコマンドでpullしているDockerイメージを確認できます。 -そのため本書ではrbenvの利用を推奨しています。 -rbenvのインストール自体は公式サイト@{rbenv}に譲ります。 +//cmd{ +docker images vvakame/review +//} -rbenvインストール後の手順は次のとおりです。 +本書の手順を実行したあとでは@{vvakame/review}リポジトリのタグ@{5.8}を確認できます。 //cmd{ -$ rbenv install --list -# 最新のを適当に入れれば良い 執筆時点では 2.4.1 -$ rbenv install 2.4.1 -# グローバルなrubyコマンドのバージョンを設定する localも存在する -$ rbenv global 2.4.1 -# reviewをインストール -$ gem install review +REPOSITORY TAG IMAGE ID CREATED SIZE +vvakame/review 5.8 5cb030602a81 4 months ago 3.28GB //} -===[/column] +書籍制作環境を全部含んでいるのでイメージサイズが3GB超と大きめです。 -//footnote[rbenv][@{https://github.com/sstephenson/rbenv#installation}] - -===[column] Ruby導入の手引き Windows編 +===[/column] -RubyInstaller@{rubyinstaller}を使うとよいでしょう。 -しかし、TechBoosterでは、Windows環境下ではロクなLaTeX環境を構築できていないのでPDFの出力に難があり、素直に仮想環境を利用しています。 -PDFを生成する必要がなければ、試す価値があるでしょう。 +== PDFファイルを出力する -===[/column] +Docker経由でのPDF出力を試しましょう。 +前節で少し触れましたがRe:VIEWでPDFに変換するにはLaTeX（platexまたはlualatexなど）を使います。 -//footnote[rubyinstaller][@{http://rubyinstaller.org/}] +Re:VIEW image for Docker内部のワークフローは@{.re}ファイルを含んだプロジェクトからRe:VIEWツールを実行し、出力対象がPDFファイルなのであればLaTeX形式に変換、TeXLive実行し、PDFファイルをローカルマシンにコピーして完了という流れです。 -== PDF出力を準備する +TechBoosterが提供しているReVIEW-templateリポジトリをベースに執筆している場合のPDF出力から説明します。 -#@# NOTE author:vvakame + * @{https://github.com/TechBooster/ReVIEW-Template} -PDF出力の準備をします。 -Re:VIEW文書をPDFに変換するにはLaTeX（platexまたはlualatexなど）を使います。 -出力時の処理はreview形式→reviewツール実行→latex形式→platex実行→PDF という流れです。 +Dockerで出力するスクリプトは@{C89-FirstStepReVIEW-v2}などプロジェクトルートから実行します（直下に@{articles}ディレクトリがあることを確認してください）。 -==== Mac OS Xの場合 +//cmd{ +yourbook_dir % pwd +/Users/mhidaka/repos/C89-FirstStepReVIEW-v2 -MacTeX@{mactex}を使いましょう。執筆時点ではMacTeX 2017が最新バージョンです。 +yourbook_dir % ./build-in-docker.sh +//} -//footnote[mactex][@{https://www.tug.org/mactex/}] +//cmd{ +yourbook_dir/articles/yourbookname.pdf +//} -==== Linuxの場合 +PDFファイルは@{articles/}ディレクトリの下に@{書籍名.pdf}という名前で出力されます。 -texliveパッケージを利用します。 -Ubuntu、Debianともに次のコマンドで導入できます。 -//emlist{ -$ sudo apt-get install texlive-lang-cjk texlive-fonts-recommended -//} +#@# prh:disable +スクリプトファイルではRe:VIEWの設定ファイルに@{articles/config.yml}を指定しています。書籍ごとに変えたいなど中身を知りたい場合は、この本のリポジトリの@{build-in-docker.sh}を参照してください。 -==== Windowsの場合 +#@# prh:disable + * @{https://github.com/TechBooster/C89-FirstStepReVIEW-v2/blob/master/build-in-docker.sh} -LaTeX環境の構築の難易度が高いため、Dockerなどの仮想環境を使うとよいでしょう。 +スクリプトを使わず@{docker}コマンドを手で打ち込んで実行する場合は次のコマンドです。 -==[column] Dockerとは？ +//cmd{ +docker run -t --rm -v `pwd`:/book vvakame/review:5.8 /bin/bash -ci + "cd /book && ./setup.sh && REVIEW_CONFIG_FILE=config.yml npm run pdf" +//} -Dockerは、最近はやりの仮想環境用のツールです。 -Linuxカーネルに組み込みの機能を使って、軽量かつ無駄の少ない仮想化環境を実現しています。 +毎回コマンドを打ち込むのは大変なので@{build-in-docker.sh}のようにまとめておくといいでしょう。 -Dockerはざっくり次の３つの利用方法があります。 +===[column] Re:VIEW image for Dockerのすごさ - 1. Dockerfile（イメージの設計図で主にコマンドの羅列）を書く - 2. Docker Hub@{docker-hub}などでホストされている他人が提供したDockerイメージを使う - 3. 他人の書いたDockerfileを元に自分のDockerfileを書く +本節で説明したワークフローでは、わかりやすさのためにRe:VIEWツールの内部で行なっている処理も含んでいます。 -本書ではDockerのインストール方法や使い方は解説しません。 -その時々で適切なやり方を調べてみてください。Ruby入れたりTeX入れたりめんどくさすぎる！ -という人のために、Dockerのイメージを用意@{docker-review}してあります。 +Re:VIEW image for DockerにはMeCabといった日本語形態素解析システムも入っているので、Re:VIEWで索引を作るといった真の書籍っぽい機能を引き出せます。索引がついた同人誌はあまり見かけませんが商業利用も盛んなRe:VIEWならではです。 -//cmd{ -$ docker run -i -t vvakame/review -v $(pwd):/book /bin/bash -//} +利用可能なフォントも豊富で、デフォルトでは原ノ味フォントを使います。オプションでIPAフォント、Notoフォントを導入可能です。いずれもフォント埋め込み済みのPDFファイルを出力できるので入稿でも安心です。 -コマンドを実行すると、reviewとlatexの実行環境が整った環境が直ちに使えます。 -コマンド実行後のディレクトリは@{/book}ディレクトリにマウントされます。 -適宜コンパイル用のコマンドを実行してください。 +原ノ味フォントは明朝体、ゴシック体ともにマルチウェイトなのでRegular、Medium、Boldといった太さも7種類に対応していて利用実績が多く、読み慣れています。 -#@# prh:disable -実用的な例を知りたい場合は、この本のリポジトリのbuild-in-docker.shを参照してください。 +IPAフォントは明朝体、ゴシック体それぞれに等幅とプロポーショナルがあるオープンソースのフォントです。 +ウェイトに対応していないため、太字にしたい場合にはシステム側で後処理が必要です。 -#@# prh:disable - * @{https://github.com/TechBooster/C89-FirstStepReVIEW-v2/blob/master/build-in-docker.sh} +NotoフォントはGoogleによって開発されたオープンソースフォントです。明朝体、ゴシック体の日本語フォント以外にも数多くのNotoフォントファミリーから構成されており、馴染みのある欧文フォントであるRobotoとの相性も抜群です。 +Re:VIEW image for Docker登場以前はフォントのセットアップだけでも一苦労で文字化けや意図しない表示に悩まされることも多かったものです。Re:VIEWの作者とコンテナのメンテナを褒め称えましょう。 -//footnote[docker-hub][@{https://hub.docker.com/}] -//footnote[docker-review][@{https://hub.docker.com/r/vvakame/review/}] +===[/column] -==[/column]