From 472b2c7eb339d14c57c5cb5cb24a46f0e5be9cde Mon Sep 17 00:00:00 2001 From: John Whitington Date: Tue, 27 Aug 2013 17:35:16 +0100 Subject: [PATCH] Started to improve ocamldoc documentation --- cpdf.mli | 274 +++++++++++++++++++++++++++-------------------- cpdfcommand.mli | 6 +- cpdfstrftime.mli | 4 +- 3 files changed, 163 insertions(+), 121 deletions(-) diff --git a/cpdf.mli b/cpdf.mli index b31b989..75b5e3d 100644 --- a/cpdf.mli +++ b/cpdf.mli @@ -1,8 +1,36 @@ (** Coherent PDF Tools Core Routines *) open Pdfutil +(** {2 Types and Exceptions} *) + type encoding = Raw | UTF8 | Stripped +exception SoftError of string +exception HardError of string + +(** {2 Debug} *) + +(** Debug: Print out a PDF in readable form to the terminal *) +val print_pdf_objs : Pdf.t -> unit + +(** {2 Working with pages} *) + +(** Like [Pdfpage.endpage], but from an input and possible password - does the +minimal work to find the number of pages. *) +val endpage_io : Pdfio.input -> string option -> string option -> int + +(** Given a function from page number and page to page, a document, and a list +of page numbers to apply it to, apply the function to all those pages. *) +val process_pages : (int -> Pdfpage.t -> Pdfpage.t) -> Pdf.t -> int list -> Pdf.t + +(** Same, but just iterate *) +val iter_pages : (int -> Pdfpage.t -> unit) -> Pdf.t -> int list -> unit + +(** Same, but map *) +val map_pages : (int -> Pdfpage.t -> 'a) -> Pdf.t -> int list -> 'a list + +(** {2 Page specifications and ranges } *) + val parse_pagespec : Pdf.t -> string -> int list val string_of_pagespec : Pdf.t -> int list -> string @@ -11,11 +39,7 @@ val validate_pagespec : string -> bool val name_of_spec : bool -> Pdfmarks.t list -> Pdf.t -> int -> string -> int -> string -> int -> int -> string -(** Debug: Print out a PDF in readable form to the terminal *) -val print_pdf_objs : Pdf.t -> unit - -(** Same, but from an input and possible password - does the minimal work to find the number of pages. *) -val endpage_io : Pdfio.input -> string option -> string option -> int +(** {2 Compress and Decompress} *) (** Compresses all streams in the PDF document which are uncompressed, using /FlateDecode, leaving out metadata. If the PDF is encrypted, does nothing. *) @@ -23,111 +47,107 @@ val recompress_pdf : Pdf.t -> Pdf.t val decompress_pdf : Pdf.t -> Pdf.t -(* [set_pdf_info (key, value, version)] sets the entry [key] in the /Info directory, updating +(** {2 Metadata and settings} *) + +(** [copy_id keepversion copyfrom copyto] *) +val copy_id : bool -> Pdf.t -> Pdf.t -> Pdf.t + +(** [set_pdf_info (key, value, version)] sets the entry [key] in the /Info directory, updating the PDF minor version to [version].*) val set_pdf_info : (string * Pdf.pdfobject * int) -> Pdf.t -> Pdf.t -(* [set_pdf_info (key, value, version)] sets the entry [key] in the +(** [set_pdf_info (key, value, version)] sets the entry [key] in the /ViewerPreferences directory, updating the PDF minor version to [version].*) val set_viewer_preference : (string * Pdf.pdfobject * int) -> Pdf.t -> Pdf.t -(* Set the page layout to the given name (sans slash) e.g SinglePage *) +(** Set the page layout to the given name (sans slash) e.g SinglePage *) val set_page_layout : Pdf.t -> string -> Pdf.t -(* Set the page layout to the given name (sans slash) e.g SinglePage *) +(** Set the page layout to the given name (sans slash) e.g SinglePage *) val set_page_mode : Pdf.t -> string -> Pdf.t -(* Expand the string "now" to a PDF date string, ignoring any other string *) -val expand_date : string -> string +val set_version : int -> Pdf.t -> unit -(* Given a function from page number and page to page, a document, and a list -of page numbers to apply it to, apply the function to all those pages. *) -val process_pages : (int -> Pdfpage.t -> Pdfpage.t) -> Pdf.t -> int list -> Pdf.t +(** Output to standard output general information about a PDF. *) -(* Same, but just iterate *) -val iter_pages : (int -> Pdfpage.t -> unit) -> Pdf.t -> int list -> unit +val get_info_utf8 : Pdf.t -> string -> string -(* Same, but map *) -val map_pages : (int -> Pdfpage.t -> 'a) -> Pdf.t -> int list -> 'a list +val output_info : encoding -> Pdf.t -> unit -(* Two possible error classes. *) -exception SoftError of string -exception HardError of string +(** {2 Presentations} *) -(* [presentation range t d h i dir effect_dur pdf] *) +(** [presentation range t d h i dir effect_dur pdf] *) val presentation : int list -> string option -> float option -> bool -> bool -> int -> float -> Pdf.t -> Pdf.t -(* [attach_file keep-version topage pdf filename] *) +(** {2 File Attachments} *) +(** [attach_file keep-version topage pdf filename] *) val attach_file : bool -> int option -> Pdf.t -> string -> Pdf.t -(* Remove attached files. *) +(** Remove attached files. *) val remove_attached_files : Pdf.t -> Pdf.t -(* List attached files. Attachment name and page number. Page 0 is document level. *) +(** List attached files. Attachment name and page number. Page 0 is document level. *) val list_attached_files : Pdf.t -> (string * int) list -(* [parse_bookmark_file verify pdf input] *) +(** {2 Bookmarks} *) + +(** [parse_bookmark_file verify pdf input] *) val parse_bookmark_file : bool -> Pdf.t -> Pdfio.input -> Pdfmarks.t list -(* [add_bookmarks verify input pdf] *) +(** [add_bookmarks verify input pdf] *) val add_bookmarks : bool -> Pdfio.input -> Pdf.t -> Pdf.t -(* [copy_id keepversion copyfrom copyto] *) -val copy_id : bool -> Pdf.t -> Pdf.t -> Pdf.t +(** [list_bookmarks deunicode range page_offset pdf output] *) +val list_bookmarks : encoding -> int list -> Pdf.t -> Pdfio.output -> unit -(* [set_metadata keepversion filename pdf] *) +(** {2 XML Metadata} *) + +(** [set_metadata keepversion filename pdf] *) val set_metadata : bool -> string -> Pdf.t -> Pdf.t val set_metadata_from_bytes : bool -> Pdfio.bytes -> Pdf.t -> Pdf.t -(* Remove the metadata from a file *) +(** Remove the metadata from a file *) val remove_metadata : Pdf.t -> Pdf.t -(* [combine_pages fast under over scaletofit swap equalize] *) -val combine_pages : bool -> Pdf.t -> Pdf.t -> bool -> bool -> bool -> Pdf.t - -(* [stamp scale_to_fit fast isover range over pdf] stamps the first page of [over] over each page of the PDF. *) -val stamp : bool -> bool -> bool -> int list -> Pdf.t -> Pdf.t -> Pdf.t - -(* [list_bookmarks deunicode range page_offset pdf output] *) -val list_bookmarks : encoding -> int list -> Pdf.t -> Pdfio.output -> unit - -(* Custom CSP1 *) -val custom_csp1 : Pdf.t -> Pdf.t - -(* Custom CSP2 *) -val custom_csp2 : float -> Pdf.t -> Pdf.t - -(* FIXME: Horrid - should return PDFs, write to file separtely. *) -(* [split_at_bookmarks linearize nobble level spec pdf] *) -val split_at_bookmarks : string -> bool -> (Pdf.t -> Pdf.t) -> int -> string -> Pdf.t -> unit - -(* The new one *) -val split_on_bookmarks : Pdf.t -> int -> Pdf.t list - -(* [split_pdf printf chunksize linearize nobble spec pdf] *) -val split_pdf : Pdfwrite.encryption option -> bool -> string -> int -> bool -> (Pdf.t -> Pdf.t) -> string -> Pdf.t -> unit - -(* Nobble a page, given pdf, pagenumber and page *) -val nobble_page : Pdf.t -> 'a -> Pdfpage.t -> Pdfpage.t - -(* Print page info (Mediabox etc) *) -val output_page_info : Pdf.t -> unit - -val hasbox : Pdf.t -> int -> string -> bool - -(* Print metadate to stdout *) +(** Print metadate to stdout *) val get_metadata : Pdf.t -> Pdfio.bytes val print_metadata : Pdf.t -> unit -(* Print font list to stdout *) +(** {2 Stamping} *) + +(** [combine_pages fast under over scaletofit swap equalize] *) +val combine_pages : bool -> Pdf.t -> Pdf.t -> bool -> bool -> bool -> Pdf.t + +(** [stamp scale_to_fit fast isover range over pdf] stamps the first page of [over] over each page of the PDF. *) +val stamp : bool -> bool -> bool -> int list -> Pdf.t -> Pdf.t -> Pdf.t + +(** {2 Splitting PDFs} *) + +(** [split_at_bookmarks linearize nobble level spec pdf] *) +val split_at_bookmarks : string -> bool -> (Pdf.t -> Pdf.t) -> int -> string -> Pdf.t -> unit + +(** The new one *) +val split_on_bookmarks : Pdf.t -> int -> Pdf.t list + +(** [split_pdf printf chunksize linearize nobble spec pdf] *) +val split_pdf : Pdfwrite.encryption option -> bool -> string -> int -> bool -> (Pdf.t -> Pdf.t) -> string -> Pdf.t -> unit + +(** {2 Listing fonts} *) + +(** Print font list to stdout *) val print_fonts : Pdf.t -> unit val list_fonts : Pdf.t -> (int * string * string * string * string) list -(* Possible positions for adding text and other uses. *) +(** {2 Adding text} *) + +(** Expand the string "now" to a PDF date string, ignoring any other string *) +val expand_date : string -> string + +(** Possible positions for adding text and other uses. *) type position = | PosCentre of float * float | PosLeft of float * float @@ -155,14 +175,14 @@ type justification = | CentreJustify | RightJustify -(* [calculate ignore_d w (xmin, ymin, xmax, ymax) shorterside pos] *) +(** [calculate ignore_d w (xmin, ymin, xmax, ymax) shorterside pos] *) val calculate_position : bool -> float -> float * float * float * float -> orientation -> position -> float * float * float -(* Returns what the added text string would be *) +(** Returns what the added text string would be *) (*val addtext_returntext : Pdf.t -> string -> int -> string -> int -> string*) val metrics_howmany : unit -> int @@ -172,7 +192,7 @@ val metrics_y : int -> float val metrics_rot : int -> float val metrics_baseline_adjustment : unit -> float -(* [add_texts fontname font bates colour positino linespacing fontsize shorterside text pages pdf] *) +(** [add_texts fontname font bates colour positino linespacing fontsize shorterside text pages pdf] *) val addtexts : bool -> (*metrics*) float -> (*linewidth*) @@ -197,109 +217,125 @@ val addtexts : Pdf.t ->(*pdf*) Pdf.t -(* Remove text from the given pages. *) +(** Remove text from the given pages. *) val removetext : int list -> Pdf.t -> Pdf.t -(* Modify the rotation of the page and its contents to leave the rotation at 0 with the page effectively unaltered. *) -val upright : ?fast:bool -> int list -> Pdf.t -> Pdf.t +(** {2 Page geometry} *) -(* [crop_pdf x y w h pdf range] *) +(** Print page info (Mediabox etc) *) +val output_page_info : Pdf.t -> unit + +val hasbox : Pdf.t -> int -> string -> bool + +(** [crop_pdf x y w h pdf range] *) val crop_pdf : float -> float -> float -> float -> Pdf.t -> int list -> Pdf.t -(* [set_mediabox x y w h pdf range] *) +(** [set_mediabox x y w h pdf range] *) val set_mediabox : float -> float -> float -> float -> Pdf.t -> int list -> Pdf.t val setBox : string -> float -> float -> float -> float -> Pdf.t -> int list -> Pdf.t -(* Remove any cropping from the given pages. *) +(** Remove any cropping from the given pages. *) val remove_cropping_pdf : Pdf.t -> int list -> Pdf.t val remove_trim_pdf : Pdf.t -> int list -> Pdf.t val remove_bleed_pdf : Pdf.t -> int list -> Pdf.t val remove_art_pdf : Pdf.t -> int list -> Pdf.t -(* Change rotation to a given value 0, 90, 180, 270 on given pages. *) +(** Change rotation to a given value 0, 90, 180, 270 on given pages. *) val rotate_pdf : int -> Pdf.t -> int list -> Pdf.t -(* Rotate clockwise by 0, 90, 180, 270 on given pages. *) +(** Rotate clockwise by 0, 90, 180, 270 on given pages. *) val rotate_pdf_by : int -> Pdf.t -> int list -> Pdf.t -(* Rotate the contents by the given angle on the given pages. *) +(** Rotate the contents by the given angle on the given pages. *) val rotate_contents : ?fast:bool -> float -> Pdf.t -> int list -> Pdf.t -(* Flip the given pages vertically *) +(** Modify the rotation of the page and its contents to leave the rotation at 0 with the page effectively unaltered. *) +val upright : ?fast:bool -> int list -> Pdf.t -> Pdf.t + +(** Flip the given pages vertically *) val vflip_pdf : ?fast:bool -> Pdf.t -> int list -> Pdf.t -(* Flip the given pages horizontally *) +(** Flip the given pages horizontally *) val hflip_pdf : ?fast:bool -> Pdf.t -> int list -> Pdf.t -(* Shift a PDF in x and y (in pts) in the given pages. *) +(** Shift a PDF in x and y (in pts) in the given pages. *) val shift_pdf : ?fast:bool -> float -> float -> Pdf.t -> int list -> Pdf.t -(* Scale a PDF in sx, sy in the given pages. *) +(** Scale a PDF in sx, sy in the given pages. *) val scale_pdf : ?fast:bool -> float -> float -> Pdf.t -> int list -> Pdf.t -(* FIXME: See .ml *) -(* [scale_to_fit_pdf input_scale x y op pdf range] *) +(** [scale_to_fit_pdf input_scale x y op pdf range] *) val scale_to_fit_pdf : ?fast:bool -> float -> float -> float -> 'a -> Pdf.t -> int list -> Pdf.t -(* Scale the contents of a page by a given factor centred around a given point in a given range. *) +(** Scale the contents of a page by a given factor centred around a given point in a given range. *) val scale_contents : ?fast:bool -> position -> float -> Pdf.t -> int list -> Pdf.t -(* Put blank pages before the given page numbers *) +(** {2 Padding} *) + +(** Put blank pages before the given page numbers *) val padbefore : int list -> Pdf.t -> Pdf.t -(* Put blank pages after the given page numbers *) +(** Put blank pages after the given page numbers *) val padafter : int list -> Pdf.t -> Pdf.t -(* Pad to a multiple of n pages *) +(** Pad to a multiple of n pages *) val padmultiple : int -> Pdf.t -> Pdf.t -(* List the annotations to standard output *) +(** {2 Annotations} *) + +(** List the annotations to standard output *) val list_annotations : encoding -> Pdf.t -> unit val list_annotations_more : Pdf.t -> unit val get_annotations : encoding -> Pdf.t -> (int * string) list -(* Copy the annotations on a given set of pages from a to b yielding c. *) +(** Copy the annotations on a given set of pages from a to b yielding c. *) val copy_annotations : int list -> Pdf.t -> Pdf.t -> Pdf.t -(* Remove the annotations on given pages. *) +(** Remove the annotations on given pages. *) val remove_annotations : int list -> Pdf.t -> Pdf.t -(* Two-up a PDF. *) +(** {2 Imposition} *) + +(** Two-up a PDF. *) val twoup : Pdf.t -> Pdf.t -(* Stack Two-up a PDF. *) +(** Stack Two-up a PDF. *) val twoup_stack : Pdf.t -> Pdf.t -(* Output to standard output general information about a PDF. *) -(*val get_info : bool -> Pdf.t -> string -> string*) - -val get_info_utf8 : Pdf.t -> string -> string - -val output_info : encoding -> Pdf.t -> unit - -(* Make all lines in the PDF at least a certain thickness. *) -val thinlines : int list -> float -> Pdf.t -> Pdf.t - -(* Make all text on certain pages black. *) -val blacktext : int list -> Pdf.t -> Pdf.t - -(* Make all lines on certain pages black. *) -val blacklines : int list -> Pdf.t -> Pdf.t - -(* Make all fills on certain pages black. *) -val blackfills : int list -> Pdf.t -> Pdf.t - -(* Remove images from a PDF, optionally adding crossed boxes. *) -val draft : bool -> int list -> Pdf.t -> Pdf.t - -val set_version : int -> Pdf.t -> unit - -(*i val pdf_of_pages : Pdfmarks.bookmark list option -> int list -> Pdfdoc.page list -> Pdf.t -> Pdf.t i*) +(** {2 Making new documents} *) val blank_document : float -> float -> int -> Pdf.t val blank_document_paper : Pdfpaper.t -> int -> Pdf.t +(** {2 Miscellany} *) + +(** Make all lines in the PDF at least a certain thickness. *) +val thinlines : int list -> float -> Pdf.t -> Pdf.t + +(** Make all text on certain pages black. *) +val blacktext : int list -> Pdf.t -> Pdf.t + +(** Make all lines on certain pages black. *) +val blacklines : int list -> Pdf.t -> Pdf.t + +(** Make all fills on certain pages black. *) +val blackfills : int list -> Pdf.t -> Pdf.t + +(** Remove images from a PDF, optionally adding crossed boxes. *) +val draft : bool -> int list -> Pdf.t -> Pdf.t + +(**/**) + +(** Custom CSP1 *) +val custom_csp1 : Pdf.t -> Pdf.t + +(** Custom CSP2 *) +val custom_csp2 : float -> Pdf.t -> Pdf.t + +(** Nobble a page, given pdf, pagenumber and page *) +val nobble_page : Pdf.t -> 'a -> Pdfpage.t -> Pdfpage.t + diff --git a/cpdfcommand.mli b/cpdfcommand.mli index 526661f..767d72b 100644 --- a/cpdfcommand.mli +++ b/cpdfcommand.mli @@ -1,7 +1,11 @@ -(* cpdfcommand.mli *) +(** PDF Command Line Tools in library form. *) + +(** Call the command line tools with the contents of [Sys.argv] *) val go : unit -> unit +(** Call the command line tools with a specialised [argv] of our own *) val go_withargv : string array -> unit +(**/**) val demo : bool diff --git a/cpdfstrftime.mli b/cpdfstrftime.mli index e9a366a..602a714 100644 --- a/cpdfstrftime.mli +++ b/cpdfstrftime.mli @@ -1,2 +1,4 @@ -(* C-style strftime *) +(** C-style strftime *) + +(** This supports the following format specifiers: %a %A %b %B %s %e %H %I %j %m %M %p %S %T %u %w %Y %% *) val strftime : string -> string