# 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
├── display.zig   # Output formatting and display
└── performance.zig # Essential performance optimizations
```

### 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, parsing, and path resolution
- **`display.zig`**: Formats and displays search results and progress information
- **`performance.zig`**: Essential optimizations for fast string operations and I/O
- **`main.zig`**: Orchestrates the program flow and coordinates between modules

## Performance Features

The tool is optimized for speed while maintaining simplicity:

- **Early filtering**: Section filtering happens during parsing for better performance
- **Efficient I/O**: Optimized buffer sizes and reading strategies
- **Fast string operations**: Optimized string comparisons for common cases
- **Memory efficiency**: Exponential growth strategy for collections
- **POSIX optimization**: Common man page directories checked first

## Usage

### Basic Search
```bash
manwhere sleep              # Find all man pages mentioning "sleep"
```

### Section Filtering
```bash
manwhere -s 1 sleep         # Find only commands (section 1)
manwhere --section 3 sleep  # Find only library functions (section 3)
```

### Verbose Mode
```bash
manwhere -v sleep           # Show timing and processing details
manwhere --verbose sleep    # Same as above
```

### Path Resolution
```bash
manwhere --paths sleep      # Show file paths (slower but more detailed)
```

### Combined Options
```bash
manwhere -v --paths -s 1 sleep  # Verbose, with paths, section 1 only
```

### Help
```bash
manwhere -h                 # Show help message
manwhere --help             # Same as above
```

## 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 (good for development)
zig build

# Release build (maximum performance)
zig build -Doptimize=ReleaseFast

# Clean build
zig build clean
```

### Install to ~/.local/bin
```bash
zig build release
```

## Performance

The tool is designed to be fast and efficient:

- **Typical search time**: 700-800ms for common keywords
- **Section filtering**: 20-30% faster than searching all sections
- **Path resolution**: Adds ~200-300ms for detailed results
- **Memory usage**: ~8-12MB for typical searches
- **Scalability**: Handles large result sets efficiently

## 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

## Error Handling

The program provides clear error messages for:
- Invalid command line options
- Missing required arguments
- Invalid section numbers
- Multiple keywords (not supported)
- Search failures

## Why Simple and Fast?

This tool prioritizes:
1. **Reliability** - Works consistently across POSIX systems
2. **Speed** - Essential optimizations without complexity
3. **Simplicity** - Easy to understand, maintain, and debug
4. **POSIX compatibility** - No platform-specific dependencies
5. **Performance** - Fast enough for daily use without over-engineering

## Contributing

The simple structure makes it easy to:
- Add new search features
- Implement different output formats
- Add support for additional platforms
- Extend the man page section detection
- Optimize performance further

## License

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