Updating html_manual/splits

html_manual/pysplits/c00.tex

@@ -9,7 +9,7 @@ install_name_tool command to tell libpycpdf.so where to find libcpdf.so.
 
 A 'range' is a list of integers specifying page numbers.
 
-Text arguments and results are in UTF8.
+Text arguments and results are in UTF8. Data is of type bytes.
 
 Any function may raise the exception CPDFError, carrying a string describing
 the error. """

html_manual/pysplits/c01.tex

@@ -79,9 +79,7 @@ useNone useOutlines useThumbs useOC useAttachments
 Page label styles:
 
 decimalArabic uppercaseRoman lowercaseRoman uppercaseLetters lowercaseLetters
-
+"""
-
-# CHAPTER 0. Preliminaries
 
 class Pdf:
     """The type of PDF documents."""

html_manual/pysplits/c02.tex

@@ -20,15 +20,6 @@ def fromMemoryLazy(data, userpw):
     """ Load a file from from a byte array and the user password (blank if
     none), but lazily like fromFileLazy."""
 
-def blankDocument(w, h, pages):
-    """ Create a blank document
-    with pages of the given width (in points), height (in points), and number
-    of pages."""
-
-def blankDocumentPaper(papersize, pages):
-    """Create a blank document with pages of the given paper size, and number
-    of pages. """
-
 def ptOfCm(i):
     """Convert a figure in centimetres to points (72 points to 1 inch)."""
 
@@ -48,9 +39,9 @@ def inOfPt(i):
     """Convert a figure in points to inches (72 points to 1 inch)."""
 
 def parsePagespec(pdf, pagespec):
-    """Parse a page specification such as "1-3,8-end" to a range with reference to
+    """Parse a page specification such as "1-3,8-end" to a range with reference
-    a given PDF (the PDF is supplied so that page ranges which reference pages
+    to a given PDF (the PDF is supplied so that page ranges which reference
-    which do not exist are rejected)."""
+    pages which do not exist are rejected)."""
 
 def validatePagespec(pagespec):
     """Validate a page specification, returning True or False, so far as is
@@ -95,6 +86,7 @@ def rangeLength(r):
 
 def rangeGet(r, n):
     """Get the page number at position n in a range, where
+    n runs from 0 to rangeLength - 1."""
 
 def rangeAdd(r, p):
     """Add the page to a range, if it is not already
@@ -105,9 +97,6 @@ def isInRange(r, p):
 
 def pages(pdf):
     """Return the number of pages in a PDF."""
-    r = libc.pycpdf_pages(pdf.pdf)
-    checkerror()
-    return r
 
 def pagesFast(userpw, filename):
     """Return the number of pages in a given
@@ -129,16 +118,12 @@ def toFileExt(pdf, filename, linearize, make_id, preserve_objstm,
     will be compressed (what we usually want). WARNING: the pdf argument will
     be invalid after this call and should not be used again."""
 
-
 def toMemory(pdf, linearize, make_id):
     """Write a file to memory, returning the buffer as a byte array of type
     bytes."""
 
 def isEncrypted(pdf):
     """Returns True if a documented is encrypted, False otherwise."""
-    r = libc.pycpdf_isEncrypted(pdf.pdf)
-    checkerror()
-    return r
 
 def toFileEncrypted(pdf, method, permissions, ownerpw, userpw, linearize,
                     makeid, filename):

html_manual/pysplits/c07.tex

@@ -7,3 +7,14 @@ def getBookmarks(pdf):
 def setBookmarks(pdf, marks):
     """Set the bookmarks for a PDF as a list of tuples of the form:
     (level : int, page : int, text : string, openstatus : bool)"""
+
+def getBookmarksJSON(pdf):
+    """Get the bookmarks in JSON format."""
+
+def setBookmarksJSON(pdf, data):
+    """setBookmarksJSON(pdf, data) sets the bookmarks from JSON bookmark data."""
+
+def tableOfContents(pdf, font, fontsize, title, bookmark):
+    """tableOfContents(pdf, font, fontsize, title, bookmark) typesets a table
+    of contents from existing bookmarks and prepends it to the document. If
+    bookmark is set, the table of contents gets its own bookmark."""

html_manual/pysplits/c09.tex

@@ -93,7 +93,6 @@ def addTextSimple(pdf, r, text, p, font, size):
 
 def removeText(pdf, r):
     """Remove any text added by libcpdf from the given pages."""
-    r = range_of_list(r)
 
 def textWidth(font, string):
     """Return the width of a given string in the given font in thousandths of a

html_manual/pysplits/c10.tex

@@ -1,4 +1,4 @@
-# CHAPTER 9. Mulitpage facilities
+# CHAPTER 9. Multipage facilities
 
 def twoUp(pdf):
     """Impose a document two up by retaining the existing page
@@ -8,6 +8,14 @@ def twoUpStack(pdf):
     """Impose a document two up by doubling the page size,
     to fit two pages on one."""
 
+def impose(pdf, x, y, fit, columns, rtl, btt, center, margin, spacing, linewidth):
+    """impose(pdf, x, y, fit, columns, rtl, btt, center, margin, spacing,
+    linewidth) imposes a PDF. There are two modes: imposing x * y, or imposing
+    to fit a page of size x * y. This is controlled by fit. Columns imposes by
+    columns rather than rows. rtl is right-to-left, btt bottom-to-top. Center
+    is unused for now. Margin is the margin around the output, spacing the
+    spacing between imposed inputs."""
+
 def padBefore(pdf, r):
     """Adds a blank page before each page in the given range."""
 

html_manual/pysplits/c11.tex

@@ -1,3 +1,4 @@
 # CHAPTER 10. Annotations
 
-# Not in the library version.
+def annotationsJSON(pdf):
+    """Get the annotations in JSON format."""

html_manual/pysplits/c12.tex

@@ -47,7 +47,7 @@ def getKeywordsXMP(pdf):
     """Return the XMP keywords of a document."""
 
 def getCreatorXMP(pdf):
-    """Returs the XMP creator of a document."""
+    """Return the XMP creator of a document."""
 
 def getProducerXMP(pdf):
     """Return the XMP producer of a document."""
@@ -210,8 +210,8 @@ def displayDocTitle(pdf, flag):
     """Set the display document title flag."""
 
 def openAtPage(pdf, fitflag, pagenumber):
-    """Set the PDF to open, possibly with zoom-to-fit, at the given page
+    """Set the PDF to open, possibly with zoom-to-fit, at the given page number.
-    number. """
+    """
 
 def setMetadataFromFile(pdf, filename):
     """Set the XMP metadata of a document, given a file name."""

html_manual/pysplits/c16.tex

@@ -1,6 +1,17 @@
 # CHAPTER 15. PDF and JSON
 
-def outputJSON(filename, parse_content, no_stream_data, pdf):
+def outputJSON(filename, parse_content, no_stream_data, decompress_streams, pdf):
     """Output a PDF in JSON format to the given filename. If parse_content is
-    True, page content is parsed. If no_stream_data is True, all stream data is
+    True, page content is parsed. If decompress_streams is True, streams are
-    suppressed entirely."""
+    decompressed. If no_stream_data is True, all stream data is suppressed
+    entirely."""
+
+def outputJSONMemory(pdf, parse_content, no_stream_data, decompress_streams):
+    """outputJSONMemory(pdf, parse_content, no_stream_data, decompress_stream)
+    is like outputJSON, but it write to a buffer in memory)."""
+
+def fromJSON(filename):
+    """Load a PDF from a JSON file given its filename."""
+
+def fromJSONMemory(data):
+    """ Load a PDF from JSON data in memory."""

html_manual/pysplits/c18.tex

@@ -1,41 +1,20 @@
-# CHAPTER 17. Miscellaneous
+# CHAPTER 17. Creating New PDFs
 
-def draft(pdf, r, boxes):
+def blankDocument(w, h, pages):
-    """Remove images on the given pages, replacing
+    """ Create a blank document
-    them with crossed boxes if 'boxes' is True."""
+    with pages of the given width (in points), height (in points), and number
+    of pages."""
 
-def removeAllText(pdf, r):
+def blankDocumentPaper(papersize, pages):
-    """Remove all text from the given pages in a document."""
+    """Create a blank document with pages of the given paper size, and number
+    of pages. """
 
-def blackText(pdf, r):
+def textToPDF(w, h, font, fontsize, filename):
-    """Blacken all text on the given pages."""
+    """textToPDF(w, h, font, fontsize, filename) typesets a UTF8 text file
+    ragged right on a page of size w * h in points in the given font and font
+    size."""
 
-def blackLines(pdf, r):
+def textToPDFPaper(papersize, font, fontsize, filename):
-    """Blacken all lines on the given pages."""
+    """textToPDF(papersize font, fontsize, filename) typesets a UTF8 text file
-
+    ragged right on a page of the given size in the given font and font
-def blackFills(pdf, r):
+    size."""
-    """Blacken all fills on the given pages."""
-
-def thinLines(pdf, r, linewidth):
-    """Thicken every line less than
-    linewidth to linewidth. Thickness given in points."""
-
-def copyId(pdf, pdf2):
-    """Copy the /ID from one pdf to pdf2."""
-
-def removeId(pdf):
-    """Remove a document's /ID"""
-
-def setVersion(pdf, version):
-    """Set the minor version number of a document."""
-
-def setFullVersion(pdf, major, minor):
-    """Set the major and minor version number of
-    a document."""
-
-def removeDictEntry(pdf, key):
-    """Remove any dictionary entry with the given
-    key anywhere in the document."""
-
-def removeClipping(pdf, r):
-    """Remove all clipping from pages in the given range"""

html_manual/pysplits/c19.tex

@@ -0,0 +1,57 @@
+# CHAPTER 18. Miscellaneous
+
+def draft(pdf, r, boxes):
+    """Remove images on the given pages, replacing
+    them with crossed boxes if 'boxes' is True."""
+
+def removeAllText(pdf, r):
+    """Remove all text from the given pages in a document."""
+
+def blackText(pdf, r):
+    """Blacken all text on the given pages."""
+
+def blackLines(pdf, r):
+    """Blacken all lines on the given pages."""
+
+def blackFills(pdf, r):
+    """Blacken all fills on the given pages."""
+
+def thinLines(pdf, r, linewidth):
+    """Thicken every line less than
+    linewidth to linewidth. Thickness given in points."""
+
+def copyId(pdf, pdf2):
+    """Copy the /ID from one pdf to pdf2."""
+
+def removeId(pdf):
+    """Remove a document's /ID"""
+
+def setVersion(pdf, version):
+    """Set the minor version number of a document."""
+
+def setFullVersion(pdf, major, minor):
+    """Set the major and minor version number of
+    a document."""
+
+def removeDictEntry(pdf, key):
+    """Remove any dictionary entry with the given
+    key anywhere in the document."""
+
+def removeDictEntrySearch(pdf, key, searchterm):
+    """Remove any dictionary entry with the given
+    key anywhere in the document, if its value matches the given search term."""
+
+def replaceDictEntry(pdf, key, newvalue):
+    """Replace any dictionary entry with the given
+    key anywhere in the document using the new value given."""
+
+def replaceDictEntrySearch(pdf, key, newvalue, searchterm):
+    """Replace any dictionary entry with the given key anywhere in the
+    document, if its value matches the given search term, with the new value
+    given."""
+
+def getDictEntries(pdf, key):
+    """Return JSON of any dict entries with the given key."""
+
+def removeClipping(pdf, r):
+    """Remove all clipping from pages in the given range"""

html_manual/splits/c02.tex

@@ -29,13 +29,6 @@ int cpdf_fromMemory(void *, int, const char[]);
  */
 int cpdf_fromMemoryLazy(void *, int, const char[]);
 
-/*
- * cpdf_blankDocument(width, height, num_pages) creates a blank document with
- * pages of the given width (in points), height (in points), and number of
- * pages.
- */
-int cpdf_blankDocument(double, double, int);
-
 /* Standard page sizes. */
 enum cpdf_papersize {
   cpdf_a0portrait,        /* A0 portrait */
@@ -56,12 +49,6 @@ enum cpdf_papersize {
   cpdf_uslegallandscape   /* US Legal landscape */
 };
 
-/*
- * cpdf_blankDocumentPaper(papersize, num_pages) makes a blank document given
- * a page size and number of pages.
- */
-int cpdf_blankDocumentPaper(enum cpdf_papersize, int);
-
 /* Remove a PDF from memory, given its number. */
 void cpdf_deletePdf(int);
 
@@ -233,7 +220,7 @@ int cpdf_pagesFast(const char[], const char[]);
 void cpdf_toFile(int, const char[], int, int);
 
 /*
- * cpdf_toFile (pdf, filename, linearize, make_id, preserve_objstm,
+ * cpdf_toFileExt (pdf, filename, linearize, make_id, preserve_objstm,
  * generate_objstm, compress_objstm) writes the file to a given filename. If
  * make_id is true, it will be given a new ID.  If preserve_objstm is true,
  * existing object streams will be preserved. If generate_objstm is true,
@@ -245,9 +232,8 @@ void cpdf_toFile(int, const char[], int, int);
 void cpdf_toFileExt(int, const char[], int, int, int, int, int);
 
 /*
- * Given a buffer of the correct size, cpdf_toFileMemory (pdf, linearize,
+ * cpdf_toFileMemory (pdf, linearize, make_id, &length) writes a PDF file it
- * make_id, &length) writes it and returns the buffer. The buffer length is
+ * and returns the buffer. The buffer length is filled in &length.
- * filled in &length.
  */
 void *cpdf_toMemory(int, int, int, int *);
 

html_manual/splits/c04.tex

@@ -8,7 +8,7 @@
 void cpdf_scalePages(int, int, double, double);
 
 /*
- * cpdf_scaleToFit(pdf, range, width height, scale) scales the content to fit
+ * cpdf_scaleToFit(pdf, range, width, height, scale) scales the content to fit
  * new page dimensions (width x height) multiplied by scale (typically 1.0).
  * Other boxed (crop etc. are altered as appropriate)
  */

html_manual/splits/c06.tex

@@ -7,7 +7,7 @@
 void cpdf_compress(int);
 
 /*
- * cpdf_uncompress(pdf) uncompresses any streams in the given PDF, so long as
+ * cpdf_decompress(pdf) decompresses any streams in the given PDF, so long as
  * the compression method is supported.
  */
 void cpdf_decompress(int);

html_manual/splits/c07.tex

@@ -68,3 +68,16 @@ void cpdf_setBookmarkText(int, const char[]);
  */
 void cpdf_endSetBookmarkInfo(int);
 
+/* cpdf_getBookmarksJSON(pdf, length) returns the bookmark data and sets the
+ * length. */
+void *cpdf_getBookmarksJSON(int, int *);
+
+/* cpdf_setBookmarksJSON(pdf, data, datalength) sets the bookmarks from JSON
+ * bookmark data. */
+void cpdf_setBookmarksJSON(int, void *, int);
+
+/* cpdf_tableOfContents(pdf, font, fontsize, title, bookmark) typesets a table
+ * of contents from existing bookmarks and prepends it to the document. If
+ * bookmark is set, the table of contents gets its own bookmark. */
+void cpdf_tableOfContents(int, int, double, const char[], int);
+

html_manual/splits/c10.tex

@@ -1,5 +1,14 @@
 /* CHAPTER 9. Multipage facilities */
 
+/* cpdf_impose(pdf, x, y, fit, columns, rtl, btt, center, margin, spacing,
+ * linewidth) imposes a PDF. There are two modes: imposing x * y, or imposing
+ * to fit a page of size x * y. This is controlled by fit. Columns imposes by
+ * columns rather than rows. rtl is right-to-left, btt bottom-to-top. Center is
+ * unused for now. Margin is the margin around the output, spacing the spacing
+ * between imposed inputs. */
+void cpdf_impose(int, double, double, int, int, int, int, int, double, double,
+                 double);
+
 /*
  * Impose a document two up. cpdf_twoUp does so by retaining the existing
  * page size, scaling pages down. cpdf_twoUpStack does so by doubling the

html_manual/splits/c11.tex

@@ -1,4 +1,6 @@
 /* CHAPTER 10. Annotations */
 
-/* Not in the library version */
+/* Return the annotations from a PDF in JSON format, returning also its length.
+ */
+void *cpdf_annotationsJSON(int, int *);
 

html_manual/splits/c12.tex

@@ -147,7 +147,7 @@ int cpdf_getPageRotation(int, int);
 int cpdf_hasBox(int, int, const char[]);
 
 /*
- * These functions get a box given the document, page range, min x, max x,
+ * These functions get a box given the document, page number, min x, max x,
  * min y, max y in points. Only succeeds if such a box exists, as checked by
  * cpdf_hasBox.
  */
@@ -292,7 +292,21 @@ char *cpdf_getPageLabelStringForPage(int, int);
 /*
  * Get page label data. Call cpdf_startGetPageLabels to find out how many
  * there are, then use these serial numbers to get the style, prefix, offset
- * and range. Call cpdf_endGetPageLabels to clean up.
+ * and start value (note not a range). Call cpdf_endGetPageLabels to clean up.
+ *
+ * For example, a document might have five pages of introduction with roman
+ * numerals, followed by the rest of the pages in decimal arabic, numbered from
+ * one:
+ *
+ * labelstyle = LowercaseRoman
+ * labelprefix = ""
+ * startpage = 1
+ * startvalue = 1
+ *
+ * labelstyle = DecimalArabic
+ * labelprefix = ""
+ * startpage = 6
+ * startvalue = 1
  */
 int cpdf_startGetPageLabels(int);
 enum cpdf_pageLabelStyle cpdf_getPageLabelStyle(int);

html_manual/splits/c15.tex

@@ -21,7 +21,7 @@ void cpdf_removeFonts(int);
 /*
  * cpdf_copyFont(from, to, range, pagenumber, fontname) copies the given font
  * from the given page in the 'from' PDF to every page in the 'to' PDF. The
- * new font is stored under it's font name.
+ * new font is stored under its font name.
  */
 void cpdf_copyFont(int, int, int, int, const char[]);
 

html_manual/splits/c16.tex

@@ -4,5 +4,15 @@
  * in JSON format to the given filename. If parse_content is true, page content
  * is parsed. If no_stream_data is true, all stream data is suppressed entirely.
  * */
-void cpdf_outputJSON(const char[], int, int, int);
+void cpdf_outputJSON(const char[], int, int, int, int);
+
+/* cpdf_outputJSONMemory(parse_content, no_stream_data, pdf, &length) is like
+ * outputJSON, but it write to a buffer in memory. The length is filled in. */
+void *cpdf_outputJSONMemory(int, int, int, int, int *);
+
+/* Load a PDF from a JSON file given its filename */
+int cpdf_fromJSON(const char[]);
+
+/* Load a PDF from a JSON file in memory, given the buffer and its length */
+int cpdf_fromJSONMemory(void *, int);
 

html_manual/splits/c18.tex

@@ -1,54 +1,23 @@
-/* CHAPTER 17. Miscellaneous */
+/* CHAPTER 17. Creating New PDFs */
+
+/* cpdf_blankDocument(width, height, num_pages) creates a blank document with
+ * pages of the given width (in points), height (in points), and number of
+ * pages.
+ */
+int cpdf_blankDocument(double, double, int);
 
 /*
- * cpdf_draft(pdf, range, boxes) removes images on the given pages, replacing
+ * cpdf_blankDocumentPaper(papersize, num_pages) makes a blank document given
- * them with crossed boxes if 'boxes' is true
+ * a page size and number of pages.
  */
-void cpdf_draft(int, int, int);
+int cpdf_blankDocumentPaper(enum cpdf_papersize, int);
 
-/*
+/* cpdf_textToPDF(w, h, font, fontsize, filename) typesets a UTF8 text file
- * cpdf_removeAllText(pdf, range) removes all text from the given pages in a
+ * ragged right on a page of size w * h in points in the given font and font
- * given document.
+ * size. */
- */
+int cpdf_textToPDF(double, double, int, double, const char[]);
-void cpdf_removeAllText(int, int);
 
-/* cpdf_blackText(pdf, range) blackens all text on the given pages. */
+/* cpdf_textToPDF(papersize font, fontsize, filename) typesets a UTF8 text file
-void cpdf_blackText(int, int);
+ * ragged right on a page of the given size in the given font and font size. */
-
+int cpdf_textToPDFPaper(int, int, double, const char[]);
-/* cpdf_blackLines(pdf, range) blackens all lines on the given pages. */
-void cpdf_blackLines(int, int);
-
-/* cpdf_blackFills(pdf, range) blackens all fills on the given pages. */
-void cpdf_blackFills(int, int);
-
-/*
- * cpdf_thinLines(pdf, range, min_thickness) thickens every line less than
- * min_thickness to min_thickness. Thickness given in points.
- */
-void cpdf_thinLines(int, int, double);
-
-/* cpdf_copyId(from, to) copies the /ID from one document to another. */
-void cpdf_copyId(int, int);
-
-/* cpdf_removeId(pdf) removes a document's /ID. */
-void cpdf_removeId(int);
-
-/* cpdf_setVersion(pdf, version) sets the minor version number of a document. */
-void cpdf_setVersion(int, int);
-
-/* cpdf_setFullVersion(pdf, major_version, minor_version) sets the full version
- * number of a document. */
-void cpdf_setFullVersion(int, int, int);
-
-/*
- * cpdf_removeDictEntry(pdf, key) removes any dictionary entry with the given
- * key anywhere in the document.
- */
-void cpdf_removeDictEntry(int, const char[]);
-
-/*
- * cpdf_removeClipping(pdf, range) removes all clipping from pages in the
- * given range.
- */
-void cpdf_removeClipping(int, int);
 

html_manual/splits/c19.tex

@@ -1,3 +1,74 @@
+/* CHAPTER 18. Miscellaneous */
+
+/*
+ * cpdf_draft(pdf, range, boxes) removes images on the given pages, replacing
+ * them with crossed boxes if 'boxes' is true
+ */
+void cpdf_draft(int, int, int);
+
+/*
+ * cpdf_removeAllText(pdf, range) removes all text from the given pages in a
+ * given document.
+ */
+void cpdf_removeAllText(int, int);
+
+/* cpdf_blackText(pdf, range) blackens all text on the given pages. */
+void cpdf_blackText(int, int);
+
+/* cpdf_blackLines(pdf, range) blackens all lines on the given pages. */
+void cpdf_blackLines(int, int);
+
+/* cpdf_blackFills(pdf, range) blackens all fills on the given pages. */
+void cpdf_blackFills(int, int);
+
+/*
+ * cpdf_thinLines(pdf, range, min_thickness) thickens every line less than
+ * min_thickness to min_thickness. Thickness given in points.
+ */
+void cpdf_thinLines(int, int, double);
+
+/* cpdf_copyId(from, to) copies the /ID from one document to another. */
+void cpdf_copyId(int, int);
+
+/* cpdf_removeId(pdf) removes a document's /ID. */
+void cpdf_removeId(int);
+
+/* cpdf_setVersion(pdf, version) sets the minor version number of a document. */
+void cpdf_setVersion(int, int);
+
+/* cpdf_setFullVersion(pdf, major_version, minor_version) sets the full version
+ * number of a document. */
+void cpdf_setFullVersion(int, int, int);
+
+/*
+ * cpdf_removeDictEntry(pdf, key) removes any dictionary entry with the given
+ * key anywhere in the document.
+ */
+void cpdf_removeDictEntry(int, const char[]);
+
+/* cpdf_removeDictEntrySearch(pdf, key, seachterm) removes any dictionary entry
+ * with the given key whose value matches the given search term. */
+void cpdf_removeDictEntrySearch(int, const char[], const char[]);
+
+/* cpdf_replaceDictEntry(pdf, key, newvalue) replaces the value associated with
+ * the given key */
+void cpdf_replaceDictEntry(int, const char[], const char[]);
+
+/* cpdf_replaceDictEntry(pdf, key, newvalue, searchterm) replaces the value
+ * associated with the given key if the existing value matches the search term.
+ */
+void cpdf_replaceDictEntrySearch(int, const char[], const char[], const char[]);
+
+/* cpdf_getDictEntries(pdf, key, length) returns a JSON array containing any
+ * and all values associated with the given key, and fills in its length. */
+void *cpdf_getDictEntries(int, const char[], int *retlen);
+
+/*
+ * cpdf_removeClipping(pdf, range) removes all clipping from pages in the
+ * given range.
+ */
+void cpdf_removeClipping(int, int);
+
 /* CHAPTER X. Internal or undocumented. */
 
 /* Internal. Used for demo versions of the commercial version of cpdflib. */