From 2340174a9190a45eaa5562dffbf5901ee8aadcbd Mon Sep 17 00:00:00 2001 From: John Whitington Date: Thu, 13 Jan 2022 15:18:21 +0000 Subject: [PATCH] more --- cpdfattach.mli | 22 ++++++++++++++-------- cpdfbookmarks.ml | 1 - cpdfbookmarks.mli | 17 +++++++++++++---- cpdfcoord.mli | 9 ++++++++- cpdfmetadata.mli | 4 ++++ cpdfpagespec.mli | 2 +- cpdfposition.mli | 2 ++ cpdfpresent.mli | 3 +-- 8 files changed, 43 insertions(+), 17 deletions(-) diff --git a/cpdfattach.mli b/cpdfattach.mli index 58b6c7b..4e32872 100644 --- a/cpdfattach.mli +++ b/cpdfattach.mli @@ -1,18 +1,24 @@ -(** {2 File Attachments} *) -val remove_unsafe_characters : Cpdfmetadata.encoding -> string -> string - -(** [attach_file keepversion topage pdf filename] attaches the file in [filename] to the pdf, optionally to a page (rather than document-level). If keepversion is true, the PDF version number won't be altered. *) -val attach_file : ?memory:Pdfio.bytes -> bool -> int option -> Pdf.t -> string -> Pdf.t - -(** Remove attached files. *) -val remove_attached_files : Pdf.t -> Pdf.t +(** File Attachments *) type attachment = {name : string; pagenumber : int; data : unit -> Pdfio.bytes} +(** Remove characters which might not make good filenames. If the encoding is + [Cpdfmetadata.Stripped] we in addition lose any character > 126. *) +val remove_unsafe_characters : Cpdfmetadata.encoding -> string -> string + +(** [attach_file keepversion topage pdf filename] attaches the file in + [filename] to the pdf, optionally to a page (rather than document-level). + If keepversion is true, the PDF version number won't be altered. *) +val attach_file : ?memory:Pdfio.bytes -> bool -> int option -> Pdf.t -> string -> Pdf.t + +(** Remove attached files. *) +val remove_attached_files : Pdf.t -> Pdf.t + (** List attached files. Attachment name and page number. Page 0 is document level. *) val list_attached_files : Pdf.t -> attachment list +(** Dump attached files to a given directory. *) val dump_attached_files : Pdf.t -> string -> unit diff --git a/cpdfbookmarks.ml b/cpdfbookmarks.ml index 29038b5..1d6cef8 100644 --- a/cpdfbookmarks.ml +++ b/cpdfbookmarks.ml @@ -413,4 +413,3 @@ let change_destination t = function let change_bookmark t m = {m with Pdfmarks.target = try change_destination t m.Pdfmarks.target with Not_found -> m.Pdfmarks.target} - diff --git a/cpdfbookmarks.mli b/cpdfbookmarks.mli index 7772c0c..79723ba 100644 --- a/cpdfbookmarks.mli +++ b/cpdfbookmarks.mli @@ -1,24 +1,33 @@ -(** {2 Bookmarks} *) +(** Bookmarks *) (** [parse_bookmark_file verify pdf input] parses the bookmark file in [input]. -Details of the bookmark file format can be found in cpdfmanual.pdf *) +Details of the bookmark file format can be found in cpdfmanual.pdf. *) val parse_bookmark_file : bool -> Pdf.t -> Pdfio.input -> Pdfmarks.t list (** [add_bookmarks verify input pdf] adds bookmarks from the bookmark file give. If [verify] is given, bookmarks will be verified to ensure, for example, -that they are not out of the page range. *) +that they are not out of the page range. In the new JSON format if chosen. *) val add_bookmarks : json:bool -> bool -> Pdfio.input -> Pdf.t -> Pdf.t (** [list_bookmarks encoding range pdf output] lists the bookmarks to the given -output in the format specified in cpdfmanual.pdf *) +output in the format specified in cpdfmanual.pdf. In the new JSON format if +chosen. *) val list_bookmarks : json:bool -> Cpdfmetadata.encoding -> int list -> Pdf.t -> Pdfio.output -> unit +(** [name_of_spec encoding marks pdf splitlevel spec n filename startpage + endpage] expands a bookmark specifiation filename. *) val name_of_spec : Cpdfmetadata.encoding -> Pdfmarks.t list -> Pdf.t -> int -> string -> int -> string -> int -> int -> string +(** Indent bookmarks in each file by one and add a title bookmark pointing to + the first page. If the boolean is set, then use the PDF's metadata title + instead of the filename. *) val add_bookmark_title : string -> bool -> Pdf.t -> Pdf.t +(** Set bookmarks to be open to the given level. *) val bookmarks_open_to_level : int -> Pdf.t -> Pdf.t +(** Alter bookmark destinations given a hash table of (old page reference +number, new page reference number) pairings *) val change_bookmark : (int, int) Hashtbl.t -> Pdfmarks.t -> Pdfmarks.t diff --git a/cpdfcoord.mli b/cpdfcoord.mli index aef004a..af096a6 100644 --- a/cpdfcoord.mli +++ b/cpdfcoord.mli @@ -1,8 +1,15 @@ -(* Parsing coordinates, numbers, positions etc. *) +(** Parsing coordinates, numbers, positions etc.*) + +(** See cpdfmanual.pdf for examples of things these functions can parse, such as page sizes. *) + +(** Read a list of rectangles from a string. *) val parse_rectangles : Pdf.t -> string -> (float * float * float * float) list +(** Read a coordinate from a string *) val parse_coordinate : Pdf.t -> string -> float * float +(** Read a list of coordinates from a string *) val parse_coordinates : Pdf.t -> string -> (float * float) list +(** Read a single number from a string *) val parse_single_number : Pdf.t -> string -> float diff --git a/cpdfmetadata.mli b/cpdfmetadata.mli index c1ed9ec..4f5081b 100644 --- a/cpdfmetadata.mli +++ b/cpdfmetadata.mli @@ -1,3 +1,4 @@ +(** Metadata *) (** {2 Types and Exceptions} *) @@ -7,6 +8,7 @@ all - the PDF string is output as-is. [UTF8] converts loslessly to UTF8. correspond to 7 bit ASCII. *) type encoding = Raw | UTF8 | Stripped +(** Encode a string using a given encoding. *) val encode_output : encoding -> string -> string (** {2 Metadata and settings} *) @@ -20,6 +22,7 @@ val copy_id : bool -> Pdf.t -> Pdf.t -> Pdf.t the PDF minor version to [version].*) val set_pdf_info : ?xmp_also:bool -> ?xmp_just_set:bool -> (string * Pdf.pdfobject * int) -> Pdf.t -> Pdf.t +(** Get XMP information for a given key. *) val get_xmp_info : Pdf.t -> string -> string (** [set_pdf_info (key, value, version)] sets the entry [key] in the @@ -71,4 +74,5 @@ val print_metadata : Pdf.t -> unit (** Set the metadata date *) val set_metadata_date : Pdf.t -> string -> Pdf.t +(** Expands the date ["now"] to the date now. Leaves any other string alone. *) val expand_date : string -> string diff --git a/cpdfpagespec.mli b/cpdfpagespec.mli index 018a4d0..5c4e158 100644 --- a/cpdfpagespec.mli +++ b/cpdfpagespec.mli @@ -1,4 +1,4 @@ -(** {2 Page specifications and ranges } *) +(** Page specifications and ranges *) (** Here are the rules for building input ranges: diff --git a/cpdfposition.mli b/cpdfposition.mli index a70cfe1..a38ce3a 100644 --- a/cpdfposition.mli +++ b/cpdfposition.mli @@ -1,3 +1,5 @@ +(** Positions *) + (** Possible positions for adding text and other uses. See cpdfmanual.pdf *) type position = PosCentre of float * float diff --git a/cpdfpresent.mli b/cpdfpresent.mli index 2305348..4da6a9f 100644 --- a/cpdfpresent.mli +++ b/cpdfpresent.mli @@ -1,8 +1,7 @@ -(** {2 Presentations} *) +(** Presentations *) (** [presentation range t d horizontal inward direction effect_duration pdf] adds a presentation on the pages in [range]. See cpdfmanual.pdf for details. *) val presentation : int list -> string option -> float option -> bool -> bool -> int -> float -> Pdf.t -> Pdf.t -