# When to Use `--mode technical` for PDF Extraction in book-to-skill

> Learn when to use --mode technical for PDF extraction in book-to-skill. Preserve code, tables, and layout accuracy for technical content. Understand the trade-off for structural fidelity.

- Repository: [Virgilio Junior/book-to-skill](https://github.com/virgiliojr94/book-to-skill)
- Tags: how-to-guide
- Published: 2026-08-28

---

**Use the `--mode technical` flag when your PDF contains code blocks, tables, or structured technical content that must retain exact syntax and layout, accepting slower processing (~1.5 seconds per page) in exchange for structural fidelity.**

The `book-to-skill` repository by virgiliojr94 provides a specialized extraction pipeline that processes PDFs into structured agent skills. By default, the tool interactively asks whether your source is **technical** or **text-heavy**, but you can override this behavior using the `--mode` flag to ensure precise handling of documentation, programming manuals, and reference materials.

## What `--mode technical` Does

The `book-to-skill` extractor supports two distinct processing pathways that handle PDF content fundamentally differently.

**Technical mode** invokes **Docling** via the `extract_with_docling` function to convert PDFs into markdown while preserving tables, code blocks, and exact whitespace. This ensures that programming syntax, API schemas, and tabular data remain intact for downstream processing.

**Text mode** (the default when unspecified) uses fast, plain-text tools like `pdftotext`, `pypdf`, and `pdfminer`. While significantly faster, these tools strip structural elements and retain only the narrative flow, making them unsuitable for technical documentation.

According to the [`README.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/README.md), the skill "asks you whether the book is **technical** or **text-heavy** and picks the right tool automatically," but the `--mode` flag allows you to bypass this interactive selection when you already know your document type.

## When to Choose Technical Mode Over Text Mode

Select `--mode technical` when your source material contains non-narrative elements that downstream agent skills must reference accurately.

### Content Types That Require Technical Mode

Use technical extraction for:
- Programming manuals with code examples
- API reference documentation containing schemas
- Technical standards with specification tables
- Academic papers with complex mathematical layouts
- Any PDF where table structure conveys semantic meaning

The [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) file indicates that technical books provide specialized **Code Examples** and **Reference Tables** sections, which rely on the exact markdown output that only Docling can generate. Without technical mode, these structural elements become garbled text, breaking the generated skill's utility.

### Performance Trade-offs

Technical mode delivers accuracy at a significant speed cost. A benchmark documented in [`docs/performance.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/performance.md) reveals that processing a 103-page technical PDF takes approximately **164 seconds** in technical mode versus only **48 seconds** in text mode.

Additionally, technical sections receive higher token budgets (approximately **1,800 tokens**) compared to prose-only sections (approximately **1,000 tokens**), as defined in the skill generation logic. This allocation reflects the density of information in structured technical content.

## How Technical Mode Works Internally

The extraction pipeline routes your request through three key components when `--mode technical` is specified.

### Argument Parsing and Validation

In [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py), the `parse_arguments` function (lines 36-68) parses the `--mode` flag and validates the input. If you provide an unrecognized value, the system defaults to `"text"` mode, making explicit flags critical for technical extraction.

### Extractor Selection

The PDF parser in [`book_to_skill/parsers/pdf.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/pdf.py) (lines 45-46) implements the mode selection logic:

```python
if extraction_mode == "technical":
    return extract_with_docling(str(pdf_path))

```

When the mode equals `"technical"`, the pipeline bypasses the fast text extractors and initializes the Docling-based extractor instead.

### Architectural Flow

As visualized in [`docs/architecture.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/architecture.md), the system makes a `BOOK_TYPE` decision (technical vs. text) that determines the entire downstream processing path. The [`docs/how-it-works.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/how-it-works.md) file illustrates how the technical branch maintains document structure through to the final skill generation, while the text branch optimizes for narrative coherence.

## Usage Examples

Force technical extraction when you know your document contains code or tables, bypassing the interactive prompt:

```bash

# Force technical extraction to preserve tables and code blocks

python -m book_to_skill extract path/to/manual.pdf --mode technical

```

Use text mode for speed when processing prose-heavy content:

```bash

# Fast extraction for novels or plain text documents

python -m book_to_skill extract path/to/book.pdf --mode text

```

Allow automatic detection when you're unsure of the content type:

```bash

# Interactive mode - the tool will ask whether the PDF is technical

python -m book_to_skill extract path/to/unknown.pdf

```

The entry point in [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) forwards your `--mode` selection directly to the core utilities, ensuring consistent behavior across the extraction pipeline.

## Summary

- Use `--mode technical` for PDFs containing code, tables, or structured layouts that must retain exact formatting
- Technical mode uses Docling via `extract_with_docling` and allocates ~1,800 tokens per section versus ~1,000 for text mode
- Expect processing times roughly 3x slower than text mode (benchmark: 164s vs 48s for 103 pages)
- The `parse_arguments` function in [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py) handles CLI validation, defaulting to text mode if invalid input is provided
- Source files including [`book_to_skill/parsers/pdf.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/pdf.py) and [`docs/performance.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/performance.md) document the implementation details and benchmarks

## Frequently Asked Questions

### How much slower is technical mode compared to text mode?

According to benchmarks in [`docs/performance.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/docs/performance.md), technical mode processes approximately 1.5 seconds per page, while text mode completes in roughly 0.47 seconds per page. For a 103-page document, this translates to approximately 164 seconds versus 48 seconds total processing time.

### Can I switch modes after extraction has started?

No, the extraction mode is determined at the outset when [`book_to_skill/parsers/pdf.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/pdf.py) selects the extractor function. Once the pipeline initializes either `extract_with_docling` or the fast text tools, you must restart the process with the correct `--mode` flag to change methodologies.

### Why does technical mode get more tokens per section?

The skill generation logic in [`SKILL.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/SKILL.md) allocates higher token budgets (~1,800 tokens) to technical sections because code blocks and tables contain dense information that requires more context window space to represent accurately, whereas prose-only sections (~1,000 tokens) contain more redundant narrative text.

### What happens if I don't specify a mode?

If you omit the `--mode` flag, the extraction script in [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) triggers an interactive prompt that asks whether your book is technical or text-heavy, then routes the PDF through the appropriate pathway automatically. This behavior is documented in the repository's [`README.md`](https://github.com/virgiliojr94/book-to-skill/blob/main/README.md).