├── .gitignore ├── .textlintrc ├── Gemfile ├── Gemfile.lock ├── Gruntfile.js ├── LICENSE ├── README.md ├── articles ├── assets │ └── sec-nombre │ │ └── sec-nombre.key ├── catalog.yml ├── config.yml ├── editor.re ├── end.re ├── epub_style.scss ├── images │ ├── improve-text │ │ ├── add.png │ │ ├── all-gothic.png │ │ ├── all-minchyo.png │ │ ├── and.png │ │ ├── because.png │ │ ├── but.png │ │ ├── exception.png │ │ ├── gothic-and-minchyo.png │ │ ├── kibana-graph.png │ │ ├── or.png │ │ ├── other_words.png │ │ ├── unexpected.png │ │ ├── unity_notation.png │ │ └── unity_notation_google_doc.png │ ├── introduction │ │ └── slack.png │ └── think-toc │ │ └── tools.png ├── improve-text.re ├── init-textlint.re ├── introduction.re ├── layouts │ └── layout.tex.erb ├── locale.yml ├── markdown │ ├── init-textlint.md │ ├── poish-your-text.md │ └── think-body.md ├── qr.re ├── references.re ├── sty │ ├── jumoline.sty │ ├── onestop-techbook.sty │ ├── reviewmacro.sty │ ├── samplemacro.sty │ ├── tatsumacro.sty │ ├── techbooster-doujin.sty │ └── ulem.sty ├── style-web.scss ├── style.scss ├── think-body.re └── think-toc.re ├── build-in-docker.sh ├── package-lock.json ├── package.json ├── redpen-conf-ja.xml └── setup.sh /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store 2 | node_modules/ 3 | .node-version 4 | .pdf 5 | articles/technical_writing_technic.pdf 6 | -------------------------------------------------------------------------------- /.textlintrc: -------------------------------------------------------------------------------- 1 | { 2 | "rules": { 3 | "preset-ja-technical-writing": true 4 | }, 5 | "plugins": [ 6 | "review" 7 | ] 8 | } -------------------------------------------------------------------------------- /Gemfile: -------------------------------------------------------------------------------- 1 | # A sample Gemfile 2 | source "https://rubygems.org" 3 | 4 | gem 'review', '2.2.0' 5 | gem 'review-peg', '0.2.2' 6 | -------------------------------------------------------------------------------- /Gemfile.lock: -------------------------------------------------------------------------------- 1 | GEM 2 | remote: https://rubygems.org/ 3 | specs: 4 | review (2.2.0) 5 | rouge 6 | rubyzip 7 | review-peg (0.2.2) 8 | rouge (3.1.1) 9 | rubyzip (1.2.2) 10 | 11 | PLATFORMS 12 | ruby 13 | 14 | DEPENDENCIES 15 | review (= 2.2.0) 16 | review-peg (= 0.2.2) 17 | 18 | BUNDLED WITH 19 | 1.16.2 20 | -------------------------------------------------------------------------------- /Gruntfile.js: -------------------------------------------------------------------------------- 1 | "use strict"; 2 | 3 | let fs = require("fs"); 4 | let yaml = require("js-yaml"); 5 | 6 | const articles = "articles"; 7 | const bookConfig = yaml.safeLoad(fs.readFileSync(`${articles}/config.yml`, "utf8")); 8 | 9 | const reviewPrefix = process.env["REVIEW_PREFIX"] || "bundle exec "; 10 | const reviewPostfix = process.env["REVIEW_POSTFIX"] || ""; // REVIEW_POSTFIX="-peg" npm run pdf とかするとPEGでビルドできるよ 11 | const reviewPreproc = `${reviewPrefix}review-preproc${reviewPostfix}`; 12 | const reviewCompile = `${reviewPrefix}review-compile${reviewPostfix}`; 13 | const reviewPdfMaker = `${reviewPrefix}review-pdfmaker${reviewPostfix}`; 14 | const reviewEpubMaker = `${reviewPrefix}review-epubmaker${reviewPostfix}`; 15 | 16 | module.exports = grunt => { 17 | grunt.initConfig({ 18 | clean: { 19 | review: { 20 | src: [ 21 | `${articles}/${bookConfig.bookname}-*/`, // pdf, epub temp dir 22 | `${articles}/*.pdf`, 23 | `${articles}/*.epub`, 24 | `${articles}/*.html`, 25 | `${articles}/*.md`, 26 | `${articles}/*.xml`, 27 | `${articles}/*.txt` 28 | ] 29 | } 30 | }, 31 | shell: { 32 | preprocess: { 33 | options: { 34 | execOptions: { 35 | cwd: articles, 36 | } 37 | }, 38 | command: `${reviewPreproc} -r --tabwidth=2 *.re` 39 | }, 40 | compile2text: { 41 | options: { 42 | execOptions: { 43 | cwd: articles, 44 | } 45 | }, 46 | command: `${reviewCompile} --target=text` 47 | }, 48 | compile2markdown: { 49 | options: { 50 | execOptions: { 51 | cwd: articles, 52 | } 53 | }, 54 | command: `${reviewCompile} --target=markdown` 55 | }, 56 | compile2html: { 57 | options: { 58 | execOptions: { 59 | cwd: articles, 60 | } 61 | }, 62 | command: `${reviewCompile} --target=html --stylesheet=style.css --chapterlink` 63 | }, 64 | compile2latex: { 65 | options: { 66 | execOptions: { 67 | cwd: articles, 68 | } 69 | }, 70 | command: `${reviewCompile} --target=latex --footnotetext` 71 | }, 72 | compile2idgxml: { 73 | options: { 74 | execOptions: { 75 | cwd: articles, 76 | } 77 | }, 78 | command: `${reviewCompile} --target=idgxml` 79 | }, 80 | compile2pdf: { 81 | options: { 82 | execOptions: { 83 | cwd: articles, 84 | } 85 | }, 86 | command: `${reviewPdfMaker} config.yml` 87 | }, 88 | compile2epub: { 89 | options: { 90 | execOptions: { 91 | cwd: articles, 92 | } 93 | }, 94 | command: `${reviewEpubMaker} config.yml` 95 | } 96 | } 97 | }); 98 | 99 | function generateTask(target) { 100 | return ["clean", "shell:preprocess", `shell:compile2${target}`]; 101 | } 102 | 103 | grunt.registerTask( 104 | "default", 105 | "原稿をコンパイルしてPDFファイルにする", 106 | "pdf"); 107 | 108 | grunt.registerTask( 109 | "text", 110 | "原稿をコンパイルしてTextファイルにする", 111 | generateTask("text")); 112 | 113 | grunt.registerTask( 114 | "markdown", 115 | "原稿をコンパイルしてMarkdownファイルにする", 116 | generateTask("markdown")); 117 | 118 | grunt.registerTask( 119 | "html", 120 | "原稿をコンパイルしてHTMLファイルにする", 121 | generateTask("html")); 122 | 123 | grunt.registerTask( 124 | "idgxml", 125 | "原稿をコンパイルしてInDesign用XMLファイルにする", 126 | generateTask("idgxml")); 127 | 128 | grunt.registerTask( 129 | "pdf", 130 | "原稿をコンパイルしてpdfファイルにする", 131 | generateTask("pdf")); 132 | 133 | grunt.registerTask( 134 | "epub", 135 | "原稿をコンパイルしてepubファイルにする", 136 | generateTask("epub")); 137 | 138 | require('load-grunt-tasks')(grunt); 139 | }; 140 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2019 MofuMofu 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # この本の趣旨 2 | 3 | 「やっぱり文章を書くのは向いていないから、技術同人誌を書くのはやめておこう」と思っていませんか？ 4 | 5 | それは大変もったいないことです。 6 | 7 | 文章の書き方を理解すれば、誰でも文章を書けるようになります。 8 | 9 | この本は、実際の文章例を交えつつ、「技術同人誌を書くための文章技術」をお伝えするものです。 10 | 11 | 特に「どうすればよりわかりやすい文章になるか」の項目を重点的に記載しています。 12 | 13 | ## 頒布場所 14 | 15 | [技術書典6](https://techbookfest.org/event/tbf06)にて、[き28 りまりま団](https://techbookfest.org/event/tbf06/circle/35980001)で頒布します。 16 | 17 | ## 通販 18 | 19 | このリポジトリを組版したものをBOOTHで公開しています。もし良ければこちらから購入してください😽 20 | 21 | - [冊子版](https://mofu-mofu.booth.pm/items/1275490) 22 | - 送付する手間と送料がかかるので、会場価格よりも500円程高くなってしまいます。 23 | - 発送は4/20ごろになります。 24 | - [電子版](https://mofu-mofu.booth.pm/items/1275494) 25 | - こちらは会場と同じ価格です。 26 | 27 | ## 再配布について 28 | 29 | - 本を組版して自分の作品として売るのはやめてください。 30 | - 引用するのはOKですが、タイトルとこのURLを貼っていただけると嬉しいです。 31 | - リポジトリはpublicにしているので、PDFの再配布は許可します。 32 | - 再配布する際は[感想を送ってください](https://marshmallow-qa.com/froakie0021?utm_medium=url_text&utm_source=promotion)。できれば反映して更新していければと考えています。 33 | - それか、イベント時にお菓子を恵んでもらえると嬉しいです。 34 | 35 | ## 正誤表 36 | 37 | | ページ数 | 修正前 | 修正後 | 38 | | ------- | ------- | ----- | 39 | | 26 | 推敲しても対して | 推敲しても大して| -------------------------------------------------------------------------------- /articles/assets/sec-nombre/sec-nombre.key: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MofuMofu2/TB6-technical-writing-technic/a83c61860b990cf7103b4efdacc932e8d4e66d7f/articles/assets/sec-nombre/sec-nombre.key -------------------------------------------------------------------------------- /articles/catalog.yml: -------------------------------------------------------------------------------- 1 | PREDEF: 2 | # はじめに 3 | - introduction.re 4 | CHAPS: 5 | 6 | # 原稿を書き始める前の準備 7 | - think-toc.re 8 | # 本の内容を記載する 9 | - think-body.re 10 | # 本を推敲する 11 | - improve-text.re 12 | APPENDIX: 13 | # 静的検査ツールで原稿を検査する 14 | - init-textlint.re 15 | POSTDEF: 16 | # 終わりに 17 | - end.re 18 | # 参考文献 19 | - references.re 20 | # 著者一覧 21 | - editor.re 22 | # おまけ 23 | - qr.re 24 | -------------------------------------------------------------------------------- /articles/config.yml: -------------------------------------------------------------------------------- 1 | # review-epubmaker向けの設定ファイルの例。 2 | # yamlファイルをRe:VIEWファイルのある場所に置き、 3 | # 「review-epubmaker yamlファイル」を実行すると、.epubファイルが 4 | # 生成されます。 5 | # このファイルはUTF-8エンコーディングで記述してください。 6 | 7 | # この設定ファイルでサポートするRe:VIEWのバージョン番号。 8 | # major versionが違うときにはエラーを出す。 9 | review_version: 2.0 10 | 11 | # ほかの設定ファイルの継承を指定できる。同じパラメータに異なる値がある場合は、 12 | # 呼び出し元の値が優先される。 13 | # A.yml、B.ymlのパラメータを継承する例。A.ymlとB.ymlに同じパラメータがある 14 | # 場合、B.ymlの値が優先される。さらに今このファイルに同じパラメータがあるなら、 15 | # その値がB.ymlよりも優先される。 16 | # 同様にA.yml、B.yml内でさらにinherit:パラメータを使うこともできる。 17 | # inherit: ["A.yml", "B.yml"] 18 | 19 | # ブック名(ファイル名になるもの。ASCII範囲の文字を使用) 20 | bookname: technical_writing_technic 21 | # 記述言語。省略した場合はja 22 | language: ja 23 | 24 | # 書名 25 | # 読みを入れる例 booktitle: {name: "Re:VIEW EPUBサンプル", file-as: "リビューイーパブサンプル"} 26 | booktitle: 技術同人誌を書くための文章技術 27 | 28 | # 著者名。「, 」で区切って複数指定できる 29 | # 読みを入れる例 aut: [{name: "青木峰郎", file-as: "アオキミネロウ"}, {name: "武藤健志", file-as: "ムトウケンシ"}, {name: "高橋征義", file-as: "タカハシマサヨシ"}, {name: "角征典", file-as: "カドマサノリ"}] 30 | aut: ["もふもふ（Twitter: @froakie0021 Mail: froakie002@gmail.com）"] 31 | 32 | # 以下はオプション 33 | # 以下はオプション(autと同じように配列書式で複数指定可能)。 34 | # 読みの指定はaut:の例を参照。 35 | # a-が付いているものはcreator側、 36 | # 付いていないものはcontributor側(二次協力者)に入る 37 | # a-adp, adp: 異なるメディア向けに作り直した者 38 | # a-ann, ann: 注釈記述者 39 | # a-arr, arr: アレンジした者 40 | # a-art, art: グラフィックデザインおよび芸術家 41 | # a-asn, asn: 関連・かつての所有者・関係者 42 | # a-aqt, aqt: 大きく引用された人物 43 | # a-aft, aft: 後書き・奥付の責任者 44 | # a-aui, aui: 序論・序文・前書きの責任者 45 | # a-ant, ant: 目録責任者 46 | # a-bkp, bkp: メディア制作責任者 47 | # a-clb, clb: 限定参加または補足者 48 | # a-cmm, cmm: 解釈・分析・考察者 49 | # a-csl, csl: 監修者 50 | # a-dsr, dsr: デザイナ 51 | # a-edt, edt: 編集者 52 | # edt: ["編集者"] 53 | # a-ill, ill: イラストレータ 54 | # a-lyr, lyr: 歌詞作成者 55 | # a-mdc, mdc: メタデータセットの一次的責任者 56 | # a-mus, mus: 音楽家 57 | # a-nrt, nrt: 語り手 58 | # a-oth, oth: その他 59 | # a-pht, pht: 撮影責任者 60 | # a-pbl, pbl: 出版社（発行所） 61 | pbl: りまりま団 62 | # a-prt, prt: 印刷所 63 | prt: 有限会社　ねこのしっぽ様 64 | # prt: TechBooster 65 | # a-red, red: 項目の枠組起草者 66 | # a-rev, rev: 評論者 67 | # a-spn, spn: 援助者 68 | # a-ths, ths: 監督者 69 | # a-trc, trc: 筆記・タイプ作業者 70 | # a-trl, trl: 翻訳者 71 | 72 | # 刊行日(省略した場合は実行時の日付) 73 | date: 2019-04-14 74 | # 発行年月。YYYY-MM-DD形式による配列指定。省略した場合はdateを使用する 75 | # 複数指定する場合は次のように記述する 76 | # [["初版第1刷の日付", "初版第2刷の日付"], ["第2版第1刷の日付"]] 77 | # 日付の後ろを空白文字で区切り、任意の文字列を置くことも可能。 78 | history: [["2019-04-14 技術書典6 v1.0.0"]] 79 | # 権利表記(配列で複数指定可) 80 | # rights: (C) 2016 Re:VIEW Developers 81 | # description: 説明 82 | # subject: 短い説明用タグ(配列で複数指定可) 83 | # type: 書籍のカテゴリーなど(配列で複数指定可) 84 | # format: メディアタイプおよび特徴(配列で複数指定可) 85 | # source: 出版物生成の重要なリソース情報(配列で複数指定可) 86 | # relation: 補助的リソース(配列で複数指定可) 87 | # coverage: 内容の範囲や領域(配列で複数指定可) 88 | 89 | # デバッグフラグ。nullでないときには一時ファイルをカレントディレクトリに作成し、削除もしない 90 | debug: null 91 | 92 | # 固有IDに使用するドメイン。省略した場合は時刻に基づくランダムUUIDが入る 93 | # urnid: urn:uid:https://github.com/TechBooster/ReVIEW-Template 94 | # 95 | # ISBN。省略した場合はurnidが入る 96 | # isbn: null 97 | # 98 | # HTMLファイルの拡張子(省略した場合はhtml) 99 | htmlext: html 100 | # 101 | # CSSファイル(配列で複数指定可、yamlファイルおよびRe:VIEWファイルを置いたディレクトリにあること) 102 | stylesheet: ["style.scss"] 103 | 104 | # ePUBのバージョン (2か3) 105 | epubversion: 3 106 | # 107 | # HTMLのバージョン (4か5。epubversionを3にしたときには5にする) 108 | htmlversion: 5 109 | 110 | # 目次として抽出する見出しレベル 111 | toclevel: 2 112 | 113 | # 採番の設定。採番させたくない見出しには「==[nonum]」のようにnonum指定をする 114 | # 115 | # 本文でセクション番号を表示する見出しレベル 116 | secnolevel: 1 117 | 118 | # 以下のsecnolevelはまだ未実装。 119 | # 前付でセクション番号を表示する見出しレベル(未実装) 120 | # pre_secnolevel: 0 121 | # 122 | # 後付(付録)でセクション番号を表示する見出しレベル(未実装) 123 | # post_secnolevel: 1 124 | # 125 | # 部番号を表示する見出しレベル(未実装) 126 | # part_secnolevel: 1 127 | 128 | # 本文中に目次ページを作成するか。省略した場合はnull (作成しない) 129 | toc: true 130 | 131 | # EPUB2標準の目次(NCX)以外に物理目次ファイルを作成するか。省略した場合はnull (作成しない) 132 | # ePUB3においてはこの設定によらず必ず作成される 133 | # mytoc: true 134 | 135 | # 表紙にするHTMLファイル。ファイル名を指定すると表紙として入る 136 | # cover: null 137 | # 138 | # 表紙に配置し、書籍の影絵にも利用する画像ファイル。省略した場合はnull (画像を使わない)。画像ディレクトリ内に置いてもディレクトリ名は不要(例: cover.jpg) 139 | # coverimage: cover.png 140 | # 141 | # 表紙の後に大扉ページを作成するか。省略した場合はnull (作成しない) 142 | titlepage: true 143 | # 144 | # 自動生成される大扉ページを上書きするファイル。ファイル名を指定すると大扉として入る 145 | # titlefile: null 146 | # 147 | # 原書大扉ページにするHTMLファイル。ファイル名を指定すると原書大扉として入る 148 | # originaltitlefile: null 149 | # 150 | # 権利表記ページファイル。ファイル名を指定すると権利表記として入る 151 | # creditfile: null 152 | 153 | # 奥付を作成するか。デフォルトでは作成されない。trueを指定するとデフォルトの奥付、ファイル名を指定するとそれがcolophon.htmlとしてコピーされる 154 | colophon: true 155 | 156 | # 裏表紙ファイル (画像はcoversまたはimagesに配置する)。ファイル名を指定すると裏表紙として入る 157 | # backcover: null 158 | 159 | # プロフィールページファイル。ファイル名を指定すると著者紹介として入る 160 | # profile: null 161 | # プロフィールページの目次上の見出し 162 | # profiletitle: 著者紹介 163 | 164 | # 広告ファイル。ファイル名を指定すると広告として入る 165 | # advfile: null 166 | 167 | # 取り込む画像が格納されているディレクトリ。省略した場合は以下 168 | # imagedir: images 169 | 170 | # 取り込むフォントが格納されているディレクトリ。省略した場合は以下 171 | # fontdir: fonts 172 | 173 | # imagedir内から取り込まれる対象となるファイル拡張子。省略した場合は以下 174 | # image_ext: ["png", "gif", "jpg", "jpeg", "svg", "ttf", "woff", "otf"] 175 | 176 | # fontdir内から取り込まれる対象となるファイル拡張子。省略した場合は以下 177 | # font_ext: ["ttf", "woff", "otf"] 178 | 179 | # ソースコードハイライトを利用する (pygmentsには外部gemが必要) 180 | # highlight: 181 | # html: "rouge" 182 | # html: "pygments" 183 | # latex: "listings" 184 | 185 | # カタログファイル名を指定する 186 | # catalogfile: catalog.yml 187 | 188 | # 1ページの行数文字数と1kbごとのページ数を用紙サイズで指定する(A5 or B5)。 189 | page_metric: B5 190 | # 191 | # あるいは、配列で指定することもできる 192 | # 各数字の意味は、順にリストの行数、リストの1行字数、テキストの行数、テキストの1行字数、1kバイト毎のページ数 193 | # page_metric: [40,80,40,80,2] 194 | 195 | # ページ送りの送り方向、page-progression-directionの値("ltr"|"rtl"|"default") 196 | direction: "ltr" 197 | 198 | # EPUBのOPFへの固有の追加ルール 199 | # 要素に追加する名前空間 200 | # opf_prefix: {ebpaj: "http://www.ebpaj.jp/"} 201 | # 追加する要素のプロパティとその値 202 | # opf_meta: {"ebpaj:guide-version": "1.1.3"} 203 | 204 | # 以下のパラメータを有効にするときには、 205 | # epubmaker: 206 | # パラメータ: 値 207 | # パラメータ: 値 208 | # ... 209 | # という構成にする必要がある(インデントさせる) 210 | 211 | epubmaker: 212 | # HTMLファイルの拡張子 213 | htmlext: xhtml 214 | # 215 | # 目次を要素の階層表現にしない。省略した場合(null)は階層化する。 216 | # 特に部扉が入るなどの理由で、構成によっては階層化目次でepubcheckに 217 | # パスしない目次ができるが、そのようなときにはこれをtrueにする 218 | # flattoc: null 219 | # 220 | # 目次のインデントレベルをスペース文字で表現する(flattocがtrueのときのみ) 221 | # flattocindent: true 222 | # 223 | # NCX目次の見出しレベルごとの飾り(配列で設定)。EPUB3ではNCXは作られない 224 | # ncxindent: 225 | #- 226 | #- - 227 | # フックは、各段階で介入したいときのプログラムを指定する。自動で適切な引数が渡される 228 | # プログラムには実行権限が必要 229 | # ファイル変換処理の前に実行するプログラム。スタイルシートのコンパイルをしたいときなどに利用する。 230 | # 渡される引数1=作業用展開ディレクトリ 231 | # hook_beforeprocess: null 232 | # 233 | # 前付の作成後に実行するプログラム。作業用展開ディレクトリにある目次ファイル(toc-html.txt)を操作したいときなどに利用する。 234 | # 渡される引数1=作業用展開ディレクトリ 235 | # hook_afterfrontmatter: null 236 | # 237 | # 本文の変換後に実行するプログラム。作業用展開ディレクトリにある目次ファイル(toc-html.txt)を操作したいときなどに利用する。 238 | # 渡される引数1=作業用展開ディレクトリ 239 | # hook_afterbody: null 240 | # 241 | # 後付の作成後に実行するプログラム。作業用展開ディレクトリにある目次ファイル(toc-html.txt)を操作したいときなどに利用する。 242 | # 渡される引数1=作業用展開ディレクトリ 243 | # hook_afterbackmatter: null 244 | # 245 | # 画像およびフォントをコピーした後に実行するプログラム。別の画像やフォントを追加したいときなどに利用する。 246 | # 渡される引数1=作業用展開ディレクトリ 247 | # hook_aftercopyimage: null 248 | # 249 | # ePUB zipアーカイブ直前に実行するプログラム。メタ情報などを加工したいときなどに利用する。 250 | # 渡される引数1=ePUB準備ディレクトリ 251 | # hook_prepack: null 252 | # 253 | # 変換したHTMLファイルおよびCSSを解析して厳密に使用している画像ファイルだけを取り込むか。デフォルトはnull(imagesディレクトリすべてを取り込む) 254 | # なお、フォント、カバー、広告についてはこの設定によらずディレクトリ内のものがすべて取り込まれる 255 | # verify_target_images: null 256 | # 257 | # verify_target_imagesがtrueの状態において、解析で発見されなくても強制的に取り込むファイルの相対パスの配列 258 | # force_include_images: [] 259 | # 260 | # Re:VIEWファイル名を使わず、前付にpre01,pre02...、本文にchap01,chap02l...、後付にpost01,post02...という名前付けルールにするか 261 | # rename_for_legacy: null 262 | # 263 | # ePUBアーカイブの非圧縮実行 264 | # zip_stage1: "zip -0Xq" 265 | # 266 | # ePUBアーカイブの圧縮実行 267 | # zip_stage2: "zip -Xr9Dq" 268 | # 269 | # ePUBアーカイブに追加するパス(デフォルトはmimetype、META-INF、OEBPS) 270 | # zip_addpath: null 271 | # 272 | # EPUBで表紙をコンテンツに含めるか。デフォルトでは作成されない。yesにするとiBooks等でも最初に表紙が表示されるようになる 273 | # cover_linear: null 274 | # 275 | # @タグでの外部リンクを禁止し、地の文にする(falseで禁止する) 276 | # externallink: true 277 | # 278 | # epubmaker:階層を使うものはここまで 279 | 280 | # LaTeX用のスタイルファイル(styディレクトリ以下に置くこと) 281 | # tatsumacroは、電子書籍版の制作に利用する 282 | # texstyle: tatsumacro 283 | # 変更する 284 | texstyle: techbooster-doujin 285 | # 286 | # LaTeX用のdocumentclassを指定する 287 | # texdocumentclass: ["jsbook", "oneside,14pt,uplatex"] 288 | texdocumentclass: ["jsbook", "b5j,oneside,openany,uplatex"] 289 | # texdocumentclass: ["jsbook", "a5j,twoside,openany,uplatex,9pt"] 290 | # 291 | # LaTeX用のコマンドを指定する 292 | # texcommand: "uplatex" 293 | # 294 | # LaTeXのコマンドに渡すオプションを指定する 295 | # texoptions: null 296 | # 297 | # LaTeX用のdvi変換コマンドを指定する(dvipdfmx) 298 | # dvicommand: "dvipdfmx" 299 | # 300 | # LaTeX用のdvi変換コマンドのオプションを指定する 301 | # dvioptions: "-d 5" 302 | 303 | # 以下のパラメータを有効にするときには、 304 | # pdfmaker: 305 | # パラメータ: 値 306 | # パラメータ: 値 307 | # ... 308 | # という構成にする必要がある(インデントさせる) 309 | # 310 | pdfmaker: 311 | # 312 | # TeXコンパイル前に実行するプログラム。変換後のTeXソースを調整したいときに使用する。 313 | # 渡される引数1=作業用展開ディレクトリ、引数2=呼び出しを実行したディレクトリ 314 | # hook_beforetexcompile: null 315 | # 316 | # TeXコンパイル後に実行するプログラム。索引作業をして再度コンパイルしたいときなどに使用する。 317 | # 渡される引数1=作業用展開ディレクトリ、引数2=呼び出しを実行したディレクトリ 318 | # hook_aftertexcompile: null 319 | # 320 | # PDF(book.pdf)作成後に実行するプログラム。PDFに加工を施したいときに使用する。 321 | # 渡される引数1=作業用展開ディレクトリ、引数2=呼び出しを実行したディレクトリ 322 | # hook_afterdvipdf: null 323 | # 324 | # 画像のscale=X.Xという指定を画像拡大縮小率からページ最大幅の相対倍率に変換します。 325 | # image_scale2width: true 326 | # 327 | # 奥付を作成するか。trueを指定するとデフォルトの奥付、ファイル名を指定するとそれがcolophon.htmlとしてコピーされる 328 | colophon: true 329 | # pdfmaker:階層を使うものはここまで 330 | 331 | # 以下のパラメータを有効にするときには、 332 | # webmaker: 333 | # パラメータ: 値 334 | # パラメータ: 値 335 | # ... 336 | # という構成にする必要がある(インデントさせる) 337 | # 338 | webmaker: 339 | stylesheet: ["style.css","style-web.css"] 340 | -------------------------------------------------------------------------------- /articles/editor.re: -------------------------------------------------------------------------------- 1 | = 作者一覧 2 | 3 | == もふもふ / @froakie0021 4 | 5 | 人間、原稿をするためには適度な高さの机（今はこたつです）・座椅子（最近はこたつ用のソファが売られています）・そして人間の監視が必要だということがわかりました。 6 | 7 | == ねこちゃん 8 | 9 | おこたでぬくぬくしている。 -------------------------------------------------------------------------------- /articles/end.re: -------------------------------------------------------------------------------- 1 | = おわりに 2 | 3 | 私が本格的に技術同人誌を書き始めたのは、2017年4月の技術書典2からでした。イベントを重ねるごとに、技術同人誌界隈は急速に規模が拡大した印象があります。 4 | その中でどうしても目立つのは、元から実績を持っている「すごい人」の書いた同人誌です。 5 | それは百歩譲ってまあいいでしょう。 6 | しかし、「すごい人のように書けないから」「自分はできることもないし」「文章書くのは苦手だし」と、技術同人誌を書いてみたいのに諦めてしまう人も出てきているように思います。 7 | 8 | 私は情報学専攻の大学を卒業していません。2019年4月で社会人5年目になりましたが、自信が持てる技術ジャンルもありません。@{advent} 9 | 技術同人誌を書き始めたのは、そのときたまたま使った技術で困ったことがあるからです。 10 | 祭りに参加してわいわいするのが好きなので、祭りに参加できるように普段技術のネタを探しているような人間です。 11 | 12 | //footnote[advent][参考：転職したけどもやもやしているから話を聞いてほしい（りまりま団の本拠地より）] 13 | 14 | このように特筆すべき実績がない人でも、技術同人誌を書き続けられるのです。同人誌は好きなことが好きなように書けるので面白いのです。 15 | 面白そうと思っているけれど、文章に自信がないからと言って避けるのはもったいないことです。 16 | 17 | たらればさんが書いた『あの高円寺のユニットバスで、何もかもを欲しがっていた』（https://mooom.chintai.mynavi.jp/koneta/story）というエッセイがあります。 18 | その中に、技術同人誌を書く私をそのまま表現したような文章があります。 19 | 20 | //quote{ 21 | 1文字書くごとに、「自分は本気を出せば、すばらしい文章を書ける、という可能性」が減ってゆきます。 22 | 書かないままでいれば浸れていた甘い幻想に抗って、少しずつ自分の可能性を減らして、 23 | 代わりに「いまの自分」をひとかけらずつ引き受けてゆく。 24 | //} 25 | 26 | 頭の中では、雄大で厚みのある知見の塊が広がっているのです。それが、いざ原稿を書こうとすると何もできない。もどかしい思いばかりが募ります。 27 | 知識や経験が不足しているのはもちろんですが、文章技術もまた、足りていないのです。 28 | 29 | そんなちょっぴり苦い現実、自分のしょうもないプライドと向き合いながら書く技術同人誌。イベント当日に刷り上がった本に向き合うとき、やりきったなあ、と思うのです。 30 | イベント直後は恥ずかしくて見返せません。しかし、その技術をまた触るときに読み返すと「知りたかったことが書いてあるなあ」などと冷静に振り返れるものです。 31 | このちょっとした「やりきった」感が、技術同人誌を書くことの面白さなのだと思います。 32 | 33 | この本を読んだ人が、原稿を書こうとすると手が止まって諦める状態を回避できたのであれば大変嬉しいです。 34 | 35 | あなたの書く技術同人誌、とても楽しみにしています。 -------------------------------------------------------------------------------- /articles/epub_style.scss: -------------------------------------------------------------------------------- 1 | @charset "utf-8"; 2 | /* Tatujin-Publishing */ 3 | /* Style sheet for epub */ 4 | /* Ver.0.8b1 */ 5 | 6 | /* 7 | Scale & Rhythm 8 | line-height 1.6 9 | 16px = 1em 10 | x:p:h1:h2:h3 = 12px:14px:16px:24px:30px 11 | */ 12 | * { 13 | } 14 | body { 15 | margin: 0; 16 | padding: 0; 17 | font-size: 1em; 18 | line-height:1.6; 19 | font-family: "ShinGoPro-Regular","ShinGo-Regular", sans-serif; 20 | /* 21 | word-break: normal; 22 | -webkit-line-break: after-white-space; 23 | */ 24 | } 25 | p, ul, ol, dl, pre, table { 26 | font-family: "ShinGo Regular","ShinGo R","新ゴR","新ゴ R", sans-serif; 27 | font-size: 0.875em; 28 | } 29 | /* Heading */ 30 | h1 { 31 | margin: 0 0 3em; 32 | padding: 0.5em 0 0; 33 | border-top: 14px #326450 solid; 34 | text-align: left; 35 | font-size: 1.875em; 36 | font-weight: bold; 37 | } 38 | h2 { 39 | margin: 3em 0 0.5em; 40 | padding: 0.5em 0 0; 41 | border-top: 2px #326450 solid; 42 | text-align: left; 43 | font-size: 1.5em; 44 | font-weight: bold; 45 | } 46 | h3 { 47 | margin: 3em 0 0.5em; 48 | padding: 0; 49 | text-align: left; 50 | font-size: 1em; 51 | font-weight: bold; 52 | } 53 | h4, h5, h6 { 54 | margin:0.7em 0; 55 | padding: 0; 56 | text-align: left; 57 | line-height: 1.6; 58 | font-weight: bold; 59 | } 60 | /* Paragraph */ 61 | p { 62 | margin:0.7em 0; 63 | padding: 0; 64 | text-align: left; 65 | text-indent: 1em; 66 | line-height: 1.6; 67 | } 68 | div.lead p { 69 | color: #666; 70 | line-height: 1.6; 71 | font-size: 0.75em; 72 | } 73 | /* List */ 74 | ul, ol { 75 | margin: 2em 0 2em 2em; 76 | padding: 0; 77 | list-style-position: outside; 78 | } 79 | ul > li, 80 | ol > li { 81 | margin: 0 0 0.7em 0; 82 | padding: 0; 83 | line-height: 1.6; 84 | } 85 | dl { 86 | margin: 2em 0; 87 | padding: 0; 88 | } 89 | dt { 90 | margin: 0; 91 | padding: 0; 92 | font-weight: bold; 93 | } 94 | dd { 95 | margin: 0 0 1em 2em; 96 | padding: 0; 97 | line-height: 1.6; 98 | } 99 | /* Table 100 | p.tablecaptionではなく 101 | table caption {}を使う方が良いかも？ 102 | */ 103 | table { 104 | margin: 0 auto 2em auto; 105 | border-collapse: collapse; 106 | } 107 | table tr th { 108 | background-color: #eee; 109 | border:1px #aaa solid; 110 | font-size: 0.75em; 111 | font-weight: normal; 112 | } 113 | table tr td { 114 | padding: 0.3em; 115 | border:1px #aaa solid; 116 | font-size: 0.75em; 117 | } 118 | p.tablecaption, table caption { 119 | margin: 0; 120 | color: #666; 121 | font-size: 0.75em; 122 | font-weight: bold; 123 | text-indent: 0; 124 | } 125 | /* Quote */ 126 | blockquote { 127 | margin: 2em 0 2em 2em; 128 | padding: 0.3em 1em; 129 | border: 1px #aaa solid; 130 | } 131 | /* Column Block */ 132 | div.column { 133 | margin: 2em 0 2em 2em; 134 | padding: 0.3em 1em; 135 | background-color: #eee; 136 | -webkit-border-radius: 0.7em; 137 | } 138 | div.column *{ 139 | margin:0.7em 0; 140 | } 141 | div.column ul, 142 | div.column ol { 143 | list-style-position: inside; 144 | } 145 | /* Code Block */ 146 | /* 147 | ※シンプルにできるかも 148 | div.code {} 149 | div.code pre.list, 150 | div.code pre.cmd {} 151 | div.code p.caption {} 152 | */ 153 | div.code, div.caption-code, div.source-code, div.emlist-code, div.emlistnum-code { 154 | margin: 1em 0 2em 2em; 155 | padding: 0; 156 | } 157 | pre.emlist, pre.source, pre.list { 158 | margin: 0; 159 | padding: 5px; 160 | border: 1px #aaa solid; 161 | } 162 | div p.caption { 163 | margin: 0; 164 | color: #666; 165 | font-size: 0.75em; 166 | font-weight: bold; 167 | } 168 | div.cmd-code pre.cmd { 169 | margin: 0; 170 | padding: 5px; 171 | color: #ccc; 172 | font-weight: bold; 173 | background-color: #444; 174 | -webkit-border-radius: 0.5em; 175 | } 176 | pre.cmd, pre.emlist, pre.list, pre.source { 177 | white-space: pre-wrap; 178 | } 179 | 180 | /* Image Block */ 181 | /* div.image p.caption {} 182 | ※captionをそろえた方が良いかも？*/ 183 | div.image { 184 | margin: 2em auto; 185 | padding: 0; 186 | } 187 | div.image img { 188 | margin: 0 auto; 189 | padding: 0; 190 | display: block; 191 | } 192 | div.image p.caption { 193 | margin: 0 auto; 194 | text-align: center; 195 | color: #666; 196 | font-size: 0.75em; 197 | font-weight: bold; 198 | text-indent: 0; 199 | } 200 | /* Footnote Block */ 201 | /* p.footnoteはいらないかも？ */ 202 | div.footnote { 203 | } 204 | div.footnote p.footnote { 205 | color: #666; 206 | line-height: 1.6; 207 | font-size: 0.75em; 208 | text-indent: 0; 209 | } 210 | /* Colophon */ 211 | div.colophon { 212 | margin: 3em auto; 213 | } 214 | div.colophon p { 215 | text-indent: 0; 216 | } 217 | div.colophon p.title { 218 | font-size: 1.5em; 219 | } 220 | div.colophon table { 221 | margin: 1em 0 2em; 222 | border: none; 223 | } 224 | div.colophon table tr th { 225 | background-color: #fff; 226 | font-size: 1.2em; 227 | font-weight: normal; 228 | border: none; 229 | } 230 | div.colophon table tr td { 231 | font-size: 1.2em; 232 | font-weight: normal; 233 | border: none; 234 | } 235 | 236 | /* Inline */ 237 | a[href], 238 | a:link, 239 | a:visited { 240 | border-bottom: 1px dotted #531084; 241 | text-decoration: none; 242 | } 243 | b { 244 | font-weight: bold; 245 | } 246 | strong { 247 | font-weight: bold; 248 | } 249 | em { 250 | font-style: italic; 251 | } 252 | 253 | /** 254 | * from EBPAJ EPUB 3 File Creation Guide sample style 255 | * 256 | * cf. http://ebpaj.jp/counsel/guide 257 | */ 258 | 259 | /* image width definition(pacentage) */ 260 | .width-010per { width: 10%; } 261 | .width-020per { width: 20%; } 262 | .width-025per { width: 25%; } 263 | .width-030per { width: 30%; } 264 | .width-033per { width: 33%; } 265 | .width-040per { width: 40%; } 266 | .width-050per { width: 50%; } 267 | .width-060per { width: 60%; } 268 | .width-067per { width: 67%; } 269 | .width-070per { width: 70%; } 270 | .width-075per { width: 75%; } 271 | .width-080per { width: 80%; } 272 | .width-090per { width: 90%; } 273 | .width-100per { width: 100%; } 274 | -------------------------------------------------------------------------------- /articles/images/improve-text/add.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MofuMofu2/TB6-technical-writing-technic/a83c61860b990cf7103b4efdacc932e8d4e66d7f/articles/images/improve-text/add.png -------------------------------------------------------------------------------- /articles/images/improve-text/all-gothic.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MofuMofu2/TB6-technical-writing-technic/a83c61860b990cf7103b4efdacc932e8d4e66d7f/articles/images/improve-text/all-gothic.png -------------------------------------------------------------------------------- /articles/images/improve-text/all-minchyo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MofuMofu2/TB6-technical-writing-technic/a83c61860b990cf7103b4efdacc932e8d4e66d7f/articles/images/improve-text/all-minchyo.png -------------------------------------------------------------------------------- /articles/images/improve-text/and.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MofuMofu2/TB6-technical-writing-technic/a83c61860b990cf7103b4efdacc932e8d4e66d7f/articles/images/improve-text/and.png -------------------------------------------------------------------------------- /articles/images/improve-text/because.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MofuMofu2/TB6-technical-writing-technic/a83c61860b990cf7103b4efdacc932e8d4e66d7f/articles/images/improve-text/because.png -------------------------------------------------------------------------------- /articles/images/improve-text/but.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MofuMofu2/TB6-technical-writing-technic/a83c61860b990cf7103b4efdacc932e8d4e66d7f/articles/images/improve-text/but.png -------------------------------------------------------------------------------- /articles/images/improve-text/exception.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MofuMofu2/TB6-technical-writing-technic/a83c61860b990cf7103b4efdacc932e8d4e66d7f/articles/images/improve-text/exception.png -------------------------------------------------------------------------------- /articles/images/improve-text/gothic-and-minchyo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MofuMofu2/TB6-technical-writing-technic/a83c61860b990cf7103b4efdacc932e8d4e66d7f/articles/images/improve-text/gothic-and-minchyo.png -------------------------------------------------------------------------------- /articles/images/improve-text/kibana-graph.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MofuMofu2/TB6-technical-writing-technic/a83c61860b990cf7103b4efdacc932e8d4e66d7f/articles/images/improve-text/kibana-graph.png -------------------------------------------------------------------------------- /articles/images/improve-text/or.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MofuMofu2/TB6-technical-writing-technic/a83c61860b990cf7103b4efdacc932e8d4e66d7f/articles/images/improve-text/or.png -------------------------------------------------------------------------------- /articles/images/improve-text/other_words.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MofuMofu2/TB6-technical-writing-technic/a83c61860b990cf7103b4efdacc932e8d4e66d7f/articles/images/improve-text/other_words.png -------------------------------------------------------------------------------- /articles/images/improve-text/unexpected.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MofuMofu2/TB6-technical-writing-technic/a83c61860b990cf7103b4efdacc932e8d4e66d7f/articles/images/improve-text/unexpected.png -------------------------------------------------------------------------------- /articles/images/improve-text/unity_notation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MofuMofu2/TB6-technical-writing-technic/a83c61860b990cf7103b4efdacc932e8d4e66d7f/articles/images/improve-text/unity_notation.png -------------------------------------------------------------------------------- /articles/images/improve-text/unity_notation_google_doc.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MofuMofu2/TB6-technical-writing-technic/a83c61860b990cf7103b4efdacc932e8d4e66d7f/articles/images/improve-text/unity_notation_google_doc.png -------------------------------------------------------------------------------- /articles/images/introduction/slack.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MofuMofu2/TB6-technical-writing-technic/a83c61860b990cf7103b4efdacc932e8d4e66d7f/articles/images/introduction/slack.png -------------------------------------------------------------------------------- /articles/images/think-toc/tools.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MofuMofu2/TB6-technical-writing-technic/a83c61860b990cf7103b4efdacc932e8d4e66d7f/articles/images/think-toc/tools.png -------------------------------------------------------------------------------- /articles/improve-text.re: -------------------------------------------------------------------------------- 1 | = 推敲してより良い原稿を作成する 2 | 3 | 原稿を一通り書き終わった後は、時間が許す限り推敲を行いましょう。推敲をコトバンクで検索すると、「詩文の字句や文章を十分に吟味して練りなおすこと」と出てきます（参考文献参照）。 4 | 技術同人誌に置ける推敲は、本文や載せるプログラム・図解を十分に吟味して練り直すこと、と言えます。 5 | 6 | 商業誌では、編集者があなたの代わりに推敲を行います。技術系の本の場合、編集者の推敲は日本語表現の修正のみで、技術的な観点でのレビューは外部にお願いする場合が多いようです。 7 | ちなみに、技術的なレビューを外部の誰かに頼んでいる場合、本の著者欄に@{監修}がクレジットされます。ここから、商業の技術書は多くの人が原稿の正しさをチェックしていることがわかります。 8 | 9 | しかし、技術同人誌はあなたが編集者の役割も兼ねています。複数人で執筆している技術同人誌に寄稿する場合、編集担当の誰かに原稿を預けることになります。 10 | ただ、原稿の中身をどのくらい確認してもらえるかはわかりません。編集担当者の方針によっては、あまり校正をかけないこともあるでしょう。 11 | 12 | Twitterなどで呼びかけてレビューを頼めばいいじゃない、と思うかもしれません。しかし、レビューを頼めるかは運次第です。加えて、あなたが望む形のレビューをもらえるかはわかりません。 13 | 最終的な原稿の修正は、あなた自身で行う必要があります。 14 | 15 | あなたは原稿を書くのでもう十分楽しんだので、早く入稿して解放されたいと思っているかもしれません。気持ちはわかりますが、より良い技術同人誌を作るために頑張りましょう。 16 | 17 | == なぜ原稿の推敲は大切なのか？ 18 | 19 | === 伝えたいことが伝わらなくなってしまうから 20 | 21 | なぜ、推敲は大切なのでしょうか？ 22 | 23 | それは、@{わかりやすい文章であればあるほど、あなたが広めたい技術を他人に伝えることができるから}です。推敲しても大して変わらないと思っていますか？では、次の文章を見てください。 24 | 25 | //list[bad-kibana-text][文章例：1]{ 26 | データの内訳に応じて円が分かれていきます。 円を分ける条件を指定しないとデータの総件数が表示されるだけなので、パイを分割する設定を一緒に入れましょう。 27 | //} 28 | 29 | //list[good-kibana-text][文章例：2]{ 30 | 円グラフを作成するための機能です。データの内訳を分析する用途で利用します。設定を変更すれば、円の中央が空いている”ドーナツ型”のグラフを作成することも可能です。 31 | //} 32 | 33 | @{good-kibana-text}は、どちらも@{Kibana}というミドルウェアの@{Pie Chart}機能を説明したものです。 34 | 35 | //image[kibana-graph][Kibanaの画面例]{ 36 | 37 | //} 38 | 39 | 画像の右上にドーナツ型の円がありますね。それがPie Chartのグラフです。Pie Chart機能の詳細は、本題ではないため割愛します。 40 | 41 | 重要なのは、言葉の使い方・文章の並べ方・句読点の多さによって、伝わってくる内容が全く違う点です。 42 | 43 | 例えば、@{bad-kibana-text}を読んだとき「Pie Chartを使うと円グラフが描ける」という意味がすぐ伝わってきたでしょうか。 44 | 「データの内訳を分割する」・「パイを分割する」できそうだ、と受け取ったのではないかと思います。しかし、筆者が伝えたかったのは「Pie Chartを使うと円グラフが描ける」ことです。 45 | パイの分割はその後のページで説明しているため、ここではさほど重要ではなかったのです。筆者の主張と実際の記載に大きな差がありますね。 46 | これでは読者が「著者の主張」を推測しながら本を読み進めることになります。何回も続けば、読者にかかる負担が増えていきます。 47 | 48 | 読者への負担が高い本は、読者にとって「読みにくい本」となってしまいます。はっきり言って、読後感の印象は最悪です。読むのに疲れるからです。 49 | こうなると、あなたの伝えたいことは3割程度しか伝わりません。 50 | 51 | === 読者の読解力が問題なのか 52 | 53 | 「読者の読解力・技術力が足りていないのが悪い」と思われるかもしれません。しかし、そうではありません。 54 | 55 | ここで『20歳の自分に受けさせたい文章講義 (星海社新書)』から、私が1番好きな文を引用します。@{seikai} 56 | 57 | //footnote[seikai][新書なので電子版は存在しません。しかし、内容は一読する価値があります。本の感想や紹介はAmazonのカスタマーレビューを見てください。私は大学生のときにこの本に出会えて本当に良かった、と思っています。] 58 | 59 | //quote{ 60 | 専門書やマニア向けの雑誌などが（一般読者にとって）読みづらいのは、このためだ。出てくる言葉が難しいのではない。読者に甘え、本来やるべき説明を怠っているから、読みづらいのである。 61 | //} 62 | 63 | 言いたいことが「伝わらない」のは読者のせいではありません。本を書いた人の責任である、と古賀さんは言います。さらに「専門性に逃げるのは、書き手の怠慢であり、甘えにすぎないのだ」とも述べています。 64 | 65 | 専門書の位置づけで技術同人誌を書くのであれば、「専門的な観点が多すぎて初心者に伝わらない」のは許されるかもしれません。 66 | ただし、タイトルやキャッチコピーに@{わかりやすい}や、@{初心者の/はじめての}と書くのであれば話は別です。専門書よりも丁寧に、かつ慎重に原稿を書かなければなりません。 67 | 68 | なぜならば、初心者はあなたの行間を読み取ることが難しいからです。前提知識が足りていないため、説明不足な点を自分で補うことができません。 69 | そのため、行間の補足が必要な箇所が多くなると「読みづらい/わかりにくい」という感想を持ちやすいのです。サンプルコードが動作しなければ、もっと印象は悪くなります。 70 | 71 | 本当かなと思うのであれば、試しにAmazonのWebサイトで@{Java 入門書}と検索してみてください。低評価のレビュー文の大半は「説明がわかりにくい」「サンプルコードが動作しない」といったものです。 72 | ひどいものだと、中級者向けの本に「初心者が読んだけどわからなかった」というレビューがついていたりします。 73 | 74 | 対象読者をきちんと定め、誰が見てもわかるように明記する（誤解ないように宣伝する）のは本を作る人がやるべきことです。売れるから、刺さりやすいから、イイねがいっぱいもらえるからといって、安易に初心者向けを謳わない方が良いです。 75 | 76 | 読者というものは勝手なように見えるかもしれません。言いたい放題で理不尽なのは、よくわかります。 77 | しかし、読者はあなたの書いた本からしか情報を取得できません。わからないことは調べて読んでほしい？行間を読んでほしい？技術書に対するAmazonのレビューをみれば、それは幻想だとわかるでしょう。 78 | 読者が本を買って読む目的は、次の2つに集約されます。 79 | 80 | * Web検索では手に入れられない情報を知ること 81 | * 横断的な情報をまとめて取得・管理すること 82 | 83 | 情報を手に入れる目的で本を読む人に、調べ物をしながら本を読むことを期待するのは難しいのです。対抗するためには、クオリティの高い原稿をぶつけるしかありません。 84 | 85 | 読者のためだけではなく、あなたの心を守るために推敲を行いましょう。 86 | 87 | == 推敲する観点（基礎編） 88 | 89 | 普段の生活で推敲をすることはどのくらいありますか？メール文化の中にいれば、書いた文章を推敲する機会があるかもしれません。 90 | Slackなど、チャットを多く利用するのであれば、長文を書くこと自体あまりないかもしれません。 91 | そこで、推敲する観点をまずは押さえましょう。 92 | 93 | 次に示す観点が網羅されていない場合、「この本は読みにくい」印象となってしまいます。本の内容ではなく、文章の読みやすさに関わる観点だからです。 94 | @
{この観点の推敲は一番最初に行いましょう。}後まわしにすると、修正箇所が大量に発生するためです。 95 | 96 | * 本の中で語調・記法は統一されているか 97 | * 接続詞の用法は正しいか 98 | * 句読点の量と位置は適切か 99 | * 一文の長さは40文字以内か 100 | * 段落を切るタイミングは適切か 101 | * 初見の単語には意味の解説があるか 102 | * 助詞の使い方は正しいか 103 | * 同じ言葉を繰り返し利用していないか 104 | 105 | こんなのはできて当たり前じゃないか、と思われるかもしれません。しかし、これらの観点が守られていない技術同人誌は数多く存在します。言い換えると、読みやすい文章を書くだけで1つ抜きん出た技術同人誌を作れるということです。 106 | 107 | 順番に内容を確認していきましょう。 108 | 109 | === 語調・記法は統一されているか 110 | 111 | 技術同人誌の作成期間は、1ヶ月〜2ヶ月となる場合が多いです。複数日にまたがって執筆していると、初期に書いた原稿と終盤間際に書いた原稿で@{技術用語や記述方法（キャメルケース/スネークケースなど）の記載方法が異なる}ことが往々にしてあります。 112 | 技術同人誌は内容に正確性が求められるジャンルの本です。@{本の中で表記は統一しましょう}。複数表記が存在すると、読者は何が正しい表現なのかわからず混乱します。 113 | 特に複数人で1冊の本を執筆している場合、表記が分かれやすいので特に注意しましょう。この複数人執筆で書かれる本は@{合同誌}と呼ばれています。今後は複数人執筆の本を@{合同誌}と表記します。 114 | 合わせて、英数字の表記法も統一するべきです。技術同人誌の場合、@{半角英数字}表記にしましょう。プログラム等を書くときと同じ記述で読みやすくなるためです。 115 | 116 | 記法と合わせて、語調も統一するべきです。統一されていない場合、本が読みづらくなってしまうからです。 117 | 具体的には、次のどちらかから選択します。 118 | 119 | * 「です/ます」などの丁寧語を利用する 120 | * 「だ/である」などの断定語を利用する 121 | 122 | 技術同人誌の場合、「です/ます」などの丁寧語を利用すると良いでしょう。これは、商業本の技術書と同じ語調を利用するためです。 123 | 自分の技術同人誌を商業出版したいと考えている場合、丁寧語にしておくべきです。修正コストが少ない方が、出版社に売り込みやすいです。 124 | 125 | 語調は本全体を通して統一します。合同誌になると、語調がバラバラになりやすいので@{事前にルールを設けておくことを強く推奨します}。 126 | 語調を後から修正するのは、かなり時間がかかります。この修正作業だけで時間と体力を無駄に消耗するため、語調は最初から統一しておくべきです。 127 | 128 | ばらばらでもわかればいいじゃない、と思うかもしれません。実際に悪い例をみてみましょう。@{unity_notation_bad}を見てください。同じミドルウェアの名前が3回出てきます。 129 | 130 | //list[unity_notation_bad][語調・記法が統一されていない例]{ 131 | BeatsはOSにインストールすることで、機器のデータをElasticsearchやlogstashに転送する 132 | 簡易的なデータ収集ツールです。例えばネットワークのパケット情報・Windowsのイベントログ・死活監視の情報などを収集することが 133 | できるため、LogStashでカバーできないような情報を集めてくることができる。 134 | Logstashにログを転送することで、他のログと同じように加工・転送が可能となるため、痒いところに手がとどくツールという位置づけ。 135 | //} 136 | 137 | 3つの表現が出てきました。 138 | 139 | * logstash 140 | * LogStash 141 | * Logstash 142 | 143 | Logstashは、Elasticsearch社製のログ収集・転送ツールです。@{Logstash}と記述するのが正しいのですが、表現が分かれてしまっていると混乱しますよね。 144 | Logstashを知っていれば「Logstashのことを指している」と理解できるでしょう。 145 | しかし、初めてLogstashを知った人は、@{Logstash}と@{LogStash}を別のプロダクトだと思ってしまうかもしれません。 146 | 147 | さらに、@{unity_notation_bad}は語調も統一されておらず、読みやすくはありません。 148 | 149 | そこで、次のように書き換えてみましょう。 150 | 151 | //list[unity_notation_good][語調・記法が統一されている例]{ 152 | BeatsはOSにインストールすることで、機器のデータをElasticsearchやLogstashに転送する 153 | 簡易的なデータ収集ツールです。例えばネットワークのパケット情報・Windowsのイベントログ・死活監視の情報などを収集することが 154 | できるため、Logstashでカバーできないような情報を集めてくることができます。 155 | Logstashにログを転送することで、他のログと同じように加工・転送が可能となるため、痒いところに手がとどくツールという位置づけです。 156 | //} 157 | 158 | これで、@{Logstash}という表現に統一できました。 159 | 160 | 目視で記法が統一されているか確認することは、とても難しい作業です。エディタ・ワープロソフトの@{検索・置換}機能で一括置換を行うと良いでしょう。 161 | 162 | 例えば、Visual Studio Codeであれば、@{Command（Ctl） + F}キーで検索・置換機能を起動できます。 163 | @{unity_notation}を見るとわかる通り、表記揺れがある場合でも文字列検索を行えます。ここで一括置換を行えば、表記ゆれを解消できます。 164 | 165 | エディタの一種Atomも、同じような置換機能を持っています。テキストで原稿を作成する場合、エディタの力で用語を統一しましょう。 166 | 167 | //image[unity_notation][Visual Studio Codeで置換を行なっている様子]{ 168 | //} 169 | 170 | WordやGoogle Documentsなどのワープロソフトを利用する場合も、同じように検索・置換を行えます。 171 | Wordの場合は@{Command（Ctl） + H}、Google Documentsの場合は@{Command（Ctl） + F}で検索・置換を行います。 172 | こちらも積極的に活用していきましょう。 173 | 174 | //image[unity_notation_google_doc][Google Documentsで置換を行なっている様子]{ 175 | 176 | //} 177 | 178 | === 接続詞の用法は正しいか 179 | 180 | @{接続詞}という言葉を聞いたことはありますか？接続詞とは、文と文とをつなぐ役割を持つ品詞の一種です。 181 | 新聞内で利用する日本語の書き方を指南している『記者ハンドブック』内（p108）では、接続詞の種類として次の単語が挙げられています。 182 | 183 | * あるいは 184 | * かつ 185 | * しかし 186 | * しかも 187 | * すなわち 188 | * それ故 189 | * それとも 190 | * ただし 191 | * ところが 192 | * ところで 193 | * ないし 194 | * なお 195 | * ならびに 196 | * また 197 | * または 198 | * もしくは 199 | * 持って 200 | * および 201 | * 従って 202 | * 併せて 203 | 204 | 数が多いので、利用する機会が多い接続詞に絞ります。 205 | 206 | * しかし 207 | ** 前の文章の内容を打ち消すときに利用する 208 | 209 | //image[but][しかしを利用する文章例]{ 210 | 211 | //} 212 | 213 | * すなわち 214 | ** 前に述べた言葉を別の意味で説明し直すときに利用する 215 | 216 | //image[other_words][すなわちを利用する文章例]{ 217 | 218 | //} 219 | 220 | * それ故 221 | ** 前の文章の理由や根拠を述べるときに記載する（だから・そのためも同じ意味） 222 | ** 最近はひらがな表記が一般的である 223 | ** "だから"は多用すると子供っぽい印象となるので注意が必要 224 | 225 | //image[because][しかしを利用する文章例]{ 226 | 227 | //} 228 | 229 | * ただし 230 | ** 前の文章について条件や例外をつけ足すときに利用する 231 | 232 | //image[exception][ただしを利用する文章例]{ 233 | 234 | //} 235 | 236 | * ところが 237 | ** 前の文章から予想できない事項について記載するときに利用する 238 | 239 | //image[unexpected][ところがを利用する文章例]{ 240 | 241 | //} 242 | 243 | * また 244 | ** 前の文章と同じ事項を重ねて表現するときに利用する 245 | 246 | //image[add][また を利用する文章例]{ 247 | 248 | //} 249 | 250 | * および 251 | ** 前の文章 AND 後ろの文章 と表現するときに利用する 252 | 253 | //image[and][およびを利用する文章例]{ 254 | 255 | //} 256 | 257 | * または 258 | ** 前の文章 OR 後ろの文章 と表現するときに利用する 259 | 260 | //image[or][またはを利用する文章例]{ 261 | 262 | //} 263 | 264 | 接続詞は用法を誤ると@{意味が正しく伝わりません}。接続詞を意識すると、文章の意味を正しく伝えるだけでなく、文章の論理構成を検討しつつ本文を記載できます。 265 | 文章を書くことに慣れていないうちは、接続詞を入れながら文章を記載しましょう。推敲中にくどいと思った時点で削れば良いのです。 266 | 267 | === 句読点の量と位置 268 | 269 | 句読点（くとうてん）とは、文章を区切るための文字のことです。句点は@{"。"}、読点は@{"、"}のことです。 270 | 271 | 句点は文章の最後につけます。ただし、かっこ（@{例：「」・（）}）内の文章の場合、基本的には句点をつけません。場合によってはつけることもあります。 272 | 『記者ハンドブック』p115に詳しい記載がありますが、技術同人誌を書く上では@{かっこを使用しない文の最後に必ず句点をつける}、と覚えておけば良いでしょう。 273 | 274 | 句点のルールは、多くの技術同人誌で守られているようです。しかし、問題は読点です。 275 | 読点の付け方で著者の文章を書く力を測れると言えます。読点の付け方が悪いせいで、内容が面白くても「読みづらい」技術同人誌が多いのです。 276 | 277 | 『記者ハンドブック』では、読点に関して次のような説明がされています。 278 | 279 | //quote{ 280 | 読点は文章を読みやすくしたり、記事内容を正しく伝えるために打つ。息の切れ目や読の間（なるべく20文字以内）を考えて付ける。 281 | //} 282 | 283 | @{息の切れ目や読の間（なるべく20文字以内）を考えて付ける。}とありました。@{息の切れ目}を@{文節}と勘違いしてやたらと読点を多用する人がいます。 284 | 文節とは、文を実際の言語として不自然でない程度に区切った最小の単位のことです。読点が多すぎる人は、助詞（てにをは）が出てくるたびに読点を打ちます。@{平成の終わりにおいて、読点を打ちまくるのはモダンな書き方ではありません。絶対にやめましょう。}@{30} 285 | 286 | //footnote[30][独断と偏見ですが、30代以上の男性は文中で読点を多用する人が多いです。そういう流行だったのでしょうか。] 287 | 288 | 別に読点が多くたっていいじゃない、と思われるかもしれません。次の例文を読んでください。 289 | 290 | //list[comma-bad][読点が多すぎる例]{ 291 | Windowsの場合、zipファイルを、利用する以外に、インストールする方法は、存在しません。 292 | 一方、Macは、brewコマンドを用いて、インストールすることもできますが、 293 | Elastic公式ではサポートされていないようなので、今回は、インストール方法から、対象外としています。 294 | //} 295 | 296 | 息切れするような文章です。この調子で60〜80ページ読み続けるのはしんどいですよね。 297 | @{comma-bad}はかなり極端な例です。しかし、このような文章を書いている人は存在します。読点が多すぎる人は、頭の中の言葉と文章が直結している傾向があります。 298 | 最初に書く文章はそれでも良いのですが、@{推敲時に必ず読点の量を削りましょう}。大変読みづらいことがお分かりいただけたかと思います。 299 | 300 | では、読点を書かなければ良いのでしょうか？今度は読点が存在しない文章をみてみましょう。 301 | 302 | //list[comma-none][読点がまったく存在しない例]{ 303 | Windowsの場合zipファイルを利用する以外にインストールする方法は存在しません。 304 | 一方Macはbrewコマンドを用いてインストールすることもできますが 305 | Elastic公式ではサポートされていないようなので今回はインストール方法から対象外としています。 306 | //} 307 | 308 | どこで文章が切れるのか全くわかりません。ここでは2文目に注目してください。@{Mac}が文中の主語になっています。このままでは、文章内の動詞は@{対象外としています}となってしまいます。 309 | Macが対象外としています、は少しおかしいですよね。ここで述べたいのは「Macのインストール方法は、今回は対象外とする」ことです。「Macは対象外としている」ではありません。 310 | 311 | 読点を打つ場所によって、日本語の意味が変わってきてしまいます。しかし、多すぎてもくどいです。次の事項を守り、文脈に注意を払いながら読点を打ちましょう。 312 | 313 | * 読点は20文字を目安に打つ 314 | * 文章を切りたい箇所に打つ 315 | * 1文に読点を打つ数は、最大2回までとする 316 | 317 | 慣れないうちは、1文に1回だけ読点を打つようにしましょう。こうすることによって、読点を打ちすぎることは無くなります。適切な位置に読点を打つ練習にもなります。 318 | どこに読点を打つべきか考えていると、文章がわかりにくくなっていることに気づける確率も上がります。 319 | 320 | //list[connma-good][読点を適切に打った例]{ 321 | Windowsの場合、インストーラーはzipファイル形式のみ提供されています。 322 | 一方Macの場合、zipファイルまたはbrewコマンドを利用できます。 323 | ただしbrewコマンドを用いた方法は、Elastic公式ではサポートされていません。 324 | よって、この本ではbrewコマンドを用いたインストール方法を扱いません。 325 | //} 326 | 327 | 1文目は、読点を打ちづらかったため文章の構成から書き換えました。以降の文章は1文に1回読点を打つルールを適用するには長すぎるため、文を分割しました。 328 | 私は読点を接続詞の後ろ、または主語の後ろに入れるようにしています。日本語は主語がわかりづらい言語だからです。主語をはっきりすることで、技術の動作や役割を簡潔に説明できると考えています。 329 | 330 | === 一文の長さは40文字以内か 331 | 332 | 文章の頭から句点までは、40文字に納めるようにしましょう。最悪でも45文字以内に納めます。文章の可読性が下がるだけでなく、1文の中に逆説が入ることで意味不明な文になるなどの弊害が発生するためです。 333 | 334 | 文章が長すぎる例を示します。 335 | 336 | //list[long-text][1文が長すぎる例]{ 337 | Timelionでは独自の関数を指定すると、複数の要素を描画することができますが、 338 | Visualizeでは1つの画面には1種類のグラフしか描画することはできません。 339 | （81文字） 340 | しかし、Timelionでは1つの画面に線グラフと棒グラフを両立させることができますので 341 | 2つのグラフを同じ画面で比較したいときに便利です。 342 | （70文字） 343 | //} 344 | 345 | @{long-text}の例は、意味は通じる文章です。そこまで「読みづらい」と思わないかもしれません。しかし、これはコードブロック内でわざと折り返しているからです。組版した形式で記載してみます。 346 | 347 | 348 | Timelionでは独自の関数を指定すると、複数の要素を描画することができますが、Visualizeでは1つの画面には1種類のグラフしか描画することはできません。 349 | しかし、Timelionでは1つの画面に線グラフと棒グラフを両立させることができますので2つのグラフを同じ画面で比較したいときに便利です。 350 | 　 351 | 352 | 今度はどうでしょう。印象が変わったのではないかと思います。では、1文が40文字以内に納まるように文章を書き換えます。 353 | 354 | //list[short-text][1文を40文字以内に納めた例]{ 355 | Timelionでは独自の関数を指定すると、複数の要素を描画できます。 356 | （35文字） 357 | しかし、Visualizeでは1つの画面には1種類のグラフしか描画できません。 358 | （39文字） 359 | Timelionは、異なる種類のグラフを同時に比較したいときに便利です。 360 | （36文字） 361 | //} 362 | 363 | 文章を見直すと、「Timelionでは独自の関数を指定すると、複数の要素を描画することができます」「Timelionでは1つの画面に線グラフと棒グラフを両立させることができます」 364 | は、内容が重複しているため削りました。では、組版するとどうなるでしょうか。 365 | 366 | 367 | Timelionでは独自の関数を指定すると、複数の要素を描画できます。 368 | しかし、Visualizeでは1つの画面には1種類のグラフしか描画できません。 369 | Timelionは、異なる種類のグラフを同時に比較したいときに便利です。 370 | 　 371 | 372 | 先ほどに比べ、かなり読みやすくなりました。単純なルールですが、一段とわかりやすい文章になります。 373 | 374 | === 段落を切るタイミングは適切か 375 | 376 | 段落は、文章のまとまりを複数に分ける役割を持っています。意味が変わるタイミングで入れましょう。 377 | 具体的には@{しかし}など、前の文章から主張が変化するときに入れます。 378 | 379 | 段落が少なすぎる場合、紙面を文字が覆いつくしてしまいます。可読性が下がってしまいます。 380 | 初めは4・5文続いたら段落を切り替える、と考えておきましょう。 381 | 382 | 文章や段落などの切り方がうまくいかない場合、主張がまとまっていないことが多いです。 383 | まずは言いたいことを整理し、余計な文章を削ってみましょう。似たような内容があれば、それも削除しましょう。 384 | 385 | 初めのうちはたくさん書かないと伝わらないかも、と不安になります。それは、カレーにケチャップとマヨネーズをかけて食べる行為に等しいのです。 386 | カレーはカレー味で十分美味しいのです。余計なものは不要です。技術同人誌も同じことです。 387 | 388 | 本筋とは関係ない内容を書きたい場合、コラムとして記載する・付録として章を追加て対策しましょう。 389 | 『技術同人誌を書くための文章技術』でも、コラムと付録を用意しています。書き方には直接関係ないものの、技術同人誌を書く上では付随する話だからです。 390 | 391 | 読みづらいと感じたら思い切って削る、これを頭に入れて進めましょう。 392 | 393 | === 初見の単語には意味の解説があるか 394 | 395 | 専門用語やプロダクト名を記述するとき、「〇〇とは××のことです」と言葉の定義を記述しているか確認しましょう。 396 | 「初心者」「はじめての」とタイトルにつけたあなた。この観点は@{絶対に守ってください}。初学者はあなたの解説するプロダクトについて知りたいのです。 397 | 単語の意味が解説されていないと、あなたの本は初学者の求める要件を満たせません。読者の満足度はかなり下がってしまいます。 398 | 399 | @{non-comment}は、本の中で初めてLogstashという単語が出てきたときの文章です。 400 | 401 | //list[non-comment][本の中で初めて記載されるプロダクト名に解説がない場合]{ 402 | Logstashは、txt・xml・jsonファイルなどを収集できます。 403 | それだけでなく、Twitter APIと連携してTwitterのつぶやき情報を取り込む事も可能です。 404 | さらに、データベース（RSDB）に接続して情報を抜くこともできます。 405 | //} 406 | 407 | @{non-comment}の文章だけでは「で、結局Logstashってなんやねん」と感じてしまいますよね。 408 | 409 | //list[add-comment][本の中で初めて記載されるプロダクト名に解説がある]{ 410 | Logstashは、ログを収集し、指定した対象に連携できるツールです。 411 | それだけではなく、ログの加工機能も持ち合わせています。 412 | LogstashはRubyで作られています。 413 | 414 | Logstashは、txt・xml・jsonファイルなどを収集できます。 415 | それだけでなく、Twitter APIと連携してTwitterのつぶやき情報を取り込む事も可能です。 416 | さらに、データベース（RSDB）に接続して情報を抜くこともできます。 417 | //} 418 | 419 | これなら、Logstashとは何か、を読者が知っている状態になります。機能解説の理解もしやすいでしょう。 420 | 対面でのコミュニケーションとは違い、筆者から読者へ情報を伝える手段は本の内容のみに限られています。 421 | 著者と読者の認識を合わせておくことは、お互いの認識齟齬がない状態にするために重要です。 422 | 本の中で一番最初に専門用語が登場したとき、解説がされているか再度確認しましょう。 423 | 424 | === 同じ言葉を繰り返し利用していないか 425 | 426 | 同じ意味の言葉は、1段落に1回のみ使用します。例外として、表現を変えて繰り返し記述する場合や、専門用語・プロダクト名は繰り返し使用しても構いません。 427 | ただし、多くても3回程度にとどめておきます。冗長な文章として見えやすいからです。 428 | 429 | //list[repeat-word][同じ言葉が繰り返し出てくる例]{ 430 | 使いたいグラフを決めたあとはグラフを配置していきます。 431 | 基本は＋の部分を押しながら、ドラック&ドロップでグラフを配置していくだけです。 432 | グラフの大きさを変更したい場合、グラフ右下をクリックしたままドラック&ドロップで 433 | 大きさを調整します。ある程度は自動で大きさが決まってしまうので、ミリ単位の調節はできません。 434 | //} 435 | 436 | @{グラフ}という単語がくどいですよね。１段落に4回も出てきています。 437 | 438 | //list[non-repeat-word][同じ言葉を削った例]{ 439 | まずはじめに、利用したいグラフを決定します。 440 | 基本は＋の部分を押しながら、ドラック&ドロップで配置していくだけです。 441 | グラフの大きさを変更したい場合、対象の右下をクリックしたままドラック&ドロップで 442 | 大きさを調整します。ある程度は自動で大きさが決まってしまうので、ミリ単位の調節はできません。 443 | //} 444 | 445 | 数を2つ減らしました。先ほどよりは見やすくなりました。 446 | 447 | === 助詞の使い方は正しいか・抜け漏れはないか 448 | 449 | 助詞とは、主語や動詞、名詞など、言葉同士の関係を示すための言葉です。例をいくつか示します。 450 | 451 | * て 452 | * に 453 | * を 454 | * は 455 | * が/は 456 | 457 | 言葉の関係性を示す言葉を慎重に利用しないと、意味が全く違うものになります。先に述べた観点を元に推敲していれば、あなたの文章はだいぶ読みやすくなっているはずです。 458 | 言いたいことと記述されている文章を比較し、言いたいこと通りに伝わってくるか確かめましょう。 459 | 460 | また、助詞に抜け漏れがあると、文章全体が稚拙に見えてしまいます。助詞の書き漏れがないか、合わせて確認しましょう。 461 | 462 | 助詞の使い方が正しいか確認するときは、@{最低でも先に述べた推敲を行った1日後}に行います。書いた直後に見直しをかけると、頭の中で内容を補完してしまうためです。 463 | 期間を空けて見直しをすることで、「言いたかったことと違う・抜け漏れがある」ことに気がつきやすくなります。 464 | 465 | == 推敲する観点（応用編） 466 | 467 | 次に紹介する観点は、技術同人誌の質を上げるために確認するべきものです。ここから先は、著者の好みや個性が出る観点です。 468 | より良い技術同人誌を作るためのアイディアが必要であれば、参考にすると良いでしょう。 469 | 470 | * こそあど言葉を利用しない 471 | * 文章を断定形で記述する 472 | * 文章に適切なフォントを利用する 473 | * タイトル詐欺をしない 474 | * 動作するコードを載せる 475 | 476 | === こそあど言葉を利用しない 477 | 478 | こそあど言葉とは、「これ・それ・あれ・どれ」などの指示語のことです。指示語は便利な言葉ですが、文章内で多用されると@{何を指しているのか理解しづらく}なってしまいます。 479 | 情報の正確性が求められる技術同人誌を書くときは、こそあど言葉の利用を避けるべきです。 480 | 481 | //list[many-this-that][こそあど言葉が多い例]{ 482 | ログは好きなディレクトリに配置できます。ただし、ログファイルに適切な読み取り権限を付与しておく必要があります。 483 | 484 | リスト6.1 apacheの出力ログ 485 | （コードブロック内にログが記載されている） 486 | 487 | ログを解凍して中身をみると、このように表示されました。これをそのまま読むのは大変ですよね。 488 | //} 489 | 490 | @{このように}と@{これ}の2つは指示語です。もちろんこのままでも意味は通じますが、指示語を使わない形式へ書き換えてみます。 491 | 492 | //list[non-this-that][こそあど言葉を利用しない例]{ 493 | ログは好きなディレクトリに配置できます。ただし、ログファイルに適切な読み取り権限を付与しておく必要があります。 494 | 495 | リスト6.1 apacheの出力ログ 496 | （コードブロック内にログが記載されている） 497 | 498 | ログを解凍して中身をみると、リスト6.1のように表示されました。リスト6.1のログをそのまま読むのは大変ですよね。 499 | //} 500 | 501 | 少しくどいかもしれませんが、@{non-this-that}の記述の方が対象がはっきりとしています。 502 | くどいのが苦手であれば、@{few-this-that}のような表記をすると良いでしょう。 503 | 504 | //list[few-this-that][こそあど言葉を最低限に抑えた例]{ 505 | ログは好きなディレクトリに配置できます。ただし、ログファイルに適切な読み取り権限を付与しておく必要があります。 506 | 507 | リスト6.1 apacheの出力ログ 508 | （コードブロック内にログが記載されている） 509 | 510 | ログを解凍して中身をみると、リスト6.1のように表示されました。このログをそのまま読むのは大変ですよね。 511 | //} 512 | 513 | @{few-this-that}では、明確に対象がわかる箇所でこそあど言葉を利用しています。 514 | @{このログ}と記述がある直前の文章内に、@{リスト6.1}という記述があります。@{リスト6.1}の繰り返し表記を避けるため、指示語を利用しているのです。 515 | こそあど言葉を利用するときは、直前の文章内の名詞を置き換える程度にとどめておくと良いでしょう。 516 | 517 | === 文章を断定形で記述する 518 | 519 | 技術同人誌は情報の正確性が求められるジャンルの本です。@{〜と思います}・@{〜のはずです}などの曖昧な言葉を避けるべきです。@{i-think} 520 | 内容が正しいという自信がなければ、参考文献を探して知識を補強する必要があります。 521 | 早速、具体例を示します。 522 | 523 | //footnote[i-think][この本では「〜すると良いでしょう」と曖昧な言い回しを利用しています。これは技術同人誌の書き方という正解がないトピックを扱っているためです。付録のtextlintの解説内には登場しないので、確認してください。] 524 | 525 | //list[use-maybe][曖昧な表見を使っている例]{ 526 | Elasticsearchは、Javaのヒープメモリをかなり消費するツールです。 527 | Dockerコンテナ上ではあまり性能が出ないため、大量のデータを流す予定がある場合はコンテナ利用を避けた方が良いと思います。 528 | //} 529 | 530 | ElasticsearchをDockerコンテナ上で利用すると、性能に影響が出るので避けるべきと記述があります。ただ、著者に自信がないためか@{良いと思います}と曖昧な言葉で記述されています。 531 | これでは、読者は「本当にElasticsearchはコンテナで利用しない方が良いのか」と不安になってしまいますね。曖昧な言葉を使わずに書き換えてみましょう。 532 | 533 | //list[not-use-maybe][曖昧な表見を使わない例]{ 534 | Elasticsearchは、Javaのヒープメモリをかなり消費するツールです。 535 | Dockerコンテナ上ではあまり性能が出ないため、大量のデータを流す予定がある場合はコンテナを利用するべきではありません。 536 | //} 537 | 538 | とはいえ、内容が合っているか不安なときもあります。そのときは潔く「わからないので情報お待ちしております」などと記載します。 539 | 奥付の連絡先を見た人が、有益な情報を送ってくれるかもしれません。 540 | 541 | === 文章に適切なフォントを利用する 542 | 543 | 一般的な本の中では、@{本文は明朝体、タイトルや見出しはゴシック体}を利用することが多いです。『書体の使い分けー伝わるデザイン 研究発表のユニバーサルデザイン』では、 544 | 「太い文字で長い文章を書くと紙面が黒々してしまうので、可読性が下がります。目にも大きな負担がかか」るため、本文は明朝体を利用するべきとあります。 545 | 見出しは目立たせる必要があるため、文字が太く目立ちやすいゴシック体を利用します。 546 | 547 | ブログは本文がゴシック体の文章でも読みやすいよ、と思われるかもしれません。本はブログなどと違い、行間が狭くなります。紙面の高さが限られているためです。 548 | よって、太い文字を本文に使うべきではありません。 549 | 550 | 実際に比較してみましょう。 551 | 552 | //image[all-gothic][全てゴシック体の例]{ 553 | 554 | //} 555 | 556 | 文章の全てにヒラギノ角ゴシック体を使用した例です。少し文章が詰まって見えます。短文であれば良いのですが、1万文字を一度に読むと疲れてしまいそうです。 557 | 558 | //image[all-minchyo][全て明朝体の例]{ 559 | 560 | //} 561 | 562 | 文章の全てにヒラギノ明朝体を使用した例です。読みやすいのですが、メリハリが足りません。どこが見出しなのか理解するのは難しそうです。 563 | 564 | //image[gothic-and-minchyo][ゴシック体と明朝体を使い分けた例]{ 565 | 566 | //} 567 | 568 | 見出しはヒラギノ角ゴシック体、本文はヒラギノ明朝体を利用した例です。文章にメリハリをつけつつ、可読性も維持されています。 569 | 570 | 組版ツールによってフォントの設定方法は変わります。自分の利用するツールと相談しつつ、適切なフォントを設定しましょう。 571 | ただし、@{PDFにフォントを埋め込まないと、印刷時にフォントが欠ける現象が発生する}可能性があります。 572 | 慣れないうちは組版ツールのデフォルトフォントを利用すると安全です。 573 | 574 | フォントを変更する場合、Adobe Acrobatを利用してフォントを埋め込む処理をするべきです。 575 | うまくできていなければ、印刷所から原稿を差し戻される可能性もあります。フォントにこだわるよりは、原稿の質にこだわった方が良いです。 576 | 577 | === タイトル詐欺をしない 578 | 579 | @{タイトル詐欺}とは、@{本のタイトルから読み取れる情報が本文の内容と一致していない}状態を指しています。 580 | タイトル詐欺が良くない理由は、@{読者の期待を裏切ってしまう行為が満足度を下げる要因になる}からです。 581 | 582 | 例をいくつか示します。 583 | 584 | * タイトル例A：初めてでもできる！Elastic Stack5 585 | ** 内容：Elasticsearch（バージョン6.4）のIndex設計において気を使うべき点 586 | * タイトル例B：Markdownを使って文章を書く方法 587 | ** 内容：MarkdownエディタのWebサービスを使う方法 588 | * タイトル例C：失敗しない監視設計 589 | ** 内容：監視のアンチパターン事例集 590 | 591 | タイトル例Aはひどいタイトル詐欺です。タイトルに記載されているバージョンと本文で取り扱っているバージョンが違います。 592 | タイトルからは、@{Elastic Stack}というプロダクトの話に関するものという印象を受けます。対する本文は@{Elasticsearch}についてです。 593 | タイトルと内容が違います。 594 | 595 | 加えて、タイトルには@{初めてでもできる！}とついています。「初めてでも」と記載されているのです。読者は@{何も知らない状態で}@{Elastic Stack}を始めても大丈夫なのだろう、と期待します。 596 | しかし本文は@{Index設計}という高度な話題を取り扱っています。具体的には、@{Elasticsearch}の中でどのようにデータを保管するかを設計する行為です。これは初心者向けの話題でしょうか？ 597 | 598 | タイトル例Aの内容であれば、@{Elasticsearch6.4におけるIndex設計手法}というタイトルの方がふさわしいでしょう。 599 | 600 | タイトル例Bも読者の期待を裏切るパターンです。@{文章を書く方法}という文言からは、Markdownを使って文章を組み上げる方法を連想します。 601 | しかし、内容はMarkdownエディタサービスの使い方について記載しています。読者に期待させる内容と、実際の内容がずれてしまっています。 602 | タイトル例Bの内容であれば、@{（サービス名）で作るMarkdown文章}の方が内容に沿っています。 603 | 604 | タイトル例Cも、具体的な内容によってはタイトル詐欺となります。@{失敗しない}からは@{失敗しない方法}のこと・@{失敗事例}の2つが連想できるからです。 605 | 人によって連想される内容が違うのが厄介です。事故を避けるためには、@{監視におけるアンチパターン集}とタイトルをつける方が安全です。 606 | 607 | タイトル詐欺を防ぐためには、内容を一通り書き終わった後に@{この内容を一言で表すとを再度確認する}ことが重要です。@{サークル申し込み時の内容をそのままにしておくのは危険です}。 608 | 609 | === 動作するコードを載せる 610 | 611 | この観点は、@{紙面に掲載されているコード・設定ファイルなどをそのまま流用しても動作する}ことを確認するものです。 612 | 商業本で低評価がついてしまう理由の一つに、「本文内のプログラムなどにミスが存在する」ことです。 613 | 614 | 人間、誰しもミスをするものです。プロの編集者を通しても誤字脱字を0にすることは難しいのです。商業本の発売後に正誤表が発表されていることが証拠です。 615 | しかし、技術的な箇所は間違いを0にしておきたいものです。ここに間違いがあると、本を通して知見を得ることが難しくなるためです。 616 | 617 | 間違いを減らすため有効なのは、@{実際に動作させたものをそのまま貼り付ける}ことです。自分の環境では動作しているのですから、安心感も担保できます。 618 | GitHubリポジトリなどにコードを載せておけば、プロフィールを充実させることも可能です。 619 | 620 | 621 | -------------------------------------------------------------------------------- /articles/init-textlint.re: -------------------------------------------------------------------------------- 1 | = 静的検査ツールを利用する 2 | 3 | 技術同人誌の本文をテキスト形式で記載した場合、文章に対する静的検査が実行できます。 4 | この本ではazuさんが作成した、@{textlint}の基本的な利用法を紹介します。 5 | 6 | == textlintのインストール 7 | 8 | textlintの実行にはNode.js（npm）環境が必要です。ここでは@{npm}を用いてインストールする方法を解説します。 9 | この本に記載している動作環境は、@{macOS Mojave バージョン10.14.3}です。 10 | 11 | Google Chrome拡張を導入する（textlint: 文章チェッカー）・textlint-appを通じてtextlintを利用することも可能です。 12 | 13 | この本ではNode.js環境を使って構築します。工夫すれば、CIにも組み込むことができるためです。 14 | 15 | はじめに、textlintをインストールします。プロジェクトフォルダに移動し、@{npm install textlint}でtextlintをインストールしましょう。 16 | Re:VIEWファイルに対して静的検査を実施する場合、専用プラグインである@{textlint-plugin-review}も合わせてインストールします。 17 | @{$}はコマンドラインであることを示しています。コンソールにコマンドを記述するときは@{$}を記載しないでください。 18 | 19 | //list[textlint-install][npm install]{ 20 | $ cd プロジェクトのフォルダ 21 | # プロジェクト内にのみインストールしたいので、--save-devオプションをつける 22 | $ npm install textlint --save-dev 23 | //} 24 | 25 | === package.jsonへtextlintを記載する 26 | 27 | textlintをインストールした後は、@{package.json}へtextlintを追記します。@{npm init}を利用すると、@{package.json}の雛形を作成できます。 28 | 29 | //list[textlint-init][npm init]{ 30 | $ npm init --yes 31 | Wrote to /Users/mofu/git/TB6-technical-writing-technic/package.json: 32 | //} 33 | 34 | === ルールプリセットの導入 35 | 36 | textlintをインストールしただけでは、静的検査を実施することはできません。検査用ルールを導入・作成する必要があります。 37 | 38 | ここでは、@{textlint-rule-preset-ja-technical-writing} 39 | というルールを導入します。このルールを利用する、技術文章を書く上で守るべき事項を網羅的に検査できます。 40 | 41 | 例えば、「「ですます調」、「である調」を統一する」・「同一の単語を間違えて連続しているのをチェックする」・「よくある日本語の誤用をチェックする」などをチェックできます。 42 | 適用されているルールを全て確認したい場合、READMEを参照してください。 43 | 44 | このルールも@{npm install}を使ってインストールします。 45 | 46 | //list[textlint-rule-install][ルールセットの導入]{ 47 | $ npm install --save-dev textlint-rule-preset-ja-technical-writing 48 | //} 49 | 50 | === ルールセットを適用 51 | 52 | @{.textlintrc}というファイルを新規に作成します。@{.textlintrc}は、textlintコマンドを実行するとき、どのルールを適用するか制御するためのファイルです。 53 | 54 | //list[add-textlintrc][.textlintrcの追加]{ 55 | { 56 | "filters": {\}, 57 | "rules": { 58 | "preset-ja-technical-writing": true 59 | \} 60 | \} 61 | //} 62 | 63 | @{.textlintrc}は、.gitignoreなどと同じ階層に配置します。@{dir}はこの本を作成するときに利用したリポジトリのディレクトリ構成です。 64 | 組版にはRe:VIEWを利用しています。 65 | 66 | //list[dir][Re:VIEWを用いた場合のディレクトリ構成例]{ 67 | $ ls -al 68 | total 328 69 | drwxr-xr-x 18 mofumofu staff 576 2 11 14:14 . 70 | drwxr-xr-x 10 mofumofu staff 320 2 5 19:52 .. 71 | drwxr-xr-x 16 mofumofu staff 512 2 17 20:19 .git 72 | -rw-r--r-- 1 mofumofu staff 82 2 10 20:55 .gitignore 73 | -rw-r--r-- 1 mofumofu staff 93 2 2 18:23 .textlintrc 74 | -rw-r--r-- 1 mofumofu staff 98 1 9 20:42 Gemfile 75 | -rw-r--r-- 1 mofumofu staff 249 1 9 20:42 Gemfile.lock 76 | -rw-r--r-- 1 mofumofu staff 3215 1 9 20:42 Gruntfile.js 77 | -rw-r--r-- 1 mofumofu staff 1065 1 9 20:41 LICENSE 78 | -rw-r--r-- 1 mofumofu staff 132 1 9 20:43 README.md 79 | drwxr-xr-x 21 mofumofu staff 672 2 17 19:44 articles 80 | -rwxr-xr-x 1 mofumofu staff 283 1 9 20:42 build-in-docker.sh 81 | drwxr-xr-x 294 mofumofu staff 9408 2 11 14:14 node_modules 82 | -rw-r--r-- 1 mofumofu staff 111874 2 2 18:23 package-lock.json 83 | -rw-r--r-- 1 mofumofu staff 1547 2 2 18:23 package.json 84 | -rw-r--r-- 1 mofumofu staff 3477 1 9 20:42 redpen-conf-ja.xml 85 | -rwxr-xr-x 1 mofumofu staff 211 1 9 20:42 setup.sh 86 | //} 87 | 88 | == textlintの実施 89 | 90 | ルールセットの定義が終わったら、静的検査を実施します。@{node_modules/.bin/textlint --preset ルール名 静的検査対象}でtextlintを実行できます。 91 | @{textlint-markdown}では、markdownファイルにtextlintを実施しています。 92 | 93 | //list[textlint-markdown][markdownファイル全てにtextlintを実施する]{ 94 | $ node_modules/.bin/textlint --preset ja-technical-writing ./articles/markdown/*.md 95 | 96 | /Users/mofu/git/TB6-technical-writing-technic/articles/markdown/init-textlint.md 97 | 48:15 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 98 | 67:11 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 99 | 84:9 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 100 | 109:18 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 101 | 120:11 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 102 | 103 | /Users/mofu/git/TB6-technical-writing-technic/articles/markdown/think-body.md 104 | 15:18 ✓ error Found invalid control character(BACKSPACE \u0008) 105 | ja-technical-writing/no-invalid-control-character 106 | 107 | 〜省略〜 108 | ✖ 94 problems (94 errors, 0 warnings) 109 | ✓ 64 fixable problems. 110 | Try to run: $ textlint --fix [file] 111 | //} 112 | 113 | 行数・エラー内容・ルール名がセットで出力されます。コマンド実行時に@{--fix}オプションを利用すると、自動でエラー個所を修正できます。 114 | 115 | === npm runで実行できるようにする 116 | 117 | @{package.json}へtextlintコマンドを登録すれば、@{npm run コマンド名}でtextlintを実行できるようになります。 118 | 今回は@{textlint}というコマンド名を登録しました。@{package.json}に@{npm run textlint}で実行したいコマンドを記載します。 119 | 120 | @{add-command}は@{"textlint": "node_modules/.bin/textlint --preset ja-technical-writing ./articles/markdown/*.md"}を@{package.json}へ追加した例です。 121 | 122 | こうすることで、CIツールと組み合わせてtextlintを実施できるようになります。 123 | 124 | //list[add-command][package.jsonへコマンドを追記]{ 125 | "scripts": { 126 | "site": "cd site ; hugo --cleanDestinationDir", 127 | "global-bundler": "gem install bundler", 128 | "global": "npm run global-bundler", 129 | "postinstall": "bundle install", 130 | "pdf": "grunt pdf", 131 | "md": "grunt markdown", 132 | "html": "grunt html", 133 | "test": "npm run html", 134 | # この行を追加 135 | "textlint": "node_modules/.bin/textlint --preset ja-technical-writing 136 | # 紙面の都合で改行 137 | ./articles/markdown/*.md" 138 | \}, 139 | //} 140 | 141 | これで、文章の静的検査ができるようになりました。複数人執筆の場合、CIツールと組み合わせて検査できる環境があると便利です。編集者の修正負荷を下げることができるからです。 142 | -------------------------------------------------------------------------------- /articles/introduction.re: -------------------------------------------------------------------------------- 1 | = はじめに 2 | 3 | こんにちは。りまりま団のもふもふです。この本を手に取ったあなたは今、こんなことを考えているのではないでしょうか。 4 | 5 | * 技術同人誌が盛り上がっているらしいので、自分でも書いてみたい 6 | * でも文章を書くのは自信がない 7 | * たくさん書かないといけないと聞くけれど、どうやって書けばいいのかわからない 8 | * 思うように文章が書けない 9 | * やっぱり文章を書くのは向いていないから、やめておこう 10 | 11 | 「やっぱり文章を書くのは向いていないから、やめておこう？」それは大変もったいないことです。 12 | 文章の書き方を理解すれば、誰でも文章を書けるようになります。 13 | 14 | 「文章の書き方」とは、次のものを指しています。 15 | 16 | * 何を書くか、をどうやって探すか 17 | * 章の組み立て方 18 | * 文章の組み立て方 19 | * 段落の切り方 20 | * 接続詞の使い方 21 | * 助詞の使い方 22 | * タイトルの付け方 23 | * 説明するための考え方 24 | * 推敲のやり方 25 | * 紙面の作り方 26 | 27 | そのくらいわかっているよ、と思われるかもしれません。しかし、これらの観点を守らないと、本の品質はガタっと落ちます。 28 | 読者が「ちょっと読みにくいかも」と感じる本は、@{「文章の書き方」がよろしくない場合が多い}のです。 29 | 30 | 「でも、その文章の書き方がわからないから困ってるんじゃないか！」と思ったでしょう？そんなあなたに向けて、この本を書くことにしました。 31 | 現時点@{whyWriteThisBook}で、@{技術同人誌に特化した「文章の書き方」を解説した本}を見つけることができなかったためです。 32 | 33 | //footnote[whyWriteThisBook][2019年2月2日現在] 34 | 35 | 「『技術同人誌を書こう！　アウトプットのススメ (技術書典シリーズ（NextPublishing）)@{writeTechbook}』という本があるよ！」と思われたかもしれません。 36 | しかし、この本は「同人誌即売会へ申し込んで本を出すまでの工程」について書かれた本です。 37 | 何について書くか、に関しては1章割かれて記載されています。ただしメインコンテンツは、表紙の作り方や即売会当日の持ち物についてです。文章の書き方講座はほぼ記載されていません。 38 | 何故断言できるのか？私もこの本に「何について書くか？」の章を寄稿しているからです。 39 | 40 | //footnote[writeTechbook][親方Project 編（2018）技術同人誌を書こう！　アウトプットのススメ (技術書典シリーズ（NextPublishing）インプレスR&D] 41 | 42 | 技術文章の書き方について記載した本は存在します。しかし、仕事や学会発表、商業本を書くことを想定していることが多いのです。技術同人誌は他の「書く」ことよりも自由度が高く、かつ誰かが品質をチェックして合格サインを出してくれることはありません。 43 | 人にレビューを依頼すれば、感想やアドバイスをもらえるかもしれません。それを取り入れるかはあなた自身が決める必要があります。 44 | 45 | 判断基準が明確でない場合、意見を取り入れるべきか迷ってしまいます。全部取り入れてしまえば楽でしょう。ただ、これは同人誌なのです。主役はあなた自身であるべきです。 46 | 47 | 自分の時間を割いて本を作るのであれば、自分の意見を読者に届けたいですよね。そのためには、「良い」文章を書くことが重要です。 48 | 「良い」文章の書き方に迷ってしまったときに、この本がお役に立てれば幸いです。 49 | 50 | 51 | == 諸注意 52 | 53 | 技術同人誌の書き方本なので、できれば実際の技術同人誌を参考文献にしたいですよね。 54 | 55 | 私は『Elastic Stackで作るBI環境』という商業本を書いたことがあります。 56 | この本は『ログと情報をレッツ・ラ・まぜまぜ！～ELK Stack で作るBI環境～』という同人誌をインプレスR&Dから商業出版したものです。 57 | 58 | せっかくなので『Elastic Stackで作るBI環境』を題材に話を進めたいのですが、本著作権はインプレスR&Dさんが持っているため気軽に引用できません。 59 | そこで、今回は同人版の『ログと情報をレッツ・ラ・まぜまぜ！～ELK Stack で作るBI環境～』を教材として話を進めていきます。この本は私が著作権を持っているためです。インプレスR&Dの編集者さんに許可もとりました。 60 | 61 | //image[slack][やり取りの証拠です]{ 62 | //} 63 | 64 | 同人誌を商業誌にするときは、校正をいただいています。また、内容も2章分ほど追記しています。商業本の内容が気になるようでしたら、ぜひAmazonで『Elastic Stackで作るBI環境』を買ってみてください。自分で言うのもアレですが、良くできた本だと思います。 65 | 66 | * この本は「読むだけで超売れる技術同人誌ができる」ことをお約束しません。技術同人誌は完成した時点で優勝ものです。また、完成するかはあなた次第です。書いた本が売れるかどうかは、読者のグルーヴ（趣味嗜好や流行など）で決まります。 67 | * この本に書かれたことを実践しなくても本は書けます。取り入れるかどうかはあなた次第です。 68 | * この本では商業出版の方法・印税については言及しません。 69 | * この本を読むだけでは原稿は完成しません。大事なことなので2回いいました。 70 | * スケジュールは余裕を持って立てましょう。締め切りをすぎると印刷所の人に長時間残業を強要することになります。 -------------------------------------------------------------------------------- /articles/layouts/layout.tex.erb: -------------------------------------------------------------------------------- 1 | \documentclass[<%= @documentclassoption %>]{<%= @documentclass %>} 2 | <%- if @texcompiler == "uplatex" -%> 3 | \usepackage[deluxe,uplatex]{otf} 4 | <%- else -%> 5 | \usepackage[deluxe]{otf} 6 | <%- end -%> 7 | \usepackage[dvipdfmx]{xcolor} 8 | \usepackage[dvipdfmx]{graphicx} 9 | \usepackage{framed} 10 | \usepackage{wrapfig} 11 | \definecolor{shadecolor}{gray}{0.9} 12 | \definecolor{shadecolorb}{gray}{0.1} 13 | \definecolor{reviewgreen}{rgb}{0,0.4,0} 14 | \definecolor{reviewblue}{rgb}{0.2,0.2,0.4} 15 | \definecolor{reviewred}{rgb}{0.7,0,0} 16 | \definecolor{reviewdarkred}{rgb}{0.3,0,0} 17 | \usepackage{lmodern} 18 | \usepackage[T1]{fontenc} 19 | \usepackage{textcomp} 20 | \usepackage[utf8]{inputenc} 21 | \usepackage{ascmac} 22 | \usepackage{float} 23 | \usepackage{alltt} 24 | \usepackage{amsmath} 25 | 26 | %% if you use @{} (underline), use jumoline.sty 27 | %%\usepackage{jumoline} 28 | 29 | \newenvironment{shadedb}{% 30 | \def\FrameCommand{\fboxsep=\FrameSep \colorbox{shadecolorb}}% 31 | \MakeFramed {\FrameRestore}}% 32 | {\endMakeFramed} 33 | 34 | <%- unless ["utbook", "tbook"].include?(@documentclass) -%> 35 | %\usepackage[top=10zw,bottom=12zw,left=10zw,right=10zw]{geometry} 36 | %\usepackage[top=5zw,bottom=5zw,left=1zw,right=1zw]{geometry} 37 | <%- end -%> 38 | 39 | \newcommand{\parasep}{\vspace*{3zh}} 40 | \setlength{\footskip}{30pt} 41 | 42 | <%- if @texcompiler == "uplatex" -%> 43 | \usepackage[dvipdfmx,bookmarks=true,bookmarksnumbered=true,colorlinks=true,% 44 | pdftitle={<%= @config.name_of("booktitle") %>},% 45 | pdfauthor={<%= @config.names_of("aut").join(I18n.t("names_splitter")) %>}]{hyperref} 46 | % uplatexでのBookmarkの文字化け対策（日本語向け） 47 | \usepackage[dvipdfmx]{pxjahyper} 48 | <%- else -%> 49 | %% Bookmarkの文字化け対策（日本語向け） 50 | \ifnum 46273=\euc"B4C1 % 46273 == 0xB4C1 == 漢(EUC-JP) 51 | \usepackage{atbegshi}% 52 | \AtBeginShipoutFirst{\special{pdf:tounicode EUC-UCS2}}% 53 | %%\AtBeginDvi{\special{pdf:tounicode EUC-UCS2}}% 54 | \else 55 | \usepackage{atbegshi}% 56 | \AtBeginShipoutFirst{\special{pdf:tounicode 90ms-RKSJ-UCS2}}% 57 | %%\AtBeginDvi{\special{pdf:tounicode 90ms-RKSJ-UCS2}}% 58 | \fi 59 | 60 | \usepackage[dvipdfm,bookmarks=true,bookmarksnumbered=true,colorlinks=true,% 61 | pdftitle={<%= @config.name_of("booktitle") %>},% 62 | pdfauthor={<%= @config.names_of("aut").join(I18n.t("names_splitter")) %>}]{hyperref} 63 | <%- end -%> 64 | 65 | <%- if ["utbook", "tbook"].include?(@documentclass) -%> 66 | \newcommand{\headfont}{\gtfamily\sffamily\bfseries} 67 | \usepackage{plext} 68 | <%- end -%> 69 | 70 | <%- if config["highlight"] && config["highlight"]["latex"] == "listings" -%> 71 | <%- if config["language"] == "ja" -%> 72 | \usepackage{listings,jlisting} 73 | <%- else -%> 74 | \usepackage{listings} 75 | <%- end -%> 76 | \renewcommand{\lstlistingname}{<%= I18n.t("list")%>} 77 | \lstset{% 78 | breaklines=true,% 79 | breakautoindent=false,% 80 | breakindent=0pt,% 81 | fontadjust=true,% 82 | backgroundcolor=\color{shadecolor},% 83 | frame=single,% 84 | framerule=0pt,% 85 | basicstyle=\ttfamily\scriptsize,% 86 | commentstyle=\color{reviewgreen},% 87 | identifierstyle=\color{reviewblue},% 88 | stringstyle=\color{reviewred},% 89 | keywordstyle=\bfseries\color{reviewdarkred},% 90 | } 91 | 92 | \lstnewenvironment{reviewemlistlst}[1][]{\lstset{#1}}{} 93 | \lstnewenvironment{reviewemlistnumlst}[1][]{\lstset{numbers=left, #1}}{} 94 | \lstnewenvironment{reviewlistlst}[1][]{\lstset{#1}}{} 95 | \lstnewenvironment{reviewlistnumlst}[1][]{\lstset{numbers=left, #1}}{} 96 | \lstnewenvironment{reviewcmdlst}[1][]{\lstset{backgroundcolor=\color{white}, frameround=tttt, frame=trbl, #1}}{} 97 | <%- end -%> 98 | 99 | \newenvironment{reviewimage}{% 100 | \begin{figure}[H] 101 | \begin{center}}{% 102 | \end{center} 103 | \end{figure}} 104 | 105 | \newenvironment{reviewdummyimage}{% 106 | \begin{figure}[H] 107 | \begin{center}\begin{alltt}}{% 108 | \end{alltt}\end{center} 109 | \end{figure}} 110 | 111 | \newenvironment{reviewemlist}{% 112 | \medskip\small\begin{shaded}\setlength{\baselineskip}{1.3zw}\begin{alltt}}{% 113 | \end{alltt}\end{shaded}} 114 | 115 | \newenvironment{reviewlist}{% 116 | \begin{shaded}\small\setlength{\baselineskip}{1.3zw}\begin{alltt}}{% 117 | \end{alltt}\end{shaded}\par\vspace*{0.5zw}} 118 | 119 | \newenvironment{reviewcmd}{% 120 | \color{white}\medskip\small\begin{shadedb}\setlength{\baselineskip}{1.3zw}\begin{alltt}}{% 121 | \end{alltt}\end{shadedb}} 122 | 123 | \newenvironment{reviewbox}{% 124 | \medskip\small\begin{framed}\setlength{\baselineskip}{1.3zw}\begin{alltt}}{% 125 | \end{alltt}\end{framed}} 126 | 127 | \newenvironment{reviewtable}[1]{% 128 | \begin{center}\small\setlength{\baselineskip}{1.2zw} 129 | \begin{tabular}{#1}}{% 130 | \end{tabular} 131 | \end{center}} 132 | 133 | \newenvironment{reviewcolumn}{% 134 | \begin{framed} 135 | }{% 136 | \end{framed} 137 | \vspace{2zw}} 138 | 139 | \newcommand{\reviewcolumnhead}[2]{% 140 | {\noindent\large <%= I18n.t("column_head")%>: #2}} 141 | 142 | \newcommand{\reviewtablecaption}[1]{% 143 | \caption{#1}} 144 | 145 | \newcommand{\reviewimgtablecaption}[1]{% 146 | \caption{#1}\vspace{-3mm}} 147 | 148 | \newcommand{\reviewbackslash}[0]{% 149 | \textbackslash{}} 150 | 151 | \newcommand{\reviewlistcaption}[1]{% 152 | \medskip{\small\noindent #1}\vspace*{-1.3zw}} 153 | 154 | \newcommand{\reviewemlistcaption}[1]{% 155 | \medskip{\small\noindent #1}\vspace*{-1.3zw}} 156 | 157 | \newcommand{\reviewcmdcaption}[1]{% 158 | \medskip{\small\noindent #1}\vspace*{-1.3zw}} 159 | 160 | \newcommand{\reviewindepimagecaption}[1]{% 161 | \begin{center}#1\end{center}} 162 | 163 | \newcommand{\reviewboxcaption}[1]{% 164 | \medskip{\small\noindent #1}\vspace*{-1.3zw}} 165 | 166 | \newcommand{\reviewimageref}[2]{<%= I18n.t("image")%> #1} 167 | \newcommand{\reviewtableref}[2]{<%= I18n.t("table")%> #1} 168 | \newcommand{\reviewlistref}[1]{<%= I18n.t("list")%> #1} 169 | \newcommand{\reviewbibref}[2]{#1} 170 | \newcommand{\reviewcolumnref}[2]{<%= I18n.t("columnname")%> #1} 171 | \newcommand{\reviewsecref}[2]{#1} 172 | 173 | \newcommand{\reviewminicolumntitle}[1]{% 174 | {\large <%= I18n.t("memo_head")%>: #1}\\} 175 | 176 | <%- if @config["toctitle"].present? -%> 177 | \renewcommand{\contentsname}{<%= @config["toctitle"]%>} 178 | <%- end -%> 179 | 180 | \newenvironment{reviewminicolumn}{% 181 | \vspace{1.5zw}\begin{screen}}{% 182 | \end{screen}\vspace{2zw}} 183 | 184 | \newcommand{\reviewkw}[1]{\textbf{\textgt{#1}}} 185 | \newcommand{\reviewami}[1]{\mask{#1}{A}} 186 | \newcommand{\reviewem}[1]{\textbf{#1}} 187 | \newcommand{\reviewstrong}[1]{\textbf{#1}} 188 | \newcommand{\reviewunderline}{\Underline} 189 | 190 | %% @ is ignored in LaTeX with default style 191 | \newcommand{\reviewstrike}[1]{#1} 192 | 193 | %%%% for ulem.sty: 194 | %%\renewcommand{\reviewstrike}[1]{\sout{#1}} 195 | %% 196 | %%%% for jumoline.sty: 197 | %%\renewcommand{\reviewstrike}[1]{\Middleline{#1}} 198 | 199 | \newcommand{\reviewth}[1]{\textgt{#1}} 200 | \newcommand{\reviewtitlefont}[0]{\usefont{T1}{phv}{b}{n}\gtfamily} 201 | \newcommand{\reviewmainfont}[0]{} 202 | \newcommand{\reviewcolophon}[0]{\clearpage} 203 | \newcommand{\reviewappendix}[0]{\appendix} 204 | 205 | \makeatletter 206 | %% maxwidth is the original width if it is less than linewidth 207 | %% otherwise use linewidth (to make sure the graphics do not exceed the margin) 208 | \def\maxwidth{% 209 | \ifdim\Gin@nat@width>\linewidth 210 | \linewidth 211 | \else 212 | \Gin@nat@width 213 | \fi 214 | } 215 | \makeatother 216 | 217 | <%- if @config["usepackage"] -%> 218 | <%= @config["usepackage"] %> 219 | <%- end -%> 220 | 221 | \usepackage[T1]{fontenc} 222 | 223 | \begin{document} 224 | 225 | \reviewmainfont 226 | 227 | \frontmatter 228 | \pagenumbering{arabic} 229 | 230 | <%- if @config["titlepage"] -%> 231 | <%- if @custom_titlepage -%> 232 | <%= @custom_titlepage %> 233 | <%- else -%> 234 | \begin{titlepage} 235 | <%- if @config["coverimage"] -%> 236 | \begin{center} 237 | \includegraphics[<%= @coverimageoption%>]{./images/<%= @config["coverimage"] %>} 238 | \end{center} 239 | \clearpage 240 | <%- end -%> 241 | \thispagestyle{plainhead} 242 | \setcounter{page}{1} 243 | \begin{center}% 244 | \mbox{} \vskip5zw 245 | \reviewtitlefont% 246 | {\Huge <%= @config.name_of("booktitle") %> \par}% 247 | \vskip 15em% 248 | {\huge 249 | \lineskip .75em 250 | \begin{tabular}[t]{c}% 251 | <%= @authors %> 252 | \end{tabular}\par}% 253 | \vfill 254 | {\large <%= @config["date"] %> <%= I18n.t("edition")%>\hspace{2zw}<%= I18n.t("published_by", @config.names_of("pbl").join(I18n.t("names_splitter")))%>\par}% 255 | \vskip4zw\mbox{} 256 | \end{center}% 257 | \end{titlepage} 258 | <%- end -%> 259 | <%- end -%> 260 | 261 | %%% originaltitle 262 | <%- if @config["originaltitlefile"] -%> 263 | <%= @custom_originaltitlepage %> 264 | <%- end -%> 265 | 266 | %%% credit 267 | <%- if @config["creditfile"] -%> 268 | <%= @custom_creditpage %> 269 | <%- end -%> 270 | 271 | %% preface 272 | <%= @input_files["PREDEF"] %> 273 | 274 | <%- if @config["toc"] -%> 275 | \setcounter{tocdepth}{<%= @config["toclevel"] %>} 276 | \tableofcontents 277 | <%- end -%> 278 | 279 | \begingroup 280 | \cleardoublepage 281 | \edef\continuenumber{\endgroup 282 | \noexpand\mainmatter 283 | \setcounter{page}{\the\value{page}}% 284 | } 285 | 286 | \mainmatter 287 | \continuenumber 288 | 289 | \renewcommand{\chaptermark}[1]{\markboth{\prechaptername\thechapter\postchaptername~#1}{}} 290 | <%= @input_files["CHAPS"] %> 291 | \renewcommand{\chaptermark}[1]{\markboth{\appendixname\thechapter~#1}{}} 292 | \reviewappendix 293 | <%= @input_files["APPENDIX"] %> 294 | 295 | %% backmatter begins 296 | <%- if @input_files["POSTDEF"] or @config["colophon"] -%> 297 | \backmatter 298 | <%- end -%> 299 | 300 | <%- if @input_files["POSTDEF"] -%> 301 | <%= @input_files["POSTDEF"] %> 302 | <%- end -%> 303 | 304 | %%% profile 305 | <%- if @config["profile"] -%> 306 | <%= @custom_profilepage %> 307 | <%- end -%> 308 | 309 | %%% advfile 310 | <%- if @config["advfile"] -%> 311 | <%= @custom_advfilepage %> 312 | <%- end -%> 313 | 314 | %%% colophon 315 | <%- if @config["colophon"] -%> 316 | <%- if @custom_colophonpage -%> 317 | <%= @custom_colophonpage %> 318 | <%- else -%> 319 | %% okuduke 320 | \reviewcolophon 321 | \thispagestyle{plainhead} 322 | 323 | \vspace*{\fill} 324 | 325 | {\noindent\reviewtitlefont\Large <%= @config.name_of("booktitle") %>} \\ 326 | \rule[8pt]{14cm}{1pt} \\ 327 | {\noindent 328 | <%= @config["pubhistory"].to_s.gsub(/\n/){"\n\n\\noindent\n"} %> 329 | } 330 | 331 | \begin{tabular}{ll} 332 | <%= @okuduke %> 333 | \end{tabular} 334 | 　\\ 335 | \rule[0pt]{14cm}{1pt} \\ 336 | <%= @config.names_of("rights").join('\\' + '\\') %> \\ 337 | <%- end -%> 338 | <%- end -%> 339 | 340 | %%% backcover 341 | <%- if @config["backcover"] -%> 342 | <%= @custom_backcoverpage %> 343 | <%- end -%> 344 | 345 | \end{document} 346 | -------------------------------------------------------------------------------- /articles/locale.yml: -------------------------------------------------------------------------------- 1 | locale: ja 2 | column_head: ■コラム 3 | columnname: コラム 4 | memo_head: ■メモ 5 | image: 図 6 | table: 表 7 | list: リスト 8 | -------------------------------------------------------------------------------- /articles/markdown/init-textlint.md: -------------------------------------------------------------------------------- 1 | ```bash 2 | → npm init --yes 3 | Wrote to /Users/mofu/git/TB6-technical-writing-technic/package.json: 4 | 5 | { 6 | "name": "TB6-technical-writing-technic", 7 | "version": "0.0.1", 8 | "private": true, 9 | "description": "同人誌の作り方本はあっても文章がかけなきゃ意味ないじゃない！だったら作るしかないですね？", 10 | "main": "Gruntfile.js", 11 | "repository": { 12 | "type": "git", 13 | "url": "git+https://github.com/MofuMofu2/TB6-technical-writing-technic.git" 14 | }, 15 | "author": "", 16 | "license": "MIT", 17 | "bugs": { 18 | "url": "https://github.com/MofuMofu2/TB6-technical-writing-technic/issues" 19 | }, 20 | "homepage": "https://github.com/MofuMofu2/TB6-technical-writing-technic#readme", 21 | "engines": { 22 | "node": ">=6.0.0" 23 | }, 24 | "scripts": { 25 | "site": "cd site ; hugo --cleanDestinationDir", 26 | "global-bundler": "gem install bundler", 27 | "global": "npm run global-bundler", 28 | "postinstall": "bundle install", 29 | "pdf": "grunt pdf", 30 | "md": "grunt markdown", 31 | "html": "grunt html", 32 | "test": "npm run html" 33 | }, 34 | "dependencies": {}, 35 | "devDependencies": { 36 | "grunt": "1.0.1", 37 | "grunt-cli": "1.2.0", 38 | "grunt-contrib-clean": "1.0.0", 39 | "grunt-open": "0.2.3", 40 | "grunt-shell": "1.3.0", 41 | "js-yaml": "3.6.0", 42 | "load-grunt-tasks": "3.5.0" 43 | }, 44 | "keywords": [] 45 | } 46 | ``` 47 | 48 | textlintのセットアップ 49 | 50 | [textlint Get Started](https://github.com/textlint/textlint/blob/master/docs/getting-started.md) 51 | 52 | ```bash 53 | → npm install --save-dev textlint 54 | npm WARN deprecated circular-json@0.3.3: CircularJSON is in maintenance only, flatted is its successor. 55 | + textlint@11.2.1 56 | added 258 packages from 138 contributors and audited 570 packages in 5.839s 57 | found 6 vulnerabilities (3 low, 2 moderate, 1 critical) 58 | run `npm audit fix` to fix them, or `npm audit` for details 59 | (11:47:14) ± [mofu@mofunoMacBook-Pro.local] ~/git/TB6-technical-writing-technic (textlint U:2 ?:1 ✗) 60 | → npm audit fix 61 | + grunt@1.0.3 62 | added 9 packages from 6 contributors, removed 3 packages and updated 9 packages in 2.549s 63 | fixed 5 of 6 vulnerabilities in 570 scanned packages 64 | 1 vulnerability required manual review and could not be updated 65 | ``` 66 | 67 | ルールプリセットの導入 68 | 69 | [textlint-rule-preset-ja-technical-writing](https://github.com/textlint-ja/textlint-rule-preset-ja-technical-writing) 70 | 71 | ```bash 72 | → npm install --save-dev textlint-rule-preset-ja-technical-writing 73 | + textlint-rule-preset-ja-technical-writing@3.1.0 74 | added 86 packages from 34 contributors and audited 1014 packages in 5.105s 75 | found 1 critical severity vulnerability 76 | run `npm audit fix` to fix them, or `npm audit` for details 77 | (11:54:08) ± [mofu@mofunoMacBook-Pro.local] ~/git/TB6-technical-writing-technic (textlint U:3 ✗) 78 | → npm audit fix 79 | up to date in 0.966s 80 | fixed 0 of 1 vulnerability in 1014 scanned packages 81 | 1 vulnerability required manual review and could not be updated 82 | ``` 83 | 84 | ルールセットを適用 85 | 86 | ```bash 87 | → ls -al 88 | total 312 89 | drwxr-xr-x 19 mofu staff 608 1 28 12:01 . 90 | drwxr-xr-x 7 mofu staff 224 1 28 11:35 .. 91 | drwxr-xr-x 13 mofu staff 416 1 28 11:54 .git 92 | -rw-r--r--@ 1 mofu staff 37 1 28 11:49 .gitignore 93 | -rw-r--r-- 1 mofu staff 7 1 28 11:43 .node-version 94 | -rw-r--r--@ 1 mofu staff 0 1 28 12:01 .textlintrc ←追加 95 | -rw-r--r-- 1 mofu staff 98 1 28 11:35 Gemfile 96 | -rw-r--r-- 1 mofu staff 249 1 28 11:35 Gemfile.lock 97 | -rw-r--r-- 1 mofu staff 3215 1 28 11:35 Gruntfile.js 98 | -rw-r--r-- 1 mofu staff 1065 1 28 11:35 LICENSE 99 | -rw-r--r-- 1 mofu staff 132 1 28 11:35 README.md 100 | drwxr-xr-x 18 mofu staff 576 1 28 11:35 articles 101 | -rwxr-xr-x 1 mofu staff 283 1 28 11:35 build-in-docker.sh 102 | drwxr-xr-x 291 mofu staff 9312 1 28 11:54 node_modules 103 | -rw-r--r-- 1 mofu staff 111065 1 28 11:54 package-lock.json 104 | -rw-r--r-- 1 mofu staff 1307 1 28 11:54 package.json 105 | -rw-r--r-- 1 mofu staff 3477 1 28 11:35 redpen-conf-ja.xml 106 | -rwxr-xr-x 1 mofu staff 211 1 28 11:35 setup.sh 107 | ``` 108 | 109 | ``.textlintrc``の追加 110 | 111 | ```json 112 | { 113 | "filters": {}, 114 | "rules": { 115 | "preset-ja-technical-writing": true 116 | } 117 | } 118 | ``` 119 | 120 | textlintの実行 121 | 122 | ```bash 123 | node_modules/.bin/textlint --preset ja-technical-writing ./articles/markdown/*.md 124 | 125 | /Users/mofu/git/TB6-technical-writing-technic/articles/markdown/init-textlint.md 126 | 48:15 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 127 | 67:11 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 128 | 84:9 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 129 | 109:18 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 130 | 120:11 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 131 | 132 | /Users/mofu/git/TB6-technical-writing-technic/articles/markdown/think-body.md 133 | 15:18 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 134 | 17:20 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 135 | 17:32 error 弱い表現: "思います" が使われています。 ja-technical-writing/ja-no-weak-phrase 136 | 19:29 error 一文に二回以上利用されている助詞 "は" がみつかりました。 ja-technical-writing/no-doubled-joshi 137 | 19:38 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 138 | 20:22 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 139 | 20:24 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 140 | 20:25 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 141 | 22:8 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 142 | 22:37 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 143 | 22:62 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 144 | 22:107 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 145 | 26:12 error 一文に二回以上利用されている助詞 "は" がみつかりました。 ja-technical-writing/no-doubled-joshi 146 | 26:22 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 147 | 36:34 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 148 | 36:83 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 149 | 36:83 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 150 | 38:33 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 151 | 46:31 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 152 | 46:32 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 153 | 46:99 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 154 | 46:101 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 155 | 46:108 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 156 | 46:133 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 157 | 46:136 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 158 | 48:11 error 漢字が7つ以上連続しています: 本全体論理展開 ja-technical-writing/max-kanji-continuous-len 159 | 50:24 error 一文に二回以上利用されている助詞 "が" がみつかりました。 ja-technical-writing/no-doubled-joshi 160 | 53:60 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 161 | 55:18 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 162 | 57:1 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 163 | 57:49 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 164 | 57:84 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 165 | 65:21 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 166 | 69:30 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 167 | 69:81 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 168 | 69:89 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 169 | 69:106 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 170 | 73:21 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 171 | 73:24 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 172 | 73:38 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 173 | 75:1 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 174 | 75:29 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 175 | 75:30 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 176 | 75:94 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 177 | 77:52 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 178 | 81:82 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 179 | 81:89 error 一文に二回以上利用されている助詞 "ので" がみつかりました。 ja-technical-writing/no-doubled-joshi 180 | 81:105 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 181 | 81:141 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 182 | 81:141 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 183 | 85:35 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 184 | 85:50 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 185 | 89:1 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 186 | 89:41 error 一文に二回以上利用されている助詞 "が" がみつかりました。 ja-technical-writing/no-doubled-joshi 187 | 89:47 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 188 | 89:48 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 189 | 89:75 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 190 | 89:75 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 191 | 91:41 error 弱い表現: "かも" が使われています。 ja-technical-writing/ja-no-weak-phrase 192 | 91:49 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 193 | 91:89 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 194 | 91:111 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 195 | 91:111 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 196 | 93:61 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 197 | 93:62 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 198 | 93:69 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 199 | 95:1 error Line 95 sentence length(159) exceeds the maximum sentence length of 100. 200 | Over 59 characters ja-technical-writing/sentence-length 201 | 95:86 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 202 | 95:174 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 203 | 95:185 error 弱い表現: "思います" が使われています。 ja-technical-writing/ja-no-weak-phrase 204 | 95:190 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 205 | 95:203 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 206 | 97:1 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 207 | 97:43 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 208 | 97:59 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 209 | 101:14 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 210 | 101:85 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 211 | 101:101 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 212 | 101:148 error 弱い表現: "思う" が使われています。 ja-technical-writing/ja-no-weak-phrase 213 | 101:163 error 一文に二回以上利用されている助詞 "が" がみつかりました。 ja-technical-writing/no-doubled-joshi 214 | 105:34 error 弱い表現: "思います" が使われています。 ja-technical-writing/ja-no-weak-phrase 215 | 105:68 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 216 | 109:17 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 217 | 111:1 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 218 | 111:14 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 219 | 113:31 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 220 | 114:22 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 221 | 115:3 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 222 | 115:4 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 223 | 224 | ✖ 94 problems (94 errors, 0 warnings) 225 | ✓ 64 fixable problems. 226 | Try to run: $ textlint --fix [file] 227 | ``` 228 | 229 | ``npm run`` で実行できるようにする 230 | 231 | package.jsonへスクリプトを登録 232 | 233 | ```json 234 | "scripts": { 235 | "site": "cd site ; hugo --cleanDestinationDir", 236 | "global-bundler": "gem install bundler", 237 | "global": "npm run global-bundler", 238 | "postinstall": "bundle install", 239 | "pdf": "grunt pdf", 240 | "md": "grunt markdown", 241 | "html": "grunt html", 242 | "test": "npm run html", 243 | + "textlint": "node_modules/.bin/textlint --preset ja-technical-writing ./articles/markdown/*.md" 244 | }, 245 | ``` 246 | 247 | - node_modules/.binにコマンドが入っているのでそこを指定する 248 | - presetオプションでルールセットを指定する 249 | - 対象のテキストを指定する 250 | 251 | 最終的にこうしました（Re:VIEWとMarkdown、どちらもLintできるように） 252 | 253 | reviewファイルがなぜかうまくlintできないので、Re:VIEW用プラグインである[textlint-plugin-review](https://www.npmjs.com/package/textlint-plugin-review)をインストール 254 | 255 | ```bash 256 | → npm install --save-dev textlint-plugin-review 257 | npm WARN deprecated txt-ast-traverse@1.2.1: See https://github.com/textlint/textlint/issues/455 258 | npm WARN deprecated textlint-ast-test@1.1.4: See https://github.com/textlint/textlint/issues/455 259 | + textlint-plugin-review@0.3.3 260 | added 3 packages from 2 contributors and audited 1017 packages in 3.241s 261 | found 1 critical severity vulnerability 262 | run `npm audit fix` to fix them, or `npm audit` for details 263 | (11:36:45) ± [mofu@mofunoMacBook-Pro.local] ~/git/TB6-technical-writing-technic (textlint U:3 ?:1 ✗) 264 | → npm audit fix 265 | up to date in 0.997s 266 | fixed 0 of 1 vulnerability in 1017 scanned packages 267 | 1 vulnerability required manual review and could not be updated 268 | (11:36:53) ± [mofu@mofunoMacBook-Pro.local] ~/git/TB6-technical-writing-technic (textlint U:3 ?:1 ✗) 269 | ``` 270 | 271 | ``.textlintrc``を編集する 272 | 273 | ```json 274 | { 275 | "rules": { 276 | "preset-ja-technical-writing": true 277 | }, 278 | + "plugins": [ 279 | + "review" 280 | + ] 281 | } 282 | ``` 283 | 284 | 実行してみる 285 | 286 | ```bash 287 | (11:39:22) ± [mofu@mofunoMacBook-Pro.local] ~/git/TB6-technical-writing-technic (textlint U:3 ?:1 ✗) 288 | → ./node_modules/.bin/textlint --preset ja-technical-writing articles/think-toc.re 289 | 290 | /Users/mofu/git/TB6-technical-writing-technic/articles/think-toc.re 291 | 5:15 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 292 | 9:76 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 293 | 12:5 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 294 | 12:60 error 一文に二回以上利用されている助詞 "か" がみつかりました。 ja-technical-writing/no-doubled-joshi 295 | 16:9 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 296 | 23:29 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 297 | 25:21 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 298 | 29:1 error Line 29 sentence length(135) exceeds the maximum sentence length of 100. 299 | Over 35 characters ja-technical-writing/sentence-length 300 | 31:85 error 漢字が7つ以上連続しています: 創造性開発技法 ja-technical-writing/max-kanji-continuous-len 301 | 33:34 error 弱い表現: "思います" が使われています。 ja-technical-writing/ja-no-weak-phrase 302 | 35:58 error 一つの文で"、"を3つ以上使用しています ja-technical-writing/max-ten 303 | 37:17 error 一文に二回以上利用されている助詞 "は" がみつかりました。 ja-technical-writing/no-doubled-joshi 304 | 37:34 error 一文に二回以上利用されている助詞 "かも" がみつかりました。 ja-technical-writing/no-doubled-joshi 305 | 47:16 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 306 | 68:16 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 307 | 71:17 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 308 | 71:56 ✓ error "することができます"は冗長な表現です。"することが"を省き簡潔な表現にすると文章が明瞭になります。参考: http://qiita.com/takahi-i/items/a93dc2ff42af6b93f6e0 ja-technical-writing/ja-no-redundant-expression 309 | 73:18 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 310 | 75:22 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 311 | 77:4 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 312 | 86:79 error 一文に二回以上利用されている助詞 "に" がみつかりました。 ja-technical-writing/no-doubled-joshi 313 | 88:32 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 314 | 90:25 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 315 | 94:107 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 316 | 96:6 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 317 | 96:14 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 318 | 98:105 error 弱い表現: "かも" が使われています。 ja-technical-writing/ja-no-weak-phrase 319 | 102:84 error 弱い表現: "かも" が使われています。 ja-technical-writing/ja-no-weak-phrase 320 | 106:1 error Line 106 sentence length(214) exceeds the maximum sentence length of 100. 321 | Over 114 characters ja-technical-writing/sentence-length 322 | 114:29 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 323 | 116:21 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 324 | 116:48 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 325 | 326 | ✖ 32 problems (32 errors, 0 warnings) 327 | ✓ 1 fixable problem. 328 | Try to run: $ textlint --fix [file] 329 | ``` 330 | 331 | MarkdownとRe:VIEW、どちらも``npm run``で実行できるようにする 332 | 333 | ```json 334 | "scripts": { 335 | "site": "cd site ; hugo --cleanDestinationDir", 336 | "global-bundler": "gem install bundler", 337 | "global": "npm run global-bundler", 338 | "postinstall": "bundle install", 339 | "pdf": "grunt pdf", 340 | "md": "grunt markdown", 341 | "html": "grunt html", 342 | "test": "npm run html", 343 | + "textlint-markdown": "./node_modules/.bin/textlint --preset ja-technical-writing ./articles/markdown/*.md", 344 | + "textlint-review": "./node_modules/.bin/textlint --preset ja-technical-writing ./articles/*.re" 345 | }, 346 | ``` 347 | 348 | 実行してみる 349 | 350 | ```bash 351 | (11:40:29) ± [mofu@mofunoMacBook-Pro.local] ~/git/TB6-technical-writing-technic (textlint U:4 ?:1 ✗) 352 | → npm run textlint-review 353 | 354 | > TB6-technical-writing-technic@0.0.1 textlint-review /Users/mofu/git/TB6-technical-writing-technic 355 | > textlint --preset ja-technical-writing ./articles/*.re 356 | 357 | 358 | /Users/mofu/git/TB6-technical-writing-technic/articles/think-body.re 359 | 15:22 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 360 | 17:18 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 361 | 19:20 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 362 | 19:32 error 弱い表現: "思います" が使われています。 ja-technical-writing/ja-no-weak-phrase 363 | 21:29 error 一文に二回以上利用されている助詞 "は" がみつかりました。 ja-technical-writing/no-doubled-joshi 364 | 21:38 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 365 | 22:22 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 366 | 22:24 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 367 | 22:25 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 368 | 24:8 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 369 | 24:37 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 370 | 24:62 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 371 | 24:107 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 372 | 28:12 error 一文に二回以上利用されている助詞 "は" がみつかりました。 ja-technical-writing/no-doubled-joshi 373 | 28:22 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 374 | 30:23 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 375 | 38:34 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 376 | 38:83 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 377 | 38:83 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 378 | 40:33 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 379 | 44:7 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 380 | 48:31 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 381 | 48:32 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 382 | 48:99 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 383 | 48:101 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 384 | 48:108 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 385 | 48:133 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 386 | 48:136 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 387 | 50:11 error 漢字が7つ以上連続しています: 本全体論理展開 ja-technical-writing/max-kanji-continuous-len 388 | 52:24 error 一文に二回以上利用されている助詞 "が" がみつかりました。 ja-technical-writing/no-doubled-joshi 389 | 53:36 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 390 | 55:60 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 391 | 57:18 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 392 | 59:1 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 393 | 59:49 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 394 | 59:84 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 395 | 61:32 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 396 | 67:21 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 397 | 67:26 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 398 | 71:30 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 399 | 71:81 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 400 | 71:89 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 401 | 71:106 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 402 | 73:17 error 一文に二回以上利用されている助詞 "に" がみつかりました。 ja-technical-writing/no-doubled-joshi 403 | 73:33 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 404 | 75:21 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 405 | 75:24 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 406 | 75:38 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 407 | 77:1 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 408 | 77:29 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 409 | 77:30 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 410 | 77:94 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 411 | 79:52 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 412 | 83:82 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 413 | 83:89 error 一文に二回以上利用されている助詞 "ので" がみつかりました。 ja-technical-writing/no-doubled-joshi 414 | 83:105 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 415 | 83:141 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 416 | 83:141 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 417 | 85:20 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 418 | 87:35 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 419 | 87:50 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 420 | 89:22 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 421 | 91:1 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 422 | 91:41 error 一文に二回以上利用されている助詞 "が" がみつかりました。 ja-technical-writing/no-doubled-joshi 423 | 91:47 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 424 | 91:48 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 425 | 91:75 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 426 | 91:75 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 427 | 93:41 error 弱い表現: "かも" が使われています。 ja-technical-writing/ja-no-weak-phrase 428 | 93:49 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 429 | 93:89 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 430 | 93:111 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 431 | 93:111 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 432 | 95:61 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 433 | 95:62 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 434 | 95:69 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 435 | 97:1 error Line 97 sentence length(189) exceeds the maximum sentence length of 100. 436 | Over 89 characters ja-technical-writing/sentence-length 437 | 97:86 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 438 | 97:174 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 439 | 97:185 error 弱い表現: "思います" が使われています。 ja-technical-writing/ja-no-weak-phrase 440 | 97:190 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 441 | 97:203 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 442 | 99:1 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 443 | 99:43 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 444 | 99:59 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 445 | 101:17 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 446 | 103:14 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 447 | 103:85 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 448 | 103:101 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 449 | 103:148 error 弱い表現: "思う" が使われています。 ja-technical-writing/ja-no-weak-phrase 450 | 103:163 error 一文に二回以上利用されている助詞 "が" がみつかりました。 ja-technical-writing/no-doubled-joshi 451 | 105:13 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 452 | 107:34 error 弱い表現: "思います" が使われています。 ja-technical-writing/ja-no-weak-phrase 453 | 107:68 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 454 | 109:17 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 455 | 111:17 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 456 | 113:1 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 457 | 113:14 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 458 | 115:31 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 459 | 116:22 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 460 | 117:3 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 461 | 117:4 ✓ error Found invalid control character(BACKSPACE \u0008) ja-technical-writing/no-invalid-control-character 462 | 117:19 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 463 | 464 | /Users/mofu/git/TB6-technical-writing-technic/articles/think-content.re 465 | 7:1 error Line 7 sentence length(103) exceeds the maximum sentence length of 100. 466 | Over 3 characters ja-technical-writing/sentence-length 467 | 7:124 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 468 | 7:207 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 469 | 11:26 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 470 | 13:4 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 471 | 13:7 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 472 | 13:32 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 473 | 15:23 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 474 | 17:4 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 475 | 17:7 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 476 | 17:19 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 477 | 19:80 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 478 | 21:94 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 479 | 21:101 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 480 | 23:9 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 481 | 25:55 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 482 | 27:14 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 483 | 32:16 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 484 | 42:15 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 485 | 44:56 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 486 | 46:4 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 487 | 51:22 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 488 | 53:56 error 弱い表現: "思います" が使われています。 ja-technical-writing/ja-no-weak-phrase 489 | 55:34 error 一文に二回以上利用されている助詞 "が" がみつかりました。 ja-technical-writing/no-doubled-joshi 490 | 66:23 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 491 | 66:30 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 492 | 66:35 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 493 | 69:22 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 494 | 71:85 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 495 | 74:17 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 496 | 80:45 error "て" が連続して2回使われています。 ja-technical-writing/ja-no-successive-word 497 | 80:57 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 498 | 85:10 error 一文に二回以上利用されている助詞 "よりは" がみつかりました。 ja-technical-writing/no-doubled-joshi 499 | 89:9 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 500 | 97:30 error 弱い表現: "思う" が使われています。 ja-technical-writing/ja-no-weak-phrase 501 | 97:72 error 弱い表現: "思う" が使われています。 ja-technical-writing/ja-no-weak-phrase 502 | 99:46 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 503 | 100:27 error 弱い表現: "思う" が使われています。 ja-technical-writing/ja-no-weak-phrase 504 | 100:59 error 弱い表現: "思う" が使われています。 ja-technical-writing/ja-no-weak-phrase 505 | 102:28 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 506 | 104:17 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 507 | 107:46 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 508 | 107:76 error "〇" が連続して2回使われています。 ja-technical-writing/ja-no-successive-word 509 | 107:112 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 510 | 109:11 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 511 | 109:14 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 512 | 109:40 error 弱い表現: "思います" が使われています。 ja-technical-writing/ja-no-weak-phrase 513 | 111:26 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 514 | 111:34 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 515 | 111:67 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 516 | 111:82 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 517 | 111:86 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 518 | 111:94 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 519 | 111:112 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 520 | 111:113 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 521 | 111:113 error "？" が連続して2回使われています。 ja-technical-writing/ja-no-successive-word 522 | 111:131 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 523 | 113:40 error Line 113 sentence length(142) exceeds the maximum sentence length of 100. 524 | Over 42 characters ja-technical-writing/sentence-length 525 | 113:181 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 526 | 115:45 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 527 | 117:1 error Line 117 sentence length(119) exceeds the maximum sentence length of 100. 528 | Over 19 characters ja-technical-writing/sentence-length 529 | 117:55 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 530 | 117:68 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 531 | 117:69 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 532 | 117:69 error "！" が連続して2回使われています。 ja-technical-writing/ja-no-successive-word 533 | 117:70 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 534 | 117:70 error "！" が連続して2回使われています。 ja-technical-writing/ja-no-successive-word 535 | 117:101 error "て" が連続して2回使われています。 ja-technical-writing/ja-no-successive-word 536 | 117:106 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 537 | 120:87 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 538 | 122:3 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 539 | 122:17 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 540 | 129:55 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 541 | 138:38 error 弱い表現: "思います" が使われています。 ja-technical-writing/ja-no-weak-phrase 542 | 140:3 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 543 | 142:19 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 544 | 142:20 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 545 | 142:21 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 546 | 142:22 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 547 | 142:23 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 548 | 142:24 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 549 | 142:25 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 550 | 142:26 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 551 | 142:27 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 552 | 142:28 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 553 | 142:29 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 554 | 142:30 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 555 | 142:31 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 556 | 142:32 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 557 | 558 | /Users/mofu/git/TB6-technical-writing-technic/articles/think-toc.re 559 | 5:15 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 560 | 9:76 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 561 | 12:5 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 562 | 12:60 error 一文に二回以上利用されている助詞 "か" がみつかりました。 ja-technical-writing/no-doubled-joshi 563 | 16:9 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 564 | 23:29 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 565 | 25:21 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 566 | 29:1 error Line 29 sentence length(135) exceeds the maximum sentence length of 100. 567 | Over 35 characters ja-technical-writing/sentence-length 568 | 31:85 error 漢字が7つ以上連続しています: 創造性開発技法 ja-technical-writing/max-kanji-continuous-len 569 | 33:34 error 弱い表現: "思います" が使われています。 ja-technical-writing/ja-no-weak-phrase 570 | 35:58 error 一つの文で"、"を3つ以上使用しています ja-technical-writing/max-ten 571 | 37:17 error 一文に二回以上利用されている助詞 "は" がみつかりました。 ja-technical-writing/no-doubled-joshi 572 | 37:34 error 一文に二回以上利用されている助詞 "かも" がみつかりました。 ja-technical-writing/no-doubled-joshi 573 | 47:16 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 574 | 68:16 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 575 | 71:17 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 576 | 71:56 ✓ error "することができます"は冗長な表現です。"することが"を省き簡潔な表現にすると文章が明瞭になります。参考: http://qiita.com/takahi-i/items/a93dc2ff42af6b93f6e0 ja-technical-writing/ja-no-redundant-expression 577 | 73:18 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 578 | 75:22 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 579 | 77:4 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 580 | 86:79 error 一文に二回以上利用されている助詞 "に" がみつかりました。 ja-technical-writing/no-doubled-joshi 581 | 88:32 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 582 | 90:25 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 583 | 94:107 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 584 | 96:6 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 585 | 96:14 error Disallow to use "？" ja-technical-writing/no-exclamation-question-mark 586 | 98:105 error 弱い表現: "かも" が使われています。 ja-technical-writing/ja-no-weak-phrase 587 | 102:84 error 弱い表現: "かも" が使われています。 ja-technical-writing/ja-no-weak-phrase 588 | 106:1 error Line 106 sentence length(214) exceeds the maximum sentence length of 100. 589 | Over 114 characters ja-technical-writing/sentence-length 590 | 114:29 error 文末が"。"で終わっていません。 ja-technical-writing/ja-no-mixed-period 591 | 116:21 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 592 | 116:48 error Disallow to use "！" ja-technical-writing/no-exclamation-question-mark 593 | 594 | ✖ 224 problems (224 errors, 0 warnings) 595 | ✓ 65 fixable problems. 596 | Try to run: $ textlint --fix [file] 597 | ``` 598 | 599 | これで準備できました。 600 | 601 | ## 参考文献 602 | 603 | ### textlint 604 | 605 | - [textlint-plugin-review](https://www.npmjs.com/package/textlint-plugin-review) 606 | 607 | ### 実際にtextlintを導入している人々 608 | 609 | - [Re:VIEWで書いた文章の校正をCircleCIとtextlintでGitHubのPRに自動コメントする仕組み](http://blog.naoshihoshi.com/entry/2018/10/15/113000) -------------------------------------------------------------------------------- /articles/markdown/poish-your-text.md: -------------------------------------------------------------------------------- 1 | # 技術同人誌を書くための文章技術 原稿をより良くするための表現法編 2 | 3 | こんにちは。りまりま団のもふもふです。 4 | 5 | 技術書典6、もうすぐサークル申し込みの締め切り日です。迷っている人はおはやめに手続きしてしまいましょう。 6 | 7 | このエントリでは下記3つのエントリを受けて、自分の書いた文章をより伝わりやすく改善するためのヒントをお伝えします。 8 | 9 | まだ本文も書けてない？それならこのエントリを読んで本文を書きましょう。これから話すことは**本文が書けてから**実施するべき事項です。詳しい理由はエントリを参照して欲しいのですが、あれこれ考えて手が止まってしまうのが1番良くないことです。 10 | 11 | ## 原稿の推敲はなぜ大切なのか？ 12 | 13 | 推敲という言葉があります。 14 | 商業誌では、編集者があなたの代わりに推敲を行います。[^suikou] あなたは提案された案を受け入れるか決め、原稿を修正するだけです。 15 | 16 | [^suikou]: Twitterを見ていると、ひどい編集者の話もあったりします。また、編集者の方から技術的な観点での推敲は受けにくいと言われています（外部レビューを頼むことが多いです）。ですが、ここでは考慮しません。 17 | 18 | しかし、同人誌には編集者が付いていません。自分で行う必要があるのです。[^goudou] 19 | 20 | [^goudou]: 合同誌に寄稿する場合は除きます。 21 | 22 | 原稿を書き上げたあなたはこう言うでしょう、「頑張って本文も書けた。もう疲れたし遊びたいし他のことしたいから入稿しちゃえ！」と。 23 | 24 | ちょっと待ってください。推敲は絶対にやるべきです。**わかりやすい文章であればあるほど、あなたが広めたい技術を他人に伝えることができるから**です。 25 | 26 | 大して変わらないから大丈夫？では、この文章を見てください。 27 | 28 | - データの内訳に応じて円が分かれていきます。 円を分ける条件を指定しないとデータの総件数が表示されるだけなので、パイを分割する設定を一緒に入れましょう。[^kibana] 29 | - 円グラフを作成するための機能です。データの内訳を分析する用途で利用します。設定を変更すれば、円の中央が空いている”ドーナツ型”のグラフを作成することも可能です。[^pie] 30 | 31 | [^kibana]: これは技術書典2のときに書いた「ログと情報をレッツ・ラ・まぜまぜ！～ELK Stack で作るBI環境～」という本の初稿です。 32 | [^pie]: この文章は、このブログを書くときに書きました。初稿を書いたときから2年弱経っています。続ければそれなりにうまくなるものですね。 33 | 34 | 実はこれ、どちらもKibanaというプロダクトの``Pie Chart``という機能を説明したものです。画像の右上にドーナツ型の円がありますね。それがPie Chartのグラフです。 35 | 36 |
37 | 38 | [f:id:MofuMofu:20190126183007j:plain]
Kibanaの画面例
[https://www.elastic.co/guide/en/kibana/current/pie-chart.html:embed:cite] 39 | 40 | 41 | 42 | この機能の詳細は、本題ではないため割愛します。言葉の使い方・文章の並べ方・句読点の違いで全然印象が違うのがわかりますか？ 43 | 44 | はじめの文章は「？？？」と思う点がたくさんあるように感じたのではないでしょうか。「データの内訳に応じて円が別れていきます」と言われて「Pie Chartを使うと円グラフが描ける」とすぐ解釈できる人は少ないと思います。 45 | この「？？？」という感情が蓄積されると、本に対する印象は「読みにくい本」へ変化します。こうなってしまうと、あなたの伝えたいことは3割程度しか伝わりません。あなたの努力は水の泡、です。 46 | 47 | 読者の読解力の問題だ！と思われる方もいるでしょう。ここで『20歳の自分に受けさせたい文章講義 (星海社新書)』から、私が1番好きな文を引用したいと思います。[^seikai] 48 | 49 | [https://www.seikaisha.co.jp/information/2011/12/20-post-71.html:embed:cite] 50 | 51 | [^seikai]: 新書なので電子版は存在しません。しかし、内容は一読する価値があります。本の感想や紹介は[Amazonのカスタマーレビュー](https://www.amazon.co.jp/20%E6%AD%B3%E3%81%AE%E8%87%AA%E5%88%86%E3%81%AB%E5%8F%97%E3%81%91%E3%81%95%E3%81%9B%E3%81%9F%E3%81%84%E6%96%87%E7%AB%A0%E8%AC%9B%E7%BE%A9-%E6%98%9F%E6%B5%B7%E7%A4%BE%E6%96%B0%E6%9B%B8-%E5%8F%A4%E8%B3%80-%E5%8F%B2%E5%81%A5/product-reviews/4061385100)に譲りますが、私は大学生のときにこの本に出会えて本当に良かった、と思っています。 52 | 53 | > 専門書やマニア向けの雑誌などが（一般読者にとって）読みづらいのは、このためだ。出てくる言葉が難しいのではない。読者に甘え、本来やるべき説明を怠っているから、読みづらいのである。 54 | 55 | 私も同感です。「伝わらない」のは読者のせいではありません。本を書いた人の責任です。古賀さんは「専門性に逃げるのは、書き手の怠慢であり、甘えにすぎないのだ」と表現しています。 56 | 57 | 専門書の位置づけで技術同人誌を書くのであればまだしも、タイトルやキャッチコピーに「わかりやすい」「初心者の/はじめての」といれるのであれば、絶対に専門用語でのゴリ押しは避けるべきです。 58 | 59 | あなたが思っている以上にタイトル詐欺の本は多いです。例えば、特定の技術のAPIに関する解説だけしか書かれていない本を初心者が読み、「わからない」と言われたときですら、本を作った人に落ち度があるのです。対象読者をきちんと定め、誰が見てもわかるように明記する（誤解ないように宣伝する）のは本を作る人がやるべきことです。 60 | 61 | 読者というものは勝手なように見えるかもしれません。理不尽なのはわかります。しかし、読者はあなたの書いた本からしか情報を取得できません。わからないことは調べて読んでほしい？行間を読んでほしい？技術書に対するAmazonのレビューをみれば、そんなものは幻想だとわかります。 62 | 63 | 読者のためにも、あなたのためにも推敲はやりましょう。 64 | 65 | ## 推敲する観点 66 | 67 | 普段の生活で推敲をすることはどのくらいありますか？メール文化の中にいれば、そこそこあるかもしれません。チャットだと少ないのではと思います。 68 | 69 | 推敲できるか不安なあなたへ、もふもふちゃん調べの推敲観点ランキングを発表します。 70 | 71 | 1. 語調・記法は統一されているか 72 | 1. 接続詞の用法は正しいか 73 | 1. 句読点の量と位置 74 | 1. 一文の長さは40文字以内か 75 | 1. 初見の単語には意味の解説があるか 76 | 1. 助詞の使い方は正しいか 77 | 78 | **4位までの観点は絶対にやっておきましょう**。 79 | 80 | 原稿を作成している環境によって、使えるやり方が変わってきますが、いくつかおすすめのやり方を挙げておきます。 81 | 82 | ### 紙出しする 83 | 84 | ベタですが、一度紙に印刷する方法です。紙出しの利点は、**原稿の仕上がりサイズを直接確認できる点**です。 85 | 86 | 字や段落が詰まって読みにくいという点をにチェックするためには、一度紙出しするのが確実です。 87 | 88 | インク代や紙代がかかるので、ほぼ完成となったところで紙出しすると良いでしょう。とはいえ技術同人誌を作るのが初めての場合、紙面で仕上がりを確認する工程はサボらない方が良いです。 89 | 90 | ### タブレットを使う 91 | 92 | 私はPDFをiPadに送信し、Apple pencil（初代の😡）で赤入れすることが多いです。 93 | 94 | 紙出しの手間を省きつつ、作業環境と別のディスプレイで確認することで、見落としを防ぐようにしています。 95 | 96 | タブレットを持っていない場合、初期購入費用がかかるのが難点です。 97 | 98 | ### lintツールを使う 99 | 100 | lintツールを使いたい！そんな人もいるでしょう。技術同人誌界隈で利用が観測されたツールを紹介します。 101 | 102 | 103 | [https://github.com/textlint/textlint:embed:cite] 104 | 105 | [https://github.com/prh/prh:embed:cite] 106 | 107 | [http://redpen.cc/docs/latest/index_ja.html:embed:cite] 108 | 109 | 110 | 注意点として、 111 | 112 | - テキスト形式の原稿にしか使えない 113 | - 論理構成や話の流れなどはチェックできない 114 | 115 | ことがあります。最後は自分で確認することには変わりません。 116 | 117 | ただ、助詞の使い方・句読点の量・一文の長さはlintツールが自動で教えてくれます。とにかく文章を書くのに自信がない場合、lintツールに助けてもらうのも良いでしょう。 118 | 119 | ## まとめ 120 | 121 | - 推敲は大事だよ 122 | - 伝わらないと負けだよ 123 | 124 | 推敲に時間をかけるためにも、本文は早いとこ完成させましょうね！ -------------------------------------------------------------------------------- /articles/markdown/think-body.md: -------------------------------------------------------------------------------- 1 | こんにちは。りまりま団のもふもふです。 2 | 3 | このエントリは、下2つのエントリからの続きモノです。 4 | 5 | 6 | 7 | [http://rimarimadan.hatenablog.com/entry/2019/01/07/210011:embed:cite] 8 | 9 | 10 | [http://rimarimadan.hatenablog.com/entry/2019/01/09/215308:embed:cite] 11 | 12 | 13 | ## 文章を書こうとすると手が止まってしまう 14 | 15 | 今までのエントリでは、技術同人誌を書き始めるまでに立ちはだかる、心理的な壁を払拭するための施策についてお話ししました。 16 | 17 | 既に、心は技術書執筆、やっていきですぞ！という気持ちなのではと思います。 18 | 19 | しかし、いざ書き始めると、手が止まってしまう人は多いのではないでしょうか。 20 | ここでの文章とは、最低1万字から始まる長文のことを指しています。チャットやSNS・メールのように、100〜500文字の文ではありません。 21 | 22 | 「い、1万字…？」と思ったあなた。これ、少ないんですよ。仮に1行40文字・1ページへ36行の設定を行なった場合、1ページに1440文字記載されます。60ページ分本文を書く場合、1440(文字) × 60（p） = 86400文字必要です。コードブロックや図形を挿入するとしても、6万字程度は文章を書くことになります。 23 | 24 | この時点で、文章を書くことに苦手意識がある人は心が折れてしまいそうです。 25 | 26 | それでも、私は「あなたは同人誌を一冊作れる！」と言いたいのです。 27 | 28 | ## 目次の中で1番好きなところから手をつける 29 | 30 | [http://rimarimadan.hatenablog.com/entry/2019/01/09/215308:embed:cite] 31 | 32 | このエントリでは、まず目次を出しましょう、という話をしました。あなたの手元には、既に目次のリストがあるはずです。 33 | 34 | リストの中から1番好きなところ・1番言いたいところを選びましょう。そして**そこから**書き始めましょう。本の頭から書こうとすると、手が止まってしまうのです。 35 | 36 | 本の構成は昔のあなたが決めてくれています。どこから書いたとしても、本全体の論理構成が大きく崩れることはありません。今は、内容を書くことだけに集中すれば良いのです。 37 | 38 | ここで重要なのは、**1つの工程が終わるまでは別のことをやらない**ことです。文章を書いているときに手が止まりやすい人は、次の作業を同時並行で進めようとする傾向があります。 39 | 40 | - 本文（解説文章や考察）の記載 41 | - コードブロック（プログラム・設定ファイル・コマンド・画面キャプチャなど）の記載 42 | - 文章の校正 43 | 44 | 大事なのは**文章の質を都度高めるよりも、書ききることを優先する**ということです。推敲[^suikou]は文章が全て出揃った時点で行うべきです。この理由を羅列します。 45 | 46 | [^suikou]: 師の字句や文章の構成を吟味して練り直すことです。（[コトバンク](https://kotobank.jp/word/%E6%8E%A8%E6%95%B2-5396890)）高校生の漢文の授業で推敲のエピソードをやった記憶があります。一字のために悩むのはエモいですよね。 47 | 48 | - 章ごとのつなぎ＝本全体論理展開がおかしくないかの確認・修正は文章が全て出揃わないとできない 49 | - 推敲時に各章の文章量の比率を調整することが多い 50 | - 推敲は文章を寝かせた後におこなった方が効率が良い 51 | - 締め切り近くになって本文が書けていない状態は心理的に負担になりやすい 52 | 53 | **印刷所に出す時点で読める原稿になっていれば良いのです**。最初から完璧な原稿が書ける人は存在しません。まずは一通りの完成段階まで持っていきましょう。 54 | 55 | ## どんな順番で記載するといいの？ 56 | 57 | ここで頭の良いあなたは、「書ききった方がいいのはわかった。じゃあ実際どんな順番で書けばいいのよ？」と思っているのではないでしょうか。あなたの置かれている状況に応じて書く順序を変えたほうが良いので、状況ごとに分けて記載します。 58 | 59 | ### 取り扱う技術に関するコードや設定ファイルが手元にある場合 60 | 61 | 次の事例に当てはまる場合、コードや設定ファイル等をコードブロックとして目次の下に挿入する作業から取り掛かりましょう。このとき、書きたい話の流れに沿って貼り付けておくと楽ができます。文章を記載するとき、コードブロックの並び替えが不要になるためです。 62 | 63 | - 載せる予定のコードが80%以上書けている 64 | - 動作する設定ファイルが手元に80%以上揃っている 65 | - 書きたい内容に関するログのストックを持っている 66 | 67 | 要は、**「成果物がある人」はそれを本文として映えるように整理して本文にする作業から行いましょう**、ということです。 68 | 69 | 先にコードブロックで本文の骨組みを作成し、コードブロックの解説を本文として記載する作戦です。自分の実装内容について語ればよいので、何を書いて良いかがわからない！という悩みなく本文を作成できるはずです。さらに、コードブロックの分量で「何かしら進んでいる」という安心感を得ることができます。 70 | 71 | ## 上記に当てはまらない（手元に成果物がない/これから作る）場合 72 | 73 | これからコードブロック内に載せる成果物を作成しようとする場合、まず**本文の文章**から記載しましょう。 74 | 75 | 文章を書き慣れていない人が「手を動かすのは早い方だから」とコードブロック内の成果物を作成しようとするのは避けるべきです。技術的にハマってしまった場合、本文を作成するために利用できる時間がどんどん無くなってしまうからです。 76 | 77 | 先に本文ができていれば、最悪コードブロックなしでも入稿することは可能です。しかし、手元に何もないと入稿すらできません。待っているのは**新刊が落ちた**という事実です。 78 | 79 | 後々焦らないようにするためには、**何かしら目に見える形で進捗をつくる**ことが重要です。 80 | 81 | 本文を記載しておくと良いこともあります。それは、自分の書いた文章を見ながらコードを作成・実行できることです。「この解説とやりたいことがずれているので修正しよう」「わかりにくいので解説をもう少し膨らませよう」など、本文の内容に対し、自分で自分にフィードバックを得やすくなります。 82 | 83 | ## 本文の内容を膨らませるためのヒント 84 | 85 | 本文を書く順番に関する知見を得ることができました。最後に必要なのは、「どんな内容を書けば良いのか？」という知見です。基本的に好きなことを書けば良いのですが、次の観点を入れると分かりやすさを増すことができます。 86 | 87 | ### 環境構築ではOS差異を網羅すると良い 88 | 89 | 技術同人誌をいくつかめくってみると、Mac OSで動作確認している人が多い印象があります。想定環境が記載されていない本もちらほらと見かけます。 90 | 91 | ただ、どんな人が本を読むかはわかりませんよね。読者がWindowsを利用しているかもしれません。Windows利用者にあなたの好きな技術を広めるのであれば、Windowsでの動作方法が記載されていた方が良いですよね。 92 | 93 | 特にインフラ・ミドルウェアに関する内容を書こうとしている方は、できればOSごとに構築手順の違いを網羅しておくと良いです。実際に環境を持つことが大変なのであれば、公式ドキュメントの環境構築手順のURLを添付しておくだけでも良いです。 94 | 95 | もふもふちゃんの『[Elastic Stackで作るBI環境](http://amzn.asia/d/be7bGtk)』という本がニッチなジャンルでも息が長かった原因は「本で利用しているミドルウェア全てにおいて、Windows・Debian系Linux・CentOS系Linux・Mac OSでの環境構築方法とセットアップ方法が記載されている」からなのではないかと思います。公式ドキュメントのどこに環境構築方法が書いてあるかわからないのであれば、本を読みながら設定したいですよね。 96 | 97 | 環境構築方法を丁寧に書いておくことは、将来の自分を大いに救ってくれるでしょう。私も本の改版時は自分の本を見ながらセットアップをやりました。 98 | 99 | ### 動作確認方法をしっかりと 100 | 101 | コードブロック内のコードが、コピー＆ペーストだけで実行できるかは必ず確認しましょう。あなたの予想以上に、本の通りにできないと戸惑う人は多いです。Amazonで技術書のレビューを読んでみてください。コードが動作しないとネガティヴな印象を持つ人はたくさんいます。人間間違えるからしょうがないと思うのですが、間違えがないほうが良いに決まっています。 102 | 103 | ### 参考文献を記載する 104 | 105 | 本の作成をするときに、自分の理解や主張は間違っていないか確認すると思います。調べた物のURLや本のタイトルを載せておくと良いでしょう。文量をカサ増しできますし、読者も文献を探す手間を省くことができるので一石二鳥です。 106 | 107 | ### 「ハマりどころ」を記載する 108 | 109 | 「ハマりどころ」とは、その技術を利用しているときに遭遇しやすいエラー文や設定ミスのことです。あなたが困った部分は他の人も困るはずです。将来の自分を助けると思って、ハマりどころとその対処法を記載しておくと良いでしょう。私は今までこれに何度も救われてきました。 110 | 111 | 文章、書けそうでしょうか？ 112 | 113 | - コードや設定ファイルがあるならコードブロックを目次の下に貼り付ける。順序を気にすると後で楽ができる。 114 | - これから作る場合、本文をとにかく書く。推敲は全部できてから。 115 | - 将来の自分を助けるつもりで書く 116 | 117 | これで「書きたいのに何も書けない」状態を回避できるはずです。 -------------------------------------------------------------------------------- /articles/qr.re: -------------------------------------------------------------------------------- 1 | = おまけ 2 | 3 | 本のダウンロードコードです。ダウンロード期限などはありません。 4 | 5 | 6 | GitHubリポジトリ（@{https://github.com/MofuMofu2/TB6-technical-writing-technic}）がPublicなこともあり、 7 | 再配布は制限していません。ただ、頑張って書いたので作者Twitter（@{https://twitter.com/froakie0021}）に感想を送ってもらうか 8 | イベント時にお菓子を恵んでもらえると嬉しいです。 9 | 10 | -------------------------------------------------------------------------------- /articles/references.re: -------------------------------------------------------------------------------- 1 | = 参考文献 2 | 3 | == 登場したりまりま団作品 4 | 5 | * ログと情報をレッツ・ラ・まぜまぜ！～ELK Stack で作るBI環境～ 6 | ** @{https://booth.pm/ja/items/666613} 7 | 8 | == 原稿を書き始める前の準備 9 | 10 | === 印刷所関連 11 | 12 | * キンコーズ 13 | ** @{https://www.kinkos.co.jp/} 14 | 15 | * 有限会社ねこのしっぽ 16 | ** @{https://www.shippo.co.jp/neko/} 17 | 18 | * 株式会社日光企画 19 | ** @{http://www.nikko-pc.com/index/top.html} 20 | 21 | === ブレインストーミング 22 | 23 | * コトバンク 24 | ** @{https://kotobank.jp/word/ブレインストーミング-180594} 25 | 26 | 27 | 28 | == 推敲してより良い原稿を作成する 29 | 30 | * コトバンク：推敲 31 | ** @{https://kotobank.jp/word/%E6%8E%A8%E6%95%B2-539689} 32 | 33 | * 古賀史健（2012）２０歳の自分に受けさせたい文章講義　星海社新書 34 | ** @{https://www.seikaisha.co.jp/information/2011/12/20-post-71.html} 35 | 36 | === 一括置換 37 | 38 | * テキストを検索および置換する（Microsoft Office） 39 | ** @{https://support.office.com/ja-jp/article/テキストを検索および置換する-c6728c16-469e-43cd-afe4-7708c6c779b7} 40 | 41 | === 接続詞 42 | 43 | * ベネッセ教育サイト 【国語文法】 接続詞とはなんですか？ 44 | ** @{https://benesse.jp/teikitest/chu/japanese/japanese/c00508.html} 45 | 46 | * 共同通信社（2016）記者ハンドブック第13版 47 | ** @{https://www.kyodo.co.jp/books/isbn/978-4-7641-0687-1/} 48 | 49 | * 接続詞・接続的副詞[句]・接続助詞の種類（日英）（有限会社西尾情報処理事務所） 50 | ** @{http://www.nipo.co.jp/conjunc1.htm} 51 | 52 | === 助詞 53 | 54 | * 東京外国語大学言語モジュール 55 | ** @{http://www.coelang.tufs.ac.jp/mt/ja/gmod/contents/explanation/052.html} 56 | 57 | === 書体 58 | 59 | * 書体の使い分けー伝わるデザイン 研究発表のユニバーサルデザイン 60 | ** @{http://tsutawarudesign.com/yomiyasuku1.html} 61 | 62 | == 静的検査ツールを利用する 63 | 64 | === textlint 65 | 66 | * textlint 67 | ** @{https://efcl.info/2015/09/10/introduce-textlint/} 68 | 69 | === プラグイン 70 | 71 | * textlint-plugin-review 72 | ** @{https://www.npmjs.com/package/textlint-plugin-review} 73 | 74 | * プラグインの紹介ページ 75 | ** @{https://github.com/textlint-ja} 76 | 77 | === 実際にtextlintを導入している人々 78 | 79 | * Re:VIEWで書いた文章の校正をCircleCIとtextlintでGitHubのPRに自動コメントする仕組み 80 | ** @{http://blog.naoshihoshi.com/entry/2018/10/15/113000} 81 | -------------------------------------------------------------------------------- /articles/sty/jumoline.sty: -------------------------------------------------------------------------------- 1 | %% 2 | %% This is file `jumoline.sty', 3 | %% generated with the docstrip utility. 4 | %% 5 | %% The original source files were: 6 | %% 7 | %% jumoline.dtx (with options: `package') 8 | %% 9 | %% IMPORTANT NOTICE: 10 | %% 11 | %% For the copyright see the source file. 12 | %% 13 | %% You are *not* allowed to modify this file. 14 | %% 15 | %% You are *not* allowed to distribute this file. 16 | %% For distribution of the original source see the terms 17 | %% for copying and modification in the file jumoline.dtx. 18 | %% 19 | %% Style file `jumoline'. 20 | %% Copyright (C) 1999-2001 Hiroshi Nakashima 21 | %% (Toyohashi Univ. of Tech.) 22 | %% 23 | %% This program can be redistributed and/or modified under the terms 24 | %% of the LaTeX Project Public License distributed from CTAN 25 | %% archives in directory macros/latex/base/lppl.txt; either 26 | %% version 1 of the License, or any later version. 27 | %% 28 | %% \CharacterTable 29 | %% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z 30 | %% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z 31 | %% Digits \0\1\2\3\4\5\6\7\8\9 32 | %% Exclamation \! Double quote \" Hash (number) \# 33 | %% Dollar \$ Percent \% Ampersand \& 34 | %% Acute accent \' Left paren \( Right paren \) 35 | %% Asterisk \* Plus \+ Comma \, 36 | %% Minus \- Point \. Solidus \/ 37 | %% Colon \: Semicolon \; Less than \< 38 | %% Equals \= Greater than \> Question mark \? 39 | %% Commercial at \@ Left bracket \[ Backslash \\ 40 | %% Right bracket \] Circumflex \^ Underscore \_ 41 | %% Grave accent \` Left brace \{ Vertical bar \| 42 | %% Right brace \} Tilde \~} 43 | %% 44 | %% 45 | \def\next{LaTeX2e} 46 | \ifx\fmtname\next 47 | \def\next{ 48 | \NeedsTeXFormat{LaTeX2e}[1994/12/01] 49 | \ProvidesPackage{jumoline}} 50 | \else\def\next[#1]{}\fi 51 | \next 52 | [2001/05/31 v1.2 ] 53 | 54 | \ifx\PackageError\undefined 55 | \def\PackageError#1#2#3{\@latexerr{#1:#2}{#3^^J\@ehc}} 56 | \fi 57 | 58 | %%^L 59 | 60 | %% Register Declaration 61 | 62 | \newdimen\UnderlineDepth \UnderlineDepth-\maxdimen 63 | \newdimen\MidlineHeight \MidlineHeight-\maxdimen 64 | \newdimen\OverlineHeight \OverlineHeight-\maxdimen 65 | \newdimen\UMOlineThickness \UMOlineThickness.4pt 66 | 67 | \newdimen\UMO@height \newdimen\UMO@depth 68 | \newdimen\UMO@dqspace \newdimen\UMO@tempdim 69 | 70 | \newskip\UMO@prejfmglue \newskip\UMO@postjfmglue 71 | 72 | \newcount\UMO@mode 73 | \let\UMO@afterblock\z@ 74 | \let\UMO@afterword\@ne 75 | \let\UMO@afterchar\tw@ 76 | 77 | \newcount\UMO@spacefactor 78 | \newcount\UMO@firstxspcode 79 | \newcount\UMO@lastxspcode 80 | \newcount\UMO@inhibitxspcode 81 | \newcount\UMO@prebreakpenalty 82 | \newcount\UMO@postbreakpenalty 83 | \newcount\UMO@kpostbreakpenalty 84 | 85 | \newif\ifUMO@nospace \newif\ifUMO@firstelem 86 | 87 | %%^L 88 | 89 | %% User Interface and Initialization 90 | 91 | \def\Underline{\UMO@line\UnderlineDepth{-\UnderlineDepth}{-\dp\strutbox}} 92 | \def\Midline{\setbox\@tempboxa\hbox{$B$"(B}% 93 | \UMO@line\MidlineHeight\MidlineHeight{.5\ht\@tempboxa}} 94 | \def\Overline{\UMO@line\OverlineHeight\OverlineHeight{\ht\strutbox}} 95 | \def\UMOline{\UMO@line{-\maxdimen}\z@} 96 | 97 | \def\UMO@line#1#2#3#4{\begingroup \let\\\UMOnewline 98 | \relax\ifdim#1<\z@ \UMO@height#3\relax 99 | \else \UMO@height#2\relax \fi 100 | \UMO@depth-\UMO@height 101 | \ifdim\UMO@height<\z@ \advance\UMO@depth\UMOlineThickness 102 | \else \advance\UMO@height\UMOlineThickness \fi 103 | \settowidth\UMO@dqspace{$B!H(B}\advance\UMO@dqspace-1zw 104 | \UMO@dqspace-\UMO@dqspace \divide\UMO@dqspace\tw@ 105 | \UMO@nospacetrue \UMO@firstelemtrue 106 | \UMO@mode\UMO@afterblock 107 | \ifvmode\leavevmode\fi 108 | \def\@tempa{#4 }\edef\@tempb{\noexpand\@nil\space}% 109 | \expandafter\expandafter\expandafter\UMO@wordloop 110 | \expandafter\@tempa\@tempb 111 | \endgroup \UMO@aftergroup} 112 | 113 | %%^L 114 | 115 | %% Processing Word Elements 116 | 117 | \def\UMO@wordloop{\UMO@ifbgroup\UMO@wordblock\UMO@iwordloop} 118 | \def\UMO@ifbgroup#1#2{\let\@tempa#1\let\@tempb#2\futurelet\@tempc\UMO@ifnc} 119 | \def\UMO@ifnc{\ifx\@tempc\bgroup \let\next\@tempa \else\let\next\@tempb \fi 120 | \next} 121 | \def\UMO@wordblock#1{\UMO@spaceskip 122 | \UMO@putbox\relax{#1}\UMO@nospacetrue \UMO@mode\UMO@afterblock 123 | \UMO@spacefactor\@m \UMO@wordloop} 124 | \def\UMO@iwordloop#1 {\def\@tempa{#1}\ifx\@tempa\@nnil \let\next\UMO@end 125 | \else 126 | \ifx\@tempa\empty \UMO@nospacefalse 127 | \else 128 | \UMO@spaceskip \UMO@mode\UMO@afterblock 129 | \def\UMO@theword{}\UMO@firstxspcode\m@ne 130 | \UMO@charloop#1\@nil \fi 131 | \let\next\UMO@wordloop \fi 132 | \next} 133 | 134 | %%^L 135 | 136 | %% Interword Spacing 137 | 138 | \def\UMO@spaceskip{\ifUMO@nospace \UMO@nospacefalse \else 139 | \ifdim\spaceskip=\z@ 140 | \@tempdima\fontdimen3\font\relax 141 | \multiply\@tempdima\UMO@spacefactor \divide\@tempdima\@m 142 | \@tempdimb\fontdimen4\font\relax \multiply\@tempdimb\@m 143 | \divide\@tempdimb\UMO@spacefactor 144 | \@tempskipa\fontdimen2\font plus\@tempdima minus\@tempdimb\relax 145 | \else 146 | \edef\@tempa{\the\spaceskip\space @ @ @ @ }% 147 | \expandafter\UMO@setspaceskip\@tempa\@nil 148 | \fi 149 | \ifnum\UMO@spacefactor<2000\else 150 | \ifdim\xspaceskip=\z@ \advance\@tempskipa\fontdimen7\font 151 | \else \@tempskipa\xspaceskip 152 | \fi\fi 153 | \UMO@skip\@tempskipa \fi} 154 | \def\UMO@setspaceskip#1 #2 #3 #4 #5 #6\@nil{\@tempdima\z@ \@tempdimb\z@ 155 | \def\@tempa{#2}\def\@tempb{#3}% 156 | \ifx\@tempa\UMO@plus \@tempdima#3\def\@tempa{#4}\def\@tempb{#5}\fi 157 | \ifx\@tempa\UMO@minus \@tempdimb\@tempb\relax\fi 158 | \multiply\@tempdima\UMO@specefactor \divide\@tempdima\@m 159 | \multiply\@tempdimb\@m \divide\UMO@spacefactor 160 | \@tempskipa#1 plus\@tempdima minus\@tempdimb\relax} 161 | \def\@tempa#1 #2 #3 #4 #5\@nil{\def\UMO@plus{#2}\def\UMO@minus{#4}} 162 | \@tempskipa1pt plus 2pt minus 3pt 163 | \expandafter\@tempa\the\@tempskipa\@nil 164 | 165 | %%^L 166 | 167 | %% Processing Characters 168 | 169 | \def\UMO@charloop{\UMO@ifbgroup\UMO@charblock\UMO@icharloop} 170 | \def\UMO@charblock#1{\UMO@putword 171 | \UMO@putbox\relax{#1}\UMO@mode\UMO@afterblock \UMO@spacefactor\@m 172 | \UMO@charloop} 173 | \def\UMO@icharloop#1{\def\@tempa{#1}% 174 | \ifx\@tempa\@nnil \UMO@putword \let\next\relax 175 | \else\ifx\UMOspace#1\relax \UMO@putword \let\next\UMO@space 176 | \else\ifx\UMOnewline#1\relax \UMO@putword \let\next\UMO@newline 177 | \else 178 | \ifnum`#1<256\relax \edef\UMO@theword{\UMO@theword#1}% 179 | \ifnum\UMO@firstxspcode<\z@ 180 | \UMO@firstxspcode\xspcode`#1\relax 181 | \UMO@prebreakpenalty\prebreakpenalty`#1\relax 182 | \fi 183 | \UMO@lastxspcode\xspcode`#1\relax 184 | \UMO@postbreakpenalty\postbreakpenalty`#1\relax 185 | \else \UMO@putword \UMO@putchar{#1}\UMO@spacefactor\@m\fi 186 | \let\next\UMO@charloop \fi\fi\fi \next} 187 | \def\UMOspace{\PackageError{jumoline}% 188 | {\string\UMOspace\space cannot be used here.}% 189 | {\string\UMOspace\space can be used only in the argument of 190 | \string\Underline\space and its relatives.}} 191 | \def\UMOnewline{\PackageError{jumoline}% 192 | {\string\UMOnewline\space cannot be used here.}% 193 | {\string\UMOnewline\space can be used only in the argument of 194 | \string\Underline\space and its relatives.}} 195 | 196 | %%^L 197 | 198 | %% Put ASCII String 199 | 200 | \def\UMO@putword{\ifx\UMO@theword\empty\else 201 | \ifnum\UMO@mode=\UMO@afterchar 202 | \advance\UMO@kpostbreakpenalty\UMO@prebreakpenalty 203 | \penalty\UMO@kpostbreakpenalty 204 | \ifdim\UMO@postjfmglue>\z@ \UMO@skip\UMO@postjfmglue 205 | \else\ifodd\UMO@inhibitxspcode \ifodd\UMO@firstxspcode 206 | \UMO@skip\xkanjiskip \fi\fi\fi\fi 207 | \setbox\@tempboxa\hbox{% 208 | \UMO@theword\global\UMO@spacefactor\spacefactor}% 209 | \UMO@putbox\relax\UMO@theword \UMO@mode\UMO@afterword 210 | \def\UMO@theword{}\fi \UMO@firstxspcode\m@ne} 211 | 212 | %%^L 213 | 214 | %% Put Kanji Letter 215 | 216 | \def\UMO@putchar#1{% 217 | \ifnum\UMO@mode=\UMO@afterchar \UMO@prejfmglue\UMO@postjfmglue 218 | \else \UMO@prejfmglue\z@ \fi 219 | \UMO@postjfmglue\z@ 220 | \ifnum`#1<\kuten"1001\relax\UMO@setjfmglue{#1}\fi 221 | \@tempskipa\UMO@prejfmglue 222 | \UMO@inhibitxspcode\inhibitxspcode`#1\relax 223 | \@tempcnta\prebreakpenalty`#1\relax 224 | \ifnum\UMO@mode=\UMO@afterchar 225 | \advance\@tempcnta\UMO@kpostbreakpenalty 226 | \ifdim\UMO@prejfmglue=\z@ \@tempskipa\kanjiskip \fi 227 | \else\ifnum\UMO@mode=\UMO@afterword 228 | \advance\@tempcnta\UMO@postbreakpenalty 229 | \ifdim\UMO@prejfmglue=\z@ 230 | \ifnum\UMO@lastxspcode>\@ne \ifnum\UMO@inhibitxspcode>\@ne 231 | \@tempskipa\xkanjiskip \fi\fi\fi\fi\fi 232 | \penalty\@tempcnta 233 | \edef\@tempa{\the\@tempskipa}\ifx\@tempa\UMO@zskip\else 234 | \UMO@skip\@tempskipa \fi 235 | \UMO@putbox\inhibitglue{#1}% 236 | \UMO@kpostbreakpenalty\postbreakpenalty`#1\relax 237 | \UMO@mode\UMO@afterchar} 238 | \@tempskipa\z@ 239 | \edef\UMO@zskip{\the\@tempskipa} 240 | \def\UMO@setjfmglue#1{% 241 | \settowidth\@tempdima{$B$"(B#1}\settowidth\@tempdimb{$B$"(B\inhibitglue#1}% 242 | \advance\@tempdima-\@tempdimb 243 | \settowidth\UMO@tempdim{#1$B$"(B}\settowidth\@tempdimb{#1\inhibitglue $B$"(B}% 244 | \advance\UMO@tempdim-\@tempdimb 245 | \ifdim\@tempdima>\z@ 246 | \ifdim\UMO@tempdim>\z@ 247 | \@tempskipa\@tempdima minus\@tempdima\relax 248 | \UMO@postjfmglue\UMO@tempdim minus\UMO@tempdim\relax 249 | \else \@tempskipa\@tempdima minus\UMO@dqspace\relax \fi 250 | \advance\UMO@prejfmglue\@tempskipa 251 | \else \UMO@postjfmglue\UMO@tempdim minus\UMO@dqspace \fi} 252 | 253 | %%^L 254 | 255 | %% Draw Under/Mid/Overline 256 | 257 | \def\UMO@putbox#1#2{\setbox\@tempboxa\hbox{#1#2#1}\@tempdima\wd\@tempboxa 258 | \ifUMO@firstelem\else 259 | \rlap{\vrule\@height\UMO@height\@depth\UMO@depth\@width\@tempdima}\fi 260 | \box\@tempboxa 261 | \ifUMO@firstelem \UMO@firstelemfalse 262 | \llap{\vrule\@height\UMO@height\@depth\UMO@depth\@width\@tempdima}\fi} 263 | \def\UMO@skip#1{% 264 | \leaders\hrule\@height\UMO@height\@depth\UMO@depth\hskip#1\relax} 265 | 266 | %%^L 267 | 268 | %% Explicit Spacing and Line Breaking 269 | 270 | \def\UMO@space{\UMO@mode\UMO@afterblock 271 | \@ifstar\UMO@sspace\UMO@ispace} 272 | \def\UMO@sspace#1{\vrule width\z@\nobreak\UMO@skip{#1}\UMO@charloop} 273 | \def\UMO@ispace#1{\@tempskipa#1\relax 274 | \@ifstar{\@tempswafalse\UMO@iispace}{\@tempswatrue\UMO@iispace}} 275 | \def\UMO@iispace{\@ifnextchar[%] 276 | {\UMO@penalty}% 277 | {\UMO@skip\@tempskipa \UMO@charloop}} 278 | \def\UMO@penalty[#1]{\@tempcnta#1\relax 279 | \if@tempswa 280 | \ifnum\@tempcnta<\z@ \@tempcnta-\@tempcnta \fi 281 | \ifcase\@tempcnta \or 282 | \@tempcnta\@lowpenalty \or 283 | \@tempcnta\@medpenalty \or 284 | \@tempcnta\@highpenalty \else 285 | \@tempcnta\@M \fi 286 | \ifnum#1<\z@ \@tempcnta-\@tempcnta \fi \fi 287 | \penalty\@tempcnta \UMO@skip\@tempskipa \UMO@charloop} 288 | 289 | \def\UMO@newline{\UMO@mode\UMO@afterblock 290 | \@ifstar{\UMO@skip{0pt plus1fil}\break \UMO@charloop}% 291 | {\hfil \break \UMO@charloop}} 292 | 293 | %%^L 294 | 295 | %% Finalization 296 | 297 | \def\UMO@end{\ifnum\UMO@mode=\UMO@afterchar 298 | \ifnum\UMO@kpostbreakpenalty>\z@ 299 | \penalty\UMO@kpostbreakpenalty \fi 300 | \ifdim\UMO@postjfmglue>\z@ 301 | \UMO@skip\UMO@postjfmglue\fi \fi 302 | \xdef\UMO@aftergroup{\ifnum\UMO@mode=\UMO@afterword 303 | \spacefactor\number\UMO@spacefactor\fi}} 304 | \endinput 305 | %% 306 | %% End of file `jumoline.sty'. 307 | -------------------------------------------------------------------------------- /articles/sty/onestop-techbook.sty: -------------------------------------------------------------------------------- 1 | \usepackage{geometry} 2 | \geometry{top=14mm,bottom=18mm,left=20mm,right=20mm} 3 | 4 | \usepackage[most]{tcolorbox} 5 | \tcbuselibrary{breakable} 6 | \renewenvironment{shaded}{ 7 | \vspace{\baselineskip} 8 | \begin{tcolorbox}[breakable, enhanced jigsaw, colback=black!10!white, colframe=black!30!white]} 9 | {\end{tcolorbox}} 10 | \renewenvironment{shadedb}{ 11 | \vspace{\baselineskip} 12 | \begin{tcolorbox}[breakable, enhanced jigsaw, colback=black!80!white, colframe=black, colupper=white, sharp corners, rounded corners=southeast]} 13 | {\end{tcolorbox}} 14 | 15 | %% サンプルコードを更に小さく 16 | \renewenvironment{reviewemlist}{% 17 | \medskip\footnotesize\begin{shaded}\setlength{\baselineskip}{1.2zw}\begin{alltt}}{% 18 | \end{alltt}\end{shaded}} 19 | 20 | \renewenvironment{reviewlist}{% 21 | \begin{shaded}\footnotesize\setlength{\baselineskip}{1.2zw}\begin{alltt}}{% 22 | \end{alltt}\end{shaded}\par\vspace*{0.5zw}} 23 | 24 | \renewenvironment{reviewcmd}{% 25 | \color{white}\medskip\footnotesize\begin{shadedb}\setlength{\baselineskip}{1.2zw}\begin{alltt}}{% 26 | \end{alltt}\end{shadedb}} 27 | 28 | %% from review-pdfmaker 29 | \usepackage{fancyhdr} 30 | \usepackage{ulem} 31 | \pagestyle{fancy} 32 | 33 | \fancyhead{} 34 | \fancyhead[LE]{\gtfamily\sffamily\bfseries\upshape \leftmark} 35 | \fancyhead[RO]{\gtfamily\sffamily\bfseries\upshape \rightmark} 36 | \cfoot{\thepage} 37 | 38 | \renewcommand{\sectionmark}[1]{\markright{\thesection~#1}{}} 39 | \renewcommand{\chaptermark}[1]{% 40 | \if@mainmatter 41 | \markboth{\prechaptername\ \thechapter\ \postchaptername~#1}{} 42 | \else 43 | \markboth{#1}{#1} 44 | \fi} 45 | \renewcommand{\headfont}{\gtfamily\sffamily\bfseries} 46 | 47 | \fancypagestyle{plainhead}{% 48 | \fancyhead{} 49 | \fancyfoot{} % clear all header and footer fields 50 | \fancyfoot[CE,CO]{\thepage} 51 | \renewcommand{\headrulewidth}{0pt} 52 | \renewcommand{\footrulewidth}{0pt}} 53 | 54 | \hypersetup{colorlinks=false} 55 | %%Helveticaを使う 56 | \renewcommand{\sfdefault}{phv} 57 | 58 | \sloppy 59 | 60 | \cfoot{\thepage} 61 | 62 | \def\cleardoublepage{% 63 | \clearpage% 64 | \if@twoside% 65 | \ifodd \c@page \else \hbox{}\thispagestyle{plainhead}\newpage% 66 | \if@twocolumn\hbox{}\thispagestyle{plainhead}\newpage\fi% 67 | \fi% 68 | \fi% 69 | } 70 | 71 | 72 | \renewcommand{\baselinestretch}{0.96} 73 | 74 | \usepackage{fancyvrb} 75 | \VerbatimFootnotes 76 | \usepackage{seqsplit} 77 | \let\textttorg=\texttt 78 | \def\texttt{\begingroup\obeyspaces\do@texttt} 79 | \def\do@texttt#1{\textttorg{\seqsplit{#1\relax}}\endgroup} 80 | 81 | \newcommand{\captionsize}{\fontsize{9}{9}\selectfont} 82 | \newlength{\captionnumwidth} 83 | \setlength{\captionnumwidth}{6zw} 84 | \newlength{\captionwidth} 85 | \setlength{\captionwidth}{\textwidth} 86 | \addtolength{\captionwidth}{-\captionnumwidth} 87 | \def\captionhead{\sffamily{\color{black!30!white}{▲}}} 88 | \long\def\@makecaption#1#2{% 89 | \addvspace\abovecaptionskip 90 | \buildcaption{!}{#1}{#2} 91 | \vskip\belowcaptionskip 92 | } 93 | \long\def\buildcaption#1#2#3{% 94 | \sbox\@tempboxa{\captionsize\sffamily #3}% 95 | \ifdim \wd\@tempboxa <\captionwidth% 96 | \def\capline{\captionsize\captionhead #2% 97 | \hskip1zw\relax\usebox{\@tempboxa}\mbox{}\relax} 98 | \ifx#1!\relax\centerline{\capline}\else\noindent\capline\fi 99 | \else 100 | \noindent% 101 | \parbox[t]{\captionnumwidth}{% 102 | {\captionsize\captionhead #2% 103 | \hskip1zw}}% 104 | \parbox[t]{\captionwidth}{\captionsize\sffamily #3} 105 | \fi 106 | } 107 | 108 | \long\def\listcaption#1:#2\relax{\buildcaption{}{#1}{#2}} 109 | 110 | \renewcommand{\reviewtablecaption}[1]{% 111 | {\def\captionhead{\sffamily{\color{black!30!white}{▼}}} 112 | \caption{#1}}} 113 | 114 | \renewcommand{\reviewlistcaption}[1]{% 115 | {\def\captionhead{\sffamily{\color{black!30!white}{▼}}} 116 | \medskip{\listcaption#1\relax}\vspace*{-1.3zw}}} 117 | 118 | \renewcommand{\reviewemlistcaption}[1]{% 119 | {\def\captionhead{\sffamily{\color{black!30!white}{▼}}} 120 | \medskip{\buildcaption{}{}{#1}\relax}\vspace*{-1.3zw}}} 121 | 122 | \renewcommand{\reviewcmdcaption}[1]{% 123 | {\def\captionhead{\sffamily{\color{black!30!white}{▼}}} 124 | \medskip{\listcaption#1\relax}\vspace*{-1.3zw}}} 125 | 126 | \renewcommand{\reviewindepimagecaption}[1]{% 127 | \begin{center}#1\end{center}} 128 | 129 | \renewcommand{\reviewboxcaption}[1]{% 130 | {\def\captionhead{\sffamily{\color{black!30!white}{▼}}} 131 | \medskip{\captionsize\captionhead #1}\vspace*{-1.3zw}}} 132 | 133 | 134 | 135 | \renewenvironment{reviewcolumn}{% 136 | \vspace{\baselineskip} 137 | \begin{tcolorbox}[colback=white] 138 | }{% 139 | \end{tcolorbox} 140 | \vspace{\baselineskip} 141 | } 142 | 143 | \renewcommand{\reviewcolumnhead}[2]{% 144 | {\noindent\large\sffamily #2} 145 | \vspace{\baselineskip}} 146 | 147 | %%シングルクォート対応 148 | \usepackage{upquote,textcomp} 149 | \xspcode`'=0 150 | -------------------------------------------------------------------------------- /articles/sty/reviewmacro.sty: -------------------------------------------------------------------------------- 1 | %% from review-pdfmaker 2 | \usepackage{fancyhdr} 3 | \pagestyle{fancy} 4 | \lhead{\gtfamily\sffamily\bfseries\upshape \leftmark} 5 | \chead{} 6 | \rhead{\gtfamily\sffamily\bfseries\upshape \rightmark} 7 | \renewcommand{\sectionmark}[1]{\markright{\thesection~#1}{}} 8 | \renewcommand{\chaptermark}[1]{\markboth{\prechaptername\ \thechapter\ \postchaptername~#1}{}} 9 | \renewcommand{\headfont}{\gtfamily\sffamily\bfseries} 10 | 11 | \fancypagestyle{plainhead}{% 12 | \fancyhead{} 13 | \fancyfoot{} % clear all header and footer fields 14 | \fancyfoot[CE,CO]{\thepage} 15 | \renewcommand{\headrulewidth}{0pt} 16 | \renewcommand{\footrulewidth}{0pt}} 17 | 18 | %% using Helvetica as sans-serif 19 | \renewcommand{\sfdefault}{phv} 20 | 21 | \sloppy 22 | 23 | %% del tag strike 24 | \usepackage{ulem} 25 | \renewcommand{\reviewstrike}[1]{\sout{#1}} 26 | 27 | -------------------------------------------------------------------------------- /articles/sty/samplemacro.sty: -------------------------------------------------------------------------------- 1 | %% from review-pdfmaker 2 | \usepackage{fancyhdr} 3 | \usepackage{ulem} 4 | \pagestyle{fancy} 5 | 6 | \fancyhead{} 7 | \fancyhead[LE]{\gtfamily\sffamily\bfseries\upshape \leftmark} 8 | \fancyhead[RO]{\gtfamily\sffamily\bfseries\upshape \rightmark} 9 | \cfoot{\thepage} 10 | 11 | \renewcommand{\sectionmark}[1]{\markright{\thesection~#1}{}} 12 | \renewcommand{\chaptermark}[1]{\markboth{\prechaptername\ \thechapter\ \postchaptername~#1}{}} 13 | \renewcommand{\headfont}{\gtfamily\sffamily\bfseries} 14 | 15 | \fancypagestyle{plainhead}{% 16 | \fancyhead{} 17 | \fancyfoot{} % clear all header and footer fields 18 | \fancyfoot[CE,CO]{\thepage} 19 | \renewcommand{\headrulewidth}{0pt} 20 | \renewcommand{\footrulewidth}{0pt}} 21 | 22 | \hypersetup{colorlinks=false} 23 | %%Helveticaを使う 24 | \renewcommand{\sfdefault}{phv} 25 | 26 | \sloppy 27 | 28 | \cfoot{\thepage} 29 | 30 | \def\cleardoublepage{% 31 | \clearpage% 32 | \if@twoside% 33 | \ifodd \c@page \else \hbox{}\thispagestyle{plainhead}\newpage% 34 | \if@twocolumn\hbox{}\thispagestyle{plainhead}\newpage\fi% 35 | \fi% 36 | \fi% 37 | } -------------------------------------------------------------------------------- /articles/sty/tatsumacro.sty: -------------------------------------------------------------------------------- 1 | \geometry{top=14mm,bottom=16mm,left=5mm,right=5mm} 2 | 3 | \definecolor{borderblue}{rgb}{0.2,0.4,0.9} 4 | 5 | \hypersetup{% 6 | colorlinks,% 7 | %%urlcolor=borderblue, 8 | linkcolor=borderblue% 9 | } 10 | 11 | %% from review-pdfmaker 12 | \usepackage{fancyhdr} 13 | \usepackage{ulem} 14 | %%\usepackage{supertabular} 15 | \setlength{\headheight}{29pt} 16 | \pagestyle{fancy} 17 | \lhead{\gtfamily\sffamily\bfseries\upshape \leftmark} 18 | \chead{} 19 | \rhead{} 20 | \cfoot{} 21 | \rfoot{\thepage} 22 | \renewcommand{\sectionmark}[1]{\markright{\thesection~#1}{}} 23 | \renewcommand{\chaptermark}[1]{% 24 | \if@mainmatter 25 | \markboth{\prechaptername\ \thechapter\ \postchaptername~#1}{} 26 | \else 27 | \markboth{#1}{#1} 28 | \fi} 29 | \renewcommand{\headfont}{\gtfamily\sffamily\bfseries} 30 | 31 | \fancypagestyle{plainhead}{% 32 | \fancyhead{} 33 | \fancyfoot{} % clear all header and footer fields 34 | \fancyfoot[R]{\thepage} 35 | \renewcommand{\headrulewidth}{0pt} 36 | \renewcommand{\footrulewidth}{0pt}} 37 | 38 | 39 | \renewcommand{\reviewtitlefont}[0]{% 40 | \usefont{T1}{pag}{b}{n}\gtfamily\ebseries} 41 | \renewcommand{\reviewmainfont}[0]{% 42 | \usefont{T1}{phv}{m}{n}\mgfamily} 43 | 44 | \renewcommand{\textbf}[1]{% 45 | {\usefont{T1}{phv}{b}{n}\gtfamily\bfseries~#1}} 46 | 47 | %%URLのフォントを通常のフォントにする 48 | \urlstyle{same} 49 | 50 | %%Helveticaを使う 51 | \renewcommand{\sfdefault}{phv} 52 | 53 | %%全体のデフォルトを丸ゴシック+Helveticaに 54 | \renewcommand{\kanjifamilydefault}{\mgdefault} 55 | \renewcommand{\familydefault}{\sfdefault} 56 | 57 | %%色修正 58 | \definecolor{shadecolorb}{gray}{0.5} 59 | 60 | %%シングルクォート対応 61 | \usepackage{upquote,textcomp} 62 | \xspcode`'=0 63 | 64 | %\renewcommand{\reviewcolumnhead}[2]{% 65 | %{\noindent\large ■#2}} 66 | 67 | %%framed.sty 68 | %%//cmdや//emlistの横幅をぎりぎりまで広げる 69 | \setlength{\FrameSep}{4pt} 70 | 71 | %%table 72 | \renewenvironment{reviewtable}[1]{% 73 | \begin{center}\scriptsize\setlength{\baselineskip}{1.5zw} 74 | \renewcommand\arraystretch{1.5} 75 | \begin{tabular}{#1}}{% 76 | \end{tabular} 77 | \end{center}} 78 | 79 | \renewcommand{\reviewappendix}{% 80 | \backmatter% 81 | \fancyhead{} 82 | } 83 | 84 | \def\@makechapterhead#1{% 85 | \vspace*{0.5\Cvs}% 欧文は50pt 86 | {\parindent \z@ \raggedright \normalfont 87 | \ifnum \c@secnumdepth >\m@ne 88 | \if@mainmatter 89 | \hfill{\huge\headfont \@chapapp\thechapter\@chappos} 90 | \par\nobreak 91 | \vskip 0.5\Cvs % 欧文は20pt 92 | \fi 93 | \fi 94 | \interlinepenalty\@M 95 | \hfill{\huge \headfont #1\par\nobreak} 96 | \vspace*{-2mm}% 97 | \rule{\textwidth}{0.1mm} 98 | \vskip 1.0\Cvs}} % 欧文は40pt 99 | 100 | 101 | 102 | \makeatletter%% 103 | 104 | \long\def\@makecaption#1#2{{\small 105 | \advance\leftskip .0628\linewidth 106 | \advance\rightskip .0628\linewidth 107 | \vskip\abovecaptionskip 108 | \sbox\@tempboxa{\textgt{\textsf{#1}}\hskip1zw\relax \textgt{\textsf{#2}}}% 109 | \ifdim \wd\@tempboxa <\hsize \centering \fi 110 | \textgt{\textsf{#1}}\hskip1zw\relax \textgt{\textsf{#2}}\par 111 | \vskip\belowcaptionskip}} 112 | 113 | \makeatother%% プリアンブルで定義する場合は必須(文字コードも) 114 | 115 | \sloppy 116 | 117 | %%目次と本文でページ番号を振り直しても表紙・中表紙ページと重複しないようRomanにしておく 118 | \pagenumbering{Roman} 119 | 120 | -------------------------------------------------------------------------------- /articles/sty/techbooster-doujin.sty: -------------------------------------------------------------------------------- 1 | \usepackage[most]{tcolorbox} 2 | \tcbuselibrary{breakable} 3 | \renewenvironment{shaded}{ 4 | \vspace{\baselineskip} 5 | \begin{tcolorbox}[breakable, enhanced jigsaw, colback=black!10!white, colframe=black!30!white]} 6 | {\end{tcolorbox}} 7 | \renewenvironment{shadedb}{ 8 | \vspace{\baselineskip} 9 | \begin{tcolorbox}[breakable, enhanced jigsaw, colback=black!80!white, colframe=black, colupper=white, sharp corners, rounded corners=southeast]} 10 | {\end{tcolorbox}} 11 | 12 | %% サンプルコードを更に小さく 13 | \renewenvironment{reviewemlist}{% 14 | \medskip\footnotesize\begin{shaded}\setlength{\baselineskip}{1.2zw}\begin{alltt}}{% 15 | \end{alltt}\end{shaded}} 16 | 17 | \renewenvironment{reviewlist}{% 18 | \begin{shaded}\footnotesize\setlength{\baselineskip}{1.2zw}\begin{alltt}}{% 19 | \end{alltt}\end{shaded}\par\vspace*{0.5zw}} 20 | 21 | \renewenvironment{reviewcmd}{% 22 | \color{white}\medskip\footnotesize\begin{shadedb}\setlength{\baselineskip}{1.2zw}\begin{alltt}}{% 23 | \end{alltt}\end{shadedb}} 24 | 25 | %% from review-pdfmaker 26 | \usepackage{fancyhdr} 27 | \usepackage{ulem} 28 | \pagestyle{fancy} 29 | 30 | \fancyhead{} 31 | \fancyhead[LE]{\gtfamily\sffamily\bfseries\upshape \leftmark} 32 | \fancyhead[RO]{\gtfamily\sffamily\bfseries\upshape \rightmark} 33 | \cfoot{\thepage} 34 | 35 | \renewcommand{\sectionmark}[1]{\markright{\thesection~#1}{}} 36 | \renewcommand{\chaptermark}[1]{% 37 | \if@mainmatter 38 | \markboth{\prechaptername\ \thechapter\ \postchaptername~#1}{} 39 | \else 40 | \markboth{#1}{#1} 41 | \fi} 42 | \renewcommand{\headfont}{\gtfamily\sffamily\bfseries} 43 | 44 | \fancypagestyle{plainhead}{% 45 | \fancyhead{} 46 | \fancyfoot{} % clear all header and footer fields 47 | \fancyfoot[CE,CO]{\thepage} 48 | \renewcommand{\headrulewidth}{0pt} 49 | \renewcommand{\footrulewidth}{0pt}} 50 | 51 | \hypersetup{colorlinks=false} 52 | %%Helveticaを使う 53 | \renewcommand{\sfdefault}{phv} 54 | 55 | \sloppy 56 | 57 | \cfoot{\thepage} 58 | 59 | \def\cleardoublepage{% 60 | \clearpage% 61 | \if@twoside% 62 | \ifodd \c@page \else \hbox{}\thispagestyle{plainhead}\newpage% 63 | \if@twocolumn\hbox{}\thispagestyle{plainhead}\newpage\fi% 64 | \fi% 65 | \fi% 66 | } 67 | 68 | \setlength{\paperheight} {257 truemm} 69 | \setlength{\paperwidth} {182 truemm} 70 | \setlength{\textheight} {190 truemm} 71 | \setlength{\textwidth} {130 truemm} 72 | \setlength{\marginparwidth} {15 truemm} 73 | \setlength{\marginparsep} {2 truemm} 74 | \setlength{\oddsidemargin} {26 truemm} 75 | \setlength{\evensidemargin} {26 truemm} 76 | \setlength{\topmargin} {10 truemm} 77 | \setlength{\headsep} {15 truemm} 78 | \setlength{\headheight} {5 truemm} 79 | \setlength{\hoffset}{-1in} 80 | \setlength{\voffset}{-1in} 81 | \renewcommand{\baselinestretch}{0.96} 82 | 83 | \usepackage{fancyvrb} 84 | \VerbatimFootnotes 85 | \usepackage{seqsplit} 86 | \let\textttorg=\texttt 87 | \def\texttt{\begingroup\obeyspaces\do@texttt} 88 | \def\do@texttt#1{\textttorg{\seqsplit{#1\relax}}\endgroup} 89 | 90 | \newcommand{\captionsize}{\fontsize{9}{9}\selectfont} 91 | \newlength{\captionnumwidth} 92 | \setlength{\captionnumwidth}{6zw} 93 | \newlength{\captionwidth} 94 | \setlength{\captionwidth}{\textwidth} 95 | \addtolength{\captionwidth}{-\captionnumwidth} 96 | \def\captionhead{\sffamily{\color{black!30!white}{▲}}} 97 | \long\def\@makecaption#1#2{% 98 | \addvspace\abovecaptionskip 99 | \buildcaption{!}{#1}{#2} 100 | \vskip\belowcaptionskip 101 | } 102 | \long\def\buildcaption#1#2#3{% 103 | \sbox\@tempboxa{\captionsize\sffamily #3}% 104 | \ifdim \wd\@tempboxa <\captionwidth% 105 | \def\capline{\captionsize\captionhead #2% 106 | \hskip1zw\relax\usebox{\@tempboxa}\mbox{}\relax} 107 | \ifx#1!\relax\centerline{\capline}\else\noindent\capline\fi 108 | \else 109 | \noindent% 110 | \parbox[t]{\captionnumwidth}{% 111 | {\captionsize\captionhead #2% 112 | \hskip1zw}}% 113 | \parbox[t]{\captionwidth}{\captionsize\sffamily #3} 114 | \fi 115 | } 116 | 117 | \long\def\listcaption#1:#2\relax{\buildcaption{}{#1}{#2}} 118 | 119 | \renewcommand{\reviewtablecaption}[1]{% 120 | {\def\captionhead{\sffamily{\color{black!30!white}{▼}}} 121 | \caption{#1}}} 122 | 123 | \renewcommand{\reviewlistcaption}[1]{% 124 | {\def\captionhead{\sffamily{\color{black!30!white}{▼}}} 125 | \medskip{\listcaption#1\relax}\vspace*{-1.3zw}}} 126 | 127 | \renewcommand{\reviewemlistcaption}[1]{% 128 | {\def\captionhead{\sffamily{\color{black!30!white}{▼}}} 129 | \medskip{\buildcaption{}{}{#1}\relax}\vspace*{-1.3zw}}} 130 | 131 | \renewcommand{\reviewcmdcaption}[1]{% 132 | {\def\captionhead{\sffamily{\color{black!30!white}{▼}}} 133 | \medskip{\listcaption#1\relax}\vspace*{-1.3zw}}} 134 | 135 | \renewcommand{\reviewindepimagecaption}[1]{% 136 | \begin{center}#1\end{center}} 137 | 138 | \renewcommand{\reviewboxcaption}[1]{% 139 | {\def\captionhead{\sffamily{\color{black!30!white}{▼}}} 140 | \medskip{\captionsize\captionhead #1}\vspace*{-1.3zw}}} 141 | 142 | 143 | 144 | \renewenvironment{reviewcolumn}{% 145 | \vspace{\baselineskip} 146 | \begin{tcolorbox}[colback=white] 147 | }{% 148 | \end{tcolorbox} 149 | \vspace{\baselineskip} 150 | } 151 | 152 | \renewcommand{\reviewcolumnhead}[2]{% 153 | {\noindent\large\sffamily #2} 154 | \vspace{\baselineskip}} 155 | 156 | %%シングルクォート対応 157 | \usepackage{upquote,textcomp} 158 | \xspcode`'=0 159 | -------------------------------------------------------------------------------- /articles/sty/ulem.sty: -------------------------------------------------------------------------------- 1 | % 2 | % U L E M . S T Y [2012-05-18] 3 | % 4 | % The ulem package provides various types of underlining that can stretch 5 | % between words and be broken across lines in LaTeX or plain TeX. 6 | % In LaTeX ulem replaces italics with underlining in \em-phasized text. 7 | % It is most suitable for simple text such as {\em ibid.} or \emph{\LaTeX: 8 | % A Document Preparation System} that may need to be underlined in a 9 | % manuscript submitted for publication. A declaration of \normalem (or 10 | % the \usepackage option "normalem") restores the normal \em behavior. 11 | % 12 | % Full instructions appear in ulem.ltx (ulem.pdf). In summary: 13 | % 14 | % \uline{important} underlined text 15 | % \uuline{urgent} double-underlined text 16 | % \uwave{boat} wavy underline 17 | % \sout{wrong} line drawn through word 18 | % \xout{removed} marked over with //////. 19 | % \dashuline{dashing} dash underline 20 | % \dotuline{dotty} dotted underline 21 | % 22 | % {\em phasized\/} | In LaTeX, by default, these are underlined; use 23 | % \emph{asized} | \normalem or [normalem] to restore italics 24 | % \useunder{\uwave}{\bfseries}{\textbf} 25 | % use wavy underline in place of bold face 26 | % Use \markoverwith for defining new types of underlining. 27 | % 28 | % Copyright (c) 1989-2011 by Donald Arseneau (Vancouver, Canada; asnd@triumf.ca) 29 | % 30 | % This software may be freely transmitted, reproduced, or modified for any 31 | % purpose provided that this copyright notice is left intact. 32 | % (Small excerpts may be taken and used without any restriction.) 33 | % 34 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 35 | % Defend against multiple loading. 36 | \expandafter \ifx \csname UL@box\endcsname \relax \else 37 | \immediate\write16{ulem.sty refuses to load twice. }\endinput \fi 38 | 39 | % Set catcode of @ in case it isn't a "letter" already 40 | \chardef\ULthickness\catcode\string`\@ % hold catcode temporarily 41 | \catcode\string`\@=11 42 | 43 | \def\uline{\relax \ifmmode\expandafter\underline 44 | \else \bgroup\expandafter\ULset\fi} 45 | 46 | \newbox\UL@box 47 | \newbox\UL@hyphenbox 48 | \newskip\UL@skip 49 | \newtoks\UL@hook 50 | 51 | \newdimen\UL@height 52 | 53 | \newcount\UL@pe 54 | \let\LA@space\ \let\LA@hskip\hskip 55 | 56 | \def\UL@end *{\relax\relax}% something harmless unlikely to be found elsewhere 57 | 58 | % For regular underlines, set the depth based on the font, or retain 59 | % the preset value, then start underlining. 60 | \def\ULset{\UL@setULdepth 61 | \def\UL@leadtype{\leaders \hrule \@height\UL@height \@depth\ULdepth}% 62 | \ifmmode \ULdepth-4\p@ \fi 63 | \UL@height-\ULdepth \advance\UL@height\ULthickness \ULon} 64 | 65 | % Automatically set \ULdepth if it is to be automatic (flagged by \maxdimen) 66 | \def\UL@setULdepth{\relax 67 | \ifdim\ULdepth=\maxdimen % Set depth based on font, if not set already 68 | \setbox\UL@box\hbox{{(j}}\ULdepth\dp\UL@box\advance\ULdepth.4\p@ 69 | % use setbox to support plain TeX 70 | \fi} 71 | 72 | % \ULon simply calls \UL@on (possibly \UL@on=\UL@onin) for text mode, but 73 | % \UL@onmath if it is math mode. 74 | \def\ULon{\ifmmode \expandafter\UL@onmath\else \expandafter\UL@on\fi} 75 | 76 | % \UL@on sets the engine of underline running, and tells it 77 | % where to stop. 78 | \long\def\UL@on#1{\leavevmode\UL@ender \let\UL@on\UL@onin 79 | \everymath{\UL@hrest}\everyvbox{\UL@hrest}\let\hskip\UL@hskip 80 | \let\\\UL@cr \let\-\UL@dischyp \let\newline\UL@newline \let\ \UL@space 81 | \def\hfil{\hskip\z@ plus1fil\relax}\def\hfill{\hskip\z@ plus1fill\relax}% 82 | \def\hss{\hskip\z@ plus1filminus1fil\relax}\let\penalty\UL@penalty 83 | \the\UL@hook 84 | \UL@word\@empty#1\xdef\UL@spfactor{\the\spacefactor} \UL@end * } 85 | 86 | % This is what \ULon does when it appears nested in an inner place. 87 | \def\UL@onin#1{\leavevmode\UL@ender % when nested, do multiple underlining 88 | \UL@height\ULthickness \advance\ULdepth\thr@@\UL@height 89 | \advance\UL@height-\ULdepth \setbox\UL@box\hbox{{#1}}% 90 | \let\UL@start\relax\UL@putbox\egroup} 91 | % \UL@putbox is disabled in inner mode, so re-enable it by changing \UL@start 92 | % \UL@hrest is implicit due to \everyhbox. Double braces for \hbox are in 93 | % lieu of \color@begin(end)group. 94 | 95 | % This is what \ULon does in math mode. 96 | \def\UL@onmath#1{\UL@ender\mathord{\UL@hrest\mathop{\kern\z@#1}\limits\sb 97 | {\UL@leadtype\LA@hskip\p@ plus1fill}}\egroup} 98 | 99 | \def\UL@unegroup{} 100 | \gdef\UL@ender{} 101 | % end-brace matching hack for when command is used as a font declaration: 102 | \def\UL@swender{\ifnum`{=\z@\fi\aftergroup}\gdef\UL@ender{}} 103 | 104 | % must expand to nothing outside the ifs for syntactical spaces to work. 105 | % the \expandafters get rid of the \@empty inserted at the beg. of word 106 | \def\UL@word#1 {\expandafter\UL@start#1 % 107 | \expandafter\ifx\expandafter\UL@end#1\egroup\egroup 108 | \unskip \unskip \unskip % remove extra leader at end 109 | \spacefactor\UL@spfactor \let\UL@word\egroup 110 | \else % not finished 111 | \ifmmode\else \ifdim\lastskip=\z@\else % allow syntactical spaces 112 | \global\UL@skip\lastskip \unskip 113 | \UL@stop \UL@leaders 114 | \fi\fi 115 | \fi \UL@word\@empty}% \@empty preserves braces in param 116 | 117 | % \UL@start: start of each chunk. It gives two levels of grouping. 118 | % Each chunk is ended by \UL@stop. Local intermissions go like 119 | % \UL@stop...\UL@start. 120 | \def\UL@start{\setbox\UL@box\hbox\bgroup\everyhbox{\UL@hrest}% 121 | % the following are to cope with stops (\ ,\- etc) within extra braces 122 | \let\UL@start\@empty \def\UL@unegroup{\bgroup\bgroup}\let\UL@leadtype\@empty 123 | \bgroup \kern-3sp\kern3sp % kerns so I can test for beginning of list 124 | \if@ignore \global\@ignorefalse \ignorespaces \fi} 125 | 126 | \def\UL@stop{\global\UL@pe\lastpenalty \unpenalty % penalty in \UL@pe 127 | \ifnum\lastkern=\thr@@ \egroup\egroup % Nothing in hbox...but make sure: 128 | \ifdim\wd\UL@box=\z@ \else \UL@putbox \fi % something in box so print it 129 | \else \egroup\egroup \UL@putbox % something in box so print it 130 | \fi \ifnum\UL@pe=\z@ \else \LA@penalty\UL@pe \fi % use penalty from inside box 131 | \UL@unegroup} 132 | % notice that a box with only a penalty in it is discarded, but the penalty 133 | % is still used! This is so a series of discardable glues and penalties 134 | % behaves properly. 135 | 136 | \def\UL@putbox{\ifx\UL@start\@empty \else % not inner 137 | \vrule\@width\z@ \LA@penalty\@M 138 | {\UL@skip\wd\UL@box \UL@leaders \kern-\UL@skip}% 139 | \box\UL@box \fi} 140 | 141 | % With interword leaders, give some overlap to avoid gaps caused by 142 | % round-off errors in the printing program. Needs \unskip \unskip \unskip 143 | % above. This version overlaps 1/300 inch, which looks good at high 144 | % resolution, and will still work down to ~150 dpi. Change the value 145 | % of \UL@pixel if necessary. 146 | 147 | \newdimen\UL@pixel \UL@pixel=1in \divide\UL@pixel 300 148 | 149 | \def\UL@leaders{{\LA@hskip-\UL@pixel \advance\UL@skip\tw@\UL@pixel 150 | \UL@leadtype\LA@hskip\UL@skip \LA@hskip-\UL@pixel}} 151 | 152 | % restore some things for inside math or \mbox 153 | \def\UL@hrest{\let\ \LA@space \let\-\@empty \let\penalty\LA@penalty} 154 | 155 | \def\UL@space{\LA@space \global\UL@skip\lastskip \unskip \UL@reskip}% \ 156 | 157 | % Hyphenation is done by explicit \discretionary. The overlapping melds 158 | % with the running overlap because it *is* part of the running overlap: 159 | % The word fragment is extended by the width of the hyphenation which is 160 | % then overlapped by leaders. The discretionary may occupy this space 161 | % if a break occurs; otherwise the next syllable gets doubly-overlapped 162 | % (in registration) for a distance of the hyphen's width. 163 | \def\UL@dischyp{\global\setbox\UL@hyphenbox\hbox 164 | {\ifnum \hyphenchar\font<\z@ \string-\else \char\hyphenchar\font \fi}% 165 | \kern\wd\UL@hyphenbox \LA@penalty\@M 166 | \UL@stop \kern-\wd\UL@hyphenbox 167 | \discretionary{\box\UL@hyphenbox}{}{}\UL@start} 168 | 169 | \let\LA@penalty\penalty 170 | \def\UL@penalty{\relax\ifhmode \afterassignment\UL@@penalty\count@ 171 | \else\LA@penalty\fi} 172 | \def\UL@@penalty{\LA@penalty \ifnum\count@=\z@ 173 | \@ne \else \count@ \fi % zero penalty => no penalty, so use 1 instead. 174 | \UL@stop \UL@start} 175 | 176 | % The test \ifx\ \LA@space \else means we are neither in math mode nor an 177 | % \mbox, so it is safe to stop the current \UL@box. \ , \- , and \penalty 178 | % (= \linebreak or \nolinebreak) are common enough that they are restored 179 | % directly (by \UL@hrest); \\, \newline, \hskip (= \hspace) are rare enough 180 | % that the test is incorporated in their UL versions. This adds processing 181 | % when they're used, but saves processing in \UL@hrest called by \everymath 182 | % \everyvbox and \everyhbox. 183 | 184 | \def\UL@hskip{\ifx\ \LA@space \LA@hskip \else 185 | \afterassignment\UL@reskip \global\UL@skip \fi} 186 | 187 | \def\UL@reskip{\UL@stop \UL@leaders \UL@start} 188 | 189 | % Redefine \\ and \newline so the vertical space from \\[ ] is not lost 190 | % and so the \hfil is not underlined! \\ and \newline do nothing if inside 191 | % inner braces. 192 | 193 | \def\UL@cr{\unskip \ifx\ \LA@space \let\UL@vad\@gobble 194 | \else \UL@stop \unskip\unskip\unskip \let\UL@vad\vadjust \fi 195 | \@ifstar{\UL@vad{\LA@penalty\@M}\UL@cra}\UL@cra} 196 | \def\UL@cra{\@ifnextchar[\UL@crb\UL@newline} 197 | \def\UL@crb[#1]{\UL@vad{\vskip#1}\UL@newline} 198 | 199 | \def\UL@newline{\ifx\UL@start\@empty % (\UL@cr may have \UL@stop-ed already) 200 | \unskip \ifx\ \LA@space \else \UL@stop \unskip\unskip\unskip \fi\fi 201 | \LA@hskip \z@\@plus.0001fil\LA@penalty -\@M \UL@start} 202 | 203 | % That concludes the basic underlining. To put various other objects 204 | % (characters) under (or over) text we need to define \markoverwith 205 | % to set the overlay material in a box, and use leaders of that box for 206 | % overlaying the text. Here, the meaning of \UL@pixel is changed so 207 | % that `pixel' size = box size. Note that we generally need \leaders 208 | % (not \cleaders) for text, because an underline will be a patchwork 209 | % of small \leaders, and the characters must stay in registration. 210 | % However, we "hook" the leaders command so specific applications can 211 | % reassign it (\let\ULleaders\xleaders or \let\ULleaders\cleaders). 212 | % 213 | \newbox\ULC@box 214 | \let\ULleaders\leaders 215 | 216 | \def\markoverwith#1{\setbox\ULC@box\hbox{{#1}}\UL@pixel.5\wd\ULC@box 217 | \ifmmode \setbox\ULC@box\hbox{\raise1.4ex\box\ULC@box}% 218 | \dp\ULC@box-1.4ex\ht\ULC@box\z@ \def\UL@leadtype{\cleaders\copy\ULC@box}% 219 | \else 220 | \def\UL@leadtype{\ULleaders\copy\ULC@box}% 221 | \fi} 222 | 223 | % Now define various special underlines. All the definitions go like 224 | % \def \command {\bgroup \markoverwith{something} \ULon} 225 | 226 | % For drawing a wavey underline instead of a straight one the command 227 | % is \uwave (under-wave) which uses the wiggle from 6-pt lasy font: 228 | 229 | \def\uwave{\bgroup \markoverwith{\lower3.5\p@\hbox{\sixly \char58}}\ULon} 230 | \font\sixly=lasy6 % does not re-load if already loaded, so no memory problem. 231 | 232 | % To draw a double underline under text, use \uuline{text} 233 | 234 | \def\uuline{\bgroup \UL@setULdepth 235 | \markoverwith{\lower\ULdepth\hbox 236 | {\kern-.03em\vbox{\hrule width.2em\kern1.2\p@\hrule}\kern-.03em}}% 237 | \ULon} 238 | 239 | % To draw a line through text instead of under it (strike out) do 240 | % `under'-line with negative depth. Note that this one uses a real 241 | % line, not characters, so there is no \markoverwith. 242 | 243 | \def\sout{\bgroup \ULdepth=-.55ex \ULset} 244 | 245 | % To mark //// over text instead of underlining (x-out) 246 | % 247 | \def\xout{\bgroup \markoverwith{\hbox to.35em{\hss/\hss}}\ULon} 248 | 249 | \def\dotuline{\bgroup 250 | \UL@setULdepth 251 | \markoverwith{\begingroup 252 | \advance\ULdepth0.08ex 253 | \lower\ULdepth\hbox{\kern.1em .\kern.04em}% 254 | \endgroup}% 255 | \ULon} 256 | 257 | \def\dashuline{\bgroup 258 | \UL@setULdepth 259 | \markoverwith{\kern.13em 260 | \vtop{\kern\ULdepth \hrule width .3em}% 261 | \kern.13em}\ULon} 262 | 263 | % A command to declare that an underline command should be used in 264 | % place of a particular font selection: 265 | % \useunder {underline_command}{font_declaration}{font_command} 266 | % e.g.: \useunder{\uuline}{\bfseries}{\textbf} 267 | % \useunder{\uwave}{\bf}{} 268 | 269 | \def\useunder#1#2#3{\relax 270 | \ifx\relax#2\relax\else % declaration command given 271 | \def#2{\def\@tempa{#1}\global\let\UL@ender\UL@swender 272 | \expandafter\@tempa\expandafter{\ifnum\z@=\string`}\fi}% 273 | \MakeRobust{#2}\fi 274 | \ifx\relax#3\relax\else % argumentative command 275 | \def#3{#1}\MakeRobust{#3}\fi} 276 | 277 | \expandafter\ifx \csname @ifundefined\endcsname \relax 278 | 279 | % Allow plain TeX to use ulem.sty: 280 | \def\@height{height} 281 | \def\@depth{depth} 282 | \def\@width{width} 283 | \def\@empty{} 284 | \long\def\@gobble#1{} 285 | \def\MakeRobust#1{} 286 | % Do non-outer \newif with no visible \if's or \fi's when skipping 287 | \csname newif\expandafter\endcsname \csname if@ignore\endcsname 288 | 289 | \else 290 | 291 | \def\MakeRobust#1{\expandafter\let 292 | \csname \expandafter\@gobble\string#1 \endcsname= #1% 293 | \edef#1{\noexpand\protect \expandafter\noexpand 294 | \csname\expandafter\@gobble\string#1 \endcsname} 295 | } 296 | \MakeRobust\uline 297 | \MakeRobust\uuline 298 | \MakeRobust\uwave 299 | \MakeRobust\sout 300 | \MakeRobust\xout 301 | 302 | \let\LA@em\em \let\LA@emph\emph 303 | \expandafter\let\expandafter\LA@Pem \csname em \endcsname 304 | \expandafter\let\expandafter\LA@Pemph \csname emph \endcsname 305 | \def\ULforem{\useunder{\uline}{\em}{\emph}} 306 | \def\normalem{\let\em\LA@em \let\emph\LA@emph 307 | \expandafter\let\csname em \endcsname\LA@Pem 308 | \expandafter\let\csname emph \endcsname\LA@Pemph} 309 | \ULforem % default is to use underlining for \em, 310 | 311 | \fi 312 | 313 | % Process LaTeX \package options; plain TeX skips this section 314 | 315 | \expandafter\ifx\csname ProvidesPackage\endcsname \relax \else 316 | \ProvidesPackage{ulem}[2012/05/18] 317 | \DeclareOption{normalem}{\normalem} 318 | \DeclareOption{ULforem}{\ULforem} 319 | \DeclareOption{normalbf}{} 320 | \DeclareOption{UWforbf}{\useunder{\uwave}{\bf}{\textbf}} 321 | \ProcessOptions 322 | % 323 | \AtBeginDocument{\let\UL@marginpar\marginpar}% 324 | \newcommand\UL@marpar[2][\gDefault@pt]{\gdef\gDefault@pt{#2}% 325 | \ifx\ \LA@space \@latexerr{Marginpar lost}% 326 | \else \UL@stop \UL@marginpar[#1]{#2}\UL@start \fi} 327 | \addto@hook\UL@hook{\let\marginpar\UL@marpar} 328 | \fi 329 | 330 | \catcode`@=\ULthickness % Scratch meaning: restore catcode of @ 331 | 332 | \def\ULthickness{.4pt}% can change this with \renewcommand 333 | \newdimen\ULdepth \ULdepth=\maxdimen 334 | % "maxdimen" depth causes the depth to be set according to the font. You 335 | % can change \ULdepth for a permanent setting or a special effect (\sout). 336 | 337 | \endinput 338 | 339 | %====================== BEGIN INSTRUCTIONS =========================== 340 | These plain text instructions may disappear soon. The primary instructions 341 | are in ulem.ltx (ulem.pdf, ulem.dvi). 342 | 343 | ULEM is a package for LaTeX or plain TeX which provides various types of 344 | underlining that can stretch between words and be broken across lines. 345 | In LaTeX this style replaces italics with underlining in emphasized text 346 | given by \em or \emph -- but only if the text is delimited by braces. A 347 | declaration \normalem (or the \usepackage option [normalem]) restores the 348 | normal \em behavior. For underlining in plain TeX, \input ulem.sty, and 349 | use the \uline command. 350 | 351 | Unlike regular underlining, ulem allows line breaks, and even primitive 352 | hyphenation, within the underlined text; but it is far from perfect. It is 353 | most suitable for simple text like {\em \LaTeX: A document preparation 354 | system\/} that may need to be underlined in a manuscript submitted for 355 | publication. Again, ulem will only replace \em and \emph when the text is 356 | delimited by explicit braces. 357 | 358 | The thickness of the underline rule is given by \ULthickness; use 359 | \renewcommand or \def (not \setlength) to change it. The depth of the 360 | underline is controlled by the length \ULdepth. The default value is a 361 | special flag which lets the current font control the depth. You can set 362 | a particular value to \ULdepth (using \setlength) to force a particular 363 | depth, either locally for a special purpose, or for the document as a 364 | whole. See the definition of \sout. 365 | 366 | Every word is typeset in an underlined box, so automatic hyphenation is 367 | normally disabled, but explicit discretionary hyphens (\-) will still be 368 | obeyed. Several text-formatting commands are specially supported within 369 | the underlining: \-, \ , ~, \\, \newline, \linebreak, \nolinebreak, 370 | \penalty, \hskip, \hspace, \hfil, \hfill, \hss. Displayed math and \par 371 | are deliberately not supported to aid in the detection of runaway arguments 372 | (missing braces). The special commands do have a problem: they end a 373 | group so any local assignments are lost. 374 | 375 | The underlines continue between words, and stretch just like ordinary 376 | spaces do. Since spaces delimit words, there may be some difficulty 377 | with syntactical spaces (e.g. "2.3 pt"). Some effort is made to handle 378 | such cases, but sometimes (such as \let\x= y) the space is interpreted 379 | incorrectly. You can usually solve the problem by enclosing the offending 380 | command in braces or in a macro (\newcommand\xeqy{\let\x= y}), but... 381 | 382 | One important incompatibility with braces and macro replacement: 383 | ALL THE TEXT IN BRACES OR COMING FROM A MACRO IS TYPESET IN A BOX. 384 | That is, braces will suppress stretching and linebreaks in the text they 385 | enclose. Moreover, the specially-taken-care-of commands \-, \\, \newline 386 | and \linebreak are usually ignored if they appear inside extra braces. 387 | They operate only when the braces delimit a command parameter without 388 | introducing a level of grouping. (Even though braces delimiting command 389 | parameters do not normally imply grouping, many commands will add their 390 | own grouping.) Thus, you should try to limit inner braces to short bits of 391 | text or for delimiting parameters to commands. For emergency repairs, see 392 | the "Marat/Sade" example below. Syntactical spaces inside braces never 393 | cause a problem, nor do spaces in math mode. 394 | 395 | Text produced by expansion of a command (macro) is boxed too, but \\, \ 396 | and \- still work properly in the expansion text: 397 | \newcommand\iff{if and only if} {\em \iff} 398 | does not allow any stretching or linebreaking between words, but 399 | \newcommand\iff{if\ and\ only\ if} {\em \iff} 400 | allows stretching and linebreaking. There is a problem though: the 401 | \ between words closes a group and any local assignments will be lost, 402 | in particular, font changes and color changes. 403 | 404 | This loss of local assignments will break some other standard commands, 405 | (e.g., \cite) which produce multiple `words' using local assignments. 406 | The way to protect such commands is to bury them in an \mbox: 407 | {\em every\-one agrees~\mbox{\cite{you,me}}.} 408 | 409 | Nested \em commands produce multiple underlining, but heed the warnings 410 | about braces above. To get italics without underlining, use \it. Nesting 411 | of other types of underline is also possible, but the `underlines' may 412 | overlap. 413 | 414 | HERE IS A SIMPLE EXAMPLE. 415 | 416 | \noindent 'Twas {\em brillig\/} and the {\em slithy~toves\/} 417 | did {\em gyre\/} and {\em gim\-ble\/} in the {\em wabe,\\[2pt] } 418 | All {\em mim\-sey\/} were the {\em boro\-goves\/} and 419 | the {\em mome raths outgrabe}. 420 | 421 | HERE IS A DIFFICULT EXAMPLE. 422 | 423 | \usepackage{ulem} 424 | \setlength\textwidth{3.3in} 425 | \begin{document} 426 | % \large 427 | No, I did {\em not} act in the movie {\em \emph{The} % <<<<<<< Nested 428 | \emph{Persecu}\-\emph{tion} \emph{and} \emph{Assassination} \emph{of} 429 | \emph{Jean-Paul} \emph{Marat}, as per\-formed by the Inmates 430 | of the Asylum of Charenton under the Direc\-tion of the 431 | Marquis de~Sade!} But I {\em did} see it. 432 | \end{document} 433 | 434 | In the nested emphasis, \emph had to be given for each word separately 435 | so the spaces between could stretch and break into lines. Even the 436 | discretionary hyphen (\-) in `Persecution' had to be outside the braces, 437 | but the hyphen in `Direction' was just fine because it was not in nested 438 | braces. The same applies to other special commands like \ and ~. Also, 439 | the spaces are printed with only a single underline because they are 440 | outside the nested \emph commands. This example really illustrates that 441 | ulem does not handle nested emphasis very well! Nevertheless, it is fine 442 | for simple things. 443 | 444 | Underlining can also be done according to \uline{this text}. To use this 445 | type of underlining, but have \em still produce italics, put the command 446 | \normalem in the preamble of the document or load ulem with 447 | \usepackage[normalem]{ulem}. 448 | 449 | Some variations on underlining are provided, including a wavey underline 450 | (\uwave{under-wave}), double underlines (\uuline{two lines under this}), 451 | dashed (\dashuline{dashes underneath}) or dotted (\dotuline{dots below}) 452 | underlines, 453 | a line through text rather than under it (\sout{strike out}), and text 454 | crossed-out with /////// (\xout{cross out, X out}). You can define your 455 | own styles following the examples provided. The definition should be 456 | something like: 457 | 458 | \newcommand\command{\bgroup \markoverwith{something}\ULon} 459 | 460 | The "something" can be as simple as a single character, or as complex as 461 | you can keep track of. 462 | 463 | The various underlining commands are essentially textual, and will not 464 | work quite the same in math mode. But since some font commands, like \bf, 465 | serve both for text and math, math mode is handled (in an approximate way). 466 | The performance in math mode is somewhat different from in text: there will 467 | be no line breaks or stretching in the underlined text, and the vertical 468 | positioning may not be right. The results should be best for \uline, 469 | \uwave, \uuline, and any other truly UNDER-line you define. 470 | 471 | Any type of underlining can be substituted for any font-selection command 472 | by issuing a proper \useunder declaration: 473 | 474 | \useunder{\underlinecommand}{\fontdeclaration}{\fontcommand} 475 | 476 | e.g., \useunder{\uuline}{\bfseries}{\textbf} gives a double underline 477 | instead of bold face in LaTeX. The commands \normalem and \ULforem switch 478 | underlining for \em off and on, respectively, and so do the \usepackage 479 | options [normalem] and [ULforem]. There is also the \usepackage style 480 | option [UWforbf] to replace boldface with a wavey underline. 481 | 482 | UWforbf does handle \bf in math mode, but it doesn't work in section titles, 483 | unfortunately, because the titles are not delimited by explicit braces when 484 | printed by the \section command. For the present version, the \bfseries 485 | command still produces bold face, but \bf makes an under-wave. To get under- 486 | waved section titles you can do 487 | 488 | \renewcommand\@seccntformat[1]{\uwave{\csname the#1\endcsname}\hskip 1em} 489 | 490 | and later specify \section[...]{\uwave{...}}. 491 | 492 | In plain TeX there is no \textbf so you should use \useunder{\UWave}{\bf}{}. 493 | You can even skip a step and define the underline or overprint with \useunder: 494 | \useunder{\bgroup\markoverwith{!}\ULon}{\sf}{} 495 | 496 | Some commands, such as \\ and \hskip are given special treatment, but 497 | others (like \marginpar) are not. Support for others can be added by 498 | assigning special meanings in the token register \UL@hook. (In LaTeX do 499 | \addto@hook\UL@hook{\let\command\ULversion}.) The UL versions of commands 500 | should be modelled on \UL@hskip or \UL@cr, and should include the test 501 | "\ifx\ \LA@space". For example, support for "\marginpar" is added through 502 | the hook mechanism. 503 | 504 | All the underlining commands are robust in LaTeX. 505 | 506 | %====================== END INSTRUCTIONS =========================== 507 | 508 | % Previous bug-finders: Esther Hu (\hfill in plain); Lones Smith (\tt\-); 509 | % Steve Anderson (\ooalign accents); Thanassi Protopapas ( { in tables). 510 | % The bug finders' fee is now $0.00; it will double for each new bug found. 511 | % Version (identified by year) 512 | % 1994: 513 | % Many changes! Notably: LaTeX2e options and \emph. Nesting works (somewhat). 514 | % Behavior with inner braces is more consistent (not stripped). \useunder. 515 | % Better underwave (using lasy6). Special underlines are not commented out. 516 | % patch 1995: fix \UL@swender to work in {tabular}; make hyphenation join 517 | % well; crude math support; eliminate \@clb 518 | % 1996: use "\csname ProvidesPackage\endcsname", tidying. 519 | % 1997: fix \\ when LaTeX changed; remove extra overlap in putbox. 520 | % 2000: hook (and marginpar) 521 | % 2004: Fix spacing in \uwave and \xout. \ULleaders hook. 522 | % 2009: Accept \par in argument (\long) 523 | % 2010: Include \dotuline and \dashuline, typeset documentation, add \UL@setULdepth 524 | % 2011: Change \dimen@ to \UL@height 525 | % 2012: Removed \let\par garbage 526 | % 527 | % Send problem reports to asnd@triumf.ca 528 | % 529 | % test integrity: 530 | % brackets: round, square, curly, angle: () [] {} <> 531 | % backslash, slash, vertical, at, dollar, and: \ / | @ $ & 532 | % hat, grave, acute (apostrophe), quote, tilde, under: ^ ` ' " ~ _ 533 | -------------------------------------------------------------------------------- /articles/style-web.scss: -------------------------------------------------------------------------------- 1 | /* stylesheet for Re:VIEW web */ 2 | 3 | $cursor-top: 100px; 4 | $cursor-width: 40px; 5 | $side-width: 200px; 6 | $page-width: 800px; 7 | 8 | nav.side-content 9 | { 10 | 11 | width: $side-width; 12 | position: fixed; 13 | 14 | h1.side-title 15 | { 16 | margin: 0; 17 | padding: 0; 18 | font-size: 1em; 19 | border-top: none; 20 | } 21 | 22 | ul 23 | { 24 | list-style: none; 25 | } 26 | } 27 | 28 | .book-body 29 | { 30 | margin-left: $cursor-width + $side-width; 31 | margin-right: $cursor-width; 32 | position: relative; 33 | 34 | .book-page 35 | { 36 | max-width: $page-width; 37 | margin:0 auto; 38 | padding: 32px 0 32px; 39 | } 40 | 41 | .book-navi 42 | { 43 | position: fixed; 44 | top: 0; 45 | min-width: $cursor-width; 46 | 47 | a 48 | { 49 | text-decoration: none; 50 | } 51 | } 52 | 53 | .book-prev 54 | { 55 | left: $side-width + 10px; 56 | } 57 | .book-next 58 | { 59 | right: 10px; 60 | } 61 | 62 | .book-cursor 63 | { 64 | height: 100vh; 65 | text-align: center; 66 | font-size: 32pt; 67 | padding: $cursor-top 0 0 0; 68 | color: #eee; 69 | } 70 | .book-cursor:hover 71 | { 72 | color: #333; 73 | } 74 | 75 | } 76 | 77 | footer p 78 | { 79 | margin-left: $side-width + $cursor-width; 80 | text-align: center; 81 | } 82 | 83 | .cover-image img 84 | { 85 | max-width: 100%; 86 | } 87 | 88 | -------------------------------------------------------------------------------- /articles/style.scss: -------------------------------------------------------------------------------- 1 | // Variables 2 | $main-color: #64C1D7; 3 | $footer-link-color: #9e9e9e; 4 | $font-size: 16px; 5 | $paragraph-margin-bottom: $font-size * 0.75; 6 | 7 | // デフォルトの装飾を上書く 8 | body { 9 | font-family: "Helvetica Neue", Helvetica, Arial, Meiryo, "メイリオ", sans-serif; 10 | font-size: $font-size; 11 | line-height: 24px / $font-size; 12 | } 13 | h2 { 14 | border-bottom: 1px solid #ccc; 15 | } 16 | h1, h2, h3 { 17 | margin-top: $font-size * 0.875 * 2; 18 | margin-bottom: $font-size * 0.875; 19 | } 20 | h4, h5, h6 { 21 | margin-top: $font-size * 0.875; 22 | margin-bottom: $font-size * 0.875; 23 | &:before { 24 | content: "■"; 25 | } 26 | } 27 | p { 28 | margin-bottom: $paragraph-margin-bottom; 29 | } 30 | dd { 31 | margin-left: 3em; 32 | } 33 | 34 | // コラム 35 | div.column { 36 | border: solid 3px; 37 | border-radius: 10px; 38 | padding-left: 1em; 39 | padding-right: 1em; 40 | margin-top: $paragraph-margin-bottom; 41 | margin-bottom: $paragraph-margin-bottom; 42 | h1, h2, h3 { 43 | margin-top: $font-size * 0.875; 44 | } 45 | } 46 | 47 | // リード文 48 | div.lead { 49 | font-size: $font-size; 50 | margin-left: 3em; 51 | } 52 | 53 | // footnote 54 | .noteref { 55 | vertical-align: super; 56 | font-size: smaller; 57 | } 58 | p.footnote { 59 | font-size: 0.8em; 60 | } 61 | // footnoteは最後に持ってくる 62 | .main-content { 63 | display: flex; 64 | flex-direction: column; 65 | } 66 | div.footnote { 67 | order: 1; 68 | } 69 | 70 | // 画像やリストなどのキャプション系 71 | .image, .table, .caption-code, .cmd-code { 72 | margin-bottom: $paragraph-margin-bottom; 73 | } 74 | .image, .table { // キャプションを中央寄せするもの 75 | .caption { 76 | text-align: center; 77 | } 78 | } 79 | .image { // キャプションに▲を付けるもの 80 | .caption { 81 | margin-top: 0; 82 | &:before { 83 | content: "▲"; 84 | color: lightgray; 85 | } 86 | } 87 | } 88 | .caption-code, .table { // キャプションに▼を付けるもの 89 | .caption { 90 | margin-bottom: 0; 91 | &:before { 92 | content: "▼"; 93 | color: lightgray; 94 | } 95 | } 96 | } 97 | .image { 98 | img { // 画像は中央余生にしとく 99 | display: block; 100 | max-width: 100%; 101 | height: auto; 102 | margin-left: auto;; 103 | margin-right: auto; 104 | } 105 | } 106 | 107 | // ヘッダ 108 | .tb-header { 109 | background-image: url(images/html_header.jpg); 110 | background-size: cover; 111 | height: 20vw; 112 | background-color: $main-color; 113 | color: white; 114 | 115 | // テキストは隠す 116 | text-indent: 150%; 117 | overflow: hidden; 118 | white-space: nowrap; 119 | } 120 | 121 | // メニューまわり 122 | .tb-nav-link { 123 | margin-top: 1em; 124 | margin-bottom: 1em; 125 | a.prev:before { 126 | content: "<<"; 127 | } 128 | a.next:after { 129 | content: ">>"; 130 | } 131 | } 132 | 133 | // フッタ 134 | .tb-footer { 135 | margin-top: 16px; 136 | padding-top: 16px; 137 | padding-bottom: 16px; 138 | color: white; 139 | background-color: #424242; 140 | a { 141 | color: $footer-link-color; 142 | } 143 | p { 144 | margin-right: 10px; 145 | } 146 | } 147 | .tb-footer-links { 148 | li:nth-child(n+2)::before { 149 | color: $footer-link-color; 150 | content: "/"; 151 | margin-right: 16px; 152 | } 153 | } 154 | -------------------------------------------------------------------------------- /articles/think-body.re: -------------------------------------------------------------------------------- 1 | = 本文を記述する 2 | 3 | 事前準備を終えた後は、実際に本文を書きます。この章では「手が止まらない」ようにするための心構えや工夫をお伝えします。 4 | ただし、本文に書くべき内容については言及を避けます。同人誌は個人の趣味嗜好を表現する場だからです。 5 | @{好きなことを好きなように書く}のが大原則です。 6 | 7 | == 最優先事項は書き終わること 8 | 9 | 本文を記載する上で重要なことは、@{最初から綺麗な文章を書こうとしない}ことです。 10 | 最初からわかりやすい・読みやすい文章が書ける人はいません。 11 | 書いた文章をそのまま提出するわけではありません。納得いくまで修正すれば良いのです。 12 | 13 | みなさんも、レポートの締め切り間際に焦った経験があるかと思います。 14 | 締め切り間際に原稿ができていないと、とにかく完成させることに気がむいてしまいますよね。 15 | 技術同人誌の質を上げるためには、締め切り間際に焦る事態は回避しなければなりません。 16 | 17 | 文章の修正には時間がかかります。また、時間があればより良い表現を再考できるかもしれません。 18 | @{早い段階で、本文を1度書ききることが重要です}。 19 | 20 | 私も技術同人誌を2年近く書いていますが、何回も書いては修正して…を繰り返した後に入稿しています。 21 | 繰り返しますが、最初に書いた文章＝入稿できるクオリティである必要はありません。 22 | まずは目次を全て埋めることに注力しましょう。 23 | 24 | == 大学生のためのレポートの書き方は参考になる 25 | 26 | 「何かを始める際には参考書や攻略方法を見たい」という方もいるでしょう。 27 | この本を手に取った方の中には@{具体的な書き進め方}を期待した方がいらっしゃるかもしれません。 28 | 29 | @{好きなことを好きなように書く}のが大原則なので「そんなものはない！」と言い切ることもできます。 30 | しかし、参考にできるものがなくて手が止まってしまうと本末転倒です。 31 | そこで、@{技術同人誌の書き進め方}を参考にできる文献を紹介します。 32 | 33 | 技術同人誌は、特定の対象について知っている（調べた）知識をまとめて記述されたものと考えることができます。 34 | プロダクトの紹介であっても、対象についてのまとめを記述するという点では同じです。 35 | これは、大学のレポートと内容が似ています。 36 | 37 | 世の中には@{レポートの書き方}本が多く出回っています。 38 | 技術同人誌の書き方が知りたいのであれば、@{高校・大学生に向けたレポートの書き方本}を参考にすると良いでしょう。 39 | これらの本は、次の事項が詳しく解説されています。 40 | 41 | * テーマの決め方 42 | * 論理展開の組み方 43 | * 参考文献の探し方・引用方法 44 | * 日本語文章の書き方（例：接続詞・句読点の打ち方） 45 | * Wordを用いたページ設定の方法 46 | * 自分の意見を思考する方法 47 | 48 | 学生向けだから、と敬遠するには勿体無い内容ばかりです。 49 | 欠点は電子版が少ないことです。図書館に置いてあることが多いので、まずは試し読みをしてみると良いでしょう。 50 | 51 | === 思考の整理学 52 | 53 | * 外山滋比古（1986）思考の整理学　筑摩書房 54 | ** http://www.chikumashobo.co.jp/product/9784480020475/ 55 | 56 | 「東京大学の生協で7年連続No1ベストセラー」という売り文句が有名な書籍です。 57 | 58 | 本の中ではアイデアの出し方と寝かせ方、アイデアのストック方法が具体的に示されています。 59 | 技術同人誌を作り始める前、章の構想が固まるまでの段階で参考にすると良いでしょう。 60 | 61 | この本がおすすめできる理由はもう1点あります。「自分の思考を育てる」ことを学べるからです。 62 | 同人誌界隈でよくある悩みの中に、「他の人とネタが被ってしまう」ことがあります。 63 | ネタが被ってしまうと不安になる気持ちはよくわかります。 64 | 他の人の方がより良い同人誌を書けるはずだから、自分の本は不要なのかもしれない、と思うのです。 65 | 66 | 技術同人誌はあなたの思考結果をまとめて頒布するのであって、誰かのために書くものではありません。 67 | 同人誌を求める人は、本に詰まった思考結果が好きでやってくるのです。 68 | 69 | 思考の整理学では、「飛行機」として自分で自分の行く先を決めて飛び回ろう、そのために思考するのだとあります。 70 | 自分だけの思考を大切にすることへのエールに溢れている本です。 71 | 72 | === 論文・レポートの書き方 73 | 74 | * 石黒圭（2012）論文・レポートの基本 75 | * https://www.njg.co.jp/book/9784534049278/ 76 | 77 | 論文を書き終えるために必要と思われる知識について、幅広く解説された本です。 78 | 79 | 文章の構成・文章の書き方についてわかりやすく書かれており、おすすめの一冊です。 80 | 引用文献の探し方、参考・引用方法について詳しく記述があるのも良い点です。 81 | 82 | 悪文と修正された文が本の中に記載されているため、文章のルールを理解しやすいです。 83 | 電子版も存在します。 84 | 85 | 似たような内容の本はいくつも出ていますので、好みの本を探すと良いでしょう。 86 | 87 | === 理科系の作文技術 88 | 89 | * 木下是雄（1981）理科系の作文技術　中央公論新社 90 | ** http://www.chuko.co.jp/shinsho/1981/09/100624.html 91 | 92 | 全編を通して、理科系の文章作成方法を指南した書籍です。 93 | 文章をなるべく短く、簡潔に書く方法が記述されています。 94 | 95 | 理科系の学問は、実験結果をまとめたレポート・論文を記述することが多いです。 96 | 実験結果を技術要素に置き換えて読み進めると良いでしょう。 97 | 98 | 先に紹介した『論文・レポートの書き方』に加えてもう一冊参考書が欲しい方におすすめです。 99 | 100 | === 記者ハンドブック 101 | 102 | * 共同通信社（2016）記者ハンドブック第13版 103 | ** https://www.kyodo.co.jp/books/isbn/978-4-7641-0687-1/ 104 | 105 | 共同通信社が発行している本です。新聞上での日本語表現ルールを示した文書です。 106 | 日本語表現における公式ドキュメントという位置付けです。 107 | 108 | 送り仮名の表記法・かっこの使い方・カタカナ表記などのルールが詳しく載っています。 109 | 国名の表記法も載っています。面白いですね。 110 | 111 | 日本語の正確な表現を知りたいとき、参考にすると良いでしょう。 112 | 113 | == 書き終わるための技術 114 | 115 | 本文は1度書き切ることが重要だ、と述べました。ここでは、私が原稿を書き終わるために工夫していることをお伝えします。 116 | @{原稿をサボらないことが一番難しいから}です。 117 | 118 | === 締め切りを見える化する 119 | 120 | @{書き始める前に締め切りを決め、カレンダーに書き込みましょう}。このとき、@{印刷所の締め切りより1週間早め}に設定するのが重要です。 121 | 締め切りを早めに設定し、書かなきゃという焦りを生み出しましょう。焦らないと机に向かわないからです。 122 | 123 | === 監視されている状態を演出する 124 | 125 | サボって締め切り間際に焦る人は、人の力を借りて机に向かう習慣をつけましょう。 126 | 自己管理ができないから締め切り間際に焦るのです。 127 | 128 | * Twitterで「〇〇について書きます」と宣言して固定ツイートにしておく 129 | * ブログに新刊の内容を書いておく 130 | * 身内に煽ってもらう 131 | 132 | 宣言してある内容の本が机に並んでいないと、本を求めてやってきた人はがっかりします。がっかりされると心苦しいですよね。 133 | こうして退路を無くしておけば、机に向かわざるを得ないというわけです。 134 | 135 | ちなみに一番効果的なのは@{身内に煽ってもらう}です。同じ家の中に身内がいると、さらに効果的です。 136 | せっかくなので、私が実際に煽られた内容を記載します。 137 | 138 | //quote{ 139 | 考えてもみてくださいよ、航空券いつ予約すんの？早割でしょう？（原稿も早割で入稿するでしょの意） 140 | //} 141 | 142 | //quote{ 143 | 通常締切で入稿するのはスタートラインですよ 144 | //} 145 | 146 | //quote{ 147 | （締切間際に焦る筆者を見て）毎日やらないからそうやって焦るんでしょう？どうして毎日できないの？ 148 | //} 149 | 150 | //quote{ 151 | 俺がキュ○ぱずを毎日やるように、原稿も毎日やるべきでしょ 152 | //} 153 | 154 | 適度な煽りは焦りを生みます。本物の人間に煽ってもらえるのであれば、関係性が壊れない程度にたくさん煽ってもらいましょう。 155 | 156 | === 毎日少しずつやる 157 | 158 | 塵も積もれば山となる、です。休日にまとめて原稿、はやめましょう。病気や急用が入った瞬間に破綻します。 159 | 160 | 未来をあてにするその根性がよろしくないのです。 161 | 162 | == 執筆時のお困り事例とその解決法 163 | 164 | これまで何回か「好きなことを好きなように書くべきだ」と述べてきました。ただ、この本は技術同人誌を書くための同人誌です。 165 | そこで表現したくてもどう書けばいいかわからない、などというお困りごとの解決方法を示したいと思います。 166 | 167 | 困ったことがあれば、こんな書き方・解決例がありますよ、くらいの気持ちで参考にしてみてください。 168 | 169 | === 仲間の筆が遅い 170 | 171 | 複数人で同人誌を執筆する場合、一番困るパターンは「自分は原稿が書けたのに、仲間の原稿ができていない」ことです。 172 | @{喧嘩の元なので、全員いいから早くやれ}、ということが大前提です。ただ、これでは解決になりません。 173 | 174 | 私が複数人執筆の音頭を取っていたとき、とった対策をお伝えします。 175 | 176 | ==== 対処法A：締め切りを入稿日より3週間早く設定する 177 | 178 | この対処法が利用できるのは、あなたが複数人執筆のリーダーをやっている場合のみです。これ以降、リーダーを@{編集長}と表記します。 179 | 180 | 締め切りを早めに設定すると、@{遅れても（あなたの）心理的に余裕がある}状態を保つことができます。 181 | 原稿が中々出てこないメンバーは、元から締め切りにルーズな人が多いです。わざと締め切りを早めに設定し、都度「あと〇〇日しかないよ」と煽りましょう。 182 | このとき、あなたの原稿がすでに完成していると効果は抜群です。 183 | 184 | わざと締めきりを早く設定しても、どうせ調べたら真の締め切りがばれるのでは？と思うかもしれません。 185 | まず、締め切りにルーズな人は@{わざわざ印刷所の締め切りを調べません}。 186 | 仮に真の締め切りがバレたとしても、「早割入稿を目指しているから」と言えば良いです。 187 | 188 | 印刷所の早割入稿日は、イベントの2週間前に設定されることが多いです。@{comikmarket}もちろん印刷所によりますので、都度しっかり確認して下さい。 189 | ただ、早割で入稿できれば印刷費が2割近く安くなります。浮いたお金で打ち上げが豪華になるから、などと理由をつけて@{早めに締め切りを設定しましょう}。 190 | 191 | 推敲・組版調整をする時間を考慮すると、通常締め切りの3週前を締め切りとするべきです。 192 | 193 | //footnote[comikmarket][コミックマーケットは締め切りがイベント3・4週前になります。他にも大規模イベントに合わせる形だと特別対応になることもあります。] 194 | 195 | ==== 対処法B：圧力を強めにかける 196 | 197 | とにかく圧力をかけて、無理矢理机に向かわせましょう。具体的には、次のような手法を使います。 198 | 199 | * 毎日進捗を聞いてまわる 200 | * あなたの原稿を早く完成させて公開する 201 | * ブログを先に書いて公開する 202 | * 執筆合宿をする 203 | 204 | しつこく、毎日、地道に圧力をかけましょう。それでも締め切りにルーズな人は、ギリギリまで何もしないのですから。 205 | 206 | ==== 対処法C：最後の手段を発動する 207 | 208 | これは最後の手段です。できれば対処法Bまでになるように努力しましょう。 209 | 210 | 最後の手段とは、@{相手の原稿を切り捨てる＝自分の原稿だけで入稿できる状態にする/入稿する}です。 211 | 原稿が間に合わないのが悪いので、あなたに非はありません。ただし、大半の場合は人間関係も切り捨てることになりがちです。 212 | できる限り回避するようにしましょう。 213 | 214 | === 書きたい内容がないよう 215 | 216 | 「内容がないようで困る」状態です。技術同人誌の内容を膨らませるためのアイデアを紹介します。 217 | 218 | ==== A. 比較する 219 | 220 | 取り扱おうとしている技術には、必ず@{競合プロダクト}が存在するはずです。例を示します。 221 | 222 | * React vs Vue.js vs Angular 223 | * AWS vs GCP vs Azure vs オンプレミス 224 | 225 | 同じ目的を達成するためのプロダクトとはいえ、プロダクトごとに癖やメリット・デメリットは存在します。 226 | 比較対象となる技術を探し、良し悪しを比較することに価値があります。あなた自身は技術についての理解が深まります。 227 | 読者は技術選定に役立つ知見を得ることができます。 228 | 229 | 機能の比較をする際は、なるべく同じ目的を達成するコード・動作を行いましょう。同じものを作ることで、プロダクトの良し悪しが見えやすくなります。 230 | エラーログなど、動作させてみないとわからないことも多いものです。 231 | 232 | ==== B. 歴史的背景を調べる 233 | 234 | 技術の出自や発展上の経緯を調べてみましょう。経緯を調べると、プロダクトの持つ思想や特徴を理解する助けになります。 235 | 調べたときに利用した資料名を載せれば、読者も同じ資料を閲覧できます。 236 | 237 | 技術の歴史的経緯は自力で調べるのが難しい知見です。プロダクトに対する理解がなければ、何を調べたら良いかすらわからないからです。 238 | 歴史的背景がまとまった本は、それだけでも価値があるのです。 239 | 240 | === 目次が出せない 241 | 242 | 「まず最初に目次を出せと言うけれど、結局どうやって出すんだよォーッ！」と感じている方もいらっしゃるかもしれません。 243 | そこで、目次の作成方針をお伝えします。それは、@{本の中で達成したい目的を決めてその作業順を洗い出す}ことです。 244 | 245 | 書こうとしている技術同人誌で達成したい目的を決め、そこに至るまでに必要な方法を全て書き出す方式です。 246 | 247 | 例えば、『ログと情報をレッツ・ラ・まぜまぜ！～ELK Stack で作るBI環境～』の目標は、@{Kibanaを用いてTwilogというサービスのログを可視化する}ことでした。 248 | 目次を起こすときは、これに必要な手順を書き出します。大まかに分けて、次のような作業が発生すると考えました。 249 | 250 | * ミドルウェアの環境構築 251 | * Logstashを用いてデータをElaticsearchに連携する 252 | * Kibanaでデータを確認する 253 | * Kibanaでグラフを作成する 254 | 255 | ELKの説明も必要でしょう。この時点で、このミドルウェアを利用した実績が少なかったためです。 256 | そこで、ミドルウェアの環境構築前に@{そもそもELKとは？}の説明を入れることにしました。 257 | 258 | 章の区切りができたので、今度は書く項目のなかで作業手順を整理します。@{Kibanaでデータを確認する}章であれば、次のような流れになるだろう、と考えました。 259 | 260 | 1. Kibanaの画面にアクセスする 261 | 2. Kibanaのメニュー内容から「データを閲覧する」画面を開く 262 | 3. 「データを閲覧する」画面でデータの内訳を参照する 263 | 4. グラフに必要な検索条件を検討する 264 | 265 | この工程を繰り返すことで、全ての章の目次を完成させます。 266 | 267 | @{本の中で達成したい目的を決めてその作業順を洗い出す}工程の良い点は、@{目次を見るだけでその技術同人誌が何を実現するのかわかりやすくなる}ことです。 268 | どんなことが書いてある本かわかりやすくなれば、対象読者により本を届けやすくなります。 269 | 270 | 技術同人誌の場合、イベントの短い立ち読み時間で本を購入するか判断しなければなりません。 271 | あなたが立ち読みする側であれば、何が書いてあるかすぐわかった方が良いですよね。本のゴールが見えやすい方が、自分にとって必要かを判断しやすくなります。 272 | 結果、読んでほしい読者に本を届けやすくなるのです。 273 | 274 | 技術要素をオムニバス形式で並べる場合、@{本全体で届けたい情報を目次に羅列し、その技術同人誌が伝えたい知見をはっきり}させると良いでしょう。 275 | とはいえ、基本的な考え方はあまり変わりません。 276 | 277 | === なかなか書き出すことができない 278 | 279 | 原稿を書かないといけないのに、いざパソコンを開くと何も書けなくなってしまう。これは、本文作成時の中で一番の困りごとです。 280 | 何を書いていいのかわからない場合、目次出しの工程に戻ると良いでしょう。 281 | 282 | 目次が書けている場合、次の方法のどれかを試してみてください。 283 | 284 | ==== A. 章・節ごとに一番言いたいことを記載する 285 | 286 | 目次を書いて本全体の流れを作るのと同じように、各章・各節ごとに言いたいことを記載していきましょう。 287 | 一番言いたいことが目に見えれば、その主張に対する根拠・事前知識を補足する作業ができます。 288 | 289 | 何を書けば良いのかわからず手が止まってしまうときは、言いたいことがぼんやりとしている場合が多いです。 290 | それを見える化してあげると、筆が進みやすくなります。 291 | 292 | ==== B. 一旦パソコンから離れる 293 | 294 | 何も思いつかないときは、パソコンを閉じてみましょう。長時間同じ姿勢を続けると疲れてしまいます。 295 | 少しその辺を散歩してみると、いいアイディアが思い浮かぶかもしれません。 296 | 297 | 私は、紙の上に本の内容を書き出した後でパソコンに向かうようにしています。 298 | パソコンで最初から書こうとすると、エディタやワープロソフトの操作で頭がいっぱいになってしまうからです。 299 | 紙を見ながら文字を打ち込むことで、@{考える時間と書く時間をずらす}ようにしています。 300 | 301 | 付箋やマインドマップアプリなどを活用して、@{書くときに内容を考えないようにする}と短時間でも進捗を出しやすいです。 302 | 303 | ==== C. 割り切って思い切り遊ぶ 304 | 305 | まったくやる気にならない場合、@{時間を区切って好きなことをしましょう}。疲労が溜まっている人は、この時間で寝ましょう。 306 | 307 | 私の場合ですが、「あァ〜やりたくないけれど原稿やらなきゃだわ〜」と言いながら書いた原稿は@{推敲時に90%捨てられてしまいます}。 308 | 気力に満ち溢れているときの文章と、書かされた感の強い文章では、前者の方が魅力的に映るのです。 309 | 310 | 締め切りに間に合っていれば良いのです。やる気がでないときは、割り切って思い切り遊びましょう。 311 | 312 | === できます地獄になってしまう 313 | 314 | 特定技術の機能を説明する際、@{〇〇できます}という文言で表現する方法しか思いつかず困る、という例です。 315 | 316 | //list[description-beats-can][機能の説明で「できます」を多用している例]{ 317 | Beatsはインストールすることで、機器のデータをElasticsearchやLogstashに転送できます。 318 | 例えばネットワークのパケット情報・Windowsのイベントログ・死活監視の情報などを収集することが 319 | できるため、Logstashでカバーできないような情報を集めてくることができます。 320 | //} 321 | 322 | @{description-beats-can}の文章でも、Beatsというプロダクトの機能は伝わります。 323 | ただ、何度も@{できます}が続くとしつこくなってしまいます。 324 | 325 | ==== A. 表現を変更する 326 | 327 | @{できます}・@{可能です}と書かず、淡々と機能について紹介する方法です。 328 | 329 | //list[description-beats][「できます」を使わずに機能を紹介する例です]{ 330 | Beatsは、機器のデータをElasticsearchやLogstashに転送する簡易的なデータ収集ツールです。 331 | 収集できるデータは、ネットワークのパケット情報・Windowsのイベントログ・死活監視の情報など様々です。 332 | その中には、Logstashでは収集できない種別のデータもあります。 333 | //} 334 | 335 | @{description-beats}では、@{できます}という文言を最小限に抑えました。 336 | そのプロダクト特有の機能のみ@{できます}を利用し、それ以外は機能の特徴を並べるだけにします。 337 | 338 | ==== B. リストを使う 339 | 340 | 機能の特徴が複数ある場合、@{リスト}記法を用いる方法もあります。リストは、同列の事柄をいくつも並べて示したいときに利用します。 341 | @{description-beats-can}をリスト化すると、次のようになります。 342 | 343 | * 機器のデータを収集する 344 | * ElasticsearchやLogstashにデータを収集する 345 | * ネットワークのパケット情報・Windowsのイベントログ・死活監視の情報などを収集する 346 | * Logstashでは収集できないデータもある 347 | 348 | このように、リストを作ることで@{できます}の多用を回避する手段もあります。 349 | -------------------------------------------------------------------------------- /articles/think-toc.re: -------------------------------------------------------------------------------- 1 | = 原稿を書き始める前の準備 2 | 3 | 技術同人誌を書くときに一番難しいことは、一体何でしょうか。それは、@{書き始める}ことです。 4 | イベントに当選してサークルスペースをもらったときは「さあ、原稿を書くぞ！」と気合が入っているものです。 5 | しかし、いざ原稿を書きはじめようとすると筆が止まってしまいます。これでは困りますよね。 6 | 7 | 筆が止まってしまう時間を少しでも減らすためには、準備がとても大切です。 8 | 9 | == 本の仕様を決定する 10 | 11 | Webアプリケーションや電子工作は、作り始める前に設計を行います。どんなものを作るか、仕様はどうするかなどを検討してから製造を行った方が手戻りがないためです。 12 | これは@{技術同人誌も同じです}。まずはじめに、どんな本を作るか決めましょう。決めやすい項目から手をつけます。こうすると、「進捗している感」を演出できるからです。 13 | 14 | 決めるべき仕様を示します。 15 | 16 | === 頒布方法 17 | 18 | まずはじめに決めるべきは、@{本を印刷するのか}どうかです。印刷する場合、印刷所の示す期限@{の前日}が完了期限となるためです。 19 | 20 | 前日としているのは、@{印刷所の入稿締め切りは日付が変わるまでではないからです}。これは大事なのでもう一度言います。 21 | @{印刷所は、その日の15時までなどと、1日の終わりまでは待ってくれません}。 22 | 23 | つまり、入稿用データ（これを@{完全原稿}と言います）は締め切り日の前日までに完成している必要があるのです。送付時のトラブルなどを考えると、前日までに入稿が完了していることが望ましいです。 24 | 加えて、ページ数が多い場合は締め切りが早まる場合があります。技術同人誌を冊子で頒布するのであれば、@{早めに行動する必要があります}。 25 | 26 | 電子版のみ頒布するのであれば、締め切りはある程度融通が効きます。ダウンロードカードは家でも印刷できますし、キンコーズでも印刷できます。 27 | 最悪、イベント前日にコピー機で印刷することも可能です。 28 | 29 | ただし、名刺カードにQRコードを載せて印刷したいのであれば話は変わります。印刷所の締め切りに合わせて名刺用データを作る必要があります。 30 | 31 | 締め切りから逆算して計算できるようにするために、まずは頒布形態を決めましょう。これ以降は冊子を同人印刷所で印刷してもらうことを前提に話を進めます。 32 | 33 | === 印刷所を決める 34 | 35 | 次に決めるべきは、@{どの印刷所を利用するか}です。締め切り日を概算するためです。初めて同人誌を作成するのであれば、@{イベントのバックアップを行なっている印刷所を利用しましょう}。 36 | これらの印刷所は、刷り上がった本を印刷所から自分のスペースへ@{直接搬入}してくれます。@{宅配搬入}の場合、本の集積所に自分の荷物を引き取りに行く必要があります。 37 | 38 | 宅配搬入の場合、印刷所から宅配業者を経由してイベント会場へ本が届きます。このとき、荷物が行方不明になる事件が発生することがあります。直接搬入であれば、印刷所が責任を持って会場へ本を運んでくれます。 39 | こだわりがない限り、直接搬入ができる印刷所を利用しましょう。 40 | 41 | 技術書典であれば、@{有限会社 ねこのしっぽ}さんを利用するか、@{株式会社 日光企画}さんを利用することになります。 42 | 43 | 私はずっとねこのしっぽさんを利用しています。 44 | Webフォームで発注から入稿まで完結する点・本の仕様がある程度決まっており迷いにくい点がとても嬉しいです。原稿のチェックも入念に行なっていただけます。 45 | 恥ずかしながら、自分では気づかないような誤字脱字を指摘いだだくこともあります。 46 | 47 | 日光企画さんも同人誌界隈で有名な印刷所です。表紙の加工種別が多く、凝った装丁の本を作ることができそうです。サポートの評判も良いと聞いています。 48 | 49 | ただし、印刷所の手厚いサポートを受けるには条件があります。@{締め切り日は厳守、できる限り締め切り日より前に入稿する}ことです。 50 | 原稿に不備があった場合、不備の内容を伝える電話がかかってくることがあります。この場合、修正期限は@{電話がかかってきた当日中}となります。修正箇所が多いと大変です。 51 | 繁忙期の場合、チェック量が減ることもあります。これは相手にするサークルが多いので仕方のないことです。 52 | 53 | しかし期限より前に入稿すれば、修正期限を少し伸ばすことができる可能性があります。また体感とはなりますが、@{原稿のチェックも丁寧にしていただけます}。 54 | 締め切りに遅れると、印刷所の方に残業を強要することになります。社会人同士（学生の方はごめんなさい）、残業を減らせるように努力しましょう。 55 | 56 | === 本のサイズを決める 57 | 58 | 本のサイズを先に決める理由は、@{組版時にページ数が変わるから}です。 59 | 同人印刷のお値段は、@{本のサイズ × ページ数 × 部数}で決定されます。印刷所の相見積もりをとる場合、3つの項目が必要となります。 60 | 61 | ページ数は書きあがってみないとわかりません。残りの2項目を使って値段の比較を行うと良いでしょう。 62 | 63 | 肝心の仕様ですが、@{大学ノートのサイズが"B5"}、@{小さめの技術書のサイズが"A5"}です。選ぶ基準の目安を示しますが、最後は自分の好みで決めましょう。 64 | 65 | * B5を選ぶと良い場合 66 | ** コードブロックをたくさん載せたい 67 | ** 文量が多くなることが予想される 68 | ** 同人誌感を出したい 69 | ** 見栄えが良い同人誌を作りたい 70 | * A5を選ぶと良い場合 71 | ** 少ない文字でページ数を稼ぎたい 72 | ** 手軽に読んでほしい 73 | ** 保管スペースを取りたくない 74 | ** 印刷費を安くしたい 75 | 76 | ページ数はレイアウトや原稿用紙の設定にも関わってきます。そのため、本を書き始める前に決めることをおすすめします。 77 | 78 | === 組版ツールを決める 79 | 80 | 組版ツールは事前に決めておくと良いでしょう。2ヶ月弱の期間で組版ツールを試しつつ、本文を書くのは無謀に近いです。 81 | 82 | テキスト形式で原稿データを作成するツールは@{原稿の静的検査ツールやバージョン管理ツールの恩恵を受けやすい}というメリットがあります。 83 | ただし、PDFデータを作成するためにはTeXのインストールを別に行う必要があります。 84 | TeXの環境構築はかなり面倒で難しいです。先に環境は作成しておきましょう。 85 | 86 | * テキスト形式で原稿データを作成するツールの例 87 | ** Re:VIEW 88 | *** PDF出力にはTeXが別途必要（Dockerイメージあり） 89 | ** Pandoc 90 | *** PDF出力にはTeXが別途必要 91 | 92 | 一方、バイナリ形式で原稿データを作成するツールは@{環境構築や原稿のスタイルを調整するのが楽・入稿しやすい}というメリットがあります。 93 | ソフト自身にPDFを作る機能が存在するため、TeXを準備する必要はありません。 94 | 95 | * バイナリ形式で原稿データを作成するツール 96 | ** Word 97 | ** 一太郎 98 | ** Google Documents 99 | *** txt形式も出力できる 100 | 101 | できれば慣れているものを利用するか、印刷所が指定する形式に出力できるツールを使うべきです。 102 | 103 | 複数人で執筆する場合、面倒でもGitリポジトリ管理できる形式で作成すると良いでしょう。入稿直前に原稿がコンフリクトしてしまうと、目も当てられません。 104 | 105 | == 目次を立てる 106 | 107 | 本の仕様や印刷所を決定した後は、目次を作成しましょう。 108 | 細分化しておくことで、進捗の把握がしやすくなります。また、原稿作成時のガイド的な役割も持っています。 109 | 110 | === 目次を出す 111 | 112 | イベントに申し込む際は@{頒布物の概要}を記述しているはずです。その概要を元に、目次を作成しましょう。次の順番で進めていきます。 113 | 114 | 1. 思いつくままに伝えたいことを羅列する 115 | 2. 羅列した項目を仲間わけする 116 | 3. 仲間わけしたものに名前をつける 117 | 4. 各項目内で伝わりやすいように順序を入れ替える 118 | 119 | === 思いつくままに伝えたいことを羅列する 120 | 121 | @{ブレインストーミング}という技法をご存知でしょうか。コトバンクで意味を調べると、次のような記載があります。 122 | 123 | //quote{ 124 | ブレインストーミング(brainstorming)とは、数名毎のチーム内で1つのテーマに対しお互いに意見を出し合う事で沢山のアイデアを生産し問題の解決に結び付ける創造性開発技法の事をいいます。 125 | //} 126 | 127 | 目次を作るときに重要なことは、@{多くのアイデアを事前に出しておくことです}。このアイデアを目次に使用するからです。 128 | 129 | 文章を書き出せない人は、はじめからアイデアを厳選する傾向があります。 130 | 「このネタは別の人とかぶるかも」「正しくないかも」「こんなものみんな知っているからな」と思う気持ちはわかります。一旦脇に置いておきましょう。 131 | 132 | 同人誌におけるネタ被りはどのジャンルでも存在します。しかし、全く同じ同人誌は存在しません。文章（や絵）の書き方・着目するトピックに個性が出るからです。 133 | また、読者の視点からすると@{同じジャンルの情報はとにかくたくさん集めたい}ものです。あなたも初めての技術に触れるとき、同じネタでも複数の情報源を参考にするはずです。 134 | 気になること、知っておきたかった情報をとにかく羅列しましょう。 135 | 136 | そのアイデアが出ない人もいるかもしれません。そこで、アイデアのヒントをいくつか載せておきます。 137 | 138 | ====[column] 他サークルとのネタ被りに負けないために 139 | 同人誌即売会に参加できるか判明する日を、業界用語で当落発表といいます。 140 | 当落発表直後に「どんなサークルが参加するのか知りたいな」と、Twitterのハッシュタグなどを追いかけてしまうものです。 141 | 142 | しかし、それはあまり得策ではないかもしれません。他のサークルが何を出すか調べるのは、入稿直後にした方が良いです。 143 | 自分よりも「すごい」人が同じネタで本を出そうとしていた場合、別のネタが良いかもしれない…と落ち込んでしまう可能性が高いからです。 144 | 145 | 『技術同人誌を書くための文章技術』は技術書典6で初めて出す本ですが、りまりま団よりも大規模で有名なサークルが、似たようなネタで同人誌を発行する予定であることを観測したためです。 146 | この情報を知ったのは、『技術同人誌を書くための文章技術』の初稿を校正した後です。原稿は「まあこのまま入稿できるでしょ」という状態まで完成していました。 147 | 148 | 正直に言うと「うわーあそことネタ被ってるとか終わった！もうこれは一冊も売れませんわ！」と思いました。 149 | しかし、原稿がほぼ完成していたのが救いでした。「もうできている物だから、捨てるのは勿体無いですわ」と思って踏みとどまれたからです。 150 | 151 | 同じ時期に、この原稿のGitHubリポジトリにStarが付いていたことも幸運でした。見てる人がいるなら大丈夫だろう、と謎の自信が持てたからです。 152 | 153 | これから書き出すときネタ被りの件を知っていた場合、「他のネタにしようか…」とグズグズ迷っていたことでしょう。 154 | 155 | 人間は弱い生き物です。いくら「ネタ被りでもいいんですよ」と言われても、それは強者の理論だろうと感じてしまうものです。 156 | 157 | ネタ被りに負けないようにするためには、他サークルの情報断ちをしておくのが一番です。 158 | 何も知らなければ、傷つくこともありません。 159 | 160 | 傾向分析や反省はイベント終了後にすれば良いのです。まずは入稿することを第一に目指しましょう。 161 | 162 | 163 | ==== 環境構築の方法 164 | 165 | この世で一番難しいのは環境構築と言われるくらい、環境構築は面倒なものです。特にミドルウェアの環境構築方法は、公式ドキュメントの情報だけで理解するのが難しいこともあります。 166 | @{きちんと検証された}環境構築手順がまとまっているだけで、その本のありがたみは増します。 167 | 168 | 私が『ログと情報をレッツ・ラ・まぜまぜ！～ELK Stack で作るBI環境～』という同人誌を書いた動機もここにあります。Elastic Stackを仕事で利用したのは2016年10月でした。 169 | このとき環境構築の手順をまとめたものがなく、構築時にかなりつまづきました。日本語のブログもほぼ情報がなく、情報を見つけてもバージョンが古いため参考にできませんでした。 170 | 171 | 「はー？もうやってられませんわ！！！2度と迷いたくないからまとめたる！！！」と怒りに任せて書いたのが、『ログと情報をレッツ・ラ・まぜまぜ！～ELK Stack で作るBI環境～』です。 172 | 要するに、環境構築をする際に参照できる手順書が欲しかったのです。 173 | 174 | 環境構築の手順を載せるときは、OSごとの手順の違い、ハマりどころとその回避方法がまとまっていると良いです。 175 | 読者の置かれている環境を推測することはできません。多くの手順が網羅されていれば、それだけその本を参考にできる人が増えるからです。 176 | 177 | ==== トラブルシュート 178 | 179 | 対象技術利用時によくあるエラーやトラブルの事例、その対処法を記述するのも良いでしょう。調べるときに利用した参考文献も合わせて提示すると、調査方法の知見も伝えることができます。 180 | 記述しておくと、将来の自分を救ってくれるかもしれません。 181 | 182 | ==== 競合プロダクトとの比較 183 | 184 | 競合プロダクトとの比較を入れることで、紹介する技術の特徴を掴みやすくなるかもしれません。ご自身が技術選定をするとき、調べた内容が役に立つはずです。 185 | 186 | ==== プロダクトや仕様の歴史的背景 187 | 188 | 歴史的背景を知るためには、多くの参考文献を探す必要があります。また、対象に対する深い理解も必要です。自分の知見を深める上でも良い体験になるでしょう。 189 | 190 | == 羅列した項目を仲間わけする 191 | 192 | アイデアの準備ができたら、いよいよ目次を作ります。まずはじめに、@{羅列したアイデアを仲間わけしましょう}。グループの単位が1つの@{章}となります。 193 | 環境構築という仲間わけの例を示します。 194 | 195 | * 参照するべきドキュメント 196 | * OSごとの差異 197 | * 構築手順 198 | * 動作確認方法 199 | 200 | 仲間わけをする基準はあなたの書きたいことによって変化します。一例として、『ログと情報をレッツ・ラ・まぜまぜ！～ELK Stack で作るBI環境～』という本の目次を抜粋して紹介します。 201 | 202 | * 利用する技術の基礎知識・概要 203 | ** Elastic Stackとは 204 | ** ユースケース 205 | ** 競合するもの 206 | * 環境構築 207 | ** 参照するべきドキュメント 208 | ** 構築手順 209 | ** 動作確認方法 210 | * 使い方・設定方法（メイン） 211 | ** Logstashでデータを取得する 212 | *** コンフィグの書き方 213 | *** データ連携の確認をする 214 | *** バージョンごとの差異 215 | ** Kibanaの使い方 216 | *** グラフの作り方 217 | *** グラフの解説 218 | * トラブルシュート 219 | ** よくあるトラブルと解決法 220 | 221 | == 仲間わけしたものに名前をつける 222 | 223 | これが章題となります。アイデアのグループを一言で表すと何か、を検討しましょう。難しいようであれば、@{○○とは}・@{〇〇について}など曖昧な言葉をつけておきます。 224 | 商業誌の目次を参考にしても良いでしょう。 225 | 226 | == 各項目内で伝わりやすいように順序を入れ替える 227 | 228 | 仲間同士のグループを作った後は、説明の順序を決めましょう。@{先に順序を決めておくと、文章を記述しているうちに支離滅裂な本になることを防げます}。 229 | 230 | 本を書いているうちに、最初と最後で主張が異なってしまう可能性を潰しておくべきです。論理展開の修正は時間がかかります。執筆に充てられる時間が少ないので、なるべく手戻りがないようにしましょう。 231 | 232 | 順序を入れ替えたあとは、原稿に反映しておきます。日付が空いてしまっても、すぐ本文を書き出すことができるからです。 233 | 234 | 順序のつけかたに迷うのであれば、@{実際の作業工程と同じ順番に並び替える}と良いです。商業本も作業順に章が進んでいくことが多いです。 235 | 工程通りに進む方が、読者も一緒に環境を作って試しやすく「わかりやすい」同人誌を作成できます。 236 | 237 | 例を示します。 238 | 239 | 1. プロダクト/取り扱う技術の紹介 240 | 2. 環境構築/必要資材の準備 241 | 3. 基本的な使い方/作り方（ここで本の目的を一旦達成しておく） 242 | 4. 応用的な事項 243 | 5. トラブルシュートや補足 244 | -------------------------------------------------------------------------------- /build-in-docker.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | # コマンド手打ちで作業したい時は以下の通り /book に pwd がマウントされます 4 | # docker run -i -t -v $(pwd):/book vvakame/review /bin/bash 5 | 6 | docker run -t --rm -v $(pwd):/book vvakame/review /bin/bash -ci "cd /book && ./setup.sh && npm run pdf" 7 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "TB6-technical-writing-technic", 3 | "version": "0.0.1", 4 | "private": true, 5 | "description": "同人誌の作り方本はあっても文章がかけなきゃ意味ないじゃない！だったら作るしかないですね？", 6 | "main": "Gruntfile.js", 7 | "repository": { 8 | "type": "git", 9 | "url": "git+https://github.com/MofuMofu2/TB6-technical-writing-technic.git" 10 | }, 11 | "author": "", 12 | "license": "MIT", 13 | "bugs": { 14 | "url": "https://github.com/MofuMofu2/TB6-technical-writing-technic/issues" 15 | }, 16 | "homepage": "https://github.com/MofuMofu2/TB6-technical-writing-technic#readme", 17 | "engines": { 18 | "node": ">=6.0.0" 19 | }, 20 | "scripts": { 21 | "site": "cd site ; hugo --cleanDestinationDir", 22 | "global-bundler": "gem install bundler", 23 | "global": "npm run global-bundler", 24 | "postinstall": "bundle install", 25 | "pdf": "grunt pdf", 26 | "md": "grunt markdown", 27 | "html": "grunt html", 28 | "test": "npm run html", 29 | "textlint-markdown": "./node_modules/.bin/textlint --preset ja-technical-writing ./articles/markdown/*.md", 30 | "textlint-review": "./node_modules/.bin/textlint --preset ja-technical-writing ./articles/*.re" 31 | }, 32 | "dependencies": {}, 33 | "devDependencies": { 34 | "grunt": "^1.0.3", 35 | "grunt-cli": "1.2.0", 36 | "grunt-contrib-clean": "1.0.0", 37 | "grunt-open": "0.2.3", 38 | "grunt-shell": "1.3.0", 39 | "js-yaml": "3.6.0", 40 | "load-grunt-tasks": "3.5.0", 41 | "textlint": "^11.2.3", 42 | "textlint-plugin-review": "^0.3.3", 43 | "textlint-rule-preset-ja-technical-writing": "^3.1.2" 44 | }, 45 | "keywords": [] 46 | } 47 | -------------------------------------------------------------------------------- /redpen-conf-ja.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 37 | 38 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | -------------------------------------------------------------------------------- /setup.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | set -eux 4 | 5 | rm -rf node_modules 6 | # --unsafe-perm はrootでの実行時(= docker環境)で必要 非root時の挙動に影響なし 7 | npm install --unsafe-perm 8 | git submodule init && git submodule update 9 | --------------------------------------------------------------------------------