RubyのコマンドラインツールのMan Pageをつくる

コマンドラインツールでは,--helpオプションで簡単に使い方やオプションの説明を出力する.単純に使ってもらう分にはこれで足りる.ただ,さらにそのコマンドラインツールを使ってもらいたい場合には,詳細なドキュメントや使い方の例,簡単なチュートリアルをコマンドライン上で提供できるのがよい.単純にOptparseなどでこれをやろうとすると,スペースが足りないし,ちょっとヘルプを見たいだけのユーザには邪魔になる.

伝統的なUNIXコマンドは,manコマンドを通じてそのような詳細な情報を提供している.例えば,man lsと打てば,lsコマンドの詳細が見れる.RubyでつくったコマンドラインツールでもMan Pageを通じて,同様の情報を提供できるとよい.

しかし,Rubygems.orgを通してコマンドラインツールを配信する場合,標準のmanコマンドを通じてMan pageを提供するのは難しい.GithubのChris Wanstrath氏によるgem-manを使えば,gem manコマンドを通じて標準のmanと同様のMan Pageを簡単に提供できる.

さらに,Man Pageは,nroffという専用の言語で書かれており,わざわざ習得するのはめんどい.これも,rtomayko/ronnを使えば,MarkdownでMan pageを書いて,nroff形式に変換することができる.

TL;DR

  • gem manでrubyでつくったコマンドラインツールのMan Pageを提供する
  • ronnでMarkdown形式をMan Pageのnroff形式を吐き出す

以下のようなものをつくる.

$ gem man your_app

NAME
    your_app - Sample of gem-man and ronn

SYNOPSIS
    your_app [options]

DESCRIPTION
    your_app is a simple command-line tool for ...

OPTIONS
    -h, --help
      Show help page.
etc...      

Install

Gemとしてgem-manronnをインストールする.

$ gem install gem-man ronn

Rubygemsとして配布する場合は,gemspecに以下を追記する.

# your_app.gemspec
spec.add_dependency "gem-man"
spec.add_development_dependency "ronn"

Man Pageのソースは,プロジェクトのルートのmanディレクトリに配置し,ファイル名はyour_app.1.ronnとする.

$ mkdir man
$ touch man/your_app.1.ronn

.1というファイル名は必須でMan Pageのセクション番号を示す.

ronnでMan Pageをつくる

ronnを使えば,Man PageをMarkdown形式で書き,nroff形式で吐き出すことができる.例えば,以下のように書く.

your_app(1) - Sample of gem-man and ronn
====

## SYNOPSIS

`your_app` [options]

## DESCRIPTION

**your_app** is a simple command-line tool for ...

## OPTIONS

  * -h, --help
      Show help page.

## Exmaple
...

##でセクションの始まり,*でリストなど,普段README.mdなどで書いてるのと同じ感じで作成できる.また,<>で囲めばリンクとなり,man/index.txtを準備すれば,他のMan Pageにリンクを貼ることもできる.

後は,以下のコマンドでnroff形式で吐き出すだけ.

$ ronn man/your_app.1.ronn
roff: man/your_app.1
html: man/your_app.1.html                                     

同時にHTML形式も吐き出される(例えば,ronnだとこんな感じのページが生成される).生成結果は,標準のmanを使ってプレビューできる.

$ man man/your_app.1

gem-manを使う

後は,上で作成したmanディレクトリを一緒にgemとして配布すれば,ユーザは以下のコマンドで作成したMan Pageを表示できるようになる.

$ gem man your_app

UNIXの他のコマンドと同様に扱いたい場合は,以下のようなAliasを設定すればよい.

$ alias man='gem man -s'

Man Pageがあれば,わざわざブラウザを立ち上げることなく,詳細のドキュメントをユーザに提示でき,より親切なコマンドラインツールをつくれる.

参考