manwhere

A fast, simple command-line tool to search man pages by keyword, written in Zig.

Features

• Fast keyword search using man -k (apropos)
• Section filtering to search specific man page sections (1-9)
• Path resolution to show actual file locations
• Verbose mode with timing information
• POSIX compatible - works on Linux and macOS
• Simple and reliable - no complex dependencies

Project Structure

The project is organized into logical modules for maintainability:

src/
├── main.zig      # Main program entry point
├── types.zig     # Data structures and types
├── parser.zig    # Command line argument parsing
└── search.zig    # Man page search functionality

Module Responsibilities

• types.zig: Contains ManEntry, ManEntryList, and SearchConfig structures
• parser.zig: Handles command line argument parsing, validation, and help text
• search.zig: Manages man page searching and keyword matching

Usage

Basic Search

manwhere sleep              # Find all man pages mentioning "sleep"
# Output:
# sleep
# appsleepd

Interactive Selection with fzf

manwhere sleep | fzf | xargs man    # Select and open a man page

Section Filtering

manwhere -s 1 sleep         # Find only commands (section 1)
manwhere --section 3 sleep  # Find only library functions (section 3)
manwhere -s 1 -s 3 sleep    # Search sections 1 and 3

Help

manwhere -h                 # Show help message

Man Page Sections

• 1: Commands (user commands)
• 2: System calls
• 3: Library functions
• 4: Device files
• 5: File formats
• 6: Games
• 7: Miscellaneous
• 8: System administration
• 9: Kernel routines

Building

Prerequisites

• Zig 0.15.1 or later

Build Commands

# Debug build (for development)
zig build

# Release build (installs to ~/.local/bin)
zig build release

Performance

• Typical search time: ~10ms
• Memory usage: Minimal (streams results)
• No database required: Scans filesystem directly

Design Philosophy

This tool follows Unix philosophy: do one thing well and compose with other tools.

• No interactive mode: Use fzf, dmenu, or similar tools
• No descriptions: Fast name-only output
• No verbose mode: Silent operation for scripts
• No formatted output: Plain text for easy parsing

Example Workflows

Find and open a man page

manwhere printf | fzf | xargs man

Quick lookup with preview

manwhere sleep | fzf --preview 'man {}'

Scripting

# Find all SSL-related functions
manwhere ssl | while read name; do
    man 3 "$name" 2>/dev/null && break
done

POSIX Compatibility

Works reliably on:

• Linux: Standard /usr/share/man and /usr/local/share/man
• macOS: Standard paths plus Homebrew (/opt/homebrew/share/man) and MacPorts (/opt/local/share/man)
• Other Unix-like systems: Standard man page directory structures

License

This project is open source. See the source code for license details.