Skip to main content
The content of a record comes as one Markdown string by default, and inside it are sections and blocks, each with an id. These ids are the addresses that make a long source readable in parts and a passage citable.

A section is a heading with everything under it

A section starts at a heading and runs to the next heading of the same level or a higher one. The outline of a record lists the sections, each with its id, its title, its level, and its size in characters. The size includes the sections under it. The text before the first heading is a section too, with the id s0. On a source without headings, s0 is the whole text. Sections come from the source. On a web page they are the page’s headings. In a document they are the document’s own structure or, in a PDF without structure, the PDF’s own outline. A scan, or a document with neither, gets one section for each page. The field basis on a section says which of these it is.

A block is one unit of content

A block is the smallest part with an address, such as one paragraph, one heading, one table, or one image. A block has an id, a kind, the section it is in, and its size.
These 3 blocks are from one scientific paper: a paragraph, the formula it introduces, and the code that computes it. Each block is cut to the fields that differ by kind.
3 blocks of a paper
Bold text in a paragraph comes as Markdown. The formula comes as TeX, and the code comes as one block with its language. None of the 3 is cut in the middle, because a block ends where the author ended it. A paragraph that runs across a page break of a document is one block. A table that continues over several pages is one block too.

A place has up to 5 parts

A highlight, a filled field, and a change in a comparison each come with a place. A place is not a count of characters from the start of the text. Such a count changes with the format and with every mark that is added to the text. A block id does not. The page has 2 fields. page_number is the position of the page in the file, and page_label is the label printed on the page, where the document declares one. A report cites “page iv” as the document prints it, and a program opens the 6th page of the file.

Ids are the same on every read

The ids of a record’s sections and blocks do not change, whatever the call and whoever makes it. Under one version and one configuration of getclean, a second fetch of the same source gives the same ids again. Each view of a web page has its own ids. A block of the view main has another id in the view whole_page, so read a place in the view it was found in.