source: project/wiki/caketext @ 10198

Last change on this file since 10198 was 10198, checked in by rlpowell, 12 years ago

Changes applied for rlpowell (64.81.66.189) through svnwiki:

File size: 5.5 KB
Line 
1[[toc:]]
2
3== Overview
4
5This egg is a Chicken Scheme port of Locale::MakeText; see
6http://search.cpan.org/dist/Locale-Maketext/lib/Locale/Maketext/TPJ13.pod
7
8To save you the trouble of reading that document, the goal is to
9provide an easy to use localization system that actually works once
10you start trying to do complicated things in more than 2 languages
11or so.
12
13If you have any problems with this egg, or would like to suggest
14changes/additions to the documentation, please e-mail
15rlpowell@digitalkingdom.org
16
17== Function Documentation
18
19This is the general documentation, containing examples, background, and so on.
20The function documentation is generated from the source using mole, and can be
21found at
22[[http://www.call-with-current-continuation.org/eggs/3/caketext-doc.html]].
23
24== Differences From Locale::MakeText
25
26Because of the history behind Common Lisp's format function, which Scheme has
27inherited, we don't use the same escape sequences.
28
29Strings are not turned into code at all, because with the 2-pass setup I'd need
30to be able to get code back from format-modular, and I can't.  This is a
31possible target for future optimization, if this module causes performance
32problems.
33
34caketext can write out auto-generated language packs; nah-nah, our language has
35code/data isomorphism and yooooours doesn't!  :) (More to the point, all
36Schemes can read/write almost all Scheme objects on the fly; it's a basic part
37of the language.)
38
39== Requirements
40
41Also because of wanting to use a CL-style format, this egg requires
42format-modular (also, format-modular has some nice modularity this egg takes
43advantage of).  If you want to compile it yourself and run the test
44suite, you'll need testbase-driver and all of its requirements.
45
46== Configuration Values
47
48; onmiss:                Function to run when a miss occurs on this pack. Arguments passed are the language pack and the text key.  No other packs are checked.  The value returned is used as the translated text.
49
50; auto-add:      Boolean; if true and there's a miss on this pack, add the string here.  No other packs are checked.
51
52Neither of these have any kind of fall-through options because I
53couldn't think of a case where that would be useful.  If you have a
54real-world examples, please let me know.
55
56== Escape Sequences
57
58We use format-modular, and the processing of escapes is done in 2
59passes.  The first pass is a regular format-modular "format" pass,
60and all those escapes apply and are dealt with.
61
62The second pass uses our own function escapes, which are like so:
63
64<enscript highlight=scheme>
65 %(function[%,argument1[%,argument2...]]%)
66</enscript>
67
68(the [...] are indicating optionality; they are not literal)
69
70Example:
71
72> "This is a test string: %(test%,~A%,~A%)."
73
74Given a function stored with the name 'test in the appropriate
75language pack, this would run that test function on the next two
76caketext-translate arguments, i.e. ~A and ~A, which have already
77been substituted by the first pass, and replace the whole %(...%)
78string with the results.
79
80== Dumping And Loading
81
82At any time, the strings in a language pack can be dumped out to a
83file using dump-language-pack.  Unlike srfi-29, no attempt is made
84to decide what the file should be named; that's up to you.
85
86Also at any time, a file full of an alist of strings can be loaded
87back into a language pack using load-language-pack.  If you do so,
88it completely replaces the pack's current strings.
89
90Similarily, you can load a file full of an alist of symbols and
91function definitons to replace the function definitions of a pack.
92The performance implications of doing so are non-trivial; see the
93documentation for the load-language-pack function for alternatives.
94
95== Examples
96
97A lot of examples can be found by looking at caketext-spec.scm,
98which is the test suite.  Here's an example of normal usage; please
99e-mail me (rlpowell@digitalkingdom.org) if it is insufficient for
100you.
101
102<enscript highlight=scheme>
103
104 (define english-pack (new-language-pack))
105
106 (set-language-pack-config! english-pack 'auto-add #t)
107
108 ...
109
110 (output-func
111   (caketext-translate english-pack #f "You found ~A files." number))
112
113</enscript>
114
115This will render the output unchanged; that is, at this point you
116might as well have used (format ...), except that the string has
117been stored for future translation, which is yay.
118
119<enscript highlight=scheme>
120 ...
121
122 (dump-language-pack "/tmp/english-strings.dump")
123</enscript>
124
125In that file your translator will find something like this (we
126pretty-print; lucky you):
127
128<enscript highlight=scheme>
129 (("You found ~A files."
130   .
131   "You found ~A files."))
132</enscript>
133
134Your translator should edit that file, perhaps to look something
135like this:
136
137<enscript highlight=scheme>
138 (("You found ~A files."
139   .
140   "You found ~A files, eh?"))
141</enscript>
142
143and saves it to a file named, say, /tmp/canadian-strings.dump
144
145After this is done, to localize your program to Canadian English
146you'd put statements like this at the top:
147
148<enscript highlight=scheme>
149 (define canadian-pack (new-language-pack))
150
151 (load-language-pack canadian-pack "/tmp/canadian-strings.dump" "")
152
153 ...
154
155 (output-func
156   (caketext-translate english-pack #f "You found ~A files." number))
157</enscript>
158
159Given the number 5, this will output:
160
161> You found 5 files, eh?
162
163== License And Copyright
164
165This entire egg (this file, the test cases, and the documentation)
166are all explicitely placed in the public domain by me, Robin Lee
167Powell, on 10 March 2008.  If you like the software, I'd sure
168appreciate a note, or a line of thanks in your own code or whatever,
169but if you do so be sure to thank Andy Lester, the Locale::Maketext
170guy, as well, as this is basically copycat work.
Note: See TracBrowser for help on using the repository browser.