ronn.md

   1 ---
   2 title: Ronn
   3 category: Ruby libraries
   4 layout: 2017/sheet
   5 updated: 2017-10-15
   6 weight: -1
   7 prism_languages: [bash, ruby, json, markdown]
   8 intro: |
   9   Ronn generates Man pages. See [ronn(1)](http://rtomayko.github.io/ronn/ronn.1.html), [ronn-format(7)](http://rtomayko.github.com/ronn/ronn-format.7.html). Also see it on GitHub: [rtomayko/ronn](https://github.com/rtomayko/ronn).
  10 ---
  11
  12 ## Getting started
  13 {: .-left-reference}
  14
  15 ### Installation
  16
  17 #### Installation
  18
  19 ```bash
  20 gem install ronn
  21 ```
  22
  23 #### Usage
  24
  25 ```bash
  26 ronn foo.1.md        # creates foo.1.html
  27 ronn -r foo.1.md     # creates foo.1 (--roff)
  28 ronn -r -h foo.1.md  # builds --roff and --html
  29 ronn -m foo.1.md     # view as manpage
  30 ```
  31
  32 Ronn is a Ruby gem.
  33
  34 ### Basic template
  35
  36 ```markdown
  37 name(1) -- short, single-sentence description
  38 =============================================
  39
  40 ## SYNOPSIS
  41
  42 `name` [<optional>...] <flags>
  43
  44 ## DESCRIPTION
  45
  46 A normal paragraph. This can span multiple lines and is terminated with two
  47 or more line endings just like Markdown.
  48
  49 ## OPTIONS
  50
  51  * `-h`, `--help` :
  52    Displays the help screen.
  53
  54  * `--version` :
  55    Displays version information.
  56
  57 ## EXAMPLES
  58
  59 Indent examples with 4 spaces.
  60
  61     $ ls
  62     $ ls -la
  63
  64 ## COPYRIGHT
  65
  66 **PROJECTNAME** is copyright (c) 2015, Rico Sta. Cruz. Released under the MIT
  67 license.
  68
  69 ## SEE ALSO
  70
  71 ronn-format(7), ronn(1)
  72 ```
  73
  74 ## Formatting tags
  75
  76 ### Inline
  77
  78 #### Bold
  79
  80 ```
  81 `code`
  82 **strong**
  83 ```
  84
  85 #### Underline
  86
  87 ```
  88 <variable>
  89 _emphasis_
  90 *emphasis*
  91 ```
  92
  93 ### Linking
  94
  95 #### Manual references
  96
  97 ```
  98 sh(1)
  99 markdown(7)
 100 ```
 101
 102 #### Sections
 103
 104 ```
 105 [STANDARDS][]
 106 [SEE ALSO][]
 107 [DIFFERENT TEXT][#SEE-ALSO]
 108 ```
 109
 110 #### URL links
 111
 112 ```
 113 [URL link](http://github.com/rstacruz)
 114 <http://github.com>
 115 ```
 116
 117 ## Frequently-used sections
 118 {: .-one-column}
 119
 120 ### Sections
 121
 122 - `## SYNOPSIS`
 123 - `## DESCRIPTION`
 124 - `## OPTIONS`
 125 - `## SYNTAX`
 126 - `## ENVIRONMENT`
 127 - `## RETURN VALUES`
 128 - `## STANDARDS`
 129 - `## SECURITY CONSIDERATIONS`
 130 - `## BUGS`
 131 - `## HISTORY`
 132 - `## AUTHOR`
 133 - `## COPYRIGHT`
 134 - `## SEE ALSO`
 135 {: .-four-column}
 136
 137 ## Other CLI options
 138
 139 ### Options
 140
 141 ```bash
 142 --pipe                       # write to stdout
 143 --server, -S                 # serve in http://localhost:1207
 144 ```
 145
 146 ```bash
 147 --html, -5                   # default
 148 --fragment, -f               # html without header/title/footer
 149 ```
 150
 151 ```bash
 152 --style=toc,80c              # toc (table of contents)
 153                              # 80c (use 80c instead of 100c)
 154                              # print (include print stylesheet)
 155                              # dark
 156 ```
 157
 158 ```bash
 159 --manual="MY MANUAL"         # shown on top-center
 160 --organization="RONN 0.7.0"  # shown on bottom-left
 161 --date="YYYY-MM-DD"          # shown on bottom-center
 162 ```
 163
 164 ## Sections
 165
 166 | Section | Description                                   |
 167 | ---     | ---                                           |
 168 | `1`     | General commands                              |
 169 | `2`     | System calls                                  |
 170 | `3`     | C standard lib                                |
 171 | `4`     | Special files (/dev) and drivers              |
 172 | `5`     | File formats                                  |
 173 | `6`     | Games                                         |
 174 | `7`     | Misc                                          |
 175 | `8`     | System administration commands and procedures |
 176
 177 See [Man page sections](http://www.december.com/unix/ref/mansec.html) (december.com).
 178
 179 ## Using with npm
 180
 181 ### npm scripts
 182
 183 Place manual files in `man/xxx.1.md`, then in package.json:
 184 {: .-setup}
 185
 186 ```json
 187 "scripts": {
 188   "prepublish": "npm run build-man",
 189   "build-man": "if which ronn; then ronn man/*.md --html --roff --style=toc,80c --organization=\"@rstacruz\"; fi"
 190 },
 191 "directories": {
 192   "man": "man"
 193 }
 194 ```
 195
 196 ### marked-man
 197
 198 ```
 199 npm install -g marked-man
 200 marked-man foo.1.md > foo.1
 201 ```
 202
 203 #### Differences
 204
 205 * No definition lists
 206 * Can't use `<br>`
 207
 208 See [marked-man](https://github.com/kapouer/marked-man).
 209