Improve Unicode filename testing

Remove dependency on the behavior of perl for reliable creation of
Unicode file names on Windows.

1 files changed, 25 insertions, 0 deletions

diff --git a/manual/qpdf-manual.xml b/manual/qpdf-manual.xml
index dac5f00d..1df6e788 100644
--- a/manual/qpdf-manual.xml
+++ b/manual/qpdf-manual.xml
@@ -2612,6 +2612,31 @@ outfile.pdf</option>
     </varlistentry>
    </variablelist>
   </sect1>
+  <sect1 id="ref.unicode-files">
+   <title>A Note About Unicode File Names</title>
+   <para>
+    When strings are passed to qpdf library routines either as
+    <literal>char*</literal> or as <literal>std::string</literal>,
+    they are treated as byte arrays except where otherwise noted. When
+    Unicode is desired, qpdf wants UTF-8 unless otherwise noted in
+    comments in header files. In modern UNIX/Linux environments, this
+    generally does the right thing. In Windows, it's a bit more
+    complicated. Starting in qpdf 8.4.0, passwords that contain
+    Unicode characters are handled much better, and starting in qpdf
+    8.4.1, the library attempts to properly handle Unicode characters
+    in filenames. In particular, in Windows, if a UTF-8 encoded string
+    is used as a filename in either <classname>QPDF</classname> or
+    <classname>QPDFWriter</classname>, it is internally converted to
+    <literal>wchar_t*</literal>, and Unicode-aware Windows APIs are
+    used. As such, qpdf will generally operate properly on files with
+    non-ASCII characters in their names as long as the filenames are
+    UTF-8 encoded for passing into the qpdf library API, but there are
+    still some rough edges, such as the encoding of the filenames in
+    error messages our CLI output messages. Patches or bug reports are
+    welcome for any continuing issues with Unicode file names in
+    Windows.
+   </para>
+  </sect1>
  </chapter>
  <chapter id="ref.json">
   <title>QPDF JSON</title>