[スレッド全体]

[353] ヘルプソースの管理・運用変更案 
2007/9/30 (日) 22:47:52 maru

今回はヘルプソースにHTML workshopのプロジェクト形式である*.hhp, *.hhc, *.hhkを含めました。(従来は中間ファイルの扱いでした)
いままで使っていたヘルプましんのUIは何かと便利ですが、機能上の制限が運用方針に適さないところがいくつかあり、メンテナンスが面倒です。

今後、ヘルプソースの取り扱いをHTML workshopの形式に変更したいと考えておりますので、ご意見などあればお願いします。期限は1.6.0.1リリースまでとします。

HTML workshopでの管理への変更にあたり
■メリット
・画像以外はすべてテキストなので変更を管理しやすい
・特にヘルプのメニューツリーの変更もhhcの差分を見れば分かる
・HTML workshopだけあればコンパイルできる
・CHMの持つ機能のすべてを活用できる
・ヘルプマシンがもつ相対パスなどの問題に対するローカルルールは基本的に不要

■デメリット
・hhcを編集保存するとマージファイル指定の記述が壊れる
・英語

*.hhcはHTML workshopから編集保存してはいけない、という前提ルールを守ることとして、*.hhcファイルはエディタで編集する方針で進めたいと思っています。
特にご指摘など無ければ次回より*.XHPと*.XHCを削除します。

[371] Re:ヘルプソースの管理・運用変更案 
2007/10/7 (日) 14:29:55 じゅうじ

▼ maruさん
> 今回はヘルプソースにHTML workshopのプロジェクト形式である*.hhp, *.hhc, *.hhkを含めました。(従来は中間ファイルの扱いでした)
> いままで使っていたヘルプましんのUIは何かと便利ですが、機能上の制限が運用方針に適さないところがいくつかあり、メンテナンスが面倒です。
>
> 今後、ヘルプソースの取り扱いをHTML workshopの形式に変更したいと考えておりますので、ご意見などあればお願いします。期限は1.6.0.1リリースまでとします。
>
> *.hhcはHTML workshopから編集保存してはいけない、という前提ルールを守ることとして、*.hhcファイルはエディタで編集する方針で進めたいと思っています。
> 特にご指摘など無ければ次回より*.XHPと*.XHCを削除します。


hhp,hhc,hhkを追加するのは賛成です、削除するのは反対です。
中間ファイルをメインにすると、前以上に面倒にならないか、の問題です。
・ヘルプマシンを使う場合で、SAKURA.HHPの[HERGE]指定での、絶対パスを削除する以外の手間には何が有りますか?
 それから、SAKURA.XHPのパス指定を削除する手間。
・HTML WorkShop のUIを使うと駄目なら、ヘルプましんで修正しても駄目なのではないですか?しかし、現行では修正出来ますが、それは、HTML WorkShop だけの問題では。

所で、インストーラ(sinst*.exe)のソースは公開されてませんね。

[374] Re2:ヘルプソースの管理・運用変更案 
2007/10/7 (日) 18:39:16 maru

▼ じゅうじさん
念のための確認ですが、中間ファイルと表現しているのは、ヘルプましんから見れば中間ファイルですが、本来の姿(HTML Workshop)ではプロジェクトファイル本体や目次ファイルなど(hhp,hhc,hhk)のことを指しているつもりです。
そして、hhp,hhc,hhkの追加の件は「HTML Workshopだけのユーザーでもコンパイルできるように」の意味よりは、「ヘルプましんは管理しにくいから離脱したい」の意味が強く、どちらかというとヘルプ作成者側の都合です。
作業感覚的には、これまでHTMLWorkshopのフロントエンドがヘルプましんだったものを、今度からテキストエディタ(普通はサクラエディタ)に変更しよう、という話です。
ここまでは、お互いの認識は合っていますよね?

さて本題ですが、以前の書き込みではWorkshop側のメリット・デメリットだけを列挙したので、主張が分かりにくかったかもしれません。

■ヘルプましんで管理するデメリット
1.コンパイルにはHTMLWorkshopとヘルプましんの2つのソフトが必要。
2.HTMLWorkshopに比べて、インストールされた環境が限定される。
3.コンテンツツリーがバイナリで保存されているので、変更点がわかりにくい。
4.コンテンツツリーがバイナリで保存されているので、パッチ配布できない。
5.コンテンツツリーがバイナリで保存されているので、別々の修正をマージできない。
6.コンパイル前には、hhp内のパス指定を修正しなければならない
7.6の理由により、リリースファイルのコンパイルは2段階の作業になってしまう。
8.ソース配布前には、XHP内のパス指定を修正しなければならない
9.7と8の理由により、7の作業でコンパイルの動作確認済みのソースはそのまま配布できず、コンパイル実施前の状態を別途保持しておかなければならない。
10.9の理由からリリース直前の細かい修正にはバージョン管理が煩雑になるが、6や8の作業が抜けても気が付きにくい。

■ヘルプましんで管理するメリット
1.UIが日本語
2.ヘルプましんからコンテンツツリー構造を変更・保存してもmerge指定が壊れない

といった状況です。
ヘルプましんの方がリリースにいたるまでのローカルルールが多くて、SVNでの管理にも不向き、というのが主な提案理由です。

> hhp,hhc,hhkを追加するのは賛成です、削除するのは反対です。
ヘルプましんとWorkshopの両サポートという意味でしょうか。これは間違いなく前以上に面倒だと思うのですが。
いずれの結論の場合も、最終的にはどちらか一方にさせてください(^^;;

[375] Re3:ヘルプソースの管理・運用変更案 
2007/10/7 (日) 20:09:46 じゅうじ

▼ maruさん
> > hhp,hhc,hhkを追加するのは賛成です、削除するのは反対です。
> ヘルプましんとWorkshopの両サポートという意味でしょうか。これは間違いなく前以上に面倒だと思うのですが。
> いずれの結論の場合も、最終的にはどちらか一方にさせてください(^^;;


いいえ、これは、コンパイル後の中間ファイルも公開しましょうと言うことで、そうすればヘルプましんの出力が変わっても分かるという意味です。
バイナリーファイルでもヘルプましんでUI出来る訳ですから、SVNで管理出来ないと言う訳は無いと思ったのですが。
HELP WorkShopのUIが使用できないと言うのが主な理由です。

[376] Re4:ヘルプソースの管理・運用変更案 
2007/10/7 (日) 21:51:21 maru

>いいえ、これは、コンパイル後の中間ファイルも公開しましょうと言うことで、そうすればヘルプましんの出力が変わっても分かるという意味です。
>バイナリーファイルでもヘルプましんでUI出来る訳ですから、SVNで管理出来ないと言う訳は無いと思ったのですが。

う〜ん、おっしゃることは理解できましたが、これだけでは私的には旨みがないですね・・・。

>HELP WorkShopのUIが使用できないと言うのが主な理由です。
えっと、まったく使えないわけではなく、一番最後の</UL>が変なところに挿入されてしまうのです。mergeの指定が<UL></UL>の内側に入ってしまいます。
もしコンテンツツリーの編集をWorkshopで行う場合は、最後の<UL>を修正する作業を追加すれば解決します。
そういうことであれば、Workshopでの編集+UL修正、という運用でも私は構いませんので、やはりヘルプましんからの離脱を推進したいのですが、いかがですか。

理由は前回書き込みのデメリット4〜9のためです。

[377] Re5:ヘルプソースの管理・運用変更案 
2007/10/8 (月) 12:26:22 じゅうじ

▼ maruさん
> ■ヘルプましんで管理するデメリット
> 3.コンテンツツリーがバイナリで保存されているので、変更点がわかりにくい。
> 4.コンテンツツリーがバイナリで保存されているので、パッチ配布できない。
> 5.コンテンツツリーがバイナリで保存されているので、別々の修正をマージできない。
> 6.コンパイル前には、hhp内のパス指定を修正しなければならない
> 8.ソース配布前には、XHP内のパス指定を修正しなければならない
>
> ■ヘルプましんで管理するメリット
> 1.UIが日本語
> 2.ヘルプましんからコンテンツツリー構造を変更・保存してもmerge指定が壊れない


A. HTML HELP Workshop で管理するメリット
1.Wikiサイトの管理との関連で、ヘルプましんのGUIは使いたくない、3と4が主な理由。
2.リリース時の手間の問題で、ヘルプましんのXHP,HHPは使いたくない、6と8が主な理由。

B. HTML HELP Workshopで管理するデメリット
1.GUIからCUIに移行する(GUIが英語で使い方が難しい)
2.GUIからコンテンツツリー構造を変更・保存するとmerge指定が壊れる

まとめるとこんな感じでしょうか、私はテキストのXHPも,バイナリーのXHCも更新出来れば更新を続けて欲しいと思います。

さて、HHPについてです。
リリースや、パッチにXHP,XHCは含めないという事でしたら、
毎回ヘルプましんのGUI出力ファイルを使う、B2の問題の為、HTML HELP Workshop のGUI出力ファイルは使わない。
(提供は出来ないが、XHP,XHCは何時でも手元に有るという状態)
A2以外、テキストファイルを直接編集しなくても良くなります。

[378] Re6:ヘルプソースの管理・運用変更案 
2007/10/8 (月) 19:43:10 maru

>リリースや、パッチにXHP,XHCは含めないという事でしたら、
ちょっと違います。「(サクラエディタのヘルプ作成において)ヘルプましんは作業性が悪いから使いたくない」です。

>(提供は出来ないが、XHP,XHCは何時でも手元に有るという状態)
これまた厳しいリクエストで・・・(^^;;
別件で Document/コンテンツツリー にパッチをアップされていらっしゃいますが、これをXHCに反映するのはかなり面倒なはずです。
手順としては
1.XHP,XHCからhhcを作成
2.hhcにパッチをあてる
3.新しいhhc「Workshopプロジェクトの取り込み」でXHCに吸い上げる
4.ヘルプましんが解釈できない部分(アンカーネームなど)を元ファイルを見ながら目視・手修正
のようなプロセスになるかと思います。
「XHP,XHCは何時でも手元に有る」というのは、そういう意味(パッチ提供を受けたらXHCを更新できることを保証する)ですよね?

>テキストファイルを直接編集しなくても良くなります。
あれ?直接テキストを編集したほうが手軽だと思うのですが。
ちょっとした修正のためだけに、いちいち関連ファイルを改変されると、それを元に戻すオーバーヘッドがものすごく無駄に思えてくるのです。
まあ、これは個人の好みに左右されますが。ヘルプましんではグラフィカルなインターフェィスしか利用できないのに対して、Workshopではグラフィカルなインターフェィスまたはテキストの直接編集どちらでもユーザーは好きなほうを選べるのです。これって素敵だと思いませんか?

[▼次のスレッド]
INCM/CMT
Cyclamen v3.81