README
1NAME
2 japana - HTTP proxy converting Japanese characters into ASCII
3
4SYNOPSIS
5 japana [ --addr *addr* ] [ --auth ] [ --configfile *configfile* ]
6 [ --kakasioptions *options* ] [ --port *port* ] [ --proxy *proxy* ]
7 [ --userfile *userfile* ] [ --version ]
8
9 japana [ -a *addr* ] [ -A ] [ -c *configfile* ] [ -o *options* ]
10 [ -p *port* ] [ -P *proxy* ] [ -u *userfile* ] [ -V ]
11
12OVERVIEW
13 japana is a small and simple proxy written in Perl. The proxy converts
14 Japanese characters (Hiragana, Katakana, Kanji etc.) into ASCII (Romaji)
15 on the fly. The conversion is done using the KAKASI library.
16
17DESCRIPTION
18 Just start japana. This will by default create a proxy running on
19 http://localhost:8080 (it will fail if something else is already running
20 on this port). Then point your browser to the proxy. Browse some
21 Japanese website (e.g. http://amazon.co.jp) and see all those Japanese
22 characters converted to plain ascii text.
23
24 Switches
25 --addr *addr* | -a *addr*
26 This is the IP address that japana will bind to. This address
27 (together with the correct port) must be configured in your browser
28 to make use of the japana proxy.
29
30 Be careful: Everybody who can reach the japana port on this address
31 can use your proxy. Consider enabling authentication (--auth
32 option). You might also bind to an address only reachable from your
33 local net or use a packet filter to 'guard' japana from the
34 outside.
35
36 The address '0.0.0.0' will bind japana to all of your network
37 devices.
38
39 Default is to bind to address '127.0.0.1' as this address can only
40 be accessed from your local computer and is not accessible from the
41 network. Please take care when binding to another address.
42
43 --auth | -A
44 This enables the "basic proxy authentication scheme" as described
45 in RFC 2617. If enabled, you must enter a valid username and
46 password before you can use the japana proxy. Note that the
47 passwords are not encrypted in any way, so don't use important
48 ones.
49
50 Default is to use no authentication.
51
52 --configfile *configfile* | -c *configfile*
53 The options from the given configuration file will be read. These
54 options can be overridden by other command line arguments.
55
56 Default is not to read a configuration file.
57
58 --kakasioptions *options* | -o *options*
59 These options are passed directly to kakasi and affect the
60 conversion process. See the kakasi documentation for details.
61
62 Default options are '-ja -ga -ka -Ea -Ka -Ha -Ja -U -s' and should
63 be reasonable.
64
65 --port *port* | -p *port*
66 This is the port on which japana listens to your incoming requests.
67 This port (together with the correct address) must be configured in
68 your browser to make use of the japana proxy.
69
70 Default setting is port 8080.
71
72 --proxy *proxy* | -P *proxy*
73 If this variable contains a value, the given proxy is used by
74 japana. This allows you to chain multiple proxies together.
75
76 Example: If you need a proxy to access the Internet then point your
77 browser to the japana proxy and in turn point japana to your
78 original proxy.
79
80 Set this to 'none' to use no proxy at all.
81
82 Default is to use the environment variable ${http_proxy}.
83
84 --userfile *userfile* | -u *userfile*
85 This file contains the usernames and passwords to use when
86 authentication is enabled.
87
88 Default userfile is '/etc/japana.users'.
89
90 --version | -V
91 This prints the current version of japana and exits.
92
93 Configuration file format
94 Configuration is also possible via configuration files. Every command
95 line switch is possible in a configuration file. Empty lines and lines
96 starting with # are ignored.
97
98 Instead of --port 3128 you would put this line in the configuration
99 file:
100
101 port = 3128
102
103 -o '-ja -ga -ka -U -s' will become
104
105 kakasioptions = -ja -ga -ka -U -s
106
107 and so on and so forth.
108
109 Userfile file format
110 This file contains the usernames and passwords used for authentication.
111 Every line must contain one username and the corresponding password
112 separated by a colon. Empty lines and lines starting with # are ignored.
113
114 This example file contains the user 'japana' with the password 'simple':
115
116 # This is just an example.
117 # Consider changing your password before using japana.
118 japana:simple
119
120MODULES NEEDED
121 use AppConfig;
122 use HTTP::Daemon;
123 use LWP::UserAgent;
124 use Text::Kakasi;
125
126 These modules can be obtained at <http://www.cpan.org> and Text::Kakasi
127 can be found here: <http://www.daionet.gr.jp/~knok/kakasi/>.
128
129 If setting up kakasi is too complicated, you might try the old 1.0.x
130 version of japana. It does not use kakasi (and because of that can't
131 convert Kanji).
132
133OPTIONAL MODULES
134 use Compress::Zlib;
135
136 This module can be obtained at <http://www.cpan.org>.
137
138 When this module is installed, gzipped data transfer is available
139 between your browser, japana and web servers.
140
141BUGS
142 In the default configuration, japana supports NO ACCESS CONTROL!
143 Everyone with access to the japana port on your system will be able to
144 use the proxy. Please consider the use of password authentication
145 (--auth) or bind japana to a port that is either only available from
146 your local network or protected by a packet filter.
147
148 Please report bugs the project website <http://sf.net/projects/japana/>
149 or send a mail to <japana-bugs@cgarbs.de>.
150
151AUTHOR
152 japana was written by Christian Garbs <mitch@cgarbs.de>. Look for
153 updates, support etc. at <http://sf.net/projects/japana/>.
154
155COPYRIGHT
156 japana is licensed under the GNU GPL.
157
158THANKS
159 Thanks go to Tobias Diedrich <ranma@gmx.at> and Benjamin Heuer
160 <benjaminheuer@t-online.de> for patches, ideas, bug-reports and beta
161 testing.
162
163 Sorry to those guys from <news:de.soc.kultur.japan> who helped with the
164 translation routine in version 1.0.x: It is not used any more.
165
166