Changeset 9773 in project


Ignore:
Timestamp:
03/15/08 21:31:51 (12 years ago)
Author:
svnwiki
Message:

Changes applied for rlpowell (64.81.66.169) through svnwiki:

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/caketext

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