※他のドキュメントは Markdown から生成していますが、mok のドキュメントは Markdown に存在しない機能を使っているため、画像等のリンクを除き mok フォーマットから mok2html で生成した HTML をそのまま出力しています

mok ドキュメントフォーマット

  • author:がりん <garin54@gmail.com>
  • create:2013-12-12
  • update:2015-04-17
  • publisher:garin.jp
  • version:1.0.3
  • tag:mok

1.はじめに

1.1.mok とは?

mok (モク)(旧名:raf) はプレーンなテキストで記述するドキュメントフォーマットの規格です。
mok はアプリケーションのインストールマニュアルやリファレンス、ブログなどのドキュメントを簡単に書け、そのドキュメントを様々な形式に変換できることを目的としています。 (この文章自体も mok で書いています )。

純粋なテキストフォーマットですが、文章を作成するのに必要な「章立て」「文字修飾」「箇条書き」「表組み(テーブル)」「注釈(footnote)」「振り仮名(ruby)」「マルチメディア(画像・音声・動画)」「リンク」「校正」「整形済みテキスト」「引用」 などの機能をサポートしています。どのような機能が使えるかは後述の「mok リファレンスマニュアル」を確認してください。

1.2.ドキュメント更新履歴

v1.0.4 (2015-05-xx)
* mok-parse v0.4.0 の内容に追従
v1.0.3 (2013-12-31)
mok v1.0.4 に追従。いくつかの説明を修正。
v1.0.0 (2013-12-12)
プロジェクト名を raf(らふ) から mok(モク) に変更して、mok の書式に内容を修正。

1.3.mok の特徴

1.3.1.簡単な記述フォーマット

mok は、記述者の思考を妨げないことを1つの目標にしています。
そのため、mok には HTML/XML のドキュメトタイプの宣言や、改行の指定、Wiki のタイトル見出しなどの"おまじない"をなるべく少なくしています。
たとえば次の例は完全に正しい mok ドキュメントです。

この文章は、
正しい mok のフォーマットです。

これを HTML で書くと冗長になってしまいます。

<!DOCTYPE html>
<html>
  <head>
    <title>mok ドキュメント</title>
  </head>
  <body>
  <h1>mok ドキュメント</h1>
  <p>
    この文章は、<br \>
    正しい mok のフォーマットです。<br \>
  </p>
  </body>
</html>

このように mok は素直な書き方で文章を書くことができます。

1.3.2.単語区切りのない言語にも適した文字修飾

多くのマークアップ言語は英語圏を中心に開発されてきました。そのため、英語や多くのヨーロッパ圏の言語のように単語をスペースで区切る言語に向けて機能が拡張されています。
たとえば wiki 記法の1つである textile の強調文字は、スペースで区切られた単語を *(アスタリスク) 囲んで「This is *Strong*」のように記述します。

このため、日本語のように単語区切りを行わない言語では、複数の文字修飾を指定するとどの指定がどの文字を修飾するのかがわかりづらくなってしまいます。
以下に textile で日本語の文を強調する例を示します。

// textile で日本語の文を強調する
...*中心*となる*構造化*ドキュメント*の*作成*に適しています。

実は、上の例では開始記号 (*)と終了記号 (*)の数が正しくないのでエラーになります (どこでエラーになるかわかりますか?)。

mok では、文字修飾として2重カッコ "((" と "))" で単語の前後を囲むという記述方法を採用しています *1
さきほどの文章を mok で書き換えます。

// mok で日本語の文を強調する
  ...((*中心*))となる ((*構造化*))ドキュメント*))の ((*作成*))に ((*適して*))います。

「((*構造化*))」の後の「ドキュメント」に開始タグ「((*(」がないのがわかるでしょうか?

1.3.3.ドキュメントの中で変数が使える

1つのドキュメント内で変数の定義と参照を行うことができます。
((@変数名=内容@)) で定義し ((@変数名@)) で参照します。
長い正式名や、URL へのリンク、変更される可能性のある文字列を表現するのに便利です。
くわしくはリファレンスの「変数」を参照してください。

1.3.4.シンプルなテーブル記法

mok はテーブル記法を持っています。
テーブルは要素ごとに |(パイプ) で囲みます。文字列の前後に * を付けるとヘッダになります

// mok でのテーブルの記述
| *ヘッダ1* | *ヘッダ2* |
| カラム1   | カラム2   |

センタリングや左右寄せ、複数行カラムなどはサポートしていません。

1.3.5.ドキュメント内プログラム

mok ではドキュメントの中に Ruby の erb 機能を使って、文章を他フォーマットに変換する時にプログラム実行することができます。
例えば、変換した時刻を記録するには以下のような文章を書いておきます。

最終更新時刻: <%%= Time.now %>

すると、変換後のフォーマットでは Time.now プログラムの実行結果が記述されます *2

最終更新時刻: <%= Time.now %>

Ruby プログラムをドキュメントに埋め込む erb の機能については西山さんの「るびま0017号:標準添付ライブラリ紹介 【第 10 回】 ERB」に詳しく書かれています。

※mok2html ではデフォルトでオフに設定されているので、--erb オプションで有効にします。
※Ruby プログラムは Ruby の セーフレベル4 で動作します。そのためファイルの操作や require などは禁止されています。

2.mok を使う

mok は文章を書くためのフォーマット規格なので特別はプログラムは不要ですが、プログラムから mok を解析するためのパーサや、mok から他のフォーマットへ変換するためのコマンドを Ruby の gem パッケージで配布しています。

$ gem install mok

mok パッケージはメタパッケージでいくつかのパッケージを含んでいます。

mok-parser
mok の racc パーサ。
mok ドキュメントを解析して、変換コマンド用の機能を提供します。
mok2html
mok から HTML 形式に変換するためのユーティリティ。
マニュアル:mok2html
mok2md(作成中)
mok から MarkDown 形式に変換するためのユーティリティ。

3.mok リファレンスマニュアル

ここは mok のリファレンスマニュアルです。
mok で文章を書くはこのリファレンスを確認にしてください。

出力例として mok2html の変換結果を載せています。

3.1.対象バージョン

このリファレンスでは、下記の mok を対象とします。
ほかのバージョンでは使用できない機能や、動作の異なる場合があります。

  • mok-mok_version
  • mok-parser-mok-parser_version
  • mok2html-mok2html_version

※mok パッケージにその他のパッケージが同梱されています。

3.1.1.後方互換について

mok フォーマットの開発ステータスは 「eperimental (試験中)」 です。
2015年後半にリリース予定の mok-parser v1.0.0 (mok v2.0.0) までの間はバージョン毎の後方互換は保証されません。

3.2.拡張子・文字コード

拡張子
mok ドキュメントの拡張子は「.mok」です。
文字コード
文字コードは UTF-8 (BOM*3なし) のみをサポートします。EUC や Shift-JIS など他の文字コードはサポートしていません。

3.3.段落・改行・コメント

3.3.1.段落

先頭を空白文字ではなく、また記号を指定せずに書きはじめると「段落」になります。
段落は次の空白行か記号付きの行まで続きます。

段落の入力例
ここは段落です。
このように続けて書くことができます。

空白行をあけると次の段落になります。
段落の出力例
<p>
ここは段落です。
このように続けて書くことができます。
</p>

<p>
空白行をあけると次の段落になります。
</p>

3.3.2.改行

段落内の改行は見た通りのまま改行として扱われます。
HTML の<br />のような特別な記号は必要ありません。

入力例
ここは段落です。
このように続けて書くことができます。
行末で改行するとそのまま改行して表示されます。
出力例
<p>
ここは段落です。<br />
このように続けて書くことができます。<br />
行末で改行するとそのまま改行して表示されます。<br />
</p>

3.3.3.コメント

行の先頭文字が「#(シャープ)」で始まる行はコメントです。行頭から行末までの1行がコメントになります。
コメントは変換ツール (mok2html, mok2md)で別の形式に変換するときに無視します *4

行頭以外の場所に「#」があってもコメントとして扱いません (行頭に「#」だけです)。また、行頭がスペースやタブであってもコメントになりません。

コメントの入力例
# この行はコメントです
この文章を記述 # ここはコメントではありません
  # 行頭がスペースの場合もコメントになりません
コメントの出力例
<p>
この文章を記述 # ここはコメントではありません<br />
# 行頭がスペースの場合もコメントになりません<br />
</p>

mok2html ではコメントは完全に無視されて HTML のコメントとしても残りません。

3.4.表題 (タイトル)

行頭が「=(イコール)」と半角スペースではじまる行は、そのドキュメントの表題 (タイトル)です。
表題はファイルの先頭 (かつ メタデータの後に) 1つだけ記述できます。

表題の入力例
= ドキュメントのタイトル
ここの文章を記述

※"=" と タイトルの間に半角スペースが必要です。

表題の出力例
<h1>ドキュメントのタイトル</h1>
<p>
ここの文章を記述
</p>

3.5.章立て

行頭が2つ以上の「=(イコール)」と半角スペースではじまる行は章立てになります。
章立ては「==」「===」「====」の3段階指定することができ、それぞれ「章 (==)」「節 (===)」「項 (====)」を表わします。

章立ては他のフォーマットに変換時に自動で「1.1.3」「1.2」のような通し番号が付きます。

章立ての入力例
= 表題
== 第1章
=== 第1章、第1節
=== 第1章、第2節
==== 第1章、第2節、第1項
== 第2章
=== 第2章、第1節
...
章立ての出力例
<h1>表題</h1>
<h2>1. 第1章</h2>
<h3>1.1. 第1章、第1節</h3>
<h3>1.2. 第1章、第2節</h3>
<h4>1.2.1 第1章、第2節、第1項</h4>
<h2>2. 第2章</h2>
<h3>2.1. 第2章、第1節</h2>
章立ての規則

章立ては、章→節→項 の順番で正しく指定する必要があります。
「章」の中で「節」を飛び越えて「項」を記述することはできません。

# これは間違った書き方
== 第1章
==== × 第1章、第1項 # 「節」を飛び越えて「項」を書こうとしているのでエラー

3.5.1.通し番号のない項目

行頭が「+(プラス)」と半角スペースではじまる行は通し番号のない項目になります。
通し番号のない項目は、章立ての順番に関係なく記述することができます。

通し番号のない項目の入力例
= 表題
== 第1章
+ 通し番号のない項目
=== 第1章1節
通し番号のない項目の出力例
<h1>表題</h1>
<h2>1. 第1章</h2>
<h5>通し番号のない項目</h5>
<h3>1.1. 第1章1節</h3>

※ 現在の mok2html では通し番号のない項目を h5 として扱います。

3.6.文字修飾

文字を強調・否定したり注釈やリンクを記述するには文字修飾記法を使います。
文字修飾は文字列の間を (( と )) に修飾機能ごとの記号を付けて囲みます。

たとえば強調文字の修飾記号は「*(アスタリスク)」なので ((* と *)) の間に強調したい文字列を記述するとその文字列を強調文字として認識します。

※文字修飾は引用テキスト・ルビ・テーブル (表組み) などの中では使用できません
※「文字修飾の無効化(verb)」を使うと修飾文字されている文字列を変換しないようにできます

3.6.1.強調(emphasis)

文字列を強調表示します。注意を促したい場合に使用します。

記述
((*強調*))されると ((*目立ち*))ます
表示
強調されると 目立ちます
HTML
<strong>強調</strong>されると<strong>目立ち</strong>ます

3.6.2.斜体(italic)

斜め文字を表示します。

記述
((_斜体_))は文字を((_ななめ_))にします
表示
斜体は文字をななめにします
HTML
<em>斜体</em>は文字を<em>ななめ</em>にします

3.6.3.否定(strike)

対象文字否定/訂正線 (横線)を引きます。

記述
((-否定-))
表示
否定
HTML
<del>否定</del>

3.6.4.振り仮名(ruby)

漢字や用語に振り仮名(ルビ)を追加します。
左に対象文字、右にルビを「|(パイプ)」で区切って記述します。

記述例
難しい((^漢字|かんじ^))
表示
難しい漢字(かんじ)
HTML
難しい<ruby><rb>漢字</rb><rp>(</rp><rt>かんじ</rt><rp>)</rp></ruby>

3.6.5.注釈(footnote)

文中に注釈を追加します。

記述
注釈は変換方法はツールによって異ります (([注釈はこのように表示されます]))
表示
注釈は変換方法はツールによって異ります *5
HTML
注釈は変換方法はツールによって異ります<a href='#mok-footnote-1-reverse'>*1</a>注釈はこのように表示されます

3.6.6.コード(code)

プログラムのコードなどに使います。

記述
(({sample = "str" if sample.nil? }))
表示
sample = "str" if sample.nil?
HTML
<code>sample = "str" if sample.nil?</code>

3.6.7.キーボード入力(kbd)

キーボードからの入力などに使います。

記述
((%keyboard input%))
表示
keyboard input
HTML
<kbd>keyboard input</kbd>

3.6.8.文字修飾の無効化(verb)

文字修飾を無効にします。文字修飾をしたくない文字列を囲むと文字修飾が無効になり記述したまま表示します。

記述
(('((*文字修飾無効*))'))

他のフォーマットに変換すると表示できなるなってしまうため、便宜上 () を全角で書いています。

表示
((*文字修飾無効*))
HTML
((*文字修飾無効*))

3.6.9.文字修飾の入れ子

文字修飾は原則として以下のように入れ子にすることができます (※注釈・ルビは除く)。

文字修飾の入れ子の例
((*強調だけ ((_強調と斜体_))*)) => <strong>強調だけ<em>強調と斜体</em></strong>

3.7.マルチメディア(画像・音声・動画)

(($ と $)) で囲まれた文字列はマルチメディアファイルとして扱います。
指定したファイルの種類はファイルの拡張子から自動で判別*6し、画像は画像、動画は動画として表示します*7
表示位置・サイズ変更 などは指定できません。

3.7.1.メディア毎の表示例

画像
記述
(($images/mok_media_sample01.jpg$))
表示

images/mok_media_sample01.jpg

imma さんがhttp://morguefile.comで公開しているDSC_0465aj.JPGを使用しています

音声
記述
(($audio/mok_media_sample03.wav$))
表示

あみたろさんがhttp://www14.big.or.jp/~amiami/happy/ で公開している音素材を使用しています。

動画
記述
(($move/mok_media_sample02.webm$))
表示

camendesign.comの "Video For Everybody" Test Page で公開している動画を使用しています。

不明な拡張子

不明な拡張子のファイルはファイル名をそのまま表示します。

記述
(($empty.nazo$))
表示
empty.nazo

3.7.2.マルチメディアのファイルベースディレクトリ

他のフォーマットに変換した時のメディアファイルを配置しておくディレクトリを指定することができます。
指定方法は変換ツールにより異なりますが、mok2html はコマンドラインか設定ファイルで指定が可能です。

$ mok2html --media_base_directory "/usr/local/media" $MOK_FILE

media_base_directory オプションを指定して変換を実行すると、マルチメディア記法(($..$))のファイルパスに /usr/local/media を付加します。

(('(($test.png$))')) #=> <img src="/usr/local/media/test.png">

メディアディレクトリの設定は URI, ルートディレクトリ、カレントディレクトリ 以外のローカルパスに対してのみ有効です。
※media_base_direcotry のデフォルト値が ""(空) です。

3.7.3.ベースディレクトリの変換

ベースディレクトリの変換リスト

media_base_direcotry オプションを /opt/mok/media と設定した場合、リンクの記述を次のように変換します。

分類 ドキュメントのパス 変換有無 出力するパス
ファイルのみ (($test.png$)) /opt/mok/media/test.png
相対パス (($images/test.png$)) /opt/mok/media/images/test.png
ルートディレクトリ (($/test.png$)) × /test.png
カレントディレクトリ (($./test.png$)) × ./test.png
URI(ファイルプロトコル) (($file://test.png$)) × file://test.png
URI(HTTP プロトコル) (($http://garin.jp/test.png$)) × http://garin.jp/test.png

ヒント:ファイルをカレントディレクトリ(./)から相対パスで記述しておくと、media_base_direcotry オプションの設定・未設定にかかわらず、相対パスで出力します。

3.8.整形済みテキスト

行頭を半角スペースを2つ空けると整形済みテキストになります。
記述された内容をそのまま表示し文字修飾も無効になります。
プログラムのソースコードの配置や、変換ツールに文字修飾を解釈されてくない場合などに使います(文章の引用には下記の「引用」構文を使ってください)。

整形済みテキストの入力例
__これは整形済みテキストです。
__整形済みテキストは、改行やスペースもそのまま表示します。
__「 (半角スペース4つ)」
__((*整形済みテキスト内では文字修飾されません*))

※ 便宜上 「_」 は、半角スペースを表わします。

整形済みテキストの出力例
<pre>
これは整形済みテキストです。
整形済みテキストは、改行やスペースもそのまま表示します。
「 (半角スペース4つ)」
((*整形済みテキスト内では文字修飾されません*))
</pre>

※garin.jp では整形テキストを google prettifyで再整形しているため、複数の半角スペースは1つにまとめて表示します。

3.8.1.整形済みの見出し

整形済みテキストに見出しを付けるには、行頭に「++」と半角スペースを置きます。
見出しは目次に登録されず整形済みテキストと同じ列にインデントされます。

整形済みテキストの見出しの入力例
++ 整形済みテキストの見出し
上記のタイトルは「整形済みテキストの見出し」です
整形済みテキストの見出しの出力例
<h6>整形済みテキストの見出し</h6>
<pre>
上記のタイトルは「整形済みテキストの見出し」です
</pre>

※ 現在の mok2html では整形済みの見出しは h6 として扱います。

3.9.引用

行頭を「>」と半角スペースを1つ空けると引用になります。

引用の入力例
> これは引用です。
> 他の人の書いた文章を文の中に引く時に使います。
> 引用では((*文字修飾*))が使えます。
引用の出力例
<blockquote>
これは引用です。
他の人の書いた文章を文の中に引く時に使います。
引用では<strong>文字修飾</strong>が使えます。
</blockquote>

3.10.箇条書き

mok の箇条書きには「記号付き」と「番号付き」の2種類があります。
箇条書きは入れ子にして階層を深くできます。
行頭記号付きと番号付きのリストを複合的に指定することはできません。

3.10.1.記号付き箇条書き

行頭が「*」と半角スペースではじまる行は箇条書きになります。

頭記号付き箇条書きの入力例
* item1-1
* item1-2
# 以下のように入れ子にすることもできます
  * item2-1
    * item3-1
頭記号付き箇条書きの出力
<ul>
  <li>item1-1</li>
  <li>item1-2
  <ul>
    <li>item2-1
    <ul>
      <li>item3-1</li>
    </ul>
    </li>
  </ul>
  </li>
</ul>

3.10.2.番号付き箇条書き

行頭に「(N)」まはた「N.」のような半角数字(N は半角数字)と記号の組合せと半角スペースで初まる行は数字付き箇条書きになります。
変換後は N の数字とは関係なく1から順番に添字されます。

番号付き箇条書きの入力例
(1) number of 1
(2) number of 2
(4) number of 4  # 添字を 4 にしても連番の3として処理される

# 以下の書式も可能
1. number 1
2. number 2
4. number 2
番号付き箇条書きの出力例

どちらの書式でも、以下のように表示されます。

<ol>
  <li>number of 1</li>
  <li>number of 2</li>
  <li>number of 4</li>
</ol>
箇条書きの後の改行

箇条書きの後の改行はインデント位置(空白の数)によって意味が異ります。

空白がない場合は、その箇条書を終了し、次の段落が続きます。

// 入力例 
* aaa
bbb

// 出力例
<ul>
  <li>aaa</li>
</ul>
<p>
bbb
</p>

インデント幅が同じ場合は、その箇条書きを継続します。

// 入力例
* aaa
  bbb

// 出力例
<ul>
  <li>aaa
  bbb</li>
</ul>

空白行がある場合は、引用テキストになります。

// 入力例
* aaa

  bbb

// 出力例
<ul>
  <li>aaa</li>
</ul>
<pre>
bbb
</pre>

3.11.表組み(テーブル)

行頭に「|(パイプ)」のある行は表組み(テーブル)になります。
それぞれのカラムは「|」で区切ります。「|*」または「| *」で開始するカラムはヘッダになります。
カラムの前後にある半角スペースは無視します。

表組みの入力例
|*ヘッダ1*|*ヘッダ2*|
|カラム1  |カラム2  |
表組みの出力例
<table>
  <tr>
    <th>ヘッダ1</th><th>ヘッダ2</th>
    <td>カラム1</td><td>カラム2</td>
  </tr>
</table>
「|-」ヘッダ記法

mok は org-mode などで使われているヘッダ記法(|-)に対応していません。
テーブル内に「|-」ヘッダ記法が記述されている場合は、何もない行として無視します。
※その他の場所の「|-」は普通のプレーンテキストとして扱います。

3.12.定義説明

用語定義の説明などを記述するには、行頭の「:」の後に定義したい語を書き(:の後に半角スペースは必要ありません)、次の行から半角スペースを2つ以上空けて説明を記述します。
行頭に半角スペースがない行がくると定義説明を終了します。

定義説明の入力例
:用語名
  説明文1       # 説明文は先頭に2行以上の半角スペースを空けます
  説明文2       # 複数行記述できます
定義説明の出力例
<dl>
  <dt>用語名</dt>
  <dd>
    説明文1       # 説明文は先頭に2行以上の半角スペースを空けます
    説明文2       # 複数行記述できます
  </dd>
</dl>

3.13.リンク

3.13.1.外部リンク

外部のファイルや URI にリンクを貼ります。
((<パス>)) または ((<タイトル|パス>)) で記述します。

ローカルファイル
ローカルファイルの記述例
((<sample.mok>)) #=> <a href="sample.mok">sample.mok</a>
((<SAMPLE|sample.mok>)) #=> <a href="sample.mok">SAMPLE</a>
URI のリンク
HTTP を使った外部 URL へのリンク
# 外部ページの URI にリンクを貼ります
((<http://google.com>)) => <a href="http://google.com">http://google.com</a>

# 外部ページの URI にリンクを貼り、タイトルをリンクタイトルとして表示します
((<Google|http://google.com>)) => <a href="http://google.com">Google</a>
ローカルファイルの記述例(URI)
# ローカルのファイルにリンクを貼ります
((<sample.mok|file:///home/garin/sample.mok>)) #=> <a href="file:///home/garin/sample.mok">sample.mok</a>

URI 形式ではファイルディレクトリを付加しません。

変換先フォーマットに合った拡張子に変換する「.%」構文

ファイルリンクで拡張子を「.%」にすると、変換先のフォーマットに合わせて拡張子を変更できます。例えば、通常の HTML であれば .html に、EPUB であれば .epub にリンク先を変更します*8

# mok2html で HTML に変換する場合(.% を .html に変換する)
((<sample.%>)) #=> <a href="sample.html">sample.html</a>
リンクのファイルベースディレクトリ

マルチメディアのファイルディレクトリ と同様に、リンク記法にもベースディレクトリを指定する、 reference_base_directory オプションがあります。
reference_base_directory オプションを指定すると ベースディレクトリの変換リスト の規則にそって、リンクパスを変換します。

3.13.2.ラベル(ドキュメント内リンク)

ラベルはそのドキュメントだけで有効な HTML のハイパーテキストのようなリンク機能を提供します。

ラベルの定義

ラベルは ((>識別子|タイトル<)) のような、左にラベルの識別子、右にラベルのタイトルを「|(パイプ)」で区切った構文を使い、そのドキュメント内で有効なラベルを作成します。
右のラベルタイトルがない場合は、識別子をタイトルとして使用します。
識別子は内部でハッシュ化されます。

ラベルの記述例
((>識別子<)) #=> <a href='#eeOpeeOZeeOrSUQIQ' id='eeOpeeOZeeOrSUQIQ'>識別子</a>
((>識別子|タイトル<)) #=> <a href='#eeOpeeOZeeOrSUQIQ' id='eeOpeeOZeeOrSUQIQ'>タイトル</a>
ラベルの参照

上記で定義したラベルへの参照をします。
左にラベルの識別子、右にラベルのタイトルを「|(パイプ)」で区切って記述します。
ラベルタイトルがない場合は、識別子をタイトルとして使用します。

ラベル参照の記述例
((=識別子=)) #=> <a href='#eeOpeeOZeeOrSUQIQ'>識別子</a>
((=識別子|タイトル=)) #=> <a href='#eeOpeeOZeeOrSUQIQ'>タイトル</a>

3.14.変数

ドキュメント内で変数の定義と参照を行うことができます。
((@変数名=内容@)) で定義し、 ((@変数名@)) で参照します。

3.14.1.変数の定義

文字修飾が使える場所であれば、どこでも変数を定義できます。
変数を定義した時点でその結果が表示されます。

((@apache=((<Apache|http://apache.rog>))@)) #=> <a href="http://apache.org">Apache</a>

変数の定義内でも、文字修飾を使うことができます。

3.14.2.変数の参照

変数名だけを指定すると変数の値を参照します。

((@apache@)) #=> <a href="http://apache.org">Apache</a>

3.14.3.変数の再定義

変数は再定義することもできます。再定義すると「それ以降の変数参照」が再定義した値を参照します。

((@version=1.0.0@))  #=> 1.0.0
((@version@))        #=> 1.0.0
...
((@version=2.0.0@))  #=> 2.0.0
((@version@))        #=> 2.0.0

※ルビやテーブル内、引用テキストなど文字修飾が使えない場所では定義・参照どちらもできません。

3.15.校正

文書の校正方法の1つである 真鵺道(まぬえど) の構文に対応しています。
ただし、置換記号として [...] ではなく ((/.../)) を使います。

校正の入力例
学校((/が/に/))行きます

「学校が行きます」を「学校に行きます」に校正するよう指定してます。

校正の出力例
学校<span class="manuedo">[が/に]</span>行きます

出力内容が真鵺道形式になるだけで実際に校正を行ったりはしません。

真鵺道の基本
[A/B]
A を B で置き換える
[A/] は A を消す(A を空文字で置き換える)
[/A] は A を挿入する(空文字を A で置き換える)
[A|B|C]
C B A の順に並び変える
[A||C] は A と C を交換する

3.16.文章情報 (メタデータ)

ドキュメントファイルの一番先頭(タイトルよりも前)に各項目を「# 項目名: 値」形式で記述すると文章のメタデータを設定します*9
文章情報はコンバート時にそれぞれのフォーマットに合わせたメタ情報として使用します。

author
ドキュメントを記述した著者名。「,」区切りで複数指定可能
publisher
出版社・発行者などドキュメントを公開した組織・個人名
create
ドキュメントを公開した日付。YYYY[-MM[-DD]] 形式
update
ドキュメントを更新した日付。YYYY[-MM[-DD]] 形式
thesis
ドキュメントの内容を1行程度で短くまとめた説明文。論題
(description は v0.4.0 で廃止)
tag
ドキュメントのカテゴリタグを指定します。半角スペースで複数指定可能
language
言語コード。日本語は ja
rights
コピーライト
version
バージョン番号
license
ライセンス表記
文章情報の記述例
# auther: がりん <garin54@gmail.com>
# publisher: garin.jp
# create: 2013-12-10
# update: 2013-12-20
# thesis: mok ドキュメントフォーマットのオンラインマニュアル
# language: ja
# rights: (c) garin.jp
# version: 1.0.0
# license: CC BY-SA 3.0
= mok ドキュメントフォーマット
以下ドキュメントを入力

3.17.ドキュメント内プログラム(erb)

mok は Ruby の ERB ライブラリを使ってドキュメント内に Ruby スクリプトを埋め込めます。
Ruby プログラムをドキュメントに埋め込む erb の機能については西山さんの「るびま0017号:標準添付ライブラリ紹介 【第 10 回】 ERB」に詳しく書かれています。

例えば Time.now メソッドを実行すると現在の時刻を出力します。

インラインスクリプトの入力例
このドキュメントの更新時刻: <%%= Time.now %>
インラインスクリプトの出力例
このドキュメントの更新時刻: <%= Time.now %>

※ドキュメント内プログラムはデフォルトでオフになっています。有効にするには各コンバートプログラムで設定します*10

Ruby スクリプトを使う時の注意
  • スクリプトは mok のドキュメントをパースする前に処理されます
    • コメント内や文字修飾の無効化内のコードも実行します
  • Ruby の セーフレベル4 で動作します。そのためファイルの操作や require などは禁止されます
ERB 書式を mok 内で表示する方法

ERB 書式を Ruby で処理せずにそのまま表示したい場合は、< の後に % を2つ続けて書きます。

<%%%= Time.now %> => <%%= Time.now %>

4.実験機能

以下の機能はまだ実験段階です。仕様の変更・削除の可能性があります。

4.1.部分テンプレート(partial)

mok-parser 0.3.2 から
ドキュメント内に他のファイルのドキュメントを読み込む。

  • 行頭に ((!partial!)) を置く。
  • ((!partial!)) 以降の文字列は無視。
  • partial を _partial.mok に変換して部分ファイルを読み込む。
  • 部分ファイルは変換元ファイルのカレントディレクトリからの相対パス。
  • options[:partial_base_directory] で既定ディレクトリを指定。
  • 部分ファイルの入れ子(部分ファイルの中で((!..!)))はできない

4.2.外部変数ファイル

mok-parser 0.3.2 から
ドキュメント内変数((@..@))を外部のファイルに定義する

  • /etc/mok/variable.yaml, ~/.mok/variable.yaml または --variables に指定したファイルに記述
  • ファイル内に YAML のハッシュ形式で値を入力(key: val)
  • ドキュメントからは変数記法((@key@))で値を取得可能

5.付録

5.1.公開されている mok ドキュメント

mok フォーマットで書かれたドキュメントのサンプルです。

5.1.1.garin.jp の ドキュメント

このサイト(garin.jp)に掲載されているドキュメントは github で公開しています。
ドキュメントはすべて mok 形式で書いています。

(ミラーリポジトリのため常に最新版とは限りません)

5.1.2.mok ドキュメントのサンプル

プログラムのインストールマニュアル
= Apache インストールマニュアル
== 概要
=== Apache とは?
((@apache@=((<Apache HTTPD Server|http://projects.apache.org/projects/http_server.html>))@))は オープンソースの HTTPD サーバです。

== インストール
Debian 系であれば apt-get、RedHat 系であれば yum を使ってインストールします。

  // Debian 系
  # apt-get install apache2

  // RedHat 系
  # yum install httpd
ブログ
# author : がりん <garin54@gmail.com>
# create : 2011-04-01
# update : 2011-04-04
# rights: (c) 2011 garin.jp
# version: 1.0.2
# publisher: garin.jp
# tag : ec2 ebs
= AmazonEC2 で EBS のサイズを変更する方法

== 概要
=== AmazonEC2 EBS とサイズ変更の問題点
EBS(Elastic Block Storage)は Amazon EC2 上で使える仮想のディスクボリュームです。
1GB 単位で最大1TB まで自由な大きさで作成し、通常のディスクボリュームと同じように OS にマウントして使えます。
...

== 移行の準備
=== 新しい EBS ボリュームの作成とアタッチ
==== 新しい EBS ボリュームの作成
まず、データを移行するための新しい EBS を作成します。
((<Amazon Management Console|https://console.aws.amazon.com>)) にログインし、以下の手順で EBS ボリュームを作成してください。
...
小説
# author : 夏目漱石
# create : 1905
# publisher: 合資会社ホトトギス社
= 吾輩は猫である
== 一
吾輩 ((^わがはい^))は猫である。名前はまだ無い。
どこで生れたかとんと見当 ((^けんとう^))がつかぬ。何でも薄暗いじめじめした所でニャーニャー泣いていた事だけは記憶している。 ...
== 二
吾輩は新年来多少有名になったので、猫ながらちょっと鼻が高く感ぜらるるのはありがたい。
元朝早々主人の許 ((^もと^))へ一枚の絵端書 ((^えはがき^))が来た。これは彼の交友某画家からの年始状であるが、上部を赤、下部を深緑 ((^ふかみど^))りで塗って、その真中に一の動物が蹲踞 ((^うずくま^))っているところをパステルで書いてある。

青空文庫「吾輩は猫である」より抜粋。

6.参考リンク

6.1.mok 関連のドキュメント

6.2.ソースコード

6.3.Gem パッケージ

*1 これは Ruby で使われている RD 書式と同じものです
*2 以下は実際に、 mok2html コマンドで変換した時の時刻が表示されてます
*3 Byte Order Mark: バイト並び順識別コード
*4 実際にどのような表示になるかは変換ツールに依ります
*5 注釈はこのように表示されます
*6 minad 氏のmimemagicライブラリを使っています
*7 mok は MIME タイプを渡すだけで実際にメディアファイルをどのように表示するかは変換ツールに委ねられています
*8 変更する拡張子は変換ツールで指定できます
*9 記述する順番は自由です
*10 mok2html の場合は --erb オプションで有効になる
(c) 2013 garin.jp