RD でも書いてみようか 【第 1 回】 ブロックレベル
書いた人：mput
まえがき
みなさんは Ruby スクリプトと一緒に README.rd などという文章が添付されているのを見た事はありませんか？ RD というのは Ruby 関連のドキュメントを書くのに広く使われている書式で、おもにこの書式から HTML に変換して使われる事が多いと思われます。
他人に読まれることを意識した文章は、自ずと他人と共通のフォーマットで書かれるものだと思います。Ruby においてはそのフォーマットが RD なのです。したがって、Ruby 関連のドキュメントを書く際には RD を選択する場合が必然的に多くなります。この連載では、みなさんが RD を書く際に最低限必要な構造に着目しつつ、それを変換した場合の出力例を交えながら、RD の書き方を解説します。
RD の書き方
文章とその構造について
これは RD に限った話ではありませんが、一般に文章には構造というものがあります。英作 文を習ったことがある人なら、英語のパラグラフは通常 3 つから 5 つ程度のセンテンスで構 成されていて云々、というのを習ったと思いますが、あれはべつに英語に限った話ではあ りません。分かりやすい文章は自ずときれいに構造化されているものです。RD は労せずに 構造化された文章を書けるように、しかし型にはまった文章以外もちゃんと書けるように、 設計されています *1。 そこで、RD 本体の説明の前にほんのちょっとだけ文章構造の説明をしておこうと思います。
- 文章はひとつ以上の文(日本語で言えば読点「。」で区切られた部分)があつまってできたものです。文の長さが少ないと詩的な文になり、長いと繰言調になります
- 文章の構成において基本となるのは段落(パラグラフ)です。段落はいくつかの文から構成されていて、基本的にひとつの段落内では内容が完結しているのがふつうです
- いくつかの段落が集合してさらに大きな構造を作る場合があります。たとえば節(セクション)と呼ばれる構造は段落が集まってできます
- さらに大きな構造として、節が集まってできた章(チャプター)という構造が出現することもあります
このように、セオリーとして文章はある要素がいくつか集まって別の大きな要素になる ように書くと読みやすくなります。もちろん読みやすさを気にしないなら必ずしもこの構 造に従う必要はありません。たとえば詩歌などは大幅にセオリーを外れた構造をしていま す。しかし、たとえば拡張ライブラリのドキュメントが都都逸で書いてあったとしたら、 読みづらくてしかたないでしょう(笑えるかもしれませんが)。他人に読まれる文章は、で きるだけ定石を踏まえた構造で書くべきと個人的には考えています。
RD と構造化
これを踏まえて、RD の書き方を見ていきましょう。
段落の作り方
RD で文章のある点に段落を作りたいときには、そこに空行を入れると段落の区切りになり ます。
入力例:
春は、あけぼの。やうやう白くなりゆく、山ぎは少し明りて、紫だちたる雲のほそくたな びきたる。 夏は、夜。月のころはさらなり、闇もなほ、蛍の多く飛びちがひたる。また、ただ一つ二 つなど、ほのかにうち光りて行くも、をかし。雨など降るも、をかし。 秋は、夕暮れ。夕日のさして、山の端いと近うなりたるに、烏の寝どころへ行くとて、三 つ四つ、二つ三つなど、飛び急ぐさへあはれなり。まいて、雁などのつらねたるが、いと 小さく見ゆるは、いとをかし。日入り果てて、風の音、虫の音など、はた言ふべきにあら ず。 冬は、つとめて。雪の降りたるは言ふべきにもあらず。霜のいと白きも、またさらでも、 いと寒きに、火など急ぎおこして、炭持て渡るも、いとつきづきし。昼になりて、ぬるく ゆるびもていけば、火桶の火も白き灰がちになりて、わろし。
出力例:
このように、RD では改行ひとつだけの場合はそこで区切りが入ったりはしないことに注意 してください。
段落より大きな構造の作り方
段落より大きな構造として章や節などがありますが、RD ではこれらの構造は タイトルを指定することで明示していきます。次の例を見てください。
入力例:
= おぼつかなきもの 十二年の山篭りの法師の女親。知らぬ所に、闇なるに行きたるに、あらはにもぞあるとて、 火もともさで、さすがに並みゐたる。今出で来る者の、心も知らぬに、やむごとなき物持 たせて人のもとにやりたるに、遅く帰る。ものもまだ言はぬちごの、そりくつがへり人に も抱かれず泣きたる。 = たとしへなきもの 夏と冬と。夜と昼と。雨降る日と照る日と。人の笑ふと腹立つと。老いたると若きと。白 きと黒きと。思ふ人とにくむ人と。同じ人ながらも心ざしあるをりとかはりたるをりは、 まことに異人とぞおぼゆる。火と水と。肥えたる人、痩せた人。髪長きと短き人と。
出力例:
このように、= で始まる行はタイトルになり、以下別のタイトルが出現するまでがひとか たまりになります。
RD では実際には複数の構造レベルを記述することができて、その場合には==、 === などで始まる行がタイトルとなります。以下にタイトル行の一覧を示しておきますが、 個人的な経験から言ってそうそうすべてのレベルが出現することはないでしょう。
タイトルレベル:
構造の大きさ|行頭
------------+-----
大きい |
｜ |=
｜ |==
｜ |===
｜ |+
↓ |++
小さい |
RD のその他の構造化要素
RD にはこのほかにも便利な構造がいくつか存在します。
逐次出力(verbatim)
上に書いたように RD ではただの改行はなにもなかったように扱われます。しかし、時とし て改行位置が大きな意味を持つ場合があります。たとえば詩歌の表現において改行と行頭 位置は重要な情報ですし、技術系の文章でプログラムコードを入力する際にも改行は意味 を持つことがあります(Python や Haskell はインデントも意味を持ちますね)。そこで、RD には verbatim という、書いたままを表示する仕組みが備わっています。この書式はとても 簡単で、単に周辺より字下げが深い箇所はそのまま出力というルールです。例を見 てみましょう。
入力例:
= 菩提といふ寺に
菩提といふ寺に、結縁の八講せしに詣でたるに、人のもとより「とく帰りたまひね。いと
さうざうし」と言ひたりければ、蓮の葉のうらに、
もとめてもかかる蓮の露をおきて憂き世に、または帰るものかは
と書きてやりつ。まことに、いと尊くあはれなれば、やがてとまりぬべくおぼゆるに、さ
うちうが家の人のもどかしさも忘れぬべし。
出力例:
これだけでは改行の扱いが分かりづらいので、もう少し別の例もあげておきます。
入力例:
= 漢詩(verbatimの例) == 偶成 朱熹 少年易老学難成 一寸光陰不可軽 未覚池塘春草夢 階前梧葉已秋声 == 春望 杜甫 国破山河在 城春草木深 感時花濺涙 恨別鳥驚心 烽火連三月 家書抵万金 白頭掻更短 渾欲不勝簪
出力例:
このように書いたままの形で出力されていることが分かります。
箇条書き
箇条書きの記法があります。箇条書きは行頭が * で始まっている行で表します。
入力例:
= 木の花は * 濃きも薄きも、紅梅 * 桜は、花びら大きに、葉の色濃きが、枝細くて咲きたる * 藤の花は、しなひ長く、色濃く咲きたる、いとめでたし。 * 四月のつごもり、五月のついたちのころほひ、橘の葉の濃く青きに、花のいと白う咲き たるが、雨うち降りたるつとめてなどは、世になう心あるさまに、をかし。花の中より 黄金の玉かと見えて、いみじうあざやかに見えたるなど、朝露に濡れたる朝ぼらけの桜 に劣らず。郭公のよすがとさへ思へばにや、なほ、さらに言ふべきにもあらず。 * 梨の花、よにすさまじきものにして、近うもてなさず、はかなき文付けなどだにせず、 愛敬おくれたる人の顔など見ては、たとひに言ふも、げに、葉の色よりはじめて、あは ひなく見ゆるを、唐土には限りなきものにて、詩にも作る、なほさりとも、やうあらむ と、せめて見れば、花びらの端にをかしきにほひこそ、心もとなうつきためれ。楊貴妃 の、帝の御使いあひて泣きける顔に似せて、「梨花一枚、春、雨を帯びたり」など言ひ たるは、おぼろけならじと思ふに、なほいみじうめでたきことは、たぐひあらじとおぼ えたり。 * 桐の木の花、紫に咲きたるは、なほをかしきに、葉のひろごりざまぞ、うたてこちたれ ど、異木どもとひとしう言ふべきにもあらず。唐土にことごとしき名つきたる鳥の、選 りてこれにのみ居るらむ、いみじう心異なり。まいて、琴に作りて、さまざまなる音の いでくるなどは、をかしなど、世の常に言ふべくやはある、いみじうこそめでたけれ。 * 木のさまにくげなれど、楝花、いとをかし。かれがれに、様異に吹きて、かならず五月 五日にあふも、をかし。
出力例:
箇条書きのルールをよりくわしく解説すると、
- 行頭が * で始まる行が箇条書きの開始
- 以下、開始行の字下げよりも字下げが戻るまでの間はずっと箇条書き
となります。ちなみにこのように字下げを最初の行に倣って続ける方式のことをハンギン グインデントと呼んだりしますが、RDは基本的にハンギングインデントを認識して構文解 析を行う言語であると言えます。
次回予告
RD のルールはまだ他にもありますが、とりあえず上に挙げたくらいの要素が分かっていれ ば、かなりの文章が書けるようになります。
ところが、ここまでの説明ではまだ、文より小さな構造単位を説明していませんでした。例えばここまでの説明では、まだ HTML にあるようなハイパーリンクを記述したりすることはできません。
そこで、次回は文よりも小さな構文要素たちを紹介します。
RD でも書いてみようか連載一覧
- RD でも書いてみようか 【第 1 回】 ブロックレベル
- RD でも書いてみようか 【第 2 回】 インライン
- RD でも書いてみようか 【第 3 回】 RD as a ruby document format
*1 構造化を最初から意図して設計したのか、無意識のうちにそうなってしまっているのかは不明ですが
References:[Rubyist Magazine 0006 号] [RD でも書いてみようか 【第 2 回】 インライン] [各号目次]