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

CLI arguments
Environment variables
.env file
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

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run tests: pytest tests/ -v
Submit a pull request

License

MIT License - see LICENSE file for details.