vivliostyle-2020-spring

Vivliostyle CLI による合同誌作り

Transcript

1. Vivliostyle CLI による
   合同誌作り
   @akabekobeko
   Vivliostyle User/Dev Meetup 2020 Spring 2020/4/4
   1
   

   View Slide

2. もくじ
   本⽇のテーマ
   Vivliostyle CLI
   Markdown
   SCSS (Sass)
   要素技術を組み合わせる
   共同執筆
   VFM と Vivliostyle Pub
   2
   

   View Slide

3. 本⽇のテーマ
   3
   

   View Slide

4. 本⽇のテーマ
   技術書典 7 で頒布した「Vivliostyleで本を作ろう Vol.2」の執筆環境について解説します
   技術書典 応援祭で頒布中の Vol.3 も同系の環境です
   ソースコードは以下に公開されています
   Vol.1 https://github.com/spring-raining/tbf06-draft
   Vol.2 https://github.com/spring-raining/tbf07-draft
   Vol.3 https://github.com/spring-raining/tbf08-draft
   env-create-book https://github.com/akabekobeko/env-create-book
   Vol.1 を参考にして env-create-book を実装、それが更に Vol.2 以降の元となっています。
   本⽇のテーマ 4
   

   View Slide

5. Vivliostyle CLI
   Vivliostyle CLI 5
   

   View Slide

6. Vivliostyle CLI とは？
   Web 標準技術による組版エンジン Vivliostyle を操作するためのツールです
   緑⾖はるさめさん (@spring_raining) により開発された vivliostyle-savepdf が元になっ
   ています
   以下で絶賛開発中！
   https://github.com/vivliostyle/vivliostyle-cli
   Vivliostyle CLI 6
   

   View Slide

7. できること
   Vivliostyle を利⽤して以下の機能を提供します。
   Web 標準技術で記述された⽂書を組版して Web ブラウザーに表⽰する
   Web 標準技術で記述された⽂書を組版して PDF 出⼒する
   これらを簡単なコマンドで実⾏する
   Web 標準技術とは主に HTML/CSS となります。Vivliostyle 本体でもこれらは可能ですが、
   動かすまでの環境を構築するのは⼿間です。
   Vivliostyle CLI をインストールすれば、あとは HTML/CSS を⽤意するだけで Vivliostyle に
   よる組版機能を簡単に利⽤できます。
   Vivliostyle CLI 7
   

   View Slide

8. インストール
   Vivliostyle CLI は npm として配布されています。Node.js と npm が利⽤できる環境を整え
   たら以下のコマンドを実⾏することでインストールされます。
   npm install -g @vivliostyle/cli
   Vivliostyle CLI 8
   

   View Slide

9. 使い⽅
   HTML/CSS で記述された⽂書が content
   に配置されているならば、以下のコマンドで組版
   されたものを Web ブラザーへ表⽰します。
   vivliostyle preview content --book
   PDF 出⼒の場合は以下のコマンドになります。
   vivliostyle build --book -s JIS-B5 content
   HTML/CSS の書き⽅は「Vivliostyleで本を作ろう Vol.1」内の記事が参考になります。
   Vivliostyle Viewer で CSS 組版ちょっと⼊⾨ - 村上 真雄 @MurakamiShinyu
   https://vivliostyle.github.io/vivliostyle_doc/ja/vivliostyle-user-group-
   vol1/shinyu/index.html
   Vivliostyle CLI 9
   

   View Slide

10. 課題
    Vivliostyle CLI は⾮常に便利ですが、組版される HTML の記述には課題があります。
    ⻑い⽂章を素の HTML で書くのは厳しい
    タグ記法の冗⻑さによるタイピング増加
    タグ整合を取りながら書くにはツールの補完が必要
    実例として著名な CMS ツール WordPress も基本は HTML で記述しますが、段落となる
    
    の省略を許可したり WYSIWYG エディターを提供しています。
    こうした補助なしに、⻑い HTML を破綻なく快適に書くのは難しいのです。
    Vivliostyle CLI 10
    

    View Slide

11. Markdown
    Markdown 11
    

    View Slide

12. 簡易 HTML としての Markdown
    ⾒出しや段落など、⽂章に頻出するものを簡易に書ける記法として Markdown が普及してい
    ます。
    # Title
    The quick brown fox jumps over the lazy dog
    このような簡易記法で⽂章を書けます。また処理系によっては Markdown の記法で⾜らない
    機能を HTML 埋め込みで補うことも可能です。
    合同誌の執筆環境ではこの点を評価して、Markdown (with HTML) な記法を採⽤しました。
    Markdown 12
    

    View Slide

13. Markdown を HTML に変換する
    ⽂章を Markdown で書き、組版を担当する Vivliostyle CLI には HTML として渡します。そ
    のための変換ツールとして remark を選びました。
    remarkjs/remark https://github.com/remarkjs/remark
    remark とその周辺ツールを利⽤することで、Markdown を好みの HTML に変換できます。
    プログラミングの知識は必要となりますが、代わりに独⾃の処理も追加できます。
    合同誌の場合、Markdown 冒頭に著者などのメタデータを記述できるようにして、それを
    HTML 要素の CSS クラス名へ反映させるなどの独⾃処理を実装しました。
    Markdown 13
    

    View Slide

14. 校正
    ⽂章の校正は textlint を利⽤。これは様々なルールを組み合わせて校正するためのツールで
    Markdown にも対応しています。
    textlint/textlint https://github.com/textlint/textlint
    ルールの npm をインストールして .textlintrc
    というファイルに設定を定義。以下のよ
    うにコマンドを実⾏することでルール違反している箇所を教えてくれます。
    textlint ./src/content/**
    ルールとして「全⾓・半⾓の分かち書き」などを⼊れています。合同執筆ということもあっ
    て利⽤は強制しませんでした。実際に採⽤したのは私だけかもしれません。
    Markdown 14
    

    View Slide

15. VS Code (Visual Studio Code)
    私は執筆⽤のテキスト エディターに VS Code を採⽤しました。理由は以下となります。
    標準で Markdown 対応、リアルタイム プレビューもある
    textlint プラグインによってリアルタイムに校正できる
    難点として macOS 環境かつ Google ⽇本語⼊⼒だと変換候補のポップアップ位置がズレる
    問題があります。
    当該 Issue https://github.com/microsoft/vscode/issues/45629
    執筆当時はこれを我慢して (慣らされて) 使⽤していたのですが、最近のバージョンだと完治
    はしていませんが症状は改善されてきたようです。
    Markdown 15
    

    View Slide

16. SCSS (Sass)
    SCSS (Sass) 16
    

    View Slide

17. SCSS (Sass)
    Vivliostyle CLI による組版で HTML と共に重要なのが CSS です。これは外観を担当しま
    す。⽂章と異なり CSS は外観の定義なので、素の CSS で書いても実⽤⼗分です。
    しかし CSS ファイルの分割と参照、クラス階層化などの便利な機能を利⽤したいので Sass
    を採⽤しました。記法は CSS 標準に近い SCSS です。
    Sass: Syntactically Awesome Style Sheets https://sass-lang.com/
    Sass: Syntax https://sass-lang.com/documentation/syntax#scss
    SCSS で書いたものをツールで CSS に変換しています。これを HTML と同じく Vivliostyle
    CLI が参照する位置へ出⼒することで、組版対象となります。
    SCSS (Sass) 17
    

    View Slide

18. SCSS のファイル分割
    CSS 標準でもファイルを分割して @import
    により参照できます。しかしこれは HTML に読
    み込まれた際に参照を解決してゆくため、HTML の解析処理をそこで停⽌させてしまいま
    す。
    SCSS の場合は CSS 変換時に参照を解決し、その結果を単⼀ CSS ファイルに出⼒できま
    す。そのため開発側の都合で気軽に分割しています。
    今回は利⽤しなかったのですが、この性質を利⽤して
    合同誌の執筆者ページ単位で SCSS ファイルを⽤意して出⼒をカスタマイズする
    という構想もありました。
    SCSS (Sass) 18
    

    View Slide

19. 要素技術を組み合わせる
    要素技術を組み合わせる 19
    

    View Slide

20. タスク ランナー
    要素技術は揃いましたが、これらを個別に実⾏するのは⾯倒です。そこで組み合わせるため
    の仕組みを利⽤します。これをタスク ランナーと呼びます。代表的なものは以下。
    Grunt https://gruntjs.com/
    Gulp https://gulpjs.com/
    npm-scripts https://docs.npmjs.com/misc/scripts
    Grunt、Gulp の順に流⾏。私も利⽤していました。しかし 2016 年からは npm-scripts に落
    ち着いています。
    拙ブログの解説記事 https://akabeko.me/blog/2016/10/npm-scripts-web-front-end-
    development/
    要素技術を組み合わせる 20
    

    View Slide

21. npm-scripts 1
    npm-scripts は npm の機能です。Vivliostyle CLI をインストールできている環境なら有効に
    なっています。Node.js プロジェクトの package.json
    ファイルにコマンドを定義すること
    で呼び出せます。
    {
    "scripts": {
    "build:pdf": "vivliostyle build --book -s JIS-B5 content/",
    "preview": "vivliostyle preview content/ --book"
    }
    }
    これは npm run build:pdf
    のように呼び出せます。
    要素技術を組み合わせる 21
    

    View Slide

22. npm-scripts 2
    npm-run-all というツールで npm-scripts のコマンド同⼠を簡単に組み合わせられます。
    npm-run-all https://www.npmjs.com/package/npm-run-all
    これを利⽤して
    . Markdown ファイルを HTML 変換する
    . SCSS ファイルを CSS に変換する
    . 1 と 2 で⽣成されたものを Vivliostyle CLI で組版する
    を 1 コマンドで実⾏したりしています。便利ですね。
    要素技術を組み合わせる 22
    

    View Slide

23. 共同執筆
    共同執筆 23
    

    View Slide

24. GitHub
    要素技術が揃ったので、これらを組み合わせた合同誌プロジェクトを GitHub リポジトリーと
    して⽤意します。冒頭で紹介した
    https://github.com/spring-raining/tbf07-draft
    https://github.com/spring-raining/tbf08-draft
    などがそれです。執筆陣はこのリポジトリーを利⽤して編集してゆきます。
    共同執筆 24
    

    View Slide

25. 執筆
    執筆者は前述のリポジトリーを GitHub 上で fork します。
    akabekobeko/tbf08-draft https://github.com/akabekobeko/tbf08-draft
    これを git clone
    してから、プロジェクト内に content/akabeko
    のような感じで⾃分の
    ディレクトリーを作成します。
    この中に index.md
    という名前の Markdown ファイルを置けば HTML 変換の対象となるの
    で、原稿を編集してゆきましょう。画像などが必要なら、それらも同じディレクトリー内に
    ⼊れておくと参照しやすくてよいです。
    ![
    画像](profile.png)
    共同執筆 25
    

    View Slide

26. 投稿
    投稿は GitHub の Pull Request 機能を利⽤します。この辺は⻑くなるので以下のページを参
    照してください。
    プルリクエストの作成⽅法 - GitHub ヘルプ
    https://help.github.com/ja/github/collaborating-with-issues-and-pull-
    requests/creating-a-pull-request#further-reading
    プルリクエストとは？｜サルでもわかるGit⼊⾨【プロジェクト管理ツールBacklog】
    https://backlog.com/ja/git-tutorial/pull-request/01/
    難しければ原稿ファイルを GitHub 操作に詳しい執筆者に渡して、操作を代⾏してもらうのも
    よいでしょう。
    投稿 26
    

    View Slide

27. VFM と Vivliostyle Pub
    VFM と Vivliostyle Pub 27
    

    View Slide

28. VFM
    合同誌の執筆で採⽤した Markdown 記法は必要に応じて拡張しました。しかし明確な仕様や
    運⽤⽅針がないため
    どのような記法が有効なのか分からない
    必要な記法の追加⽅法が不明確、プログラムを修正する？
    などの問題があります。これを解決するために Vivliostyle としての Markdown を定義するこ
    とにしました。これを VFM (Flavored Markdown) と呼びます。
    VFM と Vivliostyle Pub 28
    

    View Slide

29. VFM の仕様策定
    VFM の記法や機能などの仕様は以下の GitHub リポジトリーで策定を進めています。
    Issues https://github.com/vivliostyle/vfm/issues
    Working Draft https://github.com/vivliostyle/vfm/blob/master/spec/vfm.md
    興味があれば議論に参加してみてください！
    個⼈的には Working Draft の Walled block が気になっています。HTML 埋め込みが可能だと
    しても最⼩限にしたい勢としては要注⽬の記法です。
    VFM と Vivliostyle Pub 29
    

    View Slide

30. Vivliostyle Pub
    ここまでの登壇を聞いて、⾃分も同じような環境で執筆したいと考えた⽅がいらっしゃるか
    もしれません。
    しかしプログラミングや GitHub 操作に慣れていないとハードルは⾼いと思います。
    この問題を解決するために Vivliostyle Pub という Web サービスの⽴ち上げを計画していま
    す。
    VFM と Vivliostyle Pub 30
    

    View Slide

31. Vivliostyle Pub 概要
    詳細は他の登壇にゆずりますが、⼤まかには
    Web ブラウザーだけで執筆、Web 公開、PDF 出⼒、⼊稿までを完結可能
    本登壇で紹介したような環境が⽤意されている、⾃分で構築しなくてもよい
    VFM で執筆可能
    ...etc
    となります。お楽しみに！
    このスライドは Marp というツールで作成しましたが、将来は Pub で書いて発表したいです
    ね。そういう機能も検討しています。
    VFM と Vivliostyle Pub 31
    

    View Slide

32. ご清聴
    ありがとうございました
    Vivliostyle CLI による合同誌作り 32
    

    View Slide