Module blocks 

Paragraphs and the blocks::Block model the structured serializers consume (#567). Paragraphs out of the lines a page draws (#567).

crate::text turns a page’s glyphs into lines: one TextBlock per band, in the order an XY-cut says the page is read in. That is where extraction stopped. A line is not a unit anybody chunks, cites or embeds – the unit is the paragraph, and the line breaks inside it are an accident of the measure the typesetter chose.

So this module merges lines into Blocks. It decides on geometry the page already carries, never on the words: leading, the left edge, the right edge, the type size, and the rules the document itself draws. Two lines join when nothing on that list says they are apart.

WHAT IT REFUSES TO CROSS, and why each one is a case rather than a rule

• A COLUMN GAP. Lines from two columns are never adjacent in the list the XY-cut produces, but the last line of the left column and the first of the right one are – and the second runs UP the page. A pair that does not descend, or whose horizontal extents barely meet, is two columns meeting.
• A TABLE. The page’s own ruling lines say “rows” where no geometry of the text can (#545), and an unruled table says it a second way: two lines with a wide gap at the same x is a gutter between cells, which is the one thing justified prose – the failure case this has to survive – cannot produce twice at the same place.
• A CHANGE OF TYPE. A heading, a caption and a footnote are set in something other than the body, and a paragraph that swallows one loses both. Size and WEIGHT both count: a document set in one size says “heading” with its bold face and nothing else, and a merge deaf to weight hands #568 a paragraph with the heading inside it.
• A LIST ITEM. The commonest list of all – one line per item, set solid at one left edge – differs from a paragraph in nothing the rails above measure, so a merge deaf to markers hands back one block with every bullet inside it. crate::lists says which lines a column has confirmed as items, and this refuses to merge into one (#569).

WHAT IT JOINS THAT LOOKS LIKE A BREAK

• A HANGING INDENT: the continuation lines of a bibliography entry are indented and belong to the entry above them. A FIRST-LINE INDENT is the same measurement with the opposite meaning, so the two are told apart once per column, from what sits ABOVE each indented line: a first-line indent follows the short last line of the paragraph before it, a hanging continuation follows a line that ran the full measure.
• A DROP CAP: an initial set three lines deep is drawn in the band of the third line, so the naive reading puts it in the middle of its own paragraph. It is taken out of that line’s geometry and put back at the front of the text.

The kind is BlockKind::Paragraph or, where the merge stopped at a confirmed marker, BlockKind::ListItem. A heading is decided afterwards instead: crate::headings reads the blocks a second time (#568), because that evidence is the whole DOCUMENT’s typography where a list’s is one column’s. A TABLE is taken out before the merge runs: crate::tables reads each region’s lines for the grid they stand in, those lines never reach the merge, and they come out one block per cell (#570). Running heads (#571) add their own variant, which is what #[non_exhaustive] is for.

Structs

Block

One block of a document’s structured text: what a caller chunks, cites or embeds.

ClipMargins

Clip margins in points: left, top, right, bottom.

ExtractOptions

Which part of the document crate::PdfDocument::extract_blocks and crate::PdfDocument::extract_markdown hand back (#573).

GridDoubt

What the heuristic table builder had to go on (#574).

HeadingOverride

One caller-supplied steering of what counts as a heading (lane L1).

TatrOptions

TATR table structure, opted into per call (track B, P3).

Enums

BlockKind

The kind of a block. Paragraphs (#567), headings (#568) and list items (#569); tables and running heads arrive with theirs (#570, #571).

OcrMode

Whether extraction recognizes pages that need it before reading them.

PageSeparators

How a change of page reaches the Markdown output of PdfDocument::extract_markdown.

Quality

Which tier reads the document: the shipping engine, or the layout model beside it (#641).

TableRenderMode

How a table reaches the Markdown: pipes, HTML, or the automatic choice between them (#659).

TableStrategy

Which evidence may find a table: the lines the page drew, the alignment of its words, or both (#659).