pdf

# PDF Processing Guide

## Overview

This guide covers essential PDF processing operations using Python libraries and command-line tools. For advanced features, JavaScript libraries, and detailed examples, see REFERENCE.md. If you need to fill out a PDF form, read FORMS.md and follow its instructions.

## ⚠️ Important: Avoid Common Mistakes

**Problem**: PDF content overflow, missing text, no line wrapping

**Root Cause**: Using `drawString()` instead of `Paragraph()`

**❌ Wrong**:
```python
c = canvas.Canvas("output.pdf")
c.drawString(100, 750, "Long text will overflow and be lost...")
```

**✅ Correct**:
```python
from reportlab.platypus import SimpleDocTemplate, Paragraph
from reportlab.lib.styles import ParagraphStyle

doc = SimpleDocTemplate("output.pdf")
style = ParagraphStyle('Custom', fontName='STSong-Light', fontSize=11)
story = [Paragraph("Long text will wrap automatically", style)]
doc.build(story)
```

**📖 See**: [BEST_PRACTICES.md](BEST_PRACTICES.md) for detailed solutions

## Quick Start

### Creating PDFs (Recommended Approach)

```python
from reportlab.platypus import SimpleDocTemplate, Paragraph
from reportlab.lib.styles import ParagraphStyle
from reportlab.lib.pagesizes import A4
from reportlab.lib.units import cm
from reportlab.pdfbase import pdfmetrics
from reportlab.pdfbase.cidfonts import UnicodeCIDFont

# Register Chinese font
pdfmetrics.registerFont(UnicodeCIDFont('STSong-Light'))

# Create document
doc = SimpleDocTemplate("output.pdf", pagesize=A4,
                       rightMargin=2*cm, leftMargin=2*cm,
                       topMargin=2*cm, bottomMargin=2*cm)

# Create style
style = ParagraphStyle(
    'CustomBody',
    fontName='STSong-Light',
    fontSize=11,
    leading=16,
    firstLineIndent=22
)

# Build content
story = []
story.append(Paragraph("标题文本", ParagraphStyle('Title', fontName='STSong-Light', fontSize=18)))
story.append(Paragraph("正文内容会自动换行，不会超出页面边界。", style))

# Generate PDF
doc.build(story)
```

**Key Points**:
- ✅ Use `Paragraph` for automatic line wrapping
- ✅ Use `SimpleDocTemplate` for proper margins
- ✅ Register `STSong-Light` for Chinese text
- ✅ Use `Times-Roman` for English text (PDF built-in, no registration needed)

### Reading PDFs

```python
from pypdf import PdfReader

# Read a PDF
reader = PdfReader("document.pdf")
print(f"Pages: {len(reader.pages)}")

# Extract text
text = ""
for page in reader.pages:
    text += page.extract_text()
```

## Chinese Font Support

This skill includes intelligent font support with automatic font selection for Chinese and English text.

### Available Fonts

**Primary Fonts (Recommended)**:
- **STSong-Light (宋体)** - CIDFont, built-in to PDF readers, no file needed
- **Times-Roman (新罗马)** - PDF built-in font, similar to Times New Roman, no file needed

**Fallback Fonts (TTF/OTF)**:
- **Noto Serif CJK SC (宋体)** - OTF version, requires font file
- **Noto Sans CJK (黑体)** - Alternative Chinese font
- **WenQuanYi Zen Hei (文泉驿正黑)** - Alternative Chinese font
- **WenQuanYi Micro Hei (文泉驿微米黑)** - Lightweight Chinese font
- **Liberation Serif** - TTF version of Times New Roman

### Why CIDFont is Better

**STSong-Light (CIDFont)** advantages:
- ✅ **No font files needed** - Built into PDF readers
- ✅ **Smaller PDF files** - No font embedding required
- ✅ **Perfect compatibility** - Standard Adobe CID font
- ✅ **Full Unicode support** - Complete Chinese character set
- ✅ **Faster processing** - No font file loading
- ✅ **Avoids TTC errors** - No TTC format compatibility issues

### ⚠️ Important: TTC File Format Issue

**Problem**: ReportLab does not support TTC (TrueType Collection) font files.
- Error: `TTFError: TTC file "xxx.ttc": postscript outlines are not supported`
- TTC files like `NotoSerifCJK-Regular.ttc` cannot be used directly

**Solution**:
1. **Use CIDFont (STSong-Light)** - Recommended, no file needed
2. **Use OTF or TTF format** - Supported by ReportLab
3. **This skill automatically skips TTC files** - Prevents errors

**Supported Font Formats**:
| Format | Support | Description |
|--------|---------|-------------|
| CIDFont | ✅ Recommended | Built-in to PDF readers |
| OTF | ✅ Supported | OpenType fonts |
| TTF | ✅ Supported | TrueType fonts |
| TTC | ❌ Not supported | TrueType Collection, causes errors |

### Font Selection Rules

The system automatically selects fonts based on text content:
- **Chinese characters** → STSong-Light (宋体 CIDFont, PDF built-in)
- **English text and numbers** → Times-Roman (新罗马, PDF built-in)

**Important**: Both fonts are built into PDF readers - no font files needed!

### Register Fonts

```python
import sys
sys.path.append('scripts')
from register_fonts import register_chinese_fonts, get_chinese_font_name, get_english_font_name

# Register all available fonts
# Priority: CIDFont (STSong-Light) > TTF fonts
registered = register_chinese_fonts()

# Get recommended fonts
chinese_font = get_chinese_font_name()  # STSong-Light (CIDFont, PDF built-in)
english_font = get_english_font_name()  # Times-Roman (PDF built-in)
print(f"Chinese font: {chinese_font}")
print(f"English font: {english_font}")
```

**Note**: Both fonts are PDF built-in fonts, no font files needed!

### Using Fonts in PDF Creation

#### With reportlab (Built-in Fonts - Recommended)

```python
from reportlab.lib.pagesizes import letter
from reportlab.platypus import SimpleDocTemplate, Paragraph
from reportlab.lib.styles import getSampleStyleSheet, ParagraphStyle
from reportlab.pdfbase import pdfmetrics
from reportlab.pdfbase.cidfonts import UnicodeCIDFont

# Register CIDFont for Chinese (no font file needed!)
pdfmetrics.registerFont(UnicodeCIDFont('STSong-Light'))

# Create document with proper margins
doc = SimpleDocTemplate("output.pdf", pagesize=letter,
                       rightMargin=2*cm, leftMargin=2*cm,
                       topMargin=2*cm, bottomMargin=2*cm)

# Create styles
styles = getSampleStyleSheet()
body_style = ParagraphStyle(
    'CustomBody',
    parent=styles['Normal'],
    fontN