Cleite
******

Cleite はクライアントとサーバーから成る RSS リーダーである。サーバーを特定のホストで起動させて置くだけで、樣々な環境から RSS フィードの未讀 / 既讀管理を行ふ事が出來る。

サーバーとクライアントは獨立したプログラムになってをり、それぞれの實裝は交換可能である。現在サーバーは Scheme で書かれ、處理系 Chicken によって動作する。クライアントは EmacsLisp で書かれ、Emacs 上で動作する。

Cleite は一人で使ふ事も出來るし、サーバーを複數人で共有する事も出來る。複數人で共有する場合、もし一つの RSS フィードを見てゐるユーザーが複數人居れば、重複してフィードを取得する必要が無くなる爲に效率が良い。

Cleite [kˈlˈetˈə] （片假名で書けば「クレチャ」）とはアイルランド・ゲール語 (http://en.wikipedia.org/wiki/Irish_language) で『羽根』といふ意味であるが、この名前を付けたのはこの文書を書いてゐる時から一年以上も前の事であるので、何故そのやうな名前にしたのか、もう憶へてゐない。

導入
**

必要なもの
=====

  * SQLite 3

     SQLite (http://www.sqlite.org/) は組込み型のデータベースエンジンである。

  * Chicken

     Chicken (http://www.call-with-current-continuation.org/) は Scheme のコンパイラ/インタプリタであり、Cleite サーバー ``CleiteD'' を動作させる爲に必要である。Chicken の擴張ライブラリは ``Egg'' と呼ばれる。 CleiteD が動作する爲には次のやうな Egg (http://chicken.wiki.br/Eggs%20Unlimited) がインストールされてなければならない。

       * args (http://chicken.wiki.br/args)

       * base64 (http://www.call-with-current-continuation.org/eggs/base64.html)

       * format (http://www.call-with-current-continuation.org/eggs/format.html)

       * hostinfo (http://chicken.wiki.br/hostinfo)

       * htmlprag (http://chicken.wiki.br/htmlprag)

       * iconv (http://chicken.wiki.br/iconv)

       * mailbox (http://www.call-with-current-continuation.org/eggs/mailbox.html)

       * regex-case (http://www.call-with-current-continuation.org/eggs/regex-case.html)

       * rfc3339 (http://www.call-with-current-continuation.org/eggs/rfc3339.html)

       * ssax (http://www.call-with-current-continuation.org/eggs/ssax.html)

       * sxml-tools (http://chicken.wiki.br/sxml-tools)

       * sqlite3 (http://www.call-with-current-continuation.org/eggs/sqlite3.html)

       * sha2 (http://www.call-with-current-continuation.org/eggs/sha2.html)

       * tcp-server (http://www.call-with-current-continuation.org/eggs/tcp-server.html)

       * tinyclos (http://chicken.wiki.br/tinyclos)

     依存ライブラリが多くて濟まなく思ふが、その分、クライアント側のものは少ないので我慢して慾しい。

  * GNU Emacs

     GNU Emacs (http://www.gnu.org/software/emacs/) は言はずと知れた高性能エディタである。GNU Emacs 22.0.50.1 で動作確認した。これよりも古いバージョンでは動作しないかも知れない。

  * EIEIO

     EIEIO (http://cedet.sourceforge.net/eieio.shtml) は Emacs Lisp でオブジェクト指向プログラミングを實現する爲のパッケージである。

コンパイル方法
=======

コマンド例
-----

     % ./configure -C --with-eieio=/path/to/eieio --with-default-logging-level=error
     % make -w
     % sudo make install

configure オプション
---------------

--disable-cleited
     サーバープログラム CleiteD をビルドしない。通常このオプションは使はれない。

--disable-elcleite
     クライアントプログラム ElCleite をビルドしない。通常このオプションは使はれない。

--disable-optimize
     最適化せずにコンパイルする。通常このオプションは使はれないが、CleiteD がクラッシュするやうな問題が起きた時には最適化を無效にしなければ原因が判明しない事がある。

--enable-profile
     CleiteD の實行時效率のプロファイリングを行ふ。開發者用のオプションであり、何が起こるのか判ってゐるのでなければ使ってはならない。

--with-eieio=/path/to/eieio
     EIEIO (http://cedet.sourceforge.net/eieio.shtml) の eieio.el が含まれるディレクトリへのパスを指定する。通常この指定は必須である。

--with-daemonic=/path/to/daemonic
     daemonic (http://daemonic.sourceforge.net/) を利用したい場合、 daemonic の XML ファイル群の含まれるディレクトリへのパスを指定する。

--with-default-home=/path/to/cleited/home
     CleiteD の DB ファイルやログファイルを置くデフォルトの場所。指定しなければ ``${prefix}/var/cleited'' になる。

--with-default-port=num
     CleiteD の使用するデフォルトのポート番號。指定しなければ 9895 になる。

--with-default-user=name
     CleiteD の動作するデフォルトのユーザ名。指定しなければ ``daemon'' になる。CleiteD を root で起動すると、指定された通りのユーザの権限で動作する。

--with-default-group=group
     CleiteD の動作するデフォルトのグループ名。指定しなければ ``group'' になる。CleiteD を root で起動すると、指定された通りのグループの権限で動作する。

--with-default-client-limit=limit
     同時に幾つまでのクライアントからの接續を受け付けるか。指定しなければ 100 になる。

--with-default-poller-limit=limit
     同時に幾つまでの RSS フィードを取得するか。指定しなければ 5 になる。

--with-default-logging-level=level
     どのレベルまでのログを記録するか。レベルは none, error, warn, info, debug で指定し、後のものほど重要性が低い。指定しなければ none になり、このレベルではログが一切記録されない。

環境變數
----

CSC
     Chicken のコンパイラプログラムである csc のコマンド名を指定する。

ElCleite の導入
============

ElCleite は Emacs Lisp パッケージであるから、利用するには $HOME/.emacs.el を書き換へなければならない。次のやうな設定を追加すると、M-x cleite で ElCleite を起動出來るやうになる。

     (autoload 'cleite "cleite" "Cleite RSS Aggregator -- Emacs Interface" t)

使ひ方
***

CleiteD の起動
===========

CleiteD はサーバープログラムであるから、クライアントを接續する前に、豫め起動させて置かなければならない。

CleiteD が起動してゐなければフィードの再讀込みも行はれないので、常時起動してゐる事が望ましく、OS の起動と同時に起動するやうにすると便利である。

daemonic (http://daemonic.sourceforge.net/) の利用可能な OS（現時點でそれは Darwin と MacOS X のみであるが）を使ってゐる場合には、コンパイル時に --with-daemonic=path を指定すると daemonic 定義ファイルがインストールされる。後は % daemonic enable cleited を實行するだけで良い。その他の OS を使ってゐる場合は、/etc/init.d/cleited のやうなファイルを自分で書いて慾しい。

コマンド例
-----

     % sudo cleited

オプション
-----

-h, --help
     利用可能なオプションの一覽を表示する。

-H, --home=/path/to/home
     DB ファイルやログファイルを置く場所を指定する。

-P, --port=num
     使用するポート番號を指定する。

-U, --user=user
     setuid 先ユーザ名を指定する。

-G, --group=group
     setgid 先グループ名を指定する。

--client-limit=limit
     同時に受け付ける最大のクライアント接續數を指定する。

--poller-limit=limit
     同時に取得する最大の RSS フィード數を指定する。

--logging-level=level
     記録するログの最低レベルを指定する。レベルは none, error, warn, info, debug で指定し、後のものほど重要性が低い。

-s, --stop
     起動中の CleiteD を正常終了させる。

--kill
     起動中の CleiteD を強制終了させる。データが破損するかも知れないので、 --stop で終了しなくなった場合にのみ用ゐる。

-r, --restart
     起動中の CleiteD を正常終了させ、再度起動する。

-f, --no-fork
     fork(2) せずに動作するモードで CleiteD を起動する。基本的にはデバッグ用のオプションである。

ElCleite の起動
============

ElCleite は M-x cleite で起動する。初囘起動時にはパスワードが指定されてゐないので、パスワードを聞かれる事無く Feeds と名付けられたバッファが開かれる。このバッファでは RSS フィードの追加や削除を行ふ事が出來る。

しかし實際にフィードを追加する前に、パスワードを變更して置く事を勸める。さうしなければ誰かが勝手にログインして既讀フラグを立てたりフィードを削除したりするかも知れない。パスワードを指定すると、起動時にパスワードを訊かれるやうになる。See Account Configuration.

Feeds バッファ
==========

RSS フィードの追加、削除、撰擇などを行ふ。

q
     ElCleite を終了する。

RET
     カーソルの置かれてゐるフィードを撰擇し、項目の一覽を表示する。See Feed Items Buffer.

s
     Feeds バッファを再度讀み込む。

N
     未讀項目のある次のフィードへカーソルを移す。

P
     未讀項目のある前のフィードへカーソルを移す。

n
     次のフィードへカーソルを移す。

p
     前のフィードへカーソルを移す。

a
     フィードを追加する。See Add feed.

d
     カーソルの置かれてゐるフィードを削除する。

r
     カーソルの置かれてゐるフィードのランクを變更する。See Rank.

O
     OPML ファイルの讀み書きを行ふ。See Manipulate OPML.

フィードの追加
-------

Feeds バッファ で a を押すと、RSS フィードの URL を尋ねられる。ここでは RSS フィードへリンクしてゐる HTML の URL を入力しても良く、その場合は追加したいフィードを HTML の中から撰ぶ事が出來る。

現在 CleiteD が讀む事の出來る形式は、RSS 1.0 及び RSS 2.0 のみである。 Atom 形式には對應してゐない。

ランク
---

Feeds バッファ で r を押すと、1 から 5 までのランク値の入力を求められる。ランク値は Feeds バッファでのフィードのソート順に影響を與へる。氣に入ってゐるフィードほど高いランク値を設定すると良い。

OPML の取扱ひ
---------

Feeds バッファ で O を押すと、OPML を取扱ふ爲のメニューが表示される。

e
     OPML をファイルに出力する。

f
     OPML ファイルを讀み、その中にある全てのフィードを追加する。

u
     OPML の URL を指定し、その中にある全てのフィードを追加する。

Feed Items バッファ
===============

RSS フィード項目の撰擇や未讀管理等を行ふ。

RET
     カーソルの置かれてゐる項目を撰擇し、内容を表示する。See Article Buffer.

U
     カーソルの置かれてゐる項目の URL やタイトル等を kill-ring に入れる。

s
     Feed Items バッファを再度讀み込む。

N
     次の未讀項目へカーソルを移す。

P
     前の未讀項目へカーソルを移す。

n
     次の項目へカーソルを移す。

p
     前の項目へカーソルを移す。

u
     カーソルの置かれてゐる項目を未讀にする。

r
     カーソルの置かれてゐる項目を既讀にする。

m u
     region の範圍の項目を未讀にする。

m r
     region の範圍の項目を既讀にする。

q
     Feed Items バッファを閉ぢる。

Article バッファ
============

RSS フィード項目の内容を讀む。

RET
     (browse-url) を用ゐて内容をブラウザで開く。

U
     カーソルの置かれてゐる項目の URL やタイトル等を kill-ring に入れる。

j
     ウインドウを一行上にスクロールする。

k
     ウインドウを一行下にスクロールする。

N
     次の未讀項目を開く。

P
     前の未讀項目を開く。

n
     次の項目を開く。

p
     前の項目を開く。

q
     Article バッファを閉ぢる。

アカウント設定
=======

アカウントの管理は次のやうなコマンドで行ふ。これらは ElCleite の全てのバッファで利用可能である。

C-c C-p
     自分のアカウントのパスワードを變更する。

C-c C-a
     新規にアカウントを作成する。この操作を行へるのは特権ユーザーのみである。

C-c C-d
     アカウントを削除する。この操作を行へるのは特権ユーザーのみである。もし全ての特権ユーザーを削除してしまった場合は、次のやうにして DB を直接書き換へない限り、復活させる事は出來ない。

          % sudo sqlite3 /usr/local/var/cleited/cleited.db
          sqlite> INSERT INTO accounts
             ...>        (user_id, passwd, name, is_root)
             ...> VALUES ("root", "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU", "Root", 1);

     passwd フィールドにはパスワードの SHA-256 ハッシュを Base64 エンコードした結果が入る。``47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU'' は空文字列をそのやうにエンコードした結果である。

C-c C-u
     アカウント情報を變更する。特権ユーザーは自分以外のユーザーの情報を變更する事が出來る。もし全ての特権ユーザーの特権を剥奪してまった場合は、削除してしまった場合と同じやうに DB を書き換へる必要がある。

ElCleite の設定
============

M-x customize-group cleite で ElCleite の設定を行ふ事が出來る。きっと見れば分かるので、ここでは解説しない。

CleiteD の設定
===========

本來はクライアントを使って CleiteD の設定を變更出來るやうになってゐるのであるが、ElCleite には未だその爲の機能が實裝されてゐないので、どうしても次のやうな設定を變更したい時は、現在は DB を直接書き換へる必要がある。

max-items-per-feed
     一つのフィードにつき最大幾つまでの項目を記憶するか。設定値は自然數でなければならない。初期値は 999。

polling-interval-minute
     各々のフィードの更新を何分に一度確認するか。設定値は自然數でなければならない。初期値は 180。

DB の書き換へは次のやうに行ふ。

     % sudo sqlite3 /usr/local/var/cleited/cleited.db
     sqlite> UPDATE config
        ...>    SET conf_val = 1500
        ...>  WHERE conf_key = "max-items-per-feed"

開發者向けの情報
********

本當はここに RPC プロトコルの詳細を書かうと思ったが、面倒になった。プロトコル詳細は cleited/srpc-passible-node.scm の冒頭のコメントに有り、API ドキュメントは pod/cleite-api.pod に有る。両方讀めばクライアントを自作する事も出來るだらう。