Command reference

roff has four commands: tojson, tomd, view, and bench. All read man pages in roff/mdoc format and write to stdout.

roff tojson

Convert man page(s) to JSON.

roff tojson file.1               # compact JSON (default)
roff tojson --indent 2 file.1    # pretty-print with 2-space indent
roff tojson --indent 4 file.1    # pretty-print with 4-space indent
roff tojson --source-expand file.1
roff tojson -- < file.1

Options

Example output

{
  "title": "LS",
  "section": "1",
  "name": "ls",
  "description": "list directory contents",
  "sections": [
    {"title": "NAME", "text": "ls — list directory contents"},
    {"title": "SYNOPSIS", "text": "ls [options] [file ...]"},
    {"title": "OPTIONS", "items": [
      {"tag": "-a", "body": "do not ignore entries starting with .", "depth": 0},
      {"tag": "-l", "body": "use a long listing format", "depth": 0}
    ]}
  ],
  "source": []
}

Each list item is an object with tag (the .It/.IP/.TP argument), body (the descriptive text), and depth. Nested .Bl lists are preserved: items inside an inner list get depth ≥ 1, so an inner .El no longer prematurely closes the outer list. Reconstruct the tree by walking items in order and tracking depth.

When multiple files are given, each output is prefixed with # File: <path>.

roff tomd

Convert man page(s) to Markdown with YAML front matter.

roff tomd file.1
roff tomd --source-expand file.1
roff tomd -- < file.1

Options

Example output

---
title: "LS"
section: "1"
name: "ls"
description: "list directory contents"
---

# NAME

ls — list directory contents

# SYNOPSIS

ls [options] [file ...]

# OPTIONS

- -a: do not ignore entries starting with .
- -l: use a long listing format

roff tohtml

Convert man page(s) to minimal HTML5 (useful for documentation sites).

roff tohtml file.1
roff tohtml --source-expand file.1
roff tohtml -- < file.1

Options

Front matter is rendered as <meta> tags; sections become <h2>, paragraphs <p>, and lists nested <ul>/<li>. No new dependencies; all HTML-special characters (&, <, >, ", ') are escaped.

roff view

Progressively disclose parts of a man page. Use it to grab just the synopsis, options, or outline for an LLM prompt.

roff view ls
roff view ls 1
roff view --synopsis ls
roff view --meta ls
roff view --outline-head 3 ls
roff view /path/to/file.1
cat file.1 | roff view -

Query formats

Options

How view finds man pages

view first checks if a query contains / or . and treats it as a file path. Otherwise it walks manpath output, falling back to /usr/share/man and /usr/local/share/man. It searches sections 1 through 9 unless a numeric section argument is given.

roff bench

Benchmark parser performance over files in the manpath.

roff bench
roff bench --count 100
roff bench --all

Options

Example output

Manpath: /usr/share/man:/usr/local/share/man
Found 2847 man files, processing 100...
  Progress: 100/100

=== Benchmark Results ===
Files processed: 100
Files failed: 0
Total time: 1234 ms (1.23 s)
Avg time/file: 12.34 ms
Files/second: 81.04

bench parses each file to JSON and then to Markdown, reporting throughput and the first few errors.