技術書を技術書執筆ツール(ReVIEW)で書いてみよう

2022年7月社内勉強会 技術書を技術書執筆ツール(Re:VIEW)で書 いてみよう 2022/7/25 パーソルテクノロジースタッフ株式会社 阿部耕二 koji.abe@persol.co.jp

目次 • 自己紹介 • 勉強会開催の背景・目的 • Re:VIEW概要 • Re:VIEW環境構築 • Re:VIEW機能紹介 2

• 自己紹介 • 勉強会開催の背景・目的 • Re:VIEW概要 • Re:VIEW環境構築 • Re:VIEW機能紹介 3

自己紹介 • 阿部 耕二（あべ こうじ） • 技術本部 機電技術部 首都圏2G • koji.abe@persol.co.jp • 医療機器開発 • 組込みソフトウェア開発。C言語、ベアメタルの開発業務経験がほとん ど。 • twitter: @juraruming 4

自己紹介 (技術書作成について) • 技術書は過去に4度書きイベント参加(技術書典9〜12)。 イベント初参加時(2020年9月)からRe:VIEWを使う。 • 電子書籍作成のみで紙の本の作成経験はなし。 • 次回の技術書典13でも本を書く予定。サークル名:k-abe。 5

• https://techbookfest.org/event/tbf13
• https://techbookfest.org/organization/5706998658105344

• 自己紹介 • 勉強会開催の背景・目的 • Re:VIEW概要 • Re:VIEW環境構築 • Re:VIEW機能紹介 6

勉強会開催の背景・目的 ・技術書を書く人が増えれば良いな〜との思いから開催を決めた。 7

• 自己紹介 • 勉強会開催の背景・目的 • Re:VIEW概要 • Re:VIEW環境構築 • Re:VIEW機能紹介 8

Re:VIEW概要 ・Re:VIEWは技術書執筆ツール ・【テキストエディタ】で執筆できるのが最大の特徴と思う。 →結果、変更管理ツール(例. git・GitHub)で変更管理が可能。 →結果、複数人・チーム(≒サークル)で執筆活動可能。 ・技術書を変更管理ツールで管理するメリット(今は一般的かと思いますが・・・) 例) 読者から本の間違いをIssuesとしてあげてもらう ・読者と正誤表を共有できる。 Issuesをある程度詳しく書けば何故間違いなのかその背景・変更経緯・意図も読者は共有できる。 いままでの紙の本にはなかった情報共有の形。 ・著者は変更内容が蓄積されるので改版が楽 9

• 自己紹介 • 勉強会開催の背景・目的 • Re:VIEW概要 • Re:VIEW環境構築 • Re:VIEW機能紹介 10

Re:VIEW環境構築 ・Re:VIEWの環境構築について書く。 ・今回はつぎの環境にRe:VIEWをセッティングした。 ・macOS Monterey バージョン12.4 (Intel Coreマシン) ・Re:VIEW バージョン5.4 ・エディタ：Visual Studio Code 1.69.2 ・TechBoosterのRe:VIEW用の書籍テンプレート(Re:VIEWバージョン5.4対応)を使用 ・つぎがインストール済みの前提で環境構築を進める。 GitHubアカウント作成済み、git, docker 11

Re:VIEW環境構築 こちらのブログ参考にさせていただきRe:VIEW環境構築をおこなう。 参考リンク1: ●Dockerを使ってRe:VIEWで本が書きたい！〜ステップ2:TechBoosterの テンプレートで原稿リポジトリを作ろう〜 参考リンク2: ●Dockerを使ってRe:VIEWで本が書きたい！〜ステップ3:vvakameさんの Dockerイメージで環境構築〜 12

• https://mochikoastech.hatenablog.com/entry/2019/08/05/130711
• https://mochikoastech.hatenablog.com/entry/2019/08/08/102254

Re:VIEW環境構築 ▪TechBoosterのRe:VIEWテンプレートから技術書原稿リポジトリを作る ●参考リンク1を参照し技術書原稿リポジトリをつくる。 ・こちらのテンプレートを使うといい塩梅(私は理解していない)に執筆環境がつ くれる。 ・参考リンク1を参照し環境構築し、READMEを修正するとつぎのようになる。 例) 私の次回執筆予定の技術書リポジトリ 13

• https://github.com/grace2riku/techbookfest_13_spresense_game

Re:VIEW環境構築 ▪Dockerで技術書を出力する ●参考リンク2を参照しDockerイメージで環境構築し技術書を出力する 参考リンクの記載と違うところのみ以降に記載する。 14

Re:VIEW環境構築 ▪Dockerで技術書を出力する(参考リンク2の変更点) ●vvakameさんのDockerイメージは5.4、TechBoosterのテンプレートは5.4対 応ということでvvakameさんのDockerイメージは【5.4】を使うことにする。 ●docker imageを連れてくる。 $ docker pull vvakame/review:5.4 ●docker imageがいるか確認する $ docker images vvakame/review REPOSITORY TAG IMAGE ID CREATED SIZE vvakame/review 5.4 9bfaaa9f8906 3 weeks ago 2.98GB 15

• https://hub.docker.com/r/vvakame/review
• https://github.com/TechBooster/ReVIEW-Template

Re:VIEW環境構築 ▪Dockerで技術書を出力する(参考リンク2の変更点) ●docker-compose.ymlを用意する version: '3' services: review: image: vvakame/review:5.4 volumes: - .:/13_spresense_game build: . working_dir: /13_spresense_game 変更点1) reviewのバージョンは5.4 変更点2) 自分の作業環境に合わせてvolumes, working_dirを変更 16

▪作業環境 Re:VIEW環境構築 17

Re:VIEW環境構築 ▪Dockerで技術書を出力する(参考リンク2の変更点) ●PDF出力のコマンド(赤字)を実行する $ pwd /Users/k-abe/techbookfest/13_spresense_game $ cd articles/ $ docker-compose run --rm review rake pdf Creating articles_review_run ... done review-pdfmaker config.yml ℹ INFO compiling preface.tex ℹ INFO compiling article.tex ℹ INFO compiling contributors.tex ℹ INFO uplatex -interaction=nonstopmode -file-line-error -halton-error __REVIEW_BOOK__.tex ℹ INFO uplatex -interaction=nonstopmode -file-line-error -halton-error __REVIEW_BOOK__.tex ℹ INFO uplatex -interaction=nonstopmode -file-line-error -halton-error __REVIEW_BOOK__.tex ℹ INFO dvipdfmx -d 5 -z 9 __REVIEW_BOOK__.dvi ✔ SUCCESS built ReVIEW-Template.pdf ●articlesディレクトリ以下にReVIEW-Template.pdfが作成される。 18

Re:VIEW環境構築 ▪Dockerで技術書を出力する(参考リンク2の変更点) ●articlesディレクトリ以下にReVIEW-Template.pdfが作成される。 下図は先頭と最終ページの抜粋。 19

Re:VIEW環境構築 ▪Dockerで技術書を出力する(参考リンク2の変更点) ●自分の本に合わせてカスタマイズする。articles/config.ymlを修正しPDF 出力する。下図は変更後の先頭・最終ページ。変更内容はこちら。 20

• https://github.com/grace2riku/techbookfest_13_spresense_game/commit/ad0afd616c42bc9d408620f69683f9d89e7f3b63

• 自己紹介 • 勉強会開催の背景・目的 • Re:VIEW概要 • Re:VIEW環境構築 • Re:VIEW機能紹介 21

Re:VIEW機能紹介 ▪どう執筆していくの??? ▪見出し ▪コメント ▪リンク ▪コード ▪コマンドライン ▪画像ファイルの参照 ▪脚注 ※紹介しているのは一部の機能なので本家のRe:VIEW フォーマットガイ ド、チートシートを参照のこと。 22

• https://github.com/kmuto/review/blob/master/doc/format.ja.md
• https://gist.github.com/erukiti/c4e3189dda179a0f0b73299fb5787838

Re:VIEW機能紹介 ▪どう執筆していくの??? ●章ごとのファイル作成する。 articles/catalog.ymlに記載したファイルをarticles以下に作成し執筆して いく。過去に書いた技術書で説明する。 本の概要：Spresense タルカメラ開発 本の原稿リポジトリ：12_spresense_camera ジ デ 23

• https://techbookfest.org/product/6145133823131648?productVariantID=6677722182975488
• https://github.com/grace2riku/12_spresense_camera

・本の章の構成を決めてcatalog.ymlに
ファイル名を記載する。
・catalog.ymlに書いたファイルを編集していく

articles/catalog.yml

PREDEF:
- preface.re
CHAPS:
- spresense_overview.re
- camera_overview.re
- hardware_overview.re
- development_environment.re
- development_method.re
- Spresense_SDK.re
- Arduino_IDE.re
- SDK_Arduino_compare.re
- camera_subject.re
- camera_expand.re

PDF出力した本
Re:VIEWの書式に則り執筆する
articles/spresense_overview.re
//footnote[spresense_overview][https://developer.sony.com/ja/develop/spresense/]
= Spresense概要説明
Spresense(読み方:スプレッセンス)はソニーが開発したプロセッサ【CXD5602】が搭載された【ボード】で
す。
こちらのページ@<fn>{spresense_overview}で紹介されています。
個人的に気になるポイントを次に挙げます。
* GPS内蔵

POSTDEF:
- contributors.re

* ハイレゾソリューションオーディオ機能内蔵
* マルチコアプロセッサ(CXD5602はARM Cortex-M4Fが6つ搭載)
* Arduino IDEまたはSpresense SDKで組込み開発可能
* SONY、サードパーティー製のボードで機能拡張可能

24

• https://github.com/grace2riku/12_spresense_camera/blob/master/articles/catalog.yml
• https://github.com/grace2riku/12_spresense_camera/blob/master/articles/spresense_overview.re

Re:VIEW機能紹介 ▪どう執筆していくの??? ▪見出し ▪コメント ▪リンク ▪コード ▪コマンドライン ▪画像ファイルの参照 ▪脚注 25

見出しは【=】で階層構造がつくれる
articles/hardware_overview.re
= ハードウェアの説明

PDF出力した本

== 必要な部品
デジタルカメラに必要な部品について書きます。
1. メインボード
2. 拡張ボード
3. カメラボード
4. LCD ILI9341 2.2inch
5. APS学習ボード
6. マイクロSDカード
7. USBケーブル USBタイプA-マイクロBタイプ
=== メインボード
=== 拡張ボード
=== カメラボード
メインボード、拡張ボード、カメラボードは次に説明が書かれています。@<br>{}
@<href>{https://developer.sony.com/develop/spresense/docs/
sdk_tutorials_ja.html#_camera_%E3%83%81%E3%83%A5%E3%83%BC%E3%83
%88%E3%83%AA%E3%82%A2%E3%83%AB}
メインボードは2.1.1. Spresense メインボードです。
拡張ボードは2.1.2. Spresense 拡張ボードです。
カメラボードは2.1.4. Spresense カメラボードです。

26

• https://github.com/grace2riku/12_spresense_camera/blob/master/articles/hardware_overview.re

Re:VIEW機能紹介 ▪どう執筆していくの??? ▪見出し ▪コメント ▪リンク ▪コード ▪コマンドライン ▪画像ファイルの参照 ▪脚注 27

▪コメント Re:VIEW機能紹介 コメントは【#@#】と記載する。 例) #@# コメントだよ 1行コメントで複数行をコメントするブロックコメントはない模様。 コメント行は本に出力されない。 TODOコメントなどに使うと便利かもしれない。 28

Re:VIEW機能紹介 ▪どう執筆していくの??? ▪見出し ▪コメント ▪リンク ▪コード ▪コマンドライン ▪画像ファイルの参照 ▪脚注 29

リンクは@<href>{URL}と記載する
articles/hardware_overview.re
= ハードウェアの説明

PDF出力した本

== 必要な部品
デジタルカメラに必要な部品について書きます。
1. メインボード
2. 拡張ボード
3. カメラボード
4. LCD ILI9341 2.2inch
5. APS学習ボード
6. マイクロSDカード
7. USBケーブル USBタイプA-マイクロBタイプ
=== メインボード
=== 拡張ボード
=== カメラボード
メインボード、拡張ボード、カメラボードは次に説明が書かれています。@<br>{}
@<href>{https://developer.sony.com/develop/spresense/docs/
sdk_tutorials_ja.html#_camera_%E3%83%81%E3%83%A5%E3%83%BC%E3%83
%88%E3%83%AA%E3%82%A2%E3%83%AB}
メインボードは2.1.1. Spresense メインボードです。
拡張ボードは2.1.2. Spresense 拡張ボードです。
カメラボードは2.1.4. Spresense カメラボードです。

30

• https://github.com/grace2riku/12_spresense_camera/blob/master/articles/hardware_overview.re

Re:VIEW機能紹介 ▪どう執筆していくの??? ▪見出し ▪コメント ▪リンク ▪コード ▪コマンドライン ▪画像ファイルの参照 ▪脚注 31

コードは【リスト】で記載する
articles/hardware_overview.re
=== Spresense SDKでGPIOを指定する場合

PDF出力した本

前述の資料でSpresense SDKでAPS学習ボードのタクトスイッチSW1（拡張ボード
JP13-1に接続）を指定する名称がわかりました。
【SDK上の名称】・【SDK上のピン番号】は次のヘッダファイルに定義されていま
す。@<br>{}
* @<href>{https://github.com/sonydevworld/spresense-nuttx/blob/new-master/arch/
arm/include/cxd56xx/pin.h,【リンク】nuttx/arch/arm/include/cxd56xx/pin.h}@<br>{}
ローカルPCに環境構築したソースコードの場合（Mac）は次のファイルパス
@<br>{}
/Users/ユーザー名/spresense/nuttx/arch/arm/include/cxd56xx/pin.h
このヘッダファイルに【SDK上の名称】・【SDK上のピン番号】がマクロで定義さ
れています。
//list[sdk_pin_h_39][Spresense SDKピンヘッダーファイルの39ピンの定義]{
#de ne PIN_SPI3_CS1_X
//}

(39)

実際にタクトスイッチをリードするコードは次になります。
//list[spresense_sdk_sw1_read_list_1][Spresense SDKでSW1をリードするコード
1]{
int sw1_status = board_gpio_read(PIN_SPI3_CS1_X);
//}
または

fi

32

• https://github.com/grace2riku/12_spresense_camera/blob/master/articles/hardware_overview.re

Re:VIEW機能紹介 ▪どう執筆していくの??? ▪見出し ▪コメント ▪リンク ▪コード ▪コマンドライン ▪画像ファイルの参照 ▪脚注 33

コマンドラインの記載はつぎのとおり。 //cmd{ コマンドライン //} articles/camera_overview.re SDKの【examples/camera】サンプルプログラムは次のハードウェアを使う前提と PDF出力した本 なっています。 * Spresense Main Board（以降、メインボードと呼びます） * Spresense Camera Board（以降、カメラボードと呼びます） * Spresense Extension Board（以降、拡張ボードと呼びます） * Arduino UNO LCD Connector board * ILI9341 2.2inch LCD サンプルプログラムはコマンドライン引数により動作が次のように変わります。 撮影画像はマイクロSDカードに保存されます。 もしマイクロSDカードが拡張ボードに挿入されていない場合はFlashROMに保存さ れます。 //cmd{ nsh> camera //} LCDにカメラの画像を表示し、10フレーム撮影後に終了します。 画像ファイルのフォーマットはRGB565形式になります。 //cmd{ nsh> camera -jpg //} LCDにカメラの画像を表示し、10フレーム撮影後に終了します。 画像ファイルのフォーマットはjpg形式になります。 //cmd{ nsh> camera n //} LCDにカメラの画像を表示し、nフレーム撮影後に終了します。 画像ファイルのフォーマットはRGB565形式になります。 nは0から100の範囲内で指定します。 nが0の場合はLCDに画像を表示し続け、画像ファイルを保存しません。 34

• https://github.com/grace2riku/12_spresense_camera/blob/master/articles/camera_overview.re

Re:VIEW機能紹介 ▪どう執筆していくの??? ▪見出し ▪コメント ▪リンク ▪コード ▪コマンドライン ▪画像ファイルの参照 ▪脚注 35

・画像はつぎで記載できる。 //Image[画像ファイル名][図の名称]{ //} ・画像ファイルは下図のように/articles/imagesディレクトリ以下に配置する。 articles/camera_overview.re //image[main+ex+camera_board][拡張ボード+メインボード+カメラボード]{ //} 拡張ボードとAPS学習ボードを接続します。 //image[main+ex+camera+aps_board][拡張ボード+メインボード+カメラボード +APS学習ボード]{ //} 最後にAPS学習ボードとLCDを接続すればデジタルカメラのハードウェアが完成で す。 36

• https://github.com/grace2riku/12_spresense_camera/blob/master/articles/camera_overview.re

Re:VIEW機能紹介 ▪どう執筆していくの??? ▪見出し ▪コメント ▪リンク ▪コード ▪コマンドライン ▪画像ファイルの参照 ▪脚注 37

・//foonote[参照名称][リンク先]で参照名称・リンク先を記載する。
・@<fn>{参照名称}でページ下部に脚注が記載される。

articles/spresense_overview.re
//footnote[spresense_overview][https://developer.sony.com/ja/develop/
spresense/]
= Spresense概要説明
Spresense(読み方:スプレッセンス)はソニーが開発したプロセッサ
【CXD5602】が搭載された【ボード】です。
こちらのページ@<fn>{spresense_overview}で紹介されています。
個人的に気になるポイントを次に挙げます。
* GPS内蔵
* ハイレゾソリューションオーディオ機能内蔵
* マルチコアプロセッサ(CXD5602はARM Cortex-M4Fが6つ搭載)
* Arduino IDEまたはSpresense SDKで組込み開発可能
* SONY、サードパーティー製のボードで機能拡張可能

38

• https://github.com/grace2riku/12_spresense_camera/blob/master/articles/spresense_overview.re

終わり ご静聴ありがとう ございました。 39