Skip to content

Vivliostyle CLI v3.0 new spec

Jump to bottom
Shinyu Murakami edited this page Feb 7, 2021 · 4 revisions

Vivliostyle CLI v3.0 new spec (obsolete draft)

This draft is obsolete

このドラフト案は、v3.0.0-pre.4 当時に書かれたものです。その後、https://github.com/vivliostyle/vivliostyle-cli/issues/86 の議論で仕様が改良されてv3.0が完成してます。最新版のREADME をご覧ください。

Purpose

Revise the Vivliostyle CLI v3.0 spec to solve the issues found in the previous V3.0.0-pre-releases.
（これまでのv3.0プレリリース版で見つかった問題を解決するため、CLI v3.0の仕様を改訂）

Revised CLI v3.0 spec

vivliostyle --help will show:

Usage: vivliostyle [options] [command]

Options:
  -v, --version   output the version number
  -h, --help      display help for command

Commands:
  build           build and create PDF file
  preview         launch preview server
  init            create vivliostyle config
  help [command]  display help for command

build options

vivliostyle build --help will show:

Usage: vivliostyle build [options] <input>

build and create PDF file

Options:
  -b, --book                    input is a webbook (index.html or publication.json manifest),
                                unzipped EPUB (root dir, or package.opf file).
  -c, --config <config_file>    path to vivliostyle.config.js [vivliostyle.config.js]
  -o, --output <output_file>    specify output file path [<title>.pdf]
  -T, --theme <theme>           theme path or package name
  -s, --size <size>             output page size, default to the page size specified in CSS,
                                or Letter if not specified.
                                preset: A5, A4, A3, B5, B4, JIS-B5, JIS-B4, letter, legal, ledger
                                custom (comma separated): 182mm,257mm or 8.5in,11in
  -p, --press-ready             make generated PDF compatible with press ready PDF/X-1a [false]
  --gray-scale                  with press-ready option, use Grayscale instead of CMYK color
  -f, --format <output_format>  specify output format (pdf, webbook) [pdf]
                                
  --generate-webbook            generate a webbook (with publication.json manifest)
                                default to true if input is Markdown (.md)
  -n, --no-generate-webbook     no generate webbook (use existing publication.json and html files)
  -N, --no-output               no output (only generate webbook)
  --title <title>               title
  --author <author>             author
  -l, --language <language>     language (en, ja, etc.), default to undefined
  --verbose                     verbose log output
  --dist-dir <directory>        dist dir for webbook where publication.json and other files are generated.
                                default to undefined (use current dir as webbook root dir).
  -t, --timeout <seconds>       timeout limit (seconds) for waiting Vivliostyle process [60]
  --no-sandbox                  launch chrome without sandbox. use this option when ECONNREFUSED error occurred.
  --executable-chromium <path>  specify a path of executable Chrome (or Chromium) you installed
  -h, --help                    display help for command

Changes from v3.0.0-pre.4

preview options

vivliostyle preview --help will show:

Usage: vivliostyle preview [options] <input>

launch preview server

Options:
  -b, --book                    input is a webbook (index.html or publication.json manifest),
                                unzipped EPUB (root dir, or package.opf file).
  -c, --config <config_file>    path to vivliostyle.config.js [vivliostyle.config.js]
  -T, --theme <theme>           theme path or package name
  -s, --size <size>             output page size, default to the page size specified in CSS,
                                or Letter if not specified.
                                preset: A5, A4, A3, B5, B4, JIS-B5, JIS-B4, letter, legal, ledger
                                custom (comma separated): 182mm,257mm or 8.5in,11in
  --title <title>               title
  --author <author>             author
  -l, --language <language>     language (en, ja, etc.), default to undefined
  --verbose                     verbose log output
  --no-sandbox                  launch chrome without sandbox (use this option to avoid ECONNREFUSED error)
  --executable-chromium <path>  specify a path of executable Chrome(Chromium) you installed
  -h, --help                    display help for command

Changes from v3.0.0-pre.4

  • -t → -T (see same as build option)
  • add -l (short option for language)

init options

vivliostyle init --help will show:

Usage: vivliostyle init [options]

create vivliostyle config file

Options:
  --title <title>               title
  --author <author>             author
  -l, --language <language>     language (en, ja, etc.), default to undefined
  -T, --theme <theme>           theme path or package name
  -h, --help                    display help for command

Changes from v3.0.0-pre.4

  • -t → -T (for compat with v2, -t is for timeout)
  • remove -s, --size
    • We should leave it undefined in the config because the page size specified in CSS should be honored

Changes in vivliostyle.config.js file

Current spec: https://github.com/vivliostyle/vivliostyle-cli/blob/41aee32e19e16ad33779d02bae6bdc7eb7c808c7/src/commands/init.ts#L46-L68

Change to:

  const vivliostyleConfig = `module.exports = {
  title: '${ cliFlags.title || 'Principia'}', // populated into 'manifest.json', default to 'title' of the first entry or 'name' in 'package.json'.
  author: '${cliFlags.author || 'Isaac Newton'}', // default to 'author' in 'package.json' or undefined
  language: '${cliFlags.language || 'la'}', // default to undefined
  // size: 'A4', // default to the page size specified in CSS, or Letter if not specified
  theme: '${cliFlags.theme || ''}', // .css or local dir or npm package. default to undefined
  entry: [ // **required field**
    // 'introduction.md', // 'title' is automatically guessed from the file (frontmatter > first heading)
    // {
    //   path: 'epigraph.md',
    //   title: 'おわりに', // title can be overwritten (entry > file),
    //   theme: '@vivliostyle/theme-whatever' // theme can be set indivisually. default to root 'theme'
    // },
    // 'glossary.html' // html is also acceptable
  ], // 'entry' can be 'string' or 'object' if there's only single markdown file
  // entryContext: './manuscripts', // default to '.' (relative to 'vivliostyle.config.js')
  // outFile: './output.pdf', // path to generated pdf file. cannot be used with outDir.
  // outDir: './output', // path to the directory where the generated pdf is located. filename is picked from 'title'. cannot be used with outFile.
  // toc: true, // whether generate TOC in index.html for webbook
  // format: 'pdf', // reserved for future usage. default to 'pdf'.
  // distDir: './webbook', // default to undefined (use current dir as webbook root dir)
};
`;

Changes from v3.0.0-pre.4

  • change language that was "default to 'en'" to "default to undefined"
  • change size to not specified, and add description
  • change distDir
  • change toc that was "whether generate and include toc.html or not (does not affect manifest.json), default to 'false'. if 'string' given, use it as a custom toc.html."

そのほか v3.0 に入れたい機能

CLI v3.1 以降で追加する機能

Clone this wiki locally