resolve_links
Matches cited sources in an evidence ledger against local PDFs, verifies quoted passages, and writes page links to a private link file.
Instructions
Resolve the ledger's sources against the reader's own PDFs and write the result to
link_file, which must end in .private.json (a rerun replaces one this tool wrote, no
other file): it holds paths on this computer, so do not share it.
Give folder, link_map or both. Best layout: a sources/ folder holding only the cited
PDFs, each named <citation key>.pdf, kept out of version control (copyrighted). A file
named exactly after the key is tried first; other names work through the matching below.
Do not pass a whole reference library as folder: thousands of PDFs are slow and the call
stops at the time limit with every source source_not_found. For a library, pass
link_map instead: the path of a .private.json file (JSON Schema link-map.schema.json)
with {"link_map_version": "0.1.0", "sources": {"<key>": {"file": "<pdf path>", "open": "<optional library link>"}}}. A mapped key searches only its PDF; a key missing from the
map is not_in_map, unless folder is also given, which is then searched for it. With
Zotero and Better BibTeX, build the map from JSON-RPC item.attachments(citekey) at
http://localhost:23119/better-bibtex/json-rpc, which returns {open, path} per attachment.
folder is searched recursively.
Where no passage is found, the link file still gives the PDF page of the record's
locator.page, read through the PDF's printed page labels or, without labels, taken as the
PDF page number (page_from says which). In a folder a source matches by the first
of: a file named <key>.pdf, its DOI on a PDF's first two pages, its ISBN on the first ten,
its title on the first two
(from bibliography, a .bib or CSL JSON file, which can also supply DOI and ISBN; titles
under 20 letters and digits count only with the first author's family name), each only if
exactly one PDF matches, so that a PDF citing the source does not; last, a file named after
the first author and year (e.g. Ioannidis 2005.pdf).
Each record is then
found (its passage is in the PDF, at the page given in the link file; this confirms the
record independently), passage_not_found, source_not_found, not_in_map or
not_searchable: finding a
passage needs its quote, whole or masked to its first and last words as in masked exports;
a locator export holds only the hash. The passage must hash to quote_hash, so
whitespace, punctuation, case and line-end hyphens may differ; a whole quote split by a
page break (with or without running heads or captions between its parts) is found and
marked across_pages in the link file. PDFs that cannot be read are listed with a short
reason under unreadable_files, and time_limit when reading PDFs stopped after 300 seconds.
The result holds record ids and file paths, never source text.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| folder | No | ||
| link_map | No | ||
| link_file | Yes | ||
| bibliography | No | ||
| include_withdrawn | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |