FAQ

よくある質問とその回答をまとめました。これからも拡充していきます。質問があればこちらまで!

Vivliostyle Viewer についての FAQ

ローカル環境で Vivliostyle Viewer を使うには?

👉Vivliostyle Viewer の配布パッケージの README(日本語) の「配布パッケージ vivliostyle-viewer-*.zip を使う場合」をご覧ください。

オンラインの Vivliostyle Viewer でローカルの文書を表示するには?

まず、ローカルWebサーバーを起動して、ローカルのHTML文書にブラウザからアクセスできるようにします。ここでは、ローカルWebサーバーとして Node.js の http-server を使う方法を説明します。

Node.js がインストールされていない場合はまずそのインストールをします。👉https://nodejs.org

ターミナル(Windows ではコマンドプロンプト)で、次のコマンドにより http-server をインストールします:

npm install -g http-server

組版表示したいHTMLやCSSファイルが含まれるディレクトリ上で http-server を次のように起動します:

http-server . --cors -o -c-1

これで、ローカルWebサーバーのURL http://localhost:8080 が開き、ブラウザでローカルにあるファイルの一覧を見ることができます。そこで表示したいHTMLファイルを見つけてそのURLをコピーし、別に開いたオンラインの Vivliostyle Viewer https://vivliostyle.org/viewer/ にそのURLを指定して組版表示することができます。 (http-server コマンドの --cors オプションは、別のドメインでのスクリプトからこのローカルサーバーの文書をアクセスできるようにする指定、-o オプションはブラウザを起動する指定、-c-1 はキャッシュを無効にする指定です。)

GitHubやGistにある文書を Vivliostyle Viewer で表示するには?

GitHubGist 上にあるHTML文書を Vivliostyle Viewer で表示することができます。

例1: GitHubリポジトリ内のHTMLファイル https://github.com/vivliostyle/vivliostyle.js/blob/master/packages/core/test/files/math-sample.html を Vivliostyle Viewer で開く: https://vivliostyle.org/viewer/#src=https://github.com/vivliostyle/vivliostyle.js/blob/master/packages/core/test/files/math-sample.html

  • GitHub上のファイルのURLをそのまま Vivliostyle Viewer に指定できます。

例2: Gist に置かれた HTML ファイル https://gist.github.com/MurakamiShinyu/4f0423fd3578a277c7d29f56a31912b7#file-index-html を Vivliostyle Viewer で開く: https://vivliostyle.org/viewer/#src=https://gist.github.com/MurakamiShinyu/4f0423fd3578a277c7d29f56a31912b7/raw/af7fea921d57d6601d153101850bf95850262ece/index.html&bookMode=true

  • Gist上のファイルの Raw コンテンツへのリンクのURLを Vivliostyle Viewer に指定できます。
  • この例では URL にパラメータとして &bookMode=true を指定することにより、この HTML ファイル内の目次からリンクされる複数のHTMLファイルをロードします。

EPUBを閲覧するには?

Vivliostyle Viewer では ZIP 解凍済みの EPUB ファイルを表示することができます。この場合、次のようにパラメータを指定します:

#src=⟨表示する解凍済みEPUBフォルダのURL⟩&bookMode=true

GitHub上に公開されているZIP解凍済みのEPUBファイルを表示する例:

👉ユーザーガイドの EPUB

Webサイトに Vivliostyle Viewer を組み込むには?

Vivliostyle Viewer の配布パッケージをダウンロードして解凍した内容をWebサーバー上の公開ディレクトリにコピーします。パッケージ内容の viewer/ ディレクトリに Vivliostyle Viewer があります。例えば https://example.com/example/ として公開されるディレクトリにパッケージ内容をコピーした場合、https://example.com/example/viewer/ が Vivliostyle Viewer のURLになります。

目次パネルを有効にするには?

HTMLファイル内に次のような目次要素がある場合、Vivliostyle Viewer で Book Mode を指定することで、目次パネルが有効になります。

<nav role="doc-toc">
  <h2>Table of Contents</h2>
    <ol>
      <li><a href="#section1">First Section</a></li>
      <li><a href="#section2">Second Section</a></li>
      <li><a href="#section3">Third Section</a></li>
    </ol>
</nav>

👉ユーザーガイドの 目次パネル

👉次も参照: 目次を作るには?

複数のHTMLファイルを連結して組版表示するには?

Vivliostyle Viewer で Book Mode を指定した場合、次のように別のHTMLファイルへのリンクからなる目次要素を含むHTMLファイルをロードすると、目次要素内からリンクされているHTMLファイルも連続してロードされて、それらが連結された組版表示となります:

<nav role="doc-toc">
  <h2>Table of Contents</h2>
    <ol>
      <li><a href="chapter1.html">First Chapter</a>
        <ol>
          <li><a href="chapter1.html#section1">First Section</a></li>
          <li><a href="chapter1.html#section2">Second Section</a></li>
        </ol>
      </li>
      <li><a href="chapter2.html">Second Chapter</a></li>
    </ol>
</nav>

👉ユーザーガイドの Web出版物(複数HTML文書)

👉次も参照: 目次を作るには?

Book Mode とは?

Vivliostyle Viewer のUIの Book Mode チェックボックスをチェック、あるいはURLパラメータに &bookMode=true を追加することにより Book Mode が有効になります。このモードでは、次の機能が有効になります:

文字サイズを可変にするには?

Vivliostyle Viewer のUIには A⁻ (Text: Smaller), A⁺ (Text: Larger), A⁼ (Text: Default Size) のボタンがあり、表示する文字のサイズを変えることができます。しかし、文書に指定されているスタイルシートに固定の文字サイズが指定されていると、UI から文字サイズを変更できません。

UI から文字サイズを変更できるようにうするには、font-size の指定に相対的な長さの単位(%, em, rem)を使うことです。Vivliostyle Viewer では、font-size のデフォルトは、ブラウザと同様に 12pt (= 16px) です。ルート要素で font-size を設定していない場合、rem (root em) 単位を使うと、そのデフォルトの font-size を 1rem として、相対的な文字サイズの指定ができます。そうすると、Vivliostyle Viewer UI からの文字サイズ変更が有効になります。

スタイルシートでルートの font-size を相対的に指定するには、12pt (= 16px) を 100% とした % 単位を使えます。例:

:root {
  font-size: 87.5%; /* set 1rem = 10.5pt (87.5% of 12pt) */
}

ページサイズを可変にするには?

Vivliostyle Viewer は、スタイルシートによるページサイズの指定がない(あるいは auto が指定されている)場合、ブラウザのウインドウの表示領域をページサイズとします。これにより、画面の大きさに応じた可変のページサイズでの表示が可能です。

また、Vivliostyle Viewer の設定メニューの User Style PreferencesPage Size でページサイズを指定することも可能です。ここで指定するページサイズはスタイルシートで次のようにページサイズを指定するのと同じことになります:

@page { size: A4; }

Vivliostyle CLI についての FAQ

PDFの「しおり」(Bookmarks)を有効にするには?

Vivliostyle CLI v2.1 以降では、組版する文書の目次データを使ってPDFの「しおり」(Bookmarks) を自動生成することができます。PDF の「しおり」は、Adobe Acrobat のような PDF 閲覧ソフトで目次ナビゲーションに利用できるものです。

PDFの「しおり」生成を有効にするには vivliostyle build コマンドに --book オプションを指定する必要があります。

例:

vivliostyle build --book --size A4 --output example.pdf example.html

EPUBをPDFに変換するには?

Vivliostyle CLI ではZIP解凍済みのEPUBファイルからPDFを生成することができます。それには vivliostyle build コマンドに –book オプションを指定して、入力として解凍済みEPUBのディレクトリを指定します。

例えば、EPUBファイル example.epub をPDFファイル example.pdf に変換するには、次のように、まずEPUBファイルをZIP解凍してそれから vivliostyle を実行します:

unzip example.epub -d example/
vivliostyle build --book --size A4 --output example.pdf example/

印刷用のPDF(PDF/X-1a 形式)を生成するには?

vivliostyle build コマンドの --press-ready オプションにより印刷入稿に適した PDF/X-1a 形式で出力することができます。

この機能を使うためには GhostscriptXpdf(または Poppler)をインストールする必要があります。主なOSでそれらをインストールする方法は以下です:

macOS (Homebrew を利用):

brew install poppler ghostscript

Ubuntu:

apt-get install poppler-utils ghostscript

Windows:

  • Ghostscript for Windows を https://www.ghostscript.com/download/gsdnld.html からダウンロードしてインストール。それからインストールしたGhostscriptの実行ファイルのあるディレクトリ(例:”C:\Program Files\gs\gs9.52\bin”)を PATH 環境変数に追加。
  • Xpdf command line tools for Windows を http://www.xpdfreader.com/download.html からダウンロードしてインストール。それからインストールしたXpdfの実行ファイルのあるディレクトリ(例:”C:\xpdf-tools-win-4.02\bin64”)を PATH 環境変数に追加。

Create Book についての FAQ

Create Book とは?

Create Book は、簡単に本を作れる環境を構築します。

👉チュートリアルガイド: Create Book

テーマをカスタマイズするには?

Create Book によりインストールされたテーマパッケージは、プロジェクトフォルダ内の node_modules フォルダ内にインストールされます(例:テーマ「techbook」の場合 node_modules/@vivliostyle/theme-techbook/)。これを別のフォルダ(例えば my-theme/ フォルダ)にコピーしてカスタマイズすることができます。

cp -R node_modules/@vivliostyle/theme-techbook/ my-theme/

そして vivliostyle.config.js ファイルの theme: のところを次のように変更します:

  theme: '@vivliostyle/theme-techbook', // .css or local dir or npm package. default to undefined.

  theme: 'my-theme',

これで my-theme フォルダ内のスタイルシートをカスタマイズして自由にスタイルを変えることができるようになります。

既存のテーマパッケージをコピーしないで、オリジナルのテーマを作ることもできます。その場合、テーマのフォルダ(この場合 my-theme フォルダ)内に、次のような package.json ファイルを作る必要があります:

{
  "name": "my-theme",
  "main": "theme.css"
}

CSS組版のテクニックについてのFAQ

複数のHTMLファイルから本を作るには?

👉ユーザーガイドの Web出版物(複数HTML文書) をご覧ください。

Vivliostyle CLI でこの機能を使うには --book オプションを指定します。

目次を作るには?

HTMLのマークアップで目次を作るには、<nav role="doc-toc"></nav> で囲むブロック内に目次項目(本文中の各見出しへのリンク)のリストを入れます。

参考:W3CのPublication Manifest仕様の付録の Machine-Processable Table of Contents

ページ番号入りの目次のスタイルは、次のようなスタイルシートによって実現できます:

nav li a {
  display: inline-flex;
  width: 100%;
  text-decoration: none;
  break-inside: avoid;
  align-items: baseline;
}
nav li a::before {
  margin-left: 3px;
  margin-right: 3px;
  border-bottom: 1px dotted;
  content: "";
  order: 1;
  flex: auto;
}
nav li a::after {
  text-align: right;
  content: target-counter(attr(href url), page);  
  align-self: flex-end;
  flex: none;
  order: 2;
}

実例については、Vivliostyleのサンプル紹介ページ https://vivliostyle.org/ja/samples/ の「目次」タグが付いたサンプルをご覧ください。

👉以下も参照:

数式(MathML、TeX、AsciiMath)を埋め込むには?

Vivliostyle Viewer では MathJax により数式を組版表示することができます。

次の形式の数式をHTML文書内に埋め込むことができます:

  • MathML
  • TeX 数式
  • AsciiMath

MathML の要素 <math></math> は、HTML文書内に直接書くことができます。

TeX または AsciiMath の数式を利用するには、その数式を含むHTML要素に属性 data-math-typeset="true" を指定し、テキスト内に以下の方法で数式を記述します:

  • TeX 数式は \(\) または $$$$ で囲む
  • AsciiMath は ` … ` で囲む

数式のテストのHTMLソース: https://github.com/vivliostyle/vivliostyle.js/blob/master/packages/core/test/files/math-sample.html

Vivliostyle Viewer で組版表示: https://vivliostyle.org/viewer/#src=https://github.com/vivliostyle/vivliostyle.js/blob/master/packages/core/test/files/math-sample.html

👉vivliostyle.js issue#523: ASCIIMATH and MathJAX

本の途中でページ・カウンターをリセットするには?

👉vivliostyle.js issue#522: “reset-counter: page;” doesn’t work properly with web publications をご覧ください。

Vivliostyle のライセンスについての FAQ

Vivliostyle のオープンソース・ライセンスの種類は?

Vivliostyle はオープンソース・ライセンスとして AGPLv3 (GNU Affero General Public License, version 3) を採用しています。

AGPL は、GPL (GNU General Public License) と同様の互恵的なライセンス(派生物にも同じライセンスが適用される)であり、ソフトウェアの改変や商用利用が許可されています。GPL と異なる点は、ネットワーク経由の利用者にもソースコードにアクセスする権利が保証されることです。

参照:

Vivliostyle ソースコードのコピーライトの帰属先は?

Vivliostyle のソースコードには、次のようなコピーライト表記があります: (epub.ts の例)

  • Copyright 2013 Google, Inc.
  • Copyright 2015 Trim-marks Inc.
  • Copyright 2018 Vivliostyle Foundation

「Copyright 2013 Google, Inc.」とあるのは、Vivliostyle がもともと、Google に所属する Peter Sorotokin 氏によって開発された EPUB Adaptive Layout JavaScript-based implementation (“Adapt”) をベースとして開発されたためです。この元プロジェクト由来のソースコードの権利は Google にあります。

Trim-marks 社(旧社名は Vivliostyle Inc.)は、2015年から2018年3月までのあいだ、Vivliostyle の開発の主体でした。この期間に書かれた Vivliostyle ソースコードの権利は Trim-marks 社にあります。また、Vivliostyle のライセンスは当初、元プロジェクトの “Adapt” を継承して Apache License 2.0 でしたが、2017年2月から AGPLv3 に変更されました。

Vivliostyle Foundation は、2018年3月に Trim-marks 社がオープンソース版の Vivliostyle の取り扱いをやめてから、そのオープンソース管理を引き継ぎました。それ以降に書かれた Vivliostyle のソースコードの権利は Vivliostyle Foundation にあります。

Vivliostyle を利用して作られた出版物にオープンソース・ライセンスによる制約はありますか?

いいえ。Vivliostyle のライセンスが AGPL であることは、Vivliostyle を利用して作られた出版物には影響しません。出版物のソースデータ(HTML や CSS)を公開する義務はとくにありません。

会社内で Vivliostyle を制限なく利用できますか?

はい。Vivliostyle を会社・組織内でコピーして利用するのは自由であり、ソースコードを改変しても公開する義務はありません。

参照(GNUライセンスFAQ):

Vivliostyle Viewer または Vivliostyle Print を商用の Web アプリケーションから呼び出して利用することはできますか?

はい。Vivliostyle Viewer および Vivliostyle Print は、クライアントサイドのブラウザ上で独立したプログラムとして動作するものなので、サーバーサイドのプログラムやクライアントサイドの別のプログラムがプロプライエタリであっても、それらと組み合わせて利用することが可能です。

Vivliostyle (Viewer/Print) を改変して利用することも、改変したソースコードを公開するならば可能です。ただし、AGPL である Vivliostyle のプログラムと、それを呼び出すプロプライエタリなプログラムとがそれぞれ独立を保った形でコミュニケートする必要があります。

参照(GNUライセンスFAQ):

Vivliostyle Viewer が独立したプログラムとして動作する条件は?

Vivliostyle Viewer は、そのメインの HTML ファイルと、そこからリンクされている JavaScript ライブラリで構成されます。それが商用の Web アプリケーションと同じ Web サーバー上に置かれて使用される場合でも、それはエンドユーザーの Web ブラウザ上にロードされて実行されるものなので、サーバー側で動作する Web アプリケーションのプログラムとは明確に分離されています。

Vivliostyle Viewer で表示する対象の文書の URL や表示設定などのデータは Vivliostyle Viewer のメインの HTML ファイルの URL に付加される URL のフラグメント・パラメータで指定されます。商用の Web アプリケーションのフロントエンド側のプログラム(JavaScript など)と Vivliostyle プログラムとの間でのデータのやりとりに、この URL パラメータを使うのであれば、ふたつのプログラムを結合する必要がないので、Vivliostyle Viewer を独立したプログラムとして扱うことができます。

Vivliostyle Print が独立したプログラムとして動作する条件は?

Vivliostyle Print は、Web ページに Vivliostyle での組版処理をともなった印刷機能を付加する JavaScript プログラムです。これを、商用 Web アプリケーションのフロントエンド側など別プログラムから使用する場合、パラメータを指定して Vivliostyle Print プログラムのメインの関数を呼び出して、その処理の終了を待つことになります。終了コードや処理したページ数など単純な戻り値を返すかもしれません。このような使われ方であれば、ふたつのプログラムどうしで複雑なデータ構造を共有したり相互的なデータのやりとりをするわけではないため、Vivliostyle Print を独立したプログラムとして扱うことができます。

Vivliostyle CLI をサーバーサイドで利用することはできますか?

はい。Vivliostyle CLI は、サーバーサイドの別のプログラムから呼び出されても、それぞれが独立したプログラムとして動作するかぎりは、呼び出す側のプログラムがプロプライエタリであっても問題ありません。

Vivliostyle を商用利用する上で気を付けるべき制限事項は?

Vivliostyle を AGPL ライセンスに従いながら商用利用する上で、以下のことに気を付ける必要があります:

  • Vivliostyle を改変して配布する場合(注意:Webサイトでの利用も含まれます)、改変した Vivliostyle のソースコードを公開する必要があります。
  • Vivliostyle を組み込んで単一の結合したプログラムとして動作するものを作成して配布する場合は、その全体のソースコードを AGPL ライセンスで公開する必要があります。
  • Vivliostyle のソースコードを改変する場合は、ソースファイルのヘッダーコメントにあるコピーライトの記述を保持してください。「Copyright 2013 Google, Inc.」の記述があるソースファイルには元プロジェクトである “Adapt” 由来のソースコードが含まれており、その元ソースコードは Apache License 2.0 の適用を受けます。READMELICENSE ファイルの次の記述を保持してください:

    Vivliostyle Core is implemented based on Peter Sorotokin’s EPUB Adaptive Layout implementation, which is licensed under Apache License, Version 2.0.