Format a citation or resolve a printed page
shamela_citeRead-onlyIdempotent
Citations. mode=citation (default): build one for a book, optionally a page and quoted text — Shamela's copy format, short inline, full with death year, or BibTeX/RIS. Call it whenever you attribute a quote; it needs only the catalogue, plus the installed text for a page's printed number. Read page_resolved, components.auto_numbered and notes[] before presenting.
mode=printed_page: map a printed citation («vol. 4, p. 405») to the page_ids carrying it — no arithmetic relates the two, and one printed page often spans several ids: read them all, in order, with shamela_read(unit='page'). Resolve the work with shamela_find(kind='work') first; holding a page_id already, skip this. Failures come back as status; citable:false = Shamela's own numbering. Error: BOOK_NOT_FOUND.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Selects what the call does: citation | printed_page. Default citation. | |
| page | No | The PRINTED page number as the citation gives it (e.g. 405). Example: {book_id:6910, part:'4', page:405}; {book_id:1681, part:'1', page:6}. (mode=printed_page only.) | |
| part | No | The volume/part label as the book uses it, usually a bare number ('4'). Omit when the citation names no volume or the work is single-volume: the search then runs across every part and the response reports which parts matched, so an ambiguous page number is visible rather than silently resolved to the first volume. (mode=printed_page only.) | |
| text | No | Optional quoted text. Used by the 'shamela' style only, which then prints a two-line block: «<book>» (<part>/ <page>): «<text>». Other styles ignore it. (mode=citation only.) | |
| style | No | Citation style. 'shamela' replicates Shamela's UI copy-with-citation format (default). 'short' is a one-line inline reference. 'full' is the long form including author death year and book year, with notes listing missing fields (publisher/edition/etc are not in master.db). 'bibtex' and 'ris' are machine-readable exports for Zotero/EndNote/Mendeley (Western digits, Arabic UTF-8, stable cite key shamela<book_id>p<page_id>); they carry only fields master.db has, with the same missing-field notes[]. 'short' reads <author>، <book>، ص <page>. Every style but bibtex/ris uses Arabic-Indic digits. (mode=citation only.) | |
| book_id | No | [mode=citation] The book id, from shamela_find(kind='book'), shamela_find(kind='work') or shamela_find(kind='name'). [mode=printed_page] The book. Resolve a cited title with shamela_find(kind='work') first — and note that different printings of one work paginate differently, so the book_id must be the printing the citation came from. | |
| page_id | No | Optional page_id. When omitted, the citation references the book without a specific page and page_resolved is null. A page id that is missing, has no printed number, or belongs to a book whose text is not installed here yields a book-level citation with page_resolved:false and a note. Example: {book_id:1681, page_id:10}, or with text:'<quoted passage>', style:'shamela'. (mode=citation only.) | |
| response_format | No | Format of the human-readable text: 'markdown' (default) for display; 'json' the same data as one JSON code block; 'none' only a one-line pointer, leaving structuredContent as the whole answer. structuredContent is always returned, so a caller that parses it should pass 'none': the character budget counts both channels, and the unread copy otherwise spends most of it. Requires the 'response_format.none' capability (see shamela_get_brief). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | [mode=citation] Missing citation fields and fallbacks; never fill them in. [mode=printed_page] Guidance on reading the result. | |
| style | No | 'shamela', 'short', 'full', 'bibtex' or 'ris'. (mode=citation only.) | |
| status | No | 'ok', 'book_not_downloaded', 'no_printed_pagination' (Shamela paginates this entry itself: no printed page exists), 'part_not_found' or 'page_not_in_part'. (mode=printed_page only.) | |
| book_id | No | Catalogue book id. (mode=printed_page only.) | |
| citable | No | False when the numbers are Shamela's own, not a printed edition's. (mode=printed_page only.) | |
| matches | No | One row per page id. (mode=printed_page only.) | |
| page_ids | No | Every page id carrying the printed page, in reading order; read them all. Shamela splits a long printed page across records, so one page routinely has several ids (part '1', page 6 of book 1681 = ids 9, 10, 11 in the fixture). (mode=printed_page only.) | |
| book_name | No | Catalogue title of the book (Arabic). (mode=printed_page only.) | |
| formatted | No | The citation text in the requested style. (mode=citation only.) | |
| truncated | No | ||
| components | No | The parts the citation was built from. (mode=citation only.) | |
| page_range | No | On page_not_in_part: the printed range that exists in that part. (mode=printed_page only.) | |
| rows_dropped | No | ||
| page_resolved | No | True when the page and its printed number were found; false when the citation fell back to book level (see notes) and must not be presented as a page reference; null when no page_id was given. (mode=citation only.) | |
| parts_matched | No | Distinct parts matched; more than one means the number is ambiguous across volumes. (mode=printed_page only.) | |
| requested_page | No | Printed page requested. (mode=printed_page only.) | |
| requested_part | No | Part label requested; null when omitted. (mode=printed_page only.) | |
| available_parts | No | On part_not_found: the part labels the book uses. (mode=printed_page only.) | |
| truncation_message | No |