Text::Iconv Version 1.2

Copyright © 2001 Michael Piotrowski.  All Rights Reserved.

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

Description
-----------

This module provides a Perl interface to the iconv() codeset
conversion function, as defined by the Single UNIX Specification.  For
more details see the POD documentation embedded in the file Iconv.pm,
which will also be installed as Text::Iconv(3) man page.

Prerequisites
-------------

Your system should be compliant with the Single UNIX Specification or
at least provide iconv_open(), iconv() and iconv_close() functions
compliant with it.

Note that the possible conversions and the quality of the conversions
depend on the available iconv conversion tables and algorithms, which
are in most cases supplied by the operating system vendor.  Some
systems also allow you to build your own tables (e.g., HP-UX, Tru64
UNIX, and AIX provide the genxlt(1) command).

It is also possible to use a separate iconv library such as Bruno
Haible's libiconv package, just make sure that the desired library is
found (see <http://clisp.cons.org/~haible/packages-libiconv.html>).

Building the module
-------------------

Since the Single UNIX Specification only specifies an interface,
several issues are left to the implementation to define, namely:

    1. The supported codesets
    2. The supported conversions
    3. The names for the supported codesets

Please check your system documentation for the above points.  You
might also have to link in a special library (AIX seems to require
this).  If this is the case, add it to the list of needed libraries in
Makefile.PL (e.g.: -liconv).

The module can be built using this sequence of commands:

    perl Makefile.PL
    make
    make test

The purpose of the test scripts (run by "make test") is to check if an
iconv library can be found, and if the iconv functions can be called.
It is neither intended to find out which conversions are supported,
nor to test the quality of the conversions provided by your iconv
library.  However, since the iconv functions can only be tested by
calling them, which in turn requires the specification of codesets to
be converted.  The test scripts try some conversions which seem to be
widely supported.  Conversions not supported by your iconv
implementation are skipped, but for the purpose outlined above this is
no problem, as it shows that the iconv functions are working.  There
is no standard way to find out which conversions are supported by an
implementation.  This is also the reason why Text::Iconv can't provide
platform-independent support for codeset identifiers (even if it it
would be nice to have).

Installation
------------

    make install

Feedback
--------

This version of Locale::iconv was tested on HP-UX 10.20 and 11.00,
Solaris 2.6, and Linux 2.2.13 (whatever that means), using their
native iconv implementations.  I've also gotten success reports for
HP-UX 10.20 and Solaris 2.6 using Bruno Haible's libiconv.

If you are building the module on another platform I would appreciate
a note to tell me how you got on, especially if you need to specify
additional libraries, or if none of the codeset identifiers in the
test scripts are supported.

Thanks
------

Thanks go to:

Otto Frost, Marc Lehmann, Loic Dachary, Steve Haslam, Matt Sergeant,
and Leon Brocard.

Michael Piotrowski <mxp@dynalabs.de>
