Initial upload: man-card CLI tool with PDF/PNG generation, templates, and tests
Some checks failed
CI / test (push) Has been cancelled
Some checks failed
CI / test (push) Has been cancelled
This commit is contained in:
298
README.md
298
README.md
@@ -1,3 +1,299 @@
|
||||
# man-card
|
||||
|
||||
A CLI tool that parses man pages and generates beautiful, printable command reference cards
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user