Ronn - Markdownを使ってマニュアルファイルの生成
CLIのツールを作ったら必要になるのがコマンドの説明を記したマニュアルファイルです。特定の書き方で書かないといけないので、はじめての時や久々に書く際には書き方を忘れてしまっているのではないでしょうか。 そこで使ってみたいのがRonnです。manファイルをMarkdown形式で書けるソフトウェアです。
Ronnの使い方
RonnのインストールはRubygemsで行います。
$ gem install ronn
後はMarkdownファイルを指定してronnを実行します。デフォルトではマニュアルファイルとHTMLを生成します。例えばMarkdownファイルの内容はこんな感じです。
ronn-format(7) -- manual authoring format based on Markdown
===========================================================
## SYNOPSIS
name(1) -- short, single-sentence description
=============================================
## SYNOPSIS
`name` [<optional>...] <flags>
## DESCRIPTION
A normal paragraph. This can span multiple lines and is terminated with two
or more line endings -- just like Markdown.
実行します。
$ ronn ronn.1.ronn
roff: ./ronn.1
html: ./ronn.1.html +man
マニュアルファイルができました。
$ cat ronn.1
.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "RONN" "1" "October 2015" "" ""
.
.SH "NAME"
\fBronn\fR \- convert markdown files to manpages
.
かなり難しいですね。これを手作業で書く気にはならないですし、専用ツールの記法を覚えるならばMarkdownで書ける方が楽でしょう。
コマンドラインのオプションは次のようになっています。
$ ronn
Usage: ronn <options> <file>...
ronn -m|--man </file><file>
ronn -S|--server </file><file> ...
ronn --pipe [</file><file>...]
Convert ronn source </file><file>s to roff or HTML manpage. In the first synopsis form,
build HTML and roff output files based on the input file names.
Mode options alter the default behavior of generating files:
--pipe write to standard output instead of generating files
-m, --man show manual like with man(1)
-S, --server serve </file><file>s at http://localhost:1207/
Format options control which files / formats are generated:
-r, --roff generate roff output
-5, --html generate entire HTML page with layout
-f, --fragment generate HTML fragment
--markdown generate post-processed markdown output
Document attributes:
--date=<date> published date in YYYY-MM-DD format (bottom-center)
--manual=<name> name of the manual (top-center)
--organization=</name><name> publishing group or individual (bottom-left)
Misc options:
-w, --warnings show troff warnings on stderr
-W disable previously enabled troff warnings
--version show ronn version and exit
--help show this help message
A <file> named example.1.ronn generates example.1.html (HTML manpage)
and example.1 (roff manpage) by default.
そして -m をつけるとマニュアルっぽい表示ができます。
Ronnを使えばコマンドラインツールをより使いやすい形に仕上げることができるでしょう。普段使い慣れた記法を使えばより細かく、分かりやすいマニュアルを作ることができるはずです。
RonnはRuby製、MIT Licenseのオープンソース・ソフトウェアです。