青木日記

■ RDocのattrの扱い

[ruby-talk:119406] Re: [RDOC] Documenting accessor methods as methods

def a=(v) で作ったメソッドは attribute のとこに出るべきだ、 いやその逆に、attr_reader で作ったメソッドもメソッドとして出るべきだ、 という意見。

俺もこれはずっと気になってたんだよ。 「属性」なんて区分はなくすべきだろ。 属性かメソッド (関数) か、なんてのは実装の領分であって、 ドキュメントに書くべきことではない。 少なくとも Ruby ではその区別がないのだから区別するべきではない。 『オブジェクト指向入門』p.131「統一的参照の原則」も参照のこと。

流れによっては参戦しよう……そんな時間あるのか？

(06:25)

■ 原稿書きの手法

ふーむ、るびまって編集中から Hiki 上でやってるんだなあ。 Wiki 上で (ウェブ上で) 長い文章を書くのは大変じゃないだろうか。 俺はツールをいろいろ使わないともう文章は書けなくなくなってしまった。 最低でも分量表示付き目次とソースコード展開と用語チェッカ、 あとできれば内容の依存関係をチェックするツールも使いたいな。

分量表示付き目次ってのはこういうのね

~/c/linuxintro % list                                      aamine@harmony
 1.   22  intro.rd ........ Linuxプログラミングを始めよう
 2.   42  abstract.rd ..... Linuxのすがた
 3.   22  stream_sys.rd ... ストリーム（1）システムコール編
 4.   24  stream_stdio.rd . ストリーム（2）stdio編
 5.   19  practice1.rd .... 実習（1）headを作る
 6.   30  practice2.rd .... 実習（2）grepを作る
 7.   15  hier.rd ......... Linuxのディレクトリ構造
 8.   21  fs.rd ........... ファイルシステム
 9.   23  process.rd ...... プロセス
10.   10  signal.rd ....... シグナル
11.   16  etc.rd .......... プロセスの環境
12.   18  network.rd ...... ネットワークプログラミングの基礎
13.   32  httpd.rd ........ 実習（3）HTTPサーバを作る・基本編
14.   27  httpd2.rd ....... 実習（4）HTTPサーバを作る・発展編
15.   30  advanced.rd ..... 本書を終えた後は
　
Total 342 Kbytes
　
~/c/linuxintro % ind intro.rd                              aamine@harmony
1 Linuxプログラミングを始めよう intro.rd      509
   1 本書の対象読者                                19
   2 本書で話すこと                                10
   3 対象とする環境                                10
   4 必要な環境                                    16
   5 開発環境の導入                                31
      1 Fedora Coreの場合                               6
      2 Debian GNU/Linuxの場合                         21
   6 gccを使ったビルド（1）                        87
      1 うまくコンパイルできないとき                   22
   7 開発環境の話                                  43
      1 C言語以外の言語                                10
      2 統合開発環境について                           13
      3 どのエディタを使うか                            8
      4 C言語の規格                                    10
   8 情報の集めかた                                46
      1 man                                            35
      2 info                                            6
      3 検索エンジン                                    3
   9 gccを使ったビルド（2）gccのオプション        108
      1 デバッグ                                       17
      2 デバッガ                                       55
      3 gcc -Wall                                       9
      4 最適化                                          8
   10 コマンドライン引数                          134
      1 argcとargv                                     42
      2 args.c                                         27
      3 実験                                           65

ソースコード展開というのは以下の #@mapfile みたいなやつ。

エディタは何でも構わないので以下のプログラムを打ち込んでください。
　
//list[hello_c][hello.c]{
#@mapfile(src/hello.c)
#include <stdio.h>
　
int
main(int argc, char **argv)
{
    puts("Hello, Linux!");
    return 0;
}
#@end
//}

この原稿をプリプロセッサにかけると #@mapfile 〜 #@end の部分に ./src/hello.c が展開される。 単なる include 機能では原稿を書くのには不足である。

最後の依存チェッカは今回の Linux 本で初めて使ってるんだけど、 キーワードの provide/require を宣言しておくと 内容の依存関係をチェックしてくれるツールだ。 以下の #@require と #@provide がそれ。

このあたりの事情も「Linuxはカーネルだけ」と言われる所以です。
#@provide(libc)
　
#@require(ライブラリ)
続いて/libを眺めてみると、他にもlibmだとかlibdlだとかlibnssなんたら
というファイルがありますね。実はこれも標準Cライブラリの一部です。
libmならば数学関係の関数、例えばsin()やcos()が入っています。
一つのライブラリなのに複数のファイルに分かれている事情はそれぞれです。
例えばlibmは歴史的な理由ですが、libdlには必然性があります。

読者が知っていると仮定してよいかどうかあやふやなものも とりあえず require しておけばよい。 本全体の前提条件にしたいキーワードは別途専用ファイルで宣言できる。

原稿書きツールに関する全体的な注意としては、 人間がいじる部分とツールがいじる部分を明確に分けておくこと。 例えば用語チェックをするなら怪しい個所を報告するだけに留め、 勝手に修正したりはしない。 長い文章では適用外にしたいところが必ず出てくるからだ。

そうは言っても自動変更するツールもやはり必要になる。 例えばソースコード展開プリプロセッサがそうだ。 このようなツールを使う場合はツール適用前に必ずコミットしておいて、 適用後は cvs diff で (目で) 変更点をチェックしてから再度コミットする。 ちなみにバージョン管理システムを使わないなんてのは問題外である。

最後に、内容をチェックするときは紙に印刷して読んだほうがよい。 なんでかわからないが、画面で読むだけでは絶対にチェック漏れが出る。

(06:27)