diff --git a/README.md b/README.md index ec77314..37b0f0d 100644 --- a/README.md +++ b/README.md @@ -20,63 +20,40 @@ 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 +└── 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, 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 +- **`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) -``` - -### 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 +manwhere -s 1 -s 3 sleep # Search sections 1 and 3 ``` ### Help ```bash manwhere -h # Show help message -manwhere --help # Same as above ``` ## Man Page Sections @@ -98,30 +75,47 @@ manwhere --help # Same as above ### Build Commands ```bash -# Debug build (good for development) +# Debug build (for development) zig build -# Release build (maximum performance) -zig build -Doptimize=ReleaseFast - -# Clean build -zig build clean -``` - -### Install to ~/.local/bin -```bash +# Release build (installs to ~/.local/bin) zig build release ``` ## Performance -The tool is designed to be fast and efficient: +- **Typical search time**: ~10ms +- **Memory usage**: Minimal (streams results) +- **No database required**: Scans filesystem directly -- **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 +## 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 @@ -130,33 +124,6 @@ Works reliably on: - **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.