diff --git a/articles/build.re b/articles/build.re index 7a29e04..d6b0971 100644 --- a/articles/build.re +++ b/articles/build.re @@ -1,10 +1,9 @@ ={build} 書籍をビルドする 本章ではRe:VIEWファイルをコンパイルする方法を解説します。 -PDFを出力する@{review-pdfmaker}、EPUBを出力する@{review-epubmaker}、Webページを出力する@{review-webmaker}、 -フォーマットを変換する@{review-compile}を順番に紹介します。 +PDFを出力する@{review-pdfmaker}、EPUBを出力する@{review-epubmaker}、Webページを出力する@{review-webmaker}を順番に紹介します。 -入稿に利用する形式は@{review-pdfmaker}コマンドでのPDF形式ですが、Re:VIEWは、Markdown、プレーンテキスト、HTMLやEPUBなど多様なフォーマットに対応しています。 +入稿に利用する形式は@{review-pdfmaker}コマンドでのPDF形式ですがRe:VIEWは、Markdown、プレーンテキスト、HTMLやEPUBなど多様なフォーマットに対応しています。 == review-pdfmaker @@ -20,25 +19,28 @@ YAMLファイルには本のタイトルや筆者名といった本のメタデ その設定のひとつ@{bookname}が出力ファイル名に対応しています。 @{bookname}が「book」となっている場合、生成した@{book.pdf}を自身のディレクトリに保存します。 -#@# NOTE vv: この辺変わってる 基本はtmpdirに出力される --debug 有りでbook-pdfディレクトリに出力するが、その場合も古いディレクトリは自動的に削除されてから処理が実行される -#@# https://github.com/kmuto/review/blob/331aa87595b5188fc765e04a81ae8205dac41785/lib/review/pdfmaker.rb#L63-L74 -#@# 対応済み -@{review-pdfmaker}は内部で後述のコマンド@{review-compile --target=latex}を実行します。 -そのあとに@{platex}や@{dvipdfmx}のようなTeX形式のファイルからPDFへ変換する外部コマンドを実行します。 -Re:VIEW外部のコマンドを実行している際には外部のログがそのまま標準出力や標準エラー出力に反映されるため、驚くかもしれません。 +@{review-pdfmaker}の内部では別のコマンド@{review-compile --target=latex}を実行しています。 +そのあとに@{platex}や@{dvipdfmx}のようなTeX形式のファイルからPDFへ変換するRe:VIEW以外の外部コマンドを実行します。 -=== 制作時の注意点 +=== 制作時に出会うエラーたち @{review-pdfmaker}をはじめて使うときは作法がわからず戸惑うかもしれません。 -もっとも単純な事例では、catalog.ymlの@{CHAPS}で章の指定を忘れることです。 -構文エラーが発生すると標準出力に発生時点のエラーログが残ります。これを手がかりに問題の箇所を探すことになります。 +もっとも単純な事例では@{catalog.yml}の@{CHAPS}で追加した@{.re}ファイルを書き忘れることです。 +単純に参照がない場合もビルドが成功するので（機械にはわからないエラーなので）追加分が見えないため慣れないうちは困惑します。 -リストに掲載したソースコードが長すぎて紙面をはみ出している場合、箇条書きのつもりで書いた「@{*}」が半角スペースを忘れていて直接本文に表示されている場合など -見た目の問題についてはビルドエラーとはなりません。 +検出しにくい見た目の問題も挙げましょう。 -執筆後半となると、見栄えの調整のために頻繁に@{review-pdfmaker}を実行するので注意すべきポイントとして覚えておくとよいでしょう。 -意図したレイアウトでPDFが出力されているかは作成者によるケアが必要です。 + * 本文中にリストとして掲載したソースコードが長すぎて紙面をはみ出している場合 + * 箇条書きのつもりで書いた「@{*}」が半角スペースを忘れていて直接本文に表示されている場合 + * 表に複数行のテキストを入れたら折返しがうまくいかず不格好になる場合 + +装飾やレイアウトの問題についてはビルドエラーとはなりません。意図したレイアウトでPDFが出力されているかは作成者によるケアが必要です。 + +最後にRe:VIEW記法を間違えたときは構文エラーが起きます。エラーが発生すると標準出力に発生時点のログが残るのでとりあえず眺めることになるでしょう。 +前述の説明のとおり、TeXの出力ログやエラーも含まれているので急に大量のログがでるので驚くことになります。 +エラーログから間違えた場所を探すのは苦労するので、沢山書いてからRe:VIEW記法に書き直せばいいやというスタンスより、ちょっとずつ取り込んでおくほうが安心です。 +テンプレートリポジトリのCIはそのために存在しています。 == review-epubmaker @@ -56,19 +58,7 @@ book.epub: EPUB ebook data （電子書籍リーダに読み込ませることで内容を確認出来る） //} -YAMLファイル内の@{bookname}を元にして出力されるファイル名を決定します。 - -コマンド内部で後述の@{review-compile}を利用しており、HTML生成のオプションには@{config.yml}に項目がないものもあります。 -そういったオプションを使用するには@{review-compile}コマンドのオプションを任意に記述できる@{params}という項目を使います。 -@{config_yml_chapterlink}は@{--chapterlink}オプションを設定する例です。 - -//list[config_yml_chapterlink][--chapterlinkオプションをconfig.ymlで指定する]{ -bookname: C89-FirstStepReVIEW-v2 -stylesheet: ["style.css"] -epubversion: 3 -〜中略〜 -params: --chapterlink -//} +YAMLファイル内の@{bookname}を元にして出力ファイル名を決定します。 #@# prh:disable == review-webmaker @@ -89,81 +79,3 @@ webroot: directory #@# prh:disable //image[webroot][review-webmakerの出力例][scale=0.75]{ //} - -== review-compile - -@{review-compile}はRe:VIEWファイル１つを@{--target}オプションで指定するフォーマットに変換します。 - -もっとも簡単な例として、HTMLを出力する例を@{review-compile-example-html-1}に示します。 - -//list[review-compile-example-html-1][review-compileでHTMLを出力する例]{ -> review-compile --target=html preface.re - - - - - - - - はじめに - - -

はじめに

-

技術書をかこう！〜はじめてのRe:VIEW〜を手に取っていただき、ありがとうございます。本書は色々な種類・性質の技術書がもっと世の中に溢れてほしい、という気持ちから生まれました。本書を支えるRe:VIEWというツールの解説に始まり、印刷を発注し紙の本として体裁を整えるところまでフォローします。つまり、この本は技術書をこの世に誕生させるためのスキルがひととおり身につくガイドブックなのです。

-

タイトルにもあるRe:VIEWは書籍制作のためのツールセットです。すこしの文法をおぼえるだけで技術書がつくれる優れものです。

-... (以下省略) -//} - -HTML出力以外にも -プレーンテキスト形式にする@{--target=text}、PDFを出力するために必要なTeX形式のファイルを出力する@{--target=latex}、 -軽量マークアップ言語であるMarkdown形式を出力する@{--target=markdown}などがあります。 - -読者の環境で@{--target}で指定できるフォーマットを調べるには、 -Re:VIEW本体のインストール先にある@{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開発者らが仕事上利用するために用意されました。 -執筆時には@{reveiew-webmaker}などを指定する機会が多いでしょうが、こんな変換も可能なんだな、と知っておくと再利用で便利かもしれません。 -#@# REVIEW vv: しょうみ、僕は執筆時pdfにしか変換しなくなりましたね… どう？これ以降も僕のやり方とは結構違っているかもしんない。 -#@# review mhidaka Atomでlanguage-reviewつかってプレビューみてる - -@{--check}を指定すると結果は出力せず、そのフォーマットで入力したファイルが正しく変換できるかを確認します。 -たとえば、@{footnote}と@{fn}で対応がとれていなければ、その旨が表示されます。エラーを避けるために便利なヒントです。 - -//cmd{ -> review-compile --check --target=html build.re -build.re:11: error: ReVIEW::KeyError -//} - -出力されたhtmlの見栄えを調整するには -@{--yaml=(ファイル名)}でRe:VIEWプロジェクトの設定（@{config.yml}など）を読み込ませるととよいでしょう。設定ファイル指定のスタイルを変更できます。 -#@# REVIEW vv: これなんだっけ config.ymlのこと？ - -@{--all}を指定すると、指定したファイルだけではなく@{catalog.yml}に記載されている　すべてのファイルを一気にコンパイルすることもできます。 - -@{＠{chapter\}}や@{＠{head\}}などの章・見出しの参照をリンクにする@{--chapterlink}というオプションもあります。 - -なお、@{--help}を指定すると、ファイルを読み込んで変換する代わりに対応するオプションの一覧が表示されます。 -本章で説明されていないオプションも多々あるので、必要に応じて参照してください。 - -=== @{review-compile}の性質 - -@{review-compile}は主に単一のファイルに対して操作を行います。いわば内部コマンドに近い挙動です。 -@{review-pdfmaker}や@{review-epubmaker}などはRe:VIEWプロジェクト全体が対象です。これらコマンドの目的は最終出力なため、用途も異なります。 - -現時点では@{review-compile}からは直接PDFとEPUB形式のファイルを生成することはできません@{target_epub_is_not_for_epub}。 -仮に執筆途中の一部のRe:VIEWファイルのみ、PDFフォーマットで確認したい場合には自分自身でTeX形式から生成する、 -あるいは逆に全体を@{review-pdfmaker}で生成したあと、該当する章をpdktk@{pdftk}等のコマンドで切り出してください。 - -//footnote[target_epub_is_not_for_epub][@{--target=epub}は圧縮してEPUB形式とする前のただのHTMLを出力します] -//footnote[pdftk][@{https://www.pdflabs.com/tools/pdftk-the-pdf-toolkit/}] diff --git a/articles/config.yml b/articles/config.yml index 40c695b..ec268bd 100644 --- a/articles/config.yml +++ b/articles/config.yml @@ -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 diff --git a/articles/configure.re b/articles/configure.re index 465f89d..9eddf43 100644 --- a/articles/configure.re +++ b/articles/configure.re @@ -5,7 +5,6 @@ Re:VIEWでは書籍に関する情報を章を設定する@{catalog.yml}と =={catalog_yml} 目次を構成するcatalog.yml -#@# https://github.com/kmuto/review/wiki/catalog.yml #@# https://github.com/kmuto/review/blob/master/doc/catalog.ja.md @{catalog.yml}は章立ての設定ファイルです。 @@ -54,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}] @@ -65,41 +64,40 @@ YAMLに馴染みがないと忘れがちですが、Collection@{url_yaml_col Re:VIEWでは本を生成（コンパイル）するときのメタデータをYAMLで記述します。 コンパイル時の指定方法は@{build}を参照してください。 -ファイル名に決まりはありませんが慣例的にconfig.ymlとしています。 +ファイル名に決まりはありませんが慣例的に@{config.yml}としています。 書名や奥付の内容、どの深さまで目次に含めるかなどを設定できます。 @{config_yml}は本書で使っている@{config.yml}です。 //list[config_yml][config.yml]{ -# review-epubmaker向けの設定ファイルの例。 # ブック名(ファイル名になるもの。ASCII範囲の文字を使用) bookname: C89-FirstStepReVIEW-v2 # 記述言語。省略した場合はja language: ja # 書名 -booktitle: 技術書をかこう！～はじめてのRe:VIEW～ +booktitle: {name: "技術書をかこう！～はじめてのRe:VIEW～", file-as: "ギジュツショヲカコウ"} # 著者名。「, 」で区切って複数指定できる -aut: ["TechBooster編"] +aut: [{name: "TechBooster編", file-as: "techboosterヘン"}] + # a-edt, edt: 編集者 edt: ["mhidaka"] # a-pbl, pbl: 出版社（発行所） pbl: TechBooster + # 刊行日(省略した場合は実行時の日付) -date: 2017-8-11 +date: 2023-10-31 # 発行年月。YYYY-MM-DD形式による配列指定。省略した場合はdateを使用する -history: [["2015-12-31 C89版 v1.0.0"],["2017-8-11 C92版 v2.0.0"]] -# 権利表記 -rights: (C) 2017 TechBooster -# 固有IDに使用するドメイン。指定しない場合には、時刻に基づくランダムUUIDが入る +# 複数指定する場合は次のように記述する +# [["初版第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 + +# 固有IDに使用するドメイン。省略した場合は時刻に基づくランダムUUIDが入る urnid: urn:uid:https://github.com/TechBooster/C89-FirstStepReVIEW-v2 -# CSSファイル(配列で複数指定可) -stylesheet: ["style.css"] -# ePUBのバージョン (2か3) 省略した場合は2 -epubversion: 3 -# HTMLのバージョン (4か5。epubversionを3にしたときには5にする) -htmlversion: 5 - # 目次として抽出する見出しレベル toclevel: 2 # 本文でセクション番号を表示する見出しレベル @@ -108,24 +106,22 @@ secnolevel: 2 # 本文中に目次ページを作成するか。省略した場合はnull (作成しない) toc: true -# 表紙の後に大扉ページを作成するか。省略した場合はnull (作成しない) +# 表紙に配置し、書籍の影絵にも利用する画像ファイル。省略した場合はnull (画像を使わない)。画像ディレクトリ内に置いてもディレクトリ名は不要(例: cover.jpg) +# PDFMaker 固有の表紙設定は pdfmaker セクション内で上書き可能 +coverimage: cover.jpg +# +# 表紙の後に大扉ページを作成するか。省略した場合はtrue (作成する) titlepage: true + # 奥付を作成するか。デフォルトでは作成されない。trueを指定するとデフォルトの奥付、ファイル名を指定するとそれがcolophon.htmlとしてコピーされる +# デフォルトの奥付における各項目の名前（「著　者」など）を変えたいときにはlocale.ymlで文字列を設定する（詳細はdoc/format.ja.mdを参照） colophon: true -# ページ送りの送り方向、page-progression-directionの値("ltr"|"rtl"|"default") -direction: "ltr" - -# tatsumacroは、電子書籍版の制作に利用する -texstyle: techbooster-doujin - -# LaTeX用のdocumentclassを指定する -texdocumentclass: ["jsbook", "b5j,twoside,openany,uplatex"] //} 記述できる項目は多いので、Re:VIEW公式のサンプルとWikiを参照してください。 : サンプル - @{https://github.com/kmuto/review/blob/master/doc/sample.yml} + @{https://github.com/kmuto/review/blob/master/doc/config.yml.sample} : Wiki @{https://github.com/kmuto/review/wiki/config.yml} @@ -146,65 +142,91 @@ toclevel: 2 //image[toclevel3][toclevel:3を指定した場合の目次][scale=0.75]{ //} -=={layout} デザインを変更する +=={layout} 用紙サイズやデザインを変更する PDF形式で出力する紙面のデザインは差し替え可能です。@{config.yml}の@{texstyle:}項目の値を変更します（@{change_layout}）。 //list[change_layout][config.ymlにてスタイルファイルを指定]{ # LaTeX用のスタイルファイル(styディレクトリ以下に置くこと) -# texstyle: reviewmacro -# tatsumacroは、電子書籍版の制作に利用する -# texstyle: tatsumacro -texstyle: techbooster-doujin +# texstyle: ["reviewmacro"] //} -Re:VIEW、または本書のリポジトリには次の3つの設定が用意されています。 - : reviewmacro - Re:VIEWのデフォルトスタイルです。紙面にはあまり向いていません + Re:VIEWのデフォルトスタイルです。 + : viewermacro + 電子書籍向けのスタイルです。タブレットなどで見やすいように余白やフォントサイズを調整しています。TechBooster製のスタイルです。 - : tatsumacro - 電子書籍向けのスタイルです。タブレットなどで見やすいように余白やフォントサイズを調整しています +ReVIEW-Templateテンプレートリポジトリまたは本書のリポジトリには次の4つの@{texdocumentclass:}が用意されています。 - : techbooster-doujin - TechBooster製のスタイルです。紙面（B5サイズ）にむけて最適化しています + * B5の設定(10pt 40文字×35行) - 紙版 + * B5の設定(10pt 40文字×35行) - 電子版 + * A5の設定(9pt 38文字×37行) - 紙版 + * A5の設定(9pt 38文字×37行) - 電子版 -印刷が前提の場合、特にこだわりがなければ@{techbooster-doujin}を利用してください。もちろん独自のスタイルを作ることも可能です。 - -==== B5サイズでのお勧め設定 +==== B5サイズでの標準設定 //emlist[config.ymlの印刷用設定]{ -texstyle: techbooster-doujin -texdocumentclass: ["jsbook", "b5j,twoside,openany,uplatex"] +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"] //} -==== 電子書籍（PDF）でのお勧め設定 +==== 電子書籍（PDF）での標準設定 //emlist[config.ymlの電子書籍用設定]{ -texstyle: tatsumacro -texdocumentclass: ["jsbook", "oneside,14pt,uplatex"] +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"] //} -== サイズを変更する +B5ではなく少し小さいA5にしたい等で書籍にあった用紙サイズへ変更するだけであれば、これらのプリセットの利用を強く推奨します。 + +== スタイルにカスタマイズを加える -PDF形式で出力するページサイズを指定するには@{config.yml}の@{textdocumentclass:}項目の２番目の値を設定します（@{change_pagesize}）。 +@{config.yml}の@{textdocumentclass}はLaTeXにおけるドキュメントのクラスオプションに相当します。 +複数のオプションがある場合は、カンマで区切って列挙でき、ある程度のカスタマイズも可能です。 -この設定は、LaTeXにおけるドキュメントクラスのオプションに該当します。複数のオプションがある場合は、カンマで区切って列挙します。 -技術書であればb5jサイズが標準的です。 +前節で触れた標準設定でも多くのクラスオプションが登場していました。たとえば出力するページサイズを指定するには@{config.yml}の@{textdocumentclass}を次のようにします（@{change_pagesize}）。 -//list[change_pagesize][config.ymlにてページサイズをb5jに指定]{ -texdocumentclass: ["jsbook", "b5j"] +//list[change_pagesize][用紙サイズをB5に指定する例]{ +texdocumentclass: ["review-jsbook", "paper=b5"] //} -//table[papersize][設定できるページサイズ]{ +@{papersize}は@{review-jsbook}ドキュメントクラスに設定できる代表的な用紙サイズ（@{paper}クラスオプション）です。 +指定するドキュメントクラスによってクラスオプションで設定できる値が異なるので注意してください。 + +//table[papersize][設定できる用紙サイズ]{ 値 用紙サイズ ------------ -a4paper A4 -b5paper B5 -a4j A4 JIS -a5j A5 JIS -b5j B5 JIS +a4 A4 +a5 A5 +a6 A6 +b5 JIS B5 +b6 JIS B6 //} -@
{papersize}は、@{jsbook}ドキュメントクラスに設定できる代表的な用紙サイズです。 -指定するドキュメントクラスによっては、設定できる値が異なる場合があるので注意してください。 +=== review-jsbookに設定できる主な設定項目 + +@{review-jsbook}に設定可能なクラスオプションは公式ドキュメントにまとまっています。@
{review-jsbook}では、 +どのようなカスタマイズができるのか理解しやすいものを挙げています。 + + * @{https://github.com/kmuto/review/blob/master/templates/latex/review-jsbook/README.md} + +//table[review-jsbook][設定できる主なクラスオプションと説明]{ +オプション名 説明 +------------ +media 印刷用、電子用いずれかの用途 +cover_fit_page カバー画像を紙面に合わせる +paper 用紙サイズの変更 +fontsize 文字サイズ +startpage ページ開始番号。デフォルトは1 +//} + +Re:VIEWで利用している@{review-jsbook}はドキュメントクラスは標準的な@{jsbook}ドキュメントクラスを含んでいるので、一部のオプションはそのまま指定できます。 +たとえば@{onecolumn}であれば1段組の体裁、@{twocolumn}であれば2段組の体裁を実現します。 +ただし、このようなドキュメントの見た目に対して調整を行うにはTeXと書籍の専門知識が要求されます。 + +たとえば本のルールには章の始まりを左ページ（偶数）、右ページ（奇数）に固定できるというものがあります。一般人からすると改ページの位置が左右どっちにくるのかという問題自体に馴染みがありませんよね。@{openany}を指定すると左右どちらからでも章を開始できる！と気づいてしまい、ページ数を減らせるから印刷代もちょっと安くなるじゃないか？と考えたとしても入稿直前の疲れたタイミングで変更することは推奨しません。期せず発生する副作用に悩まないように十分検証期間を設けるなど余裕を持って作業してください。 + diff --git a/articles/distribution.re b/articles/distribution.re index 5a1bf61..cc15c2c 100644 --- a/articles/distribution.re +++ b/articles/distribution.re @@ -9,14 +9,14 @@ 前提としてターゲットとする読者（技術を使って欲しい人、興味がある人）はあなたの本を読みたがっています。 せっかく書いたわけですからいろいろな人に存在を知ってほしいところです。 -コミックマーケット、技術書典のようなイベントを中心に考えたとき、次のような流入経路があります。 +技術書典のようなイベントを中心に考えたとき、次のような流入経路があります。 * 公式ウェブサイトから出展者情報へアクセスする * 当日、ばったり出会う * ソーシャルメディア、ブログの告知から知る 公式サイトでは、出展者情報を一覧で見れるカタログが整備されています。一般参加者はカタログを見て目当ての技術書を探します。 -技術書が完成したら、こまめに頒布内容を更新しておきましょう。サークルカット（サムネイル画像）を用意するのもお勧めです。 +技術書が完成したら、こまめに頒布内容を更新しておきましょう。サークル画像や書籍情報（サンプル画像）を充実するのもお勧めです。 文字に比べて一気に情報量が増えます。 イベント会場では、当日ばったり出会った技術書を気に入ることもしばしばあります。 @@ -24,10 +24,10 @@ 自然と参加者の目に止まり、手に取ってくれることも多いです。チャンスを逃さず、にこやかに対応したいものですね。 ３つ目はソーシャルメディアです。もっとも効果が期待できる流入経路です。 -ニッチな技術書だからといって遠慮することはありません。書籍の表紙やサンプルページなど画像とともに -訴求していきましょう。Twitterであればハッシュタグ@{hash}を活用して告知してください。 +ニッチな技術書だからといって遠慮することはありません。書籍の表紙やサンプルページなど画像とともに訴求していきましょう。 +XやblueskyのようなSNSであればハッシュタグ@{hash}を活用して告知してください。 -//footnote[hash][技術書典であれば#技術書典、コミックマーケット92であれば#C92などの略称が使われます] +//footnote[hash][技術書典であれば#技術書典、コミックマーケット103であれば#C103などの略称が使われます] いずれの告知方法も一朝一夕で効果がでるものではないのですが、やらないよりはずっと効果が期待できます。 もっとも確実な告知は継続的な参加とアウトプットです。即効性はありませんが一度読んで面白かった本のことは良く覚えてるものです@{power}。 @@ -51,7 +51,7 @@ 見本誌 ◯ 手にとって見られるようにサンプルがあると便利 お釣り ◯ ある程度多めに準備しよう お釣り入れ ◯ お札と硬貨を管理するケースなど -敷き布 - 90x120cmあると十分。ただの布でOK +敷き布 - 90x180cmあると十分。ただの布でOK 文房具 - マジックなど。値札やPOPづくりに便利 ハサミ - カッターもあるとなおよい ガムテープ - 梱包に利用 @@ -65,12 +65,16 @@ //} 表ではよく使われてるものを中心に集めています。また必須の項目には◯をつけました。これらの準備は前日までに終わらせておくとベターです。 +技術書典では電子決済をサポートしているので現金をもってこない出展者も見かけるようになりましたが、それ以外のイベントでは現金もまだまだ現役です。 -イベントでは180センチ長の机を使います。多くの場合、机半分の90cm幅が展示スペースとして割り当てられます。 -出展者は開場の１～2時間前には入場して自分のスペースをレイアウトします。周りも展示の準備をしていますので -スペースのはみ出し、通路を塞ぐような荷物には注意してマナーを守って過ごしてください@{eyes}。 +イベントでは180センチ長の机を使います。技術書典の場合は机1本の180cmが割り当てられます。それ以外のイベントであれば多くの場合、机半分の90cm幅が自由に使える展示スペースです。 +出展者は開場の１～2時間前には入場して自分のスペースをレイアウトします。周りも展示の準備をしていますのでスペースのはみ出し、 +通路を塞ぐような荷物には注意してマナーを守って過ごしてください@{eyes}。 //footnote[eyes][時間帯によっては通路が混雑します。貴重品の管理は厳重に！] +今回、必須としていませんがポスターはコスパよく訴求できるのでおすすめしたい準備物です。どんな読者に読んでほしいか、目に付きやすいキャッチコピーやPRを記載しておくといいでしょう。 +よくできたポスターには眼の前を素通りさせないパワーがあります。 + 展示物にあわせてタブレットをつかったり、ハードウェアの実演、パネルやイーゼルで見やすく配置して工夫してもよいでしょう。 -来場者も技術が好きなひとです。あまり構えず、気楽に来場者と会話してみてください。楽しい時間がすごせるはずです。 +来場者も技術が好きなひとです。あまり構えず、気楽に来場者に声をかけ、会話してみてください。楽しい時間がすごせるはずです。 diff --git a/articles/images/workflow/lint.png b/articles/images/textlint/lint.png similarity index 100% rename from articles/images/workflow/lint.png rename to articles/images/textlint/lint.png diff --git a/articles/planning-book.re b/articles/planning-book.re index 931abcf..7b3b9ff 100644 --- a/articles/planning-book.re +++ b/articles/planning-book.re @@ -7,7 +7,7 @@ == モチベーションを育てよう -技術書を執筆する意味は何でしょうか。筆者は大きく3つがあると考えています。 +技術書を執筆する意味は何でしょうか。わたしたちは大きく3つがあると考えています。 * 自分の技術をまとめたい、本にしたいという欲求 * 技術の普及、共同執筆者の存在、プロジェクトとしての楽しさ @@ -29,37 +29,38 @@ == 同好者が集まる場所へ行く 本を読んでもらうためには場所も重要な要素です。 -読みたいとおもってくれそうな人にむけてリリースしないと食いついてもらえません。 +読みたいとおもってくれそうな人に向けてリリースしないと食いついてもらえません。 分かりやすい例では勉強会やカンファレンスといったエンジニア文化圏ですが、集まる人数は多くて数百人、しかもセミナー形式の 聞いて勉強するスタイルが主流です。書籍を配るには、すこしパンチに欠けますね。 -技術書が流通するもっとも有名なイベントはコミックマーケットでしょう。 -8月と12月の年2回、50万人を超える参加者が集う巨大マーケットです。参加者はそれぞれの趣味を楽しみにきており、その一角に技術書が居ます。 -コミックマーケットにはジャンルというくくりがあり、ジャンル毎に何日目のどのあたりの場所、とざっくり決まっています。 -技術書であれば、「同人ソフト」または「評論・情報」のどちらかで応募している場合が多いです。 -ちなみに、TechBoosterは毎回同人ソフトジャンルとしてコミックマーケットに応募・参加しています。 -もうひとつ、最近できたイベントが技術書典@{techbookfest}です。これまで秋葉原で開催されており、 -4月と10月の年2回、約3500人が来場する技術書のためのイベントです（@{techbookfest}）。 +技術書が流通するイベントが@{技術書典,ぎじゅつしょてん}@{techbookfest}です。 +4月と10月の年2回、約10,000人が参加する技術書のためのイベントです（@{techbookfest}）。 //image[techbookfest][技術書典ウェブサイト][scale=0.75]{ //} 技術書典は「技術書にフォーカスし、技術者があつまってはなし、新しい技術に触れる」場所です。 +これまでに秋葉原、池袋で開かれており、2023年11月には技術書典15がオフライン・オンライン同時開催します。 +一箇所に集まって熱量を感じるもよし、はじめてで準備に集中したいときや遠方でオフライン会場への来場が難しくてもオンラインマーケットに参加すれば場所によらず、全国の同好者にPRできます。 -このような事情を加味すると、同人誌をリリースする場合のターゲットは自然とコミックマーケットまたは技術書典に絞られてきます。 +技術書典のWebアカウント保持者は5万人程度です。技術書が好きな人が集まるイベントとしては最大級の規模になってきています。このような事情を加味すると、同人誌をリリースする場合のターゲットは自然と絞られるはずです。 //footnote[techbookfest][@{https://techbookfest.org/}] +本が集まるもっとも有名なイベントはコミックマーケットでしょう。いわゆるサブカルチャーが集まる即売会です。 +8月と12月の年2回、約25万人の参加者が集う巨大マーケットです。参加者はそれぞれの趣味を楽しみにきており、その一角に技術書が居ます。コミックマーケットにはジャンルというくくりがあり、ジャンル毎に何日目のどのあたりの場所、とざっくり決まっています。技術書であれば、「同人ソフト」または「評論・情報」のどちらかで応募している場合が多いです。 +ちなみに、TechBoosterは同人ソフトジャンルでモバイルアプリ関連技術で本を出しています。 + == 書きたいものを書こう 世の中には沢山の技術書があるはず、と読者の皆さんは考えるかもしれません。 またプロが書いた技術書と比べると…と気後れするかもしれません。かくいう筆者も本屋さんで沢山のよい本に出会いました。 -しかし心配は無用です。ひとつは商業誌は思ったより種類が少ないということです。 -近年は技術の変遷も速く、本屋さんにならぶ商業誌では変化のスピードに太刀打ちできない状況がつづいています。 +しかし心配は無用です。理由のひとつは商業誌は思ったより種類が少ないということです。 +近年は技術の変遷も速く、本屋さんにならぶ商業誌では変化のスピードに太刀打ちできない状況が続いています。 書籍で紹介されているソフトウェアのバージョンが古く、インストールでつまずいた経験を数えればキリがありません。 付け加えると、ひとつの技術が業界の大勢を決する時代は過ぎ去りました。いまや多くの技術要素が複雑に絡まり合って @@ -69,7 +70,7 @@ 技術書を書きはじめる前に「何について書くか」のテーマが必要ですが、ぶっちゃけ何を書いてもよいのです。 前述のイベントでは、どのような技術ジャンルでも取り扱っています。 -たとえば技術書典ではソフトウェア、ハードウェア、自然科学、その他と幅広い技術について約200の出展者が集まっています。 +たとえば技術書典ではソフトウェア、ハードウェア、自然科学、その他と幅広い技術について約400～500の出展者が集まっています。 //image[books][TechBooster発行の技術書]{ //} @@ -80,13 +81,17 @@ 自分の好きなように書いて、見た人がカッコイイと思ってしまうものが作りたいですね。 せっかく作るからには書きたいものを書いてみましょう。これはモチベーションの維持にとても大切な姿勢です。 -書きたくないことをはじめても気持ちは長続きしません。自分の身近なところからテーマをさがしてみてください。 +書きたくないことをはじめても気持ちは長続きしません。自分の身近なところからテーマを探してください。 経験をアウトプットするもよし、技術について調査、検証した結果をまとめてもよいでしょう。 趣味として触ってみた、作ってみたものについて書いてもいいですね。 どうせなら、盛大にやらかしてしまった失敗録でもいいかもしれません。 本書を読み進めることでこれを実現するための書籍制作のための技術、手法、制作にかかる知識を吸収できます。 +そして技術がニッチだから、、もう誰かが書いているから、と遠慮することもありません。書籍の世界では類書がある事実をもって市場があると判断する考え方があります。だれかが証明した後なので類書も盛り上がるということですね。ニッチな技術を追いかけているんだけど、、という場合はどうでしょうか。技術書典には5万人のユーザーがいます。その中の0.1%に刺されば50人の読者がいるわけです。 + +書籍をつくるまえに思いつく不安は沢山ありますが勇気を出して、書きたいことを書いて読みたいものを読んでもらう自由さを楽しんでください。 + == 予算を考える @@ -96,7 +101,7 @@ #@# 明日がきた #@# vv: これすき -出版業を営んでいない以上、予算は懐具合に依存します。悲しいけど現実です。そして制作にかかる出費は規模に依存します。 +出版業を営んでいない以上、予算は懐具合に依存します。悲しいけれど現実です。そして制作にかかる出費は規模に依存します。 サンプルとして表紙がカラー、本文40ページ、B5サイズで100部の技術書をはじめて作るというモデルケースを取り上げてみましょう（@
{yosan}）。 @@ -112,15 +117,20 @@ 外注費 表紙を発注する場合 （3万円〜） //} -表にあるとおり表紙制作およびデザインを委託しない最小限で構成すると5万円程度です。この場合は1冊あたり500円が採算ラインです。 +@
{yosan}にあるとおり表紙制作およびデザインを委託しない最小限で構成すると5万円程度です。この場合は1冊あたり500円が採算ラインです。 なお印刷所への入稿手順に関しては@{publishing-book}を確認してください。 -ここでちょっと気になる部数に触れておきましょう。予算計画を変えて200部を刷った場合、印刷費は4万円程度です。1冊あたり300円まで採算ラインが下がります。 +ここで読者のみなさんが気になる部数に触れておきましょう。予算計画を変えて200部を刷った場合、印刷費は4万円程度です。この場合には1冊あたり300円まで採算ラインが下がります。 一方、50部に計画を変更しても印刷費は2万5000円程度にしか下がりません（1冊あたり900円です）。 たくさん刷れば採算をとりやすくなりますが、これはたくさん頒布できることが前提の計算です。 少々ならともかく、大量の在庫を抱えたくはないので自分の懐と相談しながらよい着地を目指していきましょう。 +一種のリスクコントロールが求められるわけですが技術書典参加者の間でも難しいという声があがっていました。 +このような問題を解決すべく技術書典では独自に@{後から印刷}@{afterprinting}といった受注生産の仕組みを備えています。 + +//footnote[afterprinting][注文を受けてから印刷し、後日に匿名配送されるシステムの総称。購入者には先に電子版を渡し、後から印刷する時差を解消している] + =={plan} 企画を立てよう 企画では自分が書きたいことを書き、その上で計画した部数を頒布できるアプローチ力が求められます。 @@ -139,8 +149,10 @@ キャッチコピーを用意してもいいですね。 「アンチパターン」というキャッチコピーを見ると、つい中身を確認してどんなコードか改めたくなってしまうものです@{dont-be-evil}。 +//footnote[dont-be-evil][遊び心があるタイトルだとつい見てしまいますね。知的好奇心万歳！] + タイトルや表紙、目次は、みたひとがこんな本かな？と想像でき、 -またその想像と内容が一致している状況があれば企画は成功したといって過言ではありません。 +また想像と内容が一致している状況があれば企画は成功したといって過言ではありません。 自分が好きな技術を思ったとおりのターゲットに届けることができているわけです。 もし、書きたい内容に迷ったら書店で技術書の棚をみてください。どんな本が多く売れているか、店員さんに聞いてみるのもいいでしょう。 @@ -148,10 +160,16 @@ 同人誌ですからね。やりたい放題自由にやっていきましょう。 技術書典における発行部数は50部〜200部@{trycatch}、最頻値は100部です。 -一般的に商業誌の初版部数は3000部程度なので桁が違います。 +一般的に商業誌の初版部数は1,000~2,000部程度なので桁が違います。 我々は同人誌の特徴をこそ活かすべきで、100部売れるようなニッチな内容で全然問題ありません。 むしろコミックマーケットや技術書典といったイベントではニッチな本ほど喜ばれる傾向@{what-a-foolish-book}があります。 -商業誌に比べてページ数が少ない@{thin}のでスナックに読みやすい点も、同人誌が受け入れられているポイントです。 + +商業誌に比べてページ数が少ない@{thin}のでカジュアルに読みやすい点も、同人誌が受け入れられているポイントです。必要な事柄を網羅するのも大事ですが、そうするとどんどん厚くなっていき、ボリュームのなかに主題が埋没してブレやすくなります。本を薄く作るのもまた腕の見せ所なのです。 + +#@# prh:disable +//footnote[trycatch][TechBoosterは発行部数が多いですが何事にも例外は存在するということです。みんなありがとね！] +//footnote[what-a-foolish-book][なにこれ笑笑 ここにしかないでしょ絶対買うわ！という推せるときに推すノリです] +//footnote[thin][同人誌を薄い本と表現します。なお技術系同人誌には薄くない薄い本が稀によく存在しています] 企画の原点に悩んだら、仕事で困っていたことや不便に感じていること、気になっているんだけど調べられていない分野などテーマを決めて調べることがあります。 自分が好きなことを面白く読んでもらうための切り口探し、というのが適切かもしれません。 @@ -160,19 +178,13 @@ 深く考えず、技術的興味や、好きなジャンルを選んでください。 自分の好きな技術を魅力ある形で伝えていきましょう。 -//footnote[dont-be-evil][遊び心があるタイトルだとつい見てしまいますね。知的好奇心万歳！] -#@# prh:disable -//footnote[trycatch][TechBoosterは発行部数が多いですが何事にも例外は存在するということです。みんなありがとね！] -//footnote[what-a-foolish-book][なにこれワロスｗｗｗ買うわｗｗｗｗというノリですね] -//footnote[thin][同人誌を薄い本と表現します。なお技術系同人誌には薄くない薄い本が稀によく存在しています] - ==[column] 表紙を依頼するときの注意点 ここでは表紙を依頼@{illust}する際に伝えるべきポイントを紹介します。 * 具体的に本のテーマやテイストを伝える - * 表紙・裏表紙・ロゴなどデザインもしてほしいのか決めて伝える + * 表紙・裏表紙・ロゴ、タイトルなどデザインもお願いするのか決めて伝える * 可能な限り具体的に構図やポーズ、背景の有無などを伝える * 用途、発行部数、書籍以外の利用条件をまとめる * 制作料、締め切りを最初に決める @@ -194,6 +206,6 @@ 技術書の表紙と内容は二人三脚です。 -//footnote[illust][個人からの依頼を受けていないイラストレーターさんもいますが、イラスト制作を依頼できるサービスやブログなどのソーシャルメディア経由で探しての依頼が多いようです] - ==[/column] + +//footnote[illust][個人からの依頼を受けていないイラストレーターさんもいますが、イラスト制作を依頼できるサービスやブログなどのソーシャルメディア経由で探しての依頼が多いようです。最近ではAI生成イラストを使うことも増えています] diff --git a/articles/publishing-book.re b/articles/publishing-book.re index 764b867..d04ca16 100644 --- a/articles/publishing-book.re +++ b/articles/publishing-book.re @@ -13,31 +13,40 @@ 紙を印刷する場合は各印刷所でデータのフォーマットや記載内容のルールが異なります。 また電子書籍の場合、紙面とレイアウトが異なっていたり、文字サイズを変更できる（リフロー型とよばれる書籍）メリットがあります。 -いずれも見やすさや検索性で一長一短がありますね。TechBoosterでは紙面も電子書籍も両方つくって配っています。 +いずれも見やすさや検索性で特徴がありますね。TechBoosterでは紙面も電子書籍も両方をつくって配っています。 -本書のテンプレートレイアウトおよび制作手法で作った技術書は次の印刷所で実績があります -（が入稿を保証するものではありませんのでお気をつけください）。他にも探せば見つかるはずです！ +本書で紹介しているRe:VIEWテンプレートリポジトリおよび本書リポジトリの制作手法で作った技術書の本文は次の印刷所で実績があります。 +入稿を保証するものではありませんが、そのまま使う分には多くの実績があるので安心してください。他の印刷所への入稿実績も探せば見つかるはずです！ * 日光企画：@{http://www.nikko-pc.com/} * ねこのしっぽ：@{https://www.shippo.co.jp/neko/} +日光企画とねこのしっぽは、技術書典のバックアップ印刷所です。入稿のサポート、専用締切の提供をはじめオフライン会場当日の搬入を印刷所が行います。 +細かい話をすると印刷所によって料金プランや得意分野が違いますが、おいおい慣れてから考えればいいでしょう。はじめて利用するにはバックアップ印刷所はよい選択肢です。 + == 入稿のための最終出力を作る -印刷所へ最終的な印刷用データを渡すことを入稿と呼びます。 -本節では入稿について実際の事例をベースに解説します。 +印刷所へ最終的な印刷用データを渡すことを@{入稿,にゅうこう}と呼びます。 +本節では入稿手順を解説しますが入稿には専門的な注意点も多いため専門用語は出てきたタイミングで説明を補います。 -@{writing-book}で述べたとおり、同人誌向けのRe:VIEW構成を使用する前提です。本書のリポジトリをCloneしている場合、ノンブル（通し番号）のような同人誌特有の問題を回避できます。 +@{writing-book}で述べたとおり、同人誌向けのRe:VIEWプロジェクト構成を使用する前提です。TechBoosterのテンプレートリポジトリをcloneしている場合、@{ノンブル,通し番号}のような同人誌特有の問題を回避できます。 #@# prh:disable - * @{https://github.com/TechBooster/C89-FirstStepReVIEW-v2} + * @{https://github.com/TechBooster/ReVIEW-Template} -ここから先はTechBoosterが日光企画さんへ入稿した場合の手順として解説していきます。実のところ、印刷所ごとに印刷工程が違い、すべてで通用するスタンダードな方法というものはありません。 +ここからはTechBoosterが日光企画へ入稿した場合の手順を解説していきます。 +実のところ入稿方法は、これさえ知っていれば完璧といったスタンダードが存在していません。有名なIT企業のような大きな印刷所はなく、中小の企業が同人誌を支えており、 +そのため印刷工程やチェック項目が印刷所ごとに違ってきます。 -たとえば表紙データは印刷所ごとテンプレートが異なったり、入稿用本文にトンボ（断裁位置の目印）がないと受け付けてもらえなかったり、利用ソフトウェアのバージョン指定があったり、さまざまです。 +たとえば表紙データは印刷所ごとにテンプレートが異なったり、入稿用本文に@{トンボ,紙を断裁する位置の目印}がないと受け付けてもらえなかったり、 +利用ソフトウェアのバージョン指定があったり、違いはさまざまです。かといって、すべてを説明すると全体を理解する前に頭がパンクしてしまいます。 +今回は日光企画さんの事例に限って入稿に必要な知識をみていきましょう。実際には入稿予定の印刷所が指定するフォーマット、注意点を熟読して挑みましょう。 -かといって、すべてを説明すると流れを理解するまえに頭がパンクしてしまいます。ですので日光企画さんの事例に限って入稿に必要な知識をみていきましょう。実際には入稿予定の印刷所が指定するフォーマット、注意点を熟読して入稿に挑みましょう。 +とはいえ困ったことばかりではありません。 +繰り返すようにTechBoosterのRe:VIEWテンプレートを使っている限り、大きな問題には合いませんし、印刷所のスタッフさんも表紙や本文を目で確認してくれるため +誤字や脱字、はみ出しや印刷の問題が見つかって教えてくれるボーナスイベントも発生します。安心してください。 -入稿に先立って知っておく知識として、部数に応じて適した印刷手法が異なります。 +注文に先立って知っておく知識として、部数に応じて適した印刷手法が異なります。 : オンデマンド印刷 ～200部の小ロット印刷。印刷に使う版を作らないので手軽ですが単価は高めです @@ -45,11 +54,13 @@ : オフセット印刷 200部〜の印刷に利用。版を作る手法で、ロット数に応じて単価が安くなります -一般的にオフセット印刷のほうが品質がよいですが、近年の印刷技術向上によりオンデマンド印刷でも十分な品質を得られるケースがあります。 +オンデマンド印刷はざっくりと高級なコピー機をつかった印刷手法です。このふたつを比べると一般的にオフセット印刷のほうが品質がよいですが、近年では印刷技術向上によりオンデマンド印刷でも十分な品質を得られるケースがあります。 とくに品質については印刷所の腕の見せ所といえます。紙の種類も多数あるため詳細を知りたい場合は印刷所に相談するとよいでしょう。 だれもが最初から熟練者ではありません。はじめての人の相談にも快く応じてくれるでしょう。 -TechBoosterが過去に遭遇した事例では次のとおりです（印刷所選びに不安があれば本書のリポジトリ＋日光企画さんを使うとトラブルなく入稿できる可能性が高くなります）。 +納期という観点ではオンデマンド印刷よりオフセット印刷のほうが締切が早めです。版を作り、インクを定着させる工程があるためです。 + +TechBoosterが過去に遭遇した印刷所のルールは次のとおりです。驚かすつもりはないので印刷所選びに不安があれば日光企画やねこのしっぽを使うとトラブルなく入稿できる可能性が高くなります。 * 表紙データ：表紙は本文と別の形式で入稿する * ページ数：紙の消費単位の関係で4の公倍数とするなど制約がある @@ -63,195 +74,160 @@ TechBoosterが過去に遭遇した事例では次のとおりです（印刷所 鉄則は頒布する必要最低限だけ印刷して在庫を持たないことです。８掛けであれば予測を外しても大量には残らない数です。 同人誌においては新刊がもっとも売れます。残った在庫は既刊と呼ばれ、 -新刊ほどの勢いはありません。おおよそ２０％程度の販売速度になります。 +新刊ほどの勢いはありません。新刊と比較しておおよそ２０～５０％弱の頒布になります。 サークルごとに部数の指標は違いますが、TechBoosterは１５００～２０００部を用意してます。 -日光企画さんの場合はオンデマンド印刷、オフセット印刷どちらでもPDF入稿が可能です。 +日光企画の場合はオンデマンド印刷、オフセット印刷どちらでもPDF入稿が可能です。 つまり本書で紹介している手法で出力したらそのまま入稿形式となり、完璧！というわけです。便利ですね。 == 表紙データの作成方法 -印刷所ごとのフォーマットに合わせて表紙を作成します。フォーマットはPhotoshopのPSD形式です。 +印刷所ごとのフォーマットに合わせて表紙を作成します。フォーマットはAdobe PhotoshopのPSDファイル形式です。 イラストと表紙用の装丁をおこない、入稿用データを作成します（@{hyoushi}）。 //image[hyoushi][入稿データの一例]{ //} -表紙 1（表）と表紙 4（裏）に本の厚みも考慮した背を足したサイズが必要です。 -断ち切りのための遊びがどれぐらい必要か、なども印刷所に確認しておきます。 - -日光企画さんの標準的なセットでは背は0.063mm/ページで計算します。背幅は表紙も含めたページ数なので本文128ページであれば表紙をいれると132ページ（8.316mm）です。 +入稿ファイルのサイズは表紙１（表）と表紙４（裏）に本の厚みである背幅を足した横幅が最低限必要です。 +あとは断ち切りのための遊びがどれぐらい必要かなども印刷所に確認しておきます。 -ちなみに表紙は表紙１〜表紙４と呼び、ページ数に含めます。本の内側に来る表紙２、表紙３には通常印刷しません。 +背幅は紙の厚さとページ数で決まります。日光企画さんの標準的なセットでは0.063mm/ページで計算できます。背幅は表紙も含めたページ数なので本文128ページであれば表紙をいれると132ページなので背幅は8.316mmだとわかります。ちなみに表紙は表紙１〜表紙４と呼び、ページ数に含めます。本の内側に来る表紙２、表紙３は通常、印刷しません。 TechBoosterではデザイナーさんとイラストレーターさんが協力して表紙を作成しています。 -編集者が双方に書籍のイメージを伝えて構図を固めていきます。書籍の魅力を最大限引き出す表紙にしましょう。手に取ってもらえなければ読んでもらえないのですから。 +編集者が双方に書籍のイメージを伝えて構図を固めていきます。書籍の魅力を最大限引き出す表紙にしましょう。手に取ってもらってはじめて読まれるのですから。 -印刷所によってはAI形式でも大丈夫だったり、利用できるソフトウェアのバージョン指定があったりします。表紙のフォーマット（テンプレート）もかならず違うのでよく確認してからとりかかりましょう。 +印刷所によってはAdobe IllustratorのAIファイル形式でも大丈夫だったり、利用できるソフトウェアのバージョン指定があったりします。表紙のフォーマット（テンプレート）も違うのでよく確認してからとりかかりましょう。 -== 本文データの作成方法 +@{トンボ,断ち切り位置}までの紙面の余白、いわゆる@{塗り足し}は概ね3mmあれば十分です。機械で紙を切る際は微妙にずれるためギリギリ端っこに文字や大事なデザインを配置することは避けましょう。 +裁断位置が大きくずれることはめったにありませんが安全マージンを設計するのも制作者の努めです。1～3mm程度の余白は想定してください。 -本文データはPDF形式で入稿します。またAdobe Acrobat Proが必要@{adobe}です。 +== 本文データの作成方法（入稿用） -//footnote[adobe][表紙データの作成にもPhotoshopを使うので潔くCreative Cloudのコンプリート月々プランでの契約がオススメです] +本文データはPDFファイル形式で入稿します。万全を期すならAdobe Acrobat Proが必要@{adobe}です。 +ほとんどのケースでは、GitHubリポジトリでRe:VIEW-build-artifact-actionを使って生成したPDFファイルが使えます。 +最近はGitHub Actionsで作ったPDFファイルをそのまま印刷所に渡して入稿完了というお手軽な事例も沢山出ているので、本文の制作難易度は下がってきています。 -ページ数は基本的に４の倍数になるように揃えて入稿します。ならない場合は無理やり白いページを挟むこともあります。 -またページごとにノンブル（ページの通し番号）が必要です。たとえ白であっても、番号をいれます。 -同人誌以外では見ない制約ですが、乱丁を防ぐためにつけています。レイアウトは指がかかるのと本のノド（綴じている側の余白）があるので余裕を持った設定をしています。 -読みやすさに直結するので注意して設定してください。最初のうちは@{本書リポジトリのレイアウト設定}での利用を推奨します。 - -ここでも印刷所によっては、PDF形式での入稿が行えない（画像として出力する必要がある）、トンボが必要である、隠しノンブルに対応できる、など条件が異なります。 +//footnote[adobe][表紙データの作成にもAdobe Photoshopを使うので潔くCreative Cloudのコンプリート月々プランでの契約が覚悟の決め方です] TechBoosterが日光企画さんに入稿する事例では次のように進めています。 - -次のコマンドでPDFを出力します（B5 JISサイズを指定しています）。 +ローカルPC上にRe:VIEWの実行環境がある場合は次のコマンドで入稿用のPDFを出力できます。PDFファイルの出力にRe:VIEW-build-artifact-actionを使っている場合は、push時にPDFを自動生成するため、コマンドは読み飛ばして構いません。 //cmd{ review-pdfmaker config.yml //} -しかし、これだけでは入稿に使えません。 -フォントの埋め込みとPDFのフォーマットをPDF/Xに変換、原稿のモノクロ化をしてはじめて印刷所で扱うことができます。 +テンプレートリポジトリのデフォルト設定ではB5 JISサイズ、トンボありで出力します。 +基本的にページ数が４の倍数になるように揃えて入稿します。ならない場合は無理やり白いページを挟むこともあります。 -=== フォントの確認 -MacTexを利用している場合、現在のフォントを次のコマンドで調べることができます。 +またページごとにノンブル（ページの通し番号）は、たとえ白いページであっても必ず番号をいれます。同人誌以外では見ない制約ですし、印刷所によっても異なります。 +乱丁を防ぐ意図もありますがページ数がわかると純粋に参照しやすいのも事実です。 +ノンブル不要な印刷所であっても念のため入れておくのもよいでしょう。なおノンブルのレイアウトは紙面の下側が一般的です。 -//cmd{ -$ kanji-config-updmap status +#@# TODO 作図する -CURRENT family for ja: ipaex -Standby family : ipa -//} +本の紙面は綴じている側（本の中心）の余白をノドと呼び、左右の端側の余白を小口と呼びます。本を読むとき、小口と地に指がかかりやすいため、わたしたちの提供するレイアウトでは見やすいよう余裕を持った設定をしています。 -MacTex 2017ではデフォルトでIPAフォントを利用しています。埋め込まれていない場合は@{noEmbed}と表示しているはずです。 -後述の手法をつかうとヒラギノフォントなどデフォルト以外に変更できます。 +本を作るには凝ったものを作りたいという気持ちも否定しません。しかし最初のうちはぐっと我慢してデフォルトレイアウトの利用を推奨します。 +ノンブルに限らず、レイアウトのカスタマイズには多くの落とし穴があります。 +印刷所によっては、PDF形式での入稿が行えない（画像として出力する必要がある）、トンボが必要である（なくても受け付けてくれるケースも）、隠しノンブルに対応できるなど条件が異なります。 -=== フォントの埋め込み +== 本文データの作成方法（電子書籍用） -フォントの埋め込みをおこない、フォントがない環境で文字化けが起きないようにします。 -埋め込み方は「Tex Wiki」サイト@{mactex-font}が参考になります。次のコマンドはサイトからの引用です。 +入稿用の本文データにはトンボが含まれており、読者に提供するには不適切です。ここではPC等での閲覧を目的とした電子書籍用のPDFファイルも作りましょう。 -//cmd{ -cd /usr/local/texlive/2017/texmf-dist/scripts/cjk-gs-integrate -sudo perl cjk-gs-integrate.pl --link-texmf --force -sudo mktexlsr -//} + 1. @{config.yml}を変更し、保存する + 2. GitHub Actionsや@{review-pdfmaker}でPDFファイルを出力する -//cmd{ -sudo kanji-config-updmap-sys hiragino-elcapitan -//} - -//footnote[mactex-font][@{https://texwiki.texjp.org/?TeX%20Live%2FMac#elcapitan}] +はじめに@{articles/config.yml}を紙面レイアウトから電子書籍向けレイアウトに変更します（@{config_ebook}）。 -このコマンドを実行したあとに@{review-pdfmaker}コマンドでPDFを作成するとフォントが埋め込まれています。文書のプロパティで埋め込みフォントと表示があれば成功です（@{font}）。 +//list[config_ebook][articles/config.yml - 電子書籍用レイアウトに変更する]{ -//image[font][埋め込みフォント][scale=0.75]{ +# B5の設定(10pt 40文字×35行) - 紙版 +# 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"] +# B5の設定(10pt 40文字×35行) - 電子版 +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"] //} -=== PDFフォーマットをPDF/Xに変換 - -PDFと一口にいっても単純じゃありません。そこは長い歴史をもつPDFさんのことです。 -多数のバージョンが存在しています。TeXに続く深淵です。 - -しかし、印刷所への入稿を考えるとPDF/Xフォーマットがもっともポピュラーです。残念ながらLaTeX単体では対応できないため、ここから先はAcrobat Pro DCでの操作です。 - -ツールから印刷工程を選ぶと次のサイドメニューが表示されます（@{pdfx}）。 +@{config.yml}ファイル内の設定項目@{texdocumentclass}を紙版から電子版の設定へ変更します。サンプルでは@{#}を行頭に追加して紙版をコメントアウトし、次行の電子版を有効化しています。 +ポイントは@{media=print}と@{media=ebook}の違いです。ここでトンボを出し分けています。 -//image[pdfx][PDF/Xとして保存する（画面右サイドメニュー中）]{ -//} - -メニューの中のPDF/Xとして保存するを選んで、別名で保存してください。このとき目次のハイパーリンクなど付加情報は保存されませんが、これは仕様@{engineer}です。 - -//footnote[engineer][エンジニアは仕様といわれると弱い] - -=== 原稿のモノクロ化 - -入稿の最終段階です。作成したPDFデータをモノクロ化します。モノクロ化にあたってはPDF/Xフォーマットであることが前提ですので、前述のフォーマット変換作業を忘れずにおこなってください。 - -ツールから印刷工程を選ぶと色を置換というサイドメニューが表示されています（前述の@{pdfx}のPDF/Xとしての保存の２つ上です）。 - -ここではオブジェクトのうち、DeviceCMYKカラータイプのプロファイルを変換します（@{replace-color}、@{replace-color-dot-gain}）。 - -//image[replace-color][色を置換では、DeviceCMYKを選択する]{ -//} - -//image[replace-color-dot-gain][カラーを出力インテントに変換をチェック]{ +ローカルPC上にRe:VIEWの実行環境がある場合は次のコマンドで入稿用のPDFを出力できます。 +//cmd{ +review-pdfmaker config-ebook.yml //} -@{カラーを出力インテントに変換}にチェックをいれて、@{Dot Gain 15%}を選択します。 -また変換のオプションで@{黒を維持}もチェックします。 +電子書籍用のPDFファイルでは、トンボの有無だけではなくメタデータを追加しており、たとえばPDFのしおり機能で目次から本文へジャンプできるなど利便性に優れます。 -この設定で色を置換すると無事、モノクロ化できます。ここまでで本文の入稿データ作成は完了です。 +== 本文データの作成方法（電子書籍への最適化） -== 電子書籍（PDF）を発行する - -紙版と電子書籍、おなじPDFなのに何が違うんだと感じるでしょう。指摘はもっともです。論より証拠、比較画像を用意しました（@{ebook}）。 +紙版と電子書籍どちらも同じPDFファイルなのに何が違うんだと感じるでしょう。指摘はもっともです。論より証拠、比較画像を用意しました（@{ebook}）。 //image[ebook][紙面レイアウト（左）と電子書籍用レイアウト（右）]{ //} 大きな違いはフォントと余白です。紙面ではのりで本を綴じるため、手で持って読むために余白を広く取ってあります。 -一方の電子書籍用フォーマットでは余白は最小限に、PCやスマートフォンで読みやすいようにフォントも変えています。 +一方の電子書籍用に最適化したレイアウトでは余白を最小限に、PCやスマートフォンで読みやすいようにフォントも変えています。 小さな違いにみえるかもしれませんが、快適に読むための工夫がたっぷり含まれています。 -カラーで読める点、URLがリンクになる点なども電子書籍のメリットです。 +カラーで読める点、URLがリンクになる点などは電子書籍のメリットですね。 -電子書籍用レイアウトの適用は少々手がかかります。手順を追って説明しましょう。 +電子書籍への最適化手順は次のとおりです。 - 1. @{config.yml}の変更 - 2. レイアウトファイルの差し替え - 3. @{review-pdfmaker}でPDF出力する + 1. @{config.yml}を変更し、保存する + 2. GitHub Actionsや@{review-pdfmaker}でPDFファイルを出力する -まず@{config.yml}を紙面レイアウトから電子書籍向けレイアウトに変更します（@{config_ebook}）。 +@{articles/config.yml}を電子書籍に最適化したレイアウトに変更します（@{config_viewer}）。 -//list[config_ebook][電子書籍用レイアウトに変更する]{ -# 表紙に配置し、書籍の影絵にも利用する画像ファイル。 -coverimage: cover.jpg +//list[config_viewer][電子書籍用レイアウトに変更する]{ # LaTeX用のスタイルファイル(styディレクトリ以下に置くこと) -# texstyle: reviewmacro -# tatsumacroは、電子書籍版の制作に利用する -texstyle: tatsumacro -# texstyle: techbooster-doujin - -# LaTeX用のdocumentclassを指定する -# tatsumacro利用の場合はこちら -texdocumentclass: ["jsbook", "oneside,14pt,uplatex"] -# TechBoosterの指定は次の通り -# texdocumentclass: ["jsbook", "b5j,twoside,openany,uplatex"] -//} +# texstyle: ["reviewmacro"] +texstyle: ["viewermacro"] -@{texstyle}および@{texdocumentclass}をサンプルのとおり変更します。 -表紙がある場合は@{coverimage}に設定します。 +# A4の設定(14pt 42文字×32行) - 電子版 +texdocumentclass: ["review-jsbook", "media=ebook,paper=a4,serial_pagination=false, + oneside,fontsize=14pt,line_length=42zw,number_of_lines=32,head_space=22mm"] +//} -次にレイアウトファイルの差し替えです。 -TechBoosterのテンプレートは、Re:VIEW標準のレイアウトを拡張しています。 -手際がよいとはいえませんが電子書籍用レイアウトでビルドするときは一時的に退避しておきます。 +@{texstyle}および@{texdocumentclass}を変更しています。 +もし表紙があるなら@{coverimage}も設定しておきましょう。 -//cmd{ -mv layouts/layout.tex.erb layouts/layout.tex.erb.bak -//} +@{viewermacro}は専用のレイアウトファイルです。TechBoosterではRe:VIEW標準のレイアウトを拡張しています。 +TeXの知識が求められるので大変ですが、読みやすいので頑張ってメンテナンスを続けている秘伝のタレです。 -最後に@{review-pdfmaker}でビルドします。 +ローカルPC上にRe:VIEWの実行環境がある場合は@{review-pdfmaker}コマンドでビルドします。 //cmd{ review-pdfmaker config.yml //} 成功したら@{bookname.pdf}ファイルが得られます。念のため、フォントが埋め込まれているか確認しておいてください。 -フォントが埋め込まれていない場合は、表示時に代替フォントが利用されます。読む端末に依存するため文字化けのリスクが格段に高くなります。 +フォントが埋め込まれていない場合は、表示時に代替フォントが利用されます。読む端末に依存するため文字化けのリスクが格段に高くなります。特にモバイル端末では崩れやすいです。 なおTechBoosterでは電子書籍用レイアウトと紙面レイアウトが同じ横幅（つまり1行の文字数が一緒）になるように調整しています。 電子書籍用レイアウトのPDFを作ってもソースコードの折り返しを気にしなくていいので評判@{good}です。 -すべてメンテナンスフリーであればいいのですが、表や本文中のURLなどで折り返しが上手くいかないケースもよく遭遇します。品位を上げるためにはPDFを確認しながらの微調整が必要です。 +@{config.yml}以外の本文（@{.re}ファイル）もメンテナンスフリーであればいいのですが、表や本文中のURLなどで折り返しが上手くいかないケースにも遭遇します。次に示すのはレイアウトを変えた場合に遭遇する主な事象です。 //footnote[good][著者＝発行者なので自画自賛していることになるが気にしない] + * 本文やURLのはみ出しがある（特に図表、リスト、脚注で顕著） + * リンクが想定どおりの挙動をしない + * 画像サイズが意図と異なり、想定した見栄えにならない（画像の微調整が必要） + * ページ送りの場所などレイアウトが異なる + +最適化した場合にはトンボといった印刷に関わる設定以外も大きく変わっています。そのため改行位置やページ数など本文に関わる見栄えが大きく変わります。 +出力できたからといってチェックしないのはよくありません。品位を上げるためにはPDFファイルを確認しながらの微調整が必要です。 +近年はタブレットだけでなくスマートフォンで閲覧する読者も増えており、画像サイズや図表は細かく調整することを推奨します。 + == EPUB（リフロー）を発行する EPUBは電子書籍ファイルフォーマット規格のひとつです。多くのEPUBリーダーが普及しています（@{epub_reader}）。 -//image[epub_reader][EPUBリーダーのiBooks][scale=0.75]{ +//image[epub_reader][EPUBリーダーのApple Books][scale=0.75]{ //} @@ -263,18 +239,22 @@ Re:VIEWはEPUB3フォーマットで出力可能です。 技術書の内容でEPUBが向くものと向かないものはっきりと別れる傾向があります。 -EPUBでも表紙をつけることができます。@{config.yml}の設定を抜粋します（@{epub_config}）。 +EPUBとPDFはフォーマットの違いから設定できる項目にも違いがあります。@{config.yml}の設定を抜粋します（@{epub_config}）。 //list[epub_config][config.yml - EPUBの設定（抜粋）]{ - epubmaker: - # HTMLファイルの拡張子 - htmlext: xhtml - # 表紙に配置し、書籍の影絵にも利用する画像ファイル。 - coverimage: cover.jpg +epubmaker: + # HTMLファイルの拡張子 + htmlext: xhtml + stylesheet: ["style.css", "epub_style.css"] //} -@{cover.jpg}は@{config.yml}の位置をルートに@{image/cover.jpg}へ配置してください。 -カバー画像がない場合は署名が表示されます。 +@{epubmaker}に続く設定はEPUBフォーマット専用の項目です。PDF等と共用できるものは引き継いでいるので安心してください。 +ただEPUBの設定項目は専門的な知識が求められるので、変更する場合は表紙を最初のページとして表示するか決める@{cover_linear}ぐらいに留めておいてください。 +フォーマットごとに出力し、複数の成果物を管理するのは想像異常に大変です。慣れてきたり、必要に迫られたら考えましょう。 + + +Re:VIEW-build-artifact-actionは現時点でEPUB出力に対応していません。 +ローカルPC上にRe:VIEWの実行環境を用意して@{review-epubmaker}コマンドでビルドしてください。 ビルドするためのコマンドは次のとおりです。 @@ -282,13 +262,91 @@ EPUBでも表紙をつけることができます。@{config.yml}の設定 review-epubmaker config.yml //} -成功したら@{bookname.epub}ファイルを出力します。早速、出力されたEPUBをiBooksで表示してみましょう（@{epub}）。 +成功したら@{bookname.epub}ファイルを出力します。EPUBファイルはApple Books等で表示してみましょう（@{epub}）。 //image[epub][iBooksでの表示例]{ //} EPUBリーダーで柔軟にレイアウトし、読者の環境に合わせて読める特徴は他のフォーマットにない利点です。 +世の中にはApple Books以外のEPUBリーダーも存在しています。それぞれのリーダーごとに表示が異なるため、可能な限り多くの電子ブックアプリで動作確認してください。 +これはPDFとEPUBのフォーマットの違いをよく表しています。EPUBはレイアウトやフォントサイズなどの表示品質はリーダーに委ねているのです（委ねたほうがデバイスや読者の要望ごとに最適な読書環境が提供できるとの考えから）。 + +== 配布にあたっての注意点 + +本文データの詳細 +=== フォントの確認 +MacTexを利用している場合、現在のフォントを次のコマンドで調べることができます。 + +//cmd{ +$ kanji-config-updmap status + +CURRENT family for ja: ipaex +Standby family : ipa +//} + +MacTex 2017ではデフォルトでIPAフォントを利用しています。埋め込まれていない場合は@{noEmbed}と表示しているはずです。 +後述の手法をつかうとヒラギノフォントなどデフォルト以外に変更できます。 + +=== フォントの埋め込み + +フォントの埋め込みをおこない、フォントがない環境で文字化けが起きないようにします。 +埋め込み方は「Tex Wiki」サイト@{mactex-font}が参考になります。次のコマンドはサイトからの引用です。 + +//cmd{ +cd /usr/local/texlive/2017/texmf-dist/scripts/cjk-gs-integrate +sudo perl cjk-gs-integrate.pl --link-texmf --force +sudo mktexlsr +//} + +//cmd{ +sudo kanji-config-updmap-sys hiragino-elcapitan +//} + +//footnote[mactex-font][@{https://texwiki.texjp.org/?TeX%20Live%2FMac#elcapitan}] + +このコマンドを実行したあとに@{review-pdfmaker}コマンドでPDFを作成するとフォントが埋め込まれています。文書のプロパティで埋め込みフォントと表示があれば成功です（@{font}）。 + +//image[font][埋め込みフォント][scale=0.75]{ +//} + +=== PDFフォーマットをPDF/Xに変換 + +PDFと一口にいっても単純じゃありません。そこは長い歴史をもつPDFさんのことです。 +多数のバージョンが存在しています。TeXに続く深淵です。 + +しかし、印刷所への入稿を考えるとPDF/Xフォーマットがもっともポピュラーです。残念ながらLaTeX単体では対応できないため、ここから先はAcrobat Pro DCでの操作です。 + +ツールから印刷工程を選ぶと次のサイドメニューが表示されます（@{pdfx}）。 + +//image[pdfx][PDF/Xとして保存する（画面右サイドメニュー中）]{ +//} + +メニューの中のPDF/Xとして保存するを選んで、別名で保存してください。このとき目次のハイパーリンクなど付加情報は保存されませんが、これは仕様@{engineer}です。 + +//footnote[engineer][エンジニアは仕様といわれると弱い] + +=== 原稿のモノクロ化 + +入稿の最終段階です。作成したPDFデータをモノクロ化します。モノクロ化にあたってはPDF/Xフォーマットであることが前提ですので、前述のフォーマット変換作業を忘れずにおこなってください。 + +ツールから印刷工程を選ぶと色を置換というサイドメニューが表示されています（前述の@{pdfx}のPDF/Xとしての保存の２つ上です）。 + +ここではオブジェクトのうち、DeviceCMYKカラータイプのプロファイルを変換します（@{replace-color}、@{replace-color-dot-gain}）。 + +//image[replace-color][色を置換では、DeviceCMYKを選択する]{ +//} + +//image[replace-color-dot-gain][カラーを出力インテントに変換をチェック]{ +//} + +@{カラーを出力インテントに変換}にチェックをいれて、@{Dot Gain 15%}を選択します。 +また変換のオプションで@{黒を維持}もチェックします。 + +この設定で色を置換すると無事、モノクロ化できます。ここまでで本文の入稿データ作成は完了です。 + +@{cover.jpg}は@{config.yml}の位置をルートに@{image/cover.jpg}へ配置してください。 +カバー画像がない場合は署名が表示されます。 #@# TODO mhidaka diff --git a/articles/review-introduction.re b/articles/review-introduction.re index 090a0ce..2871ee3 100644 --- a/articles/review-introduction.re +++ b/articles/review-introduction.re @@ -4,10 +4,11 @@ 執筆にあたって適切なマークアップを選択できるよう、利用頻度の高いRe:VIEW記法について扱います。 Re:VIEW記法は、文章を書き、見出しやコードなどをマークアップするための記法です。 -たとえば技術書では、文章や単語を強調したいときに@{太字}にしたり、クラスやメソッドの名前を記述する場合、@{等幅フォント}にしたりと、 +たとえば技術書では、文章や単語を強調したいときに@{太字}にしたり、クラスやメソッドの名前を記述する場合、@{等幅フォント}にしたりと、 視覚的な差別化が行われています。 #@# REVIEW vvakame i とか tt は見た目の情報なので code とかを使ったほうがいいような…。 #@# mhidaka @{}はいまのところファイル名、Pathのマークアップにのみ利用している。@は@と@が類似に存在してるんだけどweightの使い分けがどうしようかな +#@# @はフォント指定のbold、著者が強調したいときは現時点では@で統一しています。 #@# prh:disable Re:VIEW記法でマークアップすることで文章の構造や見た目を記述できます。 @@ -157,29 +158,35 @@ Re:VIEWは、「番号なし箇条書き」と「番号つき箇条書き」に プログラムコードなど、本文とは分けて掲載する内容を「リスト」と言います。 リストの中の改行やスペースはそのまま出力されます。 -文章中でコード例や図版を挿入したとき、文中からそれらを参照するために「リスト 2.1」などと番号を振る必要がありますが、 -Re:VIEWにはリストや図版の採番を自動的にするための仕組みがあります（@{list_sample}）。 -#@# REVIEW vvakame このあたりの解説、もうちょっと後ろに送ったほうがいいと思う… - //list[list_sample][通し番号の割り当て＋キャプションを表示]{ また、画像やプログラムリストを掲載する場合、視覚的に区別しやすくし、本文に対し適切な余白をとり、適切な場所に配置することも大切です。 //} -Re:VIEWのリストには、連番付きと連番無しの２種類、行番号の有無を含めると計４種類があります。 +Re:VIEWのリストには、連番つきと連番なしの２種類、行番号の有無を含めると計４種類があります。 //table[list_table][リストの区分]{ . 行番号なし 行番号あり ------------------------- -連番付き list listnum +連番つき list listnum 連番なし emlist emlistnum //} +=== リストの参照 + +文章中でコード例や図版を挿入したとき、文中からそれらを参照するために「リスト 2.1」などと番号を振る必要がありますが、 +Re:VIEWにはリストや図版の採番を自動的にするための仕組みがあります（@{list_refs}）。 + +//list[list_refs][連番つきリストは通し番号で参照可能]{ +このリストは参照されています。 +//} + 連番つきリストにするとRe:VIEWは、リストごとに一意な番号を割り振ります。 一方、連番なしリストは、リストに番号を割り当てず、本文からは参照できません。 一般的にソースコードリストのように本文から参照する場合には、連番付きリスト（@{list}）を推奨します。 参照関係が明らかな場合のみ、連番なしリスト（@{emlist}）を利用するといいでしょう。 + === 連番つきリスト 連番つきのリストです。 @@ -281,7 +288,7 @@ Re:VIEWのリストには、連番付きと連番無しの２種類、行番号 コマンドラインの入出力などを示す構文です。本書を含め多くの書籍では黒っぽい背景色が採用されており、 わかりやすい出力が使われます。 -//list[cmd_sample][引用]{ +//list[cmd_sample][コマンドラインの例]{ //cmd{ $ git add .gitignore $ git commit -m "first commit" @@ -501,24 +508,24 @@ Re:VIEWでは、行は改行、セルとセルの間にはタブで区切りま //list[sammple_lead][リード文]{ //lead{ - 本章ではRe:VIEWで執筆をする上でもっとも重要となるRe:VIEW記法について解説します。 + 本章ではRe:VIEWで執筆をする上で最初に覚えるRe:VIEW記法について解説します。 //} //} @{sammple_lead}のマークアップは、次のように出力されます。 //lead{ -本章ではRe:VIEWで執筆をする上でもっとも重要となるRe:VIEW記法について解説します。 +本章ではRe:VIEWで執筆をする上で最初に覚えるRe:VIEW記法について解説します。 //} このように、リード文としてマークアップした内容は、本文に比べて左側の余白が大きくなります。 -Re:VIEWでは、リード文のマークアップは文章のどこにでも置くことができます。 -しかし、基本的には見出し、特に章見出しの直下に置くことを想定しています。 +Re:VIEWでは、リード文のマークアップは文章のどこにでも置けます。 +しかし、基本的には見出し、特に章見出しのすぐあとに置くことを想定しています。 == 文字の装飾 -Re:VIEW記法では文字を装飾することができます。 +Re:VIEW記法では文字を装飾できます。 文字の装飾は適用したい範囲を@{＠<修飾子>{...}}で指定するだけです。 @@ -540,7 +547,7 @@ Re:VIEW記法では文字を装飾することができます。 ＠{文字列} コードに利用 @{abcdefg} //} -＠は初出の単語で利用するとよいでしょう。またコードは＠を使っても同じ装飾表現を得られますが +＠は初出の単語で利用するとよいでしょう。またソースコード上の関数や変数名といった表記は＠を使っても同じ装飾表現を得られますが ＠を利用してください。変換前の文章では＠のほうが圧倒的に著者の意図をくみとりやすく、校正や編集で装飾のゆらぎを検出しやすくなります。 == 参照 @@ -612,20 +619,11 @@ Re:VIEWでは、見出しキャプションとは別に、参照用のラベル 通常の節の参照同様、違う章の節を参照できる優れものです。 -==[column] インライン命令とブロック命令 +==[column] ブロック命令とインライン命令 -Re:VIEW記法は、「インライン命令」と「ブロック命令」の２つに分類できます。 +Re:VIEW記法は「ブロック命令」と「インライン命令」の２つに分類できます。 #@# REVIEW vvakame インライン記法とブロック記法のほうが好きだな… どこからの表現だろう -==== インライン命令 - -インライン命令は@{＠<命令>{...}}のように、@{＠,アットマーク}に続けて括弧<>内に命令名を指定します。 -続く括弧{}の中が、インライン命令の効果が及ぶ範囲になります。 -#@# REVIEW vvakame tt より code が好きだなー - -インライン命令は、文章の装飾やリストや図の参照など表示や内容に影響します。 -文中に直接記入することができますが、改行をまたぐことはできません。 - ==== ブロック命令 #@# REVIEW vvakame ブロック記法についてはインライン記法より先に書くべきだと思う。インライン記法がなくてもemlistなどで技術書は書けるが、逆は真ではないからだ。 @@ -655,4 +653,12 @@ Re:VIEW記法は、「インライン命令」と「ブロック命令」の２ ブロック命令を文の途中から開始することはできません。ブロック命令の開始と終了は、必ず行頭に記述します。 行頭に半角スペースなどが入った場合、Re:VIEWは、その行をブロック命令として扱いません。 +==== インライン命令 + +インライン命令は@{＠<命令>{...}}のように、@{＠,アットマーク}に続けて括弧<>内に命令名を指定します。 +続く括弧{}の中が、インライン命令の効果が及ぶ範囲になります。 + +インライン命令は、文章の装飾やリストや図の参照など表示や内容に影響します。 +文中に直接記入することができますが、改行をまたぐことやインライン命令のネストはできません。 + ==[/column] diff --git a/articles/textlint.re b/articles/textlint.re new file mode 100644 index 0000000..8957d37 --- /dev/null +++ b/articles/textlint.re @@ -0,0 +1,135 @@ +={textlint} 文章をよくする改善ポイント + +本を作るうえで苦労することのひとつに統一感があります。文章が途中で変わっていないか、主張が変わっていないか、 +タイトルと内容が変わったり本の最後のほうで文体が変わったりするとやはりもったいないなぁという風になりますよね。 + +せっかく書いたのだし細部に注意して読みやすい本にしたいという方にむけて文章が断然よくなる改善ポイントをお伝えします。すべての文章がかくあるべきという意味ではありませんが、技術書に顕著な評価軸として文章のわかりやすさがあります。これは仕事でのドキュメンテーションなどにも活きる知識ですので、ここぞとばかりに覚えておいて損はありません。 + +細かい内容に関してはわたしたち本書の筆者であるmhidakaとvvakameが書いた技術的な文章を書くための手引も役に立つかでしょう。 + + : 技術的な文章を書くための第0歩 ～読者に伝わる書き方～ + @{http://qiita.com/mhidaka/items/c5fe729716c640b50ff7} + : 技術的な文章を書くための1歩、2歩、3歩 + @{http://qiita.com/vvakame/items/d657baf26cf83ac98bd0} + +次では技術書として注意したらよいポイントをいくつか列挙します。指摘内容の大小といった粒度に差はありますが、重要だと思う項目からの紹介です。 + +== 主張の統一 +ひとつの文章にたくさんの主張を入れると読む人は混乱してしまいます。 +読みやすさを考えてシンプルな構成を選びましょう。 + + * 特定のコンテキストでは、ひとつの主張のみ扱う（章、節、項で主張の大小はある） + * 初出の単語、概念は登場時点で説明する + +たとえば章のはじめには導入（リード文）を用意してまとめを説明して読者と記事のマッチングをはかります。 +書いているうちに節のタイトルが本文と異なる場合もありますので主張を意識して読みなおすことが大切です。 +執筆中は初出の単語、概念など気づかない場合があります。読みなおすことで初出の単語の発見や、 +前後の文章を入れ替えて主張を理解しやすくするなど、本の構成をよりよく変えられます。 + +== 文中の文言と装飾を書籍にあわせる + +#@# prh:disable +文章を書いていると上下を意識して「以上が」「以下のとおりです」など書きたくなりますが +組版の都合で上下が明らかでない場合があります。次のページにいってしまったりするわけですね。 +それぞれ「前述のとおり」「次のとおりです」で置き換えるとよいでしょう@{lint}。 +これらのために、@{review-introduction}で解説するリストや図があるわけです。 + +//footnote[lint][後述のprhで技術書向きの校正を行えます。自分好みにカスタマイズするとよいでしょう] + +また図、表、リストについては次のことを念頭に構成してください。 + + * 図、表、リストの登場前に本文中から参照する（＠、＠など） + * 登場前に内容を簡単に説明する一文を書く + * 登場後に詳しい解説を書く + +これらを守ることで何について述べているのかわかりやすくなり、読者が読んだときの唐突感や投げっぱなし感がなくなります。 + +装飾には、いわゆる太字、斜体などフォントの見た目を変えて読みやすくする意図があります。 +しかし利用基準を定めて守るほうが難しく、一貫性を保つのが作業量的にしんどい側面もあります。 +大事な内容であれば、装飾を多用せず文章中で注意喚起したほうがよっぽどよいでしょう。 +装飾が必要なときは編集担当者がチェックできる基準でのみ実施すべきです。 +#@# REVIEW vvakame review-introduction.reで結構文字装飾使ってる… +#@# 改訂にあわせて減らしておいたよ。強調はstrongを一部だけで、ファイル名はttで装飾に統一している。 + +たとえばリスト中の変数名ではコードとして装飾するなど明確な基準がある装飾であれば統一感がありますね。 + +== 文体の統一 +文体は著者の味となるため過剰な編集は好みませんが、それでも次のような表現は +編集段階で変更しています。 + + * ネガティブな表現を利用しない + * 体言止め、話し言葉は利用しない + * ですます調と、である調を混在しない + * 思いますなど感想にならないようにする + * 文章中の記号は全角が基本（特にカッコ） + * 文章中の英単語は前後にスペースを入れないで空きを詰める + +ネガティブな表現は読者の心証を悪くします。期待して本を読んでいる読者に、 +デメリットだけでなくメリットも感じてもらえるように表現をポジティブに改めます。 +また技術書であれば平易な表現を心がけて読者の理解に努める方針のもと、 +著者の文体を壊さない程度に調整します。 +「～だと思います」という文章であれば「です」と編集したり、 +「～することができます」という表現であれば簡潔に「～できます」と縮めています。 + +編集時には想定読者になりきって読みやすい文章を追及しましょう。 + +見た目に影響する話では、半角記号は基本的に英字に合わせてフォントが作られています。 +文章中で表現として使う場合、記号は全角を利用してください。 +メソッド名、プログラムのソースコードからの引用はその限りではありません。 + +とくに半角カッコはフォントの高さが全角文字と異なるため、沈んだ印象を受けます。 +全角カッコを利用するようにしてください。 + +== 長い文章は分割する + +著者にとって技術書に登場する文章は、なんども咀嚼して推敲を重ねた馴染み深い存在です。しかし本が読者に渡ったあとには、その文章が突如として初めて読む存在に変貌します。 + +書籍のなかに、おおむね3行を超える文章があったら2つ以上の文章に分割してください。おすすめは主語と述語（動詞）の距離を短く保つことです。 + +英語を勉強したときを思い出してみてください。ごく簡単な例文から学びはじめませんでしたか？This is a pen.というテキストを学んだあとにアリス・イン・ワンダーランドといった英語の古典的表現に踏み込んでいるはずです。技術書の文章も同様に、あまりに長いと読者が情報を取りこぼしやすくなります。読者は著者と同じバックグラウンドを備えているわけではありません。前提とする知識量の違いから、どの部分がわかりにくいかといった判断が難しいシーンもしばしばです。 + +複数の文章に分割するコツは、正確性をコントロールすることです。「AはBである。ただしCの条件を満たすときAはDとなる」この文章は最初の1文で原則を示し、続いての文で例外を伝えています。この構造であれば誤読の要素もなく混乱しにくいですよね。伝えたい内容の重要性を加味し、順序を操ってください。 + +おおむね3行を超える文章とは具体的には100文字を超える程度だと考えるといいでしょう。同様に@{段落,パタグラフ}の長さも短いほうがよいと考えるかもしれませんが、こちらはトレンドがあり、近年は5~10行程度で1段落とする程度の短さが増えています。ただし文章そのものが短ければ、段落が長くても読みやすさは維持できます。前述した主張の統一とも関連するのでテクニックも必要です。そのため本章で挙げたポイントを差し置いて気にするほどではありません。 + +== 校正支援ツールprhを導入する + +校正支援用ツールとしてprh@{prh}があります。 +prhはproofread helperの略です。 +proofreadで1単語だから略したらphだろ！とか言ってはいけません。 + +#@# prh:disable +prhは単純にルールに従い、文字列を置き換えるだけのものです。 +たとえば「例えば」と書いたときに「たとえば」に置き換えるよう促してくれます。 +これを漢字をひらがなに「開く」操作といいます。 + +一般的な表現を用いることで文章を読みやすくする効果があります。 +文章の質を高めるためにはこのような書き換え処理をたくさんこなす必要があるわけです。 + +TechBoosterでは原稿をみんなが書き終えた後、ひつじ（@mhidaka、サークル主催）くんが全員の原稿に手を加え、開く処理をいれるなどの作業を行っていました。 +そこでprhを作成し編集者の作業から著者個人の作業に変換した@{crazy-mhidaka}わけです。 +面白いもので、規則をルール化し記述できるようにしたことで著者の中での校正に対する関心も高まってきました。 + +肝心の使い方についてです。現状あまりコマンドラインツールとしての使い勝手はよくありません。 +Visual Studio Codeのようなエディタのプラグインlanguage-reviewにはprhが組み込まれているため、language-review経由で使うのが楽でしょう。 + +まずは、TechBoosterの設定ファイル@{prh_setting}をダウンロードして試してみるのがよいでしょう。 +ファイルを@{prh.yml}という名前で@{.re}ファイルと同じディレクトリに置くとlanguage-reviewが校正用ルールとして参照して、Lintを表示します（@{lint}）。 + +//image[lint][校正の指摘例]{ + +//} + +//footnote[prh][@{https://github.com/prh/prh}] +//footnote[crazy-mhidaka][「すごい！校正の労力が半分になったぞ！だから前回の2倍の冊数作った！」ってヤツは言いました。クレイジー] +//footnote[prh_setting][@{https://github.com/prh/rules/blob/a05c35d285d08dc7ba0a78dd791160116d39e9f4/media/techbooster.yml}] + +類似のツールにはRedPen@{redpen}やtextlint@{textlint}などがあります。 +さらなる文章の改善を目指すのであれば、これらのツールを利用してみるのもよいでしょう。 + +とはいえ、根本的に文章の目的と構造がしっかりしていないといくら枝葉末節を補ったところで意味はありません。 +本章で示した指標はあくまで補助線だと考えて自分が表現したい技術を書くことを追求してください。書き終わりさえすれば校正フェーズの時間は睡眠を削って絞り出したりできます。あと一歩で良いものができるぞと感じたら自然と効率が上がるものです。しかし書き終わらないと始まりません。編集のつらいところですね@{early}。 + +//footnote[redpen][@{http://redpen.cc/}] +//footnote[textlint][@{http://efcl.info/2015/09/10/introduce-textlint/}] +//footnote[early][早く終わらせるぞという意気込みで作業をすると、なぜかちょっとだけ遅延して終わります。時間はあるだけ使うんですよ] diff --git a/articles/workflow.re b/articles/workflow.re index dfcfb45..d459b57 100644 --- a/articles/workflow.re +++ b/articles/workflow.re @@ -1,12 +1,12 @@ ={workflow} 制作ワークフロー -この章では、実際に本を作るワークフローを紹介していきます。 -TechBoosterがC81から練り上げてきた本を作るよくできた方法を解説します。 +本章では、実際に本を作るときのワークフローを紹介していきます。 +TechBoosterがC81からC102まで10年以上をかけて練り上げてきた本を作るよくできた方法を解説します。 -必ずこうすべきだというものではなく、Re:VIEWを使った同人誌ってこうやってつくったんだよ、という体験記です。 +必ずこうすべきだというものではなくRe:VIEWを使った同人誌ってこうやってつくったんだよ、という体験記です。 同人誌というジャンルは広く、多様な表現が可能です。 技術誌としての企画、構成、編集、入稿まで制作フローに興味があるとより楽しめると思います。 -そしてこれを読んで作ってみたいな、と思った方はガイドラインとしてご活用ください。 +そしてこれを読んで作ってみたいなと思った方はガイドラインとしてご活用ください。 == よろしい、ならば同人誌だ @@ -20,12 +20,12 @@ TechBoosterがC81から練り上げてきた本を作るよくできた方法を 技術書を頒布する@{hanpu}のにもっとも適したイベントは技術書典@{me}です。 //footnote[hanpu][同人用語。有償、無償問わず、イベントで同人誌を提供すること] -//footnote[me][筆者かつ主宰者によるポジショントーク。コミックマーケットも盛況ですよ] +//footnote[me][筆者かつ主宰者によるポジショントーク。コミックマーケットも盛況ですよ。技術書典も長く愛されるようになっていると実感しています。率直に嬉しいです] 印刷にかかるお金は変動するのでページ数と部数は早めに想像しておきましょう。 この段階では、きっちり固まっている必要はありません@{eng}。 執筆を始める前に、ざっくりと頭の中に書く内容を固めておきましょう。 -具体的にはセクションのレベル2ぐらい、つまり章と節のタイトルとリード文があれば安心です。 +具体的にはドキュメントセクションのレベル2ぐらい、つまり章と節のタイトル、それぞれの内容を最大3行程度で表現したリード文があれば安心です。 //footnote[eng][もしあなたがエンジニアなら見積もりの困難さはご存知ですね] @@ -41,7 +41,7 @@ TechBoosterがどういう順番で執筆を行っているのか解説します そのためネタ出しから目次の作成、執筆、レビューと手直し、編集までGitHub上で行っています（@{workflow}）。 -//image[workflow][よく分かる図解][scale=0.40]{ +//image[workflow][よく分かる図解][scale=0.50]{ digraph G { planning [label="企画"]; meeting [label="ネタ出し会議"]; @@ -72,11 +72,11 @@ digraph G { 大まかな流れは次のとおりです。 - 1. 企画会議に先立って1つのIssueに知りたいネタを書き込む + 1. 企画会議に先立って1つのIssue/Slackに知りたいネタを書き込む 2. オフラインで集合し、ネタの分配や争奪戦を行う 3. 1冊＝1リポジトリでプライベートリポジトリを作成する - 4. 1ネタ=1Issue=1章という単位で目次案を書く - 5. ひたすら書く。masterに直pushでOK + 4. 1ネタ＝1Issue＝1章という単位で目次案を書く + 5. ひたすら書く。main branchに直pushでOK 6. レビューを受ける 7. レビュー指摘の修正作業を行う 8. 編集者が校正＆調整作業に入る（直pushの禁止。変更はpull requestを送る） @@ -84,13 +84,16 @@ digraph G { いくつか補足します。 -==== ひたすら書く。masterに直pushでOK +==== ひたすら書く。main branchに直pushでOK -これは同一の.reファイルを複数人で編集する機会が少ないからです。 -conflictが発生しないのであればpull requestにする必要性は薄いです。 +これは同一の@{.re}ファイルを複数人で編集する機会が少ないからです。 +Re:VIEWでは章単位のファイル構成となるため、章ごとに著者が異なっておりconflictが発生しないのであればpull requestにする必要性は薄いです。 -WIP@{wip}として、書き終わるまでmasterにmergeしない方法もあります。 -しかし、常にmasterで（もちろんビルドが通る状態であることは前提ですが）作業をすると、他の人の進捗もわかりやすく、本全体のページ数も掴みやすく、あまり執筆が進んでいない著者に圧力もかけやすくなります。 +WIP@{wip}として、書き終わるまでmain branchにmergeしない方法もあります。 +しかし、常にmain branchで（もちろんビルドが通る状態であることは前提ですが）作業をすると、他の人の進捗もわかりやすく、本全体のページ数も掴みやすく、あまり執筆が進んでいない著者に圧力もかけやすくなります。 +さらに著者がRe:VIEW記法そのものに不慣れであるケースも多いのですがmain branchにmergeするタイミングでエラーに悩まされることを防げます。締切直前で忙しいときは誰もが忙しいので余裕をうまく使ってください。 + +//footnote[wip][Work In Progress つまり書きかけ・作りかけの状態のこと] 執筆というのは著者同士による圧力鍋バトルなので頑張りましょう。 早く書いてアガリを迎え、まだできていない人に圧力をかけねば自分が圧力をかけられる側に堕ちる@{counterattack}のです。 @@ -101,178 +104,70 @@ WIP@{wip}として、書き終わるまでmasterにmergeしない方法も ==== レビューを受ける -レビューは執筆の進捗に応じて２回程度行っています。 +レビューは執筆の進捗に応じて２回程度行っています。プログラミングでのレビューと同じく複数の観点があります。 +慣れないうちは意識して使い分けることをおすすめします。 + + : 構造のレビュー + 章の目次や節の順序など執筆者の主張が適切な形で含まれているか、前提や節など構成の不足を確認します + : 文章のレビュー + センテンス単位のレビューです。主語が適切か用語が正確か、読みづらさを感じないように注意深くみていきます -まずは構造が適切か、という視点でのレビューです。目次案、またはごく簡単に構成したスケルトン状態のものに関して、対象読者、筆者の視点、説明したい内容を十分カバーしている章立てか、など確認します。 +まずは構造が適切かという視点でのレビューです。目次案、またはごく簡単に構成したスケルトン状態のものに対して、対象読者や筆者の視点、技術的に説明したい内容を十分カバーしている章立てかなど確認します。 この状態では主にIssueでのやり取りがメインです。 文章を書き上げた初校の段階で詳細なレビューを行います。 -@{writing-book}でも少し触れましたが初校レビューはインラインコメントとして.reファイル中に書くケースが大半です。 +@{writing-book}でも少し触れましたが初校レビューはインラインコメントとして@{.re}ファイル中に書くケースが大半です。 これは、レビュー内容を取り込むときにWebサイトと見比べながら行うのが面倒であること、レビュワー同士で他にどういうコメントがあるかが把握できたほうが学びが多く、指摘の重複も少ないからです。 #@# prh:disable -またコメントを書いた後、直接masterにpushしない理由は筆者の修正とconflictが発生しやすいためです。 -筆者は好きなときに好きなものを書き、気が向いたときにレビューの反映作業を行うのが精神衛生上良いでしょう。 +コメントを書いた後、直接main branchにpushしない理由は筆者の修正とconflictが発生しやすいためです。 +筆者は好きなときに好きなものを書き、気が向いたときにレビューの反映作業を行うのが精神衛生上よいでしょう。 -文章そのものへの指摘ではない、章の構造などより大きな視点で指摘する場合は、レビューのフェーズを問わずIssueのみを使って、やりとりを進めるケースもあります。 +文章そのものへの指摘ではない、章の構造などより大きな視点で指摘する場合は、レビューのフェーズを問わずIssueのみを使って、やりとりを進めるケースがあります。 -レビュー指摘をどう反映するかは著者の裁量に任せています。 +重要な点としてレビュー指摘をどう反映するかは著者の裁量に任せています。 もちろん、この後の行程では編集者が手を加えるのでヒエラルキーはレビュー＜執筆者＜編集者です。 -これは納得のいく指摘のみ取り込んで欲しいからです。レビューをすべて取り込むことがよいことではありません。わかりやすい文章がすべてをカバーしていることは稀で、何を書かないかの選択も重要です。 +これは執筆の段階では納得のいく指摘のみ取り込んで欲しいからです。レビューをすべて取り込むことがよいことではありません。とくに多くの観点をケアしようとするあまり冗長になるというのは、わたしたちが考える最も大きなデメリットです。 +わかりやすい文章がすべてをカバーしていることは稀で、何を書かないかの選択も重要です。 編集も著者の主張が適切に伝わるか、という観点で作業します。 ==== 編集者が校正＆調整作業に入る（直pushの禁止。変更はpull requestを送る） -凍結後にmasterを変更する権限をもつのは編集者（TechBoosterでは羊）だけです。 -執筆者がどうしても修正したい場合、pull requestを送りお伺いを立てます。 -これは印刷所への入稿に向け、ページ数の調整を行っている段階だからです。 -これを守らない場合、PDF化したときに改行の具合やら1行あたりの文字数やらの細かな調整がご破算になり編集者がぷっぷくぷー！になります。 -可哀想なのでやめてあげましょう。 +main branchの凍結後にmain branchを変更する権限をもつのは編集者（TechBoosterでは@{mhidaka,ひつじ}）だけです。 +執筆者がどうしても修正したい場合、pull requestを送り、お伺いを立てます。 -//footnote[wip][Work In Progress つまり書きかけ・作りかけの状態のこと] +これは編集や校正フェーズが印刷所への入稿に向け、ページ数の調整を行っている段階だからです。 +本ルールを守らない場合、PDF化したときに改行の具合やら1行あたりの文字数やらの細かな調整がご破算になり編集者がぷっぷくぷー！になります。本気で可哀想なのでやめてあげましょう。 + +== 執筆のための継続的インテグレーション - Docker & GitHub Actions + +エンジニアであればmain branchビルドが壊れることを極端に怖がると思います。正しい。 +そこでTechBoosterではCIのための仕組みを制作しました。平たくいうと常に最新のPDF出力が得られます。 +ここで重要なのは印刷を目的としたレイアウトで確認できるという点です。ソフトウェア開発でも成果物をビルドしてプロジェクトのデリバリを担保していますが、技術書の制作環境でも似ています。 -== 執筆のための継続的インテグレーション - Griflet +Re:VIEWはPDFだけでなくEPUBやHTMLなど各種フォーマットに対応しているので、執筆中の出力だってドラフトやHTML出力だけでいいんじゃない？と考えることもできますが、印刷が前提だと最終確認するだけで心許なく感じます。締切ギリギリにあがった原稿を編集者だけでチェックして印刷するなんて無茶は誰だってしたくありません。というわけで印刷用であったり最終レイアウトだったりのリリース向けの成果物を執筆中でも確認できるようにします。少なくとも著者がチェックできていないケースはなくなります。 -エンジニアであればmasterビルドが壊れることを極端に怖がると思います。正しい。 -そこでTechBoosterではCIサーバGriflet@{Griflet}を用意して常に最新のPDF出力が得られるような運用をしています。 -これには多くのメリットがありますが中でも次のような点で執筆に貢献しています。 + : Re:VIEW image for Docker + @{https://hub.docker.com/r/vvakame/review/} + : Re:VIEW-build-artifact-action + @{@{https://github.com/marketplace/actions/review-build-artifact-action}} -//footnote[Griflet][Griflet（グリフレット）はグリフ＋リーフレットの造語です。本に由来して名前を考えています。かっこいいとおもいませんか？僕は思います] +TechBoosterではDocker上でRe:VIEWを動かすツールおよびGitHub Actionsとして実行するラッパーツールを用意して常に最新のPDF出力が得られるような運用をしています。これには多くのメリットがありますが中でも次のような点で執筆に貢献しています。 * ビルド環境の準備が不要になる * Re:VIEWの文法エラーにすぐ気づける * レビュー対象物を特定できる -TechBoosterでは毎回40人程度が執筆に関わるので全員に特定のプラットフォームを強制することはできません。戦争が起きます。 -CIとlanguage-reviewがあればローカルで文法チェックを行ってCIがビルドする、という形で最低限の執筆環境ができます。 -またmasterが壊れている場合もすぐに気づけるため、常にクリーンな環境を維持できます。 +TechBoosterでは40人程度が執筆に関わるので全員に特定のプラットフォームを強制することはできません。戦争が起きます。CIとVisual Studio Codeのlanguage-reviewがあればローカルで文法チェックを行ってCIがビルドする、という形で最低限の執筆環境ができます。 + +またmain branchが壊れている場合もすぐに気づけるため、常にクリーンな環境を維持できます。 エンジニアにとってビルドエラーの恐怖は説明するまでもありませんね。 -レビュー期間も同様です。pushを停止させずにレビューしようと思うと、どこかにPDFがあることが望ましいわけです。 -そこでCIでは入校時と同じスタイルを利用して常に入稿形式に準じたPDFを生成しています。 -レビューでも紙面レイアウトも含めてみることで素早く問題点に気づき、筆者にフィードバックを返すことができます。 +レビュー期間も同様です。著者からのpushを停止させずにレビューしようと思うと、どこかにレビュー用のPDFがあることが望ましいわけです。そこで前述の仕組みが活きます。CIでは入校時と同じスタイルを利用して常に入稿形式に準じたPDFを生成しています。レビューでも紙面レイアウトでチェックすることで文字のはみ出しなど些細な問題でも素早く気づき、筆者にフィードバックを返すことができます。 -実際の所、CIサーバの構築は手間がかかるのでTechBoosterで運用しているGrifletを公開したいのですが、 -いまのところ負荷問題があり、それに至っていません。手軽に得られるビルド環境としてDockerイメージ@{docker-image}を提供しています。 -最近だとDockerイメージを流用しやすいCircle CI 2.0@{circleci-2.0}やWercker@{wercker}などのCIサービスもでてきています。 +実際の所、CIサーバの構築は手間がかかるのでTechBoosterでメンテナンスしています。手軽に得られるビルド環境としてDockerイメージRe:VIEW image for Docker@{docker-image}を提供し、Dockerイメージを流用しやすいGitHub Actionsを作っています。ReVIEW-Templateリポジトリ@{yattane}をテンプレートとして使うだけで、これらの環境が整います。すごいね！やったね！ //footnote[docker-image][@{https://hub.docker.com/r/vvakame/review/}] -//footnote[circleci-2.0][@{https://circleci.com/docs/2.0/}] -//footnote[wercker][@{http://www.wercker.com/}] - -== 文章を書く上での注意点 -本を作るうえで苦労することのひとつに統一感があります。文章が途中で変わっていないか、主張が変わっていないか、 -タイトルと内容が変わったり、本の最後のほうで文体が変わったりするとやはりもったいないなぁ、という風になりますよね。 - -本書の筆者であるmhidakaとvvakameが書いた技術的な文章を書くための手引@{guide}も役に立つかもしれません。 - -//footnote[guide][@{http://qiita.com/mhidaka/items/c5fe729716c640b50ff7}@
{}@{http://qiita.com/vvakame/items/d657baf26cf83ac98bd0}] - -技術書として注意したらよいポイントをいくつか列挙していきます。粒度に差はありますが、重要だと思う項目からの紹介です。 - -=== 主張の統一 -ひとつの文章にたくさんの主張を入れると読む人は混乱してしまいます。 -読みやすさを考えてシンプルな構成を選びましょう。 - - * 特定のコンテキストでは、ひとつの主張のみ扱う（章、節、項で主張の大小はある） - * 初出の単語、概念は登場時点で説明する - -たとえば章のはじめには導入（リード文）を用意してまとめを説明して読者と記事のマッチングをはかります。 -書いているうちに節のタイトルが本文と異なる場合もありますので主張を意識して読みなおすことが大切です。 -執筆中は初出の単語、概念など気づかない場合があります。読みなおすことで初出の単語の発見や、 -前後の文章を入れ替えて主張を理解しやすくするなど、本の構成をよりよく変えられます。 - -=== 文中の文言と装飾を書籍にあわせる - -#@# prh:disable -文章を書いていると上下を意識して「以上が」「以下のとおりです」など書きたくなりますが -組版の都合で上下が明らかでない場合があります。次のページにいってしまったりするわけですね。 -それぞれ「前述のとおり」「次のとおりです」で置き換えるとよいでしょう@{lint}。 -これらのために、@{review-introduction}で解説するリストや図があるわけです。 - -//footnote[lint][後述のprhで技術書向きの校正を行えます。自分好みにカスタマイズするとよいでしょう] - -また図、表、リストについては次のことを念頭に構成してください。 - - * 図、表、リストの登場前に本文中から参照する（＠、＠など） - * 登場前に内容を簡単に説明する一文を書く - * 登場後に詳しい解説を書く - -これらを守ることで何について述べているのかわかりやすくなり、読者が読んだときの唐突感や投げっぱなし感がなくなります。 - -装飾には、いわゆる太字、斜体などフォントの見た目を変えて読みやすくする意図があります。 -しかし、利用基準を定めて守るほうが難しく、一貫性を保つのが作業量的にしんどい側面もあります。 -大事な内容であれば、文章中で注意喚起したほうがよっぽどよいでしょう。 -装飾が必要なときは編集担当者がチェックできる基準でのみ実施すべきです。 -#@# REVIEW vvakame review-introduction.reで結構文字装飾使ってる… - -たとえばリスト中の変数名ではコードとして装飾する、など明確な基準がある装飾であれば統一感がありますね。 - -=== 文体の統一 -文体は著者の味となるため過剰な編集は好みませんが、それでも次のような表現は -編集段階で変更しています。 - - * ネガティブな表現を利用しない - * 体言止め、話し言葉は利用しない - * ですます調と、である調を混在しない - * 思いますなど感想にならないようにする - * 文章中の記号は全角が基本（特にカッコ） - * 文章中の英単語は前後にスペースを入れないで空きを詰める - -ネガティブな表現は読者の心証を悪くします。期待して本を読んでいる読者に、 -デメリットだけでなくメリットも感じてもらえるように表現をポジティブに改めます。 -また技術書であれば平易な表現を心がけて読者の理解に努める方針のもと、 -著者の文体を壊さない程度に調整します。 -「～だと思います」という文章であれば「です」と編集したり、 -「～することができます」という表現であれば簡潔に「～できます」と縮めています。 - -編集時には想定読者になりきって読みやすい文章を追及しましょう。 - -見た目に影響する話では、半角記号は基本的に英字に合わせてフォントが作られています。 -文章中で表現として使う場合、記号は全角を利用してください。 -メソッド名、プログラムのソースコードからの引用はその限りではありません。 - -とくに半角カッコはフォントの高さが全角文字と異なるため、沈んだ印象を受けます。 -全角カッコを利用するようにしてください。 - -== 校正支援ツールprhを導入する - -校正支援用ツールとしてprh@{prh}があります。 -prhはproofread helperの略です。 -proofreadで1単語だから略したらphだろ！とか言ってはいけません。 - -#@# prh:disable -prhは単純にルールに従い、文字列を置き換えるだけのものです。 -たとえば、「例えば」と書いたときに「たとえば」に置き換えるよう促してくれます。 -これを漢字をひらがなに「開く」操作といいます。 - -一般的な表現を用いることで文章を読みやすくする効果があります。 -文章の質を高めるためにはこのような書き換え処理をたくさんこなす必要があるわけです。 - -TechBoosterでは原稿をみんなが書き終えた後、羊（@mhidaka、サークル主催）くんが全員の原稿に手を加え、開く処理をいれるなどの作業を行っていました。 -そこでprhを作成し羊の作業から著者個人の作業に落とした@{crazy-mhidaka}わけです。 -面白いもので、規則をルール化し記述できるようにしたことで著者の中での校正に対する関心も高まってきました。 - -肝心の使い方についてです。現状あまりコマンドラインツールとしての使い勝手はよくありません。 -language-reviewにはprhが組み込まれているため、language-review経由で使うのが楽でしょう。 - -まずは、TechBoosterの設定ファイル@{prh_setting}をダウンロードして試してみるのがよいでしょう。 -ファイルを@{prh.yml}という名前で.reファイルと同じディレクトリに置くとlanguage-reviewが校正用ルールとして参照して、Lintを表示します（@{lint}）。 - -//image[lint][校正の指摘例]{ - -//} - -類似のツールには -RedPen@{redpen}やtextlint@{textlint}などがあります。 -さらなる文章の改善を目指すのであれば、これらのツールを利用してみるのもよいでしょう。 - -とはいえ、根本的に文章の目的と構造がしっかりしていないといくら枝葉末節を補ったところで意味はありません。 - -//footnote[prh][@{https://github.com/prh/prh}] -//footnote[crazy-mhidaka][「すごい！校正の労力が半分になったぞ！だから前回の2倍の冊数作った！」ってヤツは言いました。あたまおかしい] -//footnote[prh_setting][@{https://github.com/prh/rules/blob/a05c35d285d08dc7ba0a78dd791160116d39e9f4/media/techbooster.yml}] -//footnote[redpen][@{http://redpen.cc/}] -//footnote[textlint][@{http://efcl.info/2015/09/10/introduce-textlint/}] +//footnote[yattane][@{https://github.com/TechBooster/ReVIEW-Template}] diff --git a/articles/writing-book.re b/articles/writing-book.re index 51095fa..5318d82 100644 --- a/articles/writing-book.re +++ b/articles/writing-book.re @@ -2,8 +2,8 @@ #@# NOTE author:mhidaka -本章では、Re:VIEWを使ったエンジニア向けの執筆・編集スタイルを紹介します。 -自然言語による文章もプログラムを書くのと大差ないな！と思っていただければ幸いです。 +本章ではRe:VIEWを使ったエンジニア向けの執筆・編集スタイルを紹介します。 +自然言語による文章もプログラムを書くのと大差ないな！と感じていただければ幸いです。 == Re:VIEWとは @@ -11,7 +11,7 @@ @{Re:VIEW,レビュー}は、書籍制作のためのツールセットです。 技術書は、知識を体系的にまとめ読者の興味関心を誘引するもっともポピュラーな手段ですが、執筆や編集については独自のノウハウがあり、統一したものが存在していません。 -書籍制作は本来、手作業が多く専門知識を必要とする、ハードルの高い領域なのです。 +書籍制作は本来、手作業が多く専門知識を必要とするハードルの高い領域なのです。 しかしRe:VIEWを使えば、これまでよりずっと手軽に技術書を作ることができます。 本を作る工程を@{review-cover}に示します。 @@ -22,14 +22,15 @@ ご覧のとおり「Re:VIEW」は「執筆」「校正」「組版」「製版」までと、非常に幅広い範囲をサポートします。 TechBoosterではRe:VIEWを使うことで効率的に文書管理、執筆環境を構築できるようになりました@{products}。 +これはRe:VIEWが読者のみなさん全員にベストだという主張ではありません。技術書を書くためにちょうどよいといった具合です。標準的なツールを通してプラクティスを学び、最適な表現方法にたどり着いてください。我々が苦労し、改善してきた経緯や背景を糧に最適化してください。 -//footnote[products][制作する書籍は年間12冊超、述べ2000ページ超を数えます。ヤバすぎ] +//footnote[products][制作した書籍は50冊以上、1冊あたり平均200~300部ぐらいです。1冊で5,000部を超えるものもあります。ヤバすぎ！] =={requirement} 本を作るための技術的要求 #@# NOTE author:vvakame -わたしたちが考える、技術書を書くためにあるとよい機能を挙げます。 +わたしたちが考える技術書を書くためにあるとよい機能を挙げます。 * 文書の共有とリビジョン管理がしやすい * コメントを利用できる @@ -38,28 +39,33 @@ TechBoosterではRe:VIEWを使うことで効率的に文書管理、執筆環 #@# REVIEW vv: 外部のツール（prhなど）と連携しやすい も追加したい気もするがトップレベルでもないなぁ -世の中にはRe:VIEW以外にも、Microsoft Wordなどのワープロソフトや、Markdown、textile、reStructuredText、AsciiDoc、LaTeX、Sphinxなどのマークアップまで、さまざまな形式があります。 -この中から、これらの条件にマッチしないものは避けたほうがよいというのがわたしたちの考えです。 +世の中にはRe:VIEW以外にも、Microsoft Wordなどのワープロソフトや、Markdown、textile、reStructuredText、AsciiDoc、LaTeX、Sphinxなどのマークアップまで、さまざまな形式があります。VivliostyleなどはRe:VIEWと同じく組版を対象としています。 + +この中から、前述の4つの条件にマッチしないものは避けたほうがよいというのがわたしたちの考えです。 === 文書の共有とリビジョン管理がしやすい プログラムのソースコードと同様に、文書もリビジョン管理ができると便利です。 -リビジョン管理があれば、いらないのではないか？と思った節をバッサリ削ることも気軽にできます。 -また、いつ誰がどう変更したかを追跡できたり、どのくらいの分量を書いたかが分かるのは想像以上のメリットです。 +書いているときに、この文章はいらないのではないか？と思ったとしてもバッサリ削れます。 +さらにいつ誰がどう変更したかを追跡できたり、どのくらいの分量を書いたかが分かるのは想像以上のメリットです。 +リビジョン管理があれば、試行錯誤を気軽にできます。 === コメントを利用できる -コメントは、メモを書き残すとき、他人の原稿にレビューを書き込むときに使います。 -たとえばIssueに@{原稿の○行目に対する指摘 > わかる→分かる に置き換え}といちいち指摘を書くのは、やるのも苦行、Issueと原稿を見比べて反映するのも苦行です。 +コメントはメモを書き残すとき、他人の原稿にレビューを書き込むときに使います。 +たとえばIssueに@{原稿の○行目に対する指摘 > わかる→分かる に置き換え}といちいち指摘を書くのは、やるのも苦行ですし、Issueと原稿を見比べて反映するのも苦行です。 原稿とレビュー結果を別々の場所に置くべきではないと、わたしたちは考えています。 レビュー結果はコメントを使い、原稿にインラインに書き込んでいくスタイルを推奨しています。 +文章は厳密性という点ではソースコードと比べられません。ふわっと表現できるわけですし、伝わりやすい日本語は1種類だけでもありません。レビューの結果など適切なコメント（ディスカッション）のログは資産です。 === HTMLやPDF、EPUBなど複数の形式に変換できる 執筆した文書をWebサイトとして公開したい場合、印刷所に入稿したい場合、電子書籍として配布したい場合など、用途に応じたフォーマットに変換しなくてはなりません。 そのため、なるべくたくさんの形式に変換できるものがよいでしょう。 +技術書であれば主なターゲットはPDFですが、あとからEPUBにできればKindleのmobiファイルなどの電子リーダー独自のフォーマットにも対応できます。拡張性を求めるなら最初から考慮されているツールセットをおすすめします。 + === 文書の構造と見た目（スタイル）が分離されている たとえば章タイトルの文字を大きく強調したいときを考えます。 @@ -71,17 +77,22 @@ TechBoosterではRe:VIEWを使うことで効率的に文書管理、執筆環 構造化された文書は見出しのスタイルを一括で変更したり、目次を生成することが簡単にできます。 執筆者全員を教育してこの問題を乗り越えることもできますが、それよりも根本的に構造とスタイルが分離されているツールを使うほうが楽です。 +強調したいときに太字にしているのか、初出単語だから太字にしているのか、装飾から作者の意図を正しく読み解くのは編集者にも読者にも不可能です。 + == TechBoosterがRe:VIEWを勧める理由 -Re:VIEWは、@{requirement}に述べた理由をすべて満たします。 +Re:VIEWは@{requirement}に述べた理由をすべて満たします。 + +Re:VIEWでは本文をプレーンテキストファイルで執筆するのでGitなどを使ってリビジョンを管理できます。 +そのままGitHubなどを通じて作業するだけでなくGitHub ActionsやCircle CIを利用できますし、TechBoosterで制作したRe:VIEW専用のGitHub Actions@{github-actions}があります。CommitごとにPDFを確認できる利便性は計り知れません。 -Re:VIEWでは本文をプレーンテキストファイルで執筆するので、Gitなどを使ってリビジョンを管理できます。 -そのままGitHubなどを通じて作業するだけでなくTravis CIやCircle CI、その他Re:VIEW専用CI「@{Griflet, グリフレット}」を利用できます。 -またHTMLやPDF、EPUBやMarkdownといった主要な形式への変換にも対応しています。 +//footnote[github-actions][Re:VIEW build artifact action @{https://github.com/marketplace/actions/review-build-artifact-action}] + +またRe:VIEWはHTMLやPDF、EPUBやMarkdownといった主要な形式への変換にも対応しています。 さらに、文書の構造と見た目が十分に分離されているので、原稿ができてから見た目を調整できます。 そしてRe:VIEWは、出版を生業としている方々が作っているので「本を書くための工夫」がたくさん詰まっています。 -日本人が作っているツールだけあって、日本固有の事情も考慮されているので、今までたくさんの本の製作に使われてきた実績@{archievement}があり、そうそう落とし穴に落ちたりすることもありません。 +日本人が作っているツールだけあって、日本語固有の事情も考慮されています。そして今までたくさんの本の製作に使われてきた実績@{archievement}があり、商業誌と同じクオリティを確保しています。そうそう落とし穴に落ちたりすることもありません。 わたしたちはRe:VIEWを使うだけで、先人たちの知恵を活用できるのです。 @@ -95,21 +106,24 @@ Re:VIEWは優れた書籍制作ツールですが、そのままでは入稿で たとえば多くの印刷所ではノンブル（ページの通し番号）が必須です。乱丁を防ぐ目的で導入されていますが、これは同人誌独特のルールで、標準のRe:VIEWでは対応していません。 -それら入稿データを作成するはじめの一歩として、TechBoosterでは現実世界の例として本書のリポジトリを公開しています。 -ノンブルもサポートしつつ、見やすいレイアウトに変更しています（本書も全ページに通し番号がついています）。 +それら入稿データを作成するはじめの一歩として、TechBoosterでは現実世界の例として本書のリポジトリを公開しています。ノンブルもサポートしつつ、見やすいレイアウトに変更しています（本書も全ページに通し番号がついています）。 #@# prh:disable - * @{https://github.com/TechBooster/C89-FirstStepReVIEW-v2} + : 本書のリポジトリ + @{https://github.com/TechBooster/C89-FirstStepReVIEW-v2} + + : テンプレートリポジトリ + @{https://github.com/TechBooster/ReVIEW-Template} -同人誌制作がはじめてという場合は上記リポジトリからのCloneを@{強く推奨}します。 +同人誌制作がはじめてという場合はテンプレートリポジトリからのCloneを@{強く推奨}します。 このリポジトリでは、B5（JIS）サイズでノンブルを追加した専用レイアウトを使用しています。 -後述の方法で日光企画さんに入稿経験のあるサンプルプロジェクトです。はじめての執筆で利用するにはうってつけです。 -#@# C92で判型変えるならここんとこメンテする必要がある -#@# C92でも判型維持でいくか +印刷所である日光企画さん・ねこのしっぽさんに入稿できる、多数の利用実績があるテンプレートリポジトリです。はじめての執筆で利用するにはうってつけです。出力方法は後述の章で解説します。 しかしながらすべての印刷所で大丈夫とは限りません。印刷所ごとに入稿ルールは異なります。 -入稿に先立ってサンプルを用意し、印刷所の指示にしたがって入稿データを作成してください。 +入稿に先立って印刷所のスタッフが確認できるサンプルファイルを用意し、印刷所の指示にしたがって入稿データを作成してください。 大抵の印刷所は初心者に対して十分に優しく、トライアンドエラーで一緒に先に進む手伝いをしてくれるでしょう。 印刷所が変わる場合は、きっとカスタマイズが必要です。そのための雛形として活用してください。 -本書のリポジトリは一番手間がかかるノンブルの問題を解消しているので、すべてを自分で解決するよりは楽なはずです。 + +本書のリポジトリやテンプレートリポジトリは一番手間がかかるノンブルやトンボといった特殊な印刷専用のフォーマットの問題を解消しているので、すべてを自分で解決するよりは相当に楽ができます。なによりトラブルに巻き込まれるかもという不安が減るのは大きなメリットです。 +