diff --git a/articles/configure.re b/articles/configure.re index 415ca5b..7d243c9 100644 --- a/articles/configure.re +++ b/articles/configure.re @@ -15,12 +15,14 @@ Re:VIEWでは書籍に関する情報を章を設定する@{catalog.yml}と //list[catalog_yml_sample][５つの章をもつcatalog.yml]{ PREDEF: - preface.re + CHAPS: - writing-book.re - environment.re - workflow.re - publishing-book.re - distribution.re + APPENDIX: - tips.re @@ -29,6 +31,7 @@ POSTDEF: //} @{catalog.yml}の各項目の内容は次のとおりです。 +CHAPSのみを必須として前書き、付録、後書きなど本を構成する構造を定義しています。 : PREDEF 前書きなど目次の前に記載するものを指定します @@ -134,15 +137,16 @@ colophon: true 目次として抽出する章や節の深さを変更するには、@{config.yml}の@{toclevel}項目を設定します（@{toclevel}）。 //list[toclevel][抽出レベルを設定]{ +# 目次として抽出する見出しレベル toclevel: 2 //} 抽出レベルを変更すると、値に応じた深さの見出しを出力します（@{toclevel2}および@{toclevel3}）。 -//image[toclevel2][toclevel:2を指定した場合の目次][scale=0.75]{ +//image[toclevel2][toclevel:2を指定した場合の目次][scale=0.85]{ //} -//image[toclevel3][toclevel:3を指定した場合の目次][scale=0.75]{ +//image[toclevel3][toclevel:3を指定した場合の目次][scale=0.85]{ //} =={layout} 用紙サイズやデザインを変更する diff --git a/articles/distribution.re b/articles/distribution.re index cc15c2c..2fb3ebe 100644 --- a/articles/distribution.re +++ b/articles/distribution.re @@ -27,7 +27,7 @@ ニッチな技術書だからといって遠慮することはありません。書籍の表紙やサンプルページなど画像とともに訴求していきましょう。 XやblueskyのようなSNSであればハッシュタグ@{hash}を活用して告知してください。 -//footnote[hash][技術書典であれば#技術書典、コミックマーケット103であれば#C103などの略称が使われます] +//footnote[hash][技術書典であれば@{#技術書典}、コミックマーケット103であれば@{#C103}などの略称が使われます] いずれの告知方法も一朝一夕で効果がでるものではないのですが、やらないよりはずっと効果が期待できます。 もっとも確実な告知は継続的な参加とアウトプットです。即効性はありませんが一度読んで面白かった本のことは良く覚えてるものです@{power}。 @@ -65,7 +65,7 @@ XやblueskyのようなSNSであればハッシュタグ@{hash}を活用し //} 表ではよく使われてるものを中心に集めています。また必須の項目には◯をつけました。これらの準備は前日までに終わらせておくとベターです。 -技術書典では電子決済をサポートしているので現金をもってこない出展者も見かけるようになりましたが、それ以外のイベントでは現金もまだまだ現役です。 +技術書典では電子決済をサポートしているので現金を特別用意しない出展者も見かけるようになりました。それ以外のイベントでは現金もまだまだ現役です。 イベントでは180センチ長の机を使います。技術書典の場合は机1本の180cmが割り当てられます。それ以外のイベントであれば多くの場合、机半分の90cm幅が自由に使える展示スペースです。 出展者は開場の１～2時間前には入場して自分のスペースをレイアウトします。周りも展示の準備をしていますのでスペースのはみ出し、 @@ -73,7 +73,8 @@ XやblueskyのようなSNSであればハッシュタグ@{hash}を活用し //footnote[eyes][時間帯によっては通路が混雑します。貴重品の管理は厳重に！] -今回、必須としていませんがポスターはコスパよく訴求できるのでおすすめしたい準備物です。どんな読者に読んでほしいか、目に付きやすいキャッチコピーやPRを記載しておくといいでしょう。 +#@# prh:disable +今回、必須としていませんがポスターはコスパよく訴求できるのでお勧めしたい準備物です。どんな読者に読んでほしいか、目に付きやすいキャッチコピーやPRを記載しておくといいでしょう。 よくできたポスターには眼の前を素通りさせないパワーがあります。 展示物にあわせてタブレットをつかったり、ハードウェアの実演、パネルやイーゼルで見やすく配置して工夫してもよいでしょう。 diff --git a/articles/images/configure/toclevel2.png b/articles/images/configure/toclevel2.png index 19f774e..9145f51 100644 Binary files a/articles/images/configure/toclevel2.png and b/articles/images/configure/toclevel2.png differ diff --git a/articles/images/configure/toclevel3.png b/articles/images/configure/toclevel3.png index c3ce580..e1bc23c 100644 Binary files a/articles/images/configure/toclevel3.png and b/articles/images/configure/toclevel3.png differ diff --git a/articles/images/planning-book/books.png b/articles/images/planning-book/books.png index b5e0710..c2034e4 100644 Binary files a/articles/images/planning-book/books.png and b/articles/images/planning-book/books.png differ diff --git a/articles/images/planning-book/techbookfest.png b/articles/images/planning-book/techbookfest.png index 472ebb8..518b4eb 100644 Binary files a/articles/images/planning-book/techbookfest.png and b/articles/images/planning-book/techbookfest.png differ diff --git a/articles/images/publishing-book/ebook.png b/articles/images/publishing-book/ebook.png index 18772e7..163a273 100644 Binary files a/articles/images/publishing-book/ebook.png and b/articles/images/publishing-book/ebook.png differ diff --git a/articles/images/publishing-book/epub.png b/articles/images/publishing-book/epub.png index 8485943..65af0e0 100644 Binary files a/articles/images/publishing-book/epub.png and b/articles/images/publishing-book/epub.png differ diff --git a/articles/images/publishing-book/epub_reader.png b/articles/images/publishing-book/epub_reader.png index 5866dc2..9135a7f 100644 Binary files a/articles/images/publishing-book/epub_reader.png and b/articles/images/publishing-book/epub_reader.png differ diff --git a/articles/images/publishing-book/hyoushi.png b/articles/images/publishing-book/hyoushi.png index b44bf6a..0120272 100644 Binary files a/articles/images/publishing-book/hyoushi.png and b/articles/images/publishing-book/hyoushi.png differ diff --git a/articles/images/publishing-book/nombre.png b/articles/images/publishing-book/nombre.png new file mode 100644 index 0000000..446739c Binary files /dev/null and b/articles/images/publishing-book/nombre.png differ diff --git a/articles/images/publishing-book/pdfx.png b/articles/images/publishing-book/pdfx.png index e0a5b1a..921b4fe 100644 Binary files a/articles/images/publishing-book/pdfx.png and b/articles/images/publishing-book/pdfx.png differ diff --git a/articles/images/publishing-book/replace-color-dot-gain.png b/articles/images/publishing-book/replace-color-dot-gain.png index 133c161..bf16a7b 100644 Binary files a/articles/images/publishing-book/replace-color-dot-gain.png and b/articles/images/publishing-book/replace-color-dot-gain.png differ diff --git a/articles/images/publishing-book/replace-color.png b/articles/images/publishing-book/replace-color.png index 2cc87e8..ee2c4db 100644 Binary files a/articles/images/publishing-book/replace-color.png and b/articles/images/publishing-book/replace-color.png differ diff --git a/articles/images/setup/webroot.png b/articles/images/setup/webroot.png index b9d0487..febed26 100644 Binary files a/articles/images/setup/webroot.png and b/articles/images/setup/webroot.png differ diff --git a/articles/images/setup/webroot_browsing.png b/articles/images/setup/webroot_browsing.png new file mode 100644 index 0000000..9c6c9e9 Binary files /dev/null and b/articles/images/setup/webroot_browsing.png differ diff --git a/articles/planning-book.re b/articles/planning-book.re index d255dfc..073edd5 100644 --- a/articles/planning-book.re +++ b/articles/planning-book.re @@ -50,8 +50,8 @@ //footnote[techbookfest][@{https://techbookfest.org/}] 本が集まるもっとも有名なイベントはコミックマーケットでしょう。いわゆるサブカルチャーが集まる即売会です。 -8月と12月の年2回、約25万人の参加者が集う巨大マーケットです。参加者はそれぞれの趣味を楽しみにきており、その一角に技術書が居ます。コミックマーケットにはジャンルというくくりがあり、ジャンル毎に何日目のどのあたりの場所、とざっくり決まっています。技術書であれば、「同人ソフト」または「評論・情報」のどちらかで応募している場合が多いです。 -ちなみに、TechBoosterは同人ソフトジャンルでモバイルアプリ関連技術で本を出しています。 +8月と12月の年2回、約25万人の参加者が集う巨大マーケットです。参加者はそれぞれの趣味を楽しみにきており、その一角に技術書が居ます。コミックマーケットにはジャンルというくくりがあり、ジャンル毎に何日目のどのあたりの場所とざっくり決まっています。技術書であれば、「同人ソフト」または「評論・情報」のどちらかで応募している場合が多いです。 +ちなみにTechBoosterは同人ソフトジャンルでモバイルアプリ関連技術で本を出しています。 == 書きたいものを書こう diff --git a/articles/publishing-book.re b/articles/publishing-book.re index 3654a8a..c7f7ef2 100644 --- a/articles/publishing-book.re +++ b/articles/publishing-book.re @@ -29,7 +29,7 @@ 印刷所へ最終的な印刷用データを渡すことを@{入稿,にゅうこう}と呼びます。 本節では入稿手順を解説しますが入稿には専門的な注意点も多いため専門用語は出てきたタイミングで説明を補います。 -@{writing-book}で述べたとおり、同人誌向けのRe:VIEWプロジェクト構成を使用する前提です。TechBoosterのテンプレートリポジトリをcloneしている場合、@{ノンブル,通し番号}のような同人誌特有の問題を回避できます。 +@{writing-book}で述べたとおり、同人誌向けのRe:VIEWプロジェクト構成を使用する前提です。TechBoosterのテンプレートリポジトリをCloneしている場合、@{ノンブル,通し番号}のような同人誌特有の問題を回避できます。 #@# prh:disable * @{https://github.com/TechBooster/ReVIEW-Template} @@ -43,7 +43,7 @@ 今回は日光企画さんの事例に限って入稿に必要な知識をみていきましょう。実際には入稿予定の印刷所が指定するフォーマット、注意点を熟読して挑んでください。 とはいえ困ったことばかりではありません。 -繰り返すようにテンプレートリポジトリを使っている限り、大きな問題には合いませんし、印刷所のスタッフさんも表紙や本文を目で確認してくれるため +繰り返すようにテンプレートリポジトリを使っている限り、大きな問題にはあいませんし、印刷所のスタッフさんも表紙や本文を目で確認してくれるため 誤字や脱字、はみ出しや印刷の問題が見つかって教えてくれるボーナスイベントも発生します。安心してください。 注文に先立って知っておく知識として、部数に応じて適した印刷手法が異なります。 @@ -124,10 +124,11 @@ review-pdfmaker config.yml 基本的にページ数が４の倍数になるように揃えて入稿します。ならない場合は無理やり白いページを挟むこともあります。 またページごとにノンブル（ページの通し番号）は、たとえ白いページであっても必ず番号をいれます。同人誌以外では見ない制約ですし、印刷所によっても異なります。 -乱丁を防ぐ意図もありますがページ数がわかると純粋に参照しやすいのも事実です。 +乱丁を防ぐ意図もありますがページ数が分かると純粋に参照しやすいのも事実です。 ノンブル不要な印刷所であっても念のため入れておくのもよいでしょう。なおノンブルのレイアウトは紙面の下側が一般的です。 -#@# TODO 作図する +//image[nombre][ノンブル位置の例]{ +//} 本の紙面は綴じている側（本の中心）の余白をノドと呼び、左右の端側の余白を小口と呼びます。本を読むとき、小口と地に指がかかりやすいため、わたしたちの提供するレイアウトでは見やすいよう余裕を持った設定をしています。 @@ -175,6 +176,7 @@ review-pdfmaker config-ebook.yml //} 大きな違いはフォントと余白です。紙面ではのりで本を綴じるため、手で持って読むために余白を広く取ってあります。 + 一方の電子書籍用に最適化したレイアウトでは余白を最小限に、PCやスマートフォンで読みやすいようにフォントも変えています。 小さな違いにみえるかもしれませんが、快適に読むための工夫がたっぷり含まれています。 @@ -249,14 +251,13 @@ EPUBとPDFはフォーマットの違いから設定できる項目にも違い epubmaker: # HTMLファイルの拡張子 htmlext: xhtml - stylesheet: ["style.css", "epub_style.css"] + stylesheet: ["epub_style.css", "epub_style.scss"] //} @{epubmaker}に続く設定はEPUBフォーマット専用の項目です。PDF等と共用できるものは引き継いでいるので安心してください。 -ただEPUBの設定項目は専門的な知識が求められるので、変更する場合は表紙を最初のページとして表示するか決める@{cover_linear}ぐらいに留めておいてください。 +ただしEPUBの設定項目は専門的な知識が求められるので、変更する場合は表紙を最初のページとして表示するか決める@{cover_linear}ぐらいに留めておいてください。 フォーマットごとに出力し、複数の成果物を管理するのは想像異常に大変です。慣れてきたり、必要に迫られたら考えましょう。 - GitHub ActionsのRe:VIEW-build-artifact-actionは現時点でEPUB出力に対応していません。 ローカルPC上にRe:VIEWの実行環境を用意して@{review-epubmaker}コマンドでビルドしてください。 @@ -268,12 +269,12 @@ review-epubmaker config.yml 成功したら@{bookname.epub}ファイルを出力します。EPUBファイルはApple Books等で表示してみましょう（@{epub}）。 -//image[epub][iBooksでの表示例]{ +//image[epub][Apple Booksでの読書例]{ //} EPUBリーダーで柔軟にレイアウトし、読者の環境に合わせて読める特徴は他のフォーマットにない利点です。 -世の中にはApple Books以外のEPUBリーダーも存在しています。それぞれのリーダーごとに表示が異なるため、可能な限り多くの電子ブックアプリで動作確認してください。 +世の中にはApple Books以外のEPUBリーダーも存在しています。それぞれのリーダーで表示が異なるため、可能な限り多くの電子ブックアプリで動作確認してください。 これはPDFとEPUBのフォーマットの違いをよく表しています。EPUBはレイアウトやフォントサイズなどの表示品質はリーダーに委ねているのです@{why_epub}。 //footnote[why_epub][委ねたほうがデバイスや読者の要望ごとに最適な読書環境が提供できるとの考えからです] @@ -286,6 +287,7 @@ EPUBリーダーで柔軟にレイアウトし、読者の環境に合わせて 2. PDFファイルのフォーマット変換 3. 画像等のモノクロ化 +#@# prh:disable 実は３つともReVIEW-Templateリポジトリをデフォルトで使っている限り、ほぼ気にしなくていい内容です。 ひとつめのフォントの埋め込み確認は入稿時の確認という意味では必須です。しかし残りのふたつは印刷所のノウハウ蓄積もありほぼ問題にならなくなりました。少なくとも技術書典のバックアップ印刷所では作業の必要はありません。 @@ -323,9 +325,9 @@ PDFファイルであれば大丈夫じゃないのと感じるかもしれま === 原稿のモノクロ化 -入稿の最終段階です。作成したPDFデータをモノクロ化します。モノクロ化にあたってはPDF/Xフォーマットであることが前提ですので、前述のフォーマット変換作業を忘れずにおこなってください。 +入稿の最終段階です。作成したPDFデータをモノクロ化します。モノクロ化にあたってはPDF/Xフォーマットであることが前提ですので、前述のフォーマット変換作業を忘れずに行なってください。 -ツールから印刷工程を選ぶと色を置換というサイドメニューが表示されています（前述の@{pdfx}のPDF/Xとしての保存の２つ上です）。 +ツールから印刷工程を選ぶと色を置換というサイドメニューが出ます（@{pdfx}のPDF/Xとしての保存の２つ上です）。 ここではオブジェクトのうち、DeviceCMYKカラータイプのプロファイルを変換します（@{replace-color}、@{replace-color-dot-gain}）。 @@ -335,9 +337,9 @@ PDFファイルであれば大丈夫じゃないのと感じるかもしれま //image[replace-color-dot-gain][カラーを出力インテントに変換をチェック]{ //} -@{カラーを出力インテントに変換}にチェックをいれて、@{Dot Gain 15%}を選択します。 -また変換のオプションで@{黒を維持}もチェックします。 +@{カラーを出力インテントに変換}にチェックをいれて、@{Dot Gain 15%}を選択します。 +また変換のオプションで@{黒を維持}もチェックします。 この設定で色を置換すると無事、モノクロ化できます。ここまでで本文の入稿データ作成は完了です。 -本手法に限らずモノクロ変換の際には、カラー画像の際には全く違う色だったものが同じような色味に変わってしまうケースがあります。図やグラフでありがちなのでモノクロで見ても視認性が高く保たれているかという観点で変換後のPDFファイルを確認してください。 +本手法に限らずモノクロ変換の際には、カラー画像の際にはまったく違う色だったものが同じような色味に変わってしまうケースがあります。図やグラフでありがちなのでモノクロで見ても視認性が高く保たれているかという観点で変換後のPDFファイルを確認してください。 diff --git a/articles/review-introduction.re b/articles/review-introduction.re index 499e4be..220b0d8 100644 --- a/articles/review-introduction.re +++ b/articles/review-introduction.re @@ -609,6 +609,9 @@ Re:VIEWでは、見出しキャプションとは別に参照用のラベルを //list[refer_section_label][見出しの参照]{ ＠{commandline} + +別の章からの参照 +＠{chapter_filename|commandline} //} 通常の節の参照同様、違う章の節を参照できる優れものです。 diff --git a/articles/setup.re b/articles/setup.re index a0f4cb0..a2c5136 100644 --- a/articles/setup.re +++ b/articles/setup.re @@ -74,7 +74,7 @@ Re:VIEW image for Dockerは最新のRe:VIEWをどの環境でも安定して使 #@# TODO 入稿前にここのバージョンを再確認すること #@# prh:disable - * macOS Sonoma + * macOS Ventura 13.5.1 * Docker Desktop Version 4.25.0 (126437) Re:VIEWツールそのものはRuby言語で書かれており、macOS、Windows、LinuxどのOSでも動作します。 @@ -134,20 +134,19 @@ Docker経由でのPDF出力を試しましょう。 Re:VIEW image for Docker内部のワークフローは@{.re}ファイルを含んだプロジェクトからRe:VIEWツールを実行し、出力対象がPDFファイルであればLaTeX形式に変換、TeXLiveを実行して生成したPDFファイルをローカルマシンにコピーして完了という流れです。 #@# prh:disable -TechBoosterが提供しているReVIEW-templateリポジトリをベースに執筆している場合のPDF出力から説明します。 +TechBoosterが提供しているReVIEW-templateリポジトリをベースに執筆している場合のPDF出力方法を説明します。 #@# prh:disable * @{https://github.com/TechBooster/ReVIEW-Template} #@# prh:disable -Dockerで出力するスクリプトは@{C89-FirstStepReVIEW-v2}などプロジェクトルートから実行します（直下に@{articles}ディレクトリがあることを確認してください）。 +Docker実行用のスクリプトは@{C89-FirstStepReVIEW-v2}などプロジェクトルートから実行します（直下に@{articles}ディレクトリがあることを確認してください）。 #@# prh:disable //cmd{ -yourbook_dir % pwd +$ pwd /Users/mhidaka/repos/C89-FirstStepReVIEW-v2 - -yourbook_dir % ./build-in-docker.sh +$ ./build-in-docker.sh //} //cmd{ @@ -158,7 +157,7 @@ PDFファイルは@{articles/}ディレクトリの下に@{書籍名.pdf #@# prh:disable -スクリプトファイルのなかでRe:VIEWの設定ファイル@{articles/config.yml}を指定しています。書籍ごとに変えたいなど中身を知りたい場合は、この本のリポジトリにある@{build-in-docker.sh}を参照してください。 +スクリプトファイルのなかでRe:VIEWの設定ファイル@{articles/config.yml}を指定しています。処理を変えたいなど中身を知りたい場合は、本書のリポジトリにある@{build-in-docker.sh}を参照してください。 #@# prh:disable * @{https://github.com/TechBooster/C89-FirstStepReVIEW-v2/blob/master/build-in-docker.sh} @@ -174,7 +173,7 @@ docker run -t --rm -v `pwd`:/book vvakame/review:5.8 /bin/bash -ci ===[column] Re:VIEW image for Dockerのすごさ -本節で説明したワークフローでは、わかりやすさのためにRe:VIEWツールの内部で行なっている処理も含んでいます。 +本節で説明したワークフローでは、わかりやすさのためにRe:VIEWツールの内部で行なっている処理も含んで解説しています。 Re:VIEW image for DockerにはMeCabといった日本語形態素解析システムも入っているので、Re:VIEWで索引を作るといった真の書籍っぽい機能を引き出せます。索引がついた同人誌はあまり見かけませんが商業利用も盛んなRe:VIEWならではです。 @@ -185,9 +184,9 @@ Re:VIEW image for DockerにはMeCabといった日本語形態素解析システ IPAフォントは明朝体、ゴシック体それぞれに等幅とプロポーショナルがあるオープンソースのフォントです。 ウェイトに対応していないため、太字にしたい場合にはシステム側で後処理が必要です。 -NotoフォントはGoogleによって開発されたオープンソースフォントです。明朝体、ゴシック体の日本語フォント以外にも数多くのNotoフォントファミリーから構成されており、馴染みのある欧文フォントであるRobotoとの相性も抜群です。 +NotoフォントはGoogleによって開発されたオープンソースフォントです。明朝体、ゴシック体の日本語フォント以外にも数多くのNotoフォントファミリーから構成されており、馴染みの欧文フォントであるRobotoとの相性も抜群です。 -Re:VIEW image for Docker登場以前はフォントのセットアップだけでも一苦労で文字化けや意図しない表示に悩まされることも多かったものです。Re:VIEWの作者とコンテナのメンテナを褒め称えましょう。 +Re:VIEW image for Docker登場以前はフォントのセットアップだけでも一苦労でした。文字化けや意図しない表示に悩まされることも多かったものです。Re:VIEWの作者とコンテナのメンテナを褒め称えましょう。 ===[/column] @@ -195,7 +194,7 @@ Re:VIEW image for Docker登場以前はフォントのセットアップだけ == 応用編：書籍をローカル環境でビルドするには #@# prh:disable -本節ではRe:VIEWファイルをローカル環境でコンパイルする方法を紹介します。Re:VIEWは、Markdown、プレーンテキスト、HTMLやEPUBなど多様なフォーマットに対応しています。 +本節ではRe:VIEWファイルをローカル環境でコンパイルする方法を紹介します。Re:VIEWはMarkdown、プレーンテキスト、HTMLやEPUBなど多様なフォーマットに対応しています。 ローカル環境の構築ドキュメントとPDFを出力する@{review-pdfmaker}、EPUBを出力する@{review-epubmaker}、Webページを出力する@{review-webmaker}に触れますが 入稿に利用する形式は@{review-pdfmaker}コマンドでのPDF形式です。 @@ -218,7 +217,7 @@ gem install review //} Re:VIEWの開発チームは、定期的に新しいバージョンをリリースしています。 -執筆中、または執筆を完了した書籍のアップデートなどでバージョンを変更する場合はチェンジログを確認し、意図せずレイアウトが崩れないよう互換性確保に気をつけてください。 +執筆中、または執筆を完了した書籍のアップデートなどでバージョンを変更する際にはチェンジログを確認し、意図せずレイアウトが崩れないよう互換性確保に気をつけてください。 === review-pdfmaker @@ -241,8 +240,8 @@ YAMLファイルには本のタイトルや筆者名といった本のメタデ === 制作時に出会うエラーたち @{review-pdfmaker}をはじめて使うときは作法がわからず戸惑うかもしれません。 -もっとも単純な事例では@{catalog.yml}の@{CHAPS}で追加した@{.re}ファイルを書き忘れることです。 -単純に参照がない場合もビルドが成功するので（機械にはわからないエラーなので）追加分が見えないため慣れないうちは困惑します。 +ありがちな事例は@{catalog.yml}の@{CHAPS}に作成した@{.re}ファイルを書き忘れることです。 +単純に参照がない場合もビルドが成功するので（機械にはわからないエラーなので）追加分がPDFファイルに書き出されない現象が起きます。慣れないうちは困惑します。 検出しにくい見た目の問題も挙げましょう。 @@ -292,8 +291,12 @@ webroot: directory //} #@# prh:disable -読み込むCSSファイルなどは参照するYAMLファイル内の@{webmaker}パラメータを元にして設定しています（@{webroot}）。 +読み込むCSSファイルなどは参照するYAMLファイル内の@{webmaker}パラメータを元にして設定しています（@{webroot}、@{webroot_browsing}）。 + +#@# prh:disable +//image[webroot][review-webmakerの出力例（ファイル構成）]{ +//} #@# prh:disable -//image[webroot][review-webmakerの出力例][scale=0.75]{ +//image[webroot_browsing][review-webmakerの出力例（ブラウザ表示）]{ //} diff --git a/articles/textlint.re b/articles/textlint.re index 8645d48..8d4f62a 100644 --- a/articles/textlint.re +++ b/articles/textlint.re @@ -3,7 +3,9 @@ 本を作るうえで苦労することのひとつに統一感があります。文章が途中で変わっていないか、主張が変わっていないか、 タイトルと内容が変わったり本の最後のほうで文体が変わったりするとやはりもったいないなぁという風になりますよね。 -せっかく書いたのだし細部に注意して読みやすい本にしたいという方にむけて文章が断然よくなる改善ポイントをお伝えします。すべての文章がかくあるべきという意味ではありませんが、技術書に顕著な評価軸として文章のわかりやすさがあります。これは仕事でのドキュメンテーションなどにも活きる知識ですので、ここぞとばかりに覚えておいて損はありません。 +せっかく書いたのだし細部に注意して読みやすい本にしたいという方にむけて文章が断然よくなる改善ポイントをお伝えします。 + +すべての文章がかくあるべきという意味ではありませんが、技術書に顕著な評価軸として文章のわかりやすさがあります。これは仕事でのドキュメンテーションなどにも活きる知識ですので、ここぞとばかりに覚えておいて損はありません。 細かい内容に関してはわたしたち本書の筆者であるmhidakaとvvakameが書いた技術的な文章を書くための手引も役に立つかでしょう。 @@ -86,7 +88,8 @@ 書籍のなかに、おおむね3行を超える文章があったら2つ以上の文章に分割してください。お勧めは主語と述語（動詞）の距離を短く保つことです。 -英語を勉強したときを思い出してみてください。ごく簡単な例文から学びはじめませんでしたか？This is a pen.というテキストを学んだあとにアリス・イン・ワンダーランドといった英語の古典的表現に踏み込んでいるはずです。技術書の文章も同様に、あまりに長いと読者が情報を取りこぼしやすくなります。読者は著者と同じバックグラウンドを備えているわけではありません。前提とする知識量の違いから、どの部分がわかりにくいかといった判断が難しいシーンもしばしばです。 +英語を勉強したときを思い出してみてください。ごく簡単な例文から学びはじめませんでしたか？This is a pen.というテキストを学んだあとにアリス・イン・ワンダーランドといった英語の古典的表現に踏み込んでいるはずです。技術書の文章も同様に、あまりに長いと読者が情報を取りこぼしやすくなります。読者は著者と同じバックグラウンドを備えているわけではありません。 +前提とする知識量の違いから、どの部分がわかりにくいかといった著者自身による判断が難しいシーンもしばしばです。 複数の文章に分割するコツは、正確性をコントロールすることです。「AはBである。ただしCの条件を満たすときAはDとなる」この文章は最初の1文で原則を示し、続いての文で例外を伝えています。この構造であれば誤読の要素もなく混乱しにくいですよね。伝えたい内容の重要性を加味し、順序を操ってください。 @@ -128,7 +131,7 @@ npm install -g prh-languageserver コマンドラインから使うかもしれないので@{-g}オプションでグローバルインストールにしていますが プロジェクト単位でのインストールでも問題ありません。 -Visual Studio Codeを起動し、サイドバーの上部にマーケットの検索ウインドウがあるので検索ワード「prh」と入力してExtensionsを探してください（@{vscode-prh}）。 +Visual Studio Codeを起動し、サイドバーの上部にマーケットプレースの検索ウインドウがあるので検索ワード「prh」と入力してExtensionsを探してください（@{vscode-prh}）。 //image[vscode-prh][拡張機能のprhをインストールする]{ //} diff --git a/articles/tips.re b/articles/tips.re index 7e7216f..ba20171 100644 --- a/articles/tips.re +++ b/articles/tips.re @@ -58,15 +58,17 @@ TechBoosterが推奨するディレクトリ構成を述べておきます。 == 紙面レイアウトを変更する -印刷所へ入稿する原稿を制作しているとRe:VIEWが標準で用意している構成そのものを変更する必要に迫られるときがあります。 +印刷所へ入稿する原稿を制作しているとRe:VIEWが標準で用意している標準構成に手を加える必要に迫られるときがあります。 Re:VIEWではPDFを出力するためにLaTeXを利用しています。そのため、レイアウトの変更にはLaTeXの知識が必要です。 @{config.yml}の設定値を変更したい場合@{configure|layout}を参照してください。既存のスタイルとお勧めの組み合わせを紹介しています。きっと欲しいパラメータが見つかるでしょう。 さらにRe:VIEWが出力するLaTeXソースファイルの構成を変更する拡張例としてRe:VIEWテンプレートリポジトリの内容を紹介します。 + +この独自設定の内容は、表紙および裏表紙を実寸ではなく仕上がりサイズにリサイズするというものです。なにか設定項目を追加する際のよい手本になるはずです。 + テンプレートリポジトリでは@{articles}ディレクトリの下に@{layouts/config-local.tex.erb}と@{sty/techbooster-doujin-base.sty}を置いて @{config.yml}パラメータにTechBooster独自の設定を追加しています。 -この独自設定の内容は、表紙および裏表紙を実寸ではなく仕上がりサイズにリサイズするというものです。なにか設定項目を追加する際のよい手本になるはずです。 Re:VIEWでの紙面レイアウトやデザインを自分でカスタマイズしたいと感じましたか？そんな方のために開発者ガイドラインがあります。 @@ -75,12 +77,12 @@ Re:VIEWでの紙面レイアウトやデザインを自分でカスタマイズ : Re:VIEW 3からのLaTeX処理 @{https://review-knowledge-ja.readthedocs.io/ja/latest/latex/review3-latex.html} -カスタマイズにあたってはリストや紙面の飾りといった影響範囲の小さいものから試していくと満足度が得やすいです。 -そこまで複雑なことがしたいわけじゃなくて行あたりの文字数やフォントサイズを変えたい場合@{new_layout}にはRe:VIEWの初期設定コマンド（@{review-init -w プロジェクト名}）がGUI上で取り組めて便利です。 +カスタマイズにあたってはリストや図のキャプションやヘッダといった紙面の飾りなど影響範囲の小さいものから試していくと満足度が得やすいです。 +そこまで複雑なことがしたいわけじゃないよ、行あたりの文字数やフォントサイズを変えたいんだよという場合@{new_layout}にはRe:VIEWの初期設定コマンド（@{review-init -w プロジェクト名}）がGUI上で取り組めて便利です。 //footnote[new_layout][@{https://review-knowledge-ja.readthedocs.io/ja/latest/faq/faq-tex.html#5da91055a04a506c0d01a78b804b70a3}] -== 余白を調節する +== ページの余白を調節する PDFで出力するページの余白を指定するには@{config.yml}の@{texdocumentclass}項目を調整します。 前述の@{review-init -w プロジェクト名}で調整することも可能ですが、すでにあるプロジェクトには適用できないため@{texdocumentclass}を手でコピーするなど @@ -181,8 +183,8 @@ TeXファイルの中身は自由です。ここではRe:VIEWが提供してい //} @{\includefullpagegraphics}マクロでは@{hontobira.jpg}ファイルを白ページに中心寄せで読み込んでいます。 -このとき画像ファイルは@{articles/images}ディレクトリ内に配置してください。サンプルでは@{.jpg}ファイルを使っていますがPDFファイルを指定することもできます。 -判型を合わせて作り込むとより美しく満足度が高いものが仕上がります。 +画像ファイルは@{articles/images}ディレクトリ内に配置してください。サンプルでは@{.jpg}ファイルを使っていますがPDFファイルを指定することもできます。 +判型に合わせて作り込むとより美しく満足度が高いものが仕上がります。 ===[column] レイアウトを変更する楽しみ @@ -327,9 +329,9 @@ $ review-preproc -r --tabwidth=2 sample.re #@# prh:disable //list[sample_mapoutput_after][java -version]{ #@mapoutput(java -version 2>&1) - java version "1.8.0_131" - Java(TM) SE Runtime Environment (build 1.8.0_131-b11) - Java HotSpot(TM) 64-Bit Server VM (build 25.131-b11, mixed mode) + openjdk version "11.0.15" 2022-04-19 LTS + OpenJDK Runtime Environment Zulu11.56+19-CA (build 11.0.15+10-LTS) + OpenJDK 64-Bit Server VM Zulu11.56+19-CA (build 11.0.15+10-LTS, mixed mode) #@end //} @@ -414,7 +416,7 @@ $ review-epubmaker config.yml 欲しい出力結果に応じて、コマンドを使い分けます。 PDF、EPUBについては利用するコマンドそのものが違うので注意します。 -詳細は@{publishing-book}を参照してください。 +詳細は@{setup}を参照してください。 あとはそれぞれのターゲット向けに下準備とビルドを行うタスクを作成するだけです。 @@ -469,7 +471,10 @@ TechBoosterがRe:VIEWを使っているなかで関係したお世話になっ * 表現の統一：「どうか」でのGrep → 大抵は不要。～正しいかどうか。→ 検証する * 表現の統一：箇条書き、リストや図のキャプションが体言止めなのか、動詞で終わっているのか、統一する +列挙したチェックリストをはじめての執筆で満たすのは難しいはずです。書く訓練を積むとある程度できるようになりますが一朝一夕ではありません。自分なりの基準を作ってください。 + また文章単体では、かかりつけの距離を確認し、読みやすく訂正しています。 +主語と述語の距離は近いほどわかりやすいなど分割するコツがありますのでチェックリストを使って適切な表現をみつけてください。 //list[before][変更前]{ アプリはOSの起動やタイマーによって定期的に起動されるアプリのServiceを作成し、RecommendationパッケージのContentRecommendationを使用してNotificaitonを作成することができます。 diff --git a/articles/workflow.re b/articles/workflow.re index 31d19e5..cb174b2 100644 --- a/articles/workflow.re +++ b/articles/workflow.re @@ -144,7 +144,7 @@ main branchの凍結後にmain branchを変更する権限をもつのは編集 == 執筆のための継続的インテグレーション エンジニアであればmain branchビルドが壊れることを極端に怖がると思います。正しい。 -そこでTechBoosterではCIのための仕組みをDockerとGitHub Actionsを活用して制作しました。平たくいうと常に最新のPDF出力が得られます。 +そこでTechBoosterではDockerとGitHub Actionsを活用してCIのための仕組みを制作しました。平たくいうと常に最新のPDF出力が得られます。 : Re:VIEW image for Docker @{https://hub.docker.com/r/vvakame/review/} @@ -153,7 +153,7 @@ main branchの凍結後にmain branchを変更する権限をもつのは編集 ここで重要なのは印刷を目的としたレイアウトで確認できるという点です。ソフトウェア開発でも成果物をビルドしてプロジェクトのデリバリを担保していますが、技術書の制作環境でも似ています。 -Re:VIEWはPDFだけでなくEPUBやHTMLなど各種フォーマットに対応しているので、執筆中の出力だってドラフトやHTML出力だけでいいんじゃない？と考えることもできますが、印刷が前提だと最終確認するだけで心許なく感じます。締切ギリギリにあがった原稿を編集者だけでチェックして印刷するなんて無茶は誰だってしたくありません。というわけで印刷用であったり最終レイアウトだったりのリリース向けの成果物を執筆中でも確認できるようにします。少なくとも著者がチェックできていないケースはなくなります。 +Re:VIEWはPDFだけでなくEPUBやHTMLなど各種フォーマットに対応しているので、執筆中の出力だってドラフトやHTML出力だけでいいんじゃない？と考えることもできますが、印刷が前提だと最終確認するだけでは心許なく感じます。締切ギリギリにあがった原稿を編集者だけでチェックして印刷するなんて無茶は誰だってしたくありません。というわけで印刷用であったり最終レイアウトだったりのリリース向けの成果物を執筆中でも確認できるようにします。少なくとも著者がチェックできていないケースはなくなります。 Docker上でRe:VIEWを動かすツールおよびGitHub Actionsとして実行するラッパーツールを用意して常に最新のPDF出力が得られるような運用をしています。これには多くのメリットがありますが中でも次のような点で執筆に貢献しています。 @@ -165,7 +165,6 @@ Docker上でRe:VIEWを動かすツールおよびGitHub Actionsとして実行 TechBoosterでは40人程度が執筆に関わるので全員に特定のプラットフォームを強制することはできません。戦争が起きます。CIとVisual Studio Codeと拡張機能であるvscode-language-reviewがあればローカルで文法チェックを行ってCIがビルドする形で最低限の執筆環境ができます。 またmain branchが壊れている場合もすぐに気づけるため、常にクリーンな環境を維持できます。 -エンジニアにとってビルドエラーの恐怖は説明するまでもありませんね。 レビュー期間も同様です。著者からのpushを停止させずにレビューしようと考えると、どこかにレビュー用のPDFがあることが望ましいわけです。そこで前述の仕組みが活きます。CIでは入校時と同じスタイルを利用して常に入稿形式に準じたPDFを生成しています。レビューでも紙面レイアウトでチェックすることで文字のはみ出しなど些細な問題でも素早く気づき、筆者にフィードバックを返せます。 diff --git a/articles/writing-book.re b/articles/writing-book.re index b63211b..7c72091 100644 --- a/articles/writing-book.re +++ b/articles/writing-book.re @@ -1,7 +1,7 @@ ={writing-book} 技術書を書くための要求仕様 #@# NOTE author:mhidaka -本章ではRe:VIEWを使ったエンジニアや技術書典など技術イベント出展者向けの執筆・編集スタイルを紹介します。 +本章ではエンジニアや技術書典など技術イベント出展者向けのRe:VIEWを使った執筆・編集スタイルを紹介します。 自然言語による文章もプログラムを書くのと大差ないな！と感じていただければ幸いです。 == Re:VIEWとは @@ -14,7 +14,7 @@ しかしRe:VIEWを使えば、これまでよりずっと手軽に技術書を作ることができます。 本を作る工程を@{review-cover}に示します。 -//image[review-cover][Re:VIEWがカバーする領域][scale=0.80]{ +//image[review-cover][Re:VIEWがカバーする領域][scale=0.75]{ //} ご覧のとおり「Re:VIEW」は「執筆」「校正」「組版」「製版」までと、非常に幅広い範囲をサポートします。 @@ -90,7 +90,7 @@ Re:VIEWでは本文をプレーンテキストファイルで執筆するのでG Re:VIEWはHTMLやPDF、EPUBやMarkdownといった主要な形式への変換にも対応しています。 さらに文書の構造と見た目が十分に分離されているので、原稿ができてから見た目を調整できます。 -そしてRe:VIEWは、出版を生業としている方々が作っているので「本を書くための工夫」がたくさん詰まっています。 +そして出版を生業としている方々が作っているので「本を書くための工夫」がたくさん詰まっています。 日本人が作っているツールだけあって、日本語固有の事情も考慮されています。そして今まで数多くの本の制作に使われてきた実績@{archievement}があり、商業誌と同じクオリティを確保しています。そうそう落とし穴に落ちたりすることもありません。 わたしたちはRe:VIEWを使うだけで、先人たちの知恵を活用できるのです。 @@ -117,10 +117,10 @@ Re:VIEWは優れた書籍制作ツールですが、そのままでは入稿で 同人誌制作がはじめてという場合はテンプレートリポジトリからのCloneを@{強く推奨}します。 このリポジトリでは、B5（JIS）サイズでノンブルを追加した専用レイアウトを使用しています。 -印刷所である日光企画さん・ねこのしっぽさんに入稿できる、多数の利用実績があるテンプレートリポジトリです。はじめての執筆で利用するにはうってつけです。出力方法は後述の章で解説します。 +印刷所である日光企画さん・ねこのしっぽさんに入稿できる、多数の利用実績があるテンプレートリポジトリです。はじめての執筆で利用するにはうってつけです。 しかしながらすべての印刷所で大丈夫とは限りません。印刷所ごとに入稿ルールは異なります。 -入稿に先立って印刷所のスタッフが確認できるサンプルファイルを用意し、印刷所の指示にしたがって入稿データを作成してください。 +入稿に先立って印刷所のスタッフが確認できるサンプルファイルを用意し、印刷所の指示にしたがって入稿データを作成してください。出力方法は後述の章で解説します。 大抵の印刷所は初心者に対して十分に優しく、トライアンドエラーで一緒に先に進む手伝いをしてくれるでしょう。 印刷所が変わる場合は、きっとカスタマイズが必要です。そのための雛形として活用してください。