From ccf3a90c9764d7dca93e1cc06f2997371cba323a Mon Sep 17 00:00:00 2001 From: Michael R Sweet Date: Tue, 26 Aug 2025 15:18:36 -0400 Subject: [PATCH] Document how warning messages work (Issue #118) --- CHANGES.md | 1 + doc/pdfio.3 | 60 ++++++++++++++++++++++++++++++++++++++++++++------ doc/pdfio.html | 59 ++++++++++++++++++++++++++++++++++++++++++------- pdfio-file.c | 54 ++++++++++++++++++++++++++++++++++++++++----- 4 files changed, 153 insertions(+), 21 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index c94b516..44aa183 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -12,6 +12,7 @@ v1.6.0 - YYYY-MM-DD profile (Issue #104) - Added `pdfioFileAddOutputIntent` function to adding output intent information to a PDF file (Issue #104) +- Added explicit support for warning messages (Issue #118) - Added `pdfioFileCreateFontObjFromData` function for embedding fonts in memory (Issue #120) - Added `pdfioFileGetLanguage` and `pdfioFileSetLanguage` functions for getting diff --git a/doc/pdfio.3 b/doc/pdfio.3 index 9f64cd0..9e158e3 100644 --- a/doc/pdfio.3 +++ b/doc/pdfio.3 @@ -1,4 +1,4 @@ -.TH pdfio 3 "pdf read/write library" "2025-04-23" "pdf read/write library" +.TH pdfio 3 "pdf read/write library" "2025-08-26" "pdf read/write library" .SH NAME pdfio \- pdf read/write library .SH Introduction @@ -3914,8 +3914,24 @@ 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 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. +writes error and warning messages to \fBstderr\fR. The error handler callback +should return \fBtrue\fR to continue writing the PDF file or \fBfalse\fR to stop. +For example: +.PP +.nf + bool + my_error_cb(pdfio_file_t *pdf, const char *message, void *data) + { + (void)data; /* Not using data pointer in this callback */ + + fprintf(stderr, "%s: %sn", pdfioFileGetName(pdf), message); + + /* Return true to continue on warning messages, false otherwise... */ + return (!strncmp(message, "WARNING:", 8)); + } + +.fi + .SS pdfioFileCreateArrayObj Create a new object in a PDF file containing an array. .PP @@ -4157,9 +4173,24 @@ 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 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. +writes error and warning messages to \fBstderr\fR. The error handler callback +should return \fBtrue\fR to continue writing the PDF file or \fBfalse\fR to stop. +For example: .PP +.nf + bool + my_error_cb(pdfio_file_t *pdf, const char *message, void *data) + { + (void)data; /* Not using data pointer in this callback */ + + fprintf(stderr, "%s: %sn", pdfioFileGetName(pdf), message); + + /* Return true to continue on warning messages, false otherwise... */ + return (!strncmp(message, "WARNING:", 8)); + } + +.fi + .IP 5 \fINote\fR: Files created using this API are slightly larger than those .IP 5 @@ -4398,9 +4429,24 @@ 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 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. +writes error and warning messages to \fBstderr\fR. The error handler callback +should return \fBtrue\fR to continue reading the PDF file or \fBfalse\fR to stop. +For example: .PP +.nf + bool + my_error_cb(pdfio_file_t *pdf, const char *message, void *data) + { + (void)data; /* Not using data pointer in this callback */ + + fprintf(stderr, "%s: %sn", pdfioFileGetName(pdf), message); + + /* Return true to continue on warning messages, false otherwise... */ + return (!strncmp(message, "WARNING:", 8)); + } + +.fi + .IP 5 Note: Error messages starting with "WARNING:" are actually warning .IP 5 diff --git a/doc/pdfio.html b/doc/pdfio.html index 3285b28..8feec04 100644 --- a/doc/pdfio.html +++ b/doc/pdfio.html @@ -4133,8 +4133,23 @@ 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 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.

+writes error and warning messages to stderr. The error handler callback +should return true to continue writing the PDF file or false to stop. +For example: + +
+bool
+my_error_cb(pdfio_file_t *pdf, const char *message, void *data)
+{
+  (void)data; /* Not using data pointer in this callback */
+
+  fprintf(stderr, "%s: %sn", pdfioFileGetName(pdf), message);
+
+  /* Return true to continue on warning messages, false otherwise... */
+  return (!strncmp(message, "WARNING:", 8));
+}
+
+

pdfioFileCreateArrayObj

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

@@ -4439,9 +4454,23 @@ 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 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.
-
+writes error and warning messages to stderr. The error handler callback +should return true to continue writing the PDF file or false to stop. +For example: + +

+bool
+my_error_cb(pdfio_file_t *pdf, const char *message, void *data)
+{
+  (void)data; /* Not using data pointer in this callback */
+
+  fprintf(stderr, "%s: %sn", pdfioFileGetName(pdf), message);
+
+  /* Return true to continue on warning messages, false otherwise... */
+  return (!strncmp(message, "WARNING:", 8));
+}
+
+

Note: Files created using this API are slightly larger than those created using the pdfioFileCreate function since stream lengths are @@ -4778,9 +4807,23 @@ 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 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.
-
+writes error and warning messages to stderr. The error handler callback +should return true to continue reading the PDF file or false to stop. +For example: + +
+bool
+my_error_cb(pdfio_file_t *pdf, const char *message, void *data)
+{
+  (void)data; /* Not using data pointer in this callback */
+
+  fprintf(stderr, "%s: %sn", pdfioFileGetName(pdf), message);
+
+  /* Return true to continue on warning messages, false otherwise... */
+  return (!strncmp(message, "WARNING:", 8));
+}
+
+

Note: Error messages starting with "WARNING:" are actually warning messages - the callback should normally return true to allow PDFio to diff --git a/pdfio-file.c b/pdfio-file.c index d4a5b36..0e52124 100644 --- a/pdfio-file.c +++ b/pdfio-file.c @@ -190,8 +190,22 @@ pdfioFileClose(pdfio_file_t *pdf) // I - PDF file // // The "error_cb" and "error_cbdata" arguments specify an error handler callback // 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. +// writes error and warning messages to `stderr`. The error handler callback +// should return `true` to continue writing the PDF file or `false` to stop. +// For example: +// +// ``` +// bool +// my_error_cb(pdfio_file_t *pdf, const char *message, void *data) +// { +// (void)data; /* Not using data pointer in this callback */ +// +// fprintf(stderr, "%s: %s\n", pdfioFileGetName(pdf), message); +// +// /* Return true to continue on warning messages, false otherwise... */ +// return (!strncmp(message, "WARNING:", 8)); +// } +// ``` // pdfio_file_t * // O - PDF file or `NULL` on error @@ -429,8 +443,22 @@ _pdfioFileCreateObj( // // The "error_cb" and "error_cbdata" arguments specify an error handler callback // 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. +// writes error and warning messages to `stderr`. The error handler callback +// should return `true` to continue writing the PDF file or `false` to stop. +// For example: +// +// ``` +// bool +// my_error_cb(pdfio_file_t *pdf, const char *message, void *data) +// { +// (void)data; /* Not using data pointer in this callback */ +// +// fprintf(stderr, "%s: %s\n", pdfioFileGetName(pdf), message); +// +// /* Return true to continue on warning messages, false otherwise... */ +// return (!strncmp(message, "WARNING:", 8)); +// } +// ``` // // > *Note*: Files created using this API are slightly larger than those // > created using the @link pdfioFileCreate@ function since stream lengths are @@ -1023,8 +1051,22 @@ pdfioFileGetVersion( // // The "error_cb" and "error_cbdata" arguments specify an error handler callback // 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. +// writes error and warning messages to `stderr`. The error handler callback +// should return `true` to continue reading the PDF file or `false` to stop. +// For example: +// +// ``` +// bool +// my_error_cb(pdfio_file_t *pdf, const char *message, void *data) +// { +// (void)data; /* Not using data pointer in this callback */ +// +// fprintf(stderr, "%s: %s\n", pdfioFileGetName(pdf), message); +// +// /* Return true to continue on warning messages, false otherwise... */ +// return (!strncmp(message, "WARNING:", 8)); +// } +// ``` // // > Note: Error messages starting with "WARNING:" are actually warning // > messages - the callback should normally return `true` to allow PDFio to