Changeset 12807 in project


Ignore:
Timestamp:
12/09/08 21:51:55 (11 years ago)
Author:
Kon Lovett
Message:

Doc update.

Location:
release/3/srfi-29/trunk
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • release/3/srfi-29/trunk/srfi-29-eggdoc.scm

    r12792 r12807  
    6565      (code "(read)") ", not just a string.")
    6666
    67       (p "This implementation uses the "
    68       (url "http://www.call-with-current-continuation.org/eggs/locale.html" locale") " "
     67      (p "This implementation uses the " (url "eggs/locale.html" "locale") " "
    6968      "extension for all locale information.")
    7069
    71       (subsection "Exceptions"
    72 
    73         (p "Extension error conditions are signaled with a composite condition of "
    74         (code "(exn srfi-29)") ".")
    75 
    76         (p "The property-condition " (code "exn") " has properties "
    77         (code "location") ", " (code "message") ", and, optionally, " (code "arguments") ".")
    78 
    79         (p "An invalid bundle-specification raises the composite-condition "
    80         (code "(exn srfi-29 insufficient)") ".")
    81 
    82         (p "An unknown bundle-specification raises the composite-condition "
    83         (code "(exn srfi-29 undefined)") ".")
     70      (subsection "Parameters"
     71
     72        (parameter "(current-language [LANGUAGE])"
     73          (p "Gets or sets the " (tt "LANGUAGE") " symbol.") )
     74
     75        (parameter "(current-country [COUNTRY])"
     76          (p "Gets or sets the " (tt "COUNTRY") " symbol.") )
     77
     78        (parameter "(current-locale-details [LOCALE-DETAILS])"
     79          (p "Gets or sets the " (tt "LOCALE-DETAILS") " list.") )
     80
     81        (parameter "(current-locale-format-function [FORMAT-PROCEDURE])"
     82          (p "Gets or sets the " (tt "FORMAT-PROCEDURE") ". This procedure must "
     83          "have the signature " (code "(port | string | boolean string [object] ...)") ".") )
     84
     85        (procedure "(reset-locale-parameters)"
     86          (p "When the " (code "current-locale") " is changed, "
     87          "(see the " (url "eggs/locale.html" "locale") " egg), "
     88          "the " (code "current-*") " parameters need not be set individually. "
     89          "This will update those parameters to the values "
     90          "in the new locale. (Reset as in set anew.)") )
    8491      )
    8592
    86       (subsection "Parameters"
    87 
    88         (parameter "(current-language [LANGUAGE])"
    89           (p "Gets or sets the " (tt "LANGUAGE") ".") )
    90 
    91         (parameter "(current-country [COUNTRY])"
    92           (p "Gets or sets the " (tt "COUNTRY") ".") )
    93 
    94         (parameter "(current-locale-details [LOCALE-DETAILS])"
    95           (p "Gets or sets the " (tt "LOCALE-DETAILS") ".") )
    96 
    97         (parameter "(current-locale-format-function [FORMAT-PROCEDURE])"
    98           (p "Gets or sets the " (tt "FORMAT-PROCEDURE") ".") )
    99       )
    100 
    10193      (subsection "Procedures"
    102 
    103         (procedure "(reset-locale-parameters)"
    104           (p "If you change the " (code "current-locale") " "
    105           "(see the " (url "eggs/locale.html" "locale") " egg), "
    106           "you don't have to set all the " (code "current-foo") " "
    107           "parameters. You can simply call this "
    108           "procedure, and it will update those parameters to the values "
    109           "in the new locale. (Reset as in set anew.)") )
    110 
     94         
    11195        (procedure "(most-specific-bundle-specifier PACKAGE-NAME)"
    11296          (p "Returns the most specific bundle specifier for the "
     
    155139        (procedure "(localized-template PACKAGE-NAME TEMPLATE-NAME [NOT-FOUND #f])"
    156140          (p "Returns the object for the " (tt "TEMPLATE-NAME") " in " (tt "PACKAGE-NAME") ", "
    157           "when found, otherwise the " (tt "NOT-FOUND") ".") )
     141          "when found, otherwise the " (tt "NOT-FOUND") " value.") )
    158142
    159143        (procedure "(localized-template-set! PACKAGE-NAME TEMPLATE-NAME VALUE)"
     
    176160
    177161          (p "When a localized-template is not found and the " (tt "TEMPLATE-NAME") " "
    178           "is a string then it is used a the format-string.")
     162          "is a " (code "string") " then it is used a the format-string.")
    179163
    180164          (p "A representation is always displayed, even when no template is found. "
    181165          "Just not a localized one.") )
    182166       )
     167
     168      (subsection "Exceptions"
     169
     170        (p "Extension error conditions are signaled with a composite condition of "
     171        (code "(exn srfi-29)") ".")
     172
     173        (p "The property-condition " (code "exn") " has properties "
     174        (code "location") ", " (code "message") ", and, optionally, " (code "arguments") ".")
     175
     176        (p "An invalid bundle-specification raises the composite-condition "
     177        (code "(exn srfi-29 insufficient)") ".")
     178
     179        (p "An unknown bundle-specification raises the composite-condition "
     180        (code "(exn srfi-29 undefined)") ".")
     181      )
    183182     )
    184183
     
    205204    (history
    206205     (version "1.14.0" "Pushed defaults to locale egg.")
    207      (version "1.13.0" "Needs new Egg lookup-table.")
    208      (version "1.12.0" "Needed Unit files. Procedure 'localized-format' did not follow specification.")
     206     (version "1.13.0" "Needs newer Egg lookup-table.")
     207     (version "1.12.0" "Needs Unit files. Procedure 'localized-format' did not follow specification.")
    209208     (version "1.9.0" "Version increased to force egg update [by Ivan Raikov].")
    210209     (version "1.8.0" "Added 'localized-template-set!'.")
  • release/3/srfi-29/trunk/srfi-29.html

    r12015 r12807  
    170170<p>Bundles are assumed stored in the system bundle directory, <code>(repository-path) &quot;srfi-29-bundles&quot;</code>.</p>
    171171<p>Within a bundle directory the structure is <code>[LANGUAGE [COUNTRY [SCRIPT [CODESET [MODIFIER]]]]] PACKAGE-NAME</code>.</p>
    172 <p>The default language is <code>en</code>. The default country is <code>us</code>. The locale package will override these if a locale is set. Otherwise the user must set the corresponding parameters.</p>
    173172<p>Any object which can be returned by <code>(read)</code> and tested for equality with <code>equal?</code> is acceptable as a <tt>TEMPLATE-NAME</tt>. So strings are a valid <tt>TEMPLATE-NAME</tt>. Further, <code>(localized-template ...)</code> will return any object which can be returned by <code>(read)</code>, not just a string.</p>
    174 <p>Aborts with the composite condition <code>(exn srfi-29)</code> and properties <code>location</code>, <code>message</code>, and <code>arguments</code> for errors.</p>
     173<p>This implementation uses the <a href="eggs/locale.html">locale</a> extension for all locale information.</p>
    175174<div class="subsection">
    176175<h4>Parameters</h4>
    177176<dt class="definition"><strong>parameter:</strong> (current-language [LANGUAGE])</dt>
    178177<dd>
    179 <p>Gets or sets the <tt>LANGUAGE</tt>.</p></dd>
     178<p>Gets or sets the <tt>LANGUAGE</tt> symbol.</p></dd>
    180179<dt class="definition"><strong>parameter:</strong> (current-country [COUNTRY])</dt>
    181180<dd>
    182 <p>Gets or sets the <tt>COUNTRY</tt>.</p></dd>
     181<p>Gets or sets the <tt>COUNTRY</tt> symbol.</p></dd>
    183182<dt class="definition"><strong>parameter:</strong> (current-locale-details [LOCALE-DETAILS])</dt>
    184183<dd>
    185 <p>Gets or sets the <tt>LOCALE-DETAILS</tt>.</p></dd>
     184<p>Gets or sets the <tt>LOCALE-DETAILS</tt> list.</p></dd>
    186185<dt class="definition"><strong>parameter:</strong> (current-locale-format-function [FORMAT-PROCEDURE])</dt>
    187186<dd>
    188 <p>Gets or sets the <tt>FORMAT-PROCEDURE</tt>.</p></dd></div>
     187<p>Gets or sets the <tt>FORMAT-PROCEDURE</tt>. This procedure must have the signature <code>(port | string | boolean string [object] ...)</code>.</p></dd>
     188<dt class="definition"><strong>procedure:</strong> (reset-locale-parameters)</dt>
     189<dd>
     190<p>When the <code>current-locale</code> is changed, (see the <a href="eggs/locale.html">locale</a> egg), the <code>current-*</code> parameters need not be set individually. This will update those parameters to the values in the new locale. (Reset as in set anew.)</p></dd></div>
    189191<div class="subsection">
    190192<h4>Procedures</h4>
    191 <dt class="definition"><strong>procedure:</strong> (reset-locale-parameters)</dt>
    192 <dd>
    193 <p>If you change the <code>current-locale</code> (see the <a href="eggs/locale.html">locale</a> egg), you don't have to set all the <code>current-foo</code> parameters. You can simply call this procedure, and it will update those parameters to the values in the new locale. (Reset as in set anew.)</p></dd>
    194193<dt class="definition"><strong>procedure:</strong> (most-specific-bundle-specifier PACKAGE-NAME)</dt>
    195194<dd>
     
    223222<dt class="definition"><strong>procedure:</strong> (localized-template PACKAGE-NAME TEMPLATE-NAME [NOT-FOUND #f])</dt>
    224223<dd>
    225 <p>Returns the object for the <tt>TEMPLATE-NAME</tt> in <tt>PACKAGE-NAME</tt>, when found, otherwise the <tt>NOT-FOUND</tt>.</p></dd>
     224<p>Returns the object for the <tt>TEMPLATE-NAME</tt> in <tt>PACKAGE-NAME</tt>, when found, otherwise the <tt>NOT-FOUND</tt> value.</p></dd>
    226225<dt class="definition"><strong>procedure:</strong> (localized-template-set! PACKAGE-NAME TEMPLATE-NAME VALUE)</dt>
    227226<dd>
     
    235234<dd>
    236235<p>Formats the arguments <tt>ARG0 ...</tt> to the <tt>PORT</tt> using the <code>(current-locale-format-function)</code> and the format string <code>(localized-template PACKAGE-NAME TEMPLATE-NAME)</code>.</p>
    237 <p>When a localized-template is not found and the <tt>TEMPLATE-NAME</tt> is a string then it is used a the format-string.</p>
    238 <p>A representation is always displayed, even when no template is found. Just not a localized one.</p></dd></div></div>
     236<p>When a localized-template is not found and the <tt>TEMPLATE-NAME</tt> is a <code>string</code> then it is used a the format-string.</p>
     237<p>A representation is always displayed, even when no template is found. Just not a localized one.</p></dd></div>
     238<div class="subsection">
     239<h4>Exceptions</h4>
     240<p>Extension error conditions are signaled with a composite condition of <code>(exn srfi-29)</code>.</p>
     241<p>The property-condition <code>exn</code> has properties <code>location</code>, <code>message</code>, and, optionally, <code>arguments</code>.</p>
     242<p>An invalid bundle-specification raises the composite-condition <code>(exn srfi-29 insufficient)</code>.</p>
     243<p>An unknown bundle-specification raises the composite-condition <code>(exn srfi-29 undefined)</code>.</p></div></div>
    239244<div class="section">
    240245<h3>Issues</h3>
    241246<p>Possible race condition creating a bundle file or directory.</p>
    242247<p>The locale symbols must have a lowercase printname! As such they do not truly reflect ISO 639-1/2 &amp; ISO 3166-1 standard names. This is a SRFI 29 restriction.</p>
    243 <p><code>(current-locale-details)</code> is ill-defined by SRFI 29. Which symbol means what? This implementation defines locale details as a 3 element list <code>(SCRIPT CODESET MODIFIER)</code> where the elements are symbols or <code>#f</code>.</p></div>
     248<p><code>(current-locale-details)</code> is ill-defined by SRFI 29. Which symbol means what? This implementation defines locale details as a 3 element list <code>(SCRIPT CODESET MODIFIER)</code> where the elements are symbols or <code>#f</code>.</p>
     249<p>The SRFI 29 document uses the term &quot;country&quot; for what the locale extension knows as &quot;region&quot;.</p></div>
    244250<div class="section">
    245251<h3>Version</h3>
    246252<ul>
    247 <li>1.13.0 Needs new Egg lookup-table.</li>
    248 <li>1.12.0 Needed Unit files. Procedure 'localized-format' did not follow specification.</li>
     253<li>1.14.0 Pushed defaults to locale egg.</li>
     254<li>1.13.0 Needs newer Egg lookup-table.</li>
     255<li>1.12.0 Needs Unit files. Procedure 'localized-format' did not follow specification.</li>
    249256<li>1.9.0 Version increased to force egg update [by Ivan Raikov].</li>
    250257<li>1.8.0 Added 'localized-template-set!'.</li>
Note: See TracChangeset for help on using the changeset viewer.