Changeset 9804 in project


Ignore:
Timestamp:
03/16/08 06:17:55 (12 years ago)
Author:
rlpowell
Message:

Yet another stab at making the Egg wiki/docs do what I want.

Location:
release/3/caketext/trunk
Files:
4 edited
1 moved

Legend:

Unmodified
Added
Removed
  • release/3/caketext/trunk/README

    r9776 r9804  
    11Function documentation is in the code, and is extracted with mole to
    2 make caketext.html
     2make caketext-doc.html
    33
    44Other documentation is on the wiki at
  • release/3/caketext/trunk/SConstruct

    r9776 r9804  
    1010env.spec('tests/results/caketext-spec.tbr', [ 'tests/caketext-spec.scm', 'caketext.scm' ])
    1111
    12 env.mole('caketext.html', 'caketext.scm')
     12env.mole('caketext-doc.html', 'caketext.scm')
  • release/3/caketext/trunk/caketext-doc.html

    r9794 r9804  
    44<!-- Table of content -->
    55<p><dl>
    6 <p><dt><a name='tocchapt56283' href='#chapt56283'><b>Overview And Requirements</b></a><dd>
     6<p><dt><a name='tocchapt27995' href='#chapt27995'><b>Function Documentation</b></a><dd>
    77<p><dt><a name='tocchapt4208' href='#chapt4208'><b>Definitions</b></a><dd>
    88
     
    4545f:  <a name='tocfunc46059' href='#docfunc46059' style='text-decoration:none'>my-format</a><br>
    4646</dl>
    47 <hr height='5'><center><h3><a name='chapt56283' href='#tocchapt56283'>Overview And Requirements</a></h3></center>
     47<hr height='5'><center><h3><a name='chapt27995' href='#tocchapt27995'>Function Documentation</a></h3></center>
    4848
    4949<pre>
    50 This egg is a Chicken Scheme port of Locale::MakeText; see
    51 http://search.cpan.org/dist/Locale-Maketext/lib/Locale/Maketext/TPJ13.pod
     50This is just the low-level function documentation; see
     51http://chicken.wiki.br/caketext for examples and such.
    5252
    5353If you have any problems with this egg, or would like to suggest
    5454changes/additions to the documentation, please e-mail
    5555rlpowell@digitalkingdom.org
    56 
    57 -----
    58 
    59 Differences From Locale::MakeText
    60 
    61 Because of the history behind Common Lisp's format function, which
    62 Scheme has inherited, we don't use the same escape sequences.
    63 
    64 We don't turn strings into code at all, because with the 2-pass
    65 setup I'd need to be able to get code back from format-modular,
    66 and I can't.  This is a possible target for future optimization,
    67 if this module causes performance problems.
    68 
    69 caketext can write out auto-generated language packs; nah-nah, our
    70 language has code/data isomorphism and yooooours doesn't!  :)
    71 (More to the point, all Schemes can read/write almost all Scheme
    72 objects on the fly; it's a basic part of the language.)
    73 
    74 -----
    75 
    76 Requirements
    77 
    78 Also because of wanting to use a CL-style format, this egg
    79 requires format-modular (also, format-modular has some nice
    80 modularity this egg takes advantage of).
    81 
    82 -----
    83 
    84 Configuration Values
    85 
    86 onmiss:         Function to run when a miss occurs on this pack.
    87                 Arguments passed are the language pack and the text
    88                 key.  No other packs are checked.  The value
    89                 returned is used as the translated text.
    90 
    91 auto-add:       Boolean; if true and there's a miss on this pack,
    92                 add the string here.  No other packs are checked.
    93 
    94 Neither of these have any kind of fall-through options because I
    95 couldn't think of a case where that would be useful.  If you have
    96 a real-world examples, please let me know.
    97 
    98 -----
    99 Escape Sequences
    100 
    101 We use format-modular, and the processing of escapes is done in 2
    102 passes.  The first pass is a regular format-modular &quot;format&quot; pass,
    103 and all those escapes apply and are dealt with.
    104 
    105 The second pass uses our own function escapes, which are like so:
    106 
    107 %(function[%,argument1[%,argument2...]]%)
    108 
    109 (the [...] are indicating optionality; they are not literal)
    110 
    111 Example:
    112 
    113         &quot;This is a test string: %(test%,~A%,~A%).&quot;
    114 
    115 Given a function stored with the name 'test in the appropriate
    116 language pack, this would run that test function on the next two
    117 caketext-translate arguments, i.e. ~A and ~A, which have already
    118 been substituted by the first pass, and replace the whole %(...%)
    119 string with the results.
    120 
    121 -----
    122 
    123 Dumping And Loading
    124 
    125 At any time, the strings in a language pack can be dumped out to a
    126 file using dump-language-pack.  Unlike srfi-29, no attempt is made
    127 to decide what the file should be named; that's up to you.
    128 
    129 Also at any time, a file full of an alist of strings can be loaded
    130 back into a language pack using load-language-pack.  If you do so,
    131 it completely replaces the pack's current strings.
    132 
    133 Similarily, you can load a file full of an alist of symbols and
    134 function definitons to replace the function definitions of a pack.
    135 The performance implications of doing so are non-trivial; see the
    136 documentation for the load-language-pack function for
    137 alternatives.
    138 
    139 -----
    140 
    141 Examples
    142 
    143 A lot of examples can be found by looking at caketext-spec.scm,
    144 which is the test suite.  Here's an example of normal usage;
    145 please e-mail me (rlpowell@digitalkingdom.org) if it is
    146 insufficient for you.
    147 
    148 (define english-pack (new-language-pack))
    149 
    150 (set-language-pack-config! english-pack 'auto-add #t)
    151 
    152 ...
    153 
    154 (output-func
    155 (caketext-translate english-pack #f &quot;You found ~A files.&quot; number))
    156 
    157 This will render the output unchanged; that is, at this point you
    158 might as well have used (format ...), except that the string has
    159 been stored for future translation, which is yay.
    160 
    161 ...
    162 
    163 (dump-language-pack &quot;/tmp/english-strings.dump&quot;)
    164 
    165 In that file your translator will find something like this (we
    166 pretty-print; lucky you):
    167 
    168 ((&quot;You found ~A files.&quot;
    169 .
    170 &quot;You found ~A files.&quot;))
    171 
    172 Your translator should edit that file, perhaps to look something
    173 like this:
    174 
    175 ((&quot;You found ~A files.&quot;
    176 .
    177 &quot;You found ~A files, eh?&quot;))
    178 
    179 and saves it to a file named, say, /tmp/canadian-strings.dump
    180 
    181 After this is done, to localize your program to Canadian English
    182 you'd put statements like this at the top:
    183 
    184 (define canadian-pack (new-language-pack))
    185 
    186 (load-language-pack canadian-pack &quot;/tmp/canadian-strings.dump&quot; &quot;&quot;)
    187 
    188 ...
    189 
    190 (output-func
    191 (caketext-translate english-pack #f &quot;You found ~A files.&quot; number))
    192 
    193 Given the number 5, this will output:
    194 
    195 You found 5 files, eh?
    196 
    197 -----
    198 
    199 License And Copyright
    200 
    201 This entire egg (this file, the test cases, and the documentation)
    202 are all explicitely placed in the public domain by me, Robin Lee
    203 Powell, on 10 March 2008.  If you like the software, I'd sure
    204 appreciate a note, or a line of thanks in your own code or
    205 whatever, but if you do so be sure to thank Andy Lester, the
    206 Locale::Maketext guy, as well, as this is basically copycat work.
    20756</pre><hr height='5'><center><h3><a name='chapt4208' href='#tocchapt4208'>Definitions</a></h3></center>
    20857
  • release/3/caketext/trunk/caketext.meta

    r9776 r9804  
    44 ; that caketext.meta does not need to be listed here
    55
    6  (files "caketext.scm" "caketext.html" "caketext.setup")
     6 (files "caketext.scm" "caketext-doc.html" "caketext.setup")
    77
    88 ; The following should only be present if the egg's documentation should be
  • release/3/caketext/trunk/caketext.setup

    r9776 r9804  
    66  'caketext
    77  ; Files to install for your extension:
    8   '("caketext.o" "caketext.so" "caketext.html")
     8  '("caketext.o" "caketext.so" "caketext-doc.html")
    99  ; Assoc list with properties for your extension:
    1010  '((version 1.0)
    1111    (static "caketext.o") ;; for static linking
    12     (documentation "caketext.html")))
     12    (documentation "caketext-doc.html")))
Note: See TracChangeset for help on using the changeset viewer.