以前、仕様文書を抽出し、HTMLの形式で出力する アイディアを紹介しました。 内容は同じだとしても、一応それなりに整形して表示するせいか、 単にプレーンテキストで作るより受けはいいみたいです。
同じような考え方で、ヘルプもHTMLで作る例が最近増えてきていますね。 作る立場で見ても、表示用のプログラムを改めて開発、配布する必要がないので らくちんです。 最近このようなヘルプに関わったので、C++とは直接関係ありませんけど、 ちょっと与太話をしてみたいと思います。
ヘルプにはよく、「何々をするには?」みたいな標題で、ある操作の手順が示されます。 普通これには番号つきリスト「<ol>」を使って、 こんな具合に書きます。
<ol>
<li>ほげほげをします。</li>
<li>むにゃむにゃします。</li>
<li>ごてごてします。</li>
</ol>
すると番号がついて、次のように表示されます。番号を直接書くのに比べ、 項目を変更したときに勝手に番号が振り直されるので便利、というわけです。
ところが、上から順に実行するだけという手順ばかりではなくて、ある部分を 繰り返したり分岐したり、ということが起こるんですね。 すると例えば次のようになります。
<ol>
<li>ほげほげをします。</li>
<li>むにゃむにゃします。</li>
<li>ごてごてします。</li>
<li>ふみふみになるまで1〜3を繰り返します。</li>
</ol>
もう問題点に気づかれたことと思います。番号を文に直接書いて項目を引用すると、 項目を追加/削除したときに、その項目が何番になるかを自分で 数えて番号を書き替えなければならないんですね。 それなら<ol>なんか使わないで、直接項番をHTMLファイルに 書いておいたほうが、数える手間が省けていいということになってしまいます。
これを避けるために、次のように書くという手もあります。
<ol>
<li>ふみふみになるまで以下を繰り返します。</li>
<ol>
<li>ほげほげをします。</li>
<li>むにゃむにゃします。</li>
<li>ごてごてします。</li>
</ol>
</ol>
while ( ) ... と do ... while ( ) の違い、 というか、繰り返しの中身を必ず1回は実行するのか、みたいな違いについては 目をつぶってください。要は、繰り返しの範囲を番号で示すのではなく リストの入れ子関係で示している訳です。
ところがこれも、プログラムの処理概要を書くのならともかく、一般の利用者向け 文書としてははなはだ評判がよろしくない。それどころか、
<ol>
<li>ほげほげをします。どきどきならば3番に飛びます。</li>
<li>むにゃむにゃします。</li>
<li>ごてごてします。</li>
</ol>
みたいなgoto型の方がわかりやすいということもあります。 まあ、基本的に前に戻るgotoは避けた方がいいみたいですが。
ううむ、これって今のHTMLの枠内ではどうしようもないんでしょうかねえ。
それにしても今回関わったヘルプは不思議な構造になっていまして...
ところどころで JavaScript を呼び出して何かやっている...何か、というのは どうも別のアプリケーションのヘルプを呼び出しているみたいなんですけど、 その中身はというと、これまた別のヘルプを呼び出す VBScript になっているという、 よくわからない構造です。
でもって、ほとんど同じスクリプトがどのHTMLファイルにも繰り返されているという、 保守する立場の人にとっては地獄のようなありさまです。 ひとつひとつのテーマごとにこまごまとファイルを分けてあるので、さらに大変。
こういうのって、作者がエディターのコピー機能を極限まで駆使した結果、という 可能性もありますが、もう少し工夫して、HTMLファイルを生成するスクリプトを 用意しているかも知れません。 単純な例としては、あるキーワードがあればそれをひとかたまりのJavaScriptに 置換する、というものがあります。 メリットは、あとになってJavaScriptを修正する必要が生じたときに、 生成スクリプトの方で1回修正すれば一挙に全部修正される、という点。 そして、実行時(ヘルプの参照時)に置換する方法と比べて、(多分)すばやくヘルプが 表示されることでしょう。
でもそれならば、関係者にまわして作業してもらうときに、 生成する元の方を渡して欲しいですよね。 生成結果の方で作業(例えば文字遣いの誤りのチェックなど)して変更してしまうと、 このメリットが失われてしまいます。
なのですが、生成元の方をよこせといくら説明してもわかってくれない人が、 プログラミング経験がないくせに設計者と称する人に 多いような気がするのは、偏見、なのでしょうか?