data/TWiki/AppendixEncodeURLsWithUTF8.txt,v
author Colas Nahaboo <colas@nahaboo.net>
Sat, 26 Jan 2008 15:50:53 +0100
changeset 0 414e01d06fd5
permissions -rw-r--r--
RELEASE 4.2.0 freetown
colas@0
     1
head	1.4;
colas@0
     2
access;
colas@0
     3
symbols;
colas@0
     4
locks; strict;
colas@0
     5
comment	@# @;
colas@0
     6
colas@0
     7
colas@0
     8
1.4
colas@0
     9
date	2008.01.22.03.21.33;	author TWikiContributor;	state Exp;
colas@0
    10
branches;
colas@0
    11
next	1.3;
colas@0
    12
colas@0
    13
1.3
colas@0
    14
date	2006.04.01.05.55.04;	author TWikiContributor;	state Exp;
colas@0
    15
branches;
colas@0
    16
next	1.2;
colas@0
    17
colas@0
    18
1.2
colas@0
    19
date	2006.02.01.12.01.16;	author TWikiContributor;	state Exp;
colas@0
    20
branches;
colas@0
    21
next	1.1;
colas@0
    22
colas@0
    23
1.1
colas@0
    24
date	2004.08.14.07.35.28;	author PeterThoeny;	state Exp;
colas@0
    25
branches;
colas@0
    26
next	;
colas@0
    27
colas@0
    28
colas@0
    29
desc
colas@0
    30
@none
colas@0
    31
@
colas@0
    32
colas@0
    33
colas@0
    34
1.4
colas@0
    35
log
colas@0
    36
@buildrelease
colas@0
    37
@
colas@0
    38
text
colas@0
    39
@%META:TOPICINFO{author="TWikiContributor" date="1111929255" format="1.0" version="4"}%
colas@0
    40
%STARTINCLUDE%
colas@0
    41
#EncodeURLsUTF8
colas@0
    42
---+ Appendix B: Encode URLs With UTF8 
colas@0
    43
colas@0
    44
_Use internationalised characters within !WikiWords and attachment names_
colas@0
    45
colas@0
    46
This topic addresses implemented UTF-8 support for URLs only. The overall plan for UTF-8 support for TWiki is described in TWiki:Codev.ProposedUTF8SupportForI18N.
colas@0
    47
colas@0
    48
%TOC%
colas@0
    49
colas@0
    50
---++ Current Status
colas@0
    51
colas@0
    52
To simplify use of internationalised characters within WikiWords and attachment names, TWiki now supports UTF-8 URLs, converting on-the-fly to virtually any character set, including ISO-8859-*, KOI8-R, EUC-JP, and so on.
colas@0
    53
colas@0
    54
Support for UTF-8 URL encoding avoids having to configure the browser to turn off this encoding in URLs (the default in Internet Explorer, Opera Browser and some Mozilla Browser URLs) and enables support of browsers where only this mode is supported (e.g. Opera Browser for Symbian smartphones).  A non-UTF-8 site character set (e.g. ISO-8859-*) is still used within TWiki, and in fact pages are stored and viewed entirely in the site character set - the browser dynamically converts URLs from the site character set into UTF-8, and TWiki converts them back again.
colas@0
    55
colas@0
    56
System requirements are updated as follows:
colas@0
    57
   * ASCII or ISO-8859-1-only sites do not require any additional CPAN modules to be installed.
colas@0
    58
   * Perl 5.8 sites using any character set do not require additional modules, since CPAN:Encode is installed as part of Perl. 
colas@0
    59
   * This feature still works on Perl 5.005_03 as per TWikiSystemRequirements, or Perl 5.6, as long as CPAN:Unicode::MapUTF8 is installed.  
colas@0
    60
colas@0
    61
The following 'non-ASCII-safe' character encodings are now excluded from use as the site character set, since they interfere with TWiki markup: ISO-2022-*, HZ-*, Shift-JIS, MS-Kanji, GB2312, GBK, GB18030, Johab and UHC. However, many multi-byte character sets work fine, e.g. EUC-JP, EUC-KR, EUC-TW, and EUC-CN. In addition, UTF-8 can already be used, with some limitations, for East Asian languages where EUC character encodings are not acceptable - see TWiki:Codev.ProposedUTF8SupportForI18N.
colas@0
    62
colas@0
    63
It's now possible to override the site character set defined in the ={SiteLocale}= setting in [[%SCRIPTURLPATH{"configure"}%][configure]] - this enables you to have a slightly different spelling of the character set in the server locale (e.g. 'eucjp') and the HTTP header sent to the browser (e.g. 'euc-jp').
colas@0
    64
colas@0
    65
This feature should also support use of Mozilla Browser with TWiki:Codev.TWikiOnMainframe (as long as mainframe web server can convert or pass through UTF-8 URLs) - however, this specific combination is not tested.  Other browser-server combinations should not have any problems.
colas@0
    66
colas@0
    67
Please note that use of UTF-8 as the site character set is not yet supported - see Phase 2 of TWiki:Codev.ProposedUTF8SupportForI18N for plans and work to date in this area.
colas@0
    68
colas@0
    69
This feature is complete in TWiki releases newer than February 2004.
colas@0
    70
colas@0
    71
Note for skin developers: <nop>%INTURLENCODE% is no longer required (TWiki:Plugins.InternationalisingYourSkin).
colas@0
    72
colas@0
    73
colas@0
    74
---++ Details of Implementation
colas@0
    75
colas@0
    76
URLs are not allowed to contain non-ASCII (8th bit set) characters:
colas@0
    77
http://www.w3.org/TR/html4/appendix/notes.html#non-ascii-chars
colas@0
    78
colas@0
    79
The overall plan for UTF-8 support for TWiki is described in two phases in TWiki:/Codev.ProposedUTF8SupportForI18N - this page addresses the first phase, in which UTF-8 is supported for URLs only.
colas@0
    80
colas@0
    81
UTF-8 URL translation to virtually any character set is supported as of TWiki Release 01 Sep 2004, but full UTF-8 support (e.g. pages in UTF-8) is not supported yet - this will be phase 2.
colas@0
    82
colas@0
    83
The code automatically detects whether a URL is UTF-8 or not, taking care to avoid over-long and illegal UTF-8 encodings that could introduce TWiki:Codev.MajorSecurityProblemWithIncludeFileProcessing (tested against a comprehensive [[http://www.cl.cam.ac.uk/~mgk25/ucs/examples/UTF-8-test.txt UTF-8 test file]], which IE 5.5 fails quite dangerously, and Opera Browser passes).  Any non-ASCII URLs that are _not_ valid UTF-8 are then assumed to be directly URL-encoded as a single-byte or multi-byte character set (as now), e.g. EUC-JP.  
colas@0
    84
colas@0
    85
The main point is that you can use TWiki with international characters in WikiWords without changing your browser setup from the default, and you can also still use TWiki using non-UTF-8 URLs.  This works on any Perl version from 5.005_03 onwards and corresponds to Phase 1 of TWiki:Codev.ProposedUTF8SupportForI18N.  You can have different users using different URL formats transparently on the same server.
colas@0
    86
colas@0
    87
UTF-8 URLs are automatically converted to the current [[%SCRIPTURLPATH{"configure"}%#Localisation][{Site}{Charset}]], using modules such as CPAN:Encode if needed.
colas@0
    88
colas@0
    89
TWiki generates the whole page in the site charset, e.g. ISO-8859-1 or EUC-JP, but the browser dynamically UTF-8 encodes the attachment's URL when it's used.  Since Apache serves attachment downloads without TWiki being involved, TWiki's code can't do its UTF-8 decoding trick, so TWiki URL-encodes such URLs in ISO-8859-1 or whatever when generating the page, to bypass this URL encoding, ensuring that the URLs and filenames seen by Apache remain in the site charset.  
colas@0
    90
colas@0
    91
TWiki:Codev.TWikiOnMainframe uses EBCDIC web servers that typically translate their output to ASCII, UTF-8 or ISO-8859-1 (and URLs in the other direction) since there are so few EBCDIC web browsers.  Such web servers don't work with even ISO-8859-1 URLs if they are URL encoded, since the automated translation is bypassed for URL-encoded characters. For TWiki on Mainframe, TWiki assumes that the web server will automatically translate UTF-8 URLs into EBCDIC URLs, as long as URL encoding is turned off in TWiki pages.
colas@0
    92
colas@0
    93
colas@0
    94
---++ Testing and Limitation
colas@0
    95
colas@0
    96
It should work with TWiki:Codev.TWikiOnMainframe.  Tested with IE 5.5, Opera 7.11 and Mozilla (Firebird 0.7). 
colas@0
    97
colas@0
    98
Opera Browser on the P800 smartphone is working for page viewing but leads to corrupt page names when editing pages.
colas@0
    99
colas@0
   100
For up to date information see TWiki:Codev.EncodeURLsWithUTF8
colas@0
   101
colas@0
   102
%STOPINCLUDE%
colas@0
   103
colas@0
   104
__Related Topics:__ AdminDocumentationCategory
colas@0
   105
@
colas@0
   106
colas@0
   107
colas@0
   108
1.3
colas@0
   109
log
colas@0
   110
@buildrelease
colas@0
   111
@
colas@0
   112
text
colas@0
   113
@d1 1
colas@0
   114
a1 2
colas@0
   115
%META:TOPICINFO{author="TWikiContributor" date="1111929255" format="1.0" version="3"}%
colas@0
   116
%TOC%
colas@0
   117
d4 1
colas@0
   118
a4 1
colas@0
   119
---# Appendix B: Encode URLs With UTF8 
colas@0
   120
d10 2
colas@0
   121
@
colas@0
   122
colas@0
   123
colas@0
   124
1.2
colas@0
   125
log
colas@0
   126
@buildrelease
colas@0
   127
@
colas@0
   128
text
colas@0
   129
@d1 1
colas@0
   130
a1 1
colas@0
   131
%META:TOPICINFO{author="TWikiContributor" date="1111929255" format="1.0" version="2"}%
colas@0
   132
d18 3
colas@0
   133
a20 3
colas@0
   134
	* ASCII or ISO-8859-1-only sites do not require any additional CPAN modules to be installed.
colas@0
   135
	* Perl 5.8 sites using any character set do not require additional modules, since CPAN:Encode is installed as part of Perl. 
colas@0
   136
	* This feature still works on Perl 5.005_03 as per TWikiSystemRequirements, or Perl 5.6, as long as CPAN:Unicode::MapUTF8 is installed.  
colas@0
   137
@
colas@0
   138
colas@0
   139
colas@0
   140
1.1
colas@0
   141
log
colas@0
   142
@none
colas@0
   143
@
colas@0
   144
text
colas@0
   145
@d1 1
colas@0
   146
a1 1
colas@0
   147
%META:TOPICINFO{author="PeterThoeny" date="1092468928" format="1.0" version="1.1"}%
colas@0
   148
d5 1
colas@0
   149
a5 1
colas@0
   150
---# Appendix C: Encode URLs With UTF8 
colas@0
   151
d7 3
colas@0
   152
a9 1
colas@0
   153
_This page addresses implemented UTF-8 support for URLs only. The overall plan for UTF-8 support for TWiki is described in TWiki:Codev.ProposedUTF8SupportForI18N ._
colas@0
   154
d22 1
colas@0
   155
a22 1
colas@0
   156
ISO-2022-*, HZ-* and other 'non-ASCII-safe' multi-byte character sets are now specifically excluded from use as the site character set, since they interfere with TWiki ML; however, many multi-byte character sets work fine, e.g. EUC-JP, GB2312, etc.
colas@0
   157
d24 1
colas@0
   158
a24 1
colas@0
   159
It's now possible to override the site character set defined in the =$siteLocale= setting in TWiki.cfg - this enables you to have a slightly different spelling of the character set in the server locale (e.g. 'eucjp') and the HTTP header sent to the browser (e.g. 'euc-jp').
colas@0
   160
d48 1
colas@0
   161
a48 1
colas@0
   162
UTF-8 URLs are automatically converted to the current =$siteCharset= (from the =TWiki.cfg= locale setting), using modules such as CPAN:Encode if needed.
colas@0
   163
a62 4
colas@0
   164
-- TWiki:Main.RichardDonkin - 7 Jan 2004 %BR%
colas@0
   165
-- TWiki:Main.MattWilkie - 10 Aug 2004 %BR%
colas@0
   166
-- TWiki:Main.PeterThoeny - 14 Aug 2004
colas@0
   167
colas@0
   168
d65 1
colas@0
   169
@