青木です。なんか予想外に遅れてしまいました。

On 2007/08/27, at 9:01, sheepman wrote:

> こんにちは、sheepman です。

>> まず、ここで言及されている「例」はよく見ると二つのパターンが 
>> あると
>> 思います。一つめは文章を補足する形で入れられている「コード 
>> 例」、
>> 二つめは単独で意味をなす「コード例」です。
>
> 二つの違いが良く分かりません。例というのは常に文章を補足するた 
> めのものなんじゃ、
> と思いました。とりあえず、前者は「レアケースの例」、後者は「一 
> 般的な使用例」
> だと理解しました。

それじゃ次のように言い換えるとどうですか。

   1. 文章の中に埋め込まれているコード例
   2. 文章の中に埋め込まれていないコード例

1. は文章とつながりがあり、コードがないとどうしても理解しづらい
ときに (だけ) 補足的に使います。2. は文章とは 
独立しており、メソッドの
代表的な用例だとか境界条件下での挙動とかを一通り尽くしたものです。

> 論点は二つ。
>
> 1. 「一般的な使用例」を後ろに書いちゃうとその挙動を説明する文 
> 章と離れるわけ
> ですが、それはどうしましょう。

それで構いません。わざわざ場所を離して独立させるのは、文章を
全部順を追って読まなくても済むようにするためです。これは例えば、
メソッドの意味をだいたい知っている人が、コード例だけ見て使い
かたを思い出すような目的を想定しています。

全部の例を文章の中に埋め込んでしまうと、流れが明確になる反面、
「頭から全部読まないと読めない」という弊害が生じます。それは
リファレンスマニュアルとして望ましくありません。

> 2. あるコード例が二つのうちのどちらなのか明確である場合は少数 
> だと思います。日本語だけでは
> 理解が難しい時に文中に一般的な使用例を書いて補足するケースが多 
> いはずで、それは青木さんの言う
> 前者なのか後者なのか良く分かんないです。このまま基準を不明確に 
> しておくと、文章中の例を単に
> 文末にカットアンドペーストするだけになってしまいそうです。

文章中に書いているコード例はすべて前者です。

ちなみに、わたしはコード例が文章を補足するものだとは思っていませ 
ん。
文章は仕様 (願望) を述べますが、コード例は基本的に事 
実しか述べません。
この二つはそもそも別のものです。

>> さらに言えば、使用例は必須です。
>
> はじめて聞きました。

あれ、そうでしたっけ。じゃあ、まあ、これから方針を変えても大変
なので必須にはしないことにしましょう。でも、できるかぎりコード
例はあったほうがよいです。

-- 
青木峰郎

--
ML: ruby-reference-manual@m...
使い方: http://QuickML.com/