129 lines
3.1 KiB
Markdown
129 lines
3.1 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
|
|
```
|
|
|
|
### 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.
|