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