From 6906a9a70813af51851b07b15f7ebbd20da6121b Mon Sep 17 00:00:00 2001
From: Michael R Sweet <msweet@msweet.org>
Date: Tue, 5 Dec 2023 19:22:47 -0500
Subject: [PATCH] Fix docos for pdfioFileOpen.

---
 doc/pdfio.3    | 19 +++++++++++++++++--
 doc/pdfio.html | 16 ++++++++++++++--
 doc/pdfio.md   | 29 +++++++++++++++++++++++------
 3 files changed, 54 insertions(+), 10 deletions(-)

diff --git a/doc/pdfio.3 b/doc/pdfio.3
index f69e2bd..c8dc712 100644
--- a/doc/pdfio.3
+++ b/doc/pdfio.3
@@ -167,10 +167,25 @@ pdfio_stream_t: An object stream
 You open an existing PDF file using the pdfioFileOpen function:
 .nf
 
-    pdfio_file_t *pdf = pdfioFileOpen("myinputfile.pdf", error_cb, error_data);
+    pdfio_file_t *pdf = pdfioFileOpen("myinputfile.pdf", password_cb, password_data,
+                                      error_cb, error_data);
 .fi
 .PP
-where the three arguments to the function are the filename ("myinputfile.pdf"), an optional error callback function (error_cb), and an optional pointer value for the error callback function (error_data). 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:
+where the five arguments to the function are the filename ("myinputfile.pdf"), an optional password callback function (password_cb) and data pointer value (password_data), and an optional error callback function (error_cb) and data pointer value (error_data). The password callback is called for encrypted PDF files that are not using the default password, for example:
+.nf
+
+    const char *
+    password_cb(void *data, const char *filename)
+    {
+      (void)data;     // This callback doesn't use the data pointer
+      (void)filename; // This callback doesn't use the filename
+    
+      // Return a password string for the file...
+      return ("Password42");
+    }
+.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:
 .nf
 
     bool
diff --git a/doc/pdfio.html b/doc/pdfio.html
index 2e2017a..752aa01 100644
--- a/doc/pdfio.html
+++ b/doc/pdfio.html
@@ -577,9 +577,21 @@ LIBS    +=      `pkg-config --libs pdfio`
 </ul>
 <h3 class="title" id="reading-pdf-files">Reading PDF Files</h3>
 <p>You open an existing PDF file using the <a href="#pdfioFileOpen"><code>pdfioFileOpen</code></a> function:</p>
-<pre><code class="language-c">pdfio_file_t *pdf = pdfioFileOpen(<span class="string">&quot;myinputfile.pdf&quot;</span>, error_cb, error_data);
+<pre><code class="language-c">pdfio_file_t *pdf = pdfioFileOpen(<span class="string">&quot;myinputfile.pdf&quot;</span>, password_cb, password_data,
+                                  error_cb, error_data);
 </code></pre>
-<p>where the three arguments to the function are the filename (&quot;myinputfile.pdf&quot;), an optional error callback function (<code>error_cb</code>), and an optional pointer value for the error callback function (<code>error_data</code>). The error callback is called for both errors and warnings and accepts the <code>pdfio_file_t</code> pointer, a message string, and the callback pointer value, for example:</p>
+<p>where the five arguments to the function are the filename (&quot;myinputfile.pdf&quot;), an optional password callback function (<code>password_cb</code>) and data pointer value (<code>password_data</code>), and an optional error callback function (<code>error_cb</code>) and data pointer value (<code>error_data</code>). The password callback is called for encrypted PDF files that are not using the default password, for example:</p>
+<pre><code class="language-c"><span class="reserved">const</span> <span class="reserved">char</span> *
+password_cb(<span class="reserved">void</span> *data, <span class="reserved">const</span> <span class="reserved">char</span> *filename)
+{
+  (<span class="reserved">void</span>)data;     <span class="comment">// This callback doesn't use the data pointer</span>
+  (<span class="reserved">void</span>)filename; <span class="comment">// This callback doesn't use the filename</span>
+
+  <span class="comment">// Return a password string for the file...</span>
+  <span class="reserved">return</span> (<span class="string">&quot;Password42&quot;</span>);
+}
+</code></pre>
+<p>The error callback is called for both errors and warnings and accepts the <code>pdfio_file_t</code> pointer, a message string, and the callback pointer value, for example:</p>
 <pre><code class="language-c"><span class="reserved">bool</span>
 error_cb(pdfio_file_t *pdf, <span class="reserved">const</span> <span class="reserved">char</span> *message, <span class="reserved">void</span> *data)
 {
diff --git a/doc/pdfio.md b/doc/pdfio.md
index 2e543f7..7c6e657 100644
--- a/doc/pdfio.md
+++ b/doc/pdfio.md
@@ -138,15 +138,32 @@ Reading PDF Files
 You open an existing PDF file using the [`pdfioFileOpen`](@@) function:
 
 ```c
-pdfio_file_t *pdf = pdfioFileOpen("myinputfile.pdf", error_cb, error_data);
+pdfio_file_t *pdf = pdfioFileOpen("myinputfile.pdf", password_cb, password_data,
+                                  error_cb, error_data);
 
 ```
 
-where the three arguments to the function are the filename ("myinputfile.pdf"),
-an optional error callback function (`error_cb`), and an optional pointer value
-for the error callback function (`error_data`).  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:
+where the five arguments to the function are the filename ("myinputfile.pdf"),
+an optional password callback function (`password_cb`) and data pointer value
+(`password_data`), and an optional error callback function (`error_cb`) and data
+pointer value (`error_data`).  The password callback is called for encrypted PDF
+files that are not using the default password, for example:
+
+```c
+const char *
+password_cb(void *data, const char *filename)
+{
+  (void)data;     // This callback doesn't use the data pointer
+  (void)filename; // This callback doesn't use the filename
+
+  // Return a password string for the file...
+  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:
 
 ```c
 bool