.local-bin/scripts/manwhere

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

manwhere sleep              # Find all man pages mentioning "sleep"

Section Filtering

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

Verbose Mode

manwhere -v sleep           # Show timing and processing details
manwhere --verbose sleep    # Same as above

Path Resolution

manwhere --paths sleep      # Show file paths (slower but more detailed)

Combined Options

manwhere -v --paths -s 1 sleep  # Verbose, with paths, section 1 only

Help

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

# Debug build (good for development)
zig build

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

# Clean build
zig build clean

Install to ~/.local/bin

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.