Ronn 速查表 | Cheat Sheet

本文根据 Devhints / Ronn 翻译。代码示例及版本范围沿用原文。原文标注更新日期：2017-10-15。

Ronn 可生成 Man 页面。请参阅 ronn(1), ronn-format(7)。也可在 GitHub 上查看： rtomayko/ronn.

入门

安装

gem install ronn

用法

ronn foo.1.md        # creates foo.1.html
ronn -r foo.1.md     # creates foo.1 (--roff)
ronn -r -h foo.1.md  # builds --roff and --html
ronn -m foo.1.md     # view as manpage

Ronn 是一个 Ruby gem（Ruby 软件包）。

基础模板

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.

## OPTIONS

 * `-h`, `--help` :
   Displays the help screen.

 * `--version` :
   Displays version information.

## EXAMPLES

Indent examples with 4 spaces.

    $ ls
    $ ls -la

## COPYRIGHT

**PROJECTNAME** is copyright (c) 2015, Rico Sta. Cruz. Released under the MIT
license.

## SEE ALSO

ronn-format(7), ronn(1)

格式化标签

行内

粗体

`code`
**strong**

下划线

<variable>
_emphasis_
*emphasis*

链接

手册引用

sh(1)
markdown(7)

章节

[STANDARDS][]
[SEE ALSO][]
[DIFFERENT TEXT][#SEE-ALSO]

URL 链接

[URL link](https://github.com/rstacruz)
<https://github.com>

常用章节

章节

## SYNOPSIS
## DESCRIPTION
## OPTIONS
## SYNTAX
## ENVIRONMENT
## RETURN VALUES
## STANDARDS
## SECURITY CONSIDERATIONS
## BUGS
## HISTORY
## AUTHOR
## COPYRIGHT
## SEE ALSO

其他 CLI 选项

选项

--pipe                       # write to stdout
--server, -S                 # serve in http://localhost:1207

--html, -5                   # default
--fragment, -f               # html without header/title/footer

--style=toc,80c              # toc (table of contents)
                             # 80c (use 80c instead of 100c)
                             # print (include print stylesheet)
                             # dark

--manual="MY MANUAL"         # shown on top-center
--organization="RONN 0.7.0"  # shown on bottom-left
--date="YYYY-MM-DD"          # shown on bottom-center

章节

章节	说明
`1`	通用命令
`2`	系统调用
`3`	C 标准库
`4`	特殊文件（/dev）和驱动程序
`5`	文件格式
`6`	游戏
`7`	杂项
`8`	系统管理命令与流程

参见 Man 页面章节 (december.com).

与 npm 配合使用

npm 脚本

将手册文件放置在 man/xxx.1.md，然后在 package.json 中：

"scripts": {
  "prepublish": "npm run build-man",
  "build-man": "if which ronn; then ronn man/*.md --html --roff --style=toc,80c --organization=\"@rstacruz\"; fi"
},
"directories": {
  "man": "man"
}

marked-man

npm install -g marked-man
marked-man foo.1.md > foo.1

区别

不支持定义列表
无法使用 <br>

参见 marked-man.