162 lines
4.5 KiB
Markdown
162 lines
4.5 KiB
Markdown
# 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.
|