From 6070c018696b8c3c871fa2208b64fc9fd0525a52 Mon Sep 17 00:00:00 2001
From: jedarden <github@jedarden.com>
Date: Mon, 6 Jul 2026 17:59:11 -0400
Subject: [PATCH] docs(bf-2gfd1): document pdftract CLI text extraction flags

Identify and document the correct CLI flags for running pdftract in text
extraction/OCR mode. Verification: notes/bf-2gfd1.md.

Key findings:
- --text <PATH>: Output plain text to PATH (use '-' for stdout)
- --ocr: Enable OCR for scanned pages (requires 'ocr' feature)
- --ocr-language <OCR_LANGUAGE>: OCR language codes (comma-separated)

All acceptance criteria PASS (correct CLI subcommand identified, CLI help
confirms flags exist, flag syntax documented). Closes bf-2gfd1.
---
 notes/bf-2gfd1.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 notes/bf-2gfd1.md

diff --git a/notes/bf-2gfd1.md b/notes/bf-2gfd1.md
new file mode 100644
index 0000000..775f89e
--- /dev/null
+++ b/notes/bf-2gfd1.md
@@ -0,0 +1,64 @@
+# pdftract CLI Text Extraction Flags - Verification Note
+
+## Task
+Identify pdftract CLI text extraction flags for OCR mode and text extraction operations.
+
+## Findings
+
+### Primary Text Extraction Flags
+
+1. **`--text <PATH>`**
+   - **Purpose**: Output plain text to PATH (use '-' for stdout)
+   - **Type**: Output file path flag
+   - **Usage**: `pdftract extract input.pdf --text -` (for stdout)
+   - **Usage**: `pdftract extract input.pdf --text output.txt` (for file)
+
+2. **`--ocr`**
+   - **Purpose**: Enable OCR for scanned pages (requires 'ocr' feature)
+   - **Type**: Boolean flag
+   - **Requirement**: Requires 'ocr' feature to be enabled during build
+   - **Usage**: `pdftract extract input.pdf --ocr --text -`
+
+3. **`--ocr-language <OCR_LANGUAGE>`**
+   - **Purpose**: Specify OCR language codes (comma-separated)
+   - **Type**: Comma-separated language codes
+   - **Default**: 'eng' (English)
+   - **Examples**: 'eng,fra,deu' (English, French, German)
+   - **Usage**: `pdftract extract input.pdf --ocr --ocr-language eng,fra --text -`
+
+### Related Output Format Flags
+
+- **`--json <PATH>`**: Output JSON to PATH
+- **`--md <PATH>`**: Output Markdown to PATH  
+- **`--ndjson`**: Output NDJSON to stdout (mutually exclusive with other formats)
+- **`--format <FORMATS>`**: Comma-separated output formats (json,markdown,text,ndjson)
+
+## CLI Help Verification
+
+Ran `cargo run --bin pdftract -- extract --help` and confirmed all flags exist in the CLI help output.
+
+## Acceptance Criteria Status
+
+✅ **PASS**: Correct CLI subcommand identified - `extract` subcommand handles text extraction
+✅ **PASS**: CLI help confirms flags exist - all flags documented in help output  
+✅ **PASS**: Flag syntax is documented - each flag has clear usage syntax in help
+
+## Example Commands
+
+```bash
+# Basic text extraction to stdout
+pdftract extract document.pdf --text -
+
+# OCR-enabled text extraction
+pdftract extract scanned.pdf --ocr --text -
+
+# Multi-language OCR
+pdftract extract document.pdf --ocr --ocr-language eng,fra,deu --text output.txt
+
+# Combined format output (text + JSON)
+pdftract extract document.pdf --text - --json result.json
+```
+
+## Parent Bead Reference
+
+This task (bf-2gfd1) supports parent bead bf-677eo for understanding pdftract CLI capabilities in text extraction mode.