review-retrovert 0.2.2 → 0.9.1

data/testdata/mybook/contents/05-faq.re

@@ -0,0 +1,328 @@
+= FAQ
+
+//abstract{
+よくある質問とその回答(Frequentry Asked Question, FAQ)を紹介します。
+//}
+
+#@#//makechaptitlepage[toc=on]
+
+
+=={sec-compileerror} コンパイルエラー
+
+
+=== コンパイルエラーが出たとき
+
+PDFファイル生成時にコンパイルエラーになったときの対処方法について説明します。
+
+PDFへのコンパイルは、内部では大きく3つのステージに分かれます。
+
+ - (1) 設定ファイルを読み込む（@<file>{config.yml}、@<file>{config-starter.yml}、@<file>{catalog.yml}）
+ - (2) 原稿ファイル(@<file>{*.re})を@<LaTeX>{}ファイルへ変換する
+ - (3) @<LaTeX>{}ファイルからPDFファイルを生成する
+
+(1)のステージでは、設定ファイルの書き方に間違いがあるとエラーが発生します。
+たとえば次のような点に注意してください。
+
+ * タブ文字を使ってないか（使っているとエラー）
+ * インデントが揃っているか（揃ってないとエラー）
+ * 必要な空白が抜けてないか（「@<code>{-}」や「@<code>{:}」の直後）
+
+(2)のステージでは、インライン命令やブロック命令の書き方に間違いがあるとエラーが発生します。
+たとえば次のような点に注意してください。
+
+ * インライン命令がきちんと閉じているか
+ * ブロック命令の引数が足りているか、多すぎないか
+ * 「@<code>|//}|」が足りてないか、または多すぎないか
+ * 「@<code>|@@<nop>{}<fn>{}|」や「@<code>|@@<nop>{}<img>{}|」や「@<code>|@@<nop>{}<table>{}|」のラベルが合っているか
+ * 「@<code>|@@<nop>{}<chapref>{}|」で指定した章IDが合っているか
+ * 「@<code>|@@<nop>{}<secref>{}|」で指定した節や項が存在するか
+ * 脚注の中で「@<code>{]}」を「@<code>{\]}」とエスケープしているか
+ * 「@<code>|//image|」で指定した画像ファイルが存在するか
+ * 原稿ファイル名を間違っていないか
+ * 原稿ファイルの文字コードがUTF-8になっているか
+
+このエラーの場合はエラーメッセージが出るので、それを@<bou>{注意深く読めば}解決の糸口が掴めます。
+
+(3)のステージでのエラーはあまり発生しないものの、原因がとても分かりにくく、@<LaTeX>{}に慣れている人でないと解決は難しいです。
+ときどきキャッシュファイル(@<file>{*-pdf/})のせいでおかしくなることがあるので、@<B>{困ったらキャッシュファイルを消して再コンパイル}してみましょう。
+
+//terminal[][困ったらキャッシュファイルを消して再コンパイル]{
+$ @<userinput>{rm -rf mybook-pdf} @<balloon>{キャッシュファイルを消す}
+$ @<userinput>{rake pdf}          @<balloon>{または rake docker:pdf}
+//}
+
+それでもエラーが解決できない場合は、ハッシュタグ「@<em>{#reviewstarter}」をつけてTwitterで聞いてみてください（宛先はなくて構いません）。
+
+
+=== 「@<code>|review-pdfmaker|」でPDFが生成できない
+
+Starterでは、「@<code>|review-pdfmaker|」や「@<code>|review-epubmaker|」は使えません。
+かわりに「@<code>|rake pdf|」や「@<code>|rake epub|」を使ってください。
+
+
+
+== 本文
+
+
+=== 左右の余白が違う
+
+印刷用PDFファイルでは、左右の余白幅を意図的に変えています。
+これは印刷時の読みやすさを確保したまま、本文の幅を最大限に広げているからです。
+詳しくは@<secref>{06-bestpractice|subsec-sidemargin}を見てください。
+
+
+=== 文章中のプログラムコードに背景色をつけたい
+
+「@<code>|@@<nop>{}<code>{...}|」を使って文章中に埋め込んだプログラムコードに、背景色をつけられます。
+そのためには、「@<file>{config-starter.yml}」で「@<code>|inlinecode_gray: true|」を設定してください。
+
+//list[][ファイル「@<file>{config-starter.yml}」]{
+    inlinecode_gray: true
+//}
+
+こうすると、@<file>{sty/starter.sty}において次のような@<LaTeX>{}マクロが有効になります。
+背景色を変えたい場合はこのマクロを変更してください。
+
+//list[][ファイル「sty/starter.sty」]{
+  \renewcommand{\reviewcode}[1]{%
+    \,%                        % ほんの少しスペースを入れる
+    \colorbox{shadecolor}{%    % 背景色を薄いグレーに変更
+      \texttt{#1}%             % 文字種を等幅フォントに変更
+    }%
+    \,%                        % ほんの少しスペースを入れる
+  }
+//}
+
+
+=== 索引をつけたい
+
+Re:VIEWのWikiページを参照してください。
+
+ * @<href>{https://github.com/kmuto/review/blob/master/doc/makeindex.ja.md}
+
+
+
+== プログラムコードとターミナル
+
+
+=== プログラムコードの見た目が崩れる
+
+おそらく、プログラムコードの中でタブ文字が使われています。
+タブ文字を半角空白に置き換えてみてください。
+
+Starterでは、プログラム中のタブ文字は自動的に半角空白に置き換わります。
+しかしインライン命令があるとどうしてもカラム幅を正しく計算できないので、意図したようには半角空白に置き換わらず、プログラムの見た目が崩れます。
+
+
+=== 右端に到達してないのに折り返しされる
+
+Starterではプログラム中の長い行が自動的に右端で折り返されます。
+このとき、右端にはまだ文字が入るだけのスペースがありそうなのに折り返しされることがあります（@<img>{codeblock_rpadding1}）。
+
+//image[codeblock_rpadding1][右端にはまだ文字が入るだけのスペースがありそうだが…][scale=0.7]
+
+このような場合、プログラムやターミナルの表示幅をほんの少し広げるだけで、右端まで文字が埋まるようになります。
+
+具体的には、ファイル「@<file>{config-starter.yml}」の中の「@<code>{program_widen: 0.0mm}」や「@<code>{terminal_wide: 0.0mm}」を、たとえば「@<code>{0.3mm}」に設定してください（値は各自で調整してください）。
+
+//list[][ファイル「config-starter.yml」]{
+  ## プログラム（//list）の表示幅をほんの少しだけ広げる。
+  @<del>{program_waiden:   0.0mm}
+  @<b>{program_widen:   0.3mm}
+
+  ## ターミナル（//terminal, //cmd）の表示幅をほんの少しだけ広げる。
+  @<del>{terminal_widen:  0.0mm}
+  @<b>{terminal_widen:  0.3mm}
+//}
+
+こうすると、プログラムやターミナルの表示幅が少しだけ広がり、文字が右端まで埋まるようになります（@<img>{codeblock_rpadding2}）。
+
+//image[codeblock_rpadding2][表示幅をほんの少し広げると、右端まで埋まるようになった][scale=0.7]
+
+
+=== 半角文字の幅を全角文字の半分にしたい
+
+英数字の幅が狭いフォントを使うと、半角文字の幅が全角文字の約半分になります（ぴったりにはなりません）。
+
+@<file>{config-starter.yml}で、以下のうち必要なほうを設定してください。
+
+//list[][]{
+  ## //list用
+  program_ttfont: inconsolata-narrow
+
+  ## //terminal用
+  terminal_ttfont: inconsolata-narrow
+//}
+
+
+=== ターミナルの出力を折り返しせずに表示したい
+
+ターミナルの出力結果を折り返しせずに表示するには、いくつか方法があります。
+
+===== 小さいフォントで表示する
+
+「@<code>|//terminal|」や「@<code>|//list|」では、小さいフォントで表示するオプションがあります。
+フォントサイズは「@<code>|small|」「@<code>|x-small|」「@<code>|xx-small|」の3つが選べます。
+
+//list[][サンプル]{
+/@<nop>$$/terminal[][小さいフォントで表示する][@<b>|fontsize=x-small|]{
+                              Table "public.customers"
+   Column   |  Type   | Nullable |                Default
+------------+---------+----------+---------------------------------------
+ id         | integer | not null | nextval('customers_id_seq'::regclass)
+ name       | text    | not null |
+ created_on | date    | not null | CURRENT_DATE
+Indexes:
+    "customers_pkey" PRIMARY KEY, btree (id)
+    "customers_name_key" UNIQUE CONSTRAINT, btree (name)
+/@<nop>$$/}
+//}
+
+//sampleoutputbegin[表示結果]
+
+//terminal[][小さいフォントで表示する][fontsize=x-small]{
+                              Table "public.customers"
+   Column   |  Type   | Nullable |                Default
+------------+---------+----------+---------------------------------------
+ id         | integer | not null | nextval('customers_id_seq'::regclass)
+ name       | text    | not null |
+ created_on | date    | not null | CURRENT_DATE
+Indexes:
+    "customers_pkey" PRIMARY KEY, btree (id)
+    "customers_name_key" UNIQUE CONSTRAINT, btree (name)
+//}
+
+//sampleoutputend
+
+
+
+===== 幅の狭い等幅フォントを使う
+
+Starterでは等幅フォントを複数の中から選べます。
+このうち「@<em>{inconsolata-narrow}」は文字の表示幅が狭いので、できるだけ折り返しをさせたくない場合に有効です。
+
+「@<file>{config-starter.yml}」で「@<code>|terminal_ttfont:|」を「@<code>|inconsolata-narrow|」に設定してください。
+
+
+=== コードハイライトしたい
+
+コードハイライトは、Starterでは未サポートです@<fn>{fn-rkpw8}。
+将来的にはサポートする予定ですが、時期は未定です。
+
+//footnote[fn-rkpw8][Re:VIEWではコードハイライトができるそうです。]
+
+
+
+== その他
+
+
+=== @<LaTeX>{}のスタイルファイルから環境変数を参照する
+
+Starterでは、名前が「@<em>{STARTER_}」で始まる環境変数を@<LaTeX>{}のスタイルファイルから参照できます。
+
+たとえば「@<code>{STARTER_FOO_BAR}」という環境変数を設定すると、@<code>{sty/mystyle.sty}や@<code>{sty/starter.sty}では「@<code>{\STARTER@FOO@BAR}」という名前で参照できます。
+想像がつくと思いますが、環境変数名の「@<code>{_}」は「@<code>{@}」に変換されます。
+
+//terminal[][環境変数を設定する例(macOS, UNIX)]{
+$ @<userinput>{export STARTER_FOO_BAR="foobar"}
+//}
+
+//list[][環境変数を参照する例]{
+%% ファイル：sty/mystyle.sty
+\newcommand\foobar[0]{%             % 引数なしコマンドを定義
+  \@ifundefined{STARTER@FOO@BAR}{%  % 未定義なら
+    foobar%                         % デフォルト値を使う
+  }{%                               % 定義済みなら
+    \STARTER@FOO@BAR%               % その値を使う
+  }%
+}
+//}
+
+この機能を使うと、出力や挙動を少し変更したい場合に環境変数でコントロールできます。
+また値の中に「@<code>{$}」や「@<code>{\\}」が入っていてもエスケープはしないので注意してください。
+
+
+=== 高度なカスタマイズ
+
+設定ファイルや@<LaTeX>{}スタイルファイルでは対応できないようなカスタマイズが必要になることがあります。
+たとえば次のような場合です。
+
+ * 印刷用とタブレット用でPDFファイルの仕様を大きく変えたい。
+ * B5サイズとA5サイズの両方のPDFファイルを生成したい。
+ * β版と本番用とで設定を切り替えたい。
+ * コンパイルするたびに、あるプログラムの実行結果を原稿ファイルに埋め込みたい。
+
+このような要件を、Re:VIEWやStarterの機能を使い倒して実現してもいいですが、それよりも汎用的なやり方で実現しましょう。
+方針としては、設定ファイルや原稿ファイルを用途に応じて生成するのがいいでしょう。
+
+ここでは例として「印刷用とタブレット用で@<file>{config-starter.yml}の内容を変える」ことを考えてみます。
+
+//blankline
+//noindent
+(1) 「@<file>{config-starter.yml}」に拡張子「@<file>{.eruby}」をつけます。
+
+//terminal{
+$ @<userinput>{mv config-starter.yml config-starter.yml.eruby}
+## またはこうでもよい
+$ @<userinput>$mv config-starter.yml{,.eruby}$
+//}
+
+//noindent
+(2) 次に、そのファイルに次のような条件分岐を埋め込みます。
+
+//list[][ファイル「config-starter.yml.eruby」]{
+....(省略)....
+@<b>$<% if buildmode == 'printing'   # 印刷向け %>$
+  target:    pbook
+  pagesize:  B5
+  fontsize:  10pt
+  textwidth: 44zw
+@<b>$<% elsif buildmode == 'tablet'  # タブレット向け %>$
+  target:    tablet
+  pagesize:  A5
+  fontsize:  10pt
+  textwidth: 42zw
+@<b>$<% else abort "error: buildmode=#{buildmode.inspect}" %>$
+@<b>$<% end %>$
+//}
+
+//noindent
+(3) 「@<file>{config-starter.yml}」を生成するRakeタスクを定義します。
+ここまでが準備です。
+
+//source[lib/tasks/mytasks.rake]{
+def render_eruby_files(param)   # 要 Ruby >= 2.2
+  Dir.glob('**/*.eruby').each do |erubyfile|
+    origfile = erubyfile.sub(/\.eruby$/, '')
+    sh "erb -T 2 -P '#{param}' #{erubyfile} > #{origfile}"
+  end
+end
+
+namespace :setup do
+
+  desc "*印刷用に設定 (B5, 10pt, mono)"
+  task :printing do
+    render_eruby_files('buildmode=printing')
+  end
+
+  desc "*タブレット用に設定 (A5, 10pt, color)"
+  task :tablet do
+    render_eruby_files('buildmode=tablet')
+  end
+
+end
+//}
+
+//noindent
+(4)「@<code>{rake setup:printing}」または「@<code>{rake setup:tablet}」を実行すると、@<file>{config-starter.yml}が生成されます。
+そのあとで「@<code>{rake pdf}」を実行すれば、用途に応じたPDFが生成されます。
+
+//cmd{
+$ @<b>{rake setup:printing  # 印刷用}
+$ rake pdf
+$ mv mybook.pdf mybook_printing.pdf
+
+$ @<b>{rake setup:tablet    # タブレット用}
+$ rake pdf
+$ mv mybook.pdf mybook_tablet.pdf
+//}

data/testdata/mybook/contents/06-bestpractice.re

@@ -0,0 +1,971 @@
+= よりよい本づくり
+
+//abstract{
+せっかく本を作るなら、よりよい本づくりを目指しましょう。
+
+この章では、よりよい本にするためのポイントを紹介します。
+//}
+
+#@#//makechaptitlepage[toc=on]
+
+
+
+== まえがき
+
+
+=== まえがきには章番号をつけない
+
+ときどき、「まえがき」に章番号がついている技術系同人誌を見かけます（@<img>{preface_numbered}）。
+しかし一般的には、「まえがき」や「あとがき」には章番号はつけません。
+
+//image[preface_numbered][間違って章番号がついた「まえがき」][scale=0.8,border=on]
+
+Re:VIEWおよびStarterでは、「@<file>{catalog.yml}」の「@<code>|PREDEF:|」や「@<code>|POSTDEF:|」に指定した原稿ファイルには、章番号がつきません。
+これを間違えて「@<code>|CHAPS:|」に含めてしまうと、「まえがき」や「あとがき」に章番号がついてしまうので気をつけてください。
+
+
+=== まえがきに「本書の目的」を入れる
+
+「まえがき」に本の概要や目的があると、本を手にとった人がその本を買うかどうかを判断できます。
+
+次のは「本書の目的」のサンプルです。
+
+===={notoc} 本書の目的
+
+本書の目的は、SQLを初めてさわる初心者が、簡単な検索と集計をSQLでできるようになることです。
+マーケティング部に配属された新卒1年目の人が、SQLで簡単なデータ分析をできるようになりたいなら、この本はぴったりです。
+
+SQLのチューニングや、データベース設計といった内容は、本書の範囲ではありません。
+
+
+=== まえがきに「対象読者」を入れる
+
+先ほどの話と似ていますが、「まえがき」に本の対象読者が書かれてあると、本を手にとった人は自分がその本の対象読者かどうか、判断しやすいです。
+
+このとき、「初心者」と「初級者」をちゃんと区別するといいでしょう。
+
+ * 「初心者」は入門書をまだ読んでいない人や読んでる途中の人
+ * 「初級者」は入門書を読み終えた人、実務での経験が浅い人
+
+次のは「対象読者」のサンプルです。
+
+===={notoc} 本書の対象読者
+
+本書は、何らかのオブジェクト指向言語の入門書を読み終えた初級者を対象としています。
+そのため、「オブジェクト」「クラス」「メソッド」などの用語は説明なしに使用します。
+まったくの初心者は本書の対象ではないので注意してください。
+
+
+=== まえがきに「前提知識」を入れる
+
+これまでの話と似ていますが、その本を読むのにどんな前提知識がどのくらいのレベルで必要かを「まえがき」に書いておくと、本を手にとった人は買うかどうかの判断がしやすいです。
+
+このとき、具体例を添えておくといいでしょう。
+たとえば「Linuxの基礎知識を前提とします」だけでは、どんな基礎知識がどのレベルで必要なのか、よくわかりません。
+もしこれが「@<code>|ln -s|でシンボリックリンクが作れること」「@<code>{ps -ef|grep gzip}が何をしているのか分かること」「パイプとリダイレクトの違いが説明できること」だと、必要な前提知識のレベルがよく分かります。
+
+次のは「前提知識」のサンプルです。
+
+===={notoc} 本書の前提知識
+
+本書は、Python をある程度使いこなしている中級者以上を対象にしています。そのため、Pythonの基礎知識を持っていることを前提とします。
+
+具体的には、次のことがすべて分かることが前提となります。
+
+ * 「@<code>|[x for x in range(1, 11) if x % 2]|」の意味が分かる
+ * 「@<code>|(lambda x, y: x + y)(3, 4)|」の結果が予想できる
+ * 「@<code>|x=1|」と「@<code>|fn(x=1)|」の違いが分かる
+ * 「@<code>|return|」と「@<code>|yield|」の違いが説明できる
+ * 「@<code>|@property|」が何か分かる
+
+
+=== まえがきにサポートサイトのURLを載せる
+
+本の正誤表が載っていたり、サンプルコードがダウンロードできるサイトのことをここでは「サポートサイト」と呼ぶことにします。
+
+本や同人誌を書いたら、ぜひサポートサイトを用意しましょう。
+そして正誤表とサンプルコード、できれば質問ができる連絡先を用意しましょう。
+
+そしてそのURLをまえがき（と奥付）に載せましょう。
+
+次のはサポートサイト紹介文のサンプルです。
+
+==== サポートサイト
+
+本書の正誤表は次のサイトに載っています。
+サンプルコードもここからダウンロードできます。
+
+ * @<href>{https://www.example.com/mygreatbook/}
+
+
+=== まえがきに謝辞を載せる
+
+レビューしてくれた人や編集者がいたら、まえがきに謝辞を書きましょう。
+家族への謝辞を入れるのもよくあります。
+
+謝辞を忘れるのはかなり失礼な行為に当たります。
+また名前を間違ったり、名前が抜けるのも大変失礼です。
+締切間際に謝辞を書くと間違える可能性が高いので、執筆期間の早いうちに謝辞を書いておきましょう。
+
+
+=== まえがきにソフトウェアのバージョンを載せる
+
+まえがきに、使用した（または動作検証した）ソフトウェアのバージョンを載せるといいでしょう。
+
+たとえばPythonの2.7なのか3.Xなのかは大きな問題です。
+またLinuxだとCentOSなのかUbuntuなのか、Ubuntuなら18.04なのか20.04なのか、といった情報を、まえがきに書いておきましょう。
+
+
+=== まえがきの章タイトル以外は目次に載せない
+
+目次には「まえがき」だけが載っていればよく、「本書の目的」や「対象読者」や「謝辞」などは目次に載せる必要はありません。
+
+これらを目次に載せないための方法は2つあります。
+
+ひとつは、節(Section)や項(Subsection)のタイトルに「@<code>|[notoc]|」オプションをつけることです。
+これをつけると、その節や項は目次に載りません。
+
+//list[][]{
+@<nop>{}= はじめに
+
+@<nop>{}==@<b>|[notoc]| 本書の目的
+
+@<nop>{}==@<b>|[notoc]| 対象読者
+
+@<nop>{}==@<b>|[notoc]| 謝辞
+
+//}
+
+もうひとつは、節(Section)や項(Subsection)を飛ばして目(Subsubsection)を使うことです。
+通常、目次に乗るのは項までで目は載りません。
+そこで、次のような見出しにすれば「本書の目的」や「対象読者」や「謝辞」は目次に載りません。
+
+//list[][]{
+@<nop>{}= はじめに
+
+@<nop>{}@<b>|====| 本書の目的
+
+@<nop>{}@<b>|====| 対象読者
+
+@<nop>{}@<b>|====| 謝辞
+
+//}
+
+この方法は見出しのレベルを飛ばしているので、本文で使うのはよくありません。
+しかし目次に載らないところで使うなら、あまり気にしなくてもいいでしょう。
+
+
+
+== 初心者向け入門書
+
+
+=== 初心者向け入門書ではフォントを大きめにする
+
+Starterでは、デフォルトでは次のようなフォントサイズにしています。
+
+ * ページがB5サイズなら、フォントは10pt
+ * ページがA5サイズなら、フォントは9pt
+
+しかし初心者向けの入門書では、次のように少し大きめのフォントを使ったほうが、紙面から受ける圧迫感が減ります@<fn>{fn-8ow3e}。
+
+ * ページがB5サイズなら、フォントは11pt
+ * ページがA5サイズなら、フォントは10pt
+
+//footnote[fn-8ow3e][興味のある人は本屋に行って、入門書とオライリー本の本文を比べてみるといいでしょう。]
+
+とはいえフォントを大きくしていない入門書もよく見かけます。
+フォントを大きくするとページ数が増えてその分印刷代が高くなるので、どうするかはよく考えてください。
+
+Starterで本文のフォントサイズを変える方法は、@<secref>{04-customize|subsec-fontsize}を参照してください。
+またそれに合わせて本文の幅も変更する必要があるので、@<secref>{04-customize|subsec-textwidth}を参照してください。
+
+
+=== 初心者向け入門書では節と項の見分けをつきやすくする
+
+Re:VIEWでは@<LaTeX>{}のデザインをそのまま使っているので、節(Section)と項(Subsection)のデザインがよく似ており、見分けにくいです（@<img>{heading_design1}）。
+初心者は本を読み慣れていないので、このデザインでは節と項の違いが分からず、結果として文書構造を理解しないまま読み進めてしまいます。
+
+//image[heading_design1][Re:VIEWでは節(Section)と項(Subsection)が見分けにくい][scale=0.9,border=on]
+
+Starterでは、節と項のデザインを大きく変えており、見分けやすくなっています（@<img>{heading_design2}）。
+これは、初心者でも節と項の違いがすぐに分かり、文書構造を把握できるようにするための配慮です。
+
+//image[heading_design2][Starterでは節(Section)と項(Subsection)が見分けやすい][scale=0.9,border=on]
+
+
+=== 初心者向け入門書では節ごとに改ページする
+
+初心者向けの入門書では、節(Section)ごとに改ページしていることが多いです。
+そもそも初心者は本自体を読み慣れていないことが多いので、節ごとに改ページしてあげることで、文章の構造を分かりやすく示せます。
+
+Starterでは節ごとに改ページする設定が用意されています。
+詳しくは@<secref>{04-customize|subsec-newpagepersec}を参照してください。
+
+ただし節ごとに改ページすると、当然ですが全体のページ数は増え、それを調整するために本文をあれこれ変更する必要があります。
+実践するのは時間とお金（印刷代）に余裕がある場合だけにしましょう@<fn>{fn-njede}。
+
+//footnote[fn-njede][逆にいうと、商業の入門書はそれだけのコストを掛けて制作されているということです。]
+
+
+
+== 箇条書き
+
+=== 箇条書きを正しく使い分ける
+
+箇条書きには「番号なし」「番号つき」「ラベルつき」の3つがあります。
+
+番号なしの箇条書きは、項目に順序がないか、あっても重要ではない場合に使います。
+たとえば次の例では、公開された順に項目が並んでいますがそこはあまり重要ではなく、項目の順番を入れ替えても文章の意味は成り立つので、番号なしの箇条書きを使います。
+
+//list[][サンプル]{
+スタジオジブリ初期の代表作は次の通りです。
+
+ * 風の谷のナウシカ
+ * 天空の城ラピュタ
+ * となりのトトロ
+//}
+
+//sampleoutputbegin[表示結果]
+
+スタジオジブリ初期の代表作は次の通りです。
+
+ * 風の谷のナウシカ
+ * 天空の城ラピュタ
+ * となりのトトロ
+
+//sampleoutputend
+
+
+
+番号つきの箇条書きは、手順や順位など、項目の順序が重要な場合に使います。
+たとえば次の例では項目の順序が重要なので、番号つきの箇条書きを使います。
+
+//list[][サンプル]{
+スタジオジブリ初期の代表作を、好きな順に並べました。
+
+ 1. 風の谷のナウシカ
+ 2. 天空の城ラピュタ
+ 3. となりのトトロ
+//}
+
+//sampleoutputbegin[表示結果]
+
+スタジオジブリ初期の代表作を、好きな順に並べました。
+
+ 1. 風の谷のナウシカ
+ 2. 天空の城ラピュタ
+ 3. となりのトトロ
+
+//sampleoutputend
+
+
+
+ラベルつきの箇条書きは、一見すると番号つき箇条書きに似ていますが、数字ではなくアルファベットや文字を使う点が違います。
+またラベルはあとから参照しやすくするために使い、順番を表すためには使いません。
+そのため、ラベルつきの箇条書きは「番号なし箇条書きにラベルをつけたもの」として使います。
+
+たとえば次の例では、項目の順序は重要ではないので番号なし箇条書きでもいいのですが、あとから項目を参照するのでラベルつき箇条書きにしています。
+
+//list[][サンプル]{
+スタジオジブリ初期の代表作は次の通りです。
+
+ - (A) 風の谷のナウシカ
+ - (B) 天空の城ラピュタ
+ - (C) となりのトトロ
+
+興行収入を調べると、(A)が14.8億円、(B)が11.6億円、(C)が11.7億円でした。
+//}
+
+//sampleoutputbegin[表示結果]
+
+スタジオジブリ初期の代表作は次の通りです。
+
+ - (A) 風の谷のナウシカ
+ - (B) 天空の城ラピュタ
+ - (C) となりのトトロ
+
+興行収入を調べると、(A)が14.8億円、(B)が11.6億円、(C)が11.7億円でした。
+
+//sampleoutputend
+
+
+
+番号つき箇条書きとラベルつき箇条書きは、きちんと使い分けましょう。
+前者は順序に強い意味がある場合、後者は意味がないか弱い場合に使います。
+
+
+=== 箇条書き直後に継続する段落は字下げしない
+
+段落の途中に箇条書きを入れる場合、箇条書きの直後は字下げ（インデント）をしないようにしましょう。
+
+次の例を見てください。
+箇条書きの直後に「@<code>|//noindent|」を入れることで、字下げしないようにしています。
+
+//list[][サンプル]{
+スタジオジブリ初期の代表作には、
+
+ * 風の谷のナウシカ
+ * 天空の城ラピュタ
+ * となりのトトロ
+
+@<b>|//noindent|
+が挙げられます。
+
+しかしスタジオジブリが発足したのは実はトトロからであり、ナウシカとラピュタは厳密にはスタジオジブリの製作ではないのです。
+//}
+
+//sampleoutputbegin[表示結果]
+
+スタジオジブリ初期の代表作には、
+
+ * 風の谷のナウシカ
+ * 天空の城ラピュタ
+ * となりのトトロ
+
+//noindent
+が挙げられます。
+
+しかしスタジオジブリが発足したのは実はトトロからであり、ナウシカとラピュタは厳密にはスタジオジブリの製作ではないのです。
+
+//sampleoutputend
+
+
+
+字下げは段落の始まりを表すために使います。
+しかし上の例の「が挙げられます。」は段落の始まりではなく途中だと考えられるため、字下げは行いません。
+
+もっとも、段落の途中に箇条書きを入れること自体がよくありません。
+この例なら、次のように書き換えるといいでしょう。
+
+//list[][サンプル]{
+スタジオジブリ初期の代表作には、@<b>|次の3つが挙げられます。|
+
+ * 風の谷のナウシカ
+ * 天空の城ラピュタ
+ * となりのトトロ
+
+しかしスタジオジブリが発足したのは実はトトロからであり、ナウシカとラピュタは厳密にはスタジオジブリの製作ではないのです。
+//}
+
+
+
+
+
+== 本文
+
+
+=== 強調箇所は太字のゴシック体にする
+
+日本語の文章では本文が明朝体の場合、強調箇所は太字にするだけでなく、ゴシック体にするのがよいとされています。
+そのため、強調には「@<code>|@@<nop>{}<b>{...}|」ではなく「@<code>|@@<nop>{}<B>{...}|」または「@<code>|@@<nop>{}<strong>{...}|」を使ってください。
+
+//list[][サンプル]{
+本文本文@<b>|@@<nop>$$<B>{強調}|本文本文。@@<nop>$$<balloon>{ゴシック体なので望ましい}
+
+本文本文@<b>|@@<nop>$$<b>{太字}|本文本文。@@<nop>$$<balloon>{明朝体のままなので望ましくない}
+//}
+
+//sampleoutputbegin[表示結果]
+
+本文本文@<B>{強調}本文本文。@<balloon>{ゴシック体なので望ましい}
+
+本文本文@<b>{太字}本文本文。@<balloon>{明朝体のままなので望ましくない}
+
+//sampleoutputend
+
+
+
+
+=== 強調と傍点を使い分ける
+
+傍点とは@<bou>{このように}文章の上についた小さな点のことであり、Re:VIEWやStarterなら「@<code>|@@<nop>{}<bou>{...}|」でつけられます。
+
+傍点は強調とよく似ていますが、強調は「重要な箇所」を表すのに対し、傍点は「重要ではないけど他と区別したい、注意を向けたい」という用途で使います。
+
+たとえば次の例では、否定文であることが見落とされないよう、傍点を使っています。
+ここは重要箇所ではないので、強調は使わないほうがいいでしょう。
+
+//quote{
+//noindent
+Re:VIEW Starterではアップグレード用スクリプトを用意して@<bou>{いません}。
+//}
+
+また技術系の文書ではほとんど見かけませんが、小説やエッセーや漫画では「何か含みを持たせた表現」や「のちの伏線になる箇所」に傍点を使います。
+参考までに、『ワールドトリガー』22巻@<fn>{fn-z94o3}から傍点を使った例を（ネタバレは避けつつ）引用します。
+
+//quote{
+//noindent
+その@<ruby>{追尾弾, ハウンド}は@<bou>{相手を動かすため}の@<ruby>{追尾弾, ハウンド}なのよ @<small>{(p.132)}
+//}
+
+//quote{
+//noindent
+だとすると、@<ruby>{雨取, あまとり}ちゃんは人を@<bou>{狙って撃てない}のか？ @<small>{(p.133)}
+//}
+
+//quote{
+//noindent
+今の@<ruby>{千佳, ちか}は間違いなくちゃんと
+@<bou>{戦う意志}を持ってますよ @<small>{(p.134)}
+//}
+
+//quote{
+//noindent
+#@#さっきの@<ruby>{弾, たま}は@<bou>{追尾性能を切った}@<ruby>{追尾弾, ハウンド}か……!? @<small>{(p.174)}
+さっきの@<ruby>{弾, たま}は@<bou>{■■■■を■った}■■■か……!? @<small>{(p.174)}
+//}
+
+//footnote[fn-z94o3][『ワールドトリガー』22巻（葦原大介、集英社、2020年）]
+
+
+=== [PDF] 記号と日本語はくっつくことに注意する
+
+PDFでは、読みやすさのために日本語と英数字の間に少しアキ（隙間）が入ります。
+これは内部で使っている組版用ソフト「@<LaTeX>{}」の仕様です。
+
+//list[][サンプル]{
+あいうえおABC DEFかきくけこ123
+//}
+
+//sampleoutputbegin[表示結果]
+
+あいうえおABC DEFかきくけこ123
+
+//sampleoutputend
+
+
+
+しかし記号の場合はアキが入りません。
+たとえば次の例では、「ン」と「-」の間にはアキが入っていません。
+
+//list[][サンプル]{
+オプション-pを使う。
+//}
+
+//sampleoutputbegin[表示結果]
+
+オプション-pを使う。
+
+//sampleoutputend
+
+
+
+このような場合は、半角空白を入れるか、またはカッコでくくるといいでしょう。
+
+//list[][サンプル]{
+オプション -p を使う。
+
+オプション「-p」を使う。
+//}
+
+//sampleoutputbegin[表示結果]
+
+オプション -p を使う。
+
+オプション「-p」を使う。
+
+//sampleoutputend
+
+
+
+
+=== [PDF] 等幅フォントで余計な空白が入るのを防ぐ
+
+(TODO)
+
+
+=== 文章中のコードは折り返しする
+
+(TODO)
+
+
+=== ノートとコラムを使い分ける
+
+(TODO)
+
+
+
+== 見出し
+
+=== 節タイトルが複数行になるなら下線や背景色を使わない
+
+Starterでは節(Section)のタイトルに下線や背景色をつけられます。
+しかしそれらは節タイトルが1行に収まる場合だけを想定しており、複数行の場合は考慮されていません。
+
+タイトルが長い節(Section)がある場合は、節タイトルに下線も背景色も使わないものがいいでしょう。
+具体的には次のどちらかを選びましょう。
+
+ * 「@<code>{leftline}」… 節タイトル左に縦線を引く（@<img>{sechead_design_4}上）
+ * 「@<code>{numbox}」… 節番号を白ヌキ文字にする（@<img>{sechead_design_4}下）
+
+//image[sechead_design_4][タイトルが複数行でも崩れない節デザインの例][scale=0.8,border=on]
+
+Starterにおける節タイトルのデザインを変更する方法は、@<secref>{04-customize|subsec-sectitle}を参照してください。
+
+
+=== 項を参照するなら項番号をつける
+
+「@<code>|@@<nop>{}<secref>{}|」や「@<code>|@@<nop>{}<hd>{}|」で項(Subsection)を参照するなら、項にも番号をつけましょう。
+番号のついていない見出しを参照するのは止めておいたほうがいいでしょう。
+
+項に番号をつける方法は、@<secref>{04-customize|subsec-subsecnum}を参照してください。
+
+
+
+== プログラムコード
+
+=== 0とOや1とlが見分けやすいフォントを使う
+
+プログラムコードやターミナルでは、0とOや、1とlが見分けやすい等幅フォントを使ってください（@<img>{font_beramono}）。
+具体的には「@<em>{beramono}」フォントか「@<em>{inconsolata}」フォントを使うといいでしょう。
+
+//image[font_beramono][0とOや、1とlが見分けやすい等幅フォントを使う][scale=0.8]
+
+Starterでは、プログラムコードやターミナルの等幅フォントを選べる設定を用意しています。
+詳しくは@<secref>{04-customize|subsec-ttfont}を参照してください。
+
+
+=== フォントを小さくしすぎない
+
+プログラムコードやターミナルのフォントサイズが小さすぎると、とても読みづらくなります。
+具体的には、8pt以下@<fn>{fn-5c1j2}にするのはやめましょう。
+
+//footnote[fn-5c1j2][念のために説明すると、「8pt以下」には8ptも含まれます。]
+
+昔は長い行をページ内に収める必要があったため、プログラムコードのフォントサイズを小さくする必要がありました。
+しかし今は長い行を自動的に折り返す機能があるので、小さいフォントを使う必要性は薄れています。
+また、たとえば「@<em>{inconsolata}」フォントは@<LaTeX>{}のデフォルトフォントと比べて小さめに表示されるため、このフォントを選ぶと必要以上に小さく見えます。
+
+Starterのデフォルトでは、本文のフォントサイズに関わらず、A5サイズなら9pt、B5サイズなら10ptのフォントサイズが使われます。
+
+ * A5サイズなら、本文が9ptでも10ptでも、プログラムコードはデフォルトで9pt
+ * B5サイズなら、本文が10ptでも11ptでも、プログラムコードはデフォルトで10pt
+
+この調整は、「@<file>{config-starter.yml}」の設定項目「@<code>|program_fontsize:|」と「@<code>|terminal_fontsize:|」で行われています。
+本文がA5サイズ10ptまたはB5サイズ11ptならこれらが「@<code>|small|」に設定され、A5サイズ9ptまたはB5サイズ10ptなら「@<code>|normal|」に設定されます。
+
+
+=== 重要箇所を目立たせる
+
+プログラムコードが10行以上あると、読者はコードのどこに注目すればいいか、分からなくなります。
+もし注目してほしい箇所が強調されていれば、読者にとってとても理解しやすくなります。
+
+プログラムコードの中で注目してほしい箇所は、ぜひ太字にして目立たせましょう。
+たとえば次の例は再帰プログラムの説明なので、再帰している箇所を太字にして目立たせています。
+
+//list[][再帰プログラムの例]{
+function @<b>|fib(n)| {
+    if (n <= 1) {
+        return n;
+    } else {
+        return @<b>|fib(n-1)| + @<b>|fib(n-2)|;
+    }
+}
+//}
+
+なおプログラムコードを太字にするときは、「@<code>|@@<nop>{}<B>{}|」ではなく「@<code>|@@<nop>{}<b>{}|」を使ってください。
+「@<code>|@@<nop>{}<B>{}|」だと等幅フォントのはずがゴシック体に変わってしまいます。
+「@<code>|@@<nop>{}<b>{}|」だと太字にするだけなので等幅フォントのままで変わりません。
+
+//note[太字では目立たないことがある]{
+太字にしても目立たない文字や記号があるので注意してください@<fn>{fn-owu4i}。
+
+たとえば空白やタブ文字は、目に見えないので太字にしても見えません。
+またピリオド「@<code>|.|」やカンマ「@<code>|,|」やハイフン「@<code>|-|」やクオート「@<code>|'"`|」などは、太字にしても目立たず、読者には気づいてもらえない可能性が高いです。
+
+解決策としては、文字の色を変えるか、背景色を変えることです。
+Starterではどのような方法にするかを検討中です。
+
+//footnote[fn-owu4i][重要でない箇所を薄く表示したり、削除したコードに取り消し線をつける場合でも、同様の問題が起こります。]
+//}
+
+
+=== 重要でない箇所を目立たせない
+
+Javaの「@<code>{public static void main(String[] args)}」や、PHPの「@<code>|<?php ?>|」は、プログラムコードの説明において重要ではないので、目立たせないようにするといいでしょう。
+
+Starterでは「@<code>|@@<nop>{}<weak>{...}|」を使うと、プログラムコードの一部を目立たせないようにできます。
+
+//list[][重要でない箇所を目立たせなくした例]{
+@<weak>|public class Example {|
+@<weak>|    public static void main(String[] args) {|
+        System.out.println("Hello, world!");
+@<weak>|    }|
+@<weak>|}|
+//}
+
+
+=== 差分（追加と削除）の箇所を明示する
+
+サンプルコードを徐々に改善するような内容の場合は、削除した行に取り消し線を引き、追加した行を太字で表示すると、差分が分かりやすくなります。
+
+たとえば次のようなサンプルコードがあるとします。
+
+//list[][最初のサンプルコード]{
+/// ボタンを押すたびにラベルを入れ替える
+$('#button').on('click', function(ev) {
+  let $this = $(this);
+  let prev = $this.text();
+  let next = $this.data('label');
+  $this.text(next).data('label', prev);
+});
+//}
+
+これを改善して、次のようなコードにしました。
+しかしこれだと、どこを変更したかを読者が探さないといけません。
+
+//list[][改善したサンプルコード]{
+/// ボタンを押すたびにラベルを入れ替える
+function toggleLabel(ev) {
+  let $this = $(this);
+  let prev = $this.text();
+  let next = $this.data('label');
+  $this.text(next).data('label', prev);
+}
+$('#button').on('click', toggleLabel);
+//}
+
+もし次のように差分を分かりやすく表示すれば、読者は変更点をすぐに理解できるでしょう。
+
+//list[][]{
+/// ボタンを押すたびにラベルを入れ替える
+@<del>|$('#button').on('click', function(ev) {|
+@<b>|function toggleLabel(ev) {|
+  let $this = $(this);
+  let prev = $this.text();
+  let next = $this.data('label');
+  $this.text(next).data('label', prev);
+@<del>|});|
+@<b>|}|
+@<b>|$('#button').on('click', toggleLabel);|
+//}
+
+この作業はとても面倒です。
+それでもこの面倒を乗り切った本だけが、初心者にとって分かりやすい本になるのです。
+
+このほか、Gitでの差分のような表示方法も考えられます。
+各自で工夫してみてください。
+
+
+=== 長い行の折り返し箇所を明示する
+
+長い行を折り返したとき、折り返した箇所が分かるような表示が望ましいです。
+そのための方法は3つあります。
+
+ * 折り返し箇所に何らかの目印をつける
+ * 行番号をつける
+ * 行末を表す記号をつける
+
+たとえば次の例では、あたかも複数行あるかのように見えます。
+
+//list[][][foldmark=off]{
+*********************************************************************************************************************************************************************************************
+//}
+
+しかし折り返した箇所に折り返し記号をつけてみると、実は1行であることが分かります。
+
+//list[][][foldmark=on]{
+*********************************************************************************************************************************************************************************************
+//}
+
+また行番号をつけても、1行であることが分かります。
+
+//list[][][foldmark=off,lineno=on,linenowidth=0]{
+*********************************************************************************************************************************************************************************************
+//}
+
+あるいは行末を表す記号をつける方法でも、折り返した行にはその記号がつかないので、1行であることが分かります。
+
+//list[][][foldmark=off,eolmark=on]{
+*********************************************************************************************************************************************************************************************
+//}
+
+このように、方法は何でもいいので折り返し箇所が分かるような仕組みを使いましょう。
+
+Starterでは、デフォルトで折り返し箇所に折り返し記号がつくようになってます。
+また折り返し記号がプログラムコードの一部だと間違って認識されないよう、次のような工夫をしています。
+
+ * フォントの色をグレーにして薄く表示する。
+ * フォントの種類を等幅でなくローマン体にする。
+
+
+=== 行番号を控えめに表示する
+
+行番号は、プログラムコードと同じフォント・同じ色で表示すべきではありません。
+行番号はあくまで脇役なので、主役であるプログラムコードよりも目立たないようにすべきです。
+
+Starterでは、行番号をグレー表示しているので、行番号がプログラムコードよりも目立たちません。
+
+//list[][][lineno=1,linenowidth=0]{
+function fib(n) {
+    if (n <= 1) {
+        return n;
+    } else {
+        return fib(n-1) + fib(n-2);
+    }
+}
+//}
+
+
+=== 行番号を考慮して長い行を折り返す
+
+長い行を自動的に折り返すとき、もし行番号があればそれを考慮した表示にすべきです。
+
+Starterではそのような表示になっています。
+
+//list[][][lineno=1,linenowidth=0]{
+if error:
+    sys.err.write("Something error raised. Please contact to system administrator.\n")
+//}
+
+この例を見ると、折り返した行が左端には行かず、行番号の表示スペースを避けて折り返されています。
+これが、行番号つき折り返しの望ましい姿です。
+
+これに対し、Re:VIEWでは折り返した行が左端に到達してしまい、行番号の表示スペースを侵食します。
+これは行番号つき折り返しの望ましくない姿です。
+
+
+==={subsec-programborder} ページまたぎしていることを可視化する
+
+プログラムコードがページまたぎしていることが分かるようにしましょう。
+
+ * プログラムコードに枠線がないと、ページまたぎしたときに次のページに続いているかどうか、次のページを見ないと分かりません（@<img>{program_border}左）。
+ * プログラムコードに枠線があれば、ページまたぎしても次のページに続いているかどうかが、次のページを見なくても分かります（@<img>{program_border}右）。
+
+//image[program_border][プログラムコードに枠線がない場合とある場合の違い][scale=1.0]
+
+Starterではデフォルトでプログラムコードに枠線がつきます。
+枠線をつけたくない場合は「@<file>{config-starter.yml}」の設定項目「@<code>{program_border:}」を「@<code>{false}」に設定します。
+
+なお、プログラムコードの背景枠の四隅を角丸にすることでも、ページまたぎしていることを可視化できます。
+
+
+=== インデントを可視化する
+
+PythonやYAMLではインデントでブロック構造を表すので、ブロックの終わりを表すキーワードや記号がありません。
+そのため、プログラムコードがページをまたぐとインデントが分からなくなる（つまりブロックの構造が分からなくなる）ことがあります。
+
+これを防ぐには、何らかの方法でインデントを可視化します。
+そうすると、プログラムコードがページをまたいでもインデントが分からなくなることはありません。
+
+Starterでは「@<code>|//list[][]@<b>{[indentwidth=4]}{ ... //}|」のようにすることで、インデントごとに薄い縦線をつけられます。
+
+//list[][薄い縦線をつけてインデントを可視化する][indentwidth=4]{
+class Fib:
+
+    def __call__(n):
+        if n <= 1:
+            return n
+        else:
+            return fib(n-1) + fib(n-2)
+//}
+
+
+
+== 図表
+
+=== 図表が次のページに送られてもスペースを空けない
+
+Re:VIEWではデフォルトで、図は現在位置に置かれるよう強制されます。
+もし現在位置に図を入れるスペースがない場合は、図は次のページに表示され、そのあとに本文が続きます。
+この仕様のせいで、たくさんのスペースが空いて本文がスカスカになってしまうことがあります（@<img>{figure_heretop}上）。
+
+これはよくないので、Starterでは図が次のページに送られた場合、後続の本文を現在位置に流し込みます。
+図が現在位置に入らないからといって、スペースを空けたままにする必要はありません（@<img>{figure_heretop}下）。
+
+//image[figure_heretop][後続の本文を現在位置に流し込むかどうか]
+
+
+=== 大きい図表は独立したページに表示する
+
+たとえば図がページの3/4を占めるようなら、そのページには後続のテキストを流しこまず、その図だけのページにしましょう。
+
+Starterだと「@<code>|//image[ファイル名][説明文][scale=1.0,@<b>{pos=p}]|」とすると、その図だけの独立したページに表示されます。
+
+
+=== 図表は番号で参照する
+
+図や表は、現在位置に入り切らないとき、自動的に次のページに送られます。
+その場合、たとえば「次の図を見てください」と書いてあると「次の図」がなくて読者が混乱します。
+
+そのため、図や表は必ず番号で参照してください。
+図なら「@<code>|@@<nop>{}<img>{ファイル名}|」、表なら「@<code>|@@<nop>{}<table>{ラベル}|」で参照します。
+
+
+=== 表のカラム幅を指定する
+
+表に長い文章を入れると、ページ横にはみ出してしまいます。
+
+このような場合は、「@<code>{//tsize[|latex|@<b>{p{70mm\}}]}」のようにカラムの幅を指定しましょう。
+
+//list[][サンプル]{
+/@<nop>$$/tsize[|latex||l|@<b>|p{70mm}||]
+/@<nop>$$/table[tbl-jqqu9][長いテキストを使ったサンプル]{
+伝承地		伝承内容
+-------------------------------------------
+風の谷		その者、蒼き衣を纏て金色の野に降り立つべし。失われた大地との絆を結び、ついに人々を清浄の地に導かん。
+ゴンドアの谷	リーテ・ラトバリタ・ウルス・アリアロス・バル・ネロリール
+/@<nop>$$/}
+//}
+
+//sampleoutputbegin[表示結果]
+
+//tsize[|latex||l|p{70mm}|]
+//table[tbl-jqqu9][長いテキストを使ったサンプル]{
+伝承地		伝承内容
+-------------------------------------------
+風の谷		その者、蒼き衣を纏て金色の野に降り立つべし。失われた大地との絆を結び、ついに人々を清浄の地に導かん。
+ゴンドアの谷	リーテ・ラトバリタ・ウルス・アリアロス・バル・ネロリール
+//}
+
+//sampleoutputend
+
+
+
+
+=== 表のカラムが数値なら右寄せにする
+
+表のカラムはデフォルトで左寄せ(l)ですが、右寄せ(r)や中央揃え(c)を指定できます。
+特にカラムが数値なら、右寄せにするのがいいでしょう。
+
+//list[][サンプル]{
+/@<nop>$$/tsize[|latex|@<b>{|l|c|r|}]
+/@<nop>$$/table[tbl-o599k][左寄せ・中央揃え・右寄せのサンプル]{
+左寄せ		中央揃え	右寄せ
+-------------------------------------------
+1		1		1
+10		10		10
+100		100		100
+1000		1000		1000
+/@<nop>$$/}
+//}
+
+//sampleoutputbegin[表示結果]
+
+//tsize[|latex||l|c|r|]
+//table[tbl-o599k][左寄せ・中央揃え・右寄せのサンプル]{
+左寄せ		中央揃え	右寄せ
+-------------------------------------------
+1		1		1
+10		10		10
+100		100		100
+1000		1000		1000
+//}
+
+//sampleoutputend
+
+
+
+
+
+== ページデザイン
+
+==={subsec-sidemargin} [PDF] 印刷用では左右の余白幅を充分にとる
+
+紙の書籍では、左右いっぱいに本文を印刷してはいけません。
+必ずページ左右の余白を充分に確保してください（@<img>{margin_book}）。
+
+ * 見開きにおいて内側の余白（つまり左ページの右余白と、右ページの左余白）は、最低20mm必要です。
+   それ以上切り詰めると、本を開いたときに内側の本文がとても読みにくくなります。
+ * 見開きにおいて外側の余白（つまり左ページの左余白と、右ページの右余白）は、10〜15mmくらい必要です。
+   それ以上切り詰めると、指が本文にかかってしまうので読みにくくなります。
+
+//image[margin_book][紙の書籍ではページ左右の余白幅が必要][scale=0.8]
+
+Starterではこのような制限を考慮しつつ、本文幅が最大になるよう設定しています。
+そのため、@<b>{印刷用PDFファイルでは奇数ページと偶数ページで左右の余白幅が違います}。
+これは意図した仕様でありバグではありません。
+
+電子用PDFファイルではこのようなことを考慮する必要はありません。
+そのため、電子用PDFでは左右の余白幅は同じです。
+
+
+=== [PDF] タブレット向けでは余白を切り詰める
+
+(TODO)
+
+
+=== 電子書籍ではページ番号の位置を揃える
+
+(TODO)
+
+
+=== 非Retina向けには本文をゴシック体にする
+
+Re:VIEWやStarterでは、本文のフォントを明朝体にしています。
+明朝体は、印刷物やRetinaディスプレイのように解像度が高いと読みやすいですが、Retinaでない（つまり高解像度でない）ディスプレイだと読みづらいです。
+
+スマートフォンやノートパソコンではRetinaディスプレイが普及しましたが、外部ディスプレイでは高解像度ではないものがまだ一般的です。
+
+もし高解像度でないディスプレイでも読みやすくしたいなら、本文をゴシック体にすることを検討しましょう。
+Starterでは「@<file>{config-starter.yml}」の設定を変えるだけで変更できます。
+詳しくは@<secref>{04-customize|subsec-fontfamily}を参照してください。
+
+
+
+== 大扉
+
+
+=== 長いタイトルでは改行箇所を明示する
+
+本や同人誌のタイトルが長いと、大扉（タイトルページ）において不自然な箇所で改行されてしまいます（@<img>{multiline-title}上）。
+
+これを防ぐために、Starterではタイトルを複数行で指定できるようになっています。
+この場合、大扉（タイトルページ）ではタイトルが1行ずつ表示されるので、自然な位置を指定して改行できます（@<img>{multiline-title}下）。
+
+//image[multiline-title][タイトルの改行位置を指定しなかった場合（上）とした場合（下）][scale=0.7,border=on]
+
+
+=== 大扉を別のソフトで作成する
+
+Re:VIEWやStarterが生成する大扉（タイトルページ）は、デザインがよくありません。
+PhotoshopやIllustratorやKeynoteで作成したほうが、見栄えのいいデザインになります（@<img>{titlepage-samples}）。
+
+//image[titlepage-samples][Keynoteで作成した大扉の例][scale=0.9]
+
+
+
+== 奥付
+
+
+=== 奥付は最後のページに置く
+
+紙の本は必ず偶数ページになります。
+たとえば、ページ数が100ページの本はあっても101ページの本はありません。
+そのため、本の最終ページも偶数ページになります。
+
+そして奥付は、本の最後のページに置きます。
+言い換えると、奥付は本の最後の偶数ページに置かれるはずです。
+しかし、このことが考慮されていない同人誌がたまにあります。
+
+実は素のRe:VIEWではこれが考慮されておらず、奥付が奇数ページに置かれることがあります@<fn>{fn-qzmgo}。
+Starterではこのようなことはありません。
+奥付は必ず最後の偶数ページに置かれるようになっています。
+
+//footnote[fn-qzmgo][TechBoosterのテンプレートでは偶数ページに置かれるように修正されています。]
+
+
+=== 奥付に更新履歴とイベント名を記載する
+
+奥付には、本の更新履歴が記載されるのが一般的です。
+
+同人誌ならそれに加えて、初出のイベント名も記載するといいでしょう。
+そうすると、どのイベントで手に入れたかが分かりやすくなります@<fn>{fn-ksg34}。
+
+//footnote[fn-ksg34][少なくとも新刊はこれが当てはまります。既刊だと当てはまりませんが、初出のイベント名が分かるだけでも読者の助けになります。]
+
+
+=== 利用した素材の作者とURLを奥付に記載する
+
+本の作成に使用した素材があれば、作者名とURLを奥付に記載するといいでしょう。
+
+たとえば表紙に写真やイラストを使ったのであれば、その作者と素材へのURLを奥付に記載しましょう。
+
+
+=== 利用したソフトウェアを奥付に記載する
+
+本や同人誌をどんなソフトウェアで作ったかを奥付に記載すると、他の人の参考になります。
+
+たとえば「InDesignで作った」「MS Word 2016で作った」「Pages 10.0で作った」「Vivliostyleで作った」という情報があると、これから本や同人誌を作ろうとする人にとって大きな手がかりとなります。
+
+またエディタに強いこだわりがある人なら「VS Codeで執筆した」「Vimで執筆した」のようにアピールするのもいいでしょう。