CLI 6.0.0 (2022-12-17)にともなう変更範囲を見積もる

[ogwata]

No description provided.

[ogwata]

はじめに

手始めとして、Vivliostyle CLIのドキュメント（以下、CLI Doc）が、どのくらい現状を反映しているか調べようと思いました。

そこで、README.mdのうち、Build, previewにあるオプションと、CLI Docで説明されているオプションとを比較してみました。

（ただし現在のREADMEは、2022年9月22日修正の72c5801で、v6.0.0は反映していません）

CLI Doc記載のオプション

-o, --output specify output file name or directory [<title>.pdf]
-f, --format specify output format corresponding output target
-s, --size output pdf size [Letter]
--style additional stylesheet URL or path
--user-style <user_stylesheet> user stylesheet URL or path
-d, --single-doc single HTML document input
-p, --press-ready make generated PDF compatible with press ready PDF/X-1a
-T, --theme theme path or package name

CLI Doc未記載のオプション（helpは除外）

build

-c, --config <config_file> path to vivliostyle.config.js [vivliostyle.config.js]
-m, --crop-marks print crop marks
--bleed extent of the bleed area for printing with crop marks [3mm]
--crop-offset distance between the edge of the trim size and the edge of the media size. [auto (13mm + bleed)]
--css custom style CSS code. (ex: ":root {--my-color: lime;}")
-t, --timeout timeout limit for waiting Vivliostyle process [120]
--title <title> title
--author author
-l, --language language
--render-mode if docker is set, Vivliostyle try to render PDF on Docker container [local] (choices: "local", "docker")
--preflight apply the process to generate PDF for printing (choices: "press-ready", "press-ready-local")
--preflight-option <options...> options for preflight process (ex: gray-scale, enforce-outline) Please refer the document of press-ready for further information.
--verbose verbose log output
--no-sandbox launch chrome without sandbox. use this option when ECONNREFUSED error occurred.
--executable-browser specify a path of executable browser you installed
--image specify a docker image to render
--http launch an HTTP server hosting contents instead of file protocol It is useful that requires CORS such as external web fonts.
--viewer specify a URL of displaying viewer instead of vivliostyle-cli's one It is useful that using own viewer that has staging features.

preview

-c, --config <config_file> path to vivliostyle.config.js
-T, --theme theme path or package name
-s, --size output pdf size [Letter] preset: A5, A4, A3, B5, B4, JIS-B5, JIS-B4, letter, legal, ledger custom(comma separated): 182mm,257mm or 8.5in,11in
-m, --crop-marks print crop marks
--bleed extent of the bleed area for printing with crop marks [3mm]
--crop-offset distance between the edge of the trim size and the edge of the media size. [auto (13mm + bleed)]
--css custom style CSS code. (ex: ":root {--my-color: lime;}")
--style additional stylesheet URL or path
--user-style <user_stylesheet> user stylesheet URL or path
-d, --single-doc single HTML document input
-q, --quick quick loading with rough page count
--title <title> title
--author author
-l, --language language
--verbose verbose log output
--no-sandbox launch chrome without sandbox (use this option to avoid ECONNREFUSED error)
--executable-browser specify a path of executable browser you installed
--http launch an HTTP server hosting contents instead of file protocol It is useful that requires CORS such as external web fonts.
--viewer specify a URL of displaying viewer instead of vivliostyle-cli's one It is useful that using own viewer that has staging features.
--browser EXPERIMENTAL SUPPORT: Specify a browser type to launch Vivliostyle viewer [chromium] Currently, Firefox and Webkit support preview command only! (choices: "chromium", "firefox", "webkit")

今後の対応

上記を見て分かるように、現在のCLI Docの内容は、v6.0.0への対応以前にかなり古いようです。オプションの説明がCLI Docの全てではありません。それでも、CLI の特長は多様なオプションによる柔軟な出力だと思うので、このあたりはなるべくユーザーが迷わないよう説明したいところです。

v6.0.0への対応作業そのものは、@spring-rainingさんによる、v6.0.0にあわせたREADME.mdの修正、theme-techbookの修正を待つとして、それまでの間に、v6.0.0以前のバージョンへの対応作業をすすめてはどうでしょう？

[ogwata]

現状、CLI Docの構成（H2）は以下の通り

• 組版結果のプレビュー
• Vivliostyle Themes について
• 構成ファイル vivliostyle.config.js
• 印刷用 PDF（PDF/X-1a 形式）の生成
• PDF の「しおり」(Bookmarks) の生成
• 目次の作成
• Web 出版物 (webpub)
• その他のオプション

前掲「CLI Doc未記載のオプション」の中から適宜選択し、上記項目に配分していく構成となるだろう。

上記構成を再考する選択肢もあり得る。たとえば真っ先に「組版結果のプレビュー」がある一方で、「構成ファイル vivliostyle.config.js」が3番目になるなどしており、もうすこし導入順（読者が必要に思う順）を意識した並びにした方がよいようにも思える。最低限、「CLI自体の導入」と「CLIによるデータ作成」は分けないと読者が混乱しそう。

ただし、細かくしすぎたり、文章量が多くなると文書の閲覧性が下がってしまうので注意が必要。

[macneko-ayu]

なるほど、たしかに順番を見直すのはよさそうですね。
どこまで手を入れるかが悩ましいですが、ちょっと考えてみます！

[ogwata]

なるほど、たしかに順番を見直すのはよさそうですね。 どこまで手を入れるかが悩ましいですが、ちょっと考えてみます！

お願いします！
構成を考えるにあたり、すこし関連情報を補足します。
Vivliostyle-Docsはdocuteで生成します。
このシステムの最大の制限は、生成される見出しの深さがH3までということです。
H1は書類名に割り当てられるので、実質的に2階層（章と節）しか表現できないのです。
この点を念頭においていただければと思います。
（たぶんdocute は長文を想定していないのだと思います。）

[ogwata]

@macneko-ayu

8日の開発者会議で進捗を話してみてはどうでしょう。
ざっくばらんに、メモ程度でもけっこうです。

どうかご検討ください。

[spring-raining]

README.md はすでにv6.0.0の内容を反映しているため、更新は不要です。

CLI Docをざっと見た限り、以下の部分のみ更新が必要そうでした。

Vivliostyle Themes について

v6よりテーマファイルは自動でインストールするようになるため、npm install のステップは不要になります。

[spring-raining]

どちらかというと、チュートリアルの更新が必要になりそうです。現在レビュー中の Base theme の導入により、例に挙げられているようなカスタマイズのやり方はだいぶ簡略化できるようになります。

[ogwata]

ありがとうございます。
チュートリアルの更新をVivliostyle ユーザドキュメントリストに加えました。

ところで前のコメントで、以下のように構成の見直しもあり得ると書いたのですが、これについてはどうでしょう？

上記構成を再考する選択肢もあり得る。たとえば真っ先に「組版結果のプレビュー」がある一方で、「構成ファイル vivliostyle.config.js」が3番目になるなどしており、もうすこし導入順（読者が必要に思う順）を意識した並びにした方がよいようにも思える。