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のオープンソース・ソフトウェアです。

Ronn rtomayko/ronn