300 lines
5.7 KiB
Markdown
300 lines
5.7 KiB
Markdown
# man-card
|
|
|
|
A CLI tool that parses man pages and generates beautiful, printable command reference cards. It extracts usage examples, options, and arguments from man pages into formatted PDF/PNG reference cards perfect for developers and sysadmins to keep at their desk or in digital notebooks.
|
|
|
|
## Features
|
|
|
|
- Parse man pages for any command
|
|
- Extract usage examples, options, and arguments
|
|
- Generate professional PDF reference cards
|
|
- Generate PNG images for digital notebooks
|
|
- Multiple built-in templates (default, minimal, compact, dark)
|
|
- Custom template support via JSON files
|
|
- Batch processing for multiple commands
|
|
- Configuration via environment variables or .env file
|
|
|
|
## Installation
|
|
|
|
### Using pip
|
|
|
|
```bash
|
|
pip install man-card
|
|
```
|
|
|
|
### From source
|
|
|
|
```bash
|
|
git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/man-card
|
|
cd man-card
|
|
pip install -e .
|
|
```
|
|
|
|
### Dependencies
|
|
|
|
- Python 3.9+
|
|
- click (CLI framework)
|
|
- fpdf2 (PDF generation)
|
|
- Pillow (PNG generation)
|
|
- rich (Enhanced CLI output)
|
|
- python-dotenv (Configuration)
|
|
|
|
## Quick Start
|
|
|
|
Generate a reference card for a command:
|
|
|
|
```bash
|
|
# Generate PDF card (default)
|
|
man-card generate ls -o ls_card.pdf
|
|
|
|
# Generate PNG card
|
|
man-card generate ls --format png -o ls_card.png
|
|
|
|
# Use a different template
|
|
man-card generate ls --template dark -o ls_dark.pdf
|
|
|
|
# Preview in terminal
|
|
man-card preview ls
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Generate Command
|
|
|
|
Generate a reference card for one or more commands:
|
|
|
|
```bash
|
|
# Single command
|
|
man-card generate grep
|
|
|
|
# Multiple commands
|
|
man-card generate ls grep git
|
|
|
|
# Specify output format
|
|
man-card generate ls --format pdf -o ls_reference.pdf
|
|
man-card generate ls --format png -o ls_reference.png
|
|
|
|
# Use a specific template
|
|
man-card generate ls --template dark
|
|
man-card generate ls --template minimal
|
|
|
|
# Set DPI for PNG output
|
|
man-card generate ls --format png --dpi 300 -o ls_high_res.png
|
|
|
|
# Set page size for PDF
|
|
man-card generate ls --page-size letter
|
|
|
|
# Specify man page section
|
|
man-card generate passwd --section 1
|
|
```
|
|
|
|
### Batch Processing
|
|
|
|
Process multiple commands from a file:
|
|
|
|
```bash
|
|
# Create a file with commands (one per line)
|
|
echo -e "ls\ngrep\ngit\ntar" > commands.txt
|
|
|
|
# Generate cards for all commands
|
|
man-card generate -i commands.txt -o output/
|
|
|
|
# This creates:
|
|
# output/ls_card.pdf
|
|
# output/grep_card.pdf
|
|
# output/git_card.pdf
|
|
# output/tar_card.pdf
|
|
```
|
|
|
|
### List Templates
|
|
|
|
View available templates:
|
|
|
|
```bash
|
|
man-card list-templates
|
|
```
|
|
|
|
### Preview Command
|
|
|
|
Preview command information in terminal:
|
|
|
|
```bash
|
|
man-card preview ls
|
|
man-card preview git -s 1
|
|
```
|
|
|
|
### Parse Command
|
|
|
|
Parse and output structured data:
|
|
|
|
```bash
|
|
man-card parse ls
|
|
man-card parse ls --format json
|
|
```
|
|
|
|
## Templates
|
|
|
|
man-card includes four built-in templates:
|
|
|
|
### default
|
|
Clean, professional look suitable for printing.
|
|
|
|
### minimal
|
|
Simple black and white design, minimal styling.
|
|
|
|
### compact
|
|
High-density layout, fits more options per card. Dark theme.
|
|
|
|
### dark
|
|
Dark background with colorful accents.
|
|
|
|
### Custom Templates
|
|
|
|
Create custom templates using JSON files:
|
|
|
|
```json
|
|
{
|
|
"layout": {
|
|
"header_height": 60,
|
|
"section_spacing": 20,
|
|
"option_spacing": 10,
|
|
"margin": 30,
|
|
"columns": 2
|
|
},
|
|
"colors": {
|
|
"header_bg": "#2E3440",
|
|
"header_text": "#FFFFFF",
|
|
"section_title": "#88C0D0",
|
|
"option_flag": "#A3BE8C",
|
|
"option_desc": "#ECEFF4",
|
|
"background": "#FFFFFF",
|
|
"border": "#4C566A"
|
|
},
|
|
"fonts": {
|
|
"header": ["Helvetica-Bold", 24],
|
|
"section": ["Helvetica-Bold", 14],
|
|
"option_flag": ["Courier-Bold", 10],
|
|
"option_desc": ["Helvetica", 9],
|
|
"synopsis": ["Courier", 11],
|
|
"body": ["Helvetica", 10]
|
|
},
|
|
"spacing": {
|
|
"line_height": 14,
|
|
"margin": 20,
|
|
"section_padding": 15
|
|
}
|
|
}
|
|
```
|
|
|
|
Save custom templates to `templates/custom.json` and use with:
|
|
|
|
```bash
|
|
man-card generate ls --template custom
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Create a `.env` file in your project directory:
|
|
|
|
```bash
|
|
# Default output format (pdf or png)
|
|
MANCARD_DEFAULT_FORMAT=pdf
|
|
|
|
# Default DPI for PNG output
|
|
MANCARD_DEFAULT_DPI=150
|
|
|
|
# Default template name
|
|
MANCARD_DEFAULT_TEMPLATE=default
|
|
|
|
# PDF page size (a4 or letter)
|
|
MANCARD_PAGE_SIZE=a4
|
|
```
|
|
|
|
Configuration precedence (highest to lowest):
|
|
1. CLI arguments
|
|
2. Environment variables
|
|
3. .env file
|
|
4. Hardcoded defaults
|
|
|
|
## Examples
|
|
|
|
### Generate cards for common commands
|
|
|
|
```bash
|
|
man-card generate ls grep git tar docker -o commands/
|
|
```
|
|
|
|
### Create a PNG at high resolution
|
|
|
|
```bash
|
|
man-card generate docker --format png --dpi 300 -o docker_300dpi.png
|
|
```
|
|
|
|
### Use minimal template for printing
|
|
|
|
```bash
|
|
man-card generate awk --template minimal -o awk_minimal.pdf
|
|
```
|
|
|
|
### Create dark theme cards
|
|
|
|
```bash
|
|
man-card generate python --template dark -o python_dark.pdf
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### "Command not found" error
|
|
|
|
Ensure the command has a man page installed. On Linux, install man-pages:
|
|
|
|
```bash
|
|
# Debian/Ubuntu
|
|
sudo apt-get install man-db
|
|
|
|
# macOS
|
|
man command_name
|
|
```
|
|
|
|
### Missing fonts
|
|
|
|
If fonts don't render correctly, ensure you have DejaVu fonts installed:
|
|
|
|
```bash
|
|
# Debian/Ubuntu
|
|
sudo apt-get install fonts-dejavu
|
|
|
|
# Fedora
|
|
sudo dnf install dejavu-sans-fonts
|
|
```
|
|
|
|
### Template not found
|
|
|
|
Ensure template name matches the JSON filename (without extension):
|
|
|
|
```bash
|
|
# For templates/my_template.json, use:
|
|
man-card generate ls --template my_template
|
|
```
|
|
|
|
### Permission denied
|
|
|
|
Check output directory permissions:
|
|
|
|
```bash
|
|
mkdir -p output
|
|
man-card generate ls -o output/ls.pdf
|
|
```
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make your changes
|
|
4. Add tests for new functionality
|
|
5. Run tests: `pytest tests/ -v`
|
|
6. Submit a pull request
|
|
|
|
## License
|
|
|
|
MIT License - see LICENSE file for details.
|