Document how warning messages work (Issue #118)

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

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
+writes error and warning messages to \fBstderr\fR.  The error handler callback
-\fBtrue\fR to continue writing the PDF file or \fBfalse\fR to stop.
+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
+writes error and warning messages to \fBstderr\fR.  The error handler callback
-\fBtrue\fR to continue writing the PDF file or \fBfalse\fR to stop.
+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
+writes error and warning messages to \fBstderr\fR.  The error handler callback
-\fBtrue\fR to continue reading the PDF file or \fBfalse\fR to stop.
+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

doc/pdfio.html

@@ -4133,8 +4133,23 @@ of 8.27x11in (the intersection of US Letter and ISO A4) is used.<br>
 <br>
 The &quot;error_cb&quot; and &quot;error_cbdata&quot; arguments specify an error handler callback
 and its data pointer - if <code>NULL</code> then the default error handler is used that
-writes error messages to <code>stderr</code>.  The error handler callback should return
+writes error and warning messages to <code>stderr</code>.  The error handler callback
-<code>true</code> to continue writing the PDF file or <code>false</code> to stop.</p>
+should return <code>true</code> to continue writing the PDF file or <code>false</code> to stop.
+For example:
+
+<pre>
+bool
+my_error_cb(pdfio_file_t *pdf, const char *message, void *data)
+{
+  (void)data; /* Not using data pointer in this callback */
+
+  fprintf(stderr, &quot;%s: %sn&quot;, pdfioFileGetName(pdf), message);
+
+  /* Return true to continue on warning messages, false otherwise... */
+  return (!strncmp(message, &quot;WARNING:&quot;, 8));
+}
+</pre>
+</p>
 <h3 class="function"><a id="pdfioFileCreateArrayObj">pdfioFileCreateArrayObj</a></h3>
 <p class="description">Create a new object in a PDF file containing an array.</p>
 <p class="code">
@@ -4439,9 +4454,23 @@ of 8.27x11in (the intersection of US Letter and ISO A4) is used.<br>
 <br>
 The &quot;error_cb&quot; and &quot;error_cbdata&quot; arguments specify an error handler callback
 and its data pointer - if <code>NULL</code> then the default error handler is used that
-writes error messages to <code>stderr</code>.  The error handler callback should return
+writes error and warning messages to <code>stderr</code>.  The error handler callback
-<code>true</code> to continue writing the PDF file or <code>false</code> to stop.<br>
+should return <code>true</code> to continue writing the PDF file or <code>false</code> to stop.
-<br>
+For example:
+
+<pre>
+bool
+my_error_cb(pdfio_file_t *pdf, const char *message, void *data)
+{
+  (void)data; /* Not using data pointer in this callback */
+
+  fprintf(stderr, &quot;%s: %sn&quot;, pdfioFileGetName(pdf), message);
+
+  /* Return true to continue on warning messages, false otherwise... */
+  return (!strncmp(message, &quot;WARNING:&quot;, 8));
+}
+</pre>
+
 </p><blockquote>
 <em>Note</em>: Files created using this API are slightly larger than those
 created using the <a href="#pdfioFileCreate"><code>pdfioFileCreate</code></a> function since stream lengths are
@@ -4778,9 +4807,23 @@ PDF file requires a password, the open will always fail.<br>
 <br>
 The &quot;error_cb&quot; and &quot;error_cbdata&quot; arguments specify an error handler callback
 and its data pointer - if <code>NULL</code> then the default error handler is used that
-writes error messages to <code>stderr</code>.  The error handler callback should return
+writes error and warning messages to <code>stderr</code>.  The error handler callback
-<code>true</code> to continue reading the PDF file or <code>false</code> to stop.<br>
+should return <code>true</code> to continue reading the PDF file or <code>false</code> to stop.
-<br>
+For example:
+
+<pre>
+bool
+my_error_cb(pdfio_file_t *pdf, const char *message, void *data)
+{
+  (void)data; /* Not using data pointer in this callback */
+
+  fprintf(stderr, &quot;%s: %sn&quot;, pdfioFileGetName(pdf), message);
+
+  /* Return true to continue on warning messages, false otherwise... */
+  return (!strncmp(message, &quot;WARNING:&quot;, 8));
+}
+</pre>
+
 </p><blockquote>
 Note: Error messages starting with &quot;WARNING:&quot; are actually warning
 messages - the callback should normally return <code>true</code> to allow PDFio to

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
+// writes error and warning messages to `stderr`.  The error handler callback
-// `true` to continue writing the PDF file or `false` to stop.
+// 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
+// writes error and warning messages to `stderr`.  The error handler callback
-// `true` to continue writing the PDF file or `false` to stop.
+// 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
+// writes error and warning messages to `stderr`.  The error handler callback
-// `true` to continue reading the PDF file or `false` to stop.
+// 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