Editorial tools¶

Helper commands for manuscript cleanup, indexing, and PDF post-processing. Most operate on chapter*/*.md under the project root.

Chinese text normalization¶

Target Simplified Chinese sources (*_zh.md):

bubble-fix-zh-period
bubble-fix-zh-punct
bubble-fix-zh-quotes

Run from the book repo root. Review diffs before committing — these are batch text transforms.

Markdown style checks¶

# Whole-line *single-star* emphasis → _underscore_ (excludes chapter title line 3)
bubble-single-star
bubble-single-star --include-merged
bubble-single-star --write

# Headings that should not be bold
bubble-bold-headings

# Colon-separated list consistency
bubble-check

# Built PDF: leaked equation labels and unresolved cross-references
bubble-pdfcheck
bubble-pdfcheck book_square.pdf
bubble-pdfcheck --labels-only

Index and structure¶

bubble-index                    # add index terms to Markdown
bubble-extract-chapter-title    # extract title quote from chapter front matter
bubble-count-chars              # character counts

Code and math blocks¶

bubble-add-code-annotations
bubble-process-code-annotations
bubble-process-code-explain
bubble-add-math-summaries

These prepare or post-process Pandoc/Lua filter markers used during PDF build.

Includes and preprocessing¶

bubble-process-includes         # expand {% include %} directives

Run automatically during bubble-convert / bubble-build, but can be invoked standalone for debugging.

Images and tables¶

bubble-image clean              # chapter*/img PNGs with matching .py + cover/*/out images/PDFs
bubble-image clean --dry-run    # preview deletions
bubble-set-image-dpi            # DPI metadata
bubble-convert-svg-text         # SVG foreignObject → text for LaTeX
bubble-fix-table-width          # wide table fixes

`bubble-p2p` ("picture to picture")¶

Pastes a shrunk, bordered copy of one picture into a corner of another — e.g. a book cover badge onto a chapter mindmap PNG, handy for turning a plain mindmap into a shareable promo graphic. If a companion <name>_thumb.jpg exists next to the base image (the convention used for chapter mindmaps), it's resized and overwritten to match, so the image and its thumbnail never drift apart.

# Paste the KDP cover into the top-left corner of a chapter mindmap,
# overwriting mindmap.png in place and syncing mindmap_thumb.jpg
bubble-p2p \
    chapter1-introduction-to-modern-distributed-ai/img/mindmap.png \
    cover/7x10/amazon_cover.jpg \
    --width 430

# Write to a new file instead of overwriting, top-right corner
bubble-p2p img/mindmap.png cover/7x10/amazon_cover.jpg \
    --output img/mindmap_with_cover.png --corner top-right

# Skip thumbnail syncing, custom margin and border color
bubble-p2p img/mindmap.png cover.jpg \
    --no-thumb --margin 60 --border-color "#c9d7ea"

Flag	Default	Purpose
`--output`	overwrite base image	Where to write the merged image
`--width` / `--width-frac`	`0.16` × base width	Overlay badge size in px or as a fraction
`--corner`	`top-left`	`top-left`, `top-right`, `bottom-left`, `bottom-right`
`--margin`	`40`	Margin from the corner, in px
`--border-width` / `--border-color`	`4` / `#c9d7ea`	Badge border — keep it light, not black, so it doesn't look heavy
`--thumb` / `--no-thumb`	auto-detect `<base-stem>_thumb.jpg`	Companion thumbnail to keep in sync

PDF post-processing¶

bubble-add-watermark INPUT.pdf --text "DRAFT"
bubble-protect-pdf book.pdf     # anti-OCR rasterization (--protect-dpi)
bubble-reorder-cover-preface    # cover/preface page order
bubble-split-pdf book.pdf -n 5  # split for upload
bubble-docx-footer              # Word header/footer patches

Cover generation¶

bubble-gen-cover-bg             # matplotlib cover background
bubble-gen-latex-header         # debug LaTeX header generation
bubble-gen-toc                    # standalone TOC generation

bubble-gen-cover-bg requires matplotlib and numpy.

LaTeX debugging¶

bubble-latex-multi-pass         # multi-pass LaTeX with index

Useful when isolating LaTeX failures outside the full build orchestrator.