Updating html_manual/splits

This commit is contained in:
John Whitington 2022-01-26 12:41:19 +00:00
parent aa65ab647f
commit c067482046
22 changed files with 265 additions and 142 deletions

View File

@ -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. """

View File

@ -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."""

View File

@ -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
a given PDF (the PDF is supplied so that page ranges which reference pages
which do not exist are rejected)."""
"""Parse a page specification such as "1-3,8-end" to a range with reference
to a given PDF (the PDF is supplied so that page ranges which reference
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):

View File

@ -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."""

View File

@ -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

View File

@ -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."""

View File

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

View File

@ -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
number. """
"""Set the PDF to open, possibly with zoom-to-fit, at the given page number.
"""
def setMetadataFromFile(pdf, filename):
"""Set the XMP metadata of a document, given a file name."""

View File

@ -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
suppressed entirely."""
True, page content is parsed. If decompress_streams is True, streams are
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."""

View File

@ -1,41 +1,20 @@
# CHAPTER 17. Miscellaneous
# CHAPTER 17. Creating New PDFs
def draft(pdf, r, boxes):
"""Remove images on the given pages, replacing
them with crossed boxes if 'boxes' is True."""
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 removeAllText(pdf, r):
"""Remove all text from the given pages in a document."""
def blankDocumentPaper(papersize, pages):
"""Create a blank document with pages of the given paper size, and number
of pages. """
def blackText(pdf, r):
"""Blacken all text on the given pages."""
def textToPDF(w, h, font, fontsize, filename):
"""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):
"""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 removeClipping(pdf, r):
"""Remove all clipping from pages in the given range"""
def textToPDFPaper(papersize, font, fontsize, filename):
"""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
size."""

View File

@ -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"""

View File

@ -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,
* make_id, &length) writes it and returns the buffer. The buffer length is
* filled in &length.
* cpdf_toFileMemory (pdf, linearize, make_id, &length) writes a PDF file it
* and returns the buffer. The buffer length is filled in &length.
*/
void *cpdf_toMemory(int, int, int, int *);

View File

@ -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)
*/

View File

@ -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);

View File

@ -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);

View File

@ -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

View File

@ -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 *);

View File

@ -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);

View File

@ -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[]);

View File

@ -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);

View File

@ -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
* them with crossed boxes if 'boxes' is true
* cpdf_blankDocumentPaper(papersize, num_pages) makes a blank document given
* a page size and number of pages.
*/
void cpdf_draft(int, int, int);
int cpdf_blankDocumentPaper(enum cpdf_papersize, int);
/*
* cpdf_removeAllText(pdf, range) removes all text from the given pages in a
* given document.
*/
void cpdf_removeAllText(int, int);
/* cpdf_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. */
int cpdf_textToPDF(double, double, int, double, const char[]);
/* 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_removeClipping(pdf, range) removes all clipping from pages in the
* given range.
*/
void cpdf_removeClipping(int, int);
/* cpdf_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 size. */
int cpdf_textToPDFPaper(int, int, double, const char[]);

View File

@ -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. */