Arrangements, source groups and vocabularies

An arrangement is a tree of your own design over a project's sources. The catalogue records how an archive arranges its holdings; an arrangement records how you want to arrange them. You might divide a letter-book into its letters, lay out a calendar of correspondence by year and correspondent, or group an edition's witnesses by family. The API and the MCP tools call an arrangement a perspective.

An arrangement has levels, such as Year › Correspondent › Letter, and nodes placed on those levels. A node can stand for a whole library item, a catalogued manuscript, one leaf or a region of a leaf, a stretch of an item's text, a part of a resource, a photograph or a source group, or it can simply be a label with nothing behind it. Each level can carry fields, so that every node on it records a date, a place or a correspondent, for instance.

Arrangements belong to the project, so everyone who works in it sees the same ones. Placing something in an arrangement changes nothing in the library, and deleting an arrangement or a node leaves the items where they were.

Creating an arrangementCopy Anchor Link

The tabs above the library list show Library, Catalogue and then your arrangements. The first two are built in and cannot be renamed or deleted.

1. Choose + (New arrangement) at the end of the tabs, give the arrangement a Name and choose Create.
2. Choose Levels… and then Add level for each depth of the tree, working from the top down. A new level always goes below the deepest one.
3. If you want the nodes on a level to carry fields, choose Fields… beside that level (see Fields on a level).
4. Choose New node… to add the first node. Until at least one level exists, the button says Add a level first.

The ⋯ menu on an arrangement's tab offers Rename and Delete…. Deleting an arrangement deletes its nodes, but the items they stood for stay in your library.

You can move between the tabs with the left and right arrow keys, Home and End.

Levels and nestingCopy Anchor Link

By default an arrangement has fixed nesting, which means a node's level is its depth: every node directly under a Year is a Correspondent. When your material is less regular, turn on Allow flexible nesting. Any kind of node can then sit under any other, and New node… asks for the node's Type. To turn flexible nesting off again, every node must first stand on its fixed level, and Pangur tells you if one does not.

In Levels… you can rename a level or delete it. Only the deepest level can be deleted, and only once no nodes stand on it.

Fields on a levelCopy Anchor Link

Fields… beside a level lists the fields its nodes carry. For each field you set:

An inherited value is shown together with the node it comes from. Typing a blank value on a node stops the inheritance at that point. If you remove a field, the values already recorded under it are kept and marked as no longer belonging to a field.

Pangur checks values when it shows them and lists any problems it finds: a required field left empty, a value of the wrong type, a term that is not in the vocabulary, an authority of the wrong kind. It does not refuse to save such values, so an arrangement can be filled in gradually.

Adding nodes and sourcesCopy Anchor Link

Each node in the tree has a menu (the ⋯ button, or right-click). New node inside… adds a node on the level below. Add source inside… places a source under the node; its dialog has tabs for a Library item, a Catalogue manuscript and a Leaf, and for a leaf you choose an item with a ready facsimile, pick the leaf, and then Use whole leaf or select a region and Use selected region. Read from here opens the reading room on this node and everything below it, in the arrangement's order. The menu also offers Rename, Move to… (which asks for a New parent or Top level), Move up and Move down, and Delete…, which removes the node and every node inside it while leaving the items they stood for in your library.

The tree has no drag and drop, so moving is done with Move to…, Move up and Move down.

You can also place things in an arrangement from elsewhere in the app with Add to arrangement…, which asks for the Arrangement and where to Place under. It is available from the library's bulk bar (Add to… › An arrangement) for several items at once, from an item's Study › Arrangements tab (which also lists where the item is already placed), from Parts of this item for a part, and from a source group. If some of the sources cannot be placed, Pangur places the rest and lists the failures.

Some kinds of source can appear only once in an arrangement: a leaf, a region, a catalogued manuscript, a stretch of text and a part. If you try to place one of these a second time, Pangur refuses and names the node that already holds it. A library item, a source group or a photograph can appear at several nodes. An arrangement with flexible nesting skips this check altogether.

Dividing an item into textsCopy Anchor Link

Many sources hold several texts in one file: a letter-book, a volume of sermons, a register. Divide into texts… on an item's Read tab places each text as its own node in an arrangement, under the item's node. It works only when the item's text is read from a file or from a stretch of text, and the arrangement needs one level for the item and another below it for its texts.

1. Choose the Arrangement and, under Under, where the item's node should go.
2. Under How, either choose Mark where each text begins and click where each one starts (naming it if you wish), or choose Use the texts an Analysis reading found, which takes the divisions from the item's existing analysis. No model is run in either case.
3. Choose Place the texts.

Texts must not overlap, so each one begins where the one before ends. Dividing the same item again skips texts that are already placed. Up to 2,000 texts can be placed at once.

From the command line, pangur arrange-texts KEY --arrangement ID does the same, with --spans FILE or --from-analysis. An assistant can use the arrange_texts tool.

Reading an arrangementCopy Anchor Link

Read in the arrangement's header opens the reading room on the whole arrangement, depth first, in the order you gave the nodes. When an item is placed in an arrangement, the arrangement's texts become the text Pangur reads for that item (see Read a source).

Reading layout… ties an arrangement to a corpus. When the reading room reads that corpus, it can then take each record's identity, heading and dates from the arrangement's fields. A corpus can have one reading layout at a time, so to choose another you first turn off the current one.

Photographing into an arrangementCopy Anchor Link

Capture here… on a node photographs pages straight into the arrangement. Name the capture, give its language if you wish, and choose or take the photographs. Pangur creates a manuscript library item and a source group called "Capture" for them, places the group under the node, and adds the photographs as its pages.

If the connection drops part-way, the photographs are kept in the browser and sent one at a time when the connection returns.

Source groupsCopy Anchor Link

A source group is a named, ordered list of sources that you can reuse. Its members can be library items, catalogued manuscripts, pages, photographs or other groups. Use one when several things belong together but are not one item, such as the three leaves of a letter that are scattered through a volume. Each group has a Group name and a Type.

To create a group, select pages in an item's parts and choose Group selected pages…. Edit group… renames it, reorders its members with Move up, removes one with Remove from group, and adds one with Add a member. Add to arrangement… places the group at a node.

A group is the same group wherever it is used, so a change to its members or their order shows everywhere it has been placed. A group can hold up to 10,000 members, cannot contain the same member twice, and cannot contain itself. If someone else saved the group while you were editing it, Pangur asks you to reload it before saving. There is no way to delete a source group.

Ask can also create a source group when you agree to one of its proposals (see Ask a question). From the command line, pangur groups lists groups and pangur groups --save FILE saves one. An assistant can list groups and save one with list_source_groups and save_source_group, and it can add and reorder members but not remove them.

VocabulariesCopy Anchor Link

A vocabulary is a named list of terms that the project keeps for consistency, such as parchment, paper, vellum. Fields of the type Choice from a list can draw on one, and so can the details of copies.

Vocabularies… in an arrangement's header shows them. New vocabulary… asks for a Name and Terms (one per line, or comma-separated), and Pangur trims the terms and drops duplicates. Edit changes the terms, and the change applies at once everywhere the vocabulary is used. Delete removes a vocabulary after asking you to confirm, except that Pangur refuses while a field still uses it and names the fields concerned.

Every project starts with four vocabularies used by copies: "Imaging purpose", "Imaging method", "Surrogate role" and "Surrogate set relation". You can edit their terms. If you rename or delete one of them, Pangur adds a fresh vocabulary with the original name and terms beside it, because copy details depend on them.

An assistant can create a vocabulary with create_vocabulary.

Arrangements on other surfaces and permissionsCopy Anchor Link

The iPhone and iPad app has native arrangements, chosen from View as in the Library. The browser's menu there offers Read, Add top-level node…, Add source…, Allow flexible nesting, Levels and fields…, Vocabularies…, Rename… and Delete…, and a node offers Capture here… and Move…. Reading layouts are set on the web. Pangur for Mac shows the web screens.

The command line can divide items into texts and work with source groups, but cannot create arrangements, levels or nodes. Assistants connected over MCP can create arrangements, levels and nodes, move nodes, set node values, divide texts and save groups and vocabularies, but cannot delete anything (see MCP tools).

In an organisation's project (a feature that is not offered on every account), members with the viewer role can read arrangements but cannot change them.