readme_php3-i18n-ja

php-4.4.7学习linux时下载的源代码

==========================================
  README for I18N Package
==========================================

o Name and location of package

Name:           php-3.0.18-i18n-ja-2
Location:       http://www.happysize.co.jp/techie/php-ja-jp/
                ftp://ftp.happysize.co.jp/php-ja-jp/
                http://php.vdomains.org/
                ftp://ftp.vdomains.org/pub/php-ja-jp/
                http://php.jpnnet.com/

Currently, this I18N version of PHP only adds Japanese support to base
PHP.  It allows you to use Japanese in scripts, as well as conversion
between various Japanese encodings.  It will work perfectly fine with 
ASCII with i18n option enabled.  (note: executable is bit larger due 
to UNICODE table).  The basic design aproach is to allow for other 
languages to be added in the future.  Developers are encourage to join
us!

For more information on Japanese encodings, please refer to the 
section "Additional Notes."


o What is this package?

This package allows you to handle multiple Japanese encodings (SJIS, EUC,
UTF-8, JIS) in PHP.  If you find any bugs in this package, please report
them to the appropriate mailing list.  For now, the PHP-jp mailing list 
is the best place for this.

PHP-jp ML       mailto:[e-mail]
                http://sidecar.ics.es.osaka-u.ac.jp/php-jp/
                (discussions are in Japanese)


o Who should use this

Due to lack of documentation, it's not intended for beginners.  If
something goes wrong, be prepared to fix it on your own.


o Warranty and Copyright

There is no warranty with this package.  Use it at your own risk.

Please refer to the source code for the copyrights.  In general, each
program's copyright is owned by the programmer.  Unless you obey the
copyright holders restrictions, you are not allowed to use it in any
form.


o Redistribution

As described in the source code, this package and the components are
allowed to be redistributed with certain restrictions.

Due to this package being still in beta, please try to redistribute
it as an entire package.  Please try not to distribute it as a form
of patch.  Because we would prefer to have this package distributed
as one single package (not patch of patch of patch), avoid releasing
any patch to this package.


o Who made this

A team of volunteers, PHP3 Internationalization, has been contributing
their free time producing it.  Although we are not related to the core
PHP programmers, we are hoping to have our modifications merged into the
core distribution in the near future.  Thus, we did not call this a
"Japanese Patch" (or distribution).  Our final goal is to have true
i18nized PHP!

For anyone interested in this project, please drop us a line.

Contact Address:
        [e-mail]
        (Discussions are in Japanese, but feel free to write us in English)

Webpage (English and Japanese):
        http://php.jpnnet.com/

Project Outline (Japanese):
        http://www.happysize.co.jp/techie/php-ja-jp/spec.htm

Developers:
        Hironori Sato <[e-mail]>
        Shigeru Kanemoto <[e-mail]>
        Tsukada Takuya <[e-mail]>
        U. Kenkichi <[e-mail]>
        Tateyama  <[e-mail]>
        Other gracious contributors


o Future plans

- fulfilling what's written in outline
- support for other languages other than Japanese
- make the character conversion as a library (?)
- more testing


o Special Thanks to

PHP Japanese webpage maintainer, Hirokawa-san
        http://www.cityfujisawa.ne.jp/%7Elouis/apps/phpfi/
PHP-JP ML's Yamamoto-san
        http://sidecar.ics.es.osaka-u.ac.jp/php-jp/
Previous jp-patch developers



==========================================
  Advantages of using I18N package
==========================================

- allows you to use various character encodings for script files and 
  http output
- distinguish character encoding in POST/GET/COOKIE
- proper mail output using JIS as body and MIME/Base64/JIS subject
- if http output's Content-Type is text/html, it will set proper charset
- stable character encoding conversion
- multibyte regex



==========================================
  Installation
==========================================

o Summary

Add --enable-i18n option when running configure.  For your own setup,
add any other appropriate options as well.

Don't forget to copy php3.ini-dist to desired location.
(ex. /usr/local/lib/php3.ini)

If you have already installed PHP3, copy all the entries in php3.ini-dist
which start with "i18n.xxxx" to php3.ini.


o configure option
    --enable-i18n
      include i18n features

    --enable-mbregex
      include multibyte regex library
      (without i18n enabled, mbregex functions will not function)


o creating cgi version

    % tar xvzf php-3.0.18-i18n-ja-2.tar.gz
    % cd php-3.0.18-i18n-ja-2
    % ./configure --enable-i18n --enable-mbregex
    % make


o creating Apache version (regular module)

    % tar xvzf php-3.0.18-i18n-ja-2.tar.gz
    % tar xvzf apache_1.3.x.tar.gz
    % cd apache_1.3.x
    % ./configure
    % cd ../php-3.0.18-i18n-ja-2
    % ./configure --with-apache=../apache_1.3.x --enable-i18n --enable-mbregex
    % make
    % make install
    % cd ../apache_1.3.x
    % ./configure --activate-module=src/modules/php3/libphp3.a
    % make
    % make install


o creating Apache DSO version

    create DSO capable Apache first
    % tar xvzf apache_1.3.x.tar.gz
    % cd apache-1.3.x
    % ./configure --enable-shared=max
    % make
    % make install

    now create php3
    % cd php-3.0.18-i18n-ja-2
    % ./configure --with-apxs=/usr/local/apache/bin/apxs --enable-i18n \
        --enable-mbregex
    % make
    % make install


==========================================
  Additional Notes
==========================================

o Multibyte regex library

From beta4, we have included the multibyte (mb) regex library which comes with
Ruby.  With this addition, you can now use regex in EUC, SJIS and UTF-8
encoding.  To avoid any conflicts with HSREGEX included with Apache,
each function name has been changed.  Therefore, mb regex functions are
named differently from the original ereg functions in PHP.  The character
encoding used in mb regex is configured in i18n.internal_encoding.


o Binary Output

If http output encoding is set to other than 'pass', conversion of encoding
from internal encoding to http output is done automatically.  Thus,
if you prefer to spit out anything in raw binary format, your data
may be corrupted.  In such event, set http_output to 'pass'.

ex.
        <?
            i18n_http_output("pass");
            ...
            echo $the_binary_data_string;
        ?>


o Content-Type

Depending on the setting of http_output, PHP will output the proper charset.
ex. Content-Type: text/html; charset="..."

Be aware of following:

- If you set Content-Type header using header() function, that will
  override the automatic addition of charset.
- Be cautious when you set i18n_http_output, since if any output is
  made prior to this, proper header may have been sent out to the
  client already.


o In the event of trouble

If you find any bugs or trouble, please contact us at the above address.
It may help us to track the problem if you send us the script as well.

If you encounter any memory related error such as segmentation violation,
add --enable-debug when you run configure.  This will give you more
detail information on where error has occurred.  The error is stored
in the server log or regular http output in CGI mode.


o About Japanese encodings

Due to historical reason, there are multiple character encodings used
for Japanese.  The most common encodings are: SJIS, EUC, JIS, and UTF-8.  
Here are (very) brief description of them:

EUC
  commonly used in UNIX environment
  8bit-8bit combo
  always >=0x80

SJIS
  commonly used in Mac or PCs
  similar to EUC
  mostly 8bit-8bit (some 8bit-7bit)
  mostly >=0x80
  there are some halfwidth (size of ASCII) multibytes

JIS
  commonly used in 7bit environment (nntp and smtp)
  starts with escaping char, \033 and a few more characters

UTF-8
  16bit+ encoding
  defines many languages existing in this world
  see http://www.unicode.org/ for more detail

Because of having all these character encodings, PHP needs to translate
between these encodings on the fly.  Also, the addition of the mb regex 
library allows you to handle mb strings without fear of getting mb char 
chopped in half.

Since Japanese is not the only language with multiple encodings, we
encourage other developers to modify our code to suit your needs.  We
definitely need people to work with Korean, Chinese (both traditional
and simplified), and Russian.  Let us know if you are interested in
this project!



==========================================
  php3.ini setting
==========================================

The following init options will allow you to change the default settings.
Define these settings in the global section of php3.ini.

All keywords are case-insensitive.

o Encoding naming

    For each encoding, there are three names: standarized, alias, MIME

    - UTF-8
         standard: UTF-8
         alias: N/A 
         mime: UTF-8

    - ASCII
         standard: ASCII
         alias: N/A
         mime: US-ASCII

    - Japanese EUC
         standard: EUC-JP
         alias: EUC, EUC_JP, eucJP, x-euc-jp
         mime: EUC-JP

    - Shift JIS
         standard: SJIS
         alias: x-sjis, MS_Kanji
         mime: Shift_JIS

    - JIS
         standard: JIS
         alias: N/A 
         mime: ISO-2022-JP

    - Quoted-Printable
         standard: Quoted-Printable
         alias: qprint
         mime: N/A

    - BASE64
         standard: BASE64
         alias: N/A
         mime: N/A

    - no conversion
         standard: pass
         alias: none
         mime: N/A

    - auto encoding detection
         standard: auto
         alias: unknown
         mime: N/A

    * N/A - Not Applicapable

o i18n.http_output - default http output encoding

    i18n.http_output = EUC-JP|SJIS|JIS|UTF-8|pass
        EUC-JP : EUC
        SJIS: SJIS
        JIS : JIS
        UTF-8: UTF-8
        pass: no conversion

    The default is pass (internal encoding is used)
    It can be re-configured on the fly using i18n_http_output().


o i18n.internal_encoding - internal encoding

    i18n.internal_encoding = EUC-JP|SJIS|UTF-8
        EUC-JP : EUC
        SJIS: SJIS
        UTF-8: UTF-8

    The default is EUC-JP.  

    PHP parser is designed based on using ISO-8859-1.  For other
    encodings, following conditions have to be satisfied in order
    to use them:
       - per byte encoding
       - single byte charactor in range of 00h-7fh which is compatible 
         with ASCII
       - multibyte without 00h-7fh
    In case of Japanese, EUC-JP and UTF-8 are the only encoding that
    meets this criteria.

    If i18n.internal_encoding and i18n.http_output differs, conversion
    takes place at the time of output.  If you convert any data within
    PHP scripts to URL encoding, BASE64 or Quoted-Printable, encoding
    stays as defined in i18n.internal_encoding.  Thus, if you would
    prefer to encode in compliance with i18n.http_output, you need
    to manually convert encoding.

    ex. $str = urlencode( i18n_convert($str, i18n_http_output()) );