Rename README files before converting to markdown

1 files changed, 239 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 00000000..5c15fa3d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,239 @@
+This is the QPDF package.  Information about it can be found at
+http://qpdf.sourceforge.net.  The source code repository is hosted
+at github: https://github.com/qpdf/qpdf.
+
+QPDF is copyright (c) 2005-2017 Jay Berkenbilt
+
+This software may be distributed under the terms of version 2 of the
+Artistic License which may be found in the source distribution as
+"Artistic-2.0".  It is provided "as is" without express or implied
+warranty.
+
+
+Prerequisites
+=============
+
+QPDF depends on the external libraries "zlib" and "jpeg". These are
+part of every Linux distribution and are readily available. Download
+information appears in the documentation. For Windows, you can
+download pre-built binary versions of these libraries for some
+compilers; see README-windows.txt for additional details.
+
+QPDF requires a C++ compiler that works with STL.  Your compiler must
+also support "long long".  Almost all modern compilers do.  If you are
+trying to port qpdf to a compiler that doesn't support long long, you
+could change all occurrences of "long long" to "long" in the source
+code, noting that this would break binary compatibility with other
+builds of qpdf.  Doing so would certainly prevent qpdf from working
+with files larger than 2 GB, but remaining functionality would most
+likely work fine.  If you built qpdf this way and it passed its test
+suite with large file support disabled, you could be confident that
+you had an otherwise working qpdf.
+
+
+Licensing terms of embedded software
+====================================
+
+QPDF makes use of zlib and jpeg libraries for its functionality. These
+packages can be downloaded separately from their own download
+locations, or they can be downloaded in the external-libs area of the
+qpdf download site.
+
+The Rijndael encryption implementation used as the basis for AES
+encryption and decryption support comes from Philip J. Erdelsky's
+public domain implementation.  The files libqpdf/rijndael.cc and
+libqpdf/qpdf/rijndael.h remain in the public domain.  They were
+obtained from
+
+  http://www.efgh.com/software/rijndael.htm
+  http://www.efgh.com/software/rijndael.txt
+
+The embedded sha2 code comes from sphlib 3.0
+
+  http://www.saphir2.com/sphlib/
+
+That code has the following license:
+
+  Copyright (c) 2007-2011  Projet RNRT SAPHIR
+
+  Permission is hereby granted, free of charge, to any person obtaining
+  a copy of this software and associated documentation files (the
+  "Software"), to deal in the Software without restriction, including
+  without limitation the rights to use, copy, modify, merge, publish,
+  distribute, sublicense, and/or sell copies of the Software, and to
+  permit persons to whom the Software is furnished to do so, subject to
+  the following conditions:
+
+  The above copyright notice and this permission notice shall be included
+  in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+Building from a pristine checkout
+=================================
+
+When building qpdf from a pristine checkout from version control,
+documentation and automatically generated files are not present.
+Building on Windows from a pristine checkout is not guaranteed to work
+because of issues running autoconf; see README-windows.txt for how to
+handle this.  For UNIX and UNIX-like systems, you must have some
+addditional tools installed to build from the source repository.  To
+do this, you should run
+
+./autogen.sh
+./configure --enable-doc-maintenance
+make
+make install
+
+If you don't have Apache fop and the docbook stylesheets installed,
+you won't be able to build documentation.  You can omit
+--enable-doc-maintenance and produce working qpdf software that passes
+its test suite, but make install will fail because the documentation
+files won't exist.  Depending on your purposes, you can either work
+around this or grab the docs from a source distribution.
+
+
+Building from source distribution on UNIX/Linux
+===============================================
+
+For UNIX and UNIX-like systems, you can usually get by with just
+
+./configure
+make
+make install
+
+Packagers may set DESTDIR, in which case make install will install
+inside of DESTDIR, as is customary with many packages.  For more
+detailed general information, see the "INSTALL" file in this
+directory.  If you are already accustomed to building and installing
+software that uses autoconf, there's nothing new for you in the
+INSTALL file.
+
+
+Building on Windows
+===================
+
+QPDF is known to build and pass its test suite with mingw (latest
+version tested: gcc 4.6.2), mingw64 (latest version tested: 4.7.0) and
+Microsoft Visual C++ 2010, both 32-bit and 64-bit versions.  MSYS plus
+ActiveState Perl is required to build as well in order to get make
+and other related tools.  See README-windows.txt for details on how to
+build under Windows, see README-windows.txt.
+
+
+Additional Notes on Build
+=========================
+
+QPDF's build system, inspired by abuild (http://www.abuild.org), can
+optionally use its own built-in rules rather than using libtool and
+obeying the compiler specified with configure.  This can be enabled by
+passing --with-buildrules=buildrules where buildrules corresponds to
+one of the .mk files (other than rules.mk) in the make directory.
+This should never be necessary on a UNIX system, but may be necessary
+on a Windows system.  See README-windows.txt for details.  There is a
+gcc-linux.mk file enable "gcc-linux" build rules, but it is intended
+to help test the build system; Linux users should build with the
+"libtools" rules, which are enabled by default.
+
+The QPDF package provides some executables and a software library.  A
+user's manual can be found in the "doc" directory.  The docbook
+sources to the user's manual can be found in the "manual" directory.
+
+The software library is just libqpdf, and all the header files are in
+the qpdf subdirectory. If you link statically with -lqpdf, then you
+will also need to link with -lz and -ljpeg. The shared qpdf library is
+linked with -lz and -ljpeg, none of qpdf's public header files
+directly include files from libz, and only Pl_DCT.hh includes files
+from libjpeg, so for most cases, qpdf's development files are self
+contained. If you need to use Pl_DCT in your application code, you
+will need to have the header files for some libjpeg distribution in
+your include path.
+
+To learn about using the library, please read comments in the header
+files in include/qpdf, especially QPDF.hh, QPDFObjectHandle.hh, and
+QPDFWriter.hh.  You can also study the code of qpdf/qpdf.cc, which
+exercises most of the public interface.  There are additional example
+programs in the examples directory.  Reading all the source files in
+the qpdf directory (including the qpdf command-line tool and some test
+drivers) along with the code in the examples directory will give you a
+complete picture of every aspect of the public interface.
+
+
+Additional Notes on Test Suite
+==============================
+
+By default, slow tests are disabled.  Slow tests include image
+comparison tests and large file tests.  Image comparison tests can be
+enabled by passing --enable-test-compare-images to ./configure.  This
+was on by default in qpdf versions prior to 3.0, but is now off by
+default.  Large file tests can be enabled by passing
+--with-large-file-test-path=path to ./configure or by setting the
+QPDF_LARGE_FILE_TEST_PATH environment variable.  On Windows, this
+should be a Windows path.  Run ./configure --help for additional
+options.  The test suite provides nearly full coverage even without
+these tests.  Unless you are making deep changes to the library that
+would impact the contents of the generated PDF files or testing this
+on a new platform for the first time, there is no real reason to run
+these tests.  If you're just running the test suite to make sure that
+qpdf works for your build, the default tests are adequate.  The
+configure rules for these tests do nothing other than setting
+variables in autoconf.mk, so you can feel free to turn these on and
+off directly in autoconf.mk rather than rerunning configure.
+
+If you are packaging qpdf for a distribution and preparing a build
+that is run by an autobuilder, you may want to add the
+--enable-show-failed-test-output to configure options.  This way, if
+the test suite fails, test failure detail will be included in the
+build output.  Otherwise, you will have to have access to the
+qtest.log file from the build to view test failures.  The debian
+packages for qpdf enable this option, for example.
+
+
+Random Number Generation
+========================
+
+By default, when the qpdf detects either the Windows cryptography API
+or the existence of /dev/urandom, /dev/arandom, or /dev/random, it
+uses them to generate cryptography secure random numbers.  If none of
+these conditions are true, the build will fail with an error.  This
+behavior can be modified in several ways:
+
+ * If you configure with --disable-os-secure-random or define
+   SKIP_OS_SECURE_RANDOM, qpdf will not attempt to use Windows
+   cryptography or the random device.  You must either supply your own
+   random data provider or allow use of insecure random numbers.
+
+ * If you configure qpdf with the --enable-insecure-random option or
+   define USE_INSECURE_RANDOM, qpdf will try insecure random numbers
+   if OS-provided secure random numbers are disabled.  This is not a
+   fallback.  In order for insecure random numbers to be used, you
+   must also disable OS secure random numbers since, otherwise,
+   failure to find OS secure random numbers is a compile error.  The
+   insecure random number source is stdlib's random() or rand() calls.
+   These random numbers are not cryptography secure, but the qpdf
+   library is fully functional using them.  Using non-secure random
+   numbers means that it's easier in some cases to guess encryption
+   keys.  If you're not generating encrypted files, there's no
+   advantage to using secure random numbers.
+
+ * In all cases, you may supply your own random data provider.  To do
+   this, derive a class from qpdf/RandomDataProvider (since 5.1.0) and
+   call QUtil::setRandomDataProvider before you create any QPDF
+   objects.  If you supply your own random data provider, it will
+   always be used even if support for one of the other random data
+   providers is compiled in.  If you wish to avoid any possibility of
+   your build of qpdf from using anything but a user-supplied random
+   data provider, you can define SKIP_OS_SECURE_RANDOM and not
+   USE_INSECURE_RANDOM.  In this case, qpdf will throw a runtime error
+   if any attempt is made to generate random numbers and no random
+   data provider has been supplied.
+
+If you are building qpdf on a platform that qpdf doesn't know how to
+generate secure random numbers on, a patch would be welcome.