Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

update docs

  • Loading branch information...
commit 2261a53a495358f51632c97f9ea993316a1628a8 1 parent f0dfe8f
@hsbt hsbt authored
View
0  doc/COPYING → LICENSE
File renamed without changes
View
298 doc/HOWTO-make-io.html
@@ -0,0 +1,298 @@
+<?xml version="1.0" ?>
+<!DOCTYPE html
+ PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>HOWTO-make-io.rd</title>
+</head>
+<body>
+<h1><a name="label-0" id="label-0">IOクラスの作り方</a></h1><!-- RDLabel: "IOクラスの作り方" -->
+<h2><a name="label-1" id="label-1">概要</a></h2><!-- RDLabel: "概要" -->
+<p>tDiaryは、保存形式や日記記述フォーマットを差し替えることができます。
+保存形式はIOクラスと呼ばれるTDiary::IOBaseクラスを継承したクラスを実
+装することで変更可能です。また、記述フォーマットはDiaryBaseモジュー
+ルをincludeしたクラスで実装します。このドキュメントでは、これらの実
+装に関する解説を行います。</p>
+<h2><a name="label-2" id="label-2">IOクラス</a></h2><!-- RDLabel: "IOクラス" -->
+<p>保存形式を変更する新たなクラスを作成し、tdiary.confで指定することで、
+tDiary独自の保存形式と違う、独自の保存形式を選択できます。例えばDBMS
+に日記データを保存する等、異なる運用のtDiaryを作ることが可能です。こ
+れを実現するための仕組みを総称して「IOクラス」と呼んでいます(RubyのIO
+クラスとは違います)。</p>
+<h3><a name="label-3" id="label-3">IOBaseクラス</a></h3><!-- RDLabel: "IOBaseクラス" -->
+<p>tdiary.rbにはTDiary::IOBaseというクラスが定義されており、これを継承
+して独自のIOクラスを作成します。下記の例は、HogeIOを定義しています。</p>
+<pre>class HogeIO &lt; TDiary::IOBase
+ def clendar
+ ......
+ end
+
+ .....
+end</pre>
+<h3><a name="label-4" id="label-4">最低限実装すべきもの</a></h3><!-- RDLabel: "最低限実装すべきもの" -->
+<p>IOBaseクラスにはIOクラスに共通ないくつかのメソッドがすでに実装してあ
+ります。これを継承したIOクラスでは、さらに以下のようなメソッドを実装
+しなくてはいけません。</p>
+<h4><a name="label-5" id="label-5">calendar</a></h4><!-- RDLabel: "calendar" -->
+<p>tDiaryに、日記が存在する年月を通知するためのメソッドです。実行時にtDiary
+から呼び出されます。</p>
+<p>返り値には、現在利用できる日記が含まれている年・月を、Hashオブジェク
+トで返します。Hashに含まれている各値は、キーに西暦年(Stringで4文字)、
+対応する値にはArrayで月(Stringで2桁)を設定します。以下に例を示します。</p>
+<pre>def calendar
+ return {
+ '2001' =&gt; ['12'],
+ '2002' =&gt; ['01', '02', '03', '04', '05', '08']
+ }
+end</pre>
+<h4><a name="label-6" id="label-6">transaction( date )</a></h4><!-- RDLabel: "transaction( date )" -->
+<p>指定された月の日記データを読み込み、tDiaryに理解できる形で渡します。</p>
+<p>引数dateはTimeオブジェクトで、年と月のみがlocaltimeで与えられます。</p>
+<p>transactionメソッドはdateで指定された月の日記データをファイル(または
+その他の媒体)から読み出して、ブロックパラメタとしてtDiaryに返します。
+このブロックパラメタはHashで、キーに年月日(Stringで8桁)、値に日記デー
+タ(後述するDiaryBaseをincludeしたクラスのインスタンス)を持ちます。</p>
+<p>ブロックパラメタを受けとったtDiaryは、それを使って日記を表示または更
+新するので、transactionメソッドはその返り値に従って日記を保存する等
+の処理を行えます。以下にtDiaryからの返り値を示します。実際にはこれら
+の論理和が返ります。</p>
+<ul>
+<li>TDiary::TDiaryBase::DIRTY_NONE: 日記データに変更はありませんでした</li>
+<li>TDiary::TDiaryBase::DIRTY_DIARY: 日記本文に変更がありました</li>
+<li>TDiary::TDiaryBase::DIRTY_COMMENT: ツッコミに変更がありました</li>
+<li>TDiary::TDiaryBase::DIRTY_REFERER: リンク元に変更がありました</li>
+</ul>
+<p>以下にtransactionの例を示します。</p>
+<pre>def trasaction( date )
+ diaries = { ... } # restore data
+ dirty = yield( diaries )
+ if dirty &amp; TDiary::TDiaryBase::DIRTY_DIARY != 0 then
+ ... # saving diary data
+ if dirty &amp; TDiary::TDiaryBase::DIRTY_COMMENT != 0 then
+ ... # saving comment data
+ if dirty &amp; TDiary::TDiaryBase::DIRTY_REFERER != 0 then
+ ... # saving referer data
+ end
+end</pre>
+<h4><a name="label-7" id="label-7">diary_factory( date, title, body, style = 'tDiary' )</a></h4><!-- RDLabel: "diary_factory( date, title, body, style = 'tDiary' )" -->
+<p>diary_factoryは、指定されたフォーマットの日記オブジェクトを生成して
+返します。</p>
+<p>引数dateは日付(Stringで8桁)を指定します。title、bodyはそれぞれ生成す
+る日記のタイトルと本文です(String)。styleは日記の記述形式を指定する
+文字列で、diary_factoryに依存します。</p>
+<p>返り値はDiaryBaseをincludeした継承したクラスのオブジェクトです。</p>
+<p>以下にdiary_factoryの例を示します。</p>
+<pre>def diary_factory( date, title, body, style = 'tDiary' )
+ case style
+ when 'tDiary'
+ DefaultDiary::new( date, title, body )
+ default
+ raise StandardError, 'bad style'
+ end
+end</pre>
+<p>もし、スタイルに対応したIOクラスを作るなら、initializeでload_styleを
+呼んだ上で、以下のようにstyled_diary_factoryを呼ぶだけで良いです。</p>
+<pre>def diary_factory( date, title, body, style = 'tDiary' )
+ styled_diary_factory( date, title, body, style )
+end</pre>
+<h2><a name="label-8" id="label-8">日記データ</a></h2><!-- RDLabel: "日記データ" -->
+<p>続いて、IOクラスのtransactionメソッドの返り値に含まれる日記データが
+満たすべき条件について述べます。
+日記データの具体例としては tdiary/tdiary_style.rb で定義されている
+TDiary::DefaultDiary を参照してください。</p>
+<p>「日記データ」は以下の要素から構成されています。</p>
+<ul>
+<li>日付</li>
+<li>タイトル</li>
+<li>最終更新日</li>
+<li>0個以上のセクション</li>
+<li>0個以上のツッコミ</li>
+<li>0個以上のリンク元</li>
+</ul>
+<p>さらに「セクション」は以下の要素から構成されています。</p>
+<ul>
+<li>サブタイトル</li>
+<li>著者</li>
+<li>本文</li>
+</ul>
+<p>日記のデータ構造がこれと完全に同一である必要はなく、日記データが付加
+的なデータを持ったり、
+セクションがいくつかのサブセクションに分かれたりしても良いです。</p>
+<h2><a name="label-9" id="label-9">カテゴリ機能について</a></h2><!-- RDLabel: "カテゴリ機能について" -->
+<p>カテゴリ機能とは、日記中のセクションにキーワードを付けて、
+あとで同じキーワードをまとめて一覧できる機能のことです。</p>
+<p>セクションのカテゴリは、サブタイトル中で指定します。
+tDiaryスタイルでは</p>
+<pre>[カテゴリ] サブタイトル</pre>
+<p>のようにカテゴリを指定することにしていますが、
+IOクラス/スタイル作者が各IOクラス/スタイルに適した
+カテゴリ指定の文法を定義して下さい。</p>
+<p>カテゴリ機能の実装は必須ではありません。
+日記データをカテゴリ機能に対応させるかどうかはIOクラスの作者が判断して下さい。</p>
+<h2><a name="label-10" id="label-10">日記データのクラス</a></h2><!-- RDLabel: "日記データのクラス" -->
+<p>日記データからはその日付、タイトル、最終更新日、日記本文、
+コメント、Referer、セクションなどを参照できる必要があります。</p>
+<p>もし、この日記データをスタイルとして設計するのであれば、IOクラスとは
+分離して、別のファイルにする必要があります。この場合、スタイル名と
+ファイル名、日記データクラス名には強い依存性があります。「Hoge」という
+スタイルを作る場合、以下のように作る必要があります。</p>
+<ul>
+<li>スタイル名: Hoge</li>
+<li>ファイル名: hoge_style.rb</li>
+<li>クラス名 : TDiary::HogeDiary (スタイル名.capitalize + 'Diary')</li>
+</ul>
+<h3><a name="label-11" id="label-11">DiaryBaseモジュール</a></h3><!-- RDLabel: "DiaryBaseモジュール" -->
+<p>tdiary.rbにはDiaryBaseというモジュールが定義されており、
+日記データのクラスはこのモジュールをincludeしなければなりません。</p>
+<p>下記の例はHogeDiaryにDiaryBaseをincludeしています。</p>
+<pre>class HogeDiary
+ include DiaryBase
+
+ .....
+end</pre>
+<h3><a name="label-12" id="label-12">CategorizableDiary/UncategorizableDiaryモジュール</a></h3><!-- RDLabel: "CategorizableDiary/UncategorizableDiaryモジュール" -->
+<p>tdiary.rbにはCategorizableDiaryとUncategorizableDiaryというモジュールが定義されています。
+日記データのクラスは、カテゴリ機能に対応している場合はCategorizableDiaryモジュールを、
+カテゴリ機能に対応していない場合はUncategorizableDiaryモジュールを
+includeしなければなりません。</p>
+<p>下記の例はHogeDiaryにCategoriabeleDiaryをincludeしています。</p>
+<pre>class HogeDiary
+ include CategorizableDiary
+
+ .....
+end</pre>
+<h3><a name="label-13" id="label-13">最低限実装すべきもの</a></h3><!-- RDLabel: "最低限実装すべきもの" -->
+<p>DiaryBaseモジュールには日記データのクラスに必要な幾つかのメソッドが
+定義されています。DiaryBaseで定義されているメソッド以外に
+日記データのクラスが備えるべきメソッドは下記のものになります。
+(ここでいうメソッドは Public Instance Method のことです。)</p>
+<ul>
+<li>initialize</li>
+<li>replace</li>
+<li>append</li>
+<li>each_section</li>
+<li>to_html</li>
+<li>to_src</li>
+<li>style</li>
+</ul>
+<p>メソッドではありませんが、 インスタンス変数の @last_modified には気をつけましょう。
+日記データに変更があった場合に @last_modified に適切なTimeオブジェクトを設定しないと、
+キャッシュの更新がうまくいきません。</p>
+<ul>
+<li>@last_modified</li>
+</ul>
+<h4><a name="label-14" id="label-14">initialize</a></h4><!-- RDLabel: "initialize" -->
+<p>日記データを初期化します。引数はIOクラスによって違うものになります。
+このメソッドでは DiaryBase#init_diary を呼ばなくてはなりません。</p>
+<p>例</p>
+<pre>class HogeDiary
+ include DiaryBase
+ .....
+
+ def initialize(date, title, body, modified = Time::now)
+ init_diary
+ .....
+ end
+
+ .....
+end</pre>
+<h4><a name="label-15" id="label-15">replace(date, title, body)</a></h4><!-- RDLabel: "replace(date, title, body)" -->
+<p>日記データの日付をdateに、日記本文のソースをbodyに、タイトルをtitleに変更します。
+dateはTimeオブジェクト、もしくは、日付をあらわす文字列('YYYYMMDD')です。
+日付を表す文字列は具体的には下のようになります。</p>
+<ul>
+<li>'20020831'</li>
+<li>'20010101'</li>
+</ul>
+<p>body, titleは文字列です。</p>
+<p>日記本文が変更された場合、日記本文を解釈し直す必要があります。
+解釈し直す時には日記データを構成するセクションも変更されます。</p>
+<h4><a name="label-16" id="label-16">append(body, author = nil)</a></h4><!-- RDLabel: "append(body, author = nil)" -->
+<p>日記本文を追加します。bodyは追加される日記本文です。
+authorは日記を記述した人の名前で、文字列です。
+authorの引数はデフォルトでnilにしなければなりません。</p>
+<p>日記本文が変更された場合、日記本文を解釈し直す必要があります。
+解釈し直す時には日記データを構成するセクションも変更されます。</p>
+<h4><a name="label-17" id="label-17">each_section</a></h4><!-- RDLabel: "each_section" -->
+<p>each_section は各セクションをブロックパラメータとして返します。</p>
+<p>下に一例を示します。ここで@sectionsはセクションを保持するArrayのオブジェクトです。</p>
+<pre>class HogeDiary
+ .....
+
+ def each_section
+ @sections.each |section|
+ yield(section)
+ end
+ end
+
+ .....
+end</pre>
+<h4><a name="label-18" id="label-18">to_html(opt, mode = :HTML)</a></h4><!-- RDLabel: "to_html(opt, mode = :HTML)" -->
+<p>日記データをHTMLに変換します。引数optは設定ファイル(tdiary.conf)の内容の一部を
+保持するHashオブジェクトです。引数modeはSymbolオブジェクトで、
+現在は下記のいずれかです。</p>
+<ul>
+<li>:HTML</li>
+<li>:CHTML</li>
+</ul>
+<p>想定しないmodeが指定された場合は、:HTMLが指定されたものとみなして下
+さい。:HTMLの場合は通常のブラウザ用にHTMLに、:CHTMLの場合は携帯端末
+用にcHTMLに変換しなければなりません。</p>
+<p>optの内容によって、日記のリンク先を変更しなければならないので、注意
+が必要です。</p>
+<p>カテゴリ機能に対応した日記データのクラスでは、
+各セクションのサブタイトル中のカテゴリ指定をcategory_anchorプラグインの呼出しに変換して下さい。</p>
+<h4><a name="label-19" id="label-19">to_src</a></h4><!-- RDLabel: "to_src" -->
+<p>日記の本文を返します。</p>
+<h4><a name="label-20" id="label-20">style</a></h4><!-- RDLabel: "style" -->
+<p>日記データを記述するスタイル名を返します。
+tDiary標準の記述形式の場合は「tDiary」です。
+この文字列は、システム上は大小文字を区別しません。</p>
+<h2><a name="label-21" id="label-21">セクションのクラス</a></h2><!-- RDLabel: "セクションのクラス" -->
+<p>日記本文は幾つかのセクションに分かれます。
+セクションは日記本文、セクションのタイトル、セクションを書いた人の名前
+などをデータとして保持しています。
+セクションクラスの例としては、tdiary/defaultio.rbにある
+TDiary::DefaultSectionクラスを参照してください。</p>
+<h3><a name="label-22" id="label-22">最低限実装すべきメソッド</a></h3><!-- RDLabel: "最低限実装すべきメソッド" -->
+<p>以下にセクションのクラスが実装すべきメソッドを列挙します。</p>
+<ul>
+<li>subtitle</li>
+<li>body</li>
+<li>to_src</li>
+<li>author</li>
+<li>subtitle_to_html</li>
+<li>body_to_html</li>
+</ul>
+<p>カテゴリ機能に対応させるには、以下のメソッドを実装する必要があります。</p>
+<ul>
+<li>stripped_subtitle</li>
+<li>stripped_subtitle_to_html</li>
+<li>categories</li>
+</ul>
+<h4><a name="label-23" id="label-23">subtitleとsubtitle_to_html</a></h4><!-- RDLabel: "subtitleとsubtitle_to_html" -->
+<p>セクションのタイトルを文字列として返します。
+タイトルがない場合はnilを返します。</p>
+<p>subtitleはスタイルの文法で記述された本文を、subtitle_to_htmlはHTMLに変換後の本文を返します。</p>
+<h4><a name="label-24" id="label-24">bodyとbody_to_html</a></h4><!-- RDLabel: "bodyとbody_to_html" -->
+<p>セクションに対応する本文を返します。返り値の文字列にはタイトルも著者も含まれません。
+本文がない場合は空文字("")を返します。</p>
+<p>bodyはスタイルの文法で記述された本文を、body_to_htmlはHTMLに変換後の本文を返します。</p>
+<h4><a name="label-25" id="label-25">to_src</a></h4><!-- RDLabel: "to_src" -->
+<p>セクションに対応する本文を返します。返り値の文字列にはタイトルと著者が含まれます。
+本文がない場合は空文字("")を返します。</p>
+<h4><a name="label-26" id="label-26">author</a></h4><!-- RDLabel: "author" -->
+<p>セクションを書いた人の名前を文字列として返します。
+書いた人の名前がない場合は nil を返します。</p>
+<h4><a name="label-27" id="label-27">stripped_subtitleとstripped_subtitle_to_html</a></h4><!-- RDLabel: "stripped_subtitleとstripped_subtitle_to_html" -->
+<p>セクションのタイトルからカテゴリ指定部分を取り除いた文字列を返します。
+タイトルがない場合や、カテゴリ指定部分を取り除いた文字列が空文字("")の場合は
+nilを返します。</p>
+<p>stripped_subtitleはスタイルの文法で記述された本文を、stripped_subtitle_to_htmlはHTMLに変換後の本文を返します。</p>
+<h4><a name="label-28" id="label-28">categories</a></h4><!-- RDLabel: "categories" -->
+<p>セクションのカテゴリを文字列の配列として返します。
+タイトル中にカテゴリ指定がない場合は[]を返します。</p>
+
+</body>
+</html>
View
60 doc/UPGRADE
@@ -1,12 +1,72 @@
------------------------
このドキュメントについて
------------------------
+
 tDiaryは、バージョン番号の2桁目が偶数のもの(1.0.x、1.2.x...)がリリ
ースバージョン、奇数のもの(0.9.xx、1.1.x...)が開発バージョンとなって
います。このドキュメントでは、リリースバージョン間の変更点について解
説します。開発バージョンを使っている場合は、ChangeLogファイルを参照し
てください。
+
+--------------
+2.2と3.0の違い
+--------------
+2.2系から3.0への最大の変更点は、「UTF-8化」と「ruby 1.9対応」です。
+いずれも大きな変更になりますので、以下の注意をよく読んでから
+アップデートを行って下さい。
+すでに2.3系で運用している場合は特に大きな問題はでないでしょう。
+
+■アップデートに関する注意点■
+
+■文字コードのUTF-8化
+tDiary 3.0では日記データのファイルのエンコードをEUC-JPからUTF-8へと
+変更しています。この変更により複数の言語で日記を書けるようになりました。
+
+tDiary 3.0にバージョンアップすることで、自動的に新しく書いた日記は
+エンコーディングがUTF-8で作成され、過去の日記データも表示する際に
+EUC-JPからUTF-8に自動的に変換されます。
+
+いちどUTF-8に変換された日記データは、基本的にはEUC-JPへは戻せません。
+かならずバックアップをとってからアップデート作業をしてください。
+
+■ruby 1.9.2 への対応
+tDiary 3.0ではrubyを1.9.2にバージョンアップするだけで移行できるように
+なっていますが、 tDiaryが生成するキャッシュファイルは互換性の問題で
+まれにエラーになることがあります。
+
+エラーになった場合のもっとも簡単な対処は、データディレクトリにある
+cacheディレクトリを丸ごと削除する方法です。ただし、counter.rbの情報が
+消えるとカウンタが巻き戻ってしまうので、初期値を控えておくなどの対処が
+必要です。また makerss.rbやrecent_comment.rbが生成するキャッシュが
+消えるため、しばらくは寂しい状況になるかも知れませんが、これらは時間が
+解決してくれます:-) すべてのキャッシュを削除するのが困難な場合は、
+個別のファイルごとに対処してください。
+
+また、カテゴリに関する情報も、同様な理由でエラーを起こすことがあります。
+この場合は、categoryプラグインの設定画面で「カテゴリインデックスの作成」を
+実行してください。
+
+いちどruby 1.9.2上で動作させた日記データは、基本的には1.8へは戻せません。
+かならずバックアップをとってからアップデート作業をしてください。
+
+■tDiary 3.0とruby 1.9.2を同時にアップデートしない
+ruby 1.8.* で動かしているtDiary 2.2系をtDiary 3.0とruby 1.9.2の環境へ
+同時にアップデートすることは避けるべきでしょう。日記データが壊れることは
+ないはずですが、キャッシュデータが壊れてしまう可能性があります。
+
+どうしてもtDiaryとrubyの両方をバージョンアップしたい場合は以下の手順で
+バージョンアップして下さい。
+
+tDiaryをまず3.0にバージョンアップし、ruby 1.8の状態でブラウザから日記を
+表示します。この際に日記データと利用しているプラグインのキャッシュデータが
+UTF-8へと変換されます。
+利用しているプラグインの動作を全て確認後にruby 1.9.2へとアップデートします。
+利用しているプラグインによっては、上記の手順で完全に変換が実行されない
+可能性もあります。
+
+不安な場合は<tdiary-devel@sourceforge.net>まで相談してください。
+
--------------
2.0と2.2の違い
--------------
View
0  doc/tdiary.conf.sample-en → tdiary.conf.sample-en
File renamed without changes
Please sign in to comment.
Something went wrong with that request. Please try again.