技術書をかこう ! ~ はじめての Re : Ⅵ EW ~ 著者 TechBooster 編 編集 mhidaka 発行所 TechBooster (C) 2015 TechBooster 72

も書いています。本をつくる上での数々の障害を取り除いてくれる、とっても使いやすい ツールです。工ンジニアが好きな Git が、 di 仕が、 Lint が、 CI が、全部使えます。 本書には技術書をつくるためのツール、文法、執筆、運用について知見を、経験を、失 敗をカの限り詰め込みました。さあ、あなたの好きな技術を広めるために本をつくってみ ませんか。 TechBooster は本を作る楽しみを知っています。その世界に、ぜひ皆さんにも踏み込ん できて欲しいと思います。 ( 発行代表 @mhidaka) TechBooster とは TechBooster は Android をはじめとしたモバイルのための技術サークル * 1 です。 プンソースへの貢献や社会還元を目的にサイトでモバイル技術を解説しています。 お問い合わせ先 本書に関するお間い合わせ https://plus ・ google. com/+ TechboosterOrg/ オー 免責事項 本書に記載された内容は、情報の提供のみを目的としています。したがって、本書を用 いた開発、製作、運用は、必ずご自身の責任と判断によって行ってください。 報による開発、製作、運用の結果について、著者はいかなる責任も負いません。 * 1 TechBooster の Web サイト http: //techbooster. org/ 3 これらの情

技術書をかこう ! ~ はじめての Re : Ⅵ EW ~ TechBooster 編著 2015-12-31 版 TechBooster 発行

第 3 章 Re:VIEW の書き方 リンク URL をリンクとしてマークアップする構文です。 リンクには、出力したときに URL を表示する場合と、 ます。 リスト 3.23 は、 URL を表示する場合です。 ▽リスト 3.23 URL リンク @くhref>{http ://techbooster.org/ しない場合の 2 つの方法があり リスト 3.23 を出力した結果は、 "http://techbooster ・ org" のように URL がそのま ま表示されます。 またリスト 3.24 は、 URL を表示しない場合です。 URL に加えて、コンマで区切ってリンクを設定する文字列を続けます。 マリスト 3.24 リンク (U RL 無し ) @くhref>{http://techbooster.org/TechBooster} 30 脚注は出力されません。 脚注を有効にするには、本文で参照している必要があります。本文で参照されていない 脚注は、記述した場所に関係なく「脚注の領域」に表示されます。 //footnote [identifier] [ 脚注の内容は、ページで本文とは別の「脚注の領域」に表示されます ] V リスト 3.25 コマンドライン リスト 3.25 は、脚注を記述した例です。 本文に別の情報を付記する構文です。「注釈」とも呼ばれます。 脚注 合は、 URL を表示する方法が適しています。 URL を表示する方法では印刷後でも URL そのものは分かるので、最終的に印刷する場 当然のことながら、どちらの場合でも紙に印刷するとリンクは使えなくなりますが、 リンクが設定された状態になります。 リスト 3.24 を出力した結果は、 "TechBooster" のように URL が表示されず、文字列に

4.3 ページサイズを変更する # 固有 ID に使用するドメイン。省略した場合は時刻に基づくランダム工 D が入る urnid: urn:uid:https ://github.com/TechBooster/C89—FirstStepReVIEW—v2 # 著者名。 [ " 高橋征義 " , "John Doe"] のように配列を使うことで複数指定可 aut : C"TechBooster 編 " ] # 出版社。配列書式で複数指定可能 prt : TechBooster # 編集者。配列書式で複数指定可能 edt : ["mhidaka"] # 刊行日。 YYYY-MM-DD 形式。省略した場合は本日の日付 date: 2015 ー 12 ー 31 # 発行年月。 YYYY-MM-DD 形式による配列指定。省略した場合は date を使用する history: [ [ " 2015 ー 12 ー 31 C89 版 vl. 0.0 " ] ] # 権利表記 rights : (C) 2015 TechBooster # css ファイル ( 配列で複数指定可、 y 1 ファイルおよび Re : VIEW ファイルを置いたディレクトリ にあること ) stylesheet: ["style . css"] # ePUB のノヾージョン ( 2 か 3 ) 省略した場合は 2 epubversion : 3 # 目次を作成するか。省略した場合は皿 11 ( 作成しない ) toc : true # 目次として抽出する見出しレベル。省略した場合は 2 toclevel : 2 # 本文でセクション番号を表示する見出しレベル。省略した場合は 2 # 採番させたくない見出しには「 = = [ Ⅱ 0 Ⅱ ] 」のように n 。Ⅱ um 指定をする secnolevel : 2 # 表紙の後に大扉ページを作成するか。省略した場合は皿 11 ( 作成しない ) titlepage : true # 奥付を作成するか。デフォルトでは作成されない。 true を指定するとデフォルトの奥付、 ファイル 名を指定するとそれが coloph 。Ⅱ . html としてコピーされる C010Ph0 Ⅱ : true texstyle : techbooster—doujin "b5j ,twoside,openany"] texdocumentclass : ["jsbook" 己述できる項目は多いので、 Re : VIEW 公式のサンプルと Wiki を参照してください。 サンプル https://github. com/kmuto/review/blob/master/doc/sample.yml Wiki 二一一口 https : //github. com/kmuto/review/wiki/config.yml 生 3 ページサイズを変更する PDF 形式で出力するべージサイズを指定するには、 config. yml の textdocumentclas s : 項目の 2 番目の値を設定します ( リスト 4.4 ) 。 この設定は、 LaTeX におけるドキュメントクラスのオプションに該当します。複数の 41

7.5 関連各所の紹介 -chapterlink # html の生成 review—compile # latex の生成 review—compile # idgxml の生成 review—compile # pdf の生成 ー a11 ー a11 ー a11 —html —stylesheet=style . css —footnotetext —target=latex —target— —target=idgxml review—pdfmaker config ・ yml # epub の生成 review—epubmaker config ・ yml 69 ・記号などの文字化け探し (Tex 、フォントは UTF-8 対応しているとは限らない ) ・紙面を = や * で検索する ( 文法ミスを見つけるため ) レビューを実施する ( 読者の視点を作り出す ) ・執筆時点は早めの締め切りを設定する ( こうしておくと致命傷で済む ) 一人でかかない ( 共同執筆がお勧め ) ・企画は書きたいことを選ぶ ( モチベーション維持 ) 限られた時間のなかで可能な限り品質を確保するポイントをリスト形式で紹介します。 7.6 品質を高めるためのチェックポイント ありがとう ! そしてありがとう ! ! 日光企画 : お世話になっている印刷所 トップスタジオ : Re:VIEW によるリフロー ( 自動組版 ) を導人している制作会社 ・達人出版会 : Re:VIEW を使った電子書籍を扱う出版社 介します。 TechBooster が Re:VIEW を使っているなかで関係したお世話になっている各所を紹 7.5 関連各所の紹介 master/Gruntfi1e. js Node. js v4 以上が必要ですので注意してください。 しています。 https://github.com/TechBooster/C89—FirstStepReVIEW-v2/b10b/ これらを詰め込んだ、実際に TechBooster で使っている grunt 用設定ファイルを公開 あとはそれぞれのターゲット向けに下準備とビルドを行うタスクを作成するだけです。 ください。 マンドそのものが違うので注意します。詳細は第 3 章「 Re:VIEW の書き方」を参照して 欲しい出力結果に応じて、コマンドを使い分けます。 pdf 、 epub については利用するコ

6.2 執筆のための継続的インテグレ ーション - G ⅱ升 で、何を書かないかの選択が重要です。編集も著者の主張が適切に伝わるか、 で作業します。 という観点 編集者が校正 & 調整作業に入る ( 直 push の禁止。変更は pull request を送る ) 凍結後に master を変更する権限をもつのは編集者 (TechBooster では羊 ) だけです。 執筆者がどうしても修正したい場合、 pullrequest を送りお伺いを立てます。これを守ら ない場合、 PDF 化した時に改行の具合やら 1 行あたりの文字数やらを調整しているので 編集者がぶつぶくふー ! になります。可哀想なのでやめてあげましよう。 62 執筆のための継続的インテグレーション - GrifIet 工ンジニアであれば master ビルドが壊れることを極端に怖がると思います。正しい。 そこで TechBooster では CI サーバ Gri 日 et * 2 を用意して常に最新の PDF 出力が得られる ような運用をしています。これには多くのメリットがありますが中でも次のような点で執 筆に貢献しています。 ・ビルド環境の準備が不要になる Re:VIEW の文法工ラーにすぐ気づける ・レビュー対象物を特定できる TechB 。。 ster では毎回 40 人程度が執筆に関わるので全員に特定のプラットフォームを 強制することはできません。戦争が起きます。 CI と language-review があればローカル で文法チェックを行って CI がビルドする、という形で最低限の執筆環境ができます。ま た master が壊れている場合もすぐに気づけるため、常にクリーンな環境を維持できます。 工ンジニアにとってビルドエラーの恐怖は説明するまでもありませんね。 レビュー期間も同様です。 push を停止させずにレビューしようと思うと、どこかに PDF があることが望ましいわけです。そこで CI では人校時と同じスタイルを利用して 常に人稿形式に準じた PDF を生成しています。レビューでも紙面レイアウトも含めてみ ることで素早く間題点に気づき、筆者にフィードバックを返すことができます。 実際の所、 CI サーバの構築は手間がかかるので TechBooster で運用している Griflet を公開したいのですが、いまのところ負荷間題があり、それに至っていません。手軽に得 られるビルド環境として DockerfiIe を提供しています。 53 * 2 Griflet ( グリフレット ) はグリフ十リーフレットの造語です。本に由来して名前を考えています。かっこ いいとおもいません ? 僕は思います

第 6 章ワークフロー 54 ・表紙データ : 表紙は本文と別の形式で人稿する 書のリポジトリ十日光企画さんを使うとトラブルなく人稿できる可能性が高くなります ) 。 TechBooster が過去に遭遇した事例では次のとおりです ( 印刷所選びに不安があれば本 じてくれるでしよう。 とよいでしよう。だれもが最初から熟練者ではありません。初めての人の相談にも快く応 腕の見せ所といえます。紙の種類も多数あるため詳細を知りたい場合は印刷所に相談する マンド印刷でも十分な品質を得られるケースがあります。とくに品質については印刷所の 一般的にオフセット印刷のほうが品質がよいですが、近年の印刷技術向上によりオンデ ります。 100 部 ~ の印刷に適しています。版を作る手法で、ロット数に応じて単価が安くな オフセット印刷 方、単価は高めです。 ~ 100 部の小口ット印刷に適しています。印刷に使う版を作らないので手軽な一 オンテマンド印刷 人稿に先立って知っておく知識として、部数に応じて適した印刷手法が異なります。 予定の印刷所が指定するフォーマット、注意点を熟読して人稿に挑みましよう。 すので日光企画さんの事例に限って人稿に必要な知識をみていきましよう。実際には人稿 かといって、すべてを説明すると流れを理解するまえに頭がパンクしてしまいます。で 定があったり、さまざまです。 裁位置の目印 ) がないと受け付けてもらえなかったり、利用ソフトウェアのバージョン指 たとえば表紙データは印刷所ごとテンプレートが異なったり、人稿用本文にトンポ ( 断 というものはありません。 ます。実のところ、印刷所ごとに印刷工程が違い、すべてで通用するスタンダードな方法 こから先は TechBooster が日光企画さんへ人稿した場合の手順として解説していき https://github.com/TechBooster/C89-FirstStepReVIEW-v2 な同人誌特有の間題を回避できます。 用する前提です。本書のリポジトリを CIone している場合、ノンプル ( 通し番号 ) のよう 第 1 章「技術書を書くための要求」で述べたとおり、同人誌向けの Re : VIEW 構成を使 際の事例をベースに解説します。 印刷所へ最終的な印刷用データを渡すことを人稿と呼びます。本節では人稿について実 6.3 入稿のための最終出力を作る

6.5 校正支援ツール prh を導入する とはいえ、根本的に文章の目的と構造がしつかりしていないといくら枝葉末節を補った 指すのであれば、これらのツールを利用してみるのもよいでしよう。 類似のツールとして RedPen*9 や textlint*10 などがあります。さらなる文章の改善を目 多いと処理が重くなるのでコミットの段階でチェックする使い方もお勧めです。 と language-review が校正用ルールとして参照して、 Lint を表示します。また文章量が ウンロードしたファイルを prh. yml という名前で . re ファイルと同じディレクトリに置く master/misc/techbooster. yml) をダウンロードして試してみるのがよいでしよう。ダ まずは、 TechBooster の設定ファイル (https : //github. com/vvakame/prh/blob/ で使うのが楽でしよう。 ありません。 language-review には prh が組み込まれているため、 language-review 経由 肝心の使い方についてです。現状あまりコマンドラインツールとしての使い勝手はよく ルール化し記述できるようにしたことで著者の中での校正に対する関心も高まってきま 作成し羊の作業から著者個人個人の作業に落とした、 8 わけです。面白いもので、規則を が全員の原稿に手を加え、開く処理をいれるなどの作業を行っていました。そこで prh を 63 * 10 * 9 http: //efcl . inf0/2015/09/10/introduce—text1int/ http://redpen.cc/ * 8 「羊の労力が減るぞ ! 」と僕が言ったら、彼は「じゃあもっと作れるな ! 」って言いました。あたまおか ところで意味はありません。

第 7 章 役に立つ豆知識 技術書を作る際に詰まる部分をまとめました。知らなければたどり着かない知識や、 ちょっとした工夫など便利なテクニックを紹介します。 7-1 推奨するディレクトリ構成 TechBooster が推奨するディレクトリ構成を述べておきます。要点は次のとおりです。 具体的にはリスト 7.1 です。 リポジトリのトップレベルにはファイルをあまり散らかさない ・複数人で執筆した時にそれぞれのファイルが混ざったり邪魔になったりしないよう ビルド手順を統一するために何らかのタスクランナーを使う (TechBooster の場 著者全員で利用する review のバージョンを固定する にする 合、 Node. js 十 grunt) ティレクトリ構成 README . md circle . yml setup. sh Gemfi1e Gemfi1e . lock トーーーー package ・ j son npm—shrinkwrap ・ j son トーーー Gruntfi1e. js articles トーーー catalog ・ yml config ・ yml prh リスト 7.1 ( CI サービスである Circ1e CI の設定ファイル ) ( 執筆前に gem やⅡ pm のインストールを行うスクリプト ) (bundler 経由で Re:VIEW を利用するための設定ファイル ) ( ライブラリのバージョンをロックする ) (grunt を利用するための npm 用設定ファイル ) ( ライブラリのバージョンをロックする ) (grunt の動作設定ファイル ) (Re:VIEW 用章立ての設定ファイル ) (Re:VIEW 用本を生成する時のメタデータ記述ファイル ) (language-review 用校正設定ファイル ) 64