vivliostyle / themes Goto Github PK

#48 から引き続きの議論です。

問題

theme-bunkoという名前の公式themeは、実際には文庫サイズではないので混乱を招いている。

やりたいこと

• 公式themeの名前は正しく具体的でわかりやすいものにすべき
• すでに公式themeは4つ公開されているが、この名前もわかりやすいものに変える。ただし突然名前が変わると混乱するので、現在のバージョンのthemeはそのまま残し、次のバージョン（またはv1.x.x）から新しい名前で更新する

see vivliostyle/vfm#101.

@page :first {} は出版物全体を通して最初のページを指します。一方で @page :nth(1) {} は、vivliostyle.config.js の entry で指定した原稿ファイルそれぞれの最初のページを指します（これは Vivliostyle 独自の挙動です）。
https://vivliostyle.github.io/themes/#/ja/tutorial/step3.md#%E7%AB%A0%E7%95%AA%E5%8F%B7

後者はVivliostyle独自の挙動ではない（どちらかといえば前者）。CSS仕様では複数ドキュメントを考慮されていないので @page :first {} の挙動は独自といえるが……。

Vivliostyle のサンプル「Gutenberg」に向いた欧文用のテーマをリリースする
https://github.com/vivliostyle/vivliostyle_doc/tree/gh-pages/samples/gutenberg/

current: https://github.com/vivliostyle/themes/blob/master/DESIGN.md#category-optional

Any thoughts?

@uetchy
npm パッケージ vivliostyle-theme-scripts と create-vivliostyle-theme をリリースしようとしたら、パーミッションが必要と言われました。これらを vivliostyle の npm organization で管理するか、あるいは collaborator に加えていただけますか？ （どちらがいいんでしょう……🤔 ）

https://www.npmjs.com/package/vivliostyle-theme-scripts
https://www.npmjs.com/package/create-vivliostyle-theme

横書き、ノンブルあり　みたいなシンプルなものでよい

{
  "engines": {
      "node": ">= 12"
  }
}

ref: vivliostyle/vfm#97

• パッケージ内の /example に置かれた文書をビルドしてみる方法
• スタイルを書き換える方法

など。Wikiなどにまとめる

このリポジトリではpackage.jsonの次の設定によってcommit時にprettierによる整形が実行されるようになっている：

各テーマパッケージのexampleの原稿MDファイルに対してこれが適用されて次のように意図しない書き換えがされてしまうことがある：

• 和文文字と欧文文字との間にスペース（U+0020）が挿入される（prettier v2の問題）
  • 和欧文間スペースの処理はCSS組版エンジンで行われるものなので、原稿テキストにこのようなスペース文字を入れるべきではない
  • この問題については、prettier v3では修正されている：
    • prettier/prettier#6385
• 意図的に入れている段落の行頭の全角スペース(U+3000)が削除される
  • 電書協EPUB3制作ガイドでは段落の字下げに全角スペースを入れる（行頭が括弧以外の場合）ことが勧められている。この形式の原稿が扱えないのは問題。
• VFMでの見出しの属性記法で、見出しの行のあと改行してから属性記法 { … } を書いている場合（見出しの内容がインラインの要素で終わるときそうする必要がある）、改行がさらに追加されて空白行があいだにできる。そうすると見出しの属性記法ではなくなってしまい、{ … } がテキストとして出力されてしまう事故になる。

このうち問題のうち最初の「和文文字と欧文文字との間にスペース（U+0020）が挿入される」については、prettierのバージョンを現在使われている v2 から最新の v3 に更新すると解決するはず。しかし、commit時のprettier実行のために使われているpretty-quickがprettier v3に対応していないという問題があり、prettierを最新にするためにはpretty-quickをほかのものに置き換える必要がある。そのpretty-quickのissue:

• prettier/pretty-quick#164

実際に問題が起きた例：

• #118 の電書協のEPUBサンプルをベースにMD化したサンプルをコミットしたとき、この意図しない書き換えが生じた。そのあとそれを直したコミット 8c69966 での差分を参照。

当面の対策としては、.prettierignore ファイルでMDファイルが整形対象にならないようにする。例：

theme-academic にデフォルトで2段組みを適用したテーマをリリースする
https://github.com/vivliostyle/themes/tree/master/packages/%40vivliostyle/theme-academic

背景

現状、theme の package には用途別に複数のスタイルシートを含めている。

• theme_print.css
  • PDF の出力に使うスタイルシート
  • トンボなどを含めている
• theme_screen.css
  • ブラウザで出版物を確認する際に使うスタイルシート
  • ブラウザの横幅いっぱいにテキストが表示されることを防ぐため、max-width を設定したりしている
• theme_common.css
  • 共通のスタイルシート
  • theme_print.css と theme_screen.css では @import 'theme_common.css' している

議論すべき内容

• theme_print.css と theme_screen.css を分ける必要はあるのか？
  • theme_common.css 内で @media print {} を使えば、theme_print.css ファイルを別途作らなくて済む

参考

• theme_print.css と theme_screen.css の他に、将来的には EPUB 用のスタイルシートも作成する想定だった
  • しかし、まだそのようなスタイルシートは作られていない
  • #25

Vivliostyle Themeをカスタマイズしやすくするための議論で、Sassの変数をパラメータにすることが検討されてきました（関連issue #19 や #9）。

最近のWebの標準では、CSSカスタムプロパティ（CSS変数）が利用できるようになっているのですが、Vivliostyle Coreでそれが未サポート（Issue: vivliostyle/vivliostyle.js#540 ）であるために、Vivliostyle ThemeでのCSSカスタムプロパティの利用は検討されてませんでした。

Vivliostyle CoreではCSSカスタムプロパティを近いうちに（できれば10月にでも）サポートしようと検討中です。
それが使えるようになった場合、Vivliostyle Themeのカスタマイズのしくみに利用するのがよいと思います。

コンパイルが必要なSass変数とは違って、CSSカスタムプロパティはCSSの解釈時にCSSのカスケーディングのしくみにしたがって有効になるので、Vivliostyleでの組版実行時にパラメータをVivliostyle Coreに渡すことがより簡単です。

参考記事: MDN - CSS カスタムプロパティ (変数) の使用
https://developer.mozilla.org/ja/docs/Web/CSS/Using_CSS_custom_properties

Vivliostyle公式テーマなど公開されているテーマを使って本を作る場合、ユーザーはそのスタイルをカスタマイズできる必要があります。

（公開テーマをどのようにしてカスタマイズして使うかは、vivliostyle-cli などテーマを使う側の実装の問題かもしれませんが、vivliostyle/themes の共通のメカニズムとして検討が必要ではないかと思うので、vivliostyle/themes のissueにしました。）

一般に、既存のスタイルシートをベースにしたスタイルのカスタマイズ方法として次のものがあります：

• 既存のスタイルシート（CSSファイル）をコピーして、それを修正する。
• 既存のスタイルシートがSassなどプリプロセッサで生成されている場合は、そのソースファイル（scssファイルなど）を修正して、それらを使ってCSSファイルを生成しなおす。（その場合、ソースファイルでは、よくカスタマイズするプロパティの値などが変数で設定されて "variables.scss" ファイルなど１箇所にまとめられていたりする。）
• 既存のスタイルシート（CSSファイル）をそのまま使うが、それに加えて追加のスタイルシートを指定する（HTML内で <link rel="stylesheet"> を既存のスタイルシートと追加するスタイルシート用にそれぞれ指定）。追加のスタイルシートでは、CSSカスケーディング規則によって、既存のスタイルシートでのスタイルを新しいスタイルで上書きする。
• 既存のスタイルシート（CSSファイル）を新しいスタイルシートの先頭で @import ルールによって取り込む（HTML内の <link rel="stylesheet"> には新しいスタイルシートのみ指定する）。CSSカスケーディング規則によって、既存のスタイルシートでのスタイルを新しいスタイルで上書きする。

以上のどの方法も、現状の vivliostyle/themes と vivliostyle-cli (v3.0.0-pre.2)ではうまくできないようです。

改善案：

• ビルドのたびにテーマのCSSをnpmパッケージから取得するのではなく、テーマが最初にローカルにコピーされたら、ユーザーがそのCSSを修正してカスタマイズしたうえで本のビルドやプレビューをできるようにする。
• テーマのパッケージにSass (scss)などスタイルシートのソースファイルが含まれている場合（その方法の定義も必要）、ソースファイルがコピーされて、ユーザーはそのscssファイル類を修正してカスタマイズしたうえで本のビルドやプレビューをできるようにする。
• 現状の vivliostyle.config.js で、ルートの theme のほかに、entry配列の項目ごとにも theme を指定できるが、本全体で共通の theme を使いながら、entry項目によって追加のスタイルシートを指定できるようにはなっていない。これをできるようにする。

ref #69

テーマ独自の記法を使えるようにするため、themesにreplace用のスクリプトをもたせる

例：

• 句点をピリオドに置換する
• 対話形式のテキストを書きやすくする

• 現状は yarn dev で vivliostyle-theme-scripts preview ... が走る
  • https://github.com/vivliostyle/themes/blob/19c0e7f6cd88f2f8cda526829d85aa91bab258d9/packages/vivliostyle-theme-scripts/src/commands/preview.ts にあるように Vivliostyle Viewer を呼んでいる
• CLI の仕組みを使うのが良いと思う
  • --theme は使えないようなので vivliostyle.config.js を作ることになりそう

refs #69

Theme を開発した後の実運用に関わるガイドラインを作成する。#69 はエンド ユーザー向けでこちらは Vivliostyle 運営も含みます。

ざっと思いついたものを列挙してみます。

• 名付け方
  • 基本的に自由
  • A4 や縦書きなど CSS や Viviliostyle Viewer、Pub から動的変更しそうなものは含めない
  • 目的の明確なものと抽象的なもので分かれるだろう
  • 実社会や専門分野で規格の定められているものなら、それを踏襲するのがよい
  • などなど
• 対象単位
  • 基本は文書、帳票、帳簿
  • 版型や段組みの単位で小さなテーマを作成して組み合わせる案もあったが、これらはサンプルとして CSS のスニペットを公開すれば十分ではないか？
• 公式テーマ採用
  • 申請と審査
  • どこに申請して誰が審査するか？
• 参考資料
  • 既存のテーマをサポートしているソフトウェアのガイドラインを見つけたら随時、追加予定
  • テーマレビュー - WordPress Codex 日本語版

#43 で「文庫 (bunko)」という名前がふさわしくなかったかもという意見あり

次のテーマからは一般的すぎない名前にしたい

• vivliostyle.config.js を使って example/ 以下の原稿を出版物に変換できるようにする
• scss/ ディレクトリにスタイルを含める（Pure CSS のみで書かれている場合もそうする）

.
├── LICENSE
├── README.md
├── example
│   ├── *.html
│   └── *.md
├── package.json
├── scss
│   └── *.scss
├── *.css
├── *.css.map
└── vivliostyle.config.js

Vivliostyle プロジェクトとして作成された本から therme に必要なものだけ抽出するツールとか機能あるといいかも。開発側としてはあれとこれ、とわかるがエンド ユーザー向けにオープンな本から theme 流用するのに役立ちそうなので。#vivliostyle

— アカベコ (@akabekobeko) April 10, 2021

目的

• テーマの設計を揃えるため
• ユーザがスタイルを変更しやすくするため ref: vivliostyle/vivliostyle-cli#76
• テーマが変わってもユーザがスタイルの指定で迷わないようにするため

パラメータ例

• 文字サイズ
• 行間
• etc...

• CSSの書き方など

CLI で複数テーマ指定がサポートされ、テーマパッケージの自動インストールができるようになったので、チュートリアルのテーマカスタマイズの節を更新する必要がある。
https://vivliostyle.org/ja/tutorials/customize/

ref:

• vivliostyle/vivliostyle-cli#352
• vivliostyle/vivliostyle-cli#353

https://github.com/yamasy1549/nitac_tex_template

author: @yamasy1549

Theme name candidates

• vivliostyle/theme-academic
• vivliostyle/theme-thesis
• vivliostyle/theme-journal
• vivliostyle/theme-{more fancy name}

Merging process

1. Create a PR
2. Maintainers will review the PR
3. Merge into the repo & publish on npm

ブラウザによって未実装の機能もあるので、そういった環境でも正しく意図が伝わるように、フォールバックのスタイルを追加する

たとえば圏点ならこんな感じ

strong {
  // 一般的な強調のスタイル
}

@supports (text-emphasis: sesame) {
  strong {
    // この中に圏点のスタイル
  }
} 

CLI v3.5.0 に上げる

特に、数式モード vivliostyle/vfm#89 関係で記法が変わっているはず

vivliostyle/vivliostyle-cli#143 (comment) に関連して：

• print 用
  • 今の theme はこれがメイン
• screen 用
• EPUB用
  • 急ぎではないが、将来的に必要になる
  • （どういうふうにスタイルを指定すればいいか @yamasy1549 はよくわかっていない）
• ↑の共通部分
  • 共通部分を print 用や screen 用で @import すればよさそう

package.jsonで

    "@vivliostyle/cli": "^3.5.2",

となっているので新しい v4.x のCLIが使われません。

生成されたプロジェクトを VS Code で読み込むと膨大な node_modules が警告されるのと、それらをそのまま Git へ commit/push してしまう可能性があります。これを防ぐため Node.js 向け .gitignore を含むとよさそうです。

• gitignore/Node.gitignore at master · github/gitignore

スタイルパラメータの検討

• #19 テーマに共通して、ユーザ指定可能なパラメータを洗い出す @yamasy1549

スタイルシートのカスタマイズ方法の検討

• #9 How to customize the style of themes?
  • 案は出ているので、他の案を募る or これに決める

スタイルテーマに含まれる原稿テンプレートの利用

• 本の構成要素ごとに別の原稿テンプレートを設定できること
  • 原稿テンプレートごとに別のスタイルシートを設定できること

スタイルテーマの仕様の要件を満たすようにcreate-vivliostyle-themeを修正する

ref: Vivliostyle Pub v1 要件仕様 (WIP) より スタイルテーマ (Vivliostyle Themes)

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

EPUB用のthemeをつくる

• 電書協EPUB3ガイド準拠
• EPUBとPDFの両方の出力に対応する基本スタイルになるよう