技術系同人誌を書く人の味方「Re:VIEW Starter」の紹介


（追記 2019-08-18: [この記事公開後の新機能を紹介する記事を書きました](https://qiita.com/kauplan/items/dd8dd0f4a6e0eb539a98)。こちらも見てください。）
（追記 2019-12-27: [その後の新機能を紹介する記事を書きました](https://qiita.com/kauplan/items/e36edd7900498e231aaf)。こちらも見てください。）


## はじめに

[技術書典](https://techbookfest.org/)を筆頭に、技術系同人誌のイベントが盛り上がっています。しかし技術系同人誌を書くのは、初めての人にとってはまだまだ敷居の高いことでしょう。

この記事では、初めて技術系同人誌を書く人のために「[Re:VIEW Starter](https://kauplan.org/reviewstarter/)」というツールを紹介します。

* Re:VIEW Starter (https://kauplan.org/reviewstarter/)


## Re:VIEW Starterの概要

「Re:VIEW Starter」とは、技術系同人誌を書くための書籍作成ツールです。
特に、初めて技術系同人誌を書く人がつまづかないように工夫されています。

もともと技術書典界隈では「[Re:VIEW](https://github.com/kmuto/review/)」というツールが広く使われており、それを改良したのが「Re:VIEW Starter」です。
Re:VIEW[^9674]と比べると、Re:VIEW Starterは次のような特長があります。

* 初期設定をGUIで行える
* 見栄えのいいデザインが用意されている
* コード中の長い行を自動的に折り返す
* キャプションとコードが分かれない
* 行番号の機能が豊富
* コマンドを整理してシンプルに
* 入れ子可能な順序つきリストを用意
* ノートに箇条書きやコードが入れられる
* 図を入れる場所を指定できる
* LaTeX初心者のために詳しいコメントつき
* いろんなところに気が利いている
  * 強調を太字のゴシック体に
  * 長いタイトルの改行箇所を指定できる
  * 奥付が必ず最終ページに
  * リスト番号をつけるのが簡単

それぞれ詳しく紹介します。

なお「Re:VIEW Starter」と書くのはちょっと長いので、以降では「Starter」と表記します。

[^9674]: Re:VIEWの最新バージョンは執筆時点で3.1なので、この記事でもRe:VIEW 3.1と比較しています。


## 初期設定をGUIで行える

Starterでは、初期設定をGUIで行えます。具体的には https://kauplan.org/reviewstarter/ にアクセスし、質問に答えるだけで初期設定されたプロジェクトがダウンロードできます。

たとえば次のスクリーンショットは、用紙サイズ（B5かA5か）やフォントサイズや1行あたりの文字数を、プレビューを見ながら選択している様子です。しかも初心者がやってしまいがちな、左右の余白を狭くしすぎて印刷したらすごく見づらくなる問題をあらかじめ防いでくれます！

<img width="100%" alt="starter-11.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/d033665c-a92b-1917-51b9-0be3ac6b39fa.png">

これを自力でやろうとすると、どうしてもLaTeXの知識が必要になるので難易度が高いんですよね。Starterを使えば、Re:VIEWもLaTeXも知らなくてもいい具合に設定できます。

なおTechBoosterさんが公開している[Re:VIEW用テンプレート](https://github.com/TechBooster/ReVIEW-Template)でも、B5とA5が選べます。Starterを作ったときはなかったはずですが、いつの間にか用意されてますね。


## 見栄えのいいデザインが用意されている

多くの技術同人誌では、章(Chapter)や節(Section)がこんなデザインになっています。

<img width="75%" alt="starter-21.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/17e4c404-59bb-05ab-ff65-109b6ba2b4bb.png">

これはLaTeXという組版ソフトのデフォルトデザインです。悪くはないデザインですが、面白みに欠けるデザインでもあります。

しかしStarterを使うと、こんなデザインを選べます。
（これは電子書籍用なのでカラー版ですが、印刷用は白黒になります。）

<img width="75%" alt="starter-24.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/e698eff6-c4e1-6cd5-6a7b-d2d299ba652d.png">

ずいぶんデザインが違いますね！
また好みで、章タイトルを独立したページにできます。

<img width="75%" alt="starter-22.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/6c1a49c6-8c47-3988-2d3e-f9f2f81918c7.png">

こういったデザインを自力で実現しようとしたら、LaTeXの知識が必要になります。Starterなら、LaTeXを知らなくてもこのデザインを使えます。

そしてStarterでは、他のデザインもGUIで選べます！

<img width="" alt="starter-25.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/c95de644-0dea-d0c1-8439-83471022d838.png">


なおGUIで選べるのは初期設定時だけなので、プロジェクトをダウンロードしたあとは`sty/starter.sty`というフィルを開いてちまちま変更してください。それが面倒な人は気に入ったデザインになるまでプロジェクトを何度も作ればいいでしょう。

（追記）プロジェクトをダウンロード後も、`config-starter.yml`の「`chapter_decoration:`」や「`section_decoration:`」で変更できるようになりました。詳しくは`config-starter.yml`を見てください。


## コード中の長い行を自動的に折り返す

Starterでは、プログラムコードやターミナルの中に長い行があったら、それを自動的に折り返してくれます。また折り返した箇所には折り返し記号がつくし、行番号つきなら行番号の分だけインデントして折り返します。

<img width="75%" alt="starter-31.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/9b99258d-efb3-1f88-0da8-ab3d264bb8bb.png">

長い行を折り返す機能がないとどれだけ苦しむことになるかは、[こちらのブログ記事](https://nekopunch.hatenablog.com/entry/2019/04/25/094508#h20190425T004508Z8)が参考になるでしょう。Starterを使えば、このような苦行から解放されます。

なお折り返し箇所が日本語の場合は、折り返しはされるものの折り返し記号がつきません。この不具合は解決方法が見つかってないため、日本語の途中で折り返しする場合は折り返し記号を諦めるか、手動で `@<foldhere>{}` というコマンドを折り返したい箇所に埋め込んでください。

<img width="75%" alt="starter-32.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/eb169187-7de4-bb63-414d-16f4182cc3a7.png">


## キャプションとコードが分かれない

キャプションというのは、プログラムコードや図や表につける説明文のことです。たとえば次の例では、「フィボナッチ数列」という文がキャプションです。

<img width="762" alt="starter-41.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/a341df88-146e-f2a2-3749-9b60ca2d7a4d.png">

Re:VIEWでは、キャプションとプログラムコードとの間で改ページされることがあります。こんなかんじですね。

<img width="896" alt="starter-42.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/3a4dc6af-33fe-ff28-a5a2-ad8976ba0672.png">


読者からみると、これは読みづらい体験になります。

Starterでは、キャプションとコードとの間で改ページしないようになっています。そうなりそうになったら、キャプションの直前で改ページします。

<img width="896" alt="starter-43.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/535d9bd8-3608-a3ad-c763-162e4e2970bd.png">

（追記：改ページしないために必要となるスペースの高さを指定できるオプションを用意しました。`config-starter.yml`の「`caption_needs: 4.8zh`」を調整してください。詳しくは[別記事](https://qiita.com/kauplan/items/dd8dd0f4a6e0eb539a98#%E3%82%AD%E3%83%A3%E3%83%97%E3%82%B7%E3%83%A7%E3%83%B3%E7%9B%B4%E5%BE%8C%E3%81%AE%E6%94%B9%E3%83%9A%E3%83%BC%E3%82%B8%E3%82%92%E9%98%B2%E3%81%90%E3%83%91%E3%83%A9%E3%83%A1%E3%83%BC%E3%82%BF%E3%82%92%E5%B0%8E%E5%85%A5)で。）


## 行番号の機能が豊富

Re:VIEWにはプログラムコードに行番号をつける機能があります。

<img width="" alt="starter-51.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/18cd70c1-616e-c053-d9d6-92ca11c055f0.png">

Starterでは行番号の色を変えるので、行番号とプログラムコードの区別がつきやすいです。

<img width="762" alt="starter-52.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/1f4f145d-a3a4-cdd7-8b9a-54eba68fd886.png">

また行番号を余白に置くことで、プログラムコードの表示幅を減らさないようにもできます。

<img width="761" alt="starter-53.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/10f33a0d-7fcd-446e-3c97-c10b7e5160bc.png">

さらに、より複雑な行番号の指定ができます。たとえば次のサンプルコードにある`lineno=10-12&18-20&25-`という箇所がそれで、「10〜12行目と18〜20行目と25行目以降」を表しています。

```
//list[][][lineno=10-12&18-20&25-,linenowidth=2]{
// サンプルコード
public class Hello {
    private String name;
    ...省略...
    public void hello() {
        System.out.println("Hello, "+this.name);
    }
    ...省略...
}
//}
```

これをStarterで表示すると、このようになります。行番号が飛んでいる箇所がありますよね。こんな行番号指定が、Starterならできます。

<img width="757" alt="starter-54.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/9881ed8f-89a0-8456-4978-449a26ebc17c.png">


## コマンドを整理してシンプルに

Re:VIEWでは、プログラムコードを表すのに4つのコマンドを使い分ける必要がありました。

```
//list[ラベル][キャプション][言語名]{  ← リスト番号つき、行番号なし
  ....
//}

//emlist[キャプション][言語名]{       ← リスト番号なし、行番号なし
  ....
//}

//listnum[ラベル][キャプション][言語名]{ ← リスト番号つき、行番号あり
  ....
//}

//emlistnum[キャプション][言語名]{      ← リスト番号なし、行番号あり
  ....
//}
```

Starterではこれらを`//list`のみに集約しました。

```
//list[ラベル][キャプション][言語名]{  ← リスト番号つき、行番号なし
  ....
//}

//list[][キャプション][言語名]{       ← リスト番号なし、行番号なし
  ....
//}

//list[ラベル][キャプション][言語名,lineno=1]{ ← リスト番号つき、行番号あり
                                           ← または lineno=1,lienowidth=3
  ....
//}

//list[][キャプション][言語名,lineno=1]{      ← リスト番号なし、行番号あり
                                           ← または lineno=1,lienowidth=3
  ....
//}
```

シンプルで分かりやすい！4つのコマンドを使い分けるよりも1つだけで済むほうが、覚えやすいです。
後方互換性のために従来の`//emlist`や`//listnum`や`//emlistnum`も使えますが、`//list`に統一することを勧めます。

またターミナルを表すためにRe:VIEWでは`//cmd`というコマンドがありますが、これはリスト番号や行番号がつけられず、引数の指定方法も`//list`とは違います。

そこでStarterでは`//terminal`というコマンドを新たに用意しました。これは`//cmd`と違い、使い方が`//list`と同じです。またリスト番号もつけられます。

```
//terminal[ラベル][キャプション]{  ← リスト番号つき、行番号なし
  ....
//}

//terminal[][キャプション]{       ← リスト番号なし、行番号なし
  ....
//}

//terminal[ラベル][キャプション][lineno=1]{ ← リスト番号つき、行番号あり
                                         ← または lineno=1,lienowidth=3
  ....
//}

//terminal[][キャプション][lineno=1]{      ← リスト番号なし、行番号あり
                                         ← または lineno=1,lienowidth=3
  ....
//}
```

使い方が`//list`と同じコマンドが用意されたことで、より分かりやすくなりました。


## 入れ子可能な順序つき箇条書きを用意

Re:VIEWでは、番号つきの箇条書きが使えます。

```
 1. 項目
 2. 項目
 3. 項目
```

Re:VIEWでの表示例：

<img width="75%" alt="starter-61.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/deed28c5-4faa-6c4a-094e-9dfa651adaf1.png">

しかし数字しか使えないので「A.」や「a.」は使えないし、なにより入れ子にできません。

Starterでは、数字だけでなく「A.」や「a.」が使える順序つき箇条書きを用意しました。

```
 - 1. 項目
 - 2. 項目

 - A. 項目
 - B. 項目

 - a. 項目
 - b. 項目
```

Starterでの表示例：

<img width="75%" alt="starter-62.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/9957eea6-1711-5319-c17e-c3dfbae964a8.png">

また「(1)」や「(A)」や「(A-1)」にも指定できるし、入れ子にもできます。通常の箇条書きとも混ぜられます。

```
 - (A) 大項目
 -- (A-1) 中項目
 *** 小項目
 *** 小項目
```
（追記：入れ子の方法を間違っていたので修正。Re:VIEWやStarterでは入れ子はインデントではなく記号の数で行うのが正しい。）

<img width="75%" alt="starter-64.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/124470ec-0df7-b387-5620-d3328a4da829.png">

` - 1.` や ` - (A)` のあとには半角空白が必要です。行頭の ` - ` と半角空白の間の文字列がそのまま使われるだけなので、任意の文字列が使えます。

```
 - ア) 項目
 - イ) 項目
 - ウ) 項目

 - 甲： 山田一郎
 - 乙： 佐藤二郎
```

Starterでの表示例：
<img width="75%" alt="starter-65.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/32888f15-f671-1fce-3847-f8af09526f0e.png">

順序として任意の文字列を使えるかわりに、番号の自動採番はしません。順番の間違いや抜けには注意してください。


## ノートに箇条書きやコードが入れられる

本文の補足事項を入れる囲み枠を、ここでは「ノート」と呼びます。

Re:VIEWでは、ノートを書くためのコマンドが用意されています。

```
//note[新刊を落とさない秘訣とは？]{
『なぜ人は新刊を落とすのか』という同人誌で、新刊を出せたサークルと出せなかったサークルにアンケート調査してました。

 * 新刊を出せたサークルは、出せなかったサークルより作業時間をかけている。
 * なぜ作業時間をかけられたかというと、2週間ぐらい早く作業を開始してるから。

身も蓋もない結論ですね！
//}
```

しかしRe:VIEWでは、ノートの中に箇条書きやプログラムコードを埋め込めません。そのため、上の例はこのような表示になってしまいます。

<img width="" alt="starter-71.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/e22a923a-35a9-1da8-6911-bfefb9891639.png">

箇条書きがうまく表示されてませんね。
これはかなり困る仕様なので、Starterではノートの中に箇条書きを埋め込めるよう、改良しました。たとえば上の例は、Starterだとこのように表示されます。

<img width="80%" alt="starter-72.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/b640d7ec-854d-896f-2c9d-f26e316391df.png">

プログラムコードも埋め込めます。

```
//note[サンプルコード]{
フィボナッチ数列のサンプルコード。

//list{
function fib(n) {
  return n <= 1 ? n : fib(n-1) : fib(n-2);
}
//}

//}
```

Starterでの表示結果。

<img width="80%" alt="starter-73.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/a7d00fe9-1ef7-8668-72da-ea487a5d54f8.png">

なおノートは `===[note] ... ===[/note]` のような書き方もできます。これは後方互換性のためです。


## 図を入れる場所を指定できる

Re:VIEWで作られた技術同人誌では、大きめの図が次のページに回されると大きなスペースが空くことがあります。これは、Re:VIEWのデフォルトでは図を現在箇所に強制的に入れようとするため（そして後続の文章を流し込まないようにしているため）です。

<img width="80%" alt="starter-81.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/f62e00bb-4259-681c-164a-dee169aced2f.png">

Starterでは、図を入れるときに位置 (Position) を指定できます。次の例で「`pos=h`」というのが位置の指定です。

```
//image[filename.png][図の説明][scale=0.5,pos=h]
```

こうすると、図が次のページに回されたときに、空いた箇所に後続のテキストが流し込まれるため、大きな空白ができません。

<img width="80%" alt="starter-82.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/78a7edca-a583-1f92-f24a-61e80cfdc62b.png">

位置指定 `pos=h` には、次のような指定ができます。

* `pos=H` は強制的に現在箇所 (Here)
* `pos=h` は現在箇所 (here)
* `pos=t` はページ上部 (top)
* `pos=b` はページ下部 (bottom)

`pos=H`と`pos=h`は、どちらも現在位置に図を入れようとし、入らなければ次のページの上部に回します。その点では同じですが、`pos=H`は後続の文章を流し込まないので大きなスペースが空き（最初の画像）、`pos=h`は後続の文章を流し込むのでスペースが空きません（2つ目の画像）。

スクリーンショットを多用するような同人誌の場合、このスペースが多いとページ数が増加して印刷代がかさみます。印刷代を抑えるためにも、図の位置指定はこまめに行いましょう。


## LaTeX初心者のために詳しいコメントつき

Starterは、LaTeXに詳しくなくても使えるように気を使っています。とはいえ細かいカスタマイズをしたい場合はどうしても出てくるものです。たとえば：

* 章 (Chapter) のタイトルデザインを変えたい
* 節 (Section) タイトルの前後のマージンを増やしたい
* 項 (Subsection) のタイトルにハートマークをつけたい

このような場合はLaTeXのスタイルファイルを編集する必要があります。しかしLaTeXの知識なんて持ってない人がほとんどでしょう。

そこでStarterでは、LaTeXのスタイルファイル（`sty/starter.sty`）に詳しいコメントをつけました。たとえば次の例は、節 (Section) のデザインを設定している箇所です。

```latex
%%% 節タイトルに下線を引く
\newcommand{\starter@section@formatnumber}{%
  \textcolor{starter@sectioncolor}{%      % 色を変える
    \rule[-0.35zw]{\textwidth}{0.2pt}%    % 横幅いっぱいの細い下線
    \hspace{-\textwidth}%                 % もとの位置に戻る
    \rule[-0.35zw]{0.7zw}{1.7zw}%         % 行頭に縦長の「■」を追加
  }%
  \hspace{0.7zw}%                         % 節番号のまえにスペースを少し空ける
  \thesection%                            % 節番号
  \hspace{1.0zw}%                         % 節番号のあとに全角1文字分のスペース
}
```

ほぼ1行ごとにコメントがついていますね。このような詳しいコメントがついていれば、「この箇所のスペースをもうちょっと広げたい」とか「線をもう少し太くしたい」というときに、LaTeXの知識がなくてもなんとなく変更できるでしょう。

なおStarterは発展途上のため、`sty/starter.sty`は頻繁に変更されます。なので`sty/starter.sty`を直接変更するとバージョンアップがしにくくなるので、ユーザが行う変更は`sty/mystyle.sty`に書いたほうがいいでしょう。


## いろんなところに気が利いている

他にも、Starterは細かいところに気が利いています。


#### 強調を太字のゴシック体に

Re:VIEWでは、`@<b>{}`も`@<strong>{}`も文字を明朝体のまま太字にするだけです。

Starterでは、`@<b>{}`は太字にするだけですが、`@<strong>{}`は太字のゴシック体にします。また`@<strong>{}`のエイリアスとして、より簡潔な`@<B>{}`を用意しました。気が利いてますね！なので本文を強調したいときは`@<B>{}`を使うといいでしょう。

なおStarterでは`@<em>{}`を使うと太字ではないゴシック体になります。


#### 範囲コメントが使える

Re:VIEWには行コメント`#@#`はありますが、範囲コメントはありません。長い文章を書いていると、ある箇所をまとめてコメントアウトしたいことはよくあるので、範囲コメントがないのは不便です。

そこでStarterでは、範囲コメントを実装しました。`#@+++`と`#@---`で囲んだ範囲をコメントアウトします。

```
これから王国の復活を祝って、諸君にラピュタの力を見せてやろうと思ってね。
#@+++
見せてあげよう、ラピュタの雷を！
旧約聖書にある、ソドムとゴモラを滅ぼした天の火だよ。
ラーマーヤナではインドラの矢とも伝えているがね。
#@---
全世界は再びラピュタのもとにひれ伏すことになるだろう。
```

これをStarterで表示すると次のようになります。範囲コメントが効いてますね！

<img width="75%" alt="starter-93.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/cf4ef9ef-2ed5-8420-e7ab-73b54a3b9245.png">


#### プログラムコードを見やすいフォントで表示

プログラムコードを表示すると、Re:VIEWではLaTeXのデフォルトフォントを使うため、数字の`1`と英小文字の`l`、数字の`0`と英大文字の`O`の区別がつきにくいです。また太字にしても違いが分かりにくいという問題もあります。

Starterではプログラムコードを表示するフォントを変更しているため、これらの問題は起きません。

<img width="75%" alt="starter-94.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/3622a481-498d-f358-1d18-563eee4cab2e.png">

（追記：プログラムコードやターミナルで使われる等幅フォントをGUIで選べるようになりました。詳しくは[別記事](https://qiita.com/kauplan/items/dd8dd0f4a6e0eb539a98#%E7%AD%89%E5%B9%85%E3%83%95%E3%82%A9%E3%83%B3%E3%83%88%E3%82%92gui%E3%81%A7%E9%81%B8%E6%8A%9E%E5%8F%AF%E8%83%BD%E3%81%AB)を見てください。）


#### 長いタイトルの改行箇所を指定できる

同人誌のタイトルが長いせいで、意図せぬところで改行された経験はありませんか？たとえばこのように。

<img width="75%" alt="starter-91.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/f88002ad-a5ef-1960-26d3-f5f9754e314e.png">

こうなってしまう原因は簡単で、長いタイトルを1行で書いていて、改行してほしい箇所を指定していないからです。しかしRe:VIEWでは改行してほしい箇所を指定できません。

Starterではタイトルを複数行で指定できます。改行してほしい箇所で改行すると、大扉でのタイトルもそこで改行されます。気が利いてますね！

<img width="75%" alt="starter-92.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/e1a6f7e7-8151-6083-d899-26a50e12ac14.png">


#### 奥付が必ず最終ページに

「奥付」というのは、本の最終ページに載っている書誌情報です。こういうの↓ですね。

<img width="75%" alt="starter-A1.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/e2850c10-f126-3d66-d9ac-60b11c09bc61.png">

ところで紙は裏表あるので1枚で2ページあります。紙が何枚であろうと、全体の総ページ数は偶数になります。

そして（奥付も含めた）本文の総ページ数が偶数の場合は、奥付は自動的に最終ページに置かれます。奥付は最終ページに置くべきなので、これは何の問題もありません。

問題は本文の総ページ数が奇数の場合です。この場合、何もしなければ奥付は最終ページのひとつ前のページになり、最終ページは空ページになってしまいます。そしてこれがRe:VIEWのデフォルトの挙動なんですね。

Starterではこれを修正し、本文の総ページ数が奇数の場合でも奥付を最終ページに置き、そのひとつ前のページを空ページにします。気が利いてますね！


#### リスト番号をつけるのが簡単

Re:VIEWではプログラムコードにリスト番号をつけられます。このとき、一意なラベルをつける必要があります。たとえば次の例では`hello1`というラベルをつけています。

```
//list[hello1][ハローワールド]{
print("Hello, world!\n")
//}
```

プログラムコードを参照する場合はこのラベルを使って参照するので、ラベルは一意である必要があります。妥当な仕様ですね。

けど一意なラベルをつけるのは数が多いとかなり面倒です。たとえばプログラムコードが100個あるとして、その100個のすべてにリスト番号をつけたい場合、一意なラベルを100個つけるのが面倒なのは容易に想像がつくでしょう。

そこでStarterでは、ラベルに「`?`」を指定すると自動的に一意なラベルを割り振ります。

```
//list[?][ハローワールド]{
print("Hello, world!\n")
//}
```

自動的に割り振られたラベルはコンパイラ内部でのみ使われるので、外から参照できません。つまりラベルに「`?`」を指定した場合は、他の箇所から参照はできません。しかしリスト番号は問題なくつくので、とにかくリスト番号を簡単につけたい場合は便利です。


## バグフィックス

Re:VIEWは広く使われておりバージョンも3.1である（つまり0.xや1.xではない）わりにはバグが多く、しかも基本的な機能でバグが見つかります。Starterを開発していると結構な数のバグを見つけるのでバグ報告をしてますが[^3218]、治ったものもあれば治らないものもあるし、仕様として突っぱねられたものもあります。

ここではStarterが修正したバグや望ましくない仕様を紹介します。

[^3218]: コミッターを除けば、たぶんバグ報告数はいちばん多いと思います（[過去に行ったバグ報告の解説](https://qiita.com/kauplan/items/5068e2a0da7847c2014e)も見てください）。Re:VIEWのソースコードを読むとバグに気づきますが、読んでる人がほかにいなさそう。


#### 英単語が結合されるバグを修正

Re:VIEWでは、箇条書きに複数行の英文を書くと単語が自動的に結合されます。たとえば次のような箇条書きがあった場合：

```
 * I'm hoping to show you the power of Laputa
   to celebrate the resurrection of the kingdom.
   Let me show you the lightning of Laputa!
```
Re:VIEWでコンパイルすると、1行目終わりの「Laputa」と2行目始めの「to」が結合して「Laputato」になってしまいます。また2行目終わりの「kingdom.」と3行目始めの「Let」が結合して「kingdom.Let」になり、ピリオドのあとの空白が消えてしまいます。

<img width="75%" alt="starter-97.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/d8147de2-4940-b038-b489-4799c1c3c616.png">

どう考えてもおかしな挙動ですよね。これのバグ報告をしたところ、「どうしてそういう書き方をするの？」と言われたり「英単語が連結されることよりも、改行のせいで日本語間に不自然な空白が入るのをなくすほうが重要なんだよ！」と断言されたりで、滅入ります。~~（バグ報告なんかしなきゃよかった）~~

Starterでは、このような余計な結合をしないように修正しています。


#### 行コメントで段落が分割されるのを修正

Re:VIEWでは、段落の途中の行をコメントアウトすると、そこが空行扱いになるため、段落が分割されてしまいます。

入力例（段落の3行目と4行目をコメントアウト）：

```
これから王国の復活を祝って、諸君にラピュタの力を見せてやろうと思ってね。
見せてあげよう、ラピュタの雷を！
#@#旧約聖書にある、ソドムとゴモラを滅ぼした天の火だよ。
#@#ラーマーヤナではインドラの矢とも伝えているがね。
全世界は再びラピュタのもとにひれ伏すことになるだろう。
```

Re:VIEWでの表示例（段落が分割される）：

<img width="75%" alt="starter-98.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/45a5ee3c-15ae-5763-d902-3a828011f17e.png">

Re:VIEW開発チームに問い合わせたところ、これがRe:VIEWの仕様であるとの回答でした。しかしこんな仕様、誰にも嬉しくありません。こんな仕様では段落の途中の行を、段落を分割せずにコメントアウトする方法がありません。

Starterではこの挙動を変更し、段落の途中の行をコメントアウトしても段落が分割されないようにしています。

Starterでの表示例（段落が分割されない）：

<img width="75%" alt="starter-98-ok.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/98776412-2284-6b9b-c15e-de18984afe19.png">


#### プログラムコード中のタブ文字の展開がおかしいのを修正

Re:VIEWでは、プログラムコード中のタブ文字を自動的に半角空白に展開してくれます。しかし「`$` → `\textdollar{}`」のようなLaTeX特殊文字の変換を先に行ってから、そのあとにタブ文字を展開するため、カラム数の計算がおかしくなり、正しい展開にはなりません。

入力例（`#`の位置が揃ってる）：

```
//emlist{
echo $var;      # ← コメントの前が半角空白
echo $var;      # ← コメントの前がタブ文字
//}
```

Re:VIEWでの表示例（`#`の位置が揃わない）：

<img width="75%" alt="starter-99.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/a9cee576-d8b3-6b60-ff34-6e621e2e3b50.png">

Starterでは先にタブ文字の展開を行ってからLaTeX特殊文字の変換を行うよう修正したので、上のような問題は発生しません。

Starterでの表示（`#`の位置が揃っている）：
<img width="75%" alt="starter-99-ok.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/1375aa9a-bb7f-cf5d-52c1-061ba1f62bae.png">

ただし`@<b>{}`や`@<del>{}`のようなインライン命令をプログラムコードの中で使うと、正確なカラム数の計算ができないので、タブ文字の展開も正しくはできません。この問題は当分解決できないので、インライン命令を使っている行ではタブ文字を使わないでください。


## 今後の計画

今後、次のような機能を実装するつもりです。

* **インライン命令の入れ子機能**。Re:VIEWではインライン命令の入れ子ができないので、たとえば「`@<b>{太字の中に@<tt>{タイプライタ体}を入れる}`」ことができません。かわりに「`@<b>{太字にして}@<ttb>{太字のタイプライタ体にして}@<b>{また太字に戻す}`」というやり方をする必要があります。これはかっこ悪いし、他のフォーマットからの変換も面倒になるので、Starterで独自に入れ子対応するつもりです。<br> **【追記】インライン命令を入れ子にできるようになりました**。詳しくは「[Re:VIEW Starterの新機能（2019年冬）](https://qiita.com/kauplan/items/e36edd7900498e231aaf)」を見てください。

* **ノート機能の強化**。Re:VIEWにはもともと、`//note`以外にも`//memo`や`//info`や`//warning`などが用意されています。しかし有効に活用されているとは言い難いので、これらを活かすことを考えています。

* **プログラムコードのハイライト表示**。IDEや高機能エディタでよくある機能ですね。ハイライト表示と強調表示を同時に行うのが難しいので、どういうやり方がいいか、調査中です。

* **文法エラーメッセージの改善**。入力ファイルに文法エラーがあった場合、Re:VIEWのエラーメッセージは分かりにくいので、もっと分かりやすいエラーメッセージにしたいです。

* **より洗練されたデザインの導入**。Starterが提供しているデザインは、LaTeX標準よりはずいぶんマシだけどまだまだ洗練されてないので、よりよいデザインの提供を目指します。そのためには
TikZ
[tcolorbox](https://www.google.com/search?q=latex+tcolorbox)というパッケージの導入が避けられません。しかしこれを使うとLaTeXコンパイル時間が大きく増える[^6572]ので、導入を迷ってます。できれば
TikZ
tcolorboxを避けたままデザインを改善したいです。
  （追記：想定していたのはTikZじゃなくてtcolorboxだったので修正。tcolorboxはTikZを使っているので完全な間違いではないけど。）

[^6572]: Techboosterさんのテンプレートではすでに
TikZ
tcolorboxを導入済みですが、そのせいでコンパイルに時間がかかっています。


Re:VIEWのソースコードをがっつり読んだ人はあまりいないと思いますが、正直いって全体の設計がよくないです。本来なら木構造を作るべきところを作ってなかったり、パーサで行うべき処理をなぜかLaTeXビルダーで行ってたり、構造的な問題がいろいろあります。メジャーバージョンが3にもなって基本的なバグが見つかるのも致し方なしです。そういった問題をかいくぐりながら苦労して改造しているので、Starterの機能拡張は長い目で見てください。


## 利用者の感想

吹けば飛ぶようなStarterの利用実績ですが、Twitterで検索して見つかったものを紹介します。

* 技術書典6で『[jQuery to Vue.jsで学ぶ レガシーフロントエンド安全改善ガイド](https://note.mu/mugi_uno/n/n1be579981b73)』を執筆した[@mugi_uno](https://twitter.com/mugi_uno/)さん<br>
  (https://twitter.com/mugi_uno/status/1104879611748352001)

<img width="" alt="tw-1.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/9d1c46be-d41b-1c3f-57fb-b29c4d273c97.png">

* 技術書典6で『[Google App Engine Webアプリ開発入門](https://booth.pm/ja/items/1287245)』を執筆した[@castanea](https://twitter.com/castanea/)さん <br>
  (https://twitter.com/castanea/status/1107273826553876481)

<img width="" alt="tw-2.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/224266/94542cd9-db43-53fc-b618-2e26ff496ccc.png">

ご利用ありがとうございます！
他にも使ってる人がいたら、コメントで教えてください。


## 他のツール

Re:VIEW Starter以外にも、技術同人誌を書くためのツールやサービスはいくつかあります。

* [Re:VIEWテンプレート](https://github.com/TechBooster/ReVIEW-Template) by Techbooster
  … 技術書典界隈でもっともポピュラー、ただしRe:VIEWの問題点をほぼ引き継いでいる。
* [Re:VIEW+CSS組版](http://at-grandpa.hatenablog.jp/entry/2019/01/20/183940) by @at_granpa
  … LaTeXのかわりにCSS組版を使うよう改造したRe:VIEW。
* [Vivliostyle](https://vivliostyle.org/ja/)
  … CSS組版するならコレ。LaTeXを触らなくていいのは何事にもかえがたいメリット。
* [Viola](https://viola.pub/)
  … オンラインエディタを備えたサービス。ブラウザだけで原稿執筆からPDFまで作成できる。
* [FlightBooks](https://flightbooks.pub/)
  … Markdownで技術同人誌が作れるサービス。書籍を作るにはMarkdownは機能不足だけど、手軽さはすばらしい。
* [Sphinx](https://www.sphinx-doc.org/)
  … ドキュメント作成ツールとしての実績が豊富なツール。ただし同人誌作成では実績が弱く、利用者も少ない。もっと増えるべき。
* [Pandoc](https://pandoc.org/)
  … MarkdownからHTMLやLaTeXファイルを生成できるツール。実態はフォーマット変換ツールと呼んだほうがふさわしい。
* [AsciiDoc](http://asciidoc.org/)
  … 日本での知名度はあまりないけど、海外では実績が豊富なツール。[Wikipedia](https://ja.wikipedia.org/wiki/AsciiDoc)によると、オライリーでも使われているらしい。
* [AsciiDoctor](https://asciidoctor.org/)
  … AsciiDocの別実装(?)。たとえばあの『[Pro Git](https://github.com/progit/progit2)』はこれで書かれている。
* [scrapboxを使って同人誌が作れるサービス](https://twitter.com/daizplus/status/1132699399526780933)
  … 詳細は不明だけどデモ動画を見る限り期待大。
* [mdBook](https://github.com/rust-lang-nursery/mdBook)
  … Rust製の、Markdownからドキュメントを作るツール。ただし出力がHTMLとePubだけみたい。

多すぎでしょ！
初心者の人がこれらを全部試すわけにもいかないでしょうから、まずは[Re:VIEW Starter](https://kauplan.org/reviewstarter/)から始めましょう（強引な結論！）。

（追記：こういうのもあるよ！）

* [Gitbook](https://www.gitbook.com/) … Markdownで書いたドキュメントを管理するシステム。WYSIWYGエディタが強力らしい。
* [でんでんコンバータ](https://conv.denshochan.com/) … 独自拡張のMarkdownを使ってePubを生成するサービス。ガイドがとても丁寧。
* [LeME](https://leme.style/) … MS Wordのファイル (*.docx) をePubに変換するソフト。Windowsだけでなく、なんとUbuntuやmacOSでも動く。イメージキャラに気合い入ってる。


## まとめ

初めて技術系同人誌を書くなら、[Re:VIEW Starter](https://kauplan.org/reviewstarter/)をお勧めします。デザインがきれいだし、初心者でもGUIで初期設定できるし、機能不足も解消されています。とにかく、まずは使ってみてください。

質問や要望は、ハッシュタグ `#reviewstarter` をつけてツイートしてください。