Resources, copies and surrogates

Pangur separates the thing you study from the files that show it. A manuscript, a book or a letter is a resource. Its pages or folios are its parts. Each photograph, PDF or IIIF image of it is a surrogate, and a set of surrogates made together is a copy. Keeping these apart is what lets one resource have several copies, say a library's digitisation, your own photographs and a later campaign under raking light, without anyone losing track of which image shows which folio.

Resources and itemsCopy Anchor Link

A resource is the thing the research is about. It might be a book, an article, a manuscript, a recording or a find from an excavation. Every library item is a resource, and so is a manuscript in the catalogue that has no library item yet.

An item is the library's entry for a resource, with its title, creators, date and other details. Most of the time the two coincide. The documentation says "item" when it means the library's entry and "resource" when it means the thing the entry describes.

PartsCopy Anchor Link

A part is a page, leaf, side or face of a resource. For a catalogued manuscript, the parts are its folios in the catalogue, and you add or rearrange them there. Any other item has parts of its own, which you add with Add parts… in the item's Pages and parts panel, as pages, leaves, sides or faces, up to 2,000 at a time.

A part can also be located inside a single file, as a page range of a PDF, a region of an image or a segment of a recording. This is how an item with one PDF can still have named parts.

SurrogatesCopy Anchor Link

A surrogate is one file that stands for a resource or for one of its parts. It can be a photograph you took, a file stored in your library (a PDF, a video, a document), or one canvas of a repository's IIIF manifest. A surrogate can record which part it depicts and its role, such as recto, verso, detail or watermark.

The word "surrogate" says what a file shows. "Attachment" is the library's word for a stored file considered simply as a file, and you meet it where you download or remove one.

CopiesCopy Anchor Link

A copy is a set of files that together show a resource. The photographs you took of a manuscript one afternoon are a copy, and so are a scan and a library's digitisation of a book. Each file in a copy is a surrogate. The MCP tools and the API call a copy a surrogate set, so list_surrogate_sets, create_surrogate_set and the related tools all work on copies.

A copy can record when it was made, who made it and who holds it, together with its method (how it was made, for example colour photography, a scan or raking light) and its purpose (why it was made, for example regular page photography or watermarks). Method, purpose and a surrogate's role are drawn from the project's vocabularies, which you can edit. Each project starts with four of them, called "Imaging method", "Imaging purpose", "Surrogate role" and "Surrogate set relation".

The copies of an item appear as cards along the top of its Read tab. Adding, editing and deleting them is covered in Manage copies and parts.

The reading copyCopy Anchor Link

The reading copy is the copy that Read, Ask and transcription open by default. Every resource has exactly one, and its card carries a ribbon that says Read opens this one. To change it, choose another copy and then Make reading copy.

If you have not chosen one, Pangur picks a reading copy itself. It prefers a copy that contains a PDF, then the most recent set of photographs, and otherwise the first copy. If you delete the reading copy or hand the role to another copy, Pangur picks again by the same rule.

The reading copy decides which files open. It is related to, but separate from, the item's text, which is what Ask, analysis and the reading room read. How the text is chosen is explained in How Pangur reads your sources.

Corrects and supplementsCopy Anchor Link

Two relations between copies change what Pangur shows. A copy can correct an earlier copy of the same resource, or it can supplement it.

When one copy corrects another, Pangur shows the correcting copy's images in place of the older copy's images for the parts that both cover. This is the relation to use when you rephotograph folios that came out of focus. A copy that supplements another instead adds a second view of those parts and replaces nothing, which is right for a campaign under ultraviolet or raking light that sits beside the ordinary photographs.

A copy can only relate to another copy of the same resource, and not to itself. You set the relation in the copy's details, under Relation, choosing between a copy that stands alone, one that corrects an earlier copy and one that supplements an earlier copy, and you name the Earlier copy it refers to. Any other words you type as a relation are kept and shown, but only "corrects" and "supplements" change what is displayed.

Note that it is the relation that decides what is shown, and not the date. A newer copy that stands alone does not replace anything.

RetakesCopy Anchor Link

A retake is a single surrogate that replaces one other surrogate of the same resource, for example a photograph taken again. The replaced surrogate stays in its copy but is shown faded and marked as replaced by a later surrogate.

Choosing the image for each partCopy Anchor Link

For each part of a resource, Pangur ranks the copies and shows the first surrogate that has not been replaced. Copies that correct the reading copy come first, then the reading copy itself, then copies that supplement it.

A surrogate counts as replaced when a retake names it, or when a correcting copy has a surrogate of its own for the same part. Within one copy, the photograph you have set as a folio's default is preferred. The Pages and parts panel can show every copy, the current surrogate for each part, or the files grouped by part, by purpose or by role, which lets you see which image is current for each part and why.

Copies Pangur creates automaticallyCopy Anchor Link

Files that are not yet in any copy are gathered into copies the first time the resource is read. Photographs become one copy per session, where a pause of more than 12 hours starts a new session, and each such copy is titled "Photographs" with the date and given the method "Colour photography". Each stored PDF, video, recording or document becomes a copy of its own, titled with the file's title. Loose images go together into one copy called "Images". A linked IIIF manifest from a repository becomes one copy with a surrogate for each canvas and the method "Scan".

A text file is read as the item's text and is not made into a copy. A file you take out of a copy is not gathered into a new one later.

Deleting copiesCopy Anchor Link

Deleting a copy takes its surrogates out of the resource. What happens to the files depends on what they are: the library files in the copy go into the project's trash, photographs stay in the catalogue, and a repository's IIIF canvases are untouched because Pangur does not hold them. Assistants cannot delete copies or surrogates.