# 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
```bash
manwhere sleep              # Find all man pages mentioning "sleep"
# Output:
# sleep
# appsleepd
```

### Interactive Selection with fzf
```bash
manwhere sleep | fzf | xargs man    # Select and open a man page
```

### Section Filtering
```bash
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
```bash
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
```bash
# 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
```bash
manwhere printf | fzf | xargs man
```

### Quick lookup with preview
```bash
manwhere sleep | fzf --preview 'man {}'
```

### Scripting
```bash
# 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.