Doc Refs#

Proofscape gives you various ways to make document references (“doc refs”), which means making connections between the Content Types of notes and charts on the one hand, with docs on the other.

Specifically, a doc ref is made when you define Doc Widgets in annotations and Sphinx pages, and when you define Doc labels on nodes in deductions.

Doc ref strings#

A doc ref string is a string of the form:

Listing 77 Doc ref string format#

DOC#CODE

where DOC is a (relative) libpath resolving to a doc info object (see below), and CODE is a box combiner code (see below).

Doc ref strings may be used at various places in the Proofscape library, such as in Doc Widgets and Doc labels.

Alternatively, in such contexts there is also usually an option to specify the doc info object and the combiner code separately. See the relevant reference sections for details.

Doc Info Objects#

A doc info object is an object (in the JSON sense – see Proofscape-flavored JSON) defining information about a document. It is used for identifying a document, and is necessary for making references from doc widgets and doc labels.

It should be defined either in a .pfsc file or under a pfsc directive in an .rst file, and may look roughly like this:

MyDocument = {
    docId: "pdffp:0123456789abcdef",
    url: "https://example.org/some/document/itself.pdf",
    aboutUrl: "https://example.com/docinfo.html",
    title: "We Love Math",
    author: "Martha and Matthew Matician",
    year: 2023,
}

Below we define the required and optional fields for doc info objects.

Required Fields#

Field	Value
`docId`	String identifying the document. Format is `DOC_TYPE:DOC_CODE`. At present only one `DOC_TYPE` is accepted: `pdffp`, which stands for “PDF fingerprint”. The `DOC_CODE` for a `pdffp` is the “fingerprint” code generated by the PDF viewer in PISE, when you click the “Fingerprint” button in the toolbar. See Define a doc info object in the Authors’ Tutorial. (The fingerprint is a “hopefully unique” hash generated for any PDF document, according to this procedure.)

Field

Value

docId

String identifying the document.

Format is DOC_TYPE:DOC_CODE.

At present only one DOC_TYPE is accepted: pdffp, which stands for “PDF fingerprint”.

The DOC_CODE for a pdffp is the “fingerprint” code generated by the PDF viewer in PISE, when you click the “Fingerprint” button in the toolbar. See Define a doc info object in the Authors’ Tutorial. (The fingerprint is a “hopefully unique” hash generated for any PDF document, according to this procedure.)

Optional Fields#

Field	Value
`url`	A URL pointing directly to the document itself. Will be used by PISE to automatically load the document.
`aboutUrl`	The URL of a page where instructions can be found, for obtaining the document. Usually offered only if a `url` field cannot be provided. Will not be used by PISE to (attempt to) automatically load the document.
`title`	the title of the document
`author`	the author of the document
`year`	year of publication
`publisher`	publisher
`ISBN`	ISBN
`eBookISBN`	eBookISBN
`DOI`	DOI

Box Combiner Codes#

The box combiner language is a simple language for describing combinations of boxes in PDFs and other archival documents.

In PISE, you can interactively select one or more boxes, i.e. rectangular areas on one or more pages of the document, and then generate a combiner code to indicate the way those boxes should be arranged to form a selection from the document. See, for example, Define a doc label in the Authors’ Tutorial.

A full combiner code is a concatenation of individual commands (see table below). Each command (except the “Box” command) must be terminated with a semicolon ;. Whitespace is ignored.

Table 15 The commands of the Box Combiner Language#
Command	Format	Meaning
Version	`vFLOAT`	Indicates the version of the Combiner Code language. Must come at the start of the code. Currently `2` is the only accepted version number.

Box	`(PAGE_NUM : PAGE_WIDTH : PAGE_HEIGHT : BOX_X : BOX_Y : BOX_W : BOX_H)`	Defines a box in a page, by recording the page number within the document, the dimensions of the page at the time the box was drawn, and the position and dimensions of the box. Usually not written by hand, but instead generated by PISE after the user draws a box.

Scale	`sFLOAT`	Records the zoom scale of the document at the time that the boxes were drawn. Although this information could be determined from the box codes themselves, that requires loading the document and comparing. The Scale command makes it possible to know the zoom without loading the document.

x-shift	`xSIGNED_INT`	Shifts the “cursor” in the x-dimension, adjusting the offset at which the next box (if any) will appear. Positive shift moves to the right, negative to the left.

y-shift	`ySIGNED_INT`	Shifts the “cursor” in the y-dimension, adjusting the offset at which the next box (if any) will appear. Positive shift moves down, negative up.

Newline	`n`	Like hitting “return” in a text editor, resets the x-coordinate of the cursor to zero, and sets the y-coordinate so that the next box appears immediately below the lowest boxes already drawn.

z-index	`zSIGNED_INT`	Just like the CSS z-index property, this is an integer that can be used to elevate the box combination, above or below others that may also be present in the same document.