From 25f5e28e56200f70b40c5dbc60da7fc0f88e586e Mon Sep 17 00:00:00 2001 From: Michael R Sweet Date: Thu, 24 Apr 2025 12:30:01 -0400 Subject: [PATCH] Update docos. --- doc/pdfio.3 | 70 ++++++++++++++++++++++++++++++------- doc/pdfio.html | 93 ++++++++++++++++++++++++++++++++------------------ 2 files changed, 117 insertions(+), 46 deletions(-) diff --git a/doc/pdfio.3 b/doc/pdfio.3 index c46e913..fbc6a96 100644 --- a/doc/pdfio.3 +++ b/doc/pdfio.3 @@ -1,4 +1,4 @@ -.TH pdfio 3 "pdf read/write library" "2025-04-12" "pdf read/write library" +.TH pdfio 3 "pdf read/write library" "2025-04-24" "pdf read/write library" .SH NAME pdfio \- pdf read/write library .SH Introduction @@ -325,7 +325,7 @@ where the five arguments to the function are the filename ("myinputfile.pdf"), a } .fi .PP -The error callback is called for both errors and warnings and accepts the pdfio_file_t pointer, a message string, and the callback pointer value, for example: +The error callback is called for both errors and warnings and accepts the pdfio_file_t pointer, a message string, and the callback pointer value. It returns true to continue processing the file or false to stop, for example: .nf bool @@ -335,12 +335,15 @@ The error callback is called for both errors and warnings and accepts the pdfio_ fprintf(stderr, "%s: %s\\n", pdfioFileGetName(pdf), message); - // Return false to treat warnings as errors - return (false); + // Return true for warning messages (continue) and false for errors (stop) + return (!strncmp(message, "WARNING:", 8)); } .fi .PP The default error callback (NULL) does the equivalent of the above. +.PP +Note: Many errors are unrecoverable, so PDFio ignores the return value from the error callback and always stops processing the PDF file. Warning messages start with the prefix "WARNING:" while errors have no prefix. + .PP Each PDF file contains one or more pages. The pdfioFileGetNumPages function returns the number of pages in the file while the pdfioFileGetPage function gets the specified page in the PDF file: .nf @@ -2477,7 +2480,7 @@ PDFIO_ENCRYPTION_RC4_128 .TP 5 PDFIO_ENCRYPTION_RC4_40 .br -40-bit RC4 encryption (PDF 1.3) +40-bit RC4 encryption (PDF 1.3, reading only) .SS pdfio_filter_e Compression/decompression filters for streams .TP 5 @@ -2947,6 +2950,8 @@ bool pdfioArrayRemove ( size_t n ); .fi +.PP + .SS pdfioContentClip Clip output to the current path. .PP @@ -3083,6 +3088,8 @@ bool pdfioContentPathEnd ( pdfio_stream_t *st ); .fi +.PP + .SS pdfioContentPathLineTo Add a straight line to the current path. .PP @@ -3423,6 +3430,8 @@ double pdfioContentTextMeasure ( This function measures the given text string "s" and returns its width based on "size". The text string must always use the UTF-8 (Unicode) encoding but any control characters (such as newlines) are ignored. + + .SS pdfioContentTextMoveLine Move to the next line and offset. .PP @@ -3451,6 +3460,8 @@ bool pdfioContentTextNewLine ( pdfio_stream_t *st ); .fi +.PP + .SS pdfioContentTextNewLineShow Move to the next line and show text. .PP @@ -3468,6 +3479,8 @@ This function moves to the next line and then shows some text with optional word and character spacing in a PDF content stream. The "unicode" argument specifies that the current font maps to full Unicode. The "s" argument specifies a UTF-8 encoded string. + + .SS pdfioContentTextNewLineShowf Show formatted text. .PP @@ -3486,6 +3499,8 @@ This function moves to the next line and shows some formatted text with optional word and character spacing in a PDF content stream. The "unicode" argument specifies that the current font maps to full Unicode. The "format" argument specifies a UTF-8 encoded \fBprintf\fR-style format string. + + .SS pdfioContentTextShow Show text. .PP @@ -3536,6 +3551,8 @@ bool pdfioDictClear ( const char *key ); .fi +.PP + .SS pdfioDictCopy Copy a dictionary to a PDF file. .PP @@ -3608,6 +3625,8 @@ const char * pdfioDictGetKey ( size_t n ); .fi +.PP + .SS pdfioDictGetName Get a key name value from a dictionary. .PP @@ -3625,6 +3644,8 @@ size_t pdfioDictGetNumPairs ( pdfio_dict_t *dict ); .fi +.PP + .SS pdfioDictGetNumber Get a key number value from a dictionary. .PP @@ -3697,6 +3718,8 @@ function "cb": The iteration continues as long as the callback returns \fBtrue\fR or all keys have been iterated. + + .SS pdfioDictSetArray Set a key array in a dictionary. .PP @@ -3852,8 +3875,9 @@ CropBox for pages in the PDF file - if \fBNULL\fR then a default "Universal" siz of 8.27x11in (the intersection of US Letter and ISO A4) is used. .PP The "error_cb" and "error_cbdata" arguments specify an error handler callback -and its data pointer - if \fBNULL\fR the default error handler is used that -writes error messages to \fBstderr\fR. +and its data pointer - if \fBNULL\fR then the default error handler is used that +writes error messages to \fBstderr\fR. The error handler callback should return +\fBtrue\fR to continue writing the PDF file or \fBfalse\fR to stop. .SS pdfioFileCreateArrayObj Create a new object in a PDF file containing an array. .PP @@ -4011,6 +4035,8 @@ pdfio_obj_t * pdfioFileCreateNameObj ( .PP This function creates a new object with a name value in a PDF file. You must call \fIpdfioObjClose\fR to write the object to the file. + + .SS pdfioFileCreateNumberObj Create a new object in a PDF file containing a number. .PP @@ -4023,6 +4049,8 @@ pdfio_obj_t * pdfioFileCreateNumberObj ( .PP This function creates a new object with a number value in a PDF file. You must call \fIpdfioObjClose\fR to write the object to the file. + + .SS pdfioFileCreateObj Create a new object in a PDF file. .PP @@ -4071,8 +4099,9 @@ CropBox for pages in the PDF file - if \fBNULL\fR then a default "Universal" siz of 8.27x11in (the intersection of US Letter and ISO A4) is used. .PP The "error_cb" and "error_cbdata" arguments specify an error handler callback -and its data pointer - if \fBNULL\fR the default error handler is used that -writes error messages to \fBstderr\fR. +and its data pointer - if \fBNULL\fR then the default error handler is used that +writes error messages to \fBstderr\fR. The error handler callback should return +\fBtrue\fR to continue writing the PDF file or \fBfalse\fR to stop. .PP .IP 5 \fINote\fR: Files created using this API are slightly larger than those @@ -4101,6 +4130,8 @@ pdfio_obj_t * pdfioFileCreateStringObj ( .PP This function creates a new object with a string value in a PDF file. You must call \fIpdfioObjClose\fR to write the object to the file. + + .SS pdfioFileCreateTemporary .PP @@ -4294,8 +4325,18 @@ cancel the open. If \fBNULL\fR is specified for the callback function and the PDF file requires a password, the open will always fail. .PP The "error_cb" and "error_cbdata" arguments specify an error handler callback -and its data pointer - if \fBNULL\fR the default error handler is used that -writes error messages to \fBstderr\fR. +and its data pointer - if \fBNULL\fR then the default error handler is used that +writes error messages to \fBstderr\fR. The error handler callback should return +\fBtrue\fR to continue reading the PDF file or \fBfalse\fR to stop. +.PP +.IP 5 +Note: Error messages starting with "WARNING:" are actually warning +.IP 5 +messages - the callback should normally return \fBtrue\fR to allow PDFio to +.IP 5 +try to resolve the issue. In addition, some errors are unrecoverable and +.IP 5 +ignore the return value of the error callback. .SS pdfioFileSetAuthor Set the author for a PDF file. .PP @@ -4474,6 +4515,8 @@ const char * pdfioObjGetName ( pdfio_obj_t *obj ); .fi +.PP + .SS pdfioObjGetNumber Get the object's number. .PP @@ -4677,8 +4720,9 @@ bool pdfioStreamPrintf ( .fi .PP This function writes a formatted string to a stream. In addition to the -standard \fBprintf\fR format characters, you can use "%N" to format a PDF name -value ("/Name") and "%S" to format a PDF string ("(String)") value. +standard \fBprintf\fR format characters, you can use "%H" to format a HTML/XML +string value, "%N" to format a PDF name value ("/Name"), and "%S" to format +a PDF string ("(String)") value. .SS pdfioStreamPutChar Write a single character to a stream. .PP diff --git a/doc/pdfio.html b/doc/pdfio.html index 904979f..56fa0a9 100644 --- a/doc/pdfio.html +++ b/doc/pdfio.html @@ -728,7 +728,7 @@ password_cb(void *data, con return ("Password42"); } -

The error callback is called for both errors and warnings and accepts the pdfio_file_t pointer, a message string, and the callback pointer value, for example:

+

The error callback is called for both errors and warnings and accepts the pdfio_file_t pointer, a message string, and the callback pointer value. It returns true to continue processing the file or false to stop, for example:

bool
 error_cb(pdfio_file_t *pdf, const char *message, void *data)
 {
@@ -736,11 +736,14 @@ error_cb(pdfio_file_t *pdf, const "%s: %s\n", pdfioFileGetName(pdf), message);
 
-  // Return false to treat warnings as errors
-  return (false);
+  // Return true for warning messages (continue) and false for errors (stop)
+  return (!strncmp(message, "WARNING:", 8));
 }

The default error callback (NULL) does the equivalent of the above.

+
+

Note: Many errors are unrecoverable, so PDFio ignores the return value from the error callback and always stops processing the PDF file. Warning messages start with the prefix "WARNING:" while errors have no prefix.

+

Each PDF file contains one or more pages. The pdfioFileGetNumPages function returns the number of pages in the file while the pdfioFileGetPage function gets the specified page in the PDF file:

pdfio_file_t *pdf;   // PDF file
 size_t       i;      // Looping var
@@ -2746,7 +2749,7 @@ size_t pdfioArrayGetSize(pdfio_array_t *a);

 
 
Return Value

 
Value type

-
pdfioArrayRemove

+
 PDFio v1.4 pdfioArrayRemove

 
Remove an array entry.

 

 bool pdfioArrayRemove(pdfio_array_t *a, size_t n);

@@ -2951,7 +2954,7 @@ using the pdfioPageDictAddImage
 
Return Value

 
true on success, false on failure

-
pdfioContentPathEnd

+
 PDFio v1.1 pdfioContentPathEnd

 
Clear the current path.

 

 bool pdfioContentPathEnd(pdfio_stream_t *st);

@@ -3441,7 +3444,7 @@ are 0, a solid line is drawn.

 
 
Return Value

 
true on success, false on failure

-
pdfioContentTextMeasure

+
 PDFio v1.2 pdfioContentTextMeasure

 
Measure a text string and return its width.

 

 double pdfioContentTextMeasure(pdfio_obj_t *font, const char *s, double size);

@@ -3459,7 +3462,9 @@ are 0, a solid line is drawn.

 
Discussion

 
This function measures the given text string "s" and returns its width based
 on "size". The text string must always use the UTF-8 (Unicode) encoding but
-any control characters (such as newlines) are ignored.

+any control characters (such as newlines) are ignored.
+
+

 
pdfioContentTextMoveLine

 
Move to the next line and offset.

 

@@ -3490,7 +3495,7 @@ any control characters (such as newlines) are ignored.

 
 
Return Value

 
true on success, false on failure

-
pdfioContentTextNewLine

+
 PDFio v1.2 pdfioContentTextNewLine

 
Move to the next line.

 

 bool pdfioContentTextNewLine(pdfio_stream_t *st);

@@ -3501,7 +3506,7 @@ any control characters (such as newlines) are ignored.

 
 
Return Value

 
true on success, false on failure

-
pdfioContentTextNewLineShow

+
 PDFio v1.2 pdfioContentTextNewLineShow

 
Move to the next line and show text.

 

 bool pdfioContentTextNewLineShow(pdfio_stream_t *st, double ws, double cs, bool unicode, const char *s);

@@ -3524,8 +3529,10 @@ any control characters (such as newlines) are ignored.

 
This function moves to the next line and then shows some text with optional
 word and character spacing in a PDF content stream. The "unicode" argument
 specifies that the current font maps to full Unicode.  The "s" argument
-specifies a UTF-8 encoded string.

-
pdfioContentTextNewLineShowf

+specifies a UTF-8 encoded string.
+
+

+
 PDFio v1.2 pdfioContentTextNewLineShowf

 
Show formatted text.

 

 bool pdfioContentTextNewLineShowf(pdfio_stream_t *st, double ws, double cs, bool unicode, const char *format, ...);

@@ -3550,7 +3557,9 @@ specifies a UTF-8 encoded string.

 
This function moves to the next line and shows some formatted text with
 optional word and character spacing in a PDF content stream. The "unicode"
 argument specifies that the current font maps to full Unicode.  The "format"
-argument specifies a UTF-8 encoded printf-style format string.

+argument specifies a UTF-8 encoded printf-style format string.
+
+

 
pdfioContentTextShow

 
Show text.

 

@@ -3613,7 +3622,7 @@ argument specifies an array of UTF-8 encoded strings.

 
This function shows some formatted text in a PDF content stream. The
 "unicode" argument specifies that the current font maps to full Unicode.
 The "format" argument specifies a UTF-8 encoded printf-style format string.

-
pdfioDictClear

+
 PDFio v1.4 pdfioDictClear

 
Remove a key/value pair from a dictionary.

 

 bool pdfioDictClear(pdfio_dict_t *dict, const char *key);

@@ -3717,7 +3726,7 @@ time_t pdfioDictGetDate(pdfio_dict_t *dict, 
 
Return Value

 
Value

-
pdfioDictGetKey

+
 PDFio v1.4 pdfioDictGetKey

 
Get the key for the specified pair.

 

 const char *pdfioDictGetKey(pdfio_dict_t *dict, size_t n);

@@ -3743,7 +3752,7 @@ time_t pdfioDictGetDate(pdfio_dict_t *dict, 
 
Return Value

 
Value

-
pdfioDictGetNumPairs

+
 PDFio v1.4 pdfioDictGetNumPairs

 
Get the number of key/value pairs in a dictionary.

 

 size_t pdfioDictGetNumPairs(pdfio_dict_t *dict);

@@ -3821,7 +3830,7 @@ size_t pdfioDictGetNumPairs(pdfio_dict_t *dict);

 
 
Return Value

 
Value type

-
pdfioDictIterateKeys

+
 PDFio v1.1 pdfioDictIterateKeys

 
Iterate the keys in a dictionary.

 

 void pdfioDictIterateKeys(pdfio_dict_t *dict, pdfio_dict_cb_t cb, void *cb_data);

@@ -3848,7 +3857,9 @@ my_dict_cb(pdfio_dict_t *dict, const char *key, void *cb_data)
The iteration continues as long as the callback returns true or all keys -have been iterated.

+have been iterated. + +

pdfioDictSetArray

Set a key array in a dictionary.

@@ -4076,8 +4087,9 @@ CropBox for pages in the PDF file - if NULL then a default "Un of 8.27x11in (the intersection of US Letter and ISO A4) is used.

The "error_cb" and "error_cbdata" arguments specify an error handler callback -and its data pointer - if NULL the default error handler is used that -writes error messages to stderr.

+and its data pointer - if NULL then the default error handler is used that +writes error messages to stderr. The error handler callback should return +true to continue writing the PDF file or false to stop.

pdfioFileCreateArrayObj

Create a new object in a PDF file containing an array.

@@ -4260,7 +4272,7 @@ image on the page.
Note: Currently PNG support is limited to grayscale, RGB, or indexed files without interlacing or alpha. Transparency (masking) based on color/index is supported. -

pdfioFileCreateNameObj

+

 PDFio v1.4 pdfioFileCreateNameObj

Create a new object in a PDF file containing a name.

pdfio_obj_t *pdfioFileCreateNameObj(pdfio_file_t *pdf, const char *name);

@@ -4275,8 +4287,10 @@ is supported.

New object

Discussion

This function creates a new object with a name value in a PDF file. -You must call pdfioObjClose to write the object to the file.

-

pdfioFileCreateNumberObj

+You must call pdfioObjClose to write the object to the file. + +

+

 PDFio v1.2 pdfioFileCreateNumberObj

Create a new object in a PDF file containing a number.

pdfio_obj_t *pdfioFileCreateNumberObj(pdfio_file_t *pdf, double number);

@@ -4291,7 +4305,9 @@ You must call pdfioObjClose to write t

New object

Discussion

This function creates a new object with a number value in a PDF file. -You must call pdfioObjClose to write the object to the file.

+You must call pdfioObjClose to write the object to the file. + +

pdfioFileCreateObj

Create a new object in a PDF file.

@@ -4352,8 +4368,9 @@ CropBox for pages in the PDF file - if NULL then a default "Un of 8.27x11in (the intersection of US Letter and ISO A4) is used.

The "error_cb" and "error_cbdata" arguments specify an error handler callback -and its data pointer - if NULL the default error handler is used that -writes error messages to stderr.
+and its data pointer - if NULL then the default error handler is used that +writes error messages to stderr. The error handler callback should return +true to continue writing the PDF file or false to stop.

Note: Files created using this API are slightly larger than those @@ -4372,7 +4389,7 @@ stored as indirect object references.

Return Value

Contents stream

-

pdfioFileCreateStringObj

+

 PDFio v1.2 pdfioFileCreateStringObj

Create a new object in a PDF file containing a string.

pdfio_obj_t *pdfioFileCreateStringObj(pdfio_file_t *pdf, const char *string);

@@ -4387,7 +4404,9 @@ stored as indirect object references.

New object

Discussion

This function creates a new object with a string value in a PDF file. -You must call pdfioObjClose to write the object to the file.

+You must call pdfioObjClose to write the object to the file. + +

pdfioFileCreateTemporary

@@ -4670,8 +4689,15 @@ cancel the open. If NULL is specified for the callback function an PDF file requires a password, the open will always fail.

The "error_cb" and "error_cbdata" arguments specify an error handler callback -and its data pointer - if NULL the default error handler is used that -writes error messages to stderr.

+and its data pointer - if NULL then the default error handler is used that +writes error messages to stderr. The error handler callback should return +true to continue reading the PDF file or false to stop.
+
+

+Note: Error messages starting with "WARNING:" are actually warning +messages - the callback should normally return true to allow PDFio to +try to resolve the issue. In addition, some errors are unrecoverable and +ignore the return value of the error callback.

pdfioFileSetAuthor

Set the author for a PDF file.

@@ -4892,7 +4918,7 @@ size_t pdfioObjGetLength(pdfio_obj_t *obj);

Return Value

Length in bytes or 0 for none

-

pdfioObjGetName

+

 PDFio v1.4 pdfioObjGetName

Get the name value associated with an object.

const char *pdfioObjGetName(pdfio_obj_t *obj);

@@ -5168,8 +5194,9 @@ ssize_t pdfioStreamPeek(pdfio_stream_t *st, true on success, false on failure

Discussion

This function writes a formatted string to a stream. In addition to the -standard printf format characters, you can use "%N" to format a PDF name -value ("/Name") and "%S" to format a PDF string ("(String)") value.

+standard printf format characters, you can use "%H" to format a HTML/XML +string value, "%N" to format a PDF name value ("/Name"), and "%S" to format +a PDF string ("(String)") value.

pdfioStreamPutChar

Write a single character to a stream.

@@ -5403,7 +5430,7 @@ typedef enum pdfio_valtype_e pdfio_valtype_t; PDFIO_ENCRYPTION_AES_128 128-bit AES encryption (PDF 1.6) PDFIO_ENCRYPTION_NONE No encryption PDFIO_ENCRYPTION_RC4_128 128-bit RC4 encryption (PDF 1.4) -PDFIO_ENCRYPTION_RC4_40 40-bit RC4 encryption (PDF 1.3) +PDFIO_ENCRYPTION_RC4_40 40-bit RC4 encryption (PDF 1.3, reading only)

pdfio_filter_e

Compression/decompression filters for streams