説明
プラグインは、Ruby そのものです。tDiary 等と同じ考え方です。ただし、
- ローカルで使用することを前提
- TaskPrize から使用することを前提
ということで、いわゆるセキュリティー関係については何も考慮していません。 *1
*1 というか、そもそも、それに値するスキルを持ち合わせていない(^^;)
プラグインの仕組み
プラグインの設置は以下の2つの方法があります。
- plugin フォルダに *.rb ソースを置く
- 対象となるTPZプロジェクトのプロジェクトフォルダ文書に記述する
plugin フォルダ
単純に、 ho.rb スクリプトが置かれているフォルダに plugin フォルダがあれば その中の *.rb を無条件に読み込みます。 一般的には、ho.rb は、TaskPrize インストールフォルダ下にあるユーザーフォルダのScriptフォルダになります。
プロジェクトフォルダ文書
わざわざエディタを起動してプラグインを作成するのが面倒な場合があります。 そんな時には、プロジェクトファイルのトップフォルダに %plugin% という文書を作成して、 その文書にスクリプトを作成してください。 plugin フォルダの後に読み込むので、書き換えも可能となります。
使い方
プラグインのテストを実行する。
・{{'<br>'}} ・・単純に htmlを埋め込むことを期待している ・{{sumi "取り消しプラグイン"}} どんな感じ? ・・%plugin%文書にいれたプラグイン ・{{rb "漢字","かんじ"}} ・・%plugin%文書にいれたプラグイン
- 単純に htmlを埋め込むことを期待している
- 取り消しプラグイン どんな感じ?
- %plugin%文書にいれたプラグイン
漢字 - %plugin%文書にいれたプラグイン
プラグインの使用範囲
プラグインは、一応、どこにあっても使えるようになっています。
- アイテムのタイトル
- 文書のタイトル
- 文書の中
よって、単語展開を容易に行えると思います。
ただし、プラグインのネストは出来ませんので注意してください。
プラグインの使用上の注意
プラグインは、ruby のソースとして解釈させます。 よって、エスケープシーケンス文字「\」の扱いには注意願います。 \ を表示させたい場合、\\ としてください。
例)
{{'エ\ス\\ケ\\\ー\\\\プ文字に注意'}} {{"エ\ス\\ケ\\\ー\\\\プ文字に注意"}}
実行結果*1
エ\ス\ケ\\ー\\プ文字に注意
エス\ケ\ー\\プ文字に注意
逆に、そうだからこそ、
{{"こんにちは\nお元気ですか"}} {{"こんにちは\"山田\"さん"}}
こんにちは お元気ですか
こんにちは"山田"さん
ということも可能になるわけですから。 *2
@doc_header と @doc_footer について
各種プラグインを作成していると、文書の先頭や末尾に色々と情報を付加したくなります。 しかし、いちいち本文に
{{plugin}}
と記述するのは面倒です。
ということで、
- @doc_header
- @doc_footer
この2つの変数は、直接 ho.rb に埋め込んであります。 よって、何らかのプラグインの結果を埋め込みたい場合には、 下記のように定義することで結果を埋め込めます。
@doc_header = <<EOT <div class="doc_header">#{@navi} <small>#{@doc_navi}</small></div> #{plugin1} #{plugin2} #{plugin3} EOT @doc_footer = <<EOT #{plugin4} #{plugin5} #{plugin6} <div class="doc_footer">#{@navi}</div> EOT
文書中のプラグインとの連携を行うようなプラグインでも、 それなりに可能なようになっています。
具体的な例は、fnプラグインを参照願います。
pre
この文書はwiki記法(+SunokoDoc)で書いています
いわゆる <pre> 〜</pre> 出力する方法はいくつかあります。 また、この <pre> を行う場合には
- SunokoDoc
- wiki(HikiDoc)
かどうかを意識しておく必要があります。
SunokoDocの場合
SunokoDocの如く、 基本的にはHikiDocです。しかし行頭インデントを可能にしている関係上、 Wiki の特徴である、 行頭スペース は <pre> するということは出来ません。 よって、<pre> したい場合には、明示的に <<< 〜 >>> で挟む必要があります。
例1)<<< 〜 >>> で挟む方法
テキスト
<<< SunokoDocはHikiDocとほぼ同じです。 しかし、行頭スペースによる <pre> はできません。 >>>
表示
SunokoDocはHikiDocとほぼ同じです。 しかし、行頭スペースによる <pre> はできません。
例2)プラグインによる方法
プラグイン
{{pre 'text'}}
を用意してあります。これを用いることでも <pre> は可能です。
標準的な書き方
テキスト
{{pre 'SunokoDocはHikiDocとほぼ同じです。 しかし、行頭スペースによる <pre> はできません。'}}
表示
SunokoDocはHikiDocとほぼ同じです。 しかし、行頭スペースによる <pre> はできません。
プラグインは複数行に渡って書くことが可能です。
ヒアドキュメントを用いた書き方
プラグインは複数行に渡って記述することが可能なので、 あまり必要性は感じないかもしれませんが、 Rubyのヒアドキュメントを用いた方法も可能です。
テキスト
{{pre <<PRE SunokoDocはHikiDocとほぼ同じです。 しかし、行頭スペースによる <pre> はできません。 PRE}}
表示
SunokoDocはHikiDocとほぼ同じです。 しかし、行頭スペースによる <pre> はできません。
HikiDocの場合
基本的には前出の SunokoDoc と同じです。 ただし、HikiDoc の方がより柔軟に作成可能です
行頭スペース(又はタブ)による方法
一般的にWiki記法の場合、行頭スペースにて <pre> を判断しています。 HikiDoc ではそれに加えて、行頭タブでも <pre> 可能となっています。
<<< 行頭にタブがあります これは2行目です >>>
行頭にタブがあります これは2行目です
SunokoDoc と HikiDoc の違い
プラグインを用いた方法では両者に大きな違いが発生します。 HikiDoc は、行頭スペースを1つみて判断しています。よって、複数ある場合には、 <pre>中でもスペースが有効になります。 対し、SunokoDoc では、通常の文章に行頭空白を許可している関係で、 そこまで賢いルーチンで作成してありません。複数のスペースがあっても、 表示される <pre> は、全て先頭に詰まって表示される場合があります。
テキスト
{{pre <<PRE SunokoDocはHikiDocとほぼ同じです。 しかし、行頭スペースによる <pre> はできません。 PRE}}
HikiDocの場合の表示
SunokoDocはHikiDocとほぼ同じです。 しかし、行頭スペースによる <pre> はできません。
SunokoDocの場合の表示
SunokoDocはHikiDocとほぼ同じです。 しかし、行頭スペースによる <pre> はできません。
このように先頭が詰まってしまいます。
★よって、SunokoDocでは <<< >>> で挟む方法を推奨します。
toc
目次プラグイン
ソースコメントより引用
# {{toc('item_id', level, doc }} # item:目次のトップレベルとなる TPZ の message_id # itemを省略した場合、html 出力の選択されているアイテム全て # デフォルトは nil # level:item以下、どの階層までの目次を作成するかを指定 # itemと同階層のアイテムは level = 1 とする。 # level = 0 の場合は、item 以下全てのアイテムの目次を作成 # level = 1 の場合は、item と同階層のアイテムのみの目次を作成。 # 具体的には子(children)アイテムのみ。 # 自分自身のアイテムは目次化されない。 # また、システム変数 @folderprint_all は無視する。 # doc:文書も目次に入れるかの判定 # doc = false 文書は目次に入れない(デフォルト) # doc = true 文書も目次に入れる # # {{doctoc}} とすればその文書内のみの目次を作成。 # 文書内では、<h1>〜<h6>を見出しにする。 # # # # 2008030511585008827@1214510797115.TPZ # 数字部の長さは一定していないので、正規表現は以下とする # /[\d]{15,}@[\d]{10,}\.TPZ/ #
システム変数 @folderprint_all による制御
システム変数 @folderprint_all によりその出力は異なります。 これは、html出力するアイテムと同じパラメータを使用しているためです。 出力されるアイテムがないのに目次だけあるのは不自然なために、あえてそのようにしています。
- @folderprint_all = true の場合
- フォルダ以下のアイテムも全て出力。ただし、level = 1 の場合は無視される。
- @folderprint_all = false の場合
- フォルダ以下のアイテムは出力しない
文書の扱い
TaskPrizeの大きな特徴として、アイテムごとに文書を複数持つことが出来ます。 この文書も目次に列記することが可能です。 具体的には toc プラグインの doc パラメータにより制御を行います。
- doc = true
- 文書のタイトルを目次に入れる
- doc = false
- 文書のタイトルは目次に入れない。デフォルト。
想定している使い方
全アイテムの目次を出力する場合
選択されているアイテムのみを出力する場合。
タイトルのみの目次 {{toc}}
タイトルのみの目次
文書を含めた目次 {{toc '',0,true}}
文書を含めた目次
- HtmlOut_for_TPZ
あるアイテム以下の目次を出力する場合
例えば、章毎の目次を各章のトップに書きたい場合を考えます。 そういう場合を想定しています。
- 選択されているアイテムではなく、あくまでも指定されているアイテム以下の目次を出力するので注意。一般的にはあまり意識する必要はありません。
このアイテムを指定した場合 {{toc "#{@ItemMessageId}",0,true}}
このアイテムを指定した場合
システム変数 @ItemMessageId ではなく、直接、TPZのメッセージIDを指定しても良い。
{{toc "2008031017045104360@1214510797115.TPZ",0,true}}
同階層のアイテムのみを目次化する場合
プロジェクト全体の出力は、システム変数 @folderprint_all で制御できますが、 全体としてはフォルダ以下も出力したいが、あるところでの目次は、 同階層のアイテムだけを出力したい、という場合は以下で可能です。
親アイテムを指定した場合 {{toc "#{@ParentMessageId}",1,true}}
親アイテムを指定した場合
文書内のみの目次を埋め込む場合
文書内のみの目次を作ります。文書内では、<h1>〜<h6>を見出しにします。
目次 {{doctoc}}
目次
@doc_header に記述しておくことも可能
@doc_header = <<EOT <div class="doc_header">#{@navi} <small>#{@doc_navi}</small></div> #{doctoc} EOT
補足
目次を作る際に、TaskPrize のメッセージIDを使用しています。 通常、このメッセージID をTaskPrizeの文書でクリックすると、そのアイテムにジャンプします。 当然、HtmlOut_For_TPZ で作成している文書でもそうしたい、というのが人情。
目次としては以下としています。(以下 Wiki記法で示します)
[[文書内見出し|#link(2008031014094003960@1214510797115.TPZ).1.h13]]
message_id を 括弧 #link( message_id ) で囲っています。
また、文書や、文書内見出しは以下で可能です。
[[文書|#link(2008031014094003960@1214510797115.TPZ).1]]
最後の .1 が、doc.index です。 よって、一旦リンクを作成してから文書を移動するとずれるので注意してください。
[[文書内見出し|#link(2008031014094003960@1214510797115.TPZ).1.h13]]
文書内見出しは、最後の h13 です。この h の後の番号は連番です。 HtmlOut_For_TPZ を実行した時点で決定されます。
なお、toc を使用しなくても、標準で name 属性を アイテム、文書 につけていま す。なので、プラグイン等で自由にリンク操作が可能となっています。
さらに補足
普通に文書間のリンクを作成するには、後述の link を利用すると良いでしょう。
fn
脚注プラグイン
いわゆる脚注プラグイン。プラグインとしては
- fn(text, mark)
- fn_put
- fn_put_forget
の3つで成り立っています。
fn(text, mark)
脚注プラグイン本体。この fn にて脚注を作成します。 mark に何かしら指定すれば、それが適用されます。
fn_put
fn で溜め込んだ脚注を書き出します。 fn_put が書かれた位置に、それ以前にfnで書かれた脚注を書き出します。
fn_put_forget
プラグインを2つに分けることで、どうしても、fn_put を忘れてしまいます。 ということで、もしも本文中に fn_put が無かった場合の対策として以下を行っておくと幸せになれます。
%doc_conf% にて @doc_footer を以下のように定義。
@doc_footer = <<EOT #{fn_put_forget} <div class="doc_footer">#{@navi}</div> EOT
使い方
以下の例を参照。
脚注テスト1 {{fn "テスト1"}} 脚注テスト1 {{fn "テスト2"}} 脚注テスト1 {{fn "テスト3","脚注"}} {{fn_put}} 脚注テスト2 {{fn "テスト4"}} 脚注テスト2 {{fn "テスト5"}} 脚注テスト2 {{fn "テスト6"}} {{fn_put}}
脚注テスト1 *1
脚注テスト1 *2
脚注テスト1 脚注3
脚注テスト2 *1
脚注テスト2 *2
脚注テスト2 *3
スタイルシート
スタイルシートを適宜埋め込んであります。 参考まで。
/* footnote */ div.body span.footnote { vertical-align: super; font-size: 70%; } div.footnote { font-size: 75%; border-style: solid; border-color: #ddf; border-width: 1px 0px 0px 0px; padding: 1em 3em 1em 3em; margin : 2em 3em 1em 3em; } p.footnote { margin: 0.5em; padding: 0em; text-indent : -1.5em; }
link
image
イメージプラグイン
いわゆるイメージプラグイン。画像等のリンクに使用します。
select_image_link ファイルリンクを取得し、Wiki記法変換する で入力された形式を html に変換することを目的にしています。
画像ファイルの場合
{{image 'images/1.JPG','1.JPG','1.JPG','photo'}}
上記を
<img class="photo" src="images/1.JPG" alt="alt 1.JPG" title="title 1.jpg">
と変換するようにする。
urlファイルの場合
[[Google|http://www.google.co.jp/]]
これは、通常のリンクそのもの よって、通常の画像リンクを作成したい場合、画像のurlリンクを行っておけばリンク可能。
[[http___sunoko.s33.xrea.com_x_HtmlOut_for_TPZ_images_1.JPG|http://sunoko.s33.xrea.com/x/HtmlOut_for_TPZ/images/1.JPG]]
pbb
印刷時強制改行プラグイン
TPZ 文書中にて、強制改行を行いたい場所で
{{pbb}}
と埋め込んでおくと、その直前で強制改ページを行います。
仕組みは、改行したい箇所に以下のhtmlを埋め込んでいるだけです。 CSS がなくても動作させるために、あえてこのようにしています。
<!-- 強制改ページ--> <STYLE type="text/css"><!-- .pbb { page-break-before: always; } --></style> <div class="pbb"></div>
以下、プラグインソースそのもの
# pbb: 印刷時強制改行plugin # # 任意の位置の印刷時の強制改ページを行う def pbb r = <<EOT <!-- 強制改ページ--> <STYLE type="text/css"><!-- .pbb { page-break-before: always; } --></style> <div class="pbb"></div> EOT end