tdiary 3.2.2.20130507

data/doc/HOWTO-write-tDiary.en.md

@@ -0,0 +1,131 @@
+tDiary -- How to write diary
+============================
+
+Index
+-----
+
+  - Format of the diary in tDiary
+  - Tips
+
+Format of the diary in tDiary
+-----------------------------
+
+Basically, you write your diary in HTML. But, the format of the diary has extra rules in order to write your diary without knowledge of HTML. In this format, a linefeed and a character at the beginning of the line have special meanings. These rules are for the purpose of setting sub-title and paragraph easily.
+
+The rules are explained below. To distinguish a linefeed in appearance(HTML) from an actual linefeed(format), "$" stands for an actual linefeed in this manual.
+
+```
+sub-title(1)$ Like the above, the first line becomes a sub-title. With the tDiary's standard style sheet, the sub-title is displayed in bold face. Lines from the sub-title to the next space line are called section, and a section anchor is added in front of the sub-title. $ Lines after the sub-title, like this line and the line just above, are recognized as normal lines. If a paragraph begins with a sub-title, a section anchor is not attached in front of normal lines.$ $ If a space line exists, the line means the separation of the sections. If space exists in front of the line like this line, the section doesn't have a sub-title. In addition, only the first paragraph has a section anchor. In this case, the line is not shown in bold face.$ If a section doesn't begin with a sub-title, the second and later paragraphs don't have an anchor.$ $
+```
+$ If the paragraph begins with a line whose first character is "$ $ sub-title(2)$ As the result of it, you can't add a sub-title which begins with a HTML tag to a section. But if a line begins with "_This example is formatted below._
+
+[2001-08-03](./?date=20010803)title
+-----
+
+### [_](./?date=20010803#p01)sub-title(1)
+
+ Like the above, the first line becomes a sub-title. With the tDiary's standard style sheet, the sub-title is displayed in bold face. Lines from the sub-title to the next space line are called section, and a section anchor is added in front of the sub-title.
+
+ Lines after the sub-title, like this line and the line just above, are recognized as normal lines. If a paragraph begins with a sub-title, a section anchor is not attached in front of normal lines.
+
+[_](./?date=20010803#p02) If a space line exists, the line means the separation of the sections. If space exists in front of the line like this line, the section doesn't have a sub-title. In addition, only the first paragraph has a section anchor. In this case, the line is not shown in bold face.
+
+ If a section doesn't begin with a sub-title, the second or later paragraphs don't have an anchor.
+
+```
+ If the paragraph begins with a line whose first character is "
+### [_](./?date=20010803#p04)[sub-title(2)](foobar)
+
+As the result of it, you can't add a sub-title which begins with a HTML tag to a section. But if a line begins with "
+
+```
+In tDiary, users can write their diary without HTML if they don't need to decorate their diary. At the same time, users who are familiar to HTML can write full functions of HTML in their diaries. But, If you use HTML tags in your diary, it is better to read the next section, Tips, to avoid pitfalls of tDiary.
+
+Tips
+----
+
+### want a section to include a line which has a tag.
+
+For example, you want to use
+
+tag in your diary in order to use a list and don't want to change a section. Like this case, if you want to decorate the whole paragraph with html tags, you need to use a trick in tDiary. For instance, you hope that your diary is formatted like the next example.
+[2001-08-29](./?date=20010830)
+----------
+
+### [\_](./?date=20010829#p01)sub title
+
+Like this, you write a list which has two items.
+    - item1
+    - item2
+Here is in the same sectionOne way is to merge a paragraph with the previous paragraph. Ordinarily, a paragraph is enclosed by -tag(you can confirm it if you read the HTML source created by tDiary.). You take advantage of this.
+
+```
+sub-title Like this, you write a list which has two items.
+```
+
+  - item1
+  - item2
+
+ Here is in the same section$
+
+It is the point not to put a linefeed. This way is usable if a paragraph enclosed by a tag is not composed of plural lines. But, this is a little difficult to read.
+
+In the way above, you take advantage of the fact that a paragraph is enclosed by
+
+ in tDiary. On the contrary, another way is to take advantage of the fact that
+
+ tag is not inserted to a section if the section has a line which begin with a tag. In the next example, tDiary insert no tag into a section because the section has a line which begins with "-
+
+, except a list.
+```
+sub title$ Like this, you write a list which has two items.
+
+$
+```
+
+$   - item1
+$   - item2
+$
+$  Here is in the same section.
+
+$This way is suitable if a paragraph enclosed by tags is plural. For example, you insert source code with
+
+```
+ tag.Of course, if you don't mind the fact that the sections are split, you are not bothered with formatting. In this case, it may be better to write like the next example.
+
+```
+sub title$ Like this, you write a list which has two items.$ $
+```
+
+```
+
+$   - item1
+$   - item2
+$
+$ $ Here is in the same section.$The last line, "Here ...", has a section anchor, but this is not a big problem.
+
+### You want to insert an anchor per paragraph, not section
+
+tDiary is developed under the policy that it is not necessary to insert an anchor to a paragraph. So, basically, you can't insert an anchor to a paragraph. But, you can insert an anchor to a section in appearance if you utilize the fact that we can make a section without a sub-title. Please read the next example.
+
+```
+sub-title(2)$ $ Like this, you put a space line under the sub-title and make a section to begin with space. This makes two sections. The first section has only the sub-title. The second section has only the paragraph. $ $ If you insert a space line to every paragraph, every paragraph has an anchor.$ $ sub-title(2)$ $ Please be careful that a line which doesn't begin with space becomes a sub-title.$
+```
+This example is displayed like this. It is the point that a line begins with space.
+
+[2001-08-30](./?date=20010830)
+----------
+
+### [\_](./?date=20010830#p01)sub-title(1)
+
+[\_](./?date=20010830#p02)Like this, you put a space line under the sub-title and make a section to begin with space. This makes two sections. The first section has only the sub-title. The second section has only the paragraph.
+
+[\_](./?date=20010830#p03)If you insert a space line to every paragraph, every paragraph has an anchor.
+
+### [\_](./?date=20010830#p04)sub-title(2)
+
+[\_](./?date=20010830#p04)Please be careful that a line which doesn't begin with space becomes a sub-title.
+
+```
+
+```

data/doc/HOWTO-write-tDiary.md

@@ -0,0 +1,136 @@
+日記の書き方
+======
+
+目次
+--
+
+  -
+  -
+
+tDiaryの日記フォーマット
+---------------
+
+本文には、HTMLで日記を記述します。とは言っても、普通の文章だけの日記を書く分にはHTMLを意識しなくても良いように、HTMLに対して改行や行頭文字に特別なルールを加えたものです。サブタイトルや段落を簡単に指定するためにこのような拡張をしてあります。
+
+以下のようなルールがあります。表示上の改行と実際の改行を区別するために、実際の改行には「_↓_」と書いてあります。
+
+********
+
+ サブタイトル(1)_↓_上記のように行頭から始まる行は、サブタイトルとなります。標準のスタイルシートでは、太字で表示されます。サブタイトルから次の空改行までを「セクション」と呼び、サブタイトルの前にはセクションアンカーが付きます。_↓_上の行やこの行のように、サブタイトル以降の行は通常の文章として認識されます。段落がサブタイトルで始まっている場合には、文章の前にはセクションアンカーはつきません。_↓__↓_　空改行があると、セクションの切り替えを意味します。このように、空白で文章を始めると、サブタイトル抜きでセクションが始まります。最初の段落の先頭にだけセクションアンカーが付きます。サブタイトルのある場合ように太字にはなりません。_↓_　サブタイトルで始まらなくても、2つ目の段落以降にはアンカーは付きません。_↓__↓_```
+_↓_このように行の最初が「↓
+   
+ そのセクションは全体が整形の対象にならなくなります。_↓_次に空改行が現れるまで(つまり次のセクションまで)の文_↓_章はそのままの形でHTML内に展開されます。リストやテー_↓_ブルなどを使いたい場合等、HTMLタグをそのまま使いたい_↓_場面に利用できます。セクションアンカーは付きません。_↓_```
+_↓__↓_サブタイトル(2)_↓_必然的に、HTMLタグで始まるサブタイトルがつけられないことになりますが、上記のように「↓
+   
+********
+
+上記の内容は、以下のように表示されます。
+
+********
+
+[2001-08-03](./?date=20010803)(指定したタイトル)
+----------
+
+### [■](./?date=20010803#p01)サブタイトル(1)
+
+上記のように行頭から始まる行は、サブタイトルとなります。標準のスタイルシートでは、太字で表示されます。サブタイトルから次の空改行までを「セクション」と呼び、サブタイトルの前にはセクションアンカーが付きます。
+
+上の行やこの行のように、サブタイトル以降の行は通常の文章として認識されます。段落がサブタイトルで始まっている場合には、文章の前にはセクションアンカーはつきません。
+
+[■](./?date=20010803#p02)　空改行があると、セクションの切り替えを意味します。このように、空白で文章を始めると、サブタイトル抜きでセクションが始まります。最初の段落の先頭にだけセクションアンカーが付きます。サブタイトルのある場合ように太字にはなりません。
+
+　サブタイトルで始まらなくても、2つ目の段落以降にはアンカーは付きません。
+
+```
+ このように最初の行が「
+### [■](./?date=20010803#p04)[サブタイトル(2)](hogehoge)
+
+必然的に、HTMLタグで始まるサブタイトルがつけられないことになりますが、上記のように「
+
+```
+
+********
+
+このようにtDiaryは、簡単な文章だけからなる日記をつける場合にはHTMLを知らなくても使え、HTMLに詳しい場合にはそれもサポートするようになっています。……が、ときどき不用意にタグを使ってハマる人も少なくないので、日記中でタグを多用する人は次の「tDiary記述のコツ」もお読みください。
+
+tDiary記述のコツ
+-----------
+
+### セクションにタグ入りの行を含めたい
+
+例えば日記中にリストを埋め込むために
+
+タグを入れたいとしましょう。話題は同じなのでセクションは変えたくない。このように段落全体を特殊なタグで装飾したい場合、tDiaryでは少しコツが必要です。以下のようなレイアウトをしたい場合を例にとりあげます。
+********
+
+[2001-08-29](./?date=20010830)
+----------
+
+### [■](./?date=20010829#p01)サブタイトル
+
+　以下のように2つの項目からなるリストを書きます。
+    - リスト項目1
+    - リスト項目2
+　こんな感じです。ここまで同一のセクション。
+********
+
+まずひとつの方法は、前の段落に合体させてしまう方法です。生成された日記のHTMLを見ればわかるように、段落というのは〜で囲まれているだけです。これを利用してごまかしを入れます。
+********
+
+サブタイトル_↓_　以下のように2つの項目からなるリストを書きます。
+    - リスト項目1
+    - リスト項目2
+　こんな感じです。ここまで同一のセクション。_↓_********
+
+途中でいっさい改行を入れないところがミソです。タグで囲まれた段落が何行にもわたる場合以外はこれでもけっこういけますが、ちょっと見通しが悪いですね。上の例は、tDiaryが段落には自動的にを入れることを利用しています。逆に、タグで始まる行があるセクションにはこのタグ自体を挿入しないことを利用する方法もあります。通常の段落に、手動でタグを入れる方法です。以下の記述例では、セクション中に「〜で囲んでいます。
+********
+
+サブタイトル_↓_　以下のように2つの項目からなるリストを書きます。_↓__↓_- リスト項目1
+_↓_- リスト項目2
+_↓__↓_　こんな感じです。ここまで同一のセクション。_↓_********
+
+この手法は、タグで囲まれた段落が複数行に渡るとき(例えば
+
+```
+タグでソースコードを挿入するなど)には必須になるでしょう。もちろん、「セクションが分かれても良い」という場合にはもっと楽になります。こだわりがなければ以下のように書いてしまうのが良いかもしれません。
+
+********
+
+ サブタイトル_↓_　以下のように2つの項目からなるリストを書きます。_↓__↓_```
+
+_↓_- リスト項目1
+_↓_- リスト項目2
+_↓__↓__↓_　こんな感じです。ここまで同一のセクション。_↓_********
+
+最後の「こんな感じです〜」の行頭にはセクションアンカーが入ってしまいますが、たいして気にする問題でもないでしょう。
+
+### セクション単位でなく、段落単位にアンカーを入れたい
+
+tDiaryは、「話題の単位はセクションにあり、段落にまでアンカーを入れる必要はない」というポリシーで作られているため、基本的には段落にアンカーを入れることはできません。ただし、サブタイトルなしのセクションが作れることを利用すれば、見た目は段落単位にアンカーを入れることもできます。以下の例を見てください:
+
+********
+
+ サブタイトル(1)_↓__↓_　このようにサブタイトルの下にすぐ空改行を入れてしまい、続く段落を空白で始めるようにすれば、サブタイトルと段落は別々のセクションになります。_↓__↓_　段落の間にすべて空改行を入れるようにすれば、このようにすべての段落にアンカーを付けることができるわけです。_↓__↓_サブタイトル(2)_↓__↓_   
+ 　行頭の空白を入れないとサブタイトルになるので注意しましょう。_↓_
+   
+********
+
+上の例は以下のように展開されます。ポイントは**行頭の空白**ですね。
+
+********
+
+[2001-08-30](./?date=20010830)
+----------
+
+### [■](./?date=20010830#p01)サブタイトル(1)
+
+[■](./?date=20010830#p02)このようにサブタイトルの下にすぐ空改行を入れてしまい、続く段落を空白で始めるようにすれば、サブタイトルと段落は別々のセクションになります。
+
+[■](./?date=20010830#p03)段落の間にすべて空改行を入れるようにすれば、このようにすべての段落にアンカーを付けることができるわけです。
+
+### [■](./?date=20010830#p04)サブタイトル(2)
+
+[■](./?date=20010830#p04)行頭の空白を入れないとサブタイトルになるので注意しましょう。
+
+********
+

data/doc/INSTALL-paas.md

@@ -0,0 +1,202 @@
+Install to PaaS
+=====================
+
+概要
+--
+
+tDiary-3.1.3 以降のバージョンでは tDiary を [Heroku](http://www.heroku.com) や [sqale](http://sqale.jp) のような PasS で動かすことが可能です。PaaS を利用することで、3.1.3 以前のバージョンで必要とされていた Apache のような http サーバーの用意や CGI として動作させるための環境設定を行う事なく、 tDiary を動かして日記を書くことが可能となります。
+
+必要なもの
+-----
+
+tDiary を PaaS で動作させるためには以下のツールが必要となります。
+
+  - [git](http://git-scm.com)
+  - Ruby 1.8.7 以降
+  - RubyGems 1.3.7 以降
+  - Bundler 1.0.0 以降
+
+また、よくわからない場合は Heroku が配布している [heroku toolbelt](https://toolbelt.heroku.com) を用いると簡単に上記のツールをインストールすることができます。
+
+動かし方 - Heroku の場合
+----
+
+tDiary の最新版を取得します。
+
+```
+git clone git://github.com/tdiary/tdiary-core.git
+```
+
+heroku コマンドを用いて Heroku でアプリケーションを作成します。なお、Heroku のアカウント作成方法は本ドキュメントでは省略します。tDiary のルートディレクトリ(Gemfile が存在する箇所) で以下のコマンドを実行します。
+
+```
+% cd tdiary-core
+% heroku apps:create [アプリケーション名]
+```
+
+アプリケーション名には mydiary など任意の名前を英数字で入力します。続いて、Heroku 専用の作業ブランチを作成します。
+
+```
+% git checkout -b deploy
+```
+
+作業ブランチで Heroku で動かすために必要な設定ファイルをコピーします。
+
+```
+% cp misc/paas/heroku/* .
+```
+
+続いて .gitignore の 2 行目の .htpasswd と 9 行目の tdiary.conf を削除します。
+
+日記更新時に必要となるユーザー名とパスワードを保存する .htpasswd ファイルを作成します。この情報は重要なので、外部には公開しないでください。
+
+```
+% rake auth:password:create
+```
+
+ここまでの変更内容を deploy ブランチにコミットし、Heroku にアプリケーションを転送します。
+
+```
+git add .
+git commit -m "deploy"
+git push heroku deploy:master
+```
+
+これで http://mydiary.herokuapp.com にアクセスして日記を書くことができます。
+
+動かし方 - sqale の場合
+----
+
+tDiary の最新版を取得します。
+
+```
+git clone git://github.com/tdiary/tdiary-core.git
+```
+
+sqale.jp にアクセスして新しいアプリケーションを作成します。作成後にアプリケーションの URL を git のリモートリポジトリに追加します。tDiary のルートディレクトリ(Gemfile が存在する箇所) で以下のコマンドを実行します。
+
+```
+% cd tdiary-core
+% git remote add sqale ssh://sqale@gateway.sqale.jp:2222/[username]/[application].git
+```
+
+username と application の値は別途読み替えてください。続いて、sqale 専用の作業ブランチを作成します。
+
+```
+% git checkout -b deploy
+```
+
+作業ブランチで Sqale で動かすために必要な設定ファイルをコピーします。
+
+```
+% cp misc/paas/sqale/* .
+```
+
+続いて .gitignore の 2 行目の .htpasswd と 9 行目の tdiary.conf を削除します。
+
+日記更新時に必要となるユーザー名とパスワードを保存する .htpasswd ファイルを作成します。この情報は重要なので、外部には公開しないでください。
+
+```
+% rake auth:password:create
+```
+
+dot.env ファイルを .env にリネームして、データベースの接続情報を記入します。データベースの接続情報は sqale のアプリケーションダッシュボードから参照してください。接続情報は以下の形式で記入します。
+
+```
+DATABASE_URL=mysql2://username:password@hostname/database
+```
+
+sqale では javascript や css ファイルを作業ディレクトリの public/assets 配下に置く必要があります。以下のコマンドを実行して対象のファイルをコピーしてください。
+
+```
+rake assets:copy
+```
+
+ここまでの変更内容を deploy ブランチにコミットし、Heroku にアプリケーションを転送します。
+
+```
+git add .
+git commit -m "deploy"
+git push sqale deploy:master
+```
+
+これで http://application-username.sqale.jp にアクセスして日記を書くことができます。
+
+### サーバーの選択
+
+Sqale用の`Procfile`（`misc/paas/sqale/Procfile`）ではThinというサーバーを設定していますが、このファイルを書き換えることで他のサーバーでtDiaryを動かすこともできます。
+指定できるサーバーと設定方法の詳細は、Sqaleの[マニュアル](https://sqale.jp/support/manual/change-web-server)を参照してください。
+
+また、SqaleデフォルトのUnicornで動かしたい場合は、`Procfile`を削除してください。
+
+```
+git rm Procfile
+```
+
+独自のテーマファイルを使う方法
+----
+
+Heroku で自作や tdiary-theme に含まれるテーマファイルを用いるには、deploy 対象としてテーマファイルを登録し、Heroku に転送する必要があります。
+
+tdiary-core の deploy ブランチに切り替えます。
+
+```
+git checkout deploy
+```
+
+テーマファイルをコピーし、deploy 対象として登録します。
+
+```
+cp -rf ~/tdiary-theme/gustav theme
+git add .
+git commit -m "add theme file"
+```
+
+Heroku にファイルを転送します。
+
+```
+git push heroku deploy:master
+```
+
+これで tDiary on Heroku の設定画面よりコピーしたテーマファイルを選択できるようになります。
+
+memcache アドオンを使う方法 - Heroku の場合
+----
+
+Heroku で アドオンの追加・削除を行うことが出来るユーザーは memcache アドオンを使うことで、より高速に日記キャッシュデータを扱えるようになります。tDiary on Heroku で memcache アドオンを使う方法を以下に解説します。
+
+tdiary-core の deploy ブランチに切り替えます。
+
+```
+git checkout deploy
+```
+
+heroku コマンドを用いて memcache アドオンを有効にします。
+
+```
+heroku addons:add memcache
+```
+
+Gemfile の以下の行を有効にします。
+
+```
+gem 'dalli'
+```
+
+tdiary.conf を以下のように変更します。
+
+```
+# require 'tdiary/io/cache/file'
+# To use memcache addon
+require 'tdiary/io/cache/memcached'
+```
+
+この状態を Heroku に反映させます。
+
+```
+git add .
+git commit -m "enable memcache"
+git push heroku deploy:master
+```
+
+git push コマンドが完了すると memcached をキャッシュの保存先とした tDiary が利用可能となります。