From c2c58c157c7b4338b0f6785bd8f27f4d6721bb1e Mon Sep 17 00:00:00 2001 From: 7000pctAUTO Date: Sat, 31 Jan 2026 21:39:43 +0000 Subject: [PATCH] Initial upload: man-card CLI tool with PDF/PNG generation, templates, and tests --- README.md | 298 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 297 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index bc52a46..35b853a 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,299 @@ # man-card -A CLI tool that parses man pages and generates beautiful, printable command reference cards \ No newline at end of file +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.