Fix docos for pdfioFileOpen.

doc/pdfio.3

@@ -46,6 +46,10 @@ A C99 compiler such as Clang, GCC, or MS Visual C
 .PP
 A POSIX\-compliant make program
 
+.IP \(bu 5
+.PP
+A POSIX\-compliant sh program
+
 .IP \(bu 5
 .PP
 ZLIB (https://www.zlib.net) 1.0 or higher
@@ -55,10 +59,11 @@ ZLIB (https://www.zlib.net) 1.0 or higher
 IDE files for Xcode (macOS/iOS) and Visual Studio (Windows) are also provided.
 .SS Installing pdfio
 .PP
-PDFio comes with a portable makefile that will work on any POSIX\-compliant system with ZLIB installed. To make it, run:
+PDFio comes with a configure script that creates a portable makefile that will work on any POSIX\-compliant system with ZLIB installed. To make it, run:
 .nf
 
-    make all
+    \./configure
+    make
 .fi
 .PP
 To test it, run:
@@ -70,78 +75,28 @@ To test it, run:
 To install it, run:
 .nf
 
-    make install
+    sudo make install
 .fi
 .PP
 If you want a shared library, run:
 .nf
 
-    make all\-shared
-    make install\-shared
+    \./configure \-\-enable\-shared
+    make
+    sudo make install
 .fi
 .PP
-The default installation location is "/usr/local". Pass the prefix variable to make to install it to another location:
+The default installation location is "/usr/local". Pass the \-\-prefix option to make to install it to another location:
 .nf
 
-    make install prefix=/some/other/directory
+    \./configure \-\-prefix=/some/other/directory
 .fi
 .PP
-The makefile installs the pdfio header to "${prefix}/include", the library to "${prefix}/lib", the pkg\-config file to "${prefix}/lib/pkgconfig", the man page to "${prefix}/share/man/man3", and the documentation to "${prefix}/share/doc/pdfio".
-.PP
-The makefile supports the following variables that can be specified in the make command or as environment variables:
-.IP \(bu 5
-.PP
-AR: the library archiver (default "ar")
-
-.IP \(bu 5
-.PP
-ARFLAGS: options for the library archiver (default "cr")
-
-.IP \(bu 5
-.PP
-CC: the C compiler (default "cc")
-
-.IP \(bu 5
-.PP
-CFLAGS: options for the C compiler (default "")
-
-.IP \(bu 5
-.PP
-CODESIGN_IDENTITY: the identity to use when code signing the shared library on macOS (default "Developer ID")
-
-.IP \(bu 5
-.PP
-COMMONFLAGS: options for the C compiler and linker (typically architecture and optimization options, default is "\-Os \-g")
-
-.IP \(bu 5
-.PP
-CPPFLAGS: options for the C preprocessor (default "")
-
-.IP \(bu 5
-.PP
-DESTDIR and DSTROOT: specifies a root directory when installing (default is "", specify only one)
-
-.IP \(bu 5
-.PP
-DSOFLAGS: options for the C compiler when linking the shared library (default "")
-
-.IP \(bu 5
-.PP
-LDFLAGS: options for the C compiler when linking the test programs (default "")
-
-.IP \(bu 5
-.PP
-LIBS: library options when linking the test programs (default "\-lz")
-
-.IP \(bu 5
-.PP
-RANLIB: program that generates a table\-of\-contents in a library (default "ranlib")
-
-.IP \(bu 5
-.PP
-prefix: specifies the installation directory (default "/usr/local")
-
+Other configure options can be found using the \-\-help option:
+.nf
 
+    \./configure \-\-help
+.fi
 .SS Visual Studio Project
 .PP
 The Visual Studio solution ("pdfio.sln") is provided for Windows developers and generates both a static library and DLL.
@@ -152,12 +107,6 @@ There is also an Xcode project ("pdfio.xcodeproj") you can use on macOS which ge
 
     sudo xcodebuild install
 .fi
-.PP
-You can reproduce this with the makefile using:
-.nf
-
-    sudo make macos install
-.fi
 .SS Detecting PDFio
 .PP
 PDFio can be detected using the pkg\-config command, for example:
@@ -218,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

doc/pdfio.html

@@ -509,66 +509,40 @@ span.string {
 </li>
 <li><p>A POSIX-compliant <code>make</code> program</p>
 </li>
+<li><p>A POSIX-compliant <code>sh</code> program</p>
+</li>
 <li><p>ZLIB (<a href="https://www.zlib.net">https://www.zlib.net</a>) 1.0 or higher</p>
 </li>
 </ul>
 <p>IDE files for Xcode (macOS/iOS) and Visual Studio (Windows) are also provided.</p>
 <h3 class="title" id="installing-pdfio">Installing pdfio</h3>
-<p>PDFio comes with a portable makefile that will work on any POSIX-compliant system with ZLIB installed. To make it, run:</p>
-<pre><code>make all
+<p>PDFio comes with a configure script that creates a portable makefile that will work on any POSIX-compliant system with ZLIB installed. To make it, run:</p>
+<pre><code>./configure
+make
 </code></pre>
 <p>To test it, run:</p>
 <pre><code>make test
 </code></pre>
 <p>To install it, run:</p>
-<pre><code>make install
+<pre><code>sudo make install
 </code></pre>
 <p>If you want a shared library, run:</p>
-<pre><code>make all-shared
-make install-shared
+<pre><code>./configure --enable-shared
+make
+sudo make install
 </code></pre>
-<p>The default installation location is &quot;/usr/local&quot;. Pass the <code>prefix</code> variable to make to install it to another location:</p>
-<pre><code>make install prefix=/some/other/directory
+<p>The default installation location is &quot;/usr/local&quot;. Pass the <code>--prefix</code> option to make to install it to another location:</p>
+<pre><code>./configure --prefix=/some/other/directory
+</code></pre>
+<p>Other configure options can be found using the <code>--help</code> option:</p>
+<pre><code>./configure --help
 </code></pre>
-<p>The makefile installs the pdfio header to &quot;${prefix}/include&quot;, the library to &quot;${prefix}/lib&quot;, the <code>pkg-config</code> file to &quot;${prefix}/lib/pkgconfig&quot;, the man page to &quot;${prefix}/share/man/man3&quot;, and the documentation to &quot;${prefix}/share/doc/pdfio&quot;.</p>
-<p>The makefile supports the following variables that can be specified in the make command or as environment variables:</p>
-<ul>
-<li><p><code>AR</code>: the library archiver (default &quot;ar&quot;)</p>
-</li>
-<li><p><code>ARFLAGS</code>: options for the library archiver (default &quot;cr&quot;)</p>
-</li>
-<li><p><code>CC</code>: the C compiler (default &quot;cc&quot;)</p>
-</li>
-<li><p><code>CFLAGS</code>: options for the C compiler (default &quot;&quot;)</p>
-</li>
-<li><p><code>CODESIGN_IDENTITY</code>: the identity to use when code signing the shared library on macOS (default &quot;Developer ID&quot;)</p>
-</li>
-<li><p><code>COMMONFLAGS</code>: options for the C compiler and linker (typically architecture and optimization options, default is &quot;-Os -g&quot;)</p>
-</li>
-<li><p><code>CPPFLAGS</code>: options for the C preprocessor (default &quot;&quot;)</p>
-</li>
-<li><p><code>DESTDIR</code> and <code>DSTROOT</code>: specifies a root directory when installing (default is &quot;&quot;, specify only one)</p>
-</li>
-<li><p><code>DSOFLAGS</code>: options for the C compiler when linking the shared library (default &quot;&quot;)</p>
-</li>
-<li><p><code>LDFLAGS</code>: options for the C compiler when linking the test programs (default &quot;&quot;)</p>
-</li>
-<li><p><code>LIBS</code>: library options when linking the test programs (default &quot;-lz&quot;)</p>
-</li>
-<li><p><code>RANLIB</code>: program that generates a table-of-contents in a library (default &quot;ranlib&quot;)</p>
-</li>
-<li><p><code>prefix</code>: specifies the installation directory (default &quot;/usr/local&quot;)</p>
-</li>
-</ul>
 <h3 class="title" id="visual-studio-project">Visual Studio Project</h3>
 <p>The Visual Studio solution (&quot;pdfio.sln&quot;) is provided for Windows developers and generates both a static library and DLL.</p>
 <h3 class="title" id="xcode-project">Xcode Project</h3>
 <p>There is also an Xcode project (&quot;pdfio.xcodeproj&quot;) you can use on macOS which generates a static library that will be installed under &quot;/usr/local&quot; with:</p>
 <pre><code>sudo xcodebuild install
 </code></pre>
-<p>You can reproduce this with the makefile using:</p>
-<pre><code>sudo make macos install
-</code></pre>
 <h3 class="title" id="detecting-pdfio">Detecting PDFio</h3>
 <p>PDFio can be detected using the <code>pkg-config</code> command, for example:</p>
 <pre><code>if pkg-config --exists pdfio; then
@@ -603,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)
 {

doc/pdfio.md

@@ -27,6 +27,7 @@ PDFio requires the following to build the software:
 
 - A C99 compiler such as Clang, GCC, or MS Visual C
 - A POSIX-compliant `make` program
+- A POSIX-compliant `sh` program
 - ZLIB (<https://www.zlib.net>) 1.0 or higher
 
 IDE files for Xcode (macOS/iOS) and Visual Studio (Windows) are also provided.
@@ -35,10 +36,11 @@ IDE files for Xcode (macOS/iOS) and Visual Studio (Windows) are also provided.
 Installing pdfio
 ----------------
 
-PDFio comes with a portable makefile that will work on any POSIX-compliant
-system with ZLIB installed.  To make it, run:
+PDFio comes with a configure script that creates a portable makefile that will
+work on any POSIX-compliant system with ZLIB installed.  To make it, run:
 
-    make all
+    ./configure
+    make
 
 To test it, run:
 
@@ -46,45 +48,22 @@ To test it, run:
 
 To install it, run:
 
-    make install
+    sudo make install
 
 If you want a shared library, run:
 
-    make all-shared
-    make install-shared
+    ./configure --enable-shared
+    make
+    sudo make install
 
-The default installation location is "/usr/local".  Pass the `prefix` variable
+The default installation location is "/usr/local".  Pass the `--prefix` option
 to make to install it to another location:
 
-    make install prefix=/some/other/directory
+    ./configure --prefix=/some/other/directory
 
-The makefile installs the pdfio header to "${prefix}/include", the library to
-"${prefix}/lib", the `pkg-config` file to "${prefix}/lib/pkgconfig", the man
-page to "${prefix}/share/man/man3", and the documentation to
-"${prefix}/share/doc/pdfio".
+Other configure options can be found using the `--help` option:
 
-The makefile supports the following variables that can be specified in the make
-command or as environment variables:
-
-- `AR`: the library archiver (default "ar")
-- `ARFLAGS`: options for the library archiver (default "cr")
-- `CC`: the C compiler (default "cc")
-- `CFLAGS`: options for the C compiler (default "")
-- `CODESIGN_IDENTITY`: the identity to use when code signing the shared library
-  on macOS (default "Developer ID")
-- `COMMONFLAGS`: options for the C compiler and linker (typically architecture
-  and optimization options, default is "-Os -g")
-- `CPPFLAGS`: options for the C preprocessor (default "")
-- `DESTDIR` and `DSTROOT`: specifies a root directory when installing
-  (default is "", specify only one)
-- `DSOFLAGS`: options for the C compiler when linking the shared library
-  (default "")
-- `LDFLAGS`: options for the C compiler when linking the test programs
-  (default "")
-- `LIBS`: library options when linking the test programs (default "-lz")
-- `RANLIB`: program that generates a table-of-contents in a library
-  (default "ranlib")
-- `prefix`: specifies the installation directory (default "/usr/local")
+    ./configure --help
 
 
 Visual Studio Project
@@ -102,10 +81,6 @@ generates a static library that will be installed under "/usr/local" with:
 
     sudo xcodebuild install
 
-You can reproduce this with the makefile using:
-
-    sudo make macos install
-
 
 Detecting PDFio
 ---------------
@@ -163,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