v2.7 pysplits tranche 1

docsplits/pysplits/c01.tex

@@ -1,3 +1,4 @@
+"""
 Loading the libpypcdf and libcpdf DLLs
 --------------------------------------
 
@@ -13,8 +14,8 @@ to tell ``libpycpdf.so`` where to find ``libcpdf.so``.
 Conventions
 -----------
 
-Any function may raise the exception ``CPDFError``, carrying a string describing
+Any function may raise the exception ``CPDFError``, carrying a string
-the error.
+describing the error.
 
 A 'range' is a list of integers specifying page numbers. Page numbers start at
 1. Range arguments are called `r`.
@@ -79,8 +80,18 @@ useNone useOutlines useThumbs useOC useAttachments
 Page label styles:
 
 decimalArabic uppercaseRoman lowercaseRoman uppercaseLetters lowercaseLetters
+
+Line cap types:
+
+capButt capRound capSquare
+
+Line join types:
+
+joinMiter joinRound joinBevel
 """
 
+# CHAPTER 0. Preliminaries
+
 class Pdf:
     """The type of PDF documents."""
 
@@ -109,19 +120,28 @@ def version():
     """Return the version number of the pycpdflib library."""
 
 def setFast():
-    """ Set fast mode. Some operations have a fast mode. The default is 'slow'
+    """Set fast mode. Some operations have a fast mode. The default is 'slow'
     mode, which works even on old-fashioned files. For more details, see
-    section 1.13 of the CPDF manual. This function sets the mode globally. """
+    section 1.13 of the CPDF manual. This function sets the mode globally."""
 
 def setSlow():
-    """ Set slow mode. Some operations have a fast mode. The default is 'slow'
+    """Set slow mode. Some operations have a fast mode. The default is 'slow'
     mode, which works even on old-fashioned files. For more details, see
-    section 1.13 of the CPDF manual. This function sets the mode globally. """
+    section 1.13 of the CPDF manual. This function sets the mode globally."""
+
+def embedStd14(embed):
+    """Calling this function with a true argument sets embedding for the
+    Standard 14 fonts.  You must also set the directory to load them from with
+    the embedStd14Dir function. Default value: False."""
+
+def embedStd14Dir(d):
+    """Set the directory to load Standard 14 fonts for embedding."""
+    libc.pycpdf_embedStd14Dir(str.encode(d))
 
 def clearError():
-    """ Clear the current error state. """
+    """Clear the current error state."""
 
 def onExit():
-    """ A debug function which prints some information about
+    """A debug function which prints some information about
     resource usage. This can be used to detect if PDFs or ranges are being
     deallocated properly."""

docsplits/pysplits/c02.tex

@@ -1,23 +1,22 @@
 # CHAPTER 1. Basics
 
 def fromFile(filename, userpw):
-    """ Load a PDF file from a given file.
+    """Load a PDF file from a given file.  Supply a user password (possibly
-    Supply a user password (possibly blank) in case the file is encypted. It
+    blank) in case the file is encrypted. It won't be decrypted, but sometimes
-    won't be decrypted, but sometimes the password is needed just to load the
+    the password is needed just to load the file."""
-    file."""
 
 def fromFileLazy(filename, userpw):
-    """ Loads a PDF from a file, doing only
+    """Load a PDF from a file, doing only minimal parsing. The objects will be
-    minimal parsing. The objects will be read and parsed when they are actually
+    read and parsed when they are actually needed.  Use this when the whole
-    needed.  Use this when the whole file won't be required. Also supply a user
+    file won't be required. Also supply a user password (possibly blank) in
-    password (possibly blank) in case the file is encypted. It won't be
+    case the file is encrypted. It won't be decrypted, but sometimes the
-    decrypted, but sometimes the password is needed just to load the file."""
+    password is needed just to load the file."""
 
 def fromMemory(data, userpw):
-    """ Load a file from a byte array and the user password (blank if none)."""
+    """Load a file from a byte array and the user password (blank if none)."""
 
 def fromMemoryLazy(data, userpw):
-    """ Load a file from from a byte array and the user password (blank if
+    """Load a file from from a byte array and the user password (blank if
     none), but lazily like fromFileLazy."""
 
 def ptOfCm(i):
@@ -48,27 +47,24 @@ def validatePagespec(pagespec):
     possible in the absence of the actual document."""
 
 def stringOfPagespec(pdf, r):
-    """Build a page specification from a page
+    """Build a page specification from a page range. For example, the range
-    range. For example, the range containing 1,2,3,6,7,8 in a document of 8
+    containing 1,2,3,6,7,8 in a document of 8 pages might yield "1-3,6-end"."""
-    pages might yield "1-3,6-end" """
 
 def blankRange():
     """Create a range with no pages in."""
 
 def pageRange(f, t):
-    """ Nuild a range from one page to another inclusive.
+    """Build a range from one page to another inclusive. For example,
-    For example, pageRange(3,7) gives the range 3,4,5,6,7. """
+    pageRange(3,7) gives the range 3,4,5,6,7."""
 
 def all(pdf):
     """The range containing all the pages in a given document."""
 
 def even(r):
-    """A range which contains just the even pages of another
+    """A range which contains just the even pages of another range."""
-    range."""
 
 def odd(r):
-    """A range which contains just the odd pages of another
+    """A range which contains just the odd pages of another range."""
-    range."""
 
 def rangeUnion(a, b):
     """The union of two ranges giving a range containing
@@ -99,14 +95,15 @@ def pages(pdf):
     """Return the number of pages in a PDF."""
 
 def pagesFast(userpw, filename):
-    """Return the number of pages in a given
+    """Return the number of pages in a given PDF, with given user password. It
-    PDF, with given user password. It tries to do this as fast as
+    tries to do this as fast as possible, without loading the whole file."""
-    possible, without loading the whole file."""
 
 def toFile(pdf, filename, linearize, make_id):
     """Write the file to a given filename. If linearize is True, it will be
     linearized, if supported by libcpdf. If make_id is True, it will be given a
-    new ID."""
+    new ID. NB: Unlike with the command line tool, cpdf, streams decompressed
+    during processing will not automatically be compressed when writing. Call
+    compress() first."""
 
 def toFileExt(pdf, filename, linearize, make_id, preserve_objstm,
               generate_objstm, compress_objstm):
@@ -120,7 +117,9 @@ def toFileExt(pdf, filename, linearize, make_id, preserve_objstm,
 
 def toMemory(pdf, linearize, make_id):
     """Write a file to memory, returning the buffer as a byte array of type
-    bytes."""
+    bytes. NB: Unlike with the command line tool, cpdf, streams decompressed
+    during processing will not automatically be compressed when writing. Call
+    compress() first."""
 
 def isEncrypted(pdf):
     """Returns True if a documented is encrypted, False otherwise."""
@@ -157,3 +156,8 @@ def hasPermission(pdf, perm):
 
 def encryptionKind(pdf):
     """Return the encryption method currently in use on a document."""
+
+def loadFont(name, filename):
+    """Loads a TrueType font from the given file name, and names it. It may
+    then be used when adding text or drawing, using the name in place of a
+    standard font name. """

docsplits/pysplits/c03.tex

@@ -11,10 +11,10 @@ def merge(pdfs, retain_numbering, remove_duplicate_fonts):
     same source."""
 
 def mergeSame(pdfs, retain_numbering, remove_duplicate_fonts, ranges):
-    """The same as merge, except that it has an additional argument
+    """The same as merge, except that it has an additional argument (a list of
-    - a list of page ranges. This is used to select the pages to pick from
+    page ranges). This is used to select the pages to pick from each PDF. This
-    each PDF. This avoids duplication of information when multiple discrete
+    avoids duplication of information when multiple discrete parts of a single
-    parts of a single source PDF are included."""
+    source PDF are included."""
 
 def selectPages(pdf, r):
-    """ Returns a new document which just those pages in the page range."""
+    """Returns a new document which just those pages in the page range."""

docsplits/pysplits/c04.tex

@@ -12,7 +12,7 @@ def scaleToFit(pdf, r, w, h, scale_to_fit_scale):
 
 def scaleToFitPaper(pdf, r, papersize, scale_to_fit_scale):
     """Scales the given pages to fit the given page size, possibly multiplied
-    by scale_to_fit_scale (typically 1.0)"""
+    by scale_to_fit_scale (typically 1.0)."""
 
 def scaleContents(pdf, r, pos, scale):
     """Scales the contents of the pages in the range about the point given by
@@ -20,18 +20,22 @@ def scaleContents(pdf, r, pos, scale):
 
 def shiftContents(pdf, r, dx, dy):
     """Shift the content of the pages in the range by (dx, dy)."""
+    r = range_of_list(r)
+
+def shiftBoxes(pdf, r, dx, dy):
+    """Shift the pages boxes in the range by (dx, dy)."""
 
 def rotate(pdf, r, rotation):
-    """Change the viewing rotation of the pages in the range to an
+    """Change the viewing rotation of the pages in the range to an absolute
-    absolute value. Appropriate rotations are 0, 90, 180, 270."""
+    value. Appropriate rotations are 0, 90, 180, 270."""
 
 def rotateBy(pdf, r, rotation):
-    """Change the viewing rotation of the pages in the range by a
+    """Change the viewing rotation of the pages in the range by a given number
-    given number of degrees. Appropriate values are 90, 180, 270."""
+    of degrees. Appropriate values are 90, 180, 270."""
 
 def rotateContents(pdf, r, rotation):
-    """Rotate the content about the centre
+    """Rotate the content about the centre of the page by the given number of
-    of the page by the given number of degrees, in a clockwise direction."""
+    degrees, in a clockwise direction."""
 
 def upright(pdf, r):
     """Change the viewing rotation of the pages in the range, counter-rotating

docsplits/pysplits/c06.tex

@@ -10,4 +10,5 @@ def decompress(pdf):
 
 def squeezeInMemory(pdf):
     """squeezeToMemory(pdf) squeezes a pdf in memory. Squeezing is a lossless
-    compression method which works be rearrangement of a PDFs internal
+    compression method which works by rearrangement of a PDFs internal
+    structure."""

docsplits/pysplits/c07.tex

@@ -12,9 +12,9 @@ def getBookmarksJSON(pdf):
     """Get the bookmarks in JSON format."""
 
 def setBookmarksJSON(pdf, data):
-    """setBookmarksJSON(pdf, data) sets the bookmarks from JSON bookmark data."""
+    """Sets the bookmarks from JSON bookmark data."""
 
 def tableOfContents(pdf, font, fontsize, title, bookmark):
-    """tableOfContents(pdf, font, fontsize, title, bookmark) typesets a table
+    """Typesets a table of contents from existing bookmarks and prepends it to
-    of contents from existing bookmarks and prepends it to the document. If
+    the document. If bookmark is set, the table of contents gets its own
-    bookmark is set, the table of contents gets its own bookmark."""
+    bookmark."""

docsplits/pysplits/c09.tex

@@ -15,7 +15,8 @@ def stampExtended(pdf, pdf2, r, isover, scale_stamp_to_fit, pos,
      - isover True, pdf goes over pdf2, isover False, pdf goes under pdf2
      - scale_stamp_to_fit scales the stamp to fit the page
      - pos gives the position to put the stamp
-     - relative_to_cropbox: if True, pos is relative to crop box not media box"""
+     - relative_to_cropbox: if True, pos is relative to crop box not media box
+    """
 
 def combinePages(pdf, pdf2):
     """Combines the PDFs page-by-page, putting each page of pdf2 over each page
@@ -82,14 +83,15 @@ def addText(metrics, pdf, r, text, p, line_spacing, bates, font, size, red,
       * %%        The % character"""
 
 def addTextSimple(pdf, r, text, p, font, size):
-    """like addText, but with most parameters default
+    """Like addText, but with most parameters default
 
          * pdf = the document
          * r = the range
          * text = the text
          * p = the position
          * font = the font
-         * size = the font size"""
+         * size = the font size
+    NB: %filename cannot be used here. """
 
 def removeText(pdf, r):
     """Remove any text added by libcpdf from the given pages."""

docsplits/pysplits/c10.tex

@@ -1,20 +1,32 @@
 # CHAPTER 9. Multipage facilities
 
 def twoUp(pdf):
-    """Impose a document two up by retaining the existing page
+    """Impose a document two up by retaining the existing page size, scaling
-    size, scaling pages down."""
+    pages down."""
 
 def twoUpStack(pdf):
-    """Impose a document two up by doubling the page size,
+    """Impose a document two up by doubling the page size, to fit two pages on
-    to fit two pages on one."""
+    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,
+    """Impose a PDF. There are two modes: imposing x * y, or imposing to fit a
-    linewidth) imposes a PDF. There are two modes: imposing x * y, or imposing
+    page of size x * y. This is controlled by fit. Columns imposes by columns
-    to fit a page of size x * y. This is controlled by fit. Columns imposes by
+    rather than rows. rtl is right-to-left, btt bottom-to-top. Center is unused
-    columns rather than rows. rtl is right-to-left, btt bottom-to-top. Center
+    for now. Margin is the margin around the output, spacing the spacing
-    is unused for now. Margin is the margin around the output, spacing the
+    between imposed inputs."""
-    spacing between imposed inputs."""
+
+def chop(pdf, r, x, y, columns, rtl, btt):
+    """Chop each page in the range into x * y pieces. If columns is set, the
+    pieces go by columns instead of rows. If rtl is set, the pieces are taken
+    right-to-left. If btt is set, the pieces are taken from bottom to top. """
+
+def chopH(pdf, r, columns, y):
+    """Chop each page in the range horizontally at position y. If columns is
+    set, the pieces are arranged in reverse order. """
+
+def chopV(pdf, r, columns, x):
+    """Chop each page in the range vertically at position x. If columns is
+    set, the pieces are arranged in reverse order. """
 
 def padBefore(pdf, r):
     """Adds a blank page before each page in the given range."""
@@ -30,5 +42,5 @@ def padMultiple(pdf, n):
     length."""
 
 def padMultipleBefore(pdf, n):
-    """Adds pages at the beginning to pad the file to a
+    """Adds pages at the beginning to pad the file to a multiple of n pages in
-    multiple of n pages in length."""
+    length."""