HTMLヘルプの文字コードを変換する簡易ツールを導入する

[berryzplus]

PR の目的

ビルド直前に、UTF-8⇒Shift_JIS変換を行う仕組みを用意することにより、
HTMLヘルプのソースコードをUTF-8で登録できるようにします。

このPRは #975 を置換します。
このPRは #940 をrevertします。

カテゴリ

• ドキュメント修正 (元PRに付いてたので付けました。実態は関係ないです。)
• CI関連
  • Appveyor
  • Azure Pipelines (現在CHMビルド停止中なので、直接は関係ないです。)

PR の背景

このPRは #975 のスピンオフです。
背景事情は元ネタ #975 から順に辿っていけば把握できると思います。

「辿るのめんどくさいんじゃ～」な人のためにざっくり版背景を併記しておきます。

1. 当初、HTMLヘルプのソースコードはShift_JISで登録されていました。
2. GitHubのテキスト差分は、UTF8前提で表示されているようです。（憶測、Shift_JISだとたまに化けるから。）
3. HTMLヘルプのソースコードとほぼ同じものを GitHub.io で公開しています。
4. GitHub.ioとHTMLヘルプのソースコードの差分は文字コードで、ヘルプ更新時の同期に手間がかかることが問題になりました。
5. レビューしづらい、同期しづらいの対策として HTML ヘルプの文字コードを UTF-8 BOM 付きに変換することにより、Web サイトのデータとヘルプのデータを簡単に同期できるようにする #937, HTML の Help 中の JavaScript の文字コードを UTF-8 に修正 #939 が作られました。
6. CI環境でHTMLヘルプのビルドがコケる問題が発生しました。
7. ビルドエラー対策として HTML Help 用の HTML ファイル、Javascript の UTF-8 対応 (#937 と #939) を revert して CI ビルドが通るようにする #940(HTML ヘルプの文字コードを UTF-8 BOM 付きに変換することにより、Web サイトのデータとヘルプのデータを簡単に同期できるようにする #937,HTML の Help 中の JavaScript の文字コードを UTF-8 に修正 #939 のrevert) が作られました。
8. CI環境でHTMLヘルプの目次が化ける問題が発生しました。
9. 文字化け解消のために Appveyorのロケール設定を復活したい #954(appveyorのロケールを日本語にする), インストーラーの作成にビルド済みヘルプを使いたい #971 が作られました。

重要なとこだけ抜き出すと、問題と対策(=このPRの趣旨)は以下のとおりです。

• レビューとか同期とかのために文字コードをUTF-8に変えたい
• 単純に文字コードだけ変えると HHC.exe が認識してくれなくて文字化けしてしまう
  　　　↓
  　　HHC.exeがファイルを食う前に変換してANSI(Shift_JIS)にしちゃえばいいじゃん。

PR のメリット

• 文字コードをUTF8に戻す効果でGitHub上に差分が表示されるようになるので、レビューがしやすくなります。
• Web サイト のデータと簡単に同期がとれるようになります。

PR のデメリット (トレードオフとかあれば)

とくにないと思います。

PR の影響範囲

• CHM(=コンパイル済みHTMLヘルプ)の生成処理が増えます。（処理時間プラス5秒）
• ヘルプソースをリポジトリ登録するときの文字コードが変更になります。
• プロジェクトのヘルプソースを、GitHub.io向けに単純流用できるようになります。
• アプリ（＝サクラエディタ）の機能に影響はありません。

関連チケット

#975 [WIP] #940 を revert して HTML Help 用の HTML ファイル、Javascript の UTF-8 対応 (#937 と #939) を 再投入
#940 HTML Help 用の HTML ファイル、Javascript の UTF-8 対応 (#937 と #939) を revert して CI ビルドが通るようにする
#937 HTML ヘルプの文字コードを UTF-8 BOM 付きに変換することにより、Web サイトのデータとヘルプのデータを簡単に同期できるようにする
#939 HTML の Help 中の JavaScript の文字コードを UTF-8 に修正

sakura-editor/sakura-editor.github.io#47

[AppVeyorBot]

✅ Build sakura 1.0.2143 completed (commit 9784aad0c2 by @berryzplus)

[AppVeyorBot]

❌ Build sakura 1.0.2144 failed (commit 69da7d68bc by @berryzplus)

[beru]

GitHubの差分表示ですが Shift JIS のhtmlファイルで確認してみたらきちんと表示されていました。でもたまにきちんと表示されない時があるんですかね？

GitHub.io 側の html ファイルを Shift JIS に変えてしまうわけにはいかないんでしょうか？

CIのJobが動くたびに大量のファイルの文字エンコーディング変換処理を走らせるのに少し抵抗が有ります。まぁそんな事言ったらこれ以上二酸化炭素吐き出さないで下さいとか言われそうですが…。

[beru]

GitHubの差分表示ですが Shift JIS のhtmlファイルで確認してみたらきちんと表示されていました。でもたまにきちんと表示されない時があるんですかね？

自己レスですがこのPRの差分表示でもたまにSJISのファイルの日本語表示が化けてますね。なので常にはきちんと表示できない欠陥品という事が理解出来ました。。

文字エンコーディングの変換処理は自前で書いたのをビルドして使うより iconv とか nkf を動かせないでしょうか？もしくは powershell 使うとか。

https://www.atmarkit.co.jp/ait/articles/0804/18/news155.html

[berryzplus]

何気に、CodeFactor対応しておりました・・・

CIのJobが動くたびに大量のファイルの文字エンコーディング変換処理を走らせるのに少し抵抗が有ります。まぁそんな事言ったらこれ以上二酸化炭素吐き出さないで下さいとか言われそうですが…。

773ファイルの変換で、所要時間は5秒です。（ビルド込み）
ちょっと「ぬ？」ってなるタイムですが、おそらくこれ以上速くはならないっす 😄

文字エンコーディングの変換処理は自前で書いたのをビルドして使うより iconv とか nkf を動かせないでしょうか？もしくは powershell 使うとか。

数日前に ここ に書いたんですけど 、Git自体に「それ系（≒コミットはUTF-8、ワークツリーはそれ以外）」を実現する機能があるらしいです。⇒ マニュアル

マニュアルの例示は *.rc で、ワークツリーを UTF16LE-BOMにする方法が解説されています。 *.rc の文字コードについてはここでも問題になったことがあって、一旦UTF-8N(BOMなし)で登録することになっていたはず。visual studio が UTF-8(BOM付き) に対応してない、GitHubがUTF-16LEBOMの差分表示に対応していない、と色々問題があって苦肉の策をとった感じでした。

マニュアルに解決策が例示されてて「本家に追随！」となりそうな *.rc の話は置いておいて、htmlソースに戻ります。ワークツリーエンコードを適用するにあたっての問題点が2つあります。

1. 変換先がUnicodeじゃない(=Shift_JIS) なので、安定動作に不安があります。
2. 対象がHTMLファイルなので、文字コードがベタ書きされています。working_tree_encoding を使うにしても、metaタグの書き替えをどうするかは別途考えないといけないです。

[beru]

github上でHTMLファイルの差分表示が化けない事にこだわる必要があるのか疑問です。
ローカル側で差分確認する方法でカバーできるのではないでしょうか？

文字エンコーディング変換のお仕事はさせないに越した事は無い気がします。

しかしあんまり細かいコストは気にしてもしょうがないのかもしれないですね。
HTMLヘルプファイルを作成するコストはどうしても掛かってしまうんだし…。

いやしかしソースコードと違って変更がされないのにCIのJobが走る度にHTMLヘルプを作成するというのが気になります。HTMLヘルプに関してはリポジトリ分けてしまうのはどうなんだろうか？と思います。

[AppVeyorBot]

✅ Build sakura 1.0.2145 completed (commit 6c32409296 by @berryzplus)

[berryzplus]

ああ、そうそう、こういう事情もあります。

文字エンコーディングの変換処理は自前で書いたのをビルドして使うより iconv とか nkf を動かせないでしょうか？もしくは powershell 使うとか。

変換方向が Unicode ⇒ Shift_JIS なので、マップできない問題が発生しうるんです。

https://ja.wikipedia.org/wiki/Shift_JIS 定義コードポイント 9千くらい
https://ja.wikipedia.org/wiki/Unicode 定義コードポイント 10万以上(バージョンによって異なる)

HTML上では &#number; と書けばUNICODEコードポイントを参照できます。

文書管理をUTF-8のまま、かつ、文字化けを発生させないやり方としては、これを応用するっきゃないんかな、と思ってこういうツールができたわけです・・・。

[beru]

まぁこの問題の根本的なところはオワコンの HTML Help Compiler を使い続けているところにあるんですよね。。utf-8 対応の為にMSがオープンソース化してくれないかとも思ったりしますが、MS的にもセキュリティホールだらけな黒歴史は闇に葬りたいのでしょう。。

[beru]

変換方向が Unicode ⇒ Shift_JIS なので、マップできない問題が発生しうるんです。

https://ja.wikipedia.org/wiki/Shift_JIS 定義コードポイント 9千くらい
https://ja.wikipedia.org/wiki/Unicode 定義コードポイント 10万以上(バージョンによって異なる)

HTML上では &#number; と書けばUNICODEコードポイントを参照できます。

文書管理をUTF-8のまま、かつ、文字化けを発生させないやり方としては、これを応用するっきゃないんかな、と思ってこういうツールができたわけです・・・。

なるほどー、使える文字種の制限を取り払うとなると確かに Shift JIS から Unicode に移るのが自然ですね。あとそれならヘルプ表示も chm を使うのではなくてブラウザでヘルプのファイルを開く形にするのが良い気がします。検索とか索引も JavaScript のライブラリ使ったりで出来るんじゃないかなと安易に思っています。

[berryzplus]

A C# document may only contain a single class at the root level unless all of the classes are partial and are of the same

この指摘に対応すべきかどうか悩み中。

[beru]

AppVeyor 側で生成された chm を落として見たところきちんと表示されていました。

なので問題無いと思います。

[berryzplus]

レビューありがとうございます。
なんかあったら、対応するということでマージしてしまいます。