NoraMark Manual

(作成中・記述は未完成です。)

NoraMarkは、EPUBで利用するXHTMLを生成するためのマークアップとしてデザインされました。次のような特徴があります。

必要なもの

インストール方法

Gemfile

Gemfileに次のように書きます

gem 'nora_mark'

そして、

$ bundle

直接インストール

gem install nora_mark

使い方

コマンドラインから

$ nora2html < source.nora > output.xhtml

入力はutf-8のみ受け付けます。日本語のテキストであれば、kconvオプションでうまくうごくかもしれません。

$ nora2html --kconv < source.nora > output.xhtml

nora2htmlは、newpageコマンドを<hr />タグに置き換え、すべてのページをひとつのxhtmlとして出力します

コードから

require 'nora_mark'

document = NoraMark::Document.parse(string_or_io, lang: 'ja')
document.html.write_as_files

Emacs Lisp noramark-mode

Emacs用のメジャーモードを提供するnoramark-mode.elを用意しています。現在のところ、font-lockによるsyntax highlight機能と、outline-minor-modeのサポートを提供しています。

  1. normark-mode.elをEmacsのload-pathが通った場所に配置してください。
  2. ~/.emacs.d/init.elに次の記述をしてください。
(require 'noramark-mode)
(setq auto-mode-alist (cons '("\\.nora$" . noramark-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("-nora\\.txt$" . noramark-mode) auto-mode-alist))

マークアップ

通常のテキスト

単なるテキストもHTMLに変換されます。

原稿

吾輩は猫である。名前はまだ無い。
どこで生れたかとんと見当けんとうがつかぬ。何でも薄暗いじめじめした所でニャーニャー泣いていた事だけは記憶している。
＜中略＞
この書生の掌の裏うちでしばらくはよい心持に坐っておったが、しばらくすると非常な速力で運転し始めた。

ふと気が付いて見ると書生はいない。たくさんおった兄弟が一疋ぴきも見えぬ。

変換結果

<div class='pgroup'>
<p>吾輩は猫である。名前はまだ無い。</p>
<p>どこで生れたかとんと見当けんとうがつかぬ。何でも薄暗いじめじめした所でニャーニャー泣いていた事だけは記憶している。</p>
<p>＜中略＞</p>
<p>この書生の掌の裏うちでしばらくはよい心持に坐っておったが、しばらくすると非常な速力で運転し始めた。</p>
</div>
<div class='pgroup'>
<p>ふと気が付いて見ると書生はいない。たくさんおった兄弟が一疋ぴきも見えぬ。</p>
</div>

改行ごとに<p>要素がつくられます。空行で区切られると<div class='pgroup'>がつくられます。

言語が日本語(ja)以外の場合は、次のようになります。

原稿

Lorem ipsum dolor sit amet, consectetur adipisicing elit, 
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 

Ut enim ad minim veniam, quis nostrud exercitation

変換結果

<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, <br />sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. </p>
<p>Ut enim ad minim veniam, quis nostrud exercitation</p>

後述のparagraph_styleでもこの振る舞いを切り替えることができます。

明示的なブロック

NoraMarkでは、<コマンド> { ではじまり、} のみの行で終わる範囲を明示的なブロックとみなします。

原稿

d.column {
この部分は、divで囲まれます。
}

変換結果

<div class="column">
<div class="pgroup">
<p>この部分は、divで囲まれます。</p>
</div>
</div>

このように、コマンドにはclassを指定することができます。

同じように、idの指定も可能です。

原稿

d#the_column.column {
この部分は、divで囲まれます。
}

変換結果

<div id="the_column" class="column">
<div class="pgroup">
<p>この部分は、divで囲まれます。</p>
</div>
</div>

クラス・IDの指定は、多くのコマンドで同じように利用できます。

定義済みの明示的ブロックのコマンドは、次のものがあります。

d
divを生成します
sec, section
sectionを生成します
art, article
articleを生成します

このほかに、後述のpreformatブロックがあります。

未定義のコマンドの場合は、対応する名前のタグを生成します。

原稿

blockquote {
山路を登りながら、こう考えた。
智に働けば角が立つ。情に棹させば流される。意地を通せば窮屈だ。とかくに人の世は住みにくい
}

変換結果

<blockquote>
<div class='pgroup'>
<p>山路を登りながら、こう考えた。</p>
<p>智に働けば角が立つ。情に棹させば流される。意地を通せば窮屈だ。とかくに人の世は住みにくい</p>
</div>
</blockquote>

Preformat block

整形済みブロックは、次のように指定します。

形式1

pre {
  format 1 : 整形済みの内容
}

形式2

pre {//
  format 2: 整形済みの内容
//}

変換結果

<pre>
format 1 : 整形済みの内容
</pre>
<pre>
format 2 : 整形済みの内容
</pre>

また、次のように書くことで整形済みコードを作ることもできます。

形式1

code {
整形済みコード
}

形式2

code {//
整形済みコード
//}

形式3

```
  整形済みコード
```

変換結果

<pre></code>
整形済みコード
</code></pre>
code languageの指定

code languageの指定をすることができます。

形式1

code {//ruby
puts "Hello, World."
//}

形式2

```ruby
puts "Hello, World."
```

変換結果

<pre class='code-ruby' data-code-language='ruby'><code>
puts "Hello, World."
</code></pre>
キャプションの指定

原稿

code(ソースコードはこちら) {
puts 'Hello, World'
}

または、こんな書き方もできます。

原稿

```(ソースコードはこちら)
puts 'Hello, World'
```

こんな風になります。

変換結果

<div class='pre'>
<p class='caption'>原稿はこちら</p>
<pre><code>
puts 'Hello, World'
</code></pre>
</div>

インラインコマンド

インラインコマンドは、原則として次の形式をしています。

[<コマンド>{内容}]

定義済みのインラインコマンドには、次のものがあります。

l

リンクを定義します。

[l(http://github.com/skoji/noramark){NoraMarkのレポジトリ}]

変換結果

<a href='http://github.com/skoji/noramark'>NoraMarkのレポジトリ</a>
sp

spanを定義します。

[sp.note{spanの中にはいる}]

変換結果

<span class='note">spanの中に入る</span>
img

画像を定義します。このコマンドにはブレースのセクションがありません。

[img(img/some_image.jpg,alternate text)]

変換結果

<img src='img/some_image.jpg' alt='alternate text' />
tcy

class tcyのspanを定義します。縦書きにおける縦中横のスタイルをあてることを想定しています。

FM TOWNSが登場してからすでに[tcy{25}]年がたった。

変換結果

<p>FM TOWNSが登場してからすでに<span class='tcy'>25</span>年がたった。</p>
ruby

ルビをマークアップします。

[ruby(とんぼ){蜻蛉}]の[ruby(めがね){眼鏡}]はみずいろめがね

変換結果

<p><ruby>蜻蛉<rp>(</rp><rt>とんぼ</rt><rp>)</rp></ruby>の<ruby>眼鏡<rp>(</rp><rt>めがね</rt><rp>)</rp></ruby>はみずいろめがね</p>
code

インラインでコードをマークアップします。中はMarkupとして解釈しません。` (バッククオート)で囲む方法と、[code{}]を使う方法があります。

`puts "Hello, World."` and  [code{puts "Hello, World."}]

変換結果

<p><code>puts "Hello, World.</code> and <code>puts "Hello, World.</code> </p>

ただし[code{}]の形式ではたとえば

[code{ [ruby(とんぼ){蜻蛉}] }]

と書くと、蜻蛉の後ろにある}]でcodeコマンドは終了してしまうため、次のような変換結果となります。

<p><code>[ruby(とんぼ){蜻蛉</code>}]</p>

行コマンド

行コマンドは1行を占有し、次の形式をしています。

<コマンド>:内容

定義済みの行コマンドには、次のものがあります。

;: p {

パラグラフをマークアップします。クラスやIDを付加する目的で使うことを想定しています。

p.caution: 用量に注意してご利用ください。

変換結果

<p class='caution'>用量に注意してご利用ください。</p>
image

figureでラップされたimgをマークアップします。

image(path-to-image/img.jpg, 代替テキスト): イメージのキャプション

変換結果

<figure class='img-wrap'>
<img src='path-to-image/img.jpg' alt='代替テキスト' />
<figcaption>イメージのキャプション</figcaption>
</figure>
newpage

新規ページを作成します。この位置XHTMLファイルが区切られ、新たなXHTMLが生成されます。

newpage:

リスト

箇条書き

原稿

* *ではじまる行は、箇条書きになります
* 空行があくまで、箇条書きがつづきます。

* 空行があくと、あらたな箇条書きになります。
* さらに、
** *を続けるとネストされます。

変換結果

<ul><li>*ではじまる行は、箇条書きになります。</li>
<li>空行があくまで、箇条書きがつづきます。。</li>
</ul>
<ul><li>空行があくと、あらたな箇条書きになります。</li>
<li>さらに、
<ul> <li>*を続けるとネストされます。</li></ul>
</li>
</ul>

番号つきリスト

原稿

1. 数字.ではじまる行は、番号つきリストになる。
2. 空行があくまで、リストがつづく。

3. 空行があくと、あらたなリストになる。
10. 先頭の数字にかかわらず、1から順に番号がふられる。

変換結果

<ol><li>数字.ではじまる行は、番号つきリストになる。  </li>
<li>空行があくまで、リストがつづく。</li>
</ol>
<ol><li>空行があくと、あらたなリストになる。</li>
<li>先頭の数字にかかわらず、1から順に番号がふられる。</li>
</ol>

番号つきリストのネストはサポートしていませんが、どうしてもやりたい場合は次のような方法もあります。

原稿

ol {
li: 第一の要素
li {
  ここはネストしたい。
  ol {
    li: ネストします。
  }
li: 第三の要素  
}
}

定義リスト

定義リストには、二種類の書き方があります。

1行の定義

原稿

;: それがし : 名前がわからない，または名前を隠して人や物事をさす語。
;: それがしかれがし : 不定称。二人以上の人に対し，名を知らなかったり，名を省略していうときに用いる語。

変換結果

<dl>
<dt>それがし</dt>
<dd>名前がわからない，または名前を隠して人や物事をさす語。</dd>
<dt>それがしかれがし</dt> 
<dd>不定称。二人以上の人に対し，名を知らなかったり，名を省略していうときに用いる語。</dd>
</dl>
複数行の定義

説明が長い場合は、複数行の形式で書けます。この場合、説明部分は段落になります。

原稿

;: それがし {
 名前がわからない，または名前を隠して人や物事をさす語。
}
;: それがしかれがし {
 不定称。二人以上の人に対し，名を知らなかったり，名を省略していうときに用いる語。
}

変換結果

<dl>
<dt>それがし</dt>
<dd><div class="pgroup"><p>名前がわからない，または名前を隠して人や物事をさす語。</p></div></dd>
<dt>それがしかれがし</dt> 
<dd><div class="pgroup"><p>不定称。二人以上の人に対し，名を知らなかったり，名を省略していうときに用いる語。</p></div></dd>
</dl>

見出し

単独の見出し

h1からh6が用意されています。そのまま、<h1> タグに変換されます。

原稿

h1: 単独の見出し
ここに本文

変換結果

<h1>単独の見出し</h1>
<div class='pgroup'>
<p>ここに本文</p>
</div>

セクションを生成する見出し

Markdown風の # をつかった見出しも使えます。この見出しは、sectionを生成します。

原稿

# 見出し
本文

変換結果

<section>
  <h1>見出し</h1>
  <div class='pgroup'>
    <p>本文</p>
  </div>
</section>

入れ子にもできます。sectionの範囲は適切に判断されます。

原稿

# 見出し
本文
## 小見出し
次の本文
# 新しい章
新しい章の本文

変換結果

<section>
  <h1>見出し</h1>
  <div class='pgroup'>
    <p>本文</p>
  </div>
  <section>
    <h2>小見出し</h2>
      <div class='pgroup'>
        <p>次の本文</p>
      </div>
  </section>
</section>
<section>
  <h1>新しい章</h1>
  <div class='pgroup'>
    <p>新しい章の本文</p>
  </div>
</section>

明示的に範囲を指定したセクションをつくることもできます。

原稿

# 第一のセクション
ここは第一のセクション
## 第二のセクション {
ここは第二のセクション
}
ここは再び第一のセクション

変換結果

<section>
  <h1>第一のセクション</h1>
  <div class='pgroup'>
  <p>ここは第一のセクション</p>
  </div>
  <section>第二のセクション</h1>
    <div class='pgroup'>
    <p>ここは第二のセクション</p>
    </div>
  </section>
  <div class='pgroup'>
  <p>ここは再び第一のセクション</p>
  </div>
</section>

Frontmatter

各ページごとにYAML frontmatterでメタデータを記載できます。

Frontmatterの例

---
title: ページのタイトル
stylesheets: [reset.css, default.css]
lang: ja
paragraph_style: default
---

title, stylesheets, langはそれぞれXHTMLのheaderにかかれます。paragraph_styleは、HTML生成時の段落スタイル指示ができます。

カスタマイズ

生成ルール追加

木構造の操作

コマンドの書式

(加筆修正予定)

コマンド

コマンド名[id][class][パラメータ][名前付きパラメータ]

具体的には、たとえば次のような形をしています。

具体例

div#id1#id2.class1.class2(parameter1, parameter2)[named_parameter: 1, named_parameter 2]
  • コマンド名は英字ではじまり、英数字とハイフン、アンダースコアからなります。
  • idは、#からはじまり、英数字とハイフン、アンダースコアからなります。複数続けることができます。
  • classは、.からはじまり、英数字とハイフン、アンダースコアからなります。複数続けることができます。
  • パラメータは()で囲まれています。カンマで区切られた領域ごとに、独立したパラメータになります。
  • パラメータの内容は、NoraMarkのマークアップとしてパースされます。
  • 名前付きパラメータは[]で囲まれていて、カンマで区切られた次の形式をしています。
    • 名前: パラメータ
  • 名前は英字ではじまり、英数字とハイフン、アンダースコアからなります。名前付きパラメータの内容は、NoraMarkのマークアップとしてはパースされません。

XML生成