diff --git a/articles/configure.re b/articles/configure.re index b832b20..955c738 100644 --- a/articles/configure.re +++ b/articles/configure.re @@ -40,7 +40,7 @@ POSTDEF: 後書きを指定します 加えて@{CHAPS}はネストすることで部を構成できます。 -部を構成するには、@{catalog_yml_nested_chaps}のように、部のタイトル名や.reファイル名の下に章のファイルを記述します。 +部を構成するには、@{catalog_yml_nested_chaps}のように、部のタイトル名や@{.re}ファイル名の下に章のファイルを記述します。 //list[catalog_yml_nested_chaps][部を構成するCHAPSの記述]{ CHAPS: @@ -53,7 +53,7 @@ CHAPS: - chapter5.re //} -YAMLに馴染みがないと忘れがちですがCollection@{url_yaml_collection}にするのでコロン記号（：）を付け忘れないようにしましょう。 +YAMLの記法に馴染みがないと忘れがちですがCollection@{url_yaml_collection}にするのでコロン記号（：）を付け忘れないようにしましょう。 //footnote[url_yaml_collection][@{http://www.yaml.org/spec/1.2/spec.html#id2759963}] @@ -67,9 +67,9 @@ Re:VIEWでは本を生成（コンパイル）するときのメタデータ ファイル名に決まりはありませんが慣例的に@{config.yml}としています。 書名や奥付の内容、どの深さまで目次に含めるかなどを設定できます。 -@{config_yml}は本書で使っている@{config.yml}です。 +@{config_yml}は本書で使っている@{config.yml}の一部を抜粋したものです。 -//list[config_yml][config.yml]{ +//list[config_yml][config.ymlの中身]{ # ブック名(ファイル名になるもの。ASCII範囲の文字を使用) bookname: C89-FirstStepReVIEW-v2 # 記述言語。省略した場合はja @@ -86,11 +86,13 @@ pbl: TechBooster # 刊行日(省略した場合は実行時の日付) date: 2023-10-31 + # 発行年月。YYYY-MM-DD形式による配列指定。省略した場合はdateを使用する # 複数指定する場合は次のように記述する # [["初版第1刷の日付", "初版第2刷の日付"], ["第2版第1刷の日付"]] # 日付の後ろを空白文字で区切り、任意の文字列を置くことも可能。 history: [["2015-12-31 C89版 v1.0.0"],["2017-8-11 C92版 v2.0.0"],["2023-10-31 技術書典15版 v3.0.0"]] + # 権利表記(配列で複数指定可) # rights: (C) 2016 Re:VIEW Developers rights: (C) 2017-2023 TechBooster @@ -128,7 +130,7 @@ colophon: true == 目次に表示する項目をカスタマイズする -目次として抽出する章や節の深さを変更するには、@{config.yml}の@{toclevel:}項目を設定します（@{toclevel}）。 +目次として抽出する章や節の深さを変更するには、@{config.yml}の@{toclevel}項目を設定します（@{toclevel}）。 //list[toclevel][抽出レベルを設定]{ toclevel: 2 @@ -144,7 +146,7 @@ toclevel: 2 =={layout} 用紙サイズやデザインを変更する -PDF形式で出力する紙面のデザインは差し替え可能です。@{config.yml}の@{texstyle:}項目の値を変更します（@{change_layout}）。 +PDF形式で出力する紙面のデザインは差し替え可能です。@{config.yml}の@{texstyle}項目の値を変更します（@{change_layout}）。 //list[change_layout][config.ymlにてスタイルファイルを指定]{ # LaTeX用のスタイルファイル(styディレクトリ以下に置くこと) @@ -152,11 +154,11 @@ PDF形式で出力する紙面のデザインは差し替え可能です。@ //} : reviewmacro - Re:VIEWのデフォルトスタイルです。 + Re:VIEWのデフォルトスタイルです : viewermacro - 電子書籍向けのスタイルです。タブレットなどで見やすいように余白やフォントサイズを調整しています。TechBooster製のスタイルです。 + 電子書籍向けのスタイルです。タブレットなどで見やすいように余白やフォントサイズを調整しています。TechBooster製のスタイルです -ReVIEW-Templateテンプレートリポジトリまたは本書のリポジトリには次の4つの@{texdocumentclass:}が用意されています。 +ReVIEW-Templateテンプレートリポジトリまたは本書のリポジトリには次の4つの@{texdocumentclass}が用意されています。 * B5の設定(10pt 40文字×35行) - 紙版 * B5の設定(10pt 40文字×35行) - 電子版 @@ -168,8 +170,8 @@ ReVIEW-Templateテンプレートリポジトリまたは本書のリポジト //emlist[config.ymlの印刷用設定]{ texstyle: ["reviewmacro"] texdocumentclass: ["review-jsbook", "media=print,paper=b5,serial_pagination=true, - hiddenfolio=nikko-pc,openany,fontsize=10pt,baselineskip=15.4pt,line_length=40zw, - number_of_lines=35,head_space=30mm,headsep=10mm,headheight=5mm,footskip=10mm"] + hiddenfolio=nikko-pc,openany,fontsize=10pt,baselineskip=15.4pt,line_length=40zw, + number_of_lines=35,head_space=30mm,headsep=10mm,headheight=5mm,footskip=10mm"] //} ==== 電子書籍（PDF）での標準設定 @@ -177,16 +179,16 @@ texdocumentclass: ["review-jsbook", "media=print,paper=b5,serial_pagination=true //emlist[config.ymlの電子書籍用設定]{ texstyle: ["reviewmacro"] texdocumentclass: ["review-jsbook", "media=ebook,paper=b5,serial_pagination=true, - openany,fontsize=10pt,baselineskip=15.4pt,line_length=40zw, - number_of_lines=35,head_space=30mm,headsep=10mm,headheight=5mm,footskip=10mm"] + openany,fontsize=10pt,baselineskip=15.4pt,line_length=40zw, + number_of_lines=35,head_space=30mm,headsep=10mm,headheight=5mm,footskip=10mm"] //} -B5ではなく少し小さいA5にしたい等で書籍にあった用紙サイズへ変更するだけであれば、これらのプリセットの利用を強く推奨します。 +B5ではなく少し小さいA5にしたいなど書籍に合う用紙サイズへ変更するのであれば、これらのプリセットの利用を強く推奨します。 == スタイルにカスタマイズを加える @{config.yml}の@{textdocumentclass}はLaTeXにおけるドキュメントのクラスオプションに相当します。 -複数のオプションがある場合は、カンマで区切って列挙でき、ある程度のカスタマイズも可能です。 +複数のオプションがある場合はカンマで区切って列挙でき、ある程度のカスタマイズも可能です。 前節で触れた標準設定でも多くのクラスオプションが登場していました。たとえば出力するページサイズを指定するには@{config.yml}の@{textdocumentclass}を次のようにします（@{change_pagesize}）。 @@ -209,11 +211,12 @@ b6 JIS B6 === review-jsbookに設定できる主な設定項目 -@{review-jsbook}に設定可能なクラスオプションは公式ドキュメントにまとまっています。@{review-jsbook}では、 -どのようなカスタマイズができるのか理解しやすいものを挙げています。 +@{review-jsbook}に設定可能なクラスオプションは公式ドキュメントにまとまっています。 * @{https://github.com/kmuto/review/blob/master/templates/latex/review-jsbook/README.md} +@
{review-jsbook}では、どのようなカスタマイズができるのか理解しやすいものを挙げています。 + //table[review-jsbook][設定できる主なクラスオプションと説明]{ オプション名 説明 ------------ @@ -225,7 +228,7 @@ startpage ページ開始番号。デフォルトは1 //} Re:VIEWで利用している@{review-jsbook}はドキュメントクラスは標準的な@{jsbook}ドキュメントクラスを含んでいるので、一部のオプションはそのまま指定できます。 -たとえば@{onecolumn}であれば1段組の体裁、@{twocolumn}であれば2段組の体裁を実現します。 +ここに@{onecolumn}を指定すれば1段組の体裁、@{twocolumn}であれば2段組の体裁を実現します。 ただし、このようなドキュメントの見た目に対して調整を行うにはTeXと書籍の専門知識が要求されます。 たとえば本のルールには章の始まりを左ページ（偶数）、右ページ（奇数）に固定できるというものがあります。一般人からすると改ページの位置が左右どっちにくるのかという問題自体に馴染みがありませんよね。@{openany}を指定すると左右どちらからでも章を開始できる！と気づいてしまい、ページ数を減らせるから印刷代もちょっと安くなるじゃないか？と考えたとしても入稿直前の疲れたタイミングで変更することは推奨しません。期せず発生する副作用に悩まないように十分検証期間を設けるなど余裕を持って作業してください。 diff --git a/articles/images/tips/how_to_convert_re_to_pdf.png b/articles/images/tips/how_to_convert_re_to_pdf.png deleted file mode 100644 index af39d58..0000000 Binary files a/articles/images/tips/how_to_convert_re_to_pdf.png and /dev/null differ diff --git a/articles/images/tips/how_to_convert_re_to_pdf2.png b/articles/images/tips/how_to_convert_re_to_pdf2.png deleted file mode 100644 index e8d5590..0000000 Binary files a/articles/images/tips/how_to_convert_re_to_pdf2.png and /dev/null differ diff --git a/articles/review-introduction.re b/articles/review-introduction.re index 2871ee3..f1426be 100644 --- a/articles/review-introduction.re +++ b/articles/review-introduction.re @@ -180,10 +180,13 @@ Re:VIEWにはリストや図版の採番を自動的にするための仕組み このリストは参照されています。 //} +＠{@{identifier}}で、@{identifier,識別子}が示すリストを参照できます。 +参照は、出力時に「@{list_refs}」のようにリスト番号に置き換わります。 + 連番つきリストにするとRe:VIEWは、リストごとに一意な番号を割り振ります。 一方、連番なしリストは、リストに番号を割り当てず、本文からは参照できません。 -一般的にソースコードリストのように本文から参照する場合には、連番付きリスト（@{list}）を推奨します。 +一般的にソースコードリストなどを本文から参照したい場合には、連番付きリスト（@{list}）を推奨します。 参照関係が明らかな場合のみ、連番なしリスト（@{emlist}）を利用するといいでしょう。 @@ -445,7 +448,6 @@ PNG、JPEG、@{SVG,Scalable Vector Graphics}など、基本的なフォー 罫線で区切られた表をマークアップする構文です。 Re:VIEWでは、行は改行、セルとセルの間にはタブで区切ります。 - 空白のセルは、ピリオド（@{.}）を入力します。 セルにピリオドを表示したい、またはセルの内容をピリオドから始めたい場合、ピリオドを２つ続けて（@{..}）入力します。 @@ -488,7 +490,6 @@ Re:VIEWでは、行は改行、セルとセルの間にはタブで区切りま #@# //footnote[not_reffered_footnote][参照されない脚注は表示されません] 脚注は、記述した場所に関係なく「脚注の領域」に表示されます。 - 脚注を有効にするには、本文で参照している必要があります。本文で参照されていない脚注は出力されません。 @{footnote_refer_sample}では、記述した脚注を参照しています。 @@ -519,7 +520,6 @@ Re:VIEWでは、行は改行、セルとセルの間にはタブで区切りま //} このように、リード文としてマークアップした内容は、本文に比べて左側の余白が大きくなります。 - Re:VIEWでは、リード文のマークアップは文章のどこにでも置けます。 しかし、基本的には見出し、特に章見出しのすぐあとに置くことを想定しています。 @@ -528,7 +528,6 @@ Re:VIEWでは、リード文のマークアップは文章のどこにでも置 Re:VIEW記法では文字を装飾できます。 文字の装飾は適用したい範囲を@{＠<修飾子>{...}}で指定するだけです。 - また文字の装飾は、本文だけでなくリストや脚注、表などの中でも有効です。 利用頻度の高い文字の装飾について@
{character_decorations}にまとめています。 @@ -552,10 +551,10 @@ Re:VIEW記法では文字を装飾できます。 == 参照 -他の見出しを参照し、文章中で利用できます。 +ほかの見出しを参照し、文章中で利用できます。 参照を使わず、見出しのキャプションや番号を直接記述した場合、変更が発生するたび関連箇所を漏れなく探し出し、すべてに修正を加えなくてはなりません。 -見出しの参照を使うと、章や節の順番の入れ替え、タイトルの変更などは自動的に反映されます。 +見出しの参照を使うと章や節の順番の入れ替え、タイトルの変更などは自動的に反映されます。 見出しの参照は、大きく「章の参照」と「節の参照」の２つに分類できます。 === 章の参照 @@ -579,9 +578,8 @@ Re:VIEW記法では文字を装飾できます。 @{chapref}は、その章の見出し番号とキャプションになります（@{writing-book}）。 これらの構文の参照先には、Re:VIEWの章の識別子を指定します。 - 章の識別子は、Re:VIEWの章のファイル名から拡張子@{.re}を取り除いた名前です。 -たとえば、@{writing-book.re}の章を参照する場合、@{writing-book}が識別子になります。 +たとえば@{writing-book.re}の章を参照する場合は@{writing-book}が識別子になります。 === 節の参照 @@ -593,18 +591,15 @@ Re:VIEW記法では文字を装飾できます。 ＠{writing-book|Re:VIEWの特色} //} -同じ章の節を参照する場合、参照先には、節のキャプションだけを記載します。 - -異なる章の見出しを参照する場合、章の識別子を指定した上で、縦棒@{|}で区切って節のキャプションを記述します。 +同じ章の中にある節を参照する場合、参照先には節のキャプションだけを記載します。 -章の識別子は、Re:VIEWの章のファイル名から拡張子@{.re}を取り除いた名前です。 -たとえば、@{writing-book.re}の章を参照する場合、@{writing-book}が識別子になります。 +異なる章の見出しを参照する場合、先述した章の識別子を指定した上で縦棒@{|}で区切って節のキャプションを記述します。 === 見出しラベル 節の参照では、見出しのキャプションをそのまま記述するので、キャプションを変更したときに参照を更新する必要があります。 -Re:VIEWでは、見出しキャプションとは別に、参照用のラベルを指定できます。 +Re:VIEWでは、見出しキャプションとは別に参照用のラベルを指定できます。 //list[section_label][見出しの参照用ラベル]{ =={commandline} コマンドライン @@ -638,9 +633,8 @@ Re:VIEW記法は「ブロック命令」と「インライン命令」の２つ //} ブロック命令には複数のオプションを指定できる場合があります。 -オプションは、命令に続けて括弧[]の中に記述します（@{block_directive_with_option}）。 - 指定可能なオプションの数や省略の可否は、命令によって違います。 +オプションは、命令に続けて括弧[]の中に記述します（@{block_directive_with_option}）。 //list[block_directive_with_option][ブロック命令]{ //命令[オプション1][オプション2][オプション3]{ @@ -650,8 +644,8 @@ Re:VIEW記法は「ブロック命令」と「インライン命令」の２つ ブロック命令はリストや図など本文とは独立した内容を掲載する際に使います。 -ブロック命令を文の途中から開始することはできません。ブロック命令の開始と終了は、必ず行頭に記述します。 -行頭に半角スペースなどが入った場合、Re:VIEWは、その行をブロック命令として扱いません。 +ブロック命令を文の途中から開始することはできず、ブロック命令の開始と終了は必ず行頭に記述します。 +行頭に半角スペースなどが入った場合Re:VIEWは、その行をブロック命令として扱いません。 ==== インライン命令 @@ -659,6 +653,6 @@ Re:VIEW記法は「ブロック命令」と「インライン命令」の２つ 続く括弧{}の中が、インライン命令の効果が及ぶ範囲になります。 インライン命令は、文章の装飾やリストや図の参照など表示や内容に影響します。 -文中に直接記入することができますが、改行をまたぐことやインライン命令のネストはできません。 +文中に直接記入できますが、改行をまたぐことやインライン命令のネストはできません。 ==[/column] diff --git a/articles/setup.re b/articles/setup.re index 740ac67..e8d37b2 100644 --- a/articles/setup.re +++ b/articles/setup.re @@ -1,11 +1,10 @@ ={setup} Re:VIEWでの執筆環境を整える - #@# NOTE author:mhidaka 本章ではRe:VIEWで執筆するための環境を整えます。 - TechBoosterの著者陣は、もれなく全員がRe:VIEW記法で執筆するスタイルです。 慣れないうちはエラーに遭遇したり、やり方に迷ったりしているので、CI/CD環境があってこそ運用できているといえます。 + Re:VIEW記法は、馴染みがないものなので覚えるのはちょっと面倒ですね。書籍作りを支えるものなので表現したい内容を優先し、手を動かしながら学びノウハウを貯めてください。 2023年11月現在では、Microsoftが開発提供するエディタVisual Studio Codeと@{Extensions,拡張機能}のvscode-language-reviewを利用することが一般的です。 @@ -36,7 +35,7 @@ Visual Studio Codeをダウンロードしてインストールします。Visua //} 画面のインストールボタンを押せば完了です。 -vscode-language-reviewは、Visual Studio Code上で、Re:VIEW記法を使いやすくする便利な拡張機能を持っています。 +vscode-language-reviewは、Visual Studio Code上で、Re:VIEW記法を使いやすくする便利な拡張機能を提供します。 * Liveプレビュー * シンタックスハイライト @@ -67,7 +66,7 @@ LiveプレビューでエラーチェックしてGitHubのリポジトリにpush =={install_review} Re:VIEW image for Dockerのセットアップ Docker上でRe:VIEWを動かすための手順を解説します。Dockerはコンテナ型仮想化技術のプラットフォームです。 -Re:VIEW image for Dockerは最新のRe:VIEWをどの環境でも安定して使えるコンテナイメージで、vvakameが公開、メンテナンスしています。 +Re:VIEW image for Dockerは最新のRe:VIEWをどの環境でも安定して使えるコンテナイメージで、vvakameが公開とメンテナンスをしています。 本書執筆時点での検証済みのバージョンは次のとおりです。 @@ -77,16 +76,16 @@ Re:VIEW image for Dockerは最新のRe:VIEWをどの環境でも安定して使 * Docker Desktop Version 4.25.0 (126437) Re:VIEWツールそのものはRuby言語で書かれており、macOS、Windows、LinuxどのOSでも動作します。 -ただしRubyのバージョンやPDFを出力するLaTeXを構築する手順がプラットフォームごとに微妙に異なるので、 -Re:VIEWの環境構築でトラブルに遭遇した場合の解決は困難を極めました。 +ただしRubyのバージョンやPDFを出力するLaTeXを構築する手順はプラットフォームごとに微妙に異なるので、 +Re:VIEWの環境構築でトラブルに遭遇した場合に解決は困難を極めます。 Re:VIEWの環境を仮想化できたことで現在は多くの書籍がRe:VIEW image for Dockerを使って作られています。 -Docker Desktopを次のURLからダウンロードしてインストールします。 +導入には、まずDocker Desktopを次のURLからダウンロードしてインストールします。 * @{https://www.docker.com/} -Windowsの場合の手順は次のURLで詳しく触れられています。 +Windowsでの手順は次のURLで詳しく触れられています。 * @{https://github.com/vvakame/docker-review/blob/master/doc/windows-review.md} @@ -94,15 +93,13 @@ Windowsの場合の手順は次のURLで詳しく触れられています。 //footnote[docker-faq][@{https://matsuand.github.io/docs.docker.jp.onthefly/desktop/faqs/#do-i-need-to-pay-to-use-docker-desktop}] -Dockerのインストールが完了したあとはRe:VIEW image for Dockerをダウンロードします。 +Dockerのインストールが完了したあとはRe:VIEW image for Dockerをダウンロードします。コマンドラインに次のとおり入力してください。 //cmd{ docker pull vvakame/review:5.8 //} -コマンドは@{5.8}を指定しています。Re:VIEW image for DockerでサポートしているRe:VIEWは5.3〜5.8です。 - - * @{https://github.com/vvakame/docker-review} +コマンドではタグに@{5.8}を指定しています。Re:VIEW image for DockerでサポートしているRe:VIEWは5.3〜5.8です。 ===[column] 取得済みイメージの確認方法 @@ -120,6 +117,10 @@ vvakame/review 5.8 5cb030602a81 4 months ago 3.28GB //} 書籍制作環境を全部含んでいるのでイメージサイズが3GB超と大きめです。 +Dockerイメージは次のリポジトリで公開しています。インストールされているコマンドや初期設定を確認したい場合にアクセスしてください。 + + * @{https://github.com/vvakame/docker-review} + ===[/column] @@ -128,7 +129,7 @@ vvakame/review 5.8 5cb030602a81 4 months ago 3.28GB Docker経由でのPDF出力を試しましょう。 前節で少し触れましたがRe:VIEWでPDFに変換するにはLaTeX（platexまたはlualatexなど）を使います。 -Re:VIEW image for Docker内部のワークフローは@{.re}ファイルを含んだプロジェクトからRe:VIEWツールを実行し、出力対象がPDFファイルなのであればLaTeX形式に変換、TeXLive実行し、PDFファイルをローカルマシンにコピーして完了という流れです。 +Re:VIEW image for Docker内部のワークフローは@{.re}ファイルを含んだプロジェクトからRe:VIEWツールを実行し、出力対象がPDFファイルであればLaTeX形式に変換、TeXLiveを実行して生成したPDFファイルをローカルマシンにコピーして完了という流れです。 TechBoosterが提供しているReVIEW-templateリポジトリをベースに執筆している場合のPDF出力から説明します。 @@ -144,14 +145,14 @@ yourbook_dir % ./build-in-docker.sh //} //cmd{ -yourbook_dir/articles/yourbookname.pdf +yourbook_dir/articles/bookname.pdf //} 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} @@ -191,13 +192,14 @@ Re:VIEW image for Docker登場以前はフォントのセットアップだけ ローカル環境の構築ドキュメントとPDFを出力する@{review-pdfmaker}、EPUBを出力する@{review-epubmaker}、Webページを出力する@{review-webmaker}に触れますが 入稿に利用する形式は@{review-pdfmaker}コマンドでのPDF形式です。 -本書ではDocker経由の利用を推奨していること、ローカル環境での構築でトラブルが起きると解決が大変なことの2点を鑑みて各OSでのインストール手順を丁寧に記述することを意図的に避けています。 +わたしたちはDocker経由の利用を推奨していること、ローカル環境での構築でトラブルが起きると解決が大変なことの2点を鑑みて各OSでのインストール手順の解説を避ける構成を採っています。 + しかしローカル環境があると色々な試行錯誤、とくにレイアウト調整やデバッグなどに便利ですので試したい読者のためにポインタを示します。 -TechBoosterでは編集者は手元の環境で確認するようにしています。ページ数の調整や記法の修正、図表の見栄で頻繁なPDF再出力を行うためです。 +TechBoosterでは編集者は手元の環境でPDFファイルを確認しています。これはページ数の調整や記法の修正、図表の見栄で頻繁なPDF再出力を行うためです。 === ローカル環境の構築 -RubyのインストールおよびPDF出力を目的とするならTeXLive 2023を導入してください。OSごとのインストール手順は次のドキュメントを参照して実施してください。 +Re:VIEWを使うにはRubyのインストールおよびTeXLive 2023を導入してください。PDF出力を目的としない場合はTeXLive 2023は不要です。OSごとのインストール手順はそれぞれのドキュメントを参照して実施してください。 * @{https://github.com/kmuto/review/blob/master/doc/quickstart.ja.md} * @{https://texwiki.texjp.org/?TeX%20Live} @@ -209,11 +211,11 @@ gem install review //} Re:VIEWの開発チームは、定期的に新しいバージョンをリリースしています。 -執筆を終えた書籍で追従する場合は変更点を確認し、レイアウトが意図せず崩れないよう互換性に気をつけてください。 +執筆中、または執筆を完了した書籍のアップデートなどでバージョンを変更する場合はチェンジログを確認し、意図せずレイアウトが崩れないよう互換性確保に気をつけてください。 === review-pdfmaker -@{review-pdfmaker}はそのプロジェクトのPDFを生成します。 +@{review-pdfmaker}はそのプロジェクトのPDFファイルを生成します。 引数としてYAMLファイル（@{config.yml}）をひとつ指定します。 //cmd{ @@ -237,20 +239,21 @@ YAMLファイルには本のタイトルや筆者名といった本のメタデ 検出しにくい見た目の問題も挙げましょう。 - * 本文中にリストとして掲載したソースコードが長すぎて紙面をはみ出している場合 - * 箇条書きのつもりで書いた「@{*}」が半角スペースを忘れていて直接本文に表示されている場合 - * 表に複数行のテキストを入れたら折返しがうまくいかず不格好になる場合 + * 本文中にリスト掲載したソースコードが長すぎて紙面をはみ出している + * 箇条書きで書いた「@{*}」の先頭に付与すべき半角スペースを忘れていて本文に直接@{*}が表示されている + * 表に複数行のテキストを入れたら折返しがうまくいかず不格好になる 装飾やレイアウトの問題についてはビルドエラーとはなりません。意図したレイアウトでPDFが出力されているかは作成者によるケアが必要です。 -最後にRe:VIEW記法を間違えたときは構文エラーが起きます。エラーが発生すると標準出力に発生時点のログが残るのでとりあえず眺めることになるでしょう。 -前述の説明のとおり、TeXの出力ログやエラーも含まれているので急に大量のログがでるので驚くことになります。 -エラーログから間違えた場所を探すのは苦労するので、沢山書いてからRe:VIEW記法に書き直せばいいやというスタンスより、ちょっとずつ取り込んでおくほうが安心です。 +なおRe:VIEW記法を間違えたときは構文エラーが起きます。エラーが発生すると標準出力に発生時点のログが残るのでとりあえず眺めることになるでしょう。 + +前述のとおり、TeXの出力ログやエラーも含まれているので大量のログが急にでて驚くかもしれませんね。 +エラーログから間違えた場所を探すのは苦労するので、たくさん書いてからRe:VIEW記法に書き直せばいいやというスタンスより、ちょっとずつ取り込んでおくほうが安心です。 テンプレートリポジトリのCIはそのために存在しています。 === review-epubmaker -@{review-pdfmaker}同様、@{review-epubmaker}はプロジェクトのメタデータとなるYAMLファイルを引数としてEPUBファイルを生成します。 +@{review-epubmaker}はプロジェクトのメタデータとなるYAMLファイルを引数としてEPUBファイルを生成します。 EPUBファイルの実態はHTMLファイルやCSSファイルをZIPでアーカイブ化したものです。 Re:VIEWはEPUBの生成処理で、システムにインストールされているZIPコマンドを使用します。 diff --git a/articles/tips.re b/articles/tips.re index 719b372..3157abe 100644 --- a/articles/tips.re +++ b/articles/tips.re @@ -12,13 +12,12 @@ TechBoosterが推奨するディレクトリ構成を述べておきます。 具体的には@{directory}です。 * リポジトリのトップレベルにはファイルをあまり散らかさない - * 複数人で執筆したときにそれぞれのファイルが混ざったり邪魔になったりしないようにする + * 複数人で執筆したときにそファイルが混ざったり邪魔になったりしないようにする * 著者全員で利用するRe:VIEWのバージョンを固定する - * ビルド手順を統一するために何らかのタスクランナーを使う（TechBoosterの場合、Node.js+npm-scripts） + * ビルド手順を統一できるタスクランナーを使う（TechBoosterの場合、Node.js+npm-scripts） //list[directory][ディレクトリ構成]{ ├── README.md - ├── circle.yml （CIサービスであるCircle CIの設定ファイル） ├── setup.sh （執筆前にgemやnpmのインストールを行うスクリプト） ├── Gemfile （bundler経由でRe:VIEWを利用するための設定ファイル） ├── Gemfile.lock （ライブラリのバージョンをロックする） @@ -51,48 +50,59 @@ TechBoosterが推奨するディレクトリ構成を述べておきます。 //} 原稿は@{articles}ディレクトリに、サンプルコードは@{code}ディレクトリに入れています。 -@{articles/images}や@{code}の中は、原稿の章ごとに.reのファイル名と同名のディレクトリを用意し、その中で活動します。 +@{articles/images}や@{code}の中は、原稿の章ごとに@{.re}ファイル名と同名のディレクトリを用意し、その中で活動します。 原稿のファイル名は、わかりやすいのが一番！ということで複数名で執筆する場合、筆者の名前にしてしまう場合があります。 -@{vvakame.re}というファイル名にしてしまえば、レビューを行ったりビルドエラーなどの問題が発生したとき連絡する人がわかりやすい。 -という発想です。 +@{vvakame.re}というファイル名にしてしまえば、レビューを行ったりビルドエラーが出ていたりと問題が発生したとき連絡する人がわかりやすいという発想です。 == 紙面レイアウトを変更する -印刷所へ入稿する原稿を制作していると、Re:VIEWが標準で用意している構成そのものを変更する必要に迫られるときがあります。 +印刷所へ入稿する原稿を制作しているとRe:VIEWが標準で用意している構成そのものを変更する必要に迫られるときがあります。 Re:VIEWではPDFを出力するためにLaTeXを利用しています。そのため、レイアウトの変更にはLaTeXの知識が必要です。 @{config.yml}の設定値を変更したい場合@{configure|layout}を参照してください。既存のスタイルとお勧めの組み合わせを紹介しています。きっと欲しいパラメータが見つかるでしょう。 -具体的には.ymlや.cssを配置しているディレクトリの下に@{layouts/layout.tex.erb}を置くことで -Re:VIEWが出力するLaTeXソースファイルの構成を変更できます。 +さらにRe:VIEWが出力するLaTeXソースファイルの構成を変更する拡張例としてRe:VIEWテンプレートリポジトリの内容を紹介します。 +テンプレートリポジトリでは@{articles}ディレクトリの下に@{layouts/config-local.tex.erb}と@{sty/techbooster-doujin-base.sty}を置いて +@{config.yml}パラメータにTechBooster独自の設定を追加しています。 +この独自設定の内容は、表紙および裏表紙を実寸ではなく仕上がりサイズにリサイズするというものです。なにか設定項目を追加する際のよい手本になるはずです。 -Re:VIEWは@{https://github.com/kmuto/review}の@{templates/latex/layout.tex.erb}を、 -LaTeXのソースファイルのテンプレートとして読み込みますが、@{layouts/layout.tex.erb}がある場合、そちらを優先して適用します（@{how_to_convert_re_to_pdf2}）。 +Re:VIEWでの紙面レイアウトやデザインを自分でカスタマイズしたいと感じましたか？そんな方のために開発者ガイドラインがあります。 -//image[how_to_convert_re_to_pdf2][layout.tex.erbの取り扱い]{ -//} + : review-jsbook.clsの基本版面設計 + @{https://review-knowledge-ja.readthedocs.io/ja/latest/latex/paper-layout.html} + : Re:VIEW 3からのLaTeX処理 + @{https://review-knowledge-ja.readthedocs.io/ja/latest/latex/review3-latex.html} + +カスタマイズにあたってはリストや紙面の飾りといった影響範囲の小さいものから試していくと満足度が得やすいです。 +そこまで複雑なことがしたいわけじゃなくて行あたりの文字数やフォントサイズを変えたい場合@{new_layout}にはRe:VIEWの初期設定コマンド@{review-init -w プロジェクト名}がGUI上で取り組めて便利です。 -カスタマイズに当たっては、@{templates/latex/layout.tex.erb}を@{layouts/layout.tex.erb}にコピーして変更するとよいでしょう。 +//footnote[new_layout][@{https://review-knowledge-ja.readthedocs.io/ja/latest/faq/faq-tex.html#5da91055a04a506c0d01a78b804b70a3}] == 余白を調節する -PDFで出力するページの余白を指定するには、.styファイルに@{\geometry}を設定します（@{set_margin}）。 +PDFで出力するページの余白を指定するには@{config.yml}の@{texdocumentclass}項目を調整します。 +前述の@{review-init -w プロジェクト名}で調整することも可能ですが、既にあるプロジェクトには適用できないため@{texdocumentclass}を手でコピーするなど +ひと工夫してください。 -//list[set_margin][余白を設定]{ -\geometry{top=18mm,bottom=23mm,left=24mm,right=24mm} +//emlist[config.ymlでの余白設定]{ +texstyle: ["reviewmacro"] +texdocumentclass: ["review-jsbook", "media=print,paper=b5,serial_pagination=true, + hiddenfolio=nikko-pc,openany,fontsize=10pt,baselineskip=15.4pt,line_length=40zw, + number_of_lines=35,head_space=30mm,headsep=10mm,headheight=5mm,footskip=10mm"] //} -指定できる単位は、@{cm}、@{mm}の他にもLaTeXでサポートされている@{in}、@{pt}、@{em/ex}、@{zw/zh}、@{Q}などがあります。 - +リストはテンプレートリポジトリの標準設定です。@{head_space=30mm}は上部（天）の余白が30mmと設定しています。 +ここで指定できる単位は@{cm}、@{mm}の他にもLaTeXでサポートされている@{in}、@{pt}、@{em/ex}、@{zw/zh}、@{Q}などがあります。 ===[column] レイアウトを変更する楽しみ -ヘッダやフッタを変えたい、ノンブルを隠したい（隠しノンブルと呼びます）など紙面に凝ってくるとレイアウトへの要望がでてきます。紙面作りを楽しんでいる証拠ともいえるでしょう。 +ヘッダやフッタを変えたい、ノンブルを隠したい（隠しノンブルと呼びます）、コードハイライトがついたもっとイケているリスト表示にしたいなど +紙面に凝ってくるとレイアウトへの要望がでてきます。紙面作りを楽しんでいる証拠ともいえるでしょう。 -Re:VIEWではPDF出力を得るためにLaTeXを利用しています。そのためレイアウトに関する部分の多くはLaTeXの知識を必要とします。 -自由度が高い一方、独特の記法への馴染みの薄さやパッケージ、環境の依存関係などカスタマイズが困難なため、入門を目的とする本書では触れていません。 +Re:VIEWでのレイアウトに関する部分の多くはLaTeXの知識を必要とします。 +自由度が高い一方、独特の記法への馴染みの薄さやパッケージ、環境の依存関係などカスタマイズが困難なため入門を目的とする本書では触れていません。 そんなあなたには、奥村晴彦氏の「LATEX2e 美文書作成入門」@{book_latex2e}がお勧めです。 深淵を覗けますよ！ @@ -110,8 +120,8 @@ Re:VIEWではPDF出力を得るためにLaTeXを利用しています。その == プリプロセッサ命令 -Re:VIEWでは、最終的な見た目に影響する記法とは別に、外部の情報を.reファイルに反映する「プリプロセッサ命令」があります。 -プリプロセッサ命令を使うことで、外部ファイルとしているサンプルコードを自動で.reファイル内に反映できます。 +Re:VIEWでは最終的な見た目に影響する記法とは別に、外部の情報を@{.re}ファイルに反映する@{プリプロセッサ命令}があります。 +プリプロセッサ命令を使うことで、外部ファイルとしているサンプルコードを自動で@{.re}ファイル内に反映できます。 プリプロセッサ命令を処理するには@{review-preproc}コマンド@{preproc-doc}を使用します。 @{review-preproc}コマンドは、PDFのビルド時に自動で実行するようにしておくと便利です。 @@ -119,8 +129,8 @@ Re:VIEWでは、最終的な見た目に影響する記法とは別に、外部 //footnote[preproc-doc][@{https://github.com/kmuto/review/blob/master/doc/preproc.ja.md}] -プリプロセッサ命令は、あくまで.reファイルの一部を書き換えるだけです。 -最終的に.reファイルの内容がビルドされることに変わりはありません。 +プリプロセッサ命令は、あくまで@{.re}ファイルの一部を書き換えるだけです。 +最終的に@{.re}ファイルの内容がビルドされることに変わりはありません。 === ファイルの内容を読み込む @@ -211,17 +221,17 @@ $ review-preproc -r --tabwidth=2 sample.re === 外部コマンドの結果を読み込む @{mapoutput}命令は、外部コマンドの結果を読み込みます。 -この命令はRe:VIEWの記法の枠内に囚われず、任意の処理の結果を.reファイルに埋め込めます。 +この命令はRe:VIEWの記法の枠内に囚われず、任意の処理の結果を@{.re}ファイルに埋め込めます。 しかし、あくまでコンパイルするマシンにインストールしているコマンドを使用するため、複数人で執筆する場合は注意が必要です。 -たとえば、筆者の環境のjavaのバージョンを自動で埋め込む場合は@{sample_mapoutput_before}のように記述します。 +たとえば、筆者の環境のJavaバージョンを自動で埋め込む場合は@{sample_mapoutput_before}のように記述します。 //list[sample_mapoutput_before][java -version]{ #@mapoutput(java -version 2>&1) #@end //} -@{sample_mapoutput_before}は、コンパイル後に@{sample_mapoutput_after}のようになります。 +@{sample_mapoutput_before}はコンパイル後に@{sample_mapoutput_after}のようになります。 //list[sample_mapoutput_after][java -version]{ #@mapoutput(java -version 2>&1) @@ -238,10 +248,13 @@ $ review-preproc -r --tabwidth=2 sample.re 複数人で執筆する場合、何らかの統一された手順でのビルド手順が必要です。 TechBoosterではNode.js+npm-scripts（裏はgrunt）を利用しています。 -この構成になっているのは、プロジェクト構成を主に行っているvvakameが一番使い慣れているから、という理由が大きいです。 +この構成になっているのは、プロジェクト構成を担当しているvvakameが一番使い慣れているからという理由が大きいです。 新規に書き起こすのであれば、執筆者があまり導入の手間をかけなくてもよいものを選ぶのがよいでしょう。 -候補としては、RubyはRe:VIEWのためにすでに入っているはずなのでRuby上で動作するrakeを使うか、色々なOS・環境で導入済みである場合の多いJavaと、gradle@{why-gradle}の組み合わせがよいかもしれません。 +候補としては、RubyはRe:VIEWのためにすでに入っているはずなのでRuby上で動作するrakeを使うか、いろいろなOSや環境で導入済みである場合の多いJavaやGradle@{why-gradle}の組み合わせがよいかもしれません。 + +//footnote[why-gradle][GradleにはGradle Wrapperという仕組みがあり、Gradleの実行環境を別途用意する必要がないため便利] + タスクランナーが行うべき作業は少ないです。 @@ -249,9 +262,7 @@ TechBoosterではNode.js+npm-scripts（裏はgrunt）を利用しています。 * @{review-preproc}コマンドを実行する * 各ターゲット向けのビルド用コマンドを実行する -これだけです。 - -ひとつひとつ、どういうコマンドと等価な処理をしていけばよいかを解説します。 +これだけです。ひとつひとつ、どういうコマンドと等価な処理をしていけばよいかを解説します。 * 古い生成ファイルを消す（消さないとエラーになる場合がある） @@ -268,7 +279,7 @@ rm -rf articles/C89-FirstStepReVIEW-v2-pdf/ \ #@# prh:disable それぞれ@{--debug}オプション付きでpdfをビルドしたときのtmpディレクトリ、pdf、epub、html、idgxml（Adobe InDesign用XML）、text生成時に作成される一時ファイルまたは最終出力ファイルです。 -一番最初の行のC89-FirstStepReVIEW-v2-pdf部分はarticles/config.ymlのbooknameの設定により変化します。 +一番最初の行のC89-FirstStepReVIEW-v2-pdf部分は@{articles/config.yml}の@{bookname}の設定により変化します。 * @{review-preproc}コマンドを実行する @@ -283,8 +294,8 @@ $ review-preproc -r --tabwidth=2 *.re @{review-preproc}コマンドは文書中に埋め込まれたpragmaを処理し、サンプルコードを文書中に展開したり指定のコマンドの実行結果を文書中に展開してくれます。 C言語のマクロとだいたい同じものだと思えばよいでしょう。 -文書にソースコードを貼りこむとき、インデントは2スペースとします。 -このため、4スペース派の人はサンプルコードではタブを使うようにして、エディタ上では1タブ＝4スペースで作業し、文書中に貼りこむときにタブを2スペースに変換するとよいでしょう。 +TechBoosterでは文書にソースコードを貼りこむとき、インデントは2スペースと整理しています。 +このため4スペース派の人はサンプルコードではタブを使うようにして、エディタ上では1タブ＝4スペースで作業し、文書中に貼りこむときにタブを2スペースに変換するとよいでしょう。 詳細は@{review-introduction}に譲ります。 @@ -316,10 +327,10 @@ PDF、EPUBについては利用するコマンドそのものが違うので注 #@# prh:disable これらを詰め込んだ、実際にTechBoosterで使っているgrunt用設定ファイルを公開しています。 -@{https://github.com/TechBooster/C89-FirstStepReVIEW-v2/blob/master/Gruntfile.js} -Node.js v6以上が必要ですので注意してください。 -//footnote[why-gradle][gradleはgradle wrapperという仕組みがあり、gradle自体を別途導入する必要がないため] + * @{https://github.com/TechBooster/C89-FirstStepReVIEW-v2/blob/master/Gruntfile.js} + +Node.jsのバージョンといった動作条件はリポジトリのメンテナンスなどで更新があります。利用前にリポジトリを確認してください。 == 関連各所の紹介 TechBoosterがRe:VIEWを使っているなかで関係したお世話になっている各所を紹介します。 @@ -338,7 +349,7 @@ TechBoosterがRe:VIEWを使っているなかで関係したお世話になっ * 一人でかかない（共同執筆がお勧め） * 執筆時点は早めの締め切りを設定する（こうしておくと致命傷で済む） * レビューを実施する（読者の視点を作り出す） - * 紙面を@{=}や@{*}で検索する（文法ミスを見つけるため） + * 紙面を@{=}や@{*}、@{@}で検索する（文法ミスを見つけるため） * 記号などの文字化け探し（TeX、フォントはUTF-8対応しているとは限らない） * 紙面のはみ出しチェック（TeXコンパイル時のtoo late表示の有無を確認する）