Help : k-index
注意!
この文章は多分に古い文章を含んでいる。
近い将来改訂される予定である。
この文書について
文書の基本構造
- 文書はテキストファイルであり、文字コードはshift-JIS、改行コードはLFで記述される。
ただし、これは将来変更される可能性がある。
- ファイル名は任意である。
- 構造の基本単位は「行」である。行は改行コード及び終端文字を含まない。
- 「行」には、機能的な意味を持つ行(機能行)と、機能を持たない行(非機能行)がある。
機能行には、下記のものがある。
- タイトル : 文書のタイトルを示す。文書の第1行目(同行に:が存在すればそれ以降の内容)である。
- グループ : 内容のグループを示す。@で始まる。
- スタイル指定 : 主に項目内の表現を指定する。-で始まり-で終る。
- 非機能行は、その直前に現われた機能行に所属すると見做される。
- 文書にはタイトルが存在しなければならないが、それ以外の存在は任意である。
- 機能行の直前に存在する1つ以上の連続した空白行は、単に無視される。
- リンク指定は、機能行、非機能行の内容の任意の位置に置くことができる。
- リンクは、大括弧により表現される。
例えば、[MemoDeposit]は、「MemoDeposit」をタイトルとする文書へのリンクとなる。
機能行の定義
ex. MemoDeposit
ex. :MemoDeposit
ex. MemoDeposit:k-index
- タイトルは、以下のように定義される。
タイトル行に:が含まれる場合は、:以降の文字列の前後の空白文字を取り除いたもの。
:が含まれなければ、タイトル行内容の前後から空白文字を取り除いたもの。
タイトルは空白を含んでも良いが、連続した空白は全て単独の空白文字と見做される。
タイトルは@,*,!で始まってはならない。またバックスラッシュと|を含んではならない。
一行目にコロンがあれば、タイトルはそれ以降の内容となる。
- 空間名は、以下のように定義される。
タイトル行に:が含まれる場合は、:以前の文字列の前後の空白文字を取り除いたもの。
タイトル行が:で開始されている場合は、無名空間に属すると見做される。
:が含まれていない場合も、無名空間に属すると見做される。
命名の詳細については名前空間の項を参照。
- グループ行の内容は、@を除いた行内容の前後から空白文字(\s\t)を除いたものである。
グループ内部に空白文字は存在してもよいが、連続した空白は単独の空白と見做される。
- 例えば「@ 1st case」グループは、[1st]と指定される。
- 内部に@*\は単独で存在してはならない。
エスケープとして\@, \*, \が用意されるが、基本的に使用しないことが望ましい。
- アイテム行の内容は、*を除いた行内容の前後から空白文字(\s\t)を除いたものである。
アイテム内部の文字列に制限はない。
アイテム内部の連続した空白は、そのまま連続した空白と見做される。
- ブラケット([])を表示する場合、\[ \] といった具合にバックスラッシュでエスケープする。
また、コード中のブラケットを表示する場合は、-code, nolink-を使用することが望ましい。
- スタイル指定は、-で始まり-で終る行である。
内容は規定のパラメータであり、それ以外は無視される。
パラメータは、データ形式を示すものと、リンク機能の制限を示すものが定義される。
データ形式は、「code」「html」「list」「table」「normal」「quote」。
リンク機能は、「linked」「nolink」。
これらは、「-code, nolink-」という具合に列挙して指定する。順序は不問。
いずれか一方のみを変更した場合、もう一方の設定はそのまま維持される。
例えば-code, nolink-の後に-html-と指定した場合、リンクは-nolink-のままとなる。
スタイルは非機能行のみに影響し、機能行の出現によってリセットされる。
デフォルトのスタイルは、-normal, linked-である。
それぞれの項目についての詳しい内容は「スタイル指定」参照。
リンクの定義
- リンクは、別の文書またはウェブページを指定するために使用される。
例外として、略語、註釈(脚注)も指定できる。
- リンクはブラケットによって明示される。
- URLの直接記述はリンクとして機能しない。必ずブラケットを用いること。
- ブラケット中は|で区切られ、その前後で役割りが異なる。
- [A|B]とすると、AはBの別名と見做され、表示はAに、実際のリンクはBになる。
例えば、[KEdit|KEdit for MacOSX]なら、これは[KEdit for MacOSX]と同義である。
- リンクには、複数の指定方法がある。
指定方法の詳細
- [title {param}], [title@group {param}], [@group {param}]
指定されたタイトル(及びグループ, アイテム)の文書にリンク。文書は存在しなくても良い。
指定されたタイトルの文書がなければ文書を新規に作成する。
指定されたタイトルはあるがグループ以下がない場合、特になにもしない。
タイトルが省略された場合、その文書内のグループ、アイテムを探す。
グループが省略された場合、文書全体からアイテムを探す。
itemへのリンクは、そのitemの所属するグループへのリンクで代用する。
グループがなければ、単にドキュメントへのリンクとする。
外部文書のグループに対するリンクは、基本的に推奨されない。(内部的には推奨される)
paramは省略可。内容のない{}は許可されない。
{}は、[]の末尾に出現した時のみパラメータと見做される。
(即ち、\[\s*(.+)\s*\{([^{}])+\}\s*\] に合致したときのみ$2をparamと見做す)
paramの内容は括弧({})の使用を除き制限はない。
paramの内容は、{}に挟まれた文字列の前後から空白文字を削除したものである。
- [url]
内容がURLと判断された場合、urlを内容としてurlをリンク。
現在のところ、URLはhttp://, ftp://, mailto:のうちのいずれかで開始すること。
- [!string]
stringを註釈(脚注)と見做す。
"["と"!"の間に空白を含んではならない。
註釈は空白を含んでも良い。(エスケープする必要はない)
実装としては、ページ下部或いはグループ下部に纏めて表示される。
- [!!string]
stringを非表示の註釈と見做す。
項目を記述した日付など、表示しなくても良いが後に参照したい内容などを記述する。
HTML文書内ではコメント<!-- string -->として記述される。
- 上記に合致しない場合
リンクを生成せず、エラーを示す文字列を挿入する。
Dangling Link
リンク指定したタイトルを持つ文書が存在しない場合、そのリンクをDangling Linkと呼ぶ。
Dangling Linkはリンク指定の誤りとは見做されない。
実装上、新規文書作成の方法として用いられる。
スタイル指定
スタイル指定は、文書内容には直接関与しない。
主にウェブ表示用の機能である。
htmlスタイルを除いて、htmlで参照表記が必要なものは全て表示時に自動変換する。
スタイル指定行は、ブラウザなどには表示されない。
空白行と見做されるのではなく、存在しない行と見做される。
テキスト内容
- normal
行の先頭に存在する連続した空白文字\s\tを省略する。
実装としては、可変幅フォントが指定される。
各行は単なる文と見做される。
デフォルト動作。
- code
行先頭の空白が無視されない。
実装としては、等幅フォントが指定される。
code_c, code_ruby, code_perl, code_applescriptがcodeと同じ指定子として定義される。
こちらは、将来キーワードの色分け表示などに対応する可能性がある。
内容に即した指定子を指定することが望ましい。
先頭の空白は、\sが?に、\tが連続した?(標準は2回)に置換して表示される。
この指定子だけではブラケットを表示できないため、同時にnolinkも指定する必要がある。
- html
指定以降の非機能行をhtmlと見做し、内容をHTML形式で表示する。
htmlの形式は特に指定されないが、XHTML Basicに準拠していることが望ましい。
htmlの機能文字(&や<>など)は自動変換されないため、予め参照記法で記述する必要がある。
これはセキュリティの弱点となりうるので注意を要する。対応方法は現在未定。
(初期設定によりhtmlモードの禁止が可能になる予定)
- list
「*」で始まる行があれば、その行以降はリストと見做される。
空白行がある場合、自動的にnormalに復帰する。
「*」で始まらない行は、その直前の「*」行に所属すると見做される。
ネストはできな｢。
- table (未実装)
comma-returnまたはtab-return区切りでテーブル内容を表わす。
一行目及び一列目はそれぞれ見出しﾅある。
{0, 0}の項目がキャプションと見做され、逆にテーブル内は{0, 0}が省略される。
- quote
引用を表わす。ブロック要素として実装、表示されることが望ましい。
典型的には、<blockquote>で実装される。
引用元を表現する手段は提供されない。
引用は、quoteが指定されてから次のスタイル(または機能行)が出現するまでの範囲である。
リンクの扱い
- linked
非機能行のリンク指定が有効となる。デフォルト動作。
ブラケットは非表示となる。
- nolink
リンク指定がキャンセルされ、ブラケットはその機能を失なう。
ブラケットはそのまま表示される。
画像及びバイナリ (未実装)
- バイナリ及び画像は、文書と拡張子違いで保存されるのみ。
一般のk-index文書と異るところはない。
拡張子が同じ画像やバイナリファイルがその文書に所属すると見做される。
名前空間
- 名前空間とは、文書のタイトルリンクに一定の制限を加えるものである。
- 同じ名前空間に存在する文書間では、リンクはタイトルのみで指定される。
- 異なる名前空間に存在する文書間では、リンクはタイトルと空間名で指定される。
- 空間名(NameSpace)は、タイトル(TITLE)の前にセミコロンを挟んで置かれる。
ex. NameSpace:TITLE, MemoDeposit:k-index
- 空間名はタイトルに含まれない。
- デフォルトの空間名は長さ0の文字列である。これを「無名空間」と呼ぶ。
- 「:TITLE」と「TITLE」は、いずれも無名空間に属するという意味である。
- 文書の一行目をタイトル行とは別に「空間タイトル指定行」とも呼ぶ。
- リンクによる新規文書生成は、名前空間を越えて可能である。
- 例えば、NameA:index文書上で[NameB:index]リンクを指定すると、NameB上にindexが生成される。
- NameA:index内では、
- [NameA:title]と[title]
は全く同じ意味であるが、[:title]は無名空間上のtitleを示す。
その他
一般に、:indexがグローバルインデックスとして使用される。