source: trunk/src/corelib/codecs/codecs.qdoc@ 624

/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain additional
** rights.  These rights are described in the Nokia Qt LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \group codecs
    \title Codecs
    \ingroup groups
    \brief Codec support in Qt.

    These codecs provide facilities for conversion between Unicode and
    specific text encodings.

    \generatelist{related}
*/

/*!
    \page codec-big5.html
    \title Big5 Text Codec
    \ingroup codecs

    The Big5 codec provides conversion to and from the Big5 encoding.
    The code was originally contributed by Ming-Che Chuang
    \<[email protected]\> for the Big-5+ encoding, and was
    included in Qt with the author's permission, and the grateful
    thanks of the Qt team. (Note: Ming-Che's code is QPL'd, as
    per an mail to [email protected].)

    However, since Big-5+ was never formally approved, and was never
    used by anyone, the Taiwan Free Software community and the Li18nux
    Big5 Standard Subgroup agree that the de-facto standard Big5-ETen
    (zh_TW.Big5 or zh_TW.TW-Big5) be used instead.

    The Big5 is currently implemented as a pure subset of the
    Big5-HKSCS codec, so more fine-tuning is needed to make it
    identical to the standard Big5 mapping as determined by
    Li18nux-Big5.  See \l{http://www.autrijus.org/xml/} for the draft
    Big5 (2002) standard.

    James Su \<[email protected]\> \<[email protected]\>
    generated the Big5-HKSCS-to-Unicode tables with a very
    space-efficient algorithm. He generously donated his code to glibc
    in May 2002.  Subsequently, James has kindly allowed Anthony Fok
    \<[email protected]\> \<[email protected]\> to adapt the code
    for Qt.

    \legalese
    Copyright (C) 2000  Ming-Che Chuang \BR
    Copyright (C) 2002  James Su, Turbolinux Inc. \BR
    Copyright (C) 2002  Anthony Fok, ThizLinux Laboratory Ltd.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:

    \list 1
    \o Redistributions of source code must retain the above copyright
       notice, this list of conditions and the following disclaimer.
    \o Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in the
       documentation and/or other materials provided with the distribution.
    \endlist

    THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND
    ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
    FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
    OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
    OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
    SUCH DAMAGE.
    \endlegalese
*/

/*!
    \page codec-big5hkscs.html
    \title Big5-HKSCS Text Codec
    \ingroup codecs

    The Big5-HKSCS codec provides conversion to and from the
    Big5-HKSCS encoding.

    The codec grew out of the QBig5Codec originally contributed by
    Ming-Che Chuang \<[email protected]\>.  James Su
    \<[email protected]\> \<[email protected]\> and Anthony Fok
    \<[email protected]\> \<[email protected]\> implemented HKSCS-1999
    QBig5hkscsCodec for Qt-2.3.x, but it was too late in Qt development
    schedule to be officially included in the Qt-2.3.x series.

    Wu Yi \<[email protected]\> ported the HKSCS-1999 QBig5hkscsCodec to
    Qt-3.0.1 in March 2002.

    With the advent of the new HKSCS-2001 standard, James Su
    \<[email protected]\> \<[email protected]\> generated the
    Big5-HKSCS<->Unicode tables with a very space-efficient algorithm.
    He generously donated his code to glibc in May 2002.  Subsequently,
    James has generously allowed Anthony Fok to adapt the code for
    Qt-3.0.5.

    Currently, the Big5-HKSCS tables are generated from the following
    sources, and with the Euro character added:
    \list 1
    \o \l{http://www.microsoft.com/typography/unicode/950.txt}
    \o \l{http://www.info.gov.hk/digital21/chi/hkscs/download/big5-iso.txt}
    \o \l{http://www.info.gov.hk/digital21/chi/hkscs/download/big5cmp.txt}
    \endlist

    There may be more fine-tuning to the QBig5hkscsCodec to maximize its
    compatibility with the standard Big5 (2002) mapping as determined by
    Li18nux Big5 Standard Subgroup.  See \l{http://www.autrijus.org/xml/}
    for the various Big5 CharMapML tables.

    \legalese
    Copyright (C) 2000  Ming-Che Chuang \BR
    Copyright (C) 2001, 2002  James Su, Turbolinux Inc. \BR
    Copyright (C) 2002  WU Yi, HancomLinux Inc. \BR
    Copyright (C) 2001, 2002  Anthony Fok, ThizLinux Laboratory Ltd.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:

    \list 1
    \o Redistributions of source code must retain the above copyright
       notice, this list of conditions and the following disclaimer.
    \o Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in the
       documentation and/or other materials provided with the distribution.
    \endlist

    THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND
    ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
    FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
    OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
    OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
    SUCH DAMAGE.
    \endlegalese
*/

/*!
    \page codec-eucjp.html
    \title EUC-JP Text Codec
    \ingroup codecs

    The EUC-JP codec provides conversion to and from EUC-JP, the main
    legacy encoding for Unix machines in Japan.

    The environment variable \c UNICODEMAP_JP can be used to
    fine-tune the JIS, Shift-JIS, and EUC-JP codecs. The \l{ISO
    2022-JP (JIS) Text Codec} documentation describes how to use this
    variable.

    Most of the code here was written by Serika Kurusugawa,
    a.k.a. Junji Takagi, and is included in Qt with the author's
    permission and the grateful thanks of the Qt team. Here is
    the copyright statement for that code:

    \legalese

    Copyright (C) 1999 Serika Kurusugawa. All rights reserved.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:

    \list 1
    \o Redistributions of source code must retain the above copyright
       notice, this list of conditions and the following disclaimer.
    \o Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in the
       documentation and/or other materials provided with the distribution.
    \endlist

    THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS".
    ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
    FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
    OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
    OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
    SUCH DAMAGE.
    \endlegalese
*/

/*!
    \page codec-euckr.html
    \title EUC-KR Text Codec
    \ingroup codecs

    The EUC-KR codec provides conversion to and from EUC-KR, KR, the
    main legacy encoding for Unix machines in Korea.

    It was largely written by Mizi Research Inc. Here is the
    copyright statement for the code as it was at the point of
    contribution. The subsequent modifications are covered by
    the usual copyright for Qt.

    \legalese

    Copyright (C) 1999-2000 Mizi Research Inc. All rights reserved.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:

    \list 1
    \o Redistributions of source code must retain the above copyright
       notice, this list of conditions and the following disclaimer.
    \o Redistributions in binary form must reproduce the above copyright
       notice, this list of conditions and the following disclaimer in the
       documentation and/or other materials provided with the distribution.
    \endlist

    THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND
    ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
    FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
    OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
    OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
    SUCH DAMAGE.
    \endlegalese
*/

/*!
    \page codec-gbk.html
    \title GBK Text Codec
    \ingroup codecs

    The GBK codec provides conversion to and from the Chinese
    GB18030/GBK/GB2312 encoding.

    GBK, formally the Chinese Internal Code Specification, is a commonly
    used extension of GB 2312-80.  Microsoft Windows uses it under the
    name codepage 936.

    GBK has been superseded by the new Chinese national standard
    GB 18030-2000, which added a 4-byte encoding while remaining
    compatible with GB2312 and GBK.  The new GB 18030-2000 may be described
    as a special encoding of Unicode 3.x and ISO-10646-1.

    Special thanks to charset gurus Markus Scherer (IBM),
    Dirk Meyer (Adobe Systems) and Ken Lunde (Adobe Systems) for publishing
    an excellent GB 18030-2000 summary and specification on the Internet.
    Some must-read documents are:

    \list
    \o \l{ftp://ftp.oreilly.com/pub/examples/nutshell/cjkv/pdf/GB18030_Summary.pdf}
    \o \l{http://oss.software.ibm.com/cvs/icu/~checkout~/charset/source/gb18030/gb18030.html}
    \o \l{http://oss.software.ibm.com/cvs/icu/~checkout~/charset/data/xml/gb-18030-2000.xml}
    \endlist

    The GBK codec was contributed to Qt by
    Justin Yu \<[email protected]\> and
    Sean Chen \<