Skip to content

LearnIngest & extract

Reading order

The sequence in which a page's text blocks should be read. Columns, sidebars and captions make it differ from plain top-to-bottom, left-to-right order.

In DocSlurpIllustrated explainer

On this page
A two-column page read straight across versus column by columnThe same page has a title and two columns of three lines. Read straight across, the order is left line 1, right line 1, left line 2, right line 2, and so on, and the extracted text splices the sentences: "Revenue is projected at Operating margin lands $48.2M, up 31% year over at 24%, four points year, 12% ahead of plan. above the 20% target." Read column by column, the left column comes first, then the right, and the text is two clean sentences: "Revenue is projected at $48.2M, up 31% year over year, 12% ahead of plan. Operating margin lands at 24%, four points above the 20% target."Naive: straight across the page4.3 FY2027 projectionRevenue is projected at1$48.2M, up 31% year over3year, 12% ahead of plan.5Operating margin lands2at 24%, four points4above the 20% target.6left columnright columnEXTRACTED TEXTRevenue is projected at Operating marginlands $48.2M, up 31% year over at 24%,four points year, 12% ahead of plan. abovethe 20% target.Column-aware: finish a column first4.3 FY2027 projectionRevenue is projected at1$48.2M, up 31% year over2year, 12% ahead of plan.3Operating margin lands4at 24%, four points5above the 20% target.6left columnright columnEXTRACTED TEXTRevenue is projected at $48.2M, up 31%year over year, 12% ahead of plan.Operating margin lands at 24%, four pointsabove the 20% target.
Read a two-column page straight across and every line splices two sentences. Teal words come from the left column, violet from the right. The naive order alternates colors on every line; the column-aware order produces two solid runs, which is what a chunk and its embedding need. Every word is correct in both versions, which is why this error slips past spell checks and word-accuracy metrics.

The problem: two sentences, one line

Page 15 of growth-plan-2027.pdf is set in two columns. The left column says “Revenue is projected at $48.2M, up 31% year over year, 12% ahead of plan.” The right column says “Operating margin lands at 24%, four points above the 20% target.”

An extractor that reads the page the obvious way, top to bottom and left to right across the full width, produces this:

Revenue is projected at Operating margin lands
$48.2M, up 31% year over at 24%, four points
year, 12% ahead of plan. above the 20% target.

Every word is correct. Every word is spelled right, so no spell check or plausibility score complains. And yet the text is useless: a chunk built from it splices the revenue sentence into the margin sentence, its embedding sits halfway between two topics, and a question about how far margin beats its target retrieves a passage that answers it in shuffled fragments.

Why the order isn’t in the file

You might expect a PDF to store text in reading order. It stores drawing instructions, in whatever order the authoring software emitted them (see PDF text layer). Sometimes that order is right. Often the header is drawn last, columns are drawn line by line, or a text box added in revision is drawn at the very end. A scanned page has no order at all, only word positions from OCR. So extractors sort by position, and position alone is ambiguous.

Recovering the order

Find the gutters. Columns are separated by a vertical strip of whitespace that runs through many lines. Find those strips and you know where one column ends and the next begins. A line that crosses the gutter, such as a title or a figure spanning the full width, starts a new band. Within each band, read column 1 top to bottom, then column 2, then move to the next band.

Recursive XY-cut. A classic algorithm from the 1990s does the same thing as a tree. Find the widest horizontal whitespace gap and cut the page there. Then find the widest vertical gap in each piece and cut again. Alternate until no gaps remain. Reading the leaves of the tree in order gives the reading order.

Worked on the page in the figure:

  1. A horizontal cut separates the title band from the body.
  2. A vertical cut at the gutter splits the body into left and right columns.
  3. Each column is cut horizontally into its three lines.
  4. Reading the leaves in order: title, left lines 1 to 3, right lines 1 to 3.

Learned ordering. Models such as LayoutReader take every word with its box and predict the sequence directly. They learn conventions that geometry alone misses, like reading a caption after its figure.

DocSlurp’s native PDF engine uses the gutter approach: it finds vertical whitespace gutters, groups lines into bands, reads each band’s columns left to right and top to bottom, and reads a narrow left sidebar after the main text. It also checks its own output, comparing the last words of each segment with the first words of the next in the same column, and flags pages where the Markdown interleaves columns.

Where it breaks

  • Sidebars and pull quotes. A boxed note beside the main text has no single correct position. Before, after, or at the paragraph it annotates? Any choice is a convention.
  • Captions and footnotes. A caption belongs with its figure, not wherever its y coordinate falls. Footnotes belong at the end of the page, or at their reference.
  • Uneven columns. If one column has a figure and the other doesn’t, there may be no gutter that runs the full height. Simple gutter finders then treat the page as one column.
  • Right-to-left and vertical scripts. Arabic and Hebrew read right to left; traditional Chinese and Japanese can read in vertical columns from right to left. Left-to-right rules scramble them.
  • Tables. A table is its own reading-order problem: row by row, with every cell tied to its headers. See table extraction.
  • Articles that jump. Magazines and newsletters continue a story on a later page. No single-page algorithm can follow “continued on page 7”.

Measuring it

Reading-order errors keep every word, so word-level accuracy metrics miss them. Score the order directly: tokenize the extracted text and a reference transcript, and compare the sequences with an order-sensitive similarity such as the ratio from Python’s difflib.SequenceMatcher. Interleaved columns lose points; harmless markup differences do not. DocSlurp’s engine benchmarks score reading order this way.

For a pipeline, the practical rule is simpler: if a page has more than one column, inspect the extracted text for one or two pages before trusting the rest. Spliced sentences are easy for a person to spot and very hard for a metric to notice. Vision models are told the rule explicitly; DocSlurp’s page prompt asks the model to finish each column before starting the next.

In DocSlurp

In DocSlurp

The native PDF engine finds vertical gutters, reads each band's columns left to right and top to bottom, and flags Markdown that interleaves columns (core/worker/src/native-pdf/assemble.ts). Vision prompts ask the model to finish each column before the next (core/worker/src/tools/vision-model-profiles.ts). A bench script scores reading order by word-sequence similarity (core/worker/src/native-pdf/score_reading_order.py).

Sources

Jump to