[libpng16] Moved part of INSTALL back to manual; added table of contents.

INSTALL

@@ -41,33 +41,19 @@ is not already on your system.  zlib can usually be found
 wherever you got libpng.  zlib can be placed in another directory,
 at the same level as libpng.
 
-If your system already has a preinstalled zlib you will still need
-to have access to the zlib.h and zconf.h include files that
-correspond to the version of zlib that's installed.
-
-If you wish to test with a particular zlib that is not first in the
-standard library search path, put ZLIBLIB, ZLIBINC, CPPFLAGS, LDFLAGS,
-and LD_LIBRARY_PATH in your environment before running "make test"
-or "make distcheck":
-
-ZLIBLIB=/path/to/lib export ZLIBLIB
-ZLIBINC=/path/to/include export ZLIBINC
-CPPFLAGS="-I$ZLIBINC" export CPPFLAGS
-LDFLAGS="-L$ZLIBLIB" export LDFLAGS
-LD_LIBRARY_PATH="$ZLIBLIB:$LD_LIBRARY_PATH" export LD_LIBRARY_PATH
-
-If you are using one of the makefile scripts, put ZLIBLIB and ZLIBINC
-in your environment and type "make ZLIBLIB=$ZLIBLIB ZLIBINC=$ZLIBINC test".
-
 If you want to use "cmake" (see www.cmake.org), type
 
    cmake . -DCMAKE_INSTALL_PREFIX=/path
    make
    make install
 
+If your system already has a preinstalled zlib you will still need
+to have access to the zlib.h and zconf.h include files that
+correspond to the version of zlib that's installed.
+
 You can rename the directories that you downloaded (they
-might be called "libpng-x.y.z" or "libpngNN" and "zlib-1.2.7"
+might be called "libpng-x.y.z" or "libpngNN" and "zlib-1.2.5"
-or "zlib127") so that you have directories called "zlib" and "libpng".
+or "zlib125") so that you have directories called "zlib" and "libpng".
 
 Your directory structure should look like this:
 
@@ -85,7 +71,6 @@ Your directory structure should look like this:
              depcomp, install-sh, mkinstalldirs, test-pngtest.sh
           contrib
              gregbook
-             libtests
              pngminim
              pngminus
              pngsuite
@@ -145,272 +130,6 @@ do that, run "make install" in the zlib directory first if necessary).
 Some also allow you to run "make test-installed" after you have
 run "make install".
 
-Configuring libpng for 16-bit platforms
-
-You will want to look into zconf.h to tell zlib (and thus libpng) that
-it cannot allocate more then 64K at a time.  Even if you can, the memory
-won't be accessible.  So limit zlib and libpng to 64K by defining MAXSEG_64K.
-
-Configuring for DOS
-
-For DOS users who only have access to the lower 640K, you will
-have to limit zlib's memory usage via a png_set_compression_mem_level()
-call.  See zlib.h or zconf.h in the zlib library for more information.
-
-Configuring for Medium Model
-
-Libpng's support for medium model has been tested on most of the popular
-compilers.  Make sure MAXSEG_64K gets defined, USE_FAR_KEYWORD gets
-defined, and FAR gets defined to far in pngconf.h, and you should be
-all set.  Everything in the library (except for zlib's structure) is
-expecting far data.  You must use the typedefs with the p or pp on
-the end for pointers (or at least look at them and be careful).  Make
-note that the rows of data are defined as png_bytepp, which is
-an "unsigned char far * far *".
-
-Prepending a prefix to exported symbols
-
-Starting with libpng-1.6.0, you can configure libpng (when using the
-"configure" script) to prefix all exported symbols by means of the
-configuration option "--with-libpng-prefix=FOO_", where FOO_ can be any
-string beginning with a letter and containing only uppercase
-and lowercase letters, digits, and the underscore (i.e., a C language
-identifier).  This creates a set of macros in pnglibconf.h, so this is
-transparent to applications; their function calls get transformed by
-the macros to use the modified names.
-
-Configuring for compiler xxx:
-
-All includes for libpng are in pngconf.h.  If you need to add, change
-or delete an include, this is the place to do it.
-The includes that are not needed outside libpng are placed in pngpriv.h,
-which is only used by the routines inside libpng itself.
-The files in libpng proper only include pngpriv.h and png.h, which
-in turn includes pngconf.h and, as of libpng-1.5.0, pnglibconf.h.
-As of libpng-1.5.0, pngpriv.h also includes three other private header
-files, pngstruct.h, pnginfo.h, and pngdebug.h, which contain material
-that previously appeared in the public headers.
-
-Removing unwanted object code
-
-There are a bunch of #define's in pngconf.h that control what parts of
-libpng are compiled.  All the defines end in _SUPPORTED.  If you are
-never going to use a capability, you can change the #define to #undef
-before recompiling libpng and save yourself code and data space, or
-you can turn off individual capabilities with defines that begin with
-PNG_NO_.
-
-In libpng-1.5.0 and later, the #define's are in pnglibconf.h instead.
-
-You can also turn all of the transforms and ancillary chunk capabilities
-off en masse with compiler directives that define
-PNG_NO_READ[or WRITE]_TRANSFORMS, or PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS,
-or all four, along with directives to turn on any of the capabilities that
-you do want.  The PNG_NO_READ[or WRITE]_TRANSFORMS directives disable the
-extra transformations but still leave the library fully capable of reading
-and writing PNG files with all known public chunks. Use of the
-PNG_NO_READ[or WRITE]_ANCILLARY_CHUNKS directive produces a library
-that is incapable of reading or writing ancillary chunks.  If you are
-not using the progressive reading capability, you can turn that off
-with PNG_NO_PROGRESSIVE_READ (don't confuse this with the INTERLACING
-capability, which you'll still have).
-
-All the reading and writing specific code are in separate files, so the
-linker should only grab the files it needs.  However, if you want to
-make sure, or if you are building a stand alone library, all the
-reading files start with "pngr" and all the writing files start with "pngw".
-The files that don't match either (like png.c, pngtrans.c, etc.)
-are used for both reading and writing, and always need to be included.
-The progressive reader is in pngpread.c
-
-If you are creating or distributing a dynamically linked library (a .so
-or DLL file), you should not remove or disable any parts of the library,
-as this will cause applications linked with different versions of the
-library to fail if they call functions not available in your library.
-The size of the library itself should not be an issue, because only
-those sections that are actually used will be loaded into memory.
-
-Changes to the build and configuration of libpng in libpng-1.5.x
-
-Details of internal changes to the library code can be found in the CHANGES
-file and in the GIT repository logs.  These will be of no concern to the vast
-majority of library users or builders; however, the few who configure libpng
-to a non-default feature set may need to change how this is done.
-
-There should be no need for library builders to alter build scripts if
-these use the distributed build support - configure or the makefiles -
-however, users of the makefiles may care to update their build scripts
-to build pnglibconf.h where the corresponding makefile does not do so.
-
-Building libpng with a non-default configuration has changed completely.
-The old method using pngusr.h should still work correctly even though the
-way pngusr.h is used in the build has been changed; however, library
-builders will probably want to examine the changes to take advantage of
-new capabilities and to simplify their build system.
-
-1. Specific changes to library configuration capabilities
-
-The library now supports a complete fixed point implementation and can
-thus be used on systems that have no floating point support or very
-limited or slow support.  Previously gamma correction, an essential part
-of complete PNG support, required reasonably fast floating point.
-
-As part of this the choice of internal implementation has been made
-independent of the choice of fixed versus floating point APIs and all the
-missing fixed point APIs have been implemented.
-
-The exact mechanism used to control attributes of API functions has
-changed.  A single set of operating system independent macro definitions
-is used and operating system specific directives are defined in
-pnglibconf.h
-
-As part of this the mechanism used to choose procedure call standards on
-those systems that allow a choice has been changed.  At present this only
-affects certain Microsoft (DOS, Windows) and IBM (OS/2) operating systems
-running on Intel processors.  As before, PNGAPI is defined where required
-to control the exported API functions; however, two new macros, PNGCBAPI
-and PNGCAPI, are used instead for callback functions (PNGCBAPI) and
-(PNGCAPI) for functions that must match a C library prototype (currently
-only png_longjmp_ptr, which must match the C longjmp function.)  The new
-approach is documented in pngconf.h
-
-Despite these changes, libpng 1.5.0 only supports the native C function
-calling standard on those platforms tested so far (__cdecl on Microsoft
-Windows).  This is because the support requirements for alternative
-calling conventions seem to no longer exist.  Developers who find it
-necessary to set PNG_API_RULE to 1 should advise the mailing list
-(png-mng-implement) of this and library builders who use Openwatcom and
-therefore set PNG_API_RULE to 2 should also contact the mailing list.
-
-A new test program, pngvalid, is provided in addition to pngtest.
-pngvalid validates the arithmetic accuracy of the gamma correction
-calculations and includes a number of validations of the file format.
-A subset of the full range of tests is run when "make check" is done
-(in the 'configure' build.)  pngvalid also allows total allocated memory
-usage to be evaluated and performs additional memory overwrite validation.
-
-Many changes to individual feature macros have been made. The following
-are the changes most likely to be noticed by library builders who
-configure libpng:
-
-1) All feature macros now have consistent naming:
-
-#define PNG_NO_feature turns the feature off
-#define PNG_feature_SUPPORTED turns the feature on
-
-pnglibconf.h contains one line for each feature macro which is either:
-
-#define PNG_feature_SUPPORTED
-
-if the feature is supported or:
-
-/*#undef PNG_feature_SUPPORTED*/
-
-if it is not.  Library code consistently checks for the 'SUPPORTED' macro.
-It does not, and libpng applications should not, check for the 'NO' macro
-which will not normally be defined even if the feature is not supported.
-The 'NO' macros are only used internally for setting or not setting the
-corresponding 'SUPPORTED' macros.
-
-Compatibility with the old names is provided as follows:
-
-PNG_INCH_CONVERSIONS turns on PNG_INCH_CONVERSIONS_SUPPORTED
-
-And the following definitions disable the corresponding feature:
-
-PNG_SETJMP_NOT_SUPPORTED disables SETJMP
-PNG_READ_TRANSFORMS_NOT_SUPPORTED disables READ_TRANSFORMS
-PNG_NO_READ_COMPOSITED_NODIV disables READ_COMPOSITE_NODIV
-PNG_WRITE_TRANSFORMS_NOT_SUPPORTED disables WRITE_TRANSFORMS
-PNG_READ_ANCILLARY_CHUNKS_NOT_SUPPORTED disables READ_ANCILLARY_CHUNKS
-PNG_WRITE_ANCILLARY_CHUNKS_NOT_SUPPORTED disables WRITE_ANCILLARY_CHUNKS
-
-Library builders should remove use of the above, inconsistent, names.
-
-2) Warning and error message formatting was previously conditional on
-the STDIO feature. The library has been changed to use the
-CONSOLE_IO feature instead. This means that if CONSOLE_IO is disabled
-the library no longer uses the printf(3) functions, even though the
-default read/write implementations use (FILE) style stdio.h functions.
-
-3) Three feature macros now control the fixed/floating point decisions:
-
-PNG_FLOATING_POINT_SUPPORTED enables the floating point APIs
-
-PNG_FIXED_POINT_SUPPORTED enables the fixed point APIs; however, in
-practice these are normally required internally anyway (because the PNG
-file format is fixed point), therefore in most cases PNG_NO_FIXED_POINT
-merely stops the function from being exported.
-
-PNG_FLOATING_ARITHMETIC_SUPPORTED chooses between the internal floating
-point implementation or the fixed point one.  Typically the fixed point
-implementation is larger and slower than the floating point implementation
-on a system that supports floating point; however, it may be faster on a
-system which lacks floating point hardware and therefore uses a software
-emulation.
-
-4) Added PNG_{READ,WRITE}_INT_FUNCTIONS_SUPPORTED.  This allows the
-functions to read and write ints to be disabled independently of
-PNG_USE_READ_MACROS, which allows libpng to be built with the functions
-even though the default is to use the macros - this allows applications
-to choose at app buildtime whether or not to use macros (previously
-impossible because the functions weren't in the default build.)
-
-2. Changes to the configuration mechanism
-
-Prior to libpng-1.5.0 library builders who needed to configure libpng
-had either to modify the exported pngconf.h header file to add system
-specific configuration or had to write feature selection macros into
-pngusr.h and cause this to be included into pngconf.h by defining
-PNG_USER_CONFIG. The latter mechanism had the disadvantage that an
-application built without PNG_USER_CONFIG defined would see the
-unmodified, default, libpng API and thus would probably fail to link.
-
-These mechanisms still work in the configure build and in any makefile
-build that builds pnglibconf.h, although the feature selection macros
-have changed somewhat as described above.  In 1.5.0, however, pngusr.h is
-processed only once, when the exported header file pnglibconf.h is built.
-pngconf.h no longer includes pngusr.h, therefore pngusr.h is ignored after the
-build of pnglibconf.h and it is never included in an application build.
-
-The rarely used alternative of adding a list of feature macros to the
-CPPFLAGS setting in the build also still works; however, the macros will be
-copied to pnglibconf.h and this may produce macro redefinition warnings
-when the individual C files are compiled.
-
-All configuration now only works if pnglibconf.h is built from
-scripts/pnglibconf.dfa.  This requires the program awk.  Brian Kernighan
-(the original author of awk) maintains C source code of that awk and this
-and all known later implementations (often called by subtly different
-names - nawk and gawk for example) are adequate to build pnglibconf.h.
-The Sun Microsystems (now Oracle) program 'awk' is an earlier version
-and does not work; this may also apply to other systems that have a
-functioning awk called 'nawk'.
-
-Configuration options are now documented in scripts/pnglibconf.dfa.  This
-file also includes dependency information that ensures a configuration is
-consistent; that is, if a feature is switched off dependent features are
-also removed.  As a recommended alternative to using feature macros in
-pngusr.h a system builder may also define equivalent options in pngusr.dfa
-(or, indeed, any file) and add that to the configuration by setting
-DFA_XTRA to the file name.  The makefiles in contrib/pngminim illustrate
-how to do this, and a case where pngusr.h is still required.
-
-Configuring libpng for multiprocessing
-
-Libpng uses setjmp()/longjmp() for error handling.  Unfortunately setjmp()
-is known to be not thread-safe on some platforms and we don't know of
-any platform where it is guaranteed to be thread-safe.  Therefore, if
-your application is going to be using multiple threads, you should
-configure libpng with PNG_NO_SETJMP in your pngusr.dfa file, with
--DPNG_NO_SETJMP on your compile line, or with
-
-  #undef PNG_SETJMP_SUPPORTED
-
-in your pnglibconf.h or pngusr.h.
-
-Other sources of information about libpng:
-
 Further information can be found in the README and libpng-manual.txt
 files, in the individual makefiles, in png.h, and the manual pages
 libpng.3 and png.5.