Skip to content

Vivliostyle Pub v1 Req

Jump to bottom
Shinyu Murakami edited this page Jun 15, 2021 · 7 revisions

Vivliostyle Pub v1 要件仕様 (WIP)

生成可能なコンテンツフォーマット

  • PDF
    • 印刷用PDF
    • 閲覧用PDF
  • EPUB
    • リフロー型EPUB
  • WebBook
    • 1冊の本を表すWebコンテンツのファイル群を「WebBook」として定義する
    • 通常Webページとして閲覧可能
    • Vivliostyleで組版・閲覧可能

それぞれの詳細は以下。

PDF

  • 印刷用と閲覧用の2種類のPDFを出力できること
  • 印刷用PDFは PDF/X-1a 対応
    • CMYK可能: Vivliostyle CLI (press-ready)に実装済み✅
    • グレースケール可能: Vivliostyle CLI にオプション追加必要🔧
  • PDF Bookmarks（しおり）による目次付き
    • Vivliostyle CLI に実装済み✅
  • 縦書きの場合、右綴じの設定に
    • Vivliostyle CLI に処理追加必要🔧
  • 閲覧用PDFはテキストがアクセシブルであること
    • Chrome出力PDFの漢字が康熙部首に化ける問題の解決が必須 (解決済み)

EPUB

  • リフロー型EPUBとする
    • CSS組版前のデータであるHTMLを使いリフロー型EPUBを生成する
    • v1では、CSS組版結果を固定型EPUBにする機能は予定しない（ニーズがあれば後で検討）
  • 最新EPUB標準仕様に準拠: EPUB 3.2
  • EPUBCheck ツールで検証されて、Amazon Kindle はじめ各電子書籍書店に対応可能なこと
  • EPUB の内容に含まれるファイルは WebBook 形式と基本的に同じものとする、ただし
    • HTML(拡張子 .html)は XHTML(拡張子 .xhtml)に直す
    • EPUB に必須のファイルを追加: "package.opf", "META-INF/container.xml", "mimetype"

WebBook

  • 通常Webページとして閲覧可能で、Vivliostyle で組版・閲覧可能
  • WebBook内のルートディレクトリに
    • "index.html": 次の内容を含む
      • <link href="publication.json" rel="publication"/> による出版物マニフェストファイルへのリンク
      • <nav role="doc-toc"> 要素による目次、WebBook内の他のHTMLファイルへのリンクを含む
    • "publication.json": 出版物マニフェストファイル
      • 仕様: W3C Publication Manifest
      • 出版物のメタデータ、出版物に含まれるファイルのリスト、内容を読む順番（Reading Order）が含まれる
  • 参考仕様: WebBook Level 1 (Unofficial Proposal Draft)
  • EPUB出力との関係
    • WebBookをソースとしてEPUBを生成
    • EPUBの内容文書はXHTML(拡張子 .xhtml)、WebBookは HTML(拡張子 .html)
      • EPUB生成のときに機械的に HTML→XHTML 変換
      • ✔︎議論済み：WebBookもEPUBと同様にXHTMLファイルにするか？→しない。XHTMLはWebで扱いづらいデメリット
    • EPUBの "package.opf" ファイルは出版物マニフェストファイル "publication.json" の内容などから変換して生成
  • PDF出力との関係
    • WebBookをソースとしてVivliostyleで組版してPDFを生成
  • WebBookの公開
    • WebBookをGitHubページにより公開することが可能
      • 例：ユーザーがGitHubページ公開の設定にした場合、https://<user>.github.io/<repository>/WebBook/ に公開され、Webページとして閲覧可能
        • Vivliostyle Viewer でCSS組版結果を閲覧可能
          • https://vivliostyle.org/viewer/#src=https://<user>.github.io/<repository>/WebBook/&bookMode=true

ファイルとディレクトリ構造

WebBook のファイルとディレクトリ構造の例

  • index.html
  • publication.json
  • content/
    • cover.html
    • titlepage.html
    • foreword.html
    • toc.html
    • ch1.html
    • ch2.html
    • ch3.html
    • ch4.html
    • afterword.html
    • colophon.html
  • assets/
    • cover.jpg
    • fig1.png
    • photo1.jpg
  • themes/
    • css/
      • style.css
      • print.css
    • fonts/
      • foobar.woff

EPUB のファイルとディレクトリ構造の例

  • mimetype
  • META-INF/container.xml
  • EPUB/
    • package.opf
    • content/
      • cover.xhtml
      • titlepage.xhtml
      • foreword.xhtml
      • toc.xhtml
      • ch1.xhtml
      • ch2.xhtml
      • ch3.xhtml
      • ch4.xhtml
      • afterword.xhtml
      • colophon.xhtml
    • assets/
      • cover.jpg
      • fig1.png
      • photo1.jpg
    • themes/
      • css/
        • style.css
        • print.css
      • fonts/
        • foobar.woff

EPUBの内容を生成するのは、ユーザーがEPUBエクスポートを実行を行ったときのみ。EPUBの内容のファイルはEPUBパッケージ(.epub)作成のためにWebBookから変換して生成する。

原稿ファイル類のディレクトリ構造の例

リポジトリのルートに次の配置:

  • package.json
  • README.md
  • LICENSE
  • vivliostyle.config.js
  • content/
    • cover.md
    • titlepage.md
    • foreword.md
    • toc.md
    • ch1.md
    • ch2.md
    • ch3.md
    • ch4.md
    • afterword.md
    • colophon.md
  • assets/
    • cover.jpg
    • fig1.png
    • photo1.jpg
  • themes/
    • scss/
      • style.scss
      • print.scss
      • _variables.scss
    • fonts/
      • foobar.woff

これら原稿ファイル群（出版物のソース）からWebBook（成果物）のHTMLファイル群への変換は、原稿ファイルの更新があるたびに行われるようにする。
そのため、このファイルとディレクトリ構造とWebBookのファイルとディレクトリ構造は、一緒に合わさったものになる（content/ に原稿ファイル(.md)と変換後のHTMLファイルの両方、など）。
WebBookの公開用のビルドのときには、WebBook に含めるファイルとディレクトリだけを公開用の場所にコピーすることになる。
次のIssueの議論を参照: https://github.com/vivliostyle/vivliostyle-pub/issues/55

ユーザーのGitHubリポジトリ作成

ユーザーの出版プロジェクトごとにユーザーのGitHubのリポジトリが使用される。

以下、Vivliostyle Pubサイトにユーザーがアクセスして、執筆・編集作業を開始するまでの処理：

  • ユーザーがVivliostyle PubサイトにアクセスするとGitHubでログイン✨
    • GitHub連携がまだされていないユーザーに対して、GitHub連携の案内
      • GitHubアカウントを持っていないユーザーに対して、その作成方法の案内🔰
      • GitHub Appsのインストール処理
    • GitHubアカウントでログイン
      • ユーザーはログアウトしないでブラウザを閉じた場合、次に開くと最初からログイン状態となる
    • ログイン後の画面は、ユーザーの出版プロジェクトの一覧（すでにあれば）と新規出版プロジェクト作成のメニュー
  • 出版プロジェクトの一覧：ユーザーのGitHubリポジトリのうちVivliostyle Pub用のリポジトリ（出版プロジェクト）があれば一覧✨
    • ユーザーが書き込み権限を持つ他のアカウントや組織のリポジトリも対象とできること（共同編集を可能に）
    • Vivliostyle Pub用のリポジトリの判定
      • デフォルトブランチのルートディレクトリにファイル vivliostyle.config.js が存在すること
        • Vivliostyle CLI 用のプロジェクト（Create Book で生成されたものなど）も Vivliostyle Pub 用に移行可能とする
    • 一覧にはリポジトリ名と出版物のタイトル（vivliostyle.config.js から取得）を表示✨
      • 一覧の順番は更新が最新のものから
    • 出版プロジェクトを一覧から選択して開くと文書編集画面となる
      • 前回に開いたままで終了している場合は、最初から開いた状態（前回の作業状態）に
  • 新規出版プロジェクト作成💪
    • 最初に出版プロジェクト名（＝GitHubリポジトリ名）を入力
      • GitHub APIでリポジトリ生成
    • 以下の設定項目を入力または選択（設定はあとからも変更可能）
      • 出版物のタイトルを入力
      • スタイルテーマを選択
      • 公開リポジトリとするか：デフォルトは非公開
      • ライセンスの種類を選択：デフォルトは❓
    • 設定内容を vivliostyle.config.js に保存、そのほか以下のファイルとディレクトリを生成
      • package.json
      • README.md
      • LICENSE
      • themes/ --スタイルテーマからコピーされたスタイルシート
      • content/ --原稿(.md)を置く
      • assets/ --アップロードされた画像がここに保存される

原稿ファイルの作成と追加

  • 新規出版プロジェクト作成時、スタイルテーマに含まれる原稿テンプレートにより原稿ファイル(.md)を生成💪
    • 🌟要検討：スタイルテーマの原稿テンプレートの仕様
    • 生成されるファイルの例： content/document-1.md
  • 原稿ファイルの追加や構成変更💪
    • 原稿ファイルの追加
      • 本の構成要素の種別を指定
      • ファイル名を指定
    • 原稿ファイルの削除
    • 原稿ファイルの順番の変更

本の構成要素

参考： Wikipedia: Book design
https://en.wikipedia.org/wiki/Book_design

例：

  • Front matter
    • Title page
    • Table of contents
    • Foreword
  • Body matter
    • Chapters and sections
  • Back matter
    • Afterword
    • Appendix
    • Index
    • Colophon

利用する仕様 EPUB-SSV および DPUB-ARIA:

これらの仕様では出版物の構成要素についての語彙が定義されている。 EPUBでは epub:type 属性で、Web出版物では role 属性でそれぞれ定義されている語彙を指定することになっている。

その両方と互換性を持つように、両方の属性がHTMLに出力されるようにする💪

例: <body epub:type="appendix" role="doc-appendix">

表紙画像 (cover)

  • 画像をアップロードして、表紙画像として設定できること💪

タイトルページ (titlepage)

  • 本のメタデータ（タイトル、著者名など）とスタイルテーマによって、自動生成されること💪

目次 (toc)

  • 原稿ファイル群の各見出しとスタイルテーマによって、自動生成されること💪
  • 原稿ファイル内の見出しのどのレベルまでを目次に表示するかを指定できること💪

奥付 (colophon)

  • 本のメタデータ（タイトル、著者名など）とスタイルテーマによって、自動生成されること💪

スタイルテーマ (Vivliostyle Themes)

スタイルテーマの仕様の要件

  • 原稿サンプル(.md)を含むことができる
    • このテーマによってどのような作品ができるかわかるように
  • 原稿テンプレートを含むことができる
    • このテンプレートを使って原稿を書きはじめられるように
    • 本の構成要素ごとに別の原稿テンプレートを設定できること
      • 原稿テンプレートごとに別のスタイルシートを設定できること
  • フォントを含むことができる
  • 複数のスタイルシート(.css)を含むことができる
  • 本の構成要素（前付、本文、後付け、など）ごとに別のスタイルシートを持つことができる
  • 画面用のスタイルシート（一般のWebやリフロー型EPUBとしての表示）とページメディア(Vivliostyle)用のスタイルシートを持つことができる
    • 例：それぞれの名前を style.css と print.css とする
  • Sassを使ったスタイルシート（.scss ファイル）
    • スタイルパラメータをSassの変数で定義

Vivliostyle Pub 上でのスタイルテーマの利用

  • スタイルテーマの選択
    • npm上に公開されている Vivliostyle Themes から選べる
    • 🌟要検討：そのほかのスタイルテーマをどうやって指定する
  • スタイルパラメータの設定
    • 🌟仕組みを検討
  • スタイルシートのカスタマイズ
    • 🌟仕組みを検討
  • スタイルテーマテーマに含まれる原稿テンプレートの利用
    • 🌟仕組みを検討

原稿編集画面とプレビュー

  • プレビュー画面を確認しながらMarkdown入力・編集ができる
  • 🌟デフォルトのプレビュー画面は、変換されたHTMLをブラウザでスクロール表示✨
    • 現在編集中の原稿ファイル(.md)から変換されたHTMLのみ一度にプレビュー表示
    • 編集中の箇所が表示されるようにプレビューを自動スクロール
  • CSS組版ページ・プレビューモードに切り替えることができる
    • プレビュー画面は Vivliostyle Viewer の画面となる

原稿ファイルごとのメタデータの編集

  • マークダウンファイル(.md)では、YAMLメタデータブロックにより原稿ファイルごとのメタデータを設定できる
    • 原稿編集画面のUIからそれらを設定・編集する機能
    • 🌟要検討：原稿ファイルごとのメタデータの仕様

見出しなどの構造要素

  • 見出しなどの構造要素の挿入は、マークダウンで記述するほか、UIのメニューから選ぶことができるようにする

画像の挿入

  • 画像の挿入をUIのメニューからできるようにする
    • 画像ファイルを指定してアップロード
      • assets/ ディレクトリ内に格納される
        • 🌟要検討：ユーザーがサブディレクトリを指定できる機能
    • 画像キャプションの入力
    • マークダウンに反映される
      • 例: ![画像キャプション](../assets/画像ファイル.png)
  • アップロードされた画像の管理機能
    • 追加、削除、ファイル名変更、上書き更新

自動ビルド

  • 原稿ファイル群からWebBookのHTMLファイルへの変換は、原稿ファイル(.md)の更新のたびに行われるようにする💪
    • 時間のかかるフルビルドではなく必要なファイルだけ処理できるようにすることで効率的にすること
    • 原稿編集途中でマークダウン構文にエラーのある状態でビルド処理されることで壊れたHTMLになることのないようにすること

GitHubへの保存

  • 🌟要検討：どのようなタイミングでGitにcommitしてGitHubにpushするか

PDF出力

✍️

EPUB出力

✍️

GitHub Pages での公開

✍️

Clone this wiki locally