= チュートリアル //abstract{ 前の章では、RubyとTeXLiveのインストールを説明し、サンプルPDFファイルを生成しました。 この章では、自分で書いた原稿ファイルからPDFファイルを生成する方法を説明します。 なおこの章は、RubyとTeXLiveのインストールが済んでいること、またサンプルのPDFファイルが生成できたことを前提にしています。 まだの人は前の章を見てください。 //} #@#//makechaptitlepage[toc=on] =={sec-terminology} 用語の説明 このあとの説明で使用する用語を紹介します。 : Starter Re:VIEW Starterのことです。 「Re:VIEW Starter」はちょっと長いので、この文章では省略して「Starter」と呼んでいます。 : プロジェクトのzipファイル Re:VIEW StarterのWebサイトでプロジェクトを作ったときに、最後にダウンロードされるzipファイルのことです。 単に「zipファイル」と呼ぶこともあります。 : @{mybook.zip} 説明で使用するプロジェクトのzipファイル名です。 これはサンプルであり、実際にはたとえば「@{samplebook.zip}」だったり「@{brabra-book.zip}」だったりします。 : プロジェクトのフォルダ zipファイルを解凍したときにできるフォルダです。 たとえばzipファイル名が「@{mybook.zip}」なら、解凍してできるフォルダは「@{mybook/}」なので、これがプロジェクトのフォルダになります。 : 「@{mybook/}」フォルダ プロジェクトのフォルダのことです。 フォルダ名はあくまでサンプルであり、プロジェクトごとに異なることに注意してください。 : 原稿ファイル 原稿となるテキストファイルです。 これをもとにPDFファイルが生成されます。 原稿ファイルは拡張子が「@{.re}」なので、「@{*.re}ファイル」と呼ぶこともあります。 なお文字コードは必ずUTF-8にしてください。 : @{*.re}ファイル 原稿ファイルのことです。 拡張子が「@{.re}」なので、こう呼ばれることがあります。 : 「@{contents/}」フォルダ 原稿ファイルが置かれているフォルダです。 最近のRe:VIEW Starterでは、デフォルトで原稿ファイルを「@{contents/}」フォルダに置くことになっています（以前はプロジェクトのフォルダ直下に置かれていました）。 : テキストエディタ テキストファイルを作成したり変更するためのアプリケーションのことです。 単に「エディタ」と呼ぶこともあります。 有名なものだと「Visual Studio Code」「Atom」「Emacs」「Vim」「サクラエディタ」「秀丸」「メモ帳」などがあります。 : エディタ テキストエディタのことです。 : コンパイル 原稿ファイルからPDFファイルを生成することです。 Re:VIEW StarterではPDFだけでなくHTMLやePubのファイルも生成できるので、どの形式を生成するかを明示するなら「PDFへコンパイルする」「ePubへコンパイルする」などと言います。 == フォルダとファイルの説明 プロジェクトの「@{mybook.zip}」を解凍すると、数多くのファイルが作られます。 それらのうち、重要なものを選んで解説します。 すべてのファイルについての解説は@{92-filelist}を参照してください。 #@# : @{Gemfile} #@# @{gem}コマンドが使用します。通常は気にしなくていいです。 #@# : @{README.md} #@# プロジェクトの説明が書かれたファイルです。 #@# ユーザが好きなように上書きすることを想定しています。 #@# : @{Rakefile} #@# @{rake}コマンドが使用します。 #@# コマンドを追加する場合は、このファイルは変更せず、かわりに「@{lib/tasks/*.rake}」を変更してください。 : @{catalog.yml} 原稿ファイルが順番に並べられたファイルです。 原稿ファイルを追加した・削除した場合は、このファイルも編集します。 #@# : @{catalog.yml.orig} #@# Re:VIEWでのオリジナルファイルです。 : @{config-starter.yml} Starter独自の設定ファイルです。 Starterでは「@{cofnig.yml}」と「@{cofnig-starter.yml}」の両方を使います。 : @{config.yml} Re:VIEWの設定ファイルです。 Starterによりいくつか変更と拡張がされています。 #@# : @{config.yml.orig} #@# Re:VIEWでのオリジナルファイルです。 : @{contents/} 原稿ファイルを置くフォルダです@{fn-zuxns}。 : @{contents/*.re} 原稿ファイルです。 章(Chapter)ごとにファイルが分かれます。 #@# : @{css/} #@# HTMLファイルで使うCSSファイルを置くフォルダです。 : @{images/} 画像ファイルを置くフォルダです。 この下に章(Chapter)ごとのサブフォルダを作ることもできます。 #@# : @{layouts/layout.epub.erb} #@# 原稿ファイルからePubファイルを生成するためのテンプレートです。 #@# : @{layouts/layout.html5.erb} #@# 原稿ファイルからHTMLファイルを生成するためのテンプレートです。 #@# : @{layouts/layout.tex.erb} #@# 原稿ファイルからLaTeXファイルを生成するためのテンプレートです。 #@# : @{lib/hooks/beforetexcompile.rb} #@# LaTeXファイルをコンパイルする前に編集するスクリプトです。 #@# : @{lib/ruby/*.rb} #@# StarterによるRe:VIEWの拡張を行うRubyスクリプトです。 #@# : @{lib/ruby/mytasks.rake} #@# ユーザ独自のRakeコマンドを追加するためのファイルです。 #@# : @{lib/ruby/review.rake} #@# Re:VIEWで用意されているRakeタスクのファイルです。 #@# Starterによって変更や拡張がされています。 #@# : @{lib/ruby/review.rake.orig} #@# Starterによって変更や拡張がされる前の、オリジナルのタスクファイルです。 #@# : @{lib/ruby/starter.rake} #@# Starterが追加したRakeタスクが定義されたファイルです。 #@# : @{locale.yml} #@# 国際化用のファイルです。 #@# たとえば「リスト1.1」を「プログラム1.1」に変更したい場合は、このファイルを変更します。 #@# : @{mybook-epub/} #@# ePubファイルを生成するときの中間生成ファイルが置かれるフォルダです。 #@# 通常は気にする必要はありません。 : @{mybook-pdf/} PDFファイルを生成するときの中間生成ファイルが置かれるフォルダです。 @{}ファイルをデバッグするときに必要となりますが、通常は気にする必要はありません。 #@# : @{mybook.epub} #@# 生成されたePubファイルです。 #@# ファイル名はプロジェクトによって異なります。 : @{mybook.pdf} 生成されたPDFファイルです。 ファイル名はプロジェクトによって異なります。 : @{review-ext.rb} Re:VIEWを拡張するためのファイルです。 このファイルから「@{lib/ruby/*.rb}」が読み込まれています。 : @{sty/} @{}で使うスタイルファイルが置かれるフォルダです。 #@# : @{sty/jumoline.sty} #@# @{}で使うスタイルファイルのひとつです。 : @{sty/mycolophon.sty} 奥付@{fn-7ypmf}の内容が書かれたスタイルファイルです。 奥付を変更したい場合はこのファイルを編集します。 : @{sty/mystyle.sty} ユーザが独自に@{}マクロを定義・上書きするためのファイルです。 中身は空であり、ユーザが自由に追加して構いません。 : @{sty/mytextsize.sty} PDFにおける本文の高さと幅を定義したファイルです。 @{}では最初に本文の高さと幅を決める必要があるので、他のスタイルファイルから分離されてコンパイルの最初に読み込めるようになっています。 : @{sty/mytitlepage.sty} 大扉@{fn-cq9ws}の内容が書かれたスタイルファイルです。 大扉のデザインを変更したい場合はこのファイルを編集します。 : @{sty/starter*.sty} Starter独自のスタイルファイルです。 ここに書かれた@{}マクロを変更したい場合は、このファイルを変更するよりも「@{sty/mystyle.sty}」に書いたほうがバージョンアップがしやすくなります。 #@# : @{sty/starter-headline.sty} #@# 章(Chapter)や節(Section)や項(Subsection)の@{}マクロが定義されたファイルです。 //footnote[fn-zuxns][原稿ファイルを置くフォルダ名は「@{config.yml}」の「@|contentdir: contents|」で変更できます。] //footnote[fn-7ypmf][@{奥付}とは、本のタイトルや著者や出版社や版や刷などの情報が書かれたページのことです。通常は本のいちばん最後のページに置かれます。] //footnote[fn-cq9ws][@{大扉}とは、タイトルページのことです。表紙のことではありません。] == 原稿の追加と変更 原稿の追加と変更の方法を説明します。 原稿の追加より変更のほうが簡単なので、変更する方法を先に説明します。 === 既存の原稿ファイルを変更する プロジェクトのフォルダには、サンプルとなる原稿ファイルが存在します。 まずはこれを変更してみましょう。 - (1) まず、お好みのテキストエディタを使って「@{mybook/contents/00-preface.re}」を開いてください。 - (2) 次に、先頭の「@{= はじめに}」の下に何か適当なテキストを追加して（例：@{6f3fh}）、原稿ファイルを保存してください。 - (3) 原稿ファイルを保存したら、コンパイル@{fn-r19pw}しましょう。 MacならTerminal.app@{f90kk}、Windowsならコマンドプロンプトを開き、「@{rake pdf}」（またはDockerを使っているなら「@{rake docker:pdf}」）を実行してください。 //footnote[fn-r19pw][「コンパイル」とは、ここでは原稿ファイルからPDFファイル（またはHTMLやePub）を生成することです。このあとも使う用語なので覚えてください。また用語については@{sec-terminology}も参照してください。] //list[6f3fh][原稿ファイルの内容]{ = はじめに @{見ろ、人がゴミのようだ！} @{追加} ...（以下省略）... //} //footnote[f90kk][Terminal.appは、ファインダで「アプリケーション」フォルダ > 「ユーティリティ」フォルダ > 「ターミナル」をダブルクリックすると起動できます。] これで新しいPDFファイルが生成されるはずです。 生成された新しいPDFファイルを開き、さきほど追加した行が「はじめに」の章に表示されていることを確認してください。 //note[プロジェクトのフォルダに原稿ファイルがあるとコンパイルエラー]{ Starterのデフォルトでは、原稿ファイル(@{*.re})を「@{contents/}」フォルダに置くよう設定されています。 この場合、もし原稿ファイルがプロジェクトのフォルダ（たとえば「@{mybook/}」の直下）にあると、コンパイル@{fn-zt1bb}できずエラーになります。 エラーになるのは、Starterの仕組みに起因します。 Starterではコンパイル時に、「@{contents/}」に置かれた原稿ファイル（@{*.re}）をプロジェクトフォルダの直下にコピーしてからコンパイルします）@{fn-g6oit}。 そのため、プロジェクトフォルダ直下に別の原稿ファイルがあるとコンパイル時に上書きしてしまう可能性があるため、あえてエラーにしているのです。 //footnote[fn-zt1bb][@{コンパイル}とは、ここでは原稿ファイルからPDFファイルを生成することを指します。] //footnote[fn-g6oit][Re:VIEW 2.5の仕様上、コンパイル時に原稿ファイルがプロジェクトフォルダの直下にないといけないため。] //} ここまでが、既存の原稿ファイルを変更する方法でした。 次に、新しい原稿ファイルを追加する方法を説明します。 === 新しい原稿ファイルを追加する 新しい原稿ファイルを追加するには、次のようにします。 - (1) 新しい原稿ファイルを作成する。 - (2) 作成した原稿ファイルをプロジェクトに登録する。 - (3) PDFファイルを生成し、原稿の内容が反映されることを確認する。 順番に説明しましょう。 ===== (1) 新しい原稿ファイルを作成する お好みのテキストエディタを使って、新しい原稿ファイル「@{01-test.re}」を作成します。 このとき、次の点に注意してください。 * 原稿ファイルの拡張子は「@{.re}」にします。 * 原稿ファイルの置き場所は「@{contents/}」フォルダにします。 つまりファイルパスは「@{mybook/contents/01-test.re}」になります。 * 原稿ファイルの文字コードは「UTF-8」にします。 新しい原稿ファイル「@{contents/01-test.re}」の中身は、たとえば@{wrmlp}のようにしてください。 //list[wrmlp][原稿ファイル「@{contents/01-test.re}」]{ @{}= サンプル章タイトル @{}//abstract{ 概要概要概要 @{}//} @{}== サンプル節タイトル 本文本文本文 //} //note[原稿ファイルに番号をつけるべきか]{ この例では原稿ファイル名を「@{01-test.re}」にしました。 しかしファイル名に「@{01-}」のような番号は、必ずしもつける必要はありません（つけてもいいし、つけなくてもいい）。 ファイル名に番号をつけるのは、利点と欠点があります。 * 利点は、MacのファインダやWindowsのエクスプローラで表示したときに、ファイルが章の順番に並ぶことです。 * 欠点は、章の順番を入れ替えるときにファイル名の変更が必要なこと、またそれにより章ID@{fn-9yivn}が変わるのでその章や節を参照している箇所もすべて変更になることです。 番号をつけていない場合は、「@{catalog.yml}」での順番を入れ替えるだけで済み、参照箇所も修正する必要はありません。 //footnote[fn-9yivn][章IDについては@{03-syntax|subsec-chapterid}で説明します。] 自分の好きなほうを選んでください。 //} ===== (2) 原稿ファイルをプロジェクトに登録する 次に、作成した原稿ファイルをプロジェクトに登録しましょう。 プロジェクトのフォルダにある「@{catalog.yml}」をテキストエディタで開き、@{g9t1b}のように変更してください。 なお、このファイルでは「@{#}」以降は行コメントであり読み飛ばされます。 //list[g9t1b][ファイル「@{catalog.yml}」]{ PREDEF: - 00-preface.re CHAPS: @{- 01-install.re} @{この行を削除} @{- 01-test.re} @{この行を追加} - 02-tutorial.re APPENDIX: POSTDEF: - 99-postface.re ## ## ■Tips ## ...（以下省略）... //} ファイルを変更したら、忘れずに保存してください。 これで、新しい原稿ファイルがプロジェクトに登録できました。 ===== (3) PDFファイルを生成し、原稿の内容が反映されたか確認する 試しにPDFファイルを生成してみましょう。 MacならTerminal.app、Windowsならコマンドプロンプトを開き、次のコマンドを実行してください。 //terminal[][PDFファイルを生成する]{ $ @{rake pdf} @{Dockerを使っていない場合} $ @{rake docker:pdf} @{Dockerを使っている場合} //} 新しいPDFファイルが生成されるので、表示してみてください。 新しい原稿ファイルの章が追加されていれば成功です。 === 「@{catalog.yml}」の説明 「@{catalog.yml}」の内容は次のような構造になっています。 * 「@{PREDEF:}」は「まえがき」を表します。 * 「@{CHAPS:}」は本文を表します。 * 「@{APPENDIX:}」は付録を表します。 * 「@{POSTDEF:}」は「あとがき」を表します。 //list[][ファイル「@{catalog.yml}」]{ @{PREDEF:} - 00-preface.re @{まえがきの章} @{CHAPS:} - 01-install.re @{本文の章} - 02-tutorial.re @{本文の章} - 03-syntax.re @{本文の章} @{APPENDIX:} - 92-filelist.re @{付録の章} @{POSTDEF:} - 99-postfix.re @{あとがきの章} //} また次のような点に注意してください。 * まえがきや付録やあとがきは、なければ省略できます。 * まえがきとあとがきには、章番号や節番号がつきません。 * 目次はまえがきのあとに自動的につけられます@{fn-qyuwz}。 * 大扉（タイトルページ）や奥付も自動的につけられます@{fn-fa6pt}。 //footnote[fn-qyuwz][目次をつけたくない場合は、「@{config.yml}」に「@{toc: false}」を設定してください。] //footnote[fn-fa6pt][大扉をつけたくない場合は、「@{config.yml}」に「@{titlepage: false}」を設定してください。また奥付をつけたくない場合は「@{colophon: false}」を設定してください。] //note[YAML形式]{ 「@{catalog.yml}」の内容は、「YAML」という形式で書かれています。 YAMLについてはGoogle検索で調べてください。 ここでは3点だけ注意点を紹介します。 * タブ文字を使わないこと。 * 「@{-}」のあとに半角空白をつけること。 * 「@{#}」以降は行コメントとして読み飛ばされる。 //} ==={subsec-compileerror} コンパイルエラーになったら PDFファイルの生成がエラーになったら、以下の点を確認してください。 * インライン命令がきちんと閉じているか * ブロック命令の引数が足りているか、多すぎないか * 「@|//}|」が足りてないか、または多すぎないか * 「@|@@{}{}|」や「@|@@{}{}|」や「@|@@{}{}|」のラベルが合っているか * 「@|@@{}{}|」で指定した章IDが合っているか * 「@|@@{}{}|」で指定した節や項が存在するか * 脚注の中で「@{]}」を「@{\]}」とエスケープしているか * 「@|//image|」で指定した画像ファイルが存在するか * 原稿ファイル名を間違っていないか * 原稿ファイルの文字コードがUTF-8になっているか 詳しくは@{05-faq|sec-compileerror}を見てください。 それでもエラーになる場合は、中間ファイルを削除してみましょう。 たとえばプロジェクト名が「@{mybook}」だったら、「@{mybook-pdf}」というフォルダが作られているはずです。 これを削除してから、コンパイルし直してみてください。 //terminal[][中間ファイルを削除してコンパイルし直す]{ $ @{rm -rf mybook-pdf} @{中間ファイルを削除して、} $ @{rake pdf} @{コンパイルし直す} //} それでもダメなら、「@{https://twitter.com/search?q=%23reviewstarter, #reviewstarter}」というタグでツイートしていただければ、相談に乗ります。 === 文章をチェックする Starterでは、「textlint」というツールを使って原稿の文章をチェックできます。 たとえば「Starterを使うときれいなPDFを作成@{することが}できます」という文章は、「Starterを使うときれいなPDFを作成@{できます}」のように簡潔にできます。 このような指摘を行ってくれるのがtextlintです。 textlintをStarterのプロジェクトで使う方法は、@{06-bestpractice|sec-textlint}で解説しています。 今はまだtextlintを使う必要はありませんが、Starterに慣れてきたら使ってみてください。 =={sec-basicsyntax} 基本的な記法 原稿ファイルは、ある決まった書き方（記法）に従って記述します。 たとえば、次のような記法があります。 * 章(Chapter)は「@{= }」で始め、節(Section)は「@{== }」で始める。 * 箇条書きは「@{ * }」で始める。 * プログラムコードは「@|//list{...//}|」で囲う。 * 強調は「@|@@{}{...}|」または「@|@@{}{...}|」で囲う。 ここでは記法のうち基本的なものを説明します。 詳しいことは@{03-syntax}で説明します。 === コメント 行コメントは「@{#@#}」で、また範囲コメントは「@{#@+++}」と「@{#@---}」で表します。 どちらも行の先頭から始まってないと、コメントとして認識されません。 //list[][サンプル][]{ 本文1。 @|#@#|本文2。 本文3。 @|#@+++| 本文4。 @|#@---| 本文5。 //} //sampleoutputbegin[表示結果] 本文1。 #@#本文2。 本文3。 #@+++ 本文4。 #@--- 本文5。 //sampleoutputend 詳しくは@{03-syntax|sec-comment}を参照してください。 === 段落と改行 空行があると、新しい段落になります。 改行は無視されるか、または半角空白扱いになります。 通常は1文ごとに改行して書きます。 //list[][サンプル][]{ 言葉を慎みたまえ。君はラピュタ王の前にいるのだ。 これから王国の復活を祝って、諸君にラピュタの力を見せてやろうと思ってね。 見せてあげよう、ラピュタの雷を！ 旧約聖書にあるソドムとゴモラを滅ぼした天の火だよ。 ラーマヤーナではインドラの矢とも伝えているがね。 //} //sampleoutputbegin[表示結果] 言葉を慎みたまえ。君はラピュタ王の前にいるのだ。 これから王国の復活を祝って、諸君にラピュタの力を見せてやろうと思ってね。 見せてあげよう、ラピュタの雷を！ 旧約聖書にあるソドムとゴモラを滅ぼした天の火だよ。 ラーマヤーナではインドラの矢とも伝えているがね。 //sampleoutputend 詳しくは@{03-syntax|sec-paragraph}を参照してください。 === 見出し 章(Chapter)や節(Section)といった見出しは、「@{= }」や「@{== }」で始めます。 また章には概要を書くといいでしょう。 //list[][サンプル][]{ @|=| 章(Chapter)見出し @|//abstract{| 章の概要。 @|//}| @|==| 節(Section)見出し @|===| 項(Subsection)見出し @|====| 目(Subsubsection)見出し @|=====| 段(Paragraph)見出し @|======| 小段(Subparagraph)見出し //} Starterでは、章(Chapter)は1ファイルにつき1つだけにしてください。 1つのファイルに複数の章(Chapter)を入れないでください。 見出しについての詳細は@{03-syntax|sec-heading}を参照してください。 === 箇条書き 番号なし箇条書きは「@{ * }」で始めます（先頭に半角空白が必要）。 //needvspace[latex][6zw] //list[][サンプル][]{ @| * |箇条書き1 @| * |箇条書き2 @| ** |入れ子の箇条書き @| *** |入れ子の入れ子 //} //sampleoutputbegin[表示結果] * 箇条書き1 * 箇条書き2 ** 入れ子の箇条書き *** 入れ子の入れ子 //sampleoutputend 番号つき箇条書きは「@{ 1. }」のように始める方法と、「@{ - A. }」のように始める方法があります（どちらも先頭に半角空白が必要）。 後者では番号の自動採番はされず、指定された文字列がそのまま出力されます。 //list[][サンプル][]{ @|1.| この記法では数字しか指定できず、 @|2.| また入れ子にもできない。 @|- (A)| この記法だと、英数字だけでなく @|- (B)| 任意の文字列が使える @|-- (B-1)| 入れ子もできるし、 @|***| 番号なし箇条書きも含められる //} //sampleoutputbegin[表示結果] 1. この記法では数字しか指定できず、 2. また入れ子にもできない。 - (A) この記法だと、英数字だけでなく - (B) 任意の文字列が使える -- (B-1) 入れ子もできるし、 *** 番号なし箇条書きも含められる //sampleoutputend 箇条書きの詳細は@{03-syntax|sec-list}を参照してください。 === 用語リスト 用語リスト（HTMLでいうところの「@{
}」）は、「@{ : }」で始めて@{axm3t}、次の行からインデントします@{diwmv}。 //footnote[axm3t][先頭の半角空白は入れるようにしましょう。過去との互換性のため、先頭の半角空白がなくても動作しますが、箇条書きとの整合性のために半角空白を入れることを勧めます。] //footnote[diwmv][説明文のインデントは、半角空白でもタブ文字でもいいです。] //list[][サンプル][]{ @| : |用語1 説明文。 説明文。 @| : |用語2 説明文。 説明文。 //} //sampleoutputbegin[表示結果] : 用語1 説明文。 説明文。 : 用語2 説明文。 説明文。 //sampleoutputend 詳しくは@{03-syntax|sec-termlist}を参照してください。 === 太字と強調 太字は「@|@@{}{...}|」で囲み、強調は「@|@@{}{...}|」または「@|@@{}{...}|」で囲みます。 強調は、太字になるだけでなくフォントがゴシック体になります。 //list[][サンプル][]{ テキスト@|@@$${|テキスト@|}|テキスト。 テキスト@|@@$${|テキスト@|}|テキスト。 //} //sampleoutputbegin[表示結果] テキスト@{テキスト}テキスト。 テキスト@{テキスト}テキスト。 //sampleoutputend 日本語の文章では、強調するときは太字のゴシック体にするのがよいとされています。 なので強調には「@|@@{}{...}|」または「@|@@{}{...}|」を使い、「@|@@{}{...}|」は使わないでください。 強調や太字などテキストの装飾についての詳細は@{03-syntax|sec-decoration}を参照してください。 //note[インライン命令]{ 「@|@@{}{...}|」のような記法は@{インライン命令}と呼ばれます。 インライン命令は入れ子にできますが（Starterによる拡張）、複数行を含めることはできません。 詳細は@{03-syntax|subsec-inlinecmd}を見てください。 #@#インライン命令は入れ子にできます（Starterによる拡張）。 #@#たとえば「@|@@{}{fn(@@{}{@@{}{arg}})}|」と書くと「@{fn(@{@{arg}})}」のように表示されます。 #@# #@#またインライン命令は必ず1行に記述します。 #@#複数行を含めることはできません。 #@# #@#//list[][このような書き方はできない]{ #@#@|@@{}{|テキスト #@#テキスト #@#テキスト@|}| #@#//} //} === 等幅フォント 文字列を等幅フォントで表示するには、「@|@@{}{...}|」を使います。 ただしこれを使うことはお勧めしません。 それよりも、それぞれの用途に合ったインライン命令を使いましょう。 * プログラムコードやコマンド文字列を表すには「@|@@{}{...}|」を使ってください。 * ファイル名を表すには「@|@@{}{...}|」を使ってください。 === プログラムリスト プログラムリストは「@|//list[ラベル][説明文]{ ... //}|」で囲みます。 * ラベルは、他と重複しない文字列にします。 * 「@|@@{}{ラベル名}|」のようにプログラムリストを参照できます。 * 説明文に「@{]}」を含める場合は、「@{\]}」のようにエスケープします。 //list[][サンプル][]{ サンプルコードを@|@@$${fib1}|に示します。 @|//list[fib1][フィボナッチ数列]|{ def fib(n): return n if n <= 1 else fib(n-1) + fib(n-2) @|//}| //} //sampleoutputbegin[表示結果] サンプルコードを@{fib1}に示します。 //list[fib1][フィボナッチ数列]{ def fib(n): return n if n <= 1 else fib(n-1) + fib(n-2) //} //sampleoutputend 第1引数と第2引数のどちらも、省略できます。 たとえば第1引数だけを省略するには「@|//list[][説明]{|」のようにします。 両方とも省略するには「@|//list[][]{|」または「@|//list{|」のようにします。 またプログラムリストの中で、インライン命令が使えます。 たとえば次の例では、追加した箇所を「@|@@{}{...}|」で@{0hz8w}、削除した箇所を「@|@@{}{...}|」で表しています。 //footnote[0hz8w][プログラムリストの中では、「@|@@{}{}|」（強調）ではなく「@|@@{}{}|」（太字）を使ってください。なぜなら、「@|@@{}{}|」を使うとフォントが等幅フォントからゴシック体に変更されてしまい、表示がずれてしまうからです。] //list[][サンプル][]{ /@$$/list{ function fib(n) { @{@@$$|}if (n <= 1) { return n; }@{|} @{@@$$|}else { return fib(n-1) + fib(n-2); }@{|} @{@@$$|}return n <= 1 ? n : fib(n-1) + fib(n-2);@{|} } /@$$/} //} //sampleoutputbegin[表示結果] //list{ function fib(n) { @|if (n <= 1) { return n; }| @|else { return fib(n-1) + fib(n-2); }| @|return n <= 1 ? n : fib(n-1) + fib(n-2);| } //} //sampleoutputend その他、行番号をつけたり外部ファイルを読み込んだりできます。 プログラムコードについての詳細は@{03-syntax|sec-program}を参照してください。 また出力結果を表す「@|//output|」という命令もあります。 詳細は@{03-syntax|subsec-output}を参照してください。 //note[ブロック命令]{ 「@|//list{ ... //}|」のような形式の命令を、@{ブロック命令}といいます。 ブロック命令は入れ子にできますが（Starterによる拡張）、できないものもあります。 詳細は@{03-syntax|subsec-blockcmd}を見てください。 //} === ターミナル画面 ターミナル（端末）の画面は、「@|//terminal{ ... //}|」を使います。 次の例では、引数にラベル名と説明文字列を指定します。 また「@|@@{}{...}|」はユーザ入力を表します。 //list[][サンプル][]{ @|//terminal[term-1][PDFを生成]{| $ @@$${rake pdf} @@$${Dockerを使わない場合} $ @@$${rake docker:pdf} @@$${Dockerを使う場合} @|//}| //} //sampleoutputbegin[表示結果] //terminal[term-1][PDFを生成]{ $ @{rake pdf} @{Dockerを使わない場合} $ @{rake docker:pdf} @{Dockerを使う場合} //} //sampleoutputend ラベル名を指定していれば、プログラムリストと同じように「@|@@{}{ラベル名}|」で参照できます。 またラベル名と説明文字列はどちらも省略可能です。 どちらも省略すると「@|//terminal{ ... //}|」のように書けます。 詳しくは@{03-syntax|sec-terminal}を参照してください。 === 脚注 脚注は、脚注をつけたい箇所に「@|@@{}{ラベル}|」をつけ、段落の終わりに「@|//footnote[ラベル][脚注文]|」を書きます。 脚注文の中では「@|]|」を「@|\]|」と書いてください。 //list[][サンプル][]{ 本文テキスト@|@@$${fn-12}|。 @|//footnote[fn-12][このように脚注文を書きます。]| //} //sampleoutputbegin[表示結果] 本文テキスト@{fn-12}。 //footnote[fn-12][このように脚注文を書きます。] //sampleoutputend === 図 図を入れるには、「@|//image[画像ファイル名][説明文][オプション]|」を使います。 * 画像ファイルは「@{images/}」フォルダに置きます。 * 画像ファイルの拡張子は指定しません。 * ラベルを使って「@|@@{}{ラベル}|」のように参照できます。 //list[][サンプル][]{ @|//image[tw-icon][サンプル画像][scale=0.3]| //} //sampleoutputbegin[表示結果] //image[tw-icon][サンプル画像][scale=0.3] //sampleoutputend Starterでは、画像を入れる位置を指定したり、画像の周りに枠線をつけたりできます。 詳しくは@{03-syntax|sec-image}を参照してください。 === ノート Starterでは、本文を補足する文章を「ノート」という囲み枠で表します。 //list[][サンプル][]{ @|//note|[ムスカの苦手なもの]{ 実は、ムスカには「虫が苦手」という公式な設定があります。 有名な『読める、読めるぞ！』のシーンでムスカが顔の周りに群がるハエを追い払うのは、邪魔だったからだけでなく、虫が苦手だったからです。 /@$$/} //} //sampleoutputbegin[表示結果] //note[ムスカの苦手なもの]{ 実は、ムスカには「虫が苦手」という公式な設定があります。 有名な『読める、読めるぞ！』のシーンでムスカが顔の周りに群がるハエを追い払うのは、邪魔だったからだけでなく、虫が苦手だったからです。 //} //sampleoutputend ノート本文には箇条書きやプログラムコードを埋め込めます。 詳しくは@{03-syntax|sec-note}を参照してください。 また、補足情報や注意喚起や警告を表す囲み枠もあります。 詳しくは@{03-syntax|subsec-miniblock}を参照してください。 //list[][サンプル][]{ @|//info|[解決のヒント]{ 本製品を手に取り、古くから伝わるおまじないを唱えてみましょう。 すると天空の城への門が開きます。 /@$$/} @|//caution|[使用上の注意]{ 本製品を石版にかざすと、天空の城から雷が発射されます。 周りに人がいないことを確かめてから使用してください。 /@$$/} @|//warning|[重大な警告]{ 本製品を持ったまま滅びの呪文を唱えると、天空の城は自動的に崩壊します。 大変危険ですので、決して唱えないでください。 /@$$/} //} //sampleoutputbegin[表示結果] //info[解決のヒント]{ 本製品を手に取り、古くから伝わるおまじないを唱えてみましょう。 すると天空の城への門が開きます。 //} //caution[使用上の注意]{ 本製品を石版にかざすと、天空の城から雷が発射されます。 周りに人がいないことを確かめてから使用してください。 //} //warning[重大な警告]{ 本製品を持ったまま滅びの呪文を唱えると、天空の城は自動的に崩壊します。 大変危険ですので、決して唱えないでください。 //} //sampleoutputend === 表 表は、次のように書きます。 * 「@|//table[ラベル][説明文]{ ... //}|」で囲みます。 * セルは1つ以上のタブで区切ります。 * ヘッダの区切りは「@{-}」または「@{=}」を12個以上並べます。 * ラベルを使って「@|@@{}
{ラベル}|」のように参照できます。 //list[][サンプル][]{ @|//table[tbl-31][サンプル表]{| Name Val1 Val2 @|--------------------| AA 12 34 BB 56 78 @|//}| //} //sampleoutputbegin[表示結果] //table[tbl-31][サンプル表]{ Name Val1 Val2 -------------------- AA 12 34 BB 56 78 //} //sampleoutputend PDFではセルの右寄せ・左寄せ・中央揃えができます。 またCSVファイルからデータを読み込めます。 詳しくは@{03-syntax|sec-table}を参照してください。 === 数式 @{}の書き方を使って数式を記述できます。 //list[][サンプル][]{ @|//texequation[euler][オイラーの公式]{| e^{i\theta} = \sin{\theta} + i\cos{\theta} @|//}| @|@@$$$\theta = \pi$|のときは@|@@$$$e^{i\pi} = -1$|となり、これはオイラーの等式と呼ばれます。 //} //sampleoutputbegin[表示結果] //texequation[euler][オイラーの公式]{ e^{i\theta} = \sin{\theta} + i\cos{\theta} //} @$\theta = \pi$のときは@$e^{i\pi} = -1$となり、これはオイラーの等式と呼ばれます。 //sampleoutputend 詳しくは@{03-syntax|sec-mathexpr}を参照してください。 === 会話形式 Starterでは、会話形式も書けます。 会話形式は、アイコン画像を使う方法と使わない方法があります。 //list[][サンプル][]{ @|//talklist{| @|//talk[avatar-b]|{ あの方は何も盗らなかったわ。私のために闘ってくださったんです。 /@$$/} @|//talk[avatar-g]|{ いや、ヤツはとんでもないものを盗んでいきました…… あなたの心です。 /@$$/} @|//}| //} //sampleoutputbegin[表示結果] //talklist{ //talk[avatar-b]{ あの方は何も盗らなかったわ。私のために闘ってくださったんです。 //} //talk[avatar-g]{ いや、ヤツはとんでもないものを盗んでいきました…… あなたの心です。 //} //} //sampleoutputend //list[][サンプル][]{ @|//talklist{| @|//talk[][クラリス]|{ あの方は何も盗らなかったわ。私のために闘ってくださったんです。 /@$$/} @|//talk[][銭形警部]|{ いや、ヤツはとんでもないものを盗んでいきました…… あなたの心です。 /@$$/} @|//}| //} //sampleoutputbegin[表示結果] //talklist{ //talk[][クラリス]{ あの方は何も盗らなかったわ。私のために闘ってくださったんです。 //} //talk[][銭形警部]{ いや、ヤツはとんでもないものを盗んでいきました…… あなたの心です。 //} //} //sampleoutputend 詳しくは@{03-syntax|sec-talk}を参照してください。 //note[白黒印刷でも判別できる画像を使う]{ このサンプルでは、色が違うだけのアイコン画像を使っています。 そのせいで、白黒印刷すると誰が誰だか判別できなくなります。 もし白黒印刷するなら、色に頼らず判別できるようなアイコン画像を使いましょう。 //} //needvspace[latex][4zw] //note[会話形式にしても分かりやすくはならない]{ @{会話形式を採用しても、説明が分かりやすくなるとは限りません。} 会話形式にすると楽しさや親しみやすさを向上できますが、それは説明の分かりやすさとは違います。 会話形式だけど説明がよく分からない本はたくさんあります。 先生役や先輩役のキャラクターが何かの説明をして、それが読者には伝わっていないのに、生徒役や後輩役のキャラクターが「なるほど！」とか「そういうことか！」と言っているような本、見たことありませんか？ 先生や先輩の説明を苦もなく理解できるほどの優秀な生徒や後輩は、本の中にしかいません。 同様のことはマンガ形式にもいえます。 分かりやすく説明したいなら分かりやすく説明する技術を学ぶべきであり、マンガにしたり会話形式にすることではありません。 たとえば、『@{https://www.c-r.com/book/detail/1108, わかばちゃんと学ぶ　Git使い方入門}』が分かりやすいのはマンガだからではなく、分かりやすく説明する技術を作者の湊川先生が身につけているからです@{fn-pwgc3}。 @{分かりやすく説明できる人がたまたまマンガで説明しているから分かりやすいのであって、マンガや会話形式にすれば何でも分かりやすくなるわけではありません。} ここを履き違えないようにしましょう。 //} //footnote[fn-pwgc3][@{https://www.youtube.com/watch?v=t2eiA2ylNW0, 湊川先生による文章改善の発表動画}を見ると、分かりやすく説明する技術を先生自身が持っていることがよく分かります。] === 用語、索引 用語は「@|@@{}{用語名((よみかた))}|」のように書くとゴシック体で表示され、かつ本の巻末の索引に載ります。 ゴシック体にするけど索引に載せないなら「@|@@{}{用語名}|」、ゴシック体にせず索引に載せるなら「@|@@{}{用語名((よみかた))}|」、索引に載せるけど表示はしないなら「@|@@{}{用語名((よみかた))}|」とします。 索引は、デフォルトではオフになっています。 索引を使うには、@{config.yml}で「@|makeindex: true|」を設定してください（370行目ぐらいにあります）。 索引は@{}の機能を使うので、今のところPDFでしかサポートされません。 また索引機能をオンにすると@{}のコンパイル回数が増えるので、コンパイル時間が延びます。 原稿執筆中はオフにし、完成間近になったらオンにするといいでしょう。 なお索引に登録する用語が何もない場合は、索引を使おうとするとコンパイルエラーになります。 本文に1つでも「@|@@{}{}|」や「@|@@{}{}|」を入れてから索引機能を有効化してください。 Starterでは索引語の親子関係を指定したり、ページ番号のかわりに「〜を見よ」と指定できます。 詳しくは@{03-syntax|sec-term}を参照してください。 === 単語展開 キーを単語に展開できます。 たとえば辞書ファイル「@{data/words.txt}」の中に、キー「apple」に対応した単語「アップル」が登録されているとします。 すると、本文に「@|@@{}{apple}|」と書くと「アップル」に展開されます。 「@|@@{}{apple}|」なら展開して太字になります。 また「@|@@{}{apple}|」なら展開して強調表示します。 #@#「@|@@{}{apple}|」なら展開して太字になります（「@|@@{}{@@{}{apple}}|」と同じです）。 #@#また「@|@@{}{apple}|」なら展開して強調表示します（「@|@@{}{@@{}{apple}}|」と同じです）。 この機能は、表記が定まっていない単語に使うと便利です。 たとえば「Apple」と「アップル」のどちらの表記にするか悩んでるなら、本文には `@{apple}` と書いておけば、あとから辞書の中身を変えるだけでどちらの表記にも対応できます。 詳しくは@{03-syntax|sec-words}を参照してください。 =={sec-pdftype} 印刷用PDFと電子用PDF Starterでは、印刷用と電子用とを切り替えてPDFファイルを生成できます。 両者の違いはあとで説明するとして、まず印刷用と電子用のPDFファイルを生成する方法を説明します。 === 印刷用と電子用を切り替えてPDFを生成する Starterでは、印刷用と電子用とを切り替えてPDFを生成できます（デフォルトは印刷用）。 具体的には次のどれかを行います@{fn-0xkt4}。 * 「@|rake pdf @{t=pbook}|」を実行すると印刷用PDFが生成され、「@|rake pdf @{t=ebook}|」@{fn-3pf5z}を実行すると電子用PDFが生成される。 * 環境変数「@{$STARTER_TARGET}」を「@|pbook|」に設定してから「`rake pdf`」を実行すると印刷用PDFが生成され、「@|ebook|」に設定してから実行すると電子用PDFが生成される。 * 「@{config-starter.yml}」に設定項目「@{target:}」があるので、これを「@{pbook}」（印刷用）または「@{ebook}」（電子用）に設定する。 //footnote[fn-0xkt4][強制力はこの順序であり、設定ファイルより環境変数のほうが、また環境変数より`rake`コマンドのオプションのほうが優先されます。] //footnote[fn-3pf5z][「@{pbook}」は「printing book」、「@{ebook}」は「electronic book」を表します。] //terminal[][macOSやLinuxの場合@{fn-3pf5z}]{ $ @{rake pdf @{t=pbook}} @{印刷用PDFを生成} $ @{rake pdf @{t=ebook}} @{電子用PDFを生成} ## または $ @{@{export STARTER_TARGET=pbook}} @{印刷用に設定} $ @{rake pdf} @{またはDockerを使うなら rake docker:pdf} $ @{@{export STARTER_TARGET=ebook}} @{電子用に設定} $ @{rake pdf} @{またはDockerを使うなら rake docker:pdf} //} Windowsの場合は、「@{set STARTER_TARGET=pbook}」や「@{set STARTER_TARGET=ebook}」を使って環境変数を設定してください。 環境変数を未設定に戻すには、次のようにします。 //terminal[][macOSやLinuxの場合]{ $ @{@{unset STARTER_TARGET}} @{環境変数を未設定に戻す} //} === 印刷用PDFと電子用PDFの違い 印刷用PDFと電子用PDFには、次のような違いがあります。 : カラー 印刷用では、カラーは使われず白黒になります（画像は除く）。@
{} 電子用では、カラーが使われます@{fn-8w0hm}。 : 左右の余白幅 印刷用では、左右の余白幅が異なります。 具体的には、見開きにおいて内側の余白を約2cm、外側の余白を約1.5cmにしています@{fn-yuyf5}。 これは見開きでの読みやすさを確保したうえで本文幅をできるだけ広げるための工夫です。@
{} 電子用では見開きを考慮する必要がないので、左右の余白幅は同じに設定されます。 : ノンブル 印刷用には自動的にノンブルがつき、電子用にはつきません。 「ノンブル」とはすべてのページにつけられる通し番号であり、印刷所に入稿するときに必要です。 ノンブルについての詳細は@{05-faq|sec-nombre}を参照してください。 : 表紙 印刷用では、表紙がつきません。 なぜなら、表紙のPDFファイルは本文とは別にして印刷所に入稿するからです。@
{} 電子用では、（設定されていれば）表紙がつきます@{fn-yybgl}。 //footnote[fn-8w0hm][カラーの設定は「@{sty/starter-color.sty}」を見てください。変更する場合はこのファイルではなく「@{sty/mystyle.sty}」に書くといいでしょう。] //footnote[fn-yuyf5][余白幅は初期設定によって多少の違いがあります。設定の詳細は「@{sty/mytextsize.sty}」を見てください。] //footnote[fn-yybgl][表紙のつけ方は@{04-customize|subsec-coverpdf}を見てください。] =={sec-preview} 高速プレビュー ページ数が多くなると、PDFファイルへのコンパイルに時間がかかるようになり、執筆に支障が出ます。 ここでは高速にプレビューするための機能を紹介します。 === 指定した章だけをコンパイルする Starterでは、指定した章(Chapter)だけを@{}でコンパイルできます。 これは章の数が多い場合や、著者が多数いる合同誌の場合にはとても効果的です。 具体的には次のようにします。 * 「@|rake pdf @{c=03-syntax}|」のようにすると、「@{03-syntax.re}」だけをコンパイルします。 * または環境変数「@|$STARTER_CHAPTER|」を設定する方法でも、章を指定できます。 //terminal[][例：03-syntax-faq.reだけをコンパイルする]{ $ @{@{rake pdf c=03-syntax}} @{「.re」はつけない} ### または $ @{@{export STARTER_CHAPTER=03-syntax}} @{「.re」はつけない} $ @{rake pdf} @{Dockerを使っているなら rake docker:pdf} //} コンパイルする章を指定したとき、Starterは次のような動作になります。 * 他の章は無視されます。 * 表紙や、目次や、大扉や、奥付も無視されます。 * @{}のコンパイル回数が1回だけになります（コンパイル時間を短縮するため）。 なお「@{$STARTER_CHAPTER}」を設定した場合、全体をコンパイルするときにはリセットしてください。 //terminal[][全体をコンパイルする]{ $ @{@{unset STARTER_CHAPTER}} @{「$」はつけないことに注意} //} === コンパイル回数を1回だけに制限する Re:VIEWおよびStarterでは、@{}のコンパイルが最大で3回行われます@{mb3pa}。 //footnote[mb3pa][索引があると、コンパイル回数がもう1回増えます。] * 1回目のコンパイルで章や節のページ番号が分かる。 * 2回目のコンパイルで目次が作成される。 * もし2回目のコンパイルでページ番号が変わると、3回目のコンパイルが行われる。 しかし、ページ番号が合ってなくてもいいからとにかく仕上がりを確認したい場面はよくあり、そんなときは3回もコンパイルされるのは時間の無駄です。 そこでStarterでは、@{}のコンパイル回数を制限する機能を用意しました。 * 「@|rake pdf @{n=1}|」のようにすると、@{}のコンパイルが1回しか行われません。 * または環境変数「@|$STARTER_COMPILETIMES|」を「@|1|」に設定する方法でも、同じように制限できます。 //terminal[][@{}のコンパイル回数を1回に制限してコンパイル]{ $ @{rake pdf @{n=1} } ### または $ @{@{STARTER_COMPILETIMES=1} rake pdf} //} === 画像読み込みを省略するドラフトモード Starterでは、画像の読み込みを省略する「ドラフトモード」を用意しました。 ドラフトモードにすると、画像のかわりに枠線が表示されます。 こうすると、（@{}のコンパイル時間は変わりませんが）DVIファイルからPDFを生成する時間が短縮されます。 図やスクリーンショットが多い場合や、印刷用に高解像度の画像を使っている場合は、この機能は特に効果が高いです。 ドラフトモードにするには、次のどれを実行します@{fn-b5nlc}。 * 「@|rake pdf @{d=on}|」でコンパイルする。 * 環境変数「@{$STARTER_DRAFT}」の値を「@|on|」に設定してからコンパイルする。 * @{config-starter.yml}で「@{draft: true}」を設定してからコンパイルする。 //footnote[fn-b5nlc][強制力はこの順序であり、設定ファイルより環境変数のほうが、また環境変数より`rake`コマンドのオプションのほうが優先されます。] //terminal[][画像読み込みを省略するドラフトモードでPDFを生成する]{ $ @{rake pdf @{d=on}} @{ドラフトモードをonにする} ### または $ @{export STARTER_DRAFT=on} @{ドラフトモードをonにする} $ @{rake pdf} @{またはDocker環境なら rake docker:pdf} //} 環境変数の設定をクリアするには、「@|unset STARTER_DRAFT|」を実行してください。 また「ドラフトモードにしてPDF生成時間を短縮したい、でもこの画像は表示して確認したい」というときもあるでしょう。 そんなときは「@|//image[...][...][@{draft=off}]|」のように指定すると、その画像はドラフトモードが解除されてPDFに表示されます。 === 自動リロードつきHTMLプレビュー Starterでは、HTMLでプレビューするための機能を用意しました。 便利なことに、原稿を変更すると自動的にリロードされます。 PDFと比べてHTMLの生成はずっと高速なので、原稿執筆中に入力間違いを見つけるにはHTMLのほうが向いています。 使い方は、まずWebサーバを起動します。 //terminal[][Webサーバを起動する]{ $ @{rake web:server} @{Dockerを使っていない場合} $ @{rake docker:web:server} @{Dockerを使っている場合} //} 起動したらブラウザで @{http://localhost:9000/} にアクセスし、適当な章を開いてください。 そして開いた章の原稿ファイル（@{*.re}）を変更すると、ブラウザの画面が自動的にリロードされ、変更が反映されます。 原稿執筆中は、エディタのウィンドウの後ろにプレビュー画面が少し見えるようにするといいでしょう。 いくつか注意点があります。 * 表示はHTMLで行っているため、PDFでの表示とは差異があります。 執筆中はHTMLでプレビューし、区切りのいいところでPDFによる表示を確認するといいでしょう。 * 今のところ数式はプレビューできません。 * 変更が反映されるのは、開いているページと対応した原稿ファイルが変更された場合だけです。 たとえば「@{foo.html}」を開いているときに「@{foo.re}」を変更するとプレビューに反映されますが、別の「@{bar.re}」を変更しても反映されません。 * 画面右上の「Rebuild and Reload」リンクをクリックすると、原稿ファイルが変更されていなくても強制的にコンパイルとリロードがされます。 * 原稿ファイルに入力間違いがあった場合は、画面にエラーが表示されます。 エラー表示はあまり分かりやすくないので、今後改善される予定です。 * Webサーバを終了するには、Controlキーを押しながら「c」を押してください。