Skip to content

Commit

Permalink
改訂版にあわせて最新の状況を反映
Browse files Browse the repository at this point in the history
  • Loading branch information
@mhidaka
mhidaka committed Oct 30, 2023
1 parent dc1f74d commit c24fdfb
Show file tree
Hide file tree
Showing 11 changed files with 612 additions and 554 deletions.
126 changes: 19 additions & 107 deletions articles/build.re
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,9 @@
={build} 書籍をビルドする

本章ではRe:VIEWファイルをコンパイルする方法を解説します。
PDFを出力する@<code>{review-pdfmaker}、EPUBを出力する@<code>{review-epubmaker}、Webページを出力する@<code>{review-webmaker}、
フォーマットを変換する@<code>{review-compile}を順番に紹介します。
PDFを出力する@<code>{review-pdfmaker}、EPUBを出力する@<code>{review-epubmaker}、Webページを出力する@<code>{review-webmaker}を順番に紹介します。

入稿に利用する形式は@<code>{review-pdfmaker}コマンドでのPDF形式ですが、Re:VIEWは、Markdown、プレーンテキスト、HTMLやEPUBなど多様なフォーマットに対応しています。
入稿に利用する形式は@<code>{review-pdfmaker}コマンドでのPDF形式ですがRe:VIEWは、Markdown、プレーンテキスト、HTMLやEPUBなど多様なフォーマットに対応しています。

== review-pdfmaker

Expand All @@ -20,25 +19,28 @@ YAMLファイルには本のタイトルや筆者名といった本のメタデ
その設定のひとつ@<code>{bookname}が出力ファイル名に対応しています。

@<code>{bookname}が「book」となっている場合、生成した@<tt>{book.pdf}を自身のディレクトリに保存します。
#@# NOTE vv: この辺変わってる 基本はtmpdirに出力される --debug 有りでbook-pdfディレクトリに出力するが、その場合も古いディレクトリは自動的に削除されてから処理が実行される
#@# https://github.com/kmuto/review/blob/331aa87595b5188fc765e04a81ae8205dac41785/lib/review/pdfmaker.rb#L63-L74
#@# 対応済み

@<code>{review-pdfmaker}は内部で後述のコマンド@<code>{review-compile --target=latex}を実行します。
そのあとに@<code>{platex}や@<code>{dvipdfmx}のようなTeX形式のファイルからPDFへ変換する外部コマンドを実行します。
Re:VIEW外部のコマンドを実行している際には外部のログがそのまま標準出力や標準エラー出力に反映されるため、驚くかもしれません。
@<code>{review-pdfmaker}の内部では別のコマンド@<code>{review-compile --target=latex}を実行しています。
そのあとに@<code>{platex}や@<code>{dvipdfmx}のようなTeX形式のファイルからPDFへ変換するRe:VIEW以外の外部コマンドを実行します。

=== 制作時の注意点
=== 制作時に出会うエラーたち

@<code>{review-pdfmaker}をはじめて使うときは作法がわからず戸惑うかもしれません。
もっとも単純な事例では、catalog.ymlの@<code>{CHAPS}で章の指定を忘れることです。
構文エラーが発生すると標準出力に発生時点のエラーログが残ります。これを手がかりに問題の箇所を探すことになります。
もっとも単純な事例では@<tt>{catalog.yml}の@<code>{CHAPS}で追加した@<tt>{.re}ファイルを書き忘れることです。
単純に参照がない場合もビルドが成功するので（機械にはわからないエラーなので）追加分が見えないため慣れないうちは困惑します。

リストに掲載したソースコードが長すぎて紙面をはみ出している場合、箇条書きのつもりで書いた「@<code>{*}」が半角スペースを忘れていて直接本文に表示されている場合など
見た目の問題についてはビルドエラーとはなりません。
検出しにくい見た目の問題も挙げましょう。

執筆後半となると、見栄えの調整のために頻繁に@<code>{review-pdfmaker}を実行するので注意すべきポイントとして覚えておくとよいでしょう。
意図したレイアウトでPDFが出力されているかは作成者によるケアが必要です。
* 本文中にリストとして掲載したソースコードが長すぎて紙面をはみ出している場合
* 箇条書きのつもりで書いた「@<code>{*}」が半角スペースを忘れていて直接本文に表示されている場合
* 表に複数行のテキストを入れたら折返しがうまくいかず不格好になる場合

装飾やレイアウトの問題についてはビルドエラーとはなりません。意図したレイアウトでPDFが出力されているかは作成者によるケアが必要です。

最後にRe:VIEW記法を間違えたときは構文エラーが起きます。エラーが発生すると標準出力に発生時点のログが残るのでとりあえず眺めることになるでしょう。
前述の説明のとおり、TeXの出力ログやエラーも含まれているので急に大量のログがでるので驚くことになります。
エラーログから間違えた場所を探すのは苦労するので、沢山書いてからRe:VIEW記法に書き直せばいいやというスタンスより、ちょっとずつ取り込んでおくほうが安心です。
テンプレートリポジトリのCIはそのために存在しています。

== review-epubmaker

Expand All @@ -56,19 +58,7 @@ book.epub: EPUB ebook data
（電子書籍リーダに読み込ませることで内容を確認出来る）
//}

YAMLファイル内の@<code>{bookname}を元にして出力されるファイル名を決定します。

コマンド内部で後述の@<code>{review-compile}を利用しており、HTML生成のオプションには@<tt>{config.yml}に項目がないものもあります。
そういったオプションを使用するには@<code>{review-compile}コマンドのオプションを任意に記述できる@<code>{params}という項目を使います。
@<list>{config_yml_chapterlink}は@<code>{--chapterlink}オプションを設定する例です。

//list[config_yml_chapterlink][--chapterlinkオプションをconfig.ymlで指定する]{
bookname: C89-FirstStepReVIEW-v2
stylesheet: ["style.css"]
epubversion: 3
〜中略〜
params: --chapterlink
//}
YAMLファイル内の@<code>{bookname}を元にして出力ファイル名を決定します。

#@# prh:disable
== review-webmaker
Expand All @@ -89,81 +79,3 @@ webroot: directory
#@# prh:disable
//image[webroot][review-webmakerの出力例][scale=0.75]{
//}

== review-compile

@<code>{review-compile}はRe:VIEWファイル１つを@<code>{--target}オプションで指定するフォーマットに変換します。

もっとも簡単な例として、HTMLを出力する例を@<list>{review-compile-example-html-1}に示します。

//list[review-compile-example-html-1][review-compileでHTMLを出力する例]{
> review-compile --target=html preface.re
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"
xmlns:epub="http://www.idpf.org/2007/ops"
xmlns:ops="http://www.idpf.org/2007/ops"
xml:lang="ja">
<head>
<meta charset="UTF-8" />
<link rel="stylesheet" type="text/css" href="style.css" />
<meta name="generator" content="Re:VIEW" />
<title>はじめに</title>
</head>
<body>
<h1><a id="h"></a>はじめに</h1>
<p>技術書をかこう！〜はじめてのRe:VIEW〜を手に取っていただき、ありがとうございます。本書は色々な種類・性質の技術書がもっと世の中に溢れてほしい、という気持ちから生まれました。本書を支えるRe:VIEWというツールの解説に始まり、印刷を発注し紙の本として体裁を整えるところまでフォローします。つまり、この本は技術書をこの世に誕生させるためのスキルがひととおり身につくガイドブックなのです。</p>
<p>タイトルにもあるRe:VIEWは書籍制作のためのツールセットです。すこしの文法をおぼえるだけで技術書がつくれる優れものです。</p>
... (以下省略)
//}

HTML出力以外にも
プレーンテキスト形式にする@<code>{--target=text}、PDFを出力するために必要なTeX形式のファイルを出力する@<code>{--target=latex}、
軽量マークアップ言語であるMarkdown形式を出力する@<code>{--target=markdown}などがあります。

読者の環境で@<code>{--target}で指定できるフォーマットを調べるには、
Re:VIEW本体のインストール先にある@<code>{lib/review/???builder.rb}というファイル名のファイルを確認するのが早道です。

//cmd{
> ls lib/review/*builder.rb
lib/review/builder.rb lib/review/ewbbuilder.rb lib/review/idgxmlbuilder.rb
lib/review/latexbuilder.rb lib/review/textbuilder.rb lib/review/epubbuilder.rb
lib/review/htmlbuilder.rb lib/review/inaobuilder.rb lib/review/markdownbuilder.rb
lib/review/topbuilder.rb
//}
対応する出力形式の多くはRe:VIEW開発者らが仕事上利用するために用意されました。
執筆時には@<code>{reveiew-webmaker}などを指定する機会が多いでしょうが、こんな変換も可能なんだな、と知っておくと再利用で便利かもしれません。
#@# REVIEW vv: しょうみ、僕は執筆時pdfにしか変換しなくなりましたね… どう？これ以降も僕のやり方とは結構違っているかもしんない。
#@# review mhidaka Atomでlanguage-reviewつかってプレビューみてる
@<code>{--check}を指定すると結果は出力せず、そのフォーマットで入力したファイルが正しく変換できるかを確認します。
たとえば、@<code>{footnote}と@<code>{fn}で対応がとれていなければ、その旨が表示されます。エラーを避けるために便利なヒントです。
//cmd{
> review-compile --check --target=html build.re
build.re:11: error: ReVIEW::KeyError
//}
出力されたhtmlの見栄えを調整するには
@<code>{--yaml=(ファイル名)}でRe:VIEWプロジェクトの設定（@<tt>{config.yml}など）を読み込ませるととよいでしょう。設定ファイル指定のスタイルを変更できます。
#@# REVIEW vv: これなんだっけ config.ymlのこと？
@<code>{--all}を指定すると、指定したファイルだけではなく@<tt>{catalog.yml}に記載されている　すべてのファイルを一気にコンパイルすることもできます。
@<code>{＠<chapref>{chapter\}}や@<code>{＠<hd>{head\}}などの章・見出しの参照をリンクにする@<code>{--chapterlink}というオプションもあります。
なお、@<code>{--help}を指定すると、ファイルを読み込んで変換する代わりに対応するオプションの一覧が表示されます。
本章で説明されていないオプションも多々あるので、必要に応じて参照してください。
=== @<code>{review-compile}の性質
@<code>{review-compile}は主に単一のファイルに対して操作を行います。いわば内部コマンドに近い挙動です。
@<code>{review-pdfmaker}や@<code>{review-epubmaker}などはRe:VIEWプロジェクト全体が対象です。これらコマンドの目的は最終出力なため、用途も異なります。
現時点では@<code>{review-compile}からは直接PDFとEPUB形式のファイルを生成することはできません@<fn>{target_epub_is_not_for_epub}。
仮に執筆途中の一部のRe:VIEWファイルのみ、PDFフォーマットで確認したい場合には自分自身でTeX形式から生成する、
あるいは逆に全体を@<code>{review-pdfmaker}で生成したあと、該当する章をpdktk@<fn>{pdftk}等のコマンドで切り出してください。
//footnote[target_epub_is_not_for_epub][@<code>{--target=epub}は圧縮してEPUB形式とする前のただのHTMLを出力します]
//footnote[pdftk][@<href>{https://www.pdflabs.com/tools/pdftk-the-pdf-toolkit/}]
2 changes: 1 addition & 1 deletion articles/config.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ date: 2023-10-31
# 複数指定する場合は次のように記述する
# [["初版第1刷の日付", "初版第2刷の日付"], ["第2版第1刷の日付"]]
# 日付の後ろを空白文字で区切り、任意の文字列を置くことも可能。
history: [["2023-10-31 技術書典15版 v0.0.3"]]
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
Expand Down
Loading

0 comments on commit c24fdfb

Please sign in to comment.