# (lispkit pdf) Library `(lispkit pdf)` provides an API for manipulating and analyzing PDF documents. The library supports creating PDF documents, managing pages, adding annotations, handling bookmarks, managing outlines, extracting content, and rendering pages. A PDF document contains pages corresponding to the pages of a printed document. Each page contains text, images, hyperlinks and annotations. The page uses a coordinate system with 72 points to each printed inch. The coordinates originate at the bottom left of the page and increase going upward and to the right (as opposed to the coordinate system used by library `(lispkit draw)`. A PDF document also contains an outline which is a hierarchical data structure that defines the table of contents. ## PDF documents **(pdf? *****obj*****)** Returns `#t` if *obj* is an object representing a PDF document. Otherwise, `#f` is returned. **(pdf-encrypted? *****doc*****)** Returns `#t` if *obj* is an object representing an encrypted PDF document. Otherwise, `#f` is returned. **(pdf-locked? *****doc*****)** Returns `#t` if *obj* is an object representing a locked PDF document. Otherwise, `#f` is returned. Only encrypted documents can be locked. Encrypted documents whose password is the empty string are unlocked automatically upon opening. PDF documents can be unlocked with the `pdf-unlock` procedure. **(make-pdf)** Returns an object representing a new, empty PDF document. **(bytevector->pdf *****bvec*****)** \ \&#xNAN;**(bytevector->pdf *****bvec start*****)**\ \&#xNAN;**(bytevector->pdf *****bvec start end*****)** Returns an object representing the PDF document defined by the bytes in bytevector *bvev* between *start* and *end*. If *end* is not provided, it is assumed to be the length of *bvec*. If *start* is not provided, it is assumed to be 0. **(load-pdf *****filepath*****)** Loads the PDF file at path *filepath* and returns an object representing this PDF document. It is an error if the file at the given file path is not a PDF file. **(save-pdf *****filename doc*****)** \ \&#xNAN;**(save-pdf *****filename doc options*****)** Saves the PDF document represented by object *doc* into a file at path *filepath*. *options* is an association list supporting the following symbolic keys: * `user-password`: The value is a user password string. * `owner-password`: The value is a owner password string. * `access-permissions`: The value is either `#f` (no permissions), `#t` (access permissions as defined by *doc*), or a list of the following symbols: `commenting` (allow commenting), `content-accessibility` (allow content accessibility), `content-copying` (allow copying of content), `document-assembly` (allow mutation of page structure), `document-changes` (allow changes to the PDF document), `form-field-entry` (allow setting form field values), `high-quality-printing` (support high quality printing), and `low-quality-printing` (support low quality printing). * `burn-in-annotations`: If set to `#t`, annotations are burned into PDF pages. * `optimize-for-screen`: If set to `#t`, the PDF document representation is optimized for screen usage. * `save-images-as-jpeg`: If set to `#t`, images will all be represented as JPEGs. * `save-text-from-ocr`: If set to `#t`, OCR will be applied to all pages and the text will be stored as an invisible but searchable and selectable layer on top of the page. **(pdf-unlock *****doc passwd*****)** Unlocks the encrypted PDF document *doc* with password string *passwd*. After unlocking, predicate `pdf-locked?` will return `#f`. **(pdf->string *****doc*****)** Extracts all text from the PDF document *doc* and returns it as a string. **(pdf->bytevector *****doc*****)** \ \&#xNAN;**(pdf->bytevector *****doc options*****)** Returns a bytevector representing the PDF document *doc*. *options* is an association list supporting the following symbolic keys: * `user-password`: The value is a user password string. * `owner-password`: The value is a owner password string. * `access-permissions`: The value is either `#f` (no permissions), `#t` (access permissions as defined by *doc*), or a list of the following symbols: `commenting` (allow commenting), `content-accessibility` (allow content accessibility), `content-copying` (allow copying of content), `document-assembly` (allow mutation of page structure), `document-changes` (allow changes to the PDF document), `form-field-entry` (allow setting form field values), `high-quality-printing` (support high quality printing), and `low-quality-printing` (support low quality printing). * `burn-in-annotations`: If set to `#t`, annotations are burned into PDF pages. * `optimize-for-screen`: If set to `#t`, the PDF document representation is optimized for screen usage. * `save-images-as-jpeg`: If set to `#t`, images will all be represented as JPEGs. * `save-text-from-ocr`: If set to `#t`, OCR will be applied to all pages and the text will be stored as an invisible but searchable and selectable layer on top of the page. **(pdf-path *****doc*****)** Returns the file path of PDF document *doc* if it exists. Otherwise, `#f` is returned. **(pdf-version *****doc*****)** Returns the PDF version used for the representation of the PDF document *doc* as a pair of two numbers: (*major* . *minor*). Returns `#f` if a version is not available. **(pdf-attributes *****doc*****)** Returns an association list of document-level attributes for the PDF document *doc*. Common attributes include `Creator` (the creator of the content as a string), `Producer` (the one who made this PDF as a string), `Author` (the author of this content as a string), `Title` (the title of this document as a string), `Subject` (the subject of this document as a string), `CreationDate` (the creation date of this document), `ModDate` (the modification date of this document), `Keywords` (a string describing keywords associated with this document). **(pdf-attribute-ref *****doc key*****)** \ \&#xNAN;**(pdf-attribute-ref *****doc key default*****)** Returns a value for a document-level attribute of PDF document *doc* identified by symbol *key*. Keys of common attributes are: `Creator`, `Producer`, `Author`, `Title`, `Subject`, `CreationDate`, `ModDate`, and `Keywords`. If the attribute identified by *key* does not exist, *default* is returned if it was provided. Otherwise, `#f` is returned. **(pdf-attribute-set! *****doc key value*****)** Sets the value for a document-level attribute of PDF document *doc* identified by symbol *key* to *value*. Keys of common attributes are: `Creator`, `Producer`, `Author`, `Title`, `Subject`, `CreationDate`, `ModDate`, and `Keywords`. **(pdf-attribute-remove! *****doc key*****)** Removes a document-level attribute from PDF document *doc* identified by symbol *key*. Keys of common attributes are: `Creator`, `Producer`, `Author`, `Title`, `Subject`, `CreationDate`, `ModDate`, and `Keywords`. **(pdf-access-permissions *****doc*****)** Returns a list of symbols representing permissions enabled for the PDF document *doc*. The following symbols are supported: * `commenting`: allow commenting, * `content-accessibility`: allow content accessibility, * `content-copying`: allow copying of content, * `document-assembly`: allow mutation of page structure, * `document-changes`: allow changes to the PDF document, * `form-field-entry`: allow setting form field values, * `high-quality-printing`: support high quality printing, and * `low-quality-printing`: support low quality printing. **(pdf-page-count *****doc*****)** Returns the number of pages of PDF document *doc*. **(pdf-pages *****doc*****)** Returns a list of PDF pages for PDF document *doc*. **(pdf-page *****doc n*****)** Returns the PDF page at index *n* of PDF document *doc*. **(pdf-insert-page! *****doc page*****)** \ \&#xNAN;**(pdf-insert-page! *****doc n page*****)** Inserts the given PDF *page* at index *n* into the PDF document *doc*. If *n* is not provided, the page is inserted at the end. **(pdf-remove-page! *****doc n*****)** Removes the page at index *n* of PDF document *doc*. **(pdf-swap-page! *****doc n m*****)** Swaps the page at index *n* with the page at index *m* of PDF document *doc*. **(pdf-page-index *****doc page*****)** Returns the index of PDF *page* in the given PDF document *doc*. If *page* is not a valid PDF page in *doc*, `#f` is returned. **(pdf-outline *****doc*****)** Returns the outline (table of contents) for the given PDF document *doc* or `#f` if there is no outline available for *doc*. **(pdf-outline-set! *****doc outline*****)** Sets the outline (table of contents) for the given PDF document *doc* to *outline*. If *outline* is `#f`, then the table of contents of *doc* is removed. ## Predicates **(pdf-display-box? *****obj*****)** Returns `#t` if *obj* is a valid display box specifier. Supported display box specifiers are: `media-box`, `crop-box`, `bleed-box`, `trim-box`, and `art-box`. **(pdf-line-style? *****obj*****)** Returns `#t` if *obj* is a valid line style specifier. Supported line style specifiers are: `none`, `square`, `circle`, `diamond`, `open-arrow`, and `closed-arrow`. **(pdf-text-alignment? *****obj*****)** Returns `#t` if *obj* is a valid text alignment specifier. Supported text alignment specifiers are: `left`, `right`, `center`, `justified`, and `natural`. **(pdf-icon-type? *****obj*****)** Returns `#t` if *obj* is a valid icon type specifier. Supported icon type specifiers are: `comment`, `key`, `note`, `help`, `new-paragraph`, `paragraph`, and `insert`. **(pdf-markup-type? *****obj*****)** Returns `#t` if *obj* is a valid markup type specifier. Supported markup type specifiers are: `highlight`, `strike-out`, `underline`, and `redact`. ## PDF pages Pages in a PDF document are represented with `pdf-page` objects. A *PDF page* can either be inserted into a PDF document or it is standalone. If the page has been inserted, `pdf-page-number` returns the page number. If it has not been inserted, `pdf-page-number` returns `#f`. *Page numbers* are managed automatically and they potentially change when the pages of a PDF document are rearranged. *Page labels* on the other hand are customizable names for pages that are stable. The orientation of a PDF page is set by specifying a *rotation*. A PDF page defines rectangular *bounds* for different types of *display boxes* of that page. *Display boxes* are identified via symbolic specifiers. Supported are: `media-box`, `crop-box`, `bleed-box`, `trim-box`, and `art-box`. The content of a PDF page is defined in terms of up to three different layers: besides the native PDF content, it is possible to set an *underlay drawing* which is drawn underneith the native content. If is also possible to define an *overlay drawing* which is drawn on top of the native content. One type of element of the native content of a PDF page are *PDF annotations*. These are widgets that can be inserted at specified coordinates. Many different types of widgets are supported. They can be identified on the page, inserted, modified, and removed. **(pdf-page? *****obj*****)** Returns `#t` if *obj* is an object representing a PDF page. Otherwise, `#f` is returned. **(make-pdf-page)** \ \&#xNAN;**(make-pdf-page *****box*****)**\ \&#xNAN;**(make-pdf-page *****image*****)**\ \&#xNAN;**(make-pdf-page *****image compress*****)**\ \&#xNAN;**(make-pdf-page *****image compress rotate*****)**\ \&#xNAN;**(make-pdf-page *****image compress rotate media*****)**\ \&#xNAN;**(make-pdf-page *****image compress rotate media upscale*****)** Returns a new PDF page. If *box* is provided, it is either a size describing the size of the media box of the page, or a rectangle defining the media box of the page. Alternatively, an *image* can be provided as the basis for the new PDF page. In this case, parameters *compress*, *rotate*, *media*, and *upscale* can be provided to customize the usage of the image. *compress* is a flonum between 0.0 (= lowest quality) and 1.0 (= highest quality) defining the compression quality, *rotate* is a positive or negative multiple of 90 describing the rotation of the image, *media* is either `#f`, a size object, or a rect describing the media box of the page, and *upscale* is a boolean to enable the upscaling of the image if it is smaller than the size of the page. **(pdf-page-copy *****page*****)** Returns a copy of the given PDF *page*. **(pdf-page-document *****page*****)** Returns the PDF document to which the given PDF *page* belongs, or `#f` if the page has not been inserted into a PDF document. **(pdf-page-number *****page*****)** Returns the page index (starting from 0) of the given PDF *page* in the PDF document in which it was inserted. `pdf-page-number` returns `#f` is the PDF *page* has not been inserted into a PDF document. **(pdf-page-label *****page*****)** Returns the label of the given PDF *page* in the PDF document in which it was inserted. `pdf-page-label` returns `#f` is the PDF *page* has not been inserted into a PDF document or does not have a label. **(pdf-page-bounds *****page box-spec*****)** Returns a rect describing the page bounds for the display box specifier *box-spec* of PDF *page*. *box-spec* is one of the following symbols: `media-box`, `crop-box`, `bleed-box`, `trim-box`, and `art-box`. **(pdf-page-bounds-set! *****page box-spec box*****)** Sets the display box specified by *box-spec* for the given PDF *page* to the rect *box*. *box-spec* is one of the following symbols: `media-box`, `crop-box`, `bleed-box`, `trim-box`, and `art-box`. **(pdf-page-rotation *****page*****)** Returns the rotation angle in degrees (a multiple of 90) of PDF *page*. **(pdf-page-rotation-set! *****page rotate*****)** Sets the rotation angle of PDF\_page\_ to *rotate*. *rotate* is a positive or negative multiple of 90 describing the rotation of *page*. **(pdf-page-annotations-display *****page*****)** Returns `#t` if annotations should be displayed on PDF *page*; otherwise `#f` is returned. **(pdf-page-annotations-display-set! *****page display?*****)** Enables the display of annotations on PDF *page* if *display* is true. If *display* is `#f`, then the display of annotations gets disabled for *page*. **(pdf-page-annotations *****page*****)** Returns a list of all PDF annotations on PDF *page*. **(pdf-page-annotation-ref *****page point*****)** Returns the PDF annotations that can be found at coordinates *point* on PDF *page*. `#f` is returned if there is no annotation at *point*. **(pdf-page-annotation-add! *****page annot*****)** Adds the PDF annotation *annot* to PDF *page*. **(pdf-page-annotation-remove! *****page annot*****)** Removes the annotation *annot* from PDF *page*. **(pdf-page-underlay *****page*****)** PDF pages are drawn in three layers: first an *underlay drawing* is drawn (if it exists) followed by the PDF page content including its annotations, and finally an *overlay drawing* is drawn (if it exists). `pdf-page-underlay` returns the underlay drawing for *page* if it exists, otherwise `#f` is returned. **(pdf-page-underlay-set! *****page drawing*****)** Sets the underlay drawing of PDF *page* to *drawing*. An underlay drawing is removed if *drawing* is `#f`. **(pdf-page-overlay *****page*****)** PDF pages are drawn in three layers: first an *underlay drawing* is drawn (if it exists) followed by the PDF page content including its annotations, and finally an *overlay drawing* is drawn (if it exists). `pdf-page-underlay` returns the overlay drawing for *page* if it exists, otherwise `#f` is returned. **(pdf-page-overlay-set! *****page drawing*****)** Sets the overlay drawing of PDF *page* to *drawing*. An overlay drawing is removed if *drawing* is `#f`. **(pdf-page-images *****page*****)** Returns a list of all images that can be found on PDF *page*. **(pdf-page-thumbnail *****page box size*****)** Generates a thumbnail of *size* (in points) from the content in the rect *box* on PDF *page* and returns a corresponding image. **(pdf-page->bitmap *****page box size*****)** \ \&#xNAN;**(pdf-page->bitmap *****page box size ppi*****)**\ \&#xNAN;**(pdf-page->bitmap *****page box size ppi ipol*****)** Returns a bitmap of *size* (in points) from the content in rect *box* on PDF *page*. *ppi* determines the number of pixels per inch. By default, *ppi* is set to 72. In this case, the number of pixels of the returned bitmap corresponds to the number of points (since 1 pixel corresponds to 1/72 of an inch). *ipol* is a fixnum between 0 and 4 indicating the interpolation quality used for creating the bitmap: `0` = default, `1` = none, `2` = low, `3` = high, and `4` = medium. **(pdf-page->string *****page*****)** Returns a string representing all the text on PDF *page*. If no string can be extracted, `#f` is returned. **(pdf-page->styled-text *****page*****)** Returns a styled-text object representing all the text on PDF *page*. If no styled-text can be extracted, `#f` is returned. **(pdf-page->bytevector *****page*****)** Returns a bytevector representing a PDF document with *page* as the only page of the PDF document. If no binary representation of this page can be created, then `#f` is returned. **(draw-pdf-page *****page box-spec rect drawing*****)** Draws the content within the display box specified by *box-spec* of PDF *page* into *drawing*. Drawings are defined by library `(lispkit draw)`. *box-spec* is one of the following symbols: `media-box`, `crop-box`, `bleed-box`, `trim-box`, and `art-box`. *rect* specifies a rectangular region into which *page* is drawn. *rect* can be specified in the following ways: * `#f`: *rect* corresponds to the rectangular specified by *box-spec*. * `#t`: *rect* has its origin at `zero-point` and the width and height correspond to the size of the rectangular specified by *box-spec*. * `(x . y)`: *rect* has its origin at point (x, y) and the width and height correspond to the size of the rectangular specified by *box-spec*. * `((x . y) . (w . h))`: *rect* corresponds to the given rectangular. * `(#f . (w . h))`: rect\_ has its origin at `zero-point` and the width and height correspond to `w` and `h` respectively. ## PDF outlines A *outline* is an optional hierarchical component of a PDF document which defines the structure of a document and facilitates navigating within it. A *PDF outline* object represents a node in the outline hierarchy. Each outline object belongs at most to one PDF document. Except for outline objects representing the root of a document, all outline objects have a parent outline object. This root outline object is not visible to the reader of a PDF document and serves merely as a container for the visible outlines. Each outline object has an index which defines an ordering underneath the parent of the outline object. Outline objects have a customizable label, destination, and are associated with an optional action. Each outline object may have several children. **(pdf-outline? *****obj*****)** Returns `#t` if *obj* is a PDF outline object; otherwise `#f` is returned. **(make-pdf-outline)** \ \&#xNAN;**(make-pdf-outline *****label*****)**\ \&#xNAN;**(make-pdf-outline *****label page*****)**\ \&#xNAN;**(make-pdf-outline *****label page point*****)**\ \&#xNAN;**(make-pdf-outline *****label page point zoom*****)** Returns a new PDF outline object. *label* is a string defining the label of the outline object. *page* is a PDF page which is the target destination for this outline object. *point* is a specific point on that page and *zoom* is a floating-point number defining the zoom factor for that destination. All arguments are optional and `#f` by default. **(pdf-outline-document *****outline*****)** If *outline* is the child of an outline object which is part of the outline hierarchy of a PDF document, then `pdf-outline-document` returns this PDF document. **(pdf-outline-parent *****outline*****)** Returns the parent outline object of *outline*. For root outline objects, `pdf-outline-parent` returns `#f`. **(pdf-outline-index *****outline*****)** Returns the index of *outline* within all the children sharing the same parent as *outline*. `pdf-outline-index` returns 0 for outline objects which do not have a parent. **(pdf-outline-label *****outline*****)** Returns the label of *outline* if a label has been defined, or `#f` otherwise. **(pdf-outline-label-set! *****outline str*****)** Sets the label of *outline* to string *str*. **(pdf-outline-destination *****outline*****)** Returns the destination of *outline*. A destination is defined in terms of a list with three elements: (*page* *point* *zoom*). *page* is a PDF page which is the target destination for this outline object. *point* is a specific point on that page and *zoom* is a floating-point number defining the zoom factor for that destination. All elements can be `#f` if not defined. **(pdf-outline-destination-set! *****outline dest*****)** \ \&#xNAN;**(pdf-outline-destination-set! *****outline page*****)**\ \&#xNAN;**(pdf-outline-destination-set! *****outline page point*****)**\ \&#xNAN;**(pdf-outline-destination-set! *****outline page point zoom*****)** Sets the destination of *outline*. If *dest* is provided, it is either `#f` (in which case the destination will be removed), or a list with exactly three elements: (*page* *point* *zoom*). Alternatively, *page*, *point*, and *zoom* can be provided individually. *page* is a PDF page which is the target destination for this outline object. *point* is a specific point on that page and *zoom* is a floating-point number defining the zoom factor for that destination. *point* and *zoom* can be `#f` if not defined. **(pdf-outline-action *****outline*****)** Returns the action associated with *outline*, or `#f` if no action is defined. The following action types are supported: * (`goto` *page point*): Goes to *point* on *page*. * (`goto-remote` *url page-index point*): Opens a PDF document at *url* and goes to *point* on the page with index *page-index*. * (`goto-url` *url*): Opens the page/document at *url*. * (`perform` *action-name*): Performs a named action. *action-name* is one of the following symbols: `none`, `find`, `go-back`, `go-forward`, `goto-page`, `first-page`, `last-page`, `next-page`, `previous-page`, `print`, `zoom-in`, or `zoom-out`. * (`reset-fields` *name ...*): Resets the fields with the names *name ...*. *name ...* are strings. * (`reset-fields-except` *name ...*): Resets all fields except for the ones with the names *name ...*. *name ...* are strings. **(pdf-outline-action-set! *****outline action*****)** Sets the action of *outline* to *action*. *action* is a PDF outline action matching one of the following supported action types: * (`goto` *page point*): Goes to *point* on *page*. * (`goto-remote` *url page-index point*): Opens a PDF document at *url* and goes to *point* on the page with index *page-index*. * (`goto-url` *url*): Opens the page/document at *url*. * (`perform` *action-name*): Performs a named action. *action-name* is one of the following symbols: `none`, `find`, `go-back`, `go-forward`, `goto-page`, `first-page`, `last-page`, `next-page`, `previous-page`, `print`, `zoom-in`, or `zoom-out`. * (`reset-fields` *name ...*): Resets the fields with the names *name ...*. *name ...* are strings. * (`reset-fields-except` *name ...*): Resets all fields except for the ones with the names *name ...*. *name ...* are strings. **(pdf-outline-open? *****outline*****)** Returns `#t` if the *outline* is currently open, otherwise `#f` is returned. **(pdf-outline-open-set! *****outline*****)** \ \&#xNAN;**(pdf-outline-open-set! *****outline open?*****)** Closes the *outline* if *open?* is `#t`, otherwise *outline* will be opened. If *open?* is not provided, *outline*'s open state will be toggled. **(pdf-outline-child-count *****outline*****)** Returns the number of children of *outline*. **(pdf-outline-child-ref *****outline n*****)** Returns the *n*-th child from *outline*. If that outline child does not exist, `#f` is returned. **(pdf-outline-child-insert! *****outline child*****)** \ \&#xNAN;**(pdf-outline-child-insert! *****outline n child*****)** Inserts a PDF outline object *child* at index *n* into *outline*. If *n* is not provided, *child* is inserted at the end. **(pdf-outline-child-remove! *****outline n*****)** Removes the *n*-th child from *outline*. If there is no *n*-th child, then `pdf-outline-child-remove!` fails. ## PDF annotations PDF annotations are non-intrusive elements added to a PDF document to provide comments, feedback, or interactive features without altering the original content. PDF annotations are represented via its own object by library `(lispkit pdf)`. There are a lot of different types of annotations, but only some are supported by this library. The type of an annotation is represented as a symbol. Supported are annotations of the following types: `circle`, `free-text`, `highlight`, `ink`, `line`, `link`, `popup`, `square`, `stamp`, `strike-out`, `text`, and `underline`. **(pdf-annotation? *****obj*****)** Returns `#t` if *obj* is a PDF annotation object; otherwise `#f` is returned. **(make-pdf-annotation *****bounds type*****)** Creates a new PDF annotation object with the given *bounds* and *type*. *bounds* is a rect that specifies the bounding box for the annotation. *type* is a symbol specifying the PDF annotation type. Supported are: * `circle`: Displays an elliptical or circular shape on the page. * `free-text`: Displays text directly on the page within a customizable box, remaining visible without needing to be opened. Callouts are a special type of free text annotation that includes a line or arrow pointing from the text box to a specific area of the document. * `highlight`: Marks important text by applying a translucent color over it. * `line`: Displays a single straight line on the page. * `ink`: Allows for free-form drawing or sketching directly on the document, represented by a custom shape. * `link`: Creates a clickable area that can jump to a web URL, a specific page within the document, or an external document. * `popup`: Displays text in a pop-up window for entry and editing. * `square`: Displays a rectangular shape on the page. * `stamp`: Applies pre-defined or custom visual stamps (e.g., "Approved", "Draft", "Confidential") to the document, similar to a physical rubber stamp. * `strike-out`: Draws a line through selected text, often indicating it should be removed. * `text`: A sticky-note like annotation which adds a small pop-up note or comment icon to the page that opens to display text when clicked. * `underline`: Draws a line beneath selected text. * `widget`: Displays interactive form elements, including text or signature fields, radio buttons, checkboxes, push buttons, pop-ups, and tables. Annotations of other types can be managed with `(lispkit pdf)`, but there is no specific support to create or modify them. They typically use symbolic identifiers that start with a capital letter. Once created, some annotations might require other attributes/metadata to be set. This can be done with the various PDF annotation management procedures. Annotations created with `make-pdf-annotation` are by default not attached to a PDF page. Adding an annotation to a PDF page can be done with procedure `pdf-page-annotation-add!`. **(pdf-annotation-page *****annot*****)** Returns the PDF page on which this annotation is shown. If this annotation is not associated with a PDF page, `#f` is returned. **(pdf-annotation-type *****annot*****)** Returns a symbol representing the annotation type of *annot*. The officially supported annotation types are `circle`, `free-text`, `highlight`, `ink`, `line`, `link`, `popup`, `square`, `stamp`, `strike-out`, `text`, `underline`, and `widget`. **(pdf-annotation-name *****annot*****)** Returns the name of PDF annotation *annot* as a string. If *annot* does not have a name, `#f` is returned. **(pdf-annotation-name-set! *****annot str*****)** Sets the name of PDF annotation *annot* to string *str*. If *str* is `#f`, then the name of *annot* is cleared. **(pdf-annotation-bounds *****annot*****)** Returns the bounds of PDF annotation *annot* as a rect. **(pdf-annotation-bounds-set! *****annot bounds*****)** Sets the bounds of PDF annotation *annot* to rect *bounds*. **(pdf-annotation-padding *****annot*****)** Returns the padding of PDF annotation *annot* as a list with four elements: `(left-padding top-padding right-padding bottom-padding)`. **(pdf-annotation-padding-set! *****annot padding*****)** Sets the padding of PDF annotation *annot* to *padding*. *padding* is a list of four flonum values: `(left-padding top-padding right-padding bottom-padding)`. If *padding* is `#f`, padding is removed from *annot*. **(pdf-annotation-border *****annot*****)** Returns the border of PDF annotation *annot*. If *annot* does not have a border, `#f` is returned. The border is expressed either as a list of two elements `(border-type line-width)` or three elements `(border-type line-width dash-pattern)` for dashed borders. The supported border types are `solid`, `dashed`, `beveled`, `inset`, and `underline`. The line width is a flonum value in points. The dash pattern is a list of flonum values that specify the lengths (measured in points) of the line segments and gaps in the pattern. The values in the array alternate, starting with the first line segment length, followed by the first gap length. **(pdf-annotation-border-set! *****annot border*****)** Sets the border of the PDF annotation *annot* to *border*. *border* is either a list of two elements `(border-type line-width)` or three elements `(border-type line-width dash-pattern)` for dashed borders. The supported border types are `solid`, `dashed`, `beveled`, `inset`, and `underline`. The line width is a flonum value in points. The dash pattern is a list of flonum values that specify the lengths (measured in points) of the line segments and gaps in the pattern. The values in the array alternate, starting with the first line segment length, followed by the first gap length. *border* may also be `#f`, in which case the border of *annot* is cleared. **(pdf-annotation-contents *****annot*****)** Returns a string representing the textual content associated with the PDF annotation *annot*. `#f` is returned if there is no textual content associated with *annot*. **(pdf-annotation-contents-set! *****annot str*****)** Sets the textual content of PDF annotation *annot* to string *str*. If *str* is `#f`, the existing textual content associated with *annot* is cleared. **(pdf-annotation-alignment *****annot*****)** Returns a symbol representing the textual alignment used by PDF annotation *annot*. Supported alignment values are `left`, `right`, `center`, `justified`, and `natural`. **(pdf-annotation-alignment-set! *****annot alignment*****)** Sets the textual alignment used by PDF annotation *annot* to *alignment*. *alignment* is one of the following symbols: `left`, `right`, `center`, `justified`, and `natural`. **(pdf-annotation-text-intent *****annot*****)** Returns the text intent associated with PDF annotation *annot* as a symbol (for the supported intents) or string (for the unsupported ones). The two supported intents are `callout` and `type-writer`. **(pdf-annotation-text-intent-set! *****annot intent*****)** Sets the text intent associated with PDF annotation *annot* to *intent*. *intent* is either a string, or one of the two supported symbols `callout` and `type-writer`. If *intent* is `#f`, the text intent is cleared. **(pdf-annotation-font *****annot*****)** Returns the font associated with PDF annotation *annot*. If no font is associated with *annot*, `#f` is returned. **(pdf-annotation-font-set! *****annot font*****)** Associates *font* with PDF annotation *annot*. *font* is a font object as defined by library `(lispkit draw)`. **(pdf-annotation-color *****annot*****)** Returns the annotation color of PDF annotation *annot*. **(pdf-annotation-color-set! *****annot color*****)** Sets the annotation color of PDF annotation *annot* to *color*. *color* is a color object as defined by library `(lispkit draw)`. **(pdf-annotation-interior-color *****annot*****)** Returns the interior color of PDF annotation *annot*. **(pdf-annotation-interior-color-set! *****annot color*****)** Sets the interior color of PDF annotation *annot* to *color*. *color* is a color object as defined by library `(lispkit draw)`. **(pdf-annotation-background-color *****annot*****)** Returns the background color of PDF annotation *annot*. **(pdf-annotation-background-color-set! *****annot color*****)** Sets the background color of PDF annotation *annot* to *color*. *color* is a color object as defined by library `(lispkit draw)`. **(pdf-annotation-font-color *****annot*****)** Returns the font color of PDF annotation *annot*. **(pdf-annotation-font-color-set! *****annot color*****)** Sets the font color of PDF annotation *annot* to *color*. *color* is a color object as defined by library `(lispkit draw)`. **(pdf-annotation-start-point *****annot*****)** Returns a pair consisting of the point where a line begins, in annotation-space coordinates, and a symbol specifying the start line style. Supported line styles are `none`, `square`, `circle`, `diamond`, `open-arrow`, `closed-arrow`. Custom line styles are represented as strings. **(pdf-annotation-start-point-set! *****annot point*****)** \ \&#xNAN;**(pdf-annotation-start-point-set! *****annot style*****)**\ \&#xNAN;**(pdf-annotation-start-point-set! *****annot point style*****)** Sets the starting point of a line represented by PDF annotation *annot* to *point* and the corresponding start line style to *style*. Supported line styles are `none`, `square`, `circle`, `diamond`, `open-arrow`, `closed-arrow`. Custom line styles are represented as strings. **(pdf-annotation-end-point *****annot*****)** Returns a pair consisting of the point where a line ends, in annotation-space coordinates, and a symbol specifying the end line style. Supported line styles are `none`, `square`, `circle`, `diamond`, `open-arrow`, `closed-arrow`. Custom line styles are represented as strings. **(pdf-annotation-end-point-set! *****annot point*****)** \ \&#xNAN;**(pdf-annotation-end-point-set! *****annot style*****)**\ \&#xNAN;**(pdf-annotation-end-point-set! *****annot point style*****)** Sets the end point of a line represented by PDF annotation *annot* to *point* and the corresponding end line style to *style*. Supported line styles are `none`, `square`, `circle`, `diamond`, `open-arrow`, `closed-arrow`. Custom line styles are represented as strings. **(pdf-annotation-icon *****annot*****)** Returns the type of icon to display for a pop-up text annotation represented by PDF annotation *annot* as a symbol. Supported icon types are `comment`, `key`, `note`, `help`, `new-paragraph`, `paragraph`, and `insert`. **(pdf-annotation-icon-set! *****annot icon*****)** Sets the icon type for PDF annotation *annot* to *icon*. *icon* is one of the following supported icon types: `comment`, `key`, `note`, `help`, `new-paragraph`, `paragraph`, and `insert`. The icon type is only relevant for pop-up text annotations. **(pdf-annotation-stamp *****annot*****)** Returns the stamp string associated with PDF annotation *annot*. If there is no stamp associated with *annot*, `#f` is returned. **(pdf-annotation-stamp-set! *****annot stamp*****)** Sets the stamp of PDF annotation *annot* to *stamp*. *stamp* is a string or `#f` if no stamp should be associated. **(pdf-annotation-popup *****annot*****)** Returns a pair consisting of a PDF popup annotation and a boolean value indicating whether the popup annotation is open (`#t`) or not (`#f`). If no popup annotation is associated with PDF annotation *annot*, then `#f` is returned. **(pdf-annotation-popup-set! *****annot popup*****)** \ \&#xNAN;**(pdf-annotation-popup-set! *****annot popup*****)**\ \&#xNAN;**(pdf-annotation-popup-set! *****annot popannot open*****)** Associates a popup annotation with PDF annotation *annot*. *popup* is either a PDF annotation, or it is a pair consisting of a PDF annotation and a boolean value indicating whether the popup annotation is open (`#t`) or not (`#f`). If two arguments are provided, *popannot* refers to a PDF annotation and boolean *open* to its open status. If *popannot* is `()`, then the current PDF popup annotation remains as is. If *popannot* is `#f`, it is being removed. **(pdf-annotation-markup-type *****annot*****)** Returns the markup type of PDF annotation *annot*. The markup type is either `highlight`, `strike-out`, `underline`, `redact`, or `#f` if no markup type is defined. **(pdf-annotation-markup-type-set! *****annot type*****)** Sets the markup type of PDF annotation *annot* to *type*. *type* is either `#f` (for no markup type) or one of the following symbols: `highlight`, `strike-out`, `underline`, or `redact`. **(pdf-annotation-markup-points *****annot*****)** Returns the quadrilateral points that define the marked text region, or `#f` if no text is marked up by PDF annotation *annot*. The quadrilateral points are returned as a list of points bounding the marked-up text. **(pdf-annotation-markup-points-set! *****annot points*****)** Sets the quadrilateral points that define the text region marked-up by PDF annotation *annot* to *points*. *points* is a list of points or `#f`, which will remove existing quadrilateral points. **(pdf-annotation-callout-points *****annot*****)** Returns the callout points associated with callout annotation *annot*. A callout annotation includes a text box and an arrow that can be moved independently of the text box. The arrow consists of an optional knee line followed by an end-point line defined by 2 or 3 points. These are returned by `pdf-annotation-callout-points` as a list of 2 or 3 points. `#f` is returned if there are no callout points. **(pdf-annotation-callout-points-set! *****annot copts*****)** Sets the callout points of callout annotation *annot* to *copts*. A callout annotation includes a text box and an arrow that can be moved independently of the text box. The arrow consists of an optional knee line followed by an end-point line defined by 2 or 3 points. *copts* is either a 2 or 3 point list. Alternatively, *copts* can be set to `#f`, in which case potentially existing callout points are being removed. **(pdf-annotation-shapes *****annot*****)** Returns a list of shape objects that compose the PDF annotation *annot*. Shape objects are defined by library `(lispkit draw)`. They are provided in annotation-space coordinates. **(pdf-annotation-shape-add! *****annot sh*****)** Adds a shape object *sh* to the list of shape objects that compose the PDF annotation *annot*. Shape objects are defined by library `(lispkit draw)`. They are provided in annotation-space coordinates. **(pdf-annotation-shapes-clear! *****annot*****)** Removes all shape objects from the PDF annotation *annot*. Shape objects are defined by library `(lispkit draw)`. They define the overall shape of a PDF annotation. **(pdf-annotation-modification-date *****annot*****)** Returns the modification date of PDF annotation *annot* as a date-time object as defined by library `(lispkit date-time)`. **(pdf-annotation-modification-date-set! *****annot dt*****)** Sets the modification date of PDF annotation *annot* to *dt*. *dt* is a date-time object as defined by library `(lispkit date-time)`. **(pdf-annotation-username *****annot*****)** Returns the username associated with PDF annotation *annot* as a string or `#f` if there is no associated username. **(pdf-annotation-username-set! *****annot name*****)** Sets the username associated with PDF annotation *annot* to *name*. *name* is either a string or it is `#f`, in which case a potentially existing username is being removed. **(pdf-annotation-url *****annot*****)** Returns the URL associated with PDF annotation *annot* as a string. `#f` is returned if there is no associated URL. **(pdf-annotation-url-set! *****annot url*****)** Sets the URL associated with PDF annotation *annot* to *url*. *url* is either a string or it is `#f`, in which case a potentially existing URL is being removed. **(pdf-annotation-destination *****annot*****)** Returns the document destination for link annotation *annot*. A destination is defined in terms of a list with three elements: (*page* *point* *zoom*). *page* is a PDF page which is the target destination for this outline object. *point* is a specific point on that page and *zoom* is a floating-point number defining the zoom factor for that destination. All elements can be `#f` if not defined. **(pdf-annotation-destination-set! *****annot dest*****)** \ \&#xNAN;**(pdf-annotation-destination-set! *****annot page*****)**\ \&#xNAN;**(pdf-annotation-destination-set! *****annot page point*****)**\ \&#xNAN;**(pdf-annotation-destination-set! *****annot page point zoom*****)** Sets the document destination for link annotation *annot* . If *dest* is provided, it is either `#f` (which will remove the destination), or a list with exactly three elements: (*page* *point* *zoom*). Alternatively, *page*, *point*, and *zoom* can be provided individually. *page* is a PDF page which is the target destination for this outline object. *point* is a specific point on that page and *zoom* is a floating-point number defining the zoom factor for that destination. *point* and *zoom* can be `#f` if not defined. **(pdf-annotation-action *****annot*****)** Returns the action associated with PDF annotation *annot*, or `#f` if no action is defined. The following forms of actions are supported: * (`goto` *page point*): Goes to *point* on *page*. * (`goto-remote` *url page-index point*): Opens a PDF document at *url* and goes to *point* on the page with index *page-index*. * (`goto-url` *url*): Opens the page/document at *url*. * (`perform` *action-name*): Performs a named action. *action-name* is one of the following symbols: `none`, `find`, `go-back`, `go-forward`, `goto-page`, `first-page`, `last-page`, `next-page`, `previous-page`, `print`, `zoom-in`, or `zoom-out`. * (`reset-fields` *name ...*): Resets the fields with the names *name ...*. *name ...* are strings. * (`reset-fields-except` *name ...*): Resets all fields except for the ones with the names *name ...*. *name ...* are strings. **(pdf-annotation-action-set! *****annot action*****)** Sets the action of PDF annotation *annot* to *action*. *action* is a PDF action matching one of the following supported forms of actions: * (`goto` *page point*): Goes to *point* on *page*. * (`goto-remote` *url page-index point*): Opens a PDF document at *url* and goes to *point* on the page with index *page-index*. * (`goto-url` *url*): Opens the page/document at *url*. * (`perform` *action-name*): Performs a named action. *action-name* is one of the following symbols: `none`, `find`, `go-back`, `go-forward`, `goto-page`, `first-page`, `last-page`, `next-page`, `previous-page`, `print`, `zoom-in`, or `zoom-out`. * (`reset-fields` *name ...*): Resets the fields with the names *name ...*. *name ...* are strings. * (`reset-fields-except` *name ...*): Resets all fields except for the ones with the names *name ...*. *name ...* are strings. **(pdf-annotation-display *****annot*****)** Returns a boolean value indicating whether the PDF annotation *annot* should be displayed. **(pdf-annotation-display-set! *****annot disp?*****)** Controls whether the PDF annotation *annot* should be displayed. If *disp?* is `#f`, the annotation will be hidden, otherwise shown. **(pdf-annotation-print *****annot*****)** Returns a boolean value indicating whether the PDF annotation *annot* should appear when the document is printed. **(pdf-annotation-print-set! *****annot print?*****)** Controls whether the PDF annotation *annot* should be printed. If *print?* is `#f`, the annotation will be hidden while printing, otherwise shown. **(pdf-annotation-highlighted *****annot*****)** Returns a boolean value indicating whether the PDF annotation *annot* is in a highlighted state, such as when the mouse is down on a link annotation. **(pdf-annotation-highlighted-set! *****annot highl?*****)** Controls whether the PDF annotation *annot* should be put into a highlighted state, such as when the mouse is down on a link annotation. If *highl?* is `#f`, the annotation will not be in highlighted state, otherwise it will. **(pdf-annotation-attributes *****annot*****)** Returns the attribute dictionary of the PDF annotation *annot* as an association list mapping symbols to attribute values. **(pdf-annotation-attributes-ref *****annot attrib*****)** Returns the attribute value for the given attribute key *attrib* (a symbol) from the dictionary of the PDF annotation *annot*. `#f` is returned if attribute *attrib* does not exist. **(pdf-annotation-attributes-set! *****annot attrib val*****)** Sets the attribute given by symbol *attrib* to the attribute value *val* for the dictionary of the PDF annotation *annot*. **(pdf-annotation-attributes-remove! *****annot attrib*****)** Removes the attribute identified by symbol *attrib* from the dictionary of the PDF annotation *annot*. **(draw-pdf-annotation *****annot box-spec rect drawing*****)** Draws the PDF annotation *annot* within the display box specified by *box-spec* into *drawing*. Drawings are defined by library `(lispkit draw)`. *box-spec* is one of the following symbols: `media-box`, `crop-box`, `bleed-box`, `trim-box`, and `art-box`. *rect* specifies a rectangular region into which *page* is drawn. *rect* is a rectangle specified by an expression of this form: `((x . y) . (w . h))`. ## Paper sizes **letter-size** \ **legal-size**\ **executive-size**\ **a2-size**\ **a3-size**\ **a4-size**\ **a5-size**\ **a6-size**\ **b3-size**\ **b4-size**\ **b5-size**\ **b6-size**\ **c3-size**\ **c4-size**\ **c5-size**\ **c6-size** A size object representing a corresponding standardize size of a page in points. The size object is assuming 72 ppi, i.e. that there are 72 points per inch. ```scheme ;; US sizes letter-size ⇒ (612.0 . 792.0) ; 8.5" × 11" legal-size ⇒ (612.0 . 1008.0) ; 8.5" × 14" executive-size ⇒ (522.0 . 756.0) ; 7.25" × 10.5" ;; ISO sizes a2-size ⇒ (1190.4 . 1683.6) a3-size ⇒ (841.8 . 1190.4) a4-size ⇒ (595.2 . 841.8) a5-size ⇒ (419.4 . 595.2) a6-size ⇒ (297.6 . 419.4) ```