Documentation
¶
Overview ¶
Package sectionize reconstructs a document's clause hierarchy.
The input is a doc.Document and, when the file has one, its structure tree. The output is a doc.Outline: a real tree of sections, each with a title, a level, its own content, and its children.
The package rests on one measured fact about how real specifications declare hierarchy. ISO 32000-2 contains 7 Sect elements against 981 headings, and a single Part holds 13,442 direct children in a flat H1 P P P … stream — 966 of those 981 headings have no element children at all. So a clause's body is not its heading's subtree; it is the heading's *following siblings*, up to the next heading of equal or higher rank. Collecting container elements would emit 7 sections from a 1,023-page standard, and would look correct on any document that happened to nest properly.
That makes the hierarchy a level stack over a linear sequence of headings rather than a subtree extraction, which is also why the same builder will serve the untagged path: a sequence of (level, title, content) triples is all it needs, and font-size clustering can produce those where a structure tree cannot.
This is also where roles are assigned. extract deliberately marks every block RoleParagraph, because heading rank, list nesting and cell membership are declared by the tree and inferring them from geometry as well would mean two packages guessing at the same thing from less evidence. The declared role arrives here.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var DefaultOptions = Options{MaxTitle: 200}
DefaultOptions is reconstruction as the CLI runs it.
Functions ¶
This section is empty.
Types ¶
type Options ¶
type Options struct {
// MaxTitle bounds a resolved title's length in bytes. A heading is short, so a
// title in the hundreds of characters means the join picked up something that is
// not the heading — a producer that put a whole paragraph in one marked-content
// sequence, most often. Truncating keeps the clause, where dropping the title
// would leave a section nothing can name. Zero means the default.
MaxTitle int
}
Options configures reconstruction.
type Stats ¶
type Stats struct {
// Sections is the total at every level. docs/DESIGN.md §8 puts ISO 32000-2 at
// roughly 981.
Sections int
// Titled is the sections whose title resolved to something.
Titled int
// Numbered is the sections whose title began with a clause number.
Numbered int
// MaxLevel is the deepest heading level reached.
MaxLevel int
// Blocks is the content blocks attributed to a section or to the preamble.
Blocks int
// UnplacedBlocks and UnplacedChars are the content that reached
// doc.Outline.Unplaced: text the extractor produced that no structure element
// claimed. A tagged document should have little, and what it has is a property of
// the file rather than of this join — ISO 32000-2 draws clause 1 outside any
// marked content — but a large number means the join is losing content, so it is
// reported rather than left to be noticed.
//
// Measured: 0 on ISO/TS 32005, 0.23% of characters on ISO 32000-2.
UnplacedBlocks int
UnplacedChars int
}
Stats reports what a reconstruction did, and exists because the failure modes here are quiet ones. A run that emits 7 sections from a standard has silently reverted to container-driven segmentation; a run that leaves half the text unclaimed has silently dropped it. Neither is an error and both are visible in these numbers.
func Tagged ¶
Tagged reconstructs the outline from a structure tree.
The tree supplies heading rank and reading order — both declared, which is the expensive part to infer — and the document supplies the text. They are joined on (page, MCID), so tag.Tree.ResolvePages must have run first; without it no element knows its page and every title and body comes back empty.
A nil tree yields an outline with no sections and the whole document as preamble. That is the honest result for an untagged file rather than an error: it means this path does not apply.
Source Files