man-card/README.md

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

pip install man-card

From source

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:

# 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:

# 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:

# 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:

man-card list-templates

Preview Command

Preview command information in terminal:

man-card preview ls
man-card preview git -s 1

Parse Command

Parse and output structured data:

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:

{
    "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:

man-card generate ls --template custom

Configuration

Create a .env file in your project directory:

# 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

man-card generate ls grep git tar docker -o commands/

Create a PNG at high resolution

man-card generate docker --format png --dpi 300 -o docker_300dpi.png

Use minimal template for printing

man-card generate awk --template minimal -o awk_minimal.pdf

Create dark theme cards

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:

# 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:

# 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):

# For templates/my_template.json, use:
man-card generate ls --template my_template

Permission denied

Check output directory permissions:

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.