source: project/release/3/locale/trunk/locale-eggdoc.scm @ 12818

Last change on this file since 12818 was 12818, checked in by Kon Lovett, 12 years ago

Save.

File size: 12.2 KB
Line 
1;;;; locale-eggdoc.scm
2
3(use eggdoc)
4
5(define license
6"Copyright (c) 2005, Kon Lovett.  All rights reserved.
7
8Permission is hereby granted, free of charge, to any person obtaining a
9copy of this software and associated documentation files (the Software),
10to deal in the Software without restriction, including without limitation
11the rights to use, copy, modify, merge, publish, distribute, sublicense,
12and/or sell copies of the Software, and to permit persons to whom the
13Software is furnished to do so, subject to the following conditions:
14
15The above copyright notice and this permission notice shall be included
16in all copies or substantial portions of the Software.
17
18THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
21THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
22OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
23ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
24OTHER DEALINGS IN THE SOFTWARE.")
25
26(define examples '((pre #<<EOF
27EOF
28)))
29
30(define doc `(
31        (eggdoc:begin
32                (name "locale")
33                (description (p "Provides locale operations."))
34                (author (url "mailto:klovett@pacbell.net" "Kon Lovett"))
35
36                (usage)
37                (download "locale.egg")
38                (requires (url "miscmacros.html" "miscmacros"))
39
40                (documentation
41                        (p "locale is a set of routines supporting locale query operations. "
42                        "The environment locale information is determined upon module load and the "
43                        "corresponding parameters are set.")
44
45      (subsection "Locale Components"
46
47        (p "The major data structure is the " (code "locale-components") " type, "
48        "portrayed as an extensible " (tt "key+value") " pairing. The " (tt "key") " "
49        "is a " (code "symbol") ". The " (tt "value") " is usually a " (code "string") ".")
50
51        (p "A " (code "locale-components") " object will have more properties but the "
52        "following are provided for every instance:")
53                          (symbol-table "Common Component Keys"
54          (describe tag "What kind.")
55          (describe name "The composite information object, source specific.")
56          (describe source "The origin for the information.") )
57
58        (p "The " (code "source") " property is one of the following (others are possible):")
59                          (symbol-table "Source Values"
60          (describe POSIX "Information from POSIX environment. The \"name\" is a string.")
61          (describe PLATFORM "Information from the system.")
62          (describe BUILTIN "Information from system defaults.") )
63
64        (p "The " (code "PLATFORM") " source is used for information first. Then the "
65        (code "POSIX") " source is attempted. When all have failed the " (code "BUILTIN") " "
66        "source is used. The point being locale information will be available, but "
67        "without an accuracy guarantee.")
68
69        (p "The " (code "BUILTIN") " source creates a POSIX-style string \"name\" "
70        "constructed using constants and library procedures.")
71      )
72
73      (subsection "Generic Locale Components Property Access"
74
75        (procedure "(locale-components? OBJECT)"
76          (p "Is the " (tt "OBJECT") " a " (code "locale-compenents") " object?") )
77
78        (procedure "(locale-component-ref LOCALE-COMPONENTS KEY [DEFAULT #f])"
79          (p "Returns the " (tt "KEY") " property of " (tt "LOCALE-COMPONENTS") " "
80          "or the " (tt "DEFAULT") " when not found.") )
81
82        (procedure "(set-locale-component! LOCALE-COMPONENTS KEY VALUE)"
83          (p "Updates or creates the " (tt "KEY") " property of " (tt "LOCALE-COMPONENTS") " "
84          "with the " (tt "VALUE") ".") )
85      )
86
87                        (subsection "Timezone"
88
89                                (p "Access to timezone information. A timezone object is a " (code "locale-components") " "
90                                "object with properties for Standard Time Name and Offset, and an optional Summer or "
91                                "Daylight Saving Time Name and Offset. The offset is seconds west (positive) or east "
92                                "(negative) of UTC. The name is some locally accepted timezone name, such as \"PST\". A "
93                                "Daylight Saving Time start rule and end rule are optional properties.")
94
95                          (symbol-table "Timezone Component Properties"
96          (describe std-name "The Standard timezone name.")
97          (describe std-offset "Seconds +/- UTC.")
98          (describe dst-name "The Daylight Saving Time timezone name.")
99          (describe dst-offset "Seconds +/- UTC.")
100          (describe dst-start "The start of Daylight Saving Time; a timezone-dst-rule.")
101          (describe dst-end "The end of Daylight Saving Time; a timezone-dst-rule.") )
102
103                                (group
104                                        (parameter "(current-timezone [VALUE])"
105                                                (p "The currently defined timezone. The specified " (tt "VALUE") " "
106                                                "is either a timezone string value, or " (code "#f") ", indicating no timezone. When "
107                                                "no timezone value is set the default timezone is UTC.") )
108
109                                        (procedure "(current-timezone-components)"
110                                                (p "Returns the timezone-components object corresponding to the current-timezone.") )
111
112                                        (procedure "(timezone-components? TIMEZONE-COMPONENTS)"
113                                                (p "Is the specified " (tt "TIMEZONE-COMPONENTS") " object actually a "
114                                                "timezone-components object?") )
115
116                                        (procedure "(timezone-component-ref TIMEZONE-COMPONENTS KEY [DEFAULT #f])"
117                                                (p "Returns the timezone-component " (tt "KEY") " of the "
118                                                (tt "TIMEZONE-COMPONENTS") " object, or the " (tt "DEFAULT") " for a "
119                                                "missing component.") )
120
121                                        (procedure "(set-timezone-component! TIMEZONE-COMPONENTS KEY VALUE)"
122                                                (p "Sets the timezone-component " (tt "KEY") " of the "
123                                                (tt "TIMEZONE-COMPONENTS") " object to " (tt "VALUE") ".") )
124
125                                        (procedure "(timezone-dst-rule-julian-noleap? TIMEZONE-DST-RULE)"
126                                                (p "Is the specified " (tt "TIMEZONE-DST-RULE") " object actually a "
127                                                "daylight saving time julian day without leap seconds object?") )
128
129                                        (procedure "(timezone-dst-rule-julian-leap? TIMEZONE-DST-RULE)"
130                                                (p "Is the specified " (tt "TIMEZONE-DST-RULE") " object actually "
131                                                "a daylight saving time julian day assuming leap seconds object?") )
132
133                                        (procedure "(timezone-dst-rule-mwd? TIMEZONE-DST-RULE)"
134                                                (p "Is the specified " (tt "TIMEZONE-DST-RULE") " object actually "
135                                                "a daylight saving time month+week+day object?") )
136
137                                        (procedure "(timezone-dst-rule-offset TIMEZONE-DST-RULE)"
138                                                (p "Returns the seconds within day offset component of the specified "
139                                                (tt "TIMEZONE-DST-RULE") " object.") )
140
141                                        (procedure "(timezone-dst-rule-julian TIMEZONE-DST-RULE)"
142                                                (p "Returns the julian day component of the specified "
143                                                (tt "TIMEZONE-DST-RULE") " object.") )
144
145                                        (procedure "(timezone-dst-rule-month TIMEZONE-DST-RULE)"
146                                                (p "Returns the month of year component of the specified "
147                                                (tt "TIMEZONE-DST-RULE") " object.") )
148
149                                        (procedure "(timezone-dst-rule-week TIMEZONE-DST-RULE)"
150                                                (p "Returns the week of month component of the specified "
151                                                (tt "TIMEZONE-DST-RULE") " object.") )
152
153                                        (procedure "(timezone-dst-rule-day TIMEZONE-DST-RULE)"
154                                                (p "Returns the day of week component of the specified "
155                                                (tt "TIMEZONE-DST-RULE") " object.") )
156
157                                        (procedure "(make-timezone-dst-rule-julian-leap JULIAN-DAY OFFSET)"
158                                                (p "Returns a daylight saving time julian day assuming leap seconds rule object.") )
159
160                                        (procedure "(make-timezone-dst-rule-julian-noleap JULIAN-DAY OFFSET)"
161                                                (p "Returns a daylight saving time julian day without leap seconds rule object.") )
162
163                                        (procedure "(make-timezone-dst-rule-mwd MONTH WEEK DAY OFFSET)"
164                                                (p "Returns a daylight saving time month.week.day rule object.") )
165
166                                        (procedure "(posix-timezone-string->timezone-components STRING [SOURCE \"POSIX\"])"
167                                                (p "Parses a POSIX timezone string specification, " (tt "STRING") ", and "
168                                                "returns the corresponding timezone-components object, or "
169                                                (code "#f") " when a parse error occurs. A " (code "#f") " or empty string "
170                                                "value is mapped to the default timezone. The optional " (tt "SOURCE") " "
171                                                "indicates what locale system supplied the string.") )
172
173                                        (procedure "(posix-load-timezone)"
174                                                (p "Initialize the current-timezone from the TZ environment variable.") )
175                                )
176                        )
177
178                        (subsection "Locale"
179
180                                (p "Access to locale information. A locale object is composed of a "
181                                "Language, an optional Script, an optional Region, an optional Codeset, and an "
182                                "optional Modifier. The language should be an ISO 639-1 or ISO 639-2 name. The "
183                                "Script should be a RFC 3066bis name. The region should be an ISO 3166-1 name. "
184                                "The codeset and modifier forms are locale dependent.")
185
186                                (symbol-table "Locale Properties"
187                                  (describe language "ISO 639-1 or ISO 639-2 name string. Default \"en\".")
188                                  (describe script "RFC 3066bis name string.")
189                                  (describe region "ISO 3166-1 name string. Default \"US\".")
190                                  (describe codeset "The character code to character mapping system.")
191                                  (describe modifier "Instance data, if any.") )
192
193                                (group
194                                        (parameter "(current-locale [VALUE])"
195                                                (p "The currently defined locale. The specified " (tt "VALUE") " "
196                                                "is either a locale string value, or " (code "#f") ", indicating locale independence. "
197                                                "When no locale value is set the default locale is " (code "#f") ".") )
198
199                                        (procedure "(current-locale-components)"
200                                                (p "Returns the locale-components object corresponding to the current-locale.") )
201
202                                        (procedure "(locale-components? LOCALE-COMPONENTS)"
203                                                (p "Is the specified " (tt "LOCALE-COMPONENTS") " object actually a "
204                                                "locale-components object?") )
205
206                                        (procedure "(locale-component-ref LOCALE-COMPONENTS KEY [DEFAULT #f])"
207                                                (p "Returns the locale-component " (tt "KEY") " of the "
208                                                (tt "LOCALE-COMPONENTS") " object, or the " (tt "DEFAULT") " for a "
209                                                "missing component.") )
210
211                                        (procedure "(set-locale-component! LOCALE-COMPONENTS KEY VALUE)"
212                                                (p "Sets the locale-component " (tt "KEY") " of the "
213                                                (tt "LOCALE-COMPONENTS") " object to " (tt "VALUE") ".") )
214
215                                        (procedure "(posix-locale-string->locale-components STRING [SOURCE \"POSIX\"])"
216                                                (p "Parses a POSIX locale string specification, " (tt "STRING") ", and "
217                                                "returns the corresponding locale-components object, or " (code "#f") " "
218                                                "when a parse error occurs. A " (code "#f") " or empty string value is "
219                                                "mapped to the default locale. The optional " (tt "SOURCE") " indicates "
220                                                "what locale system supplied the string.") )
221
222                                        (procedure "(posix-load-locale)"
223                                                (p "Sets up the locale using POSIX rules. Initializes the "
224                                                (code "current-locale") " from the " (tt "MESSAGES") "category.") )
225                                )
226                        )
227
228                        (subsection "Locale Category"
229
230                                (p "Access to the locale information by category.")
231
232                          (symbol-table "Locale Category Keys"
233          (describe ADDRESS "")
234          (describe COLLATE "")
235          (describe CTYPE "")
236          (describe IDENTIFICATION "")
237          (describe LANGUAGE "")
238          (describe MEASUREMENT "")
239          (describe MESSAGES "")
240          (describe MONETARY "")
241          (describe NAME "")
242          (describe NUMERIC "")
243          (describe PAPER "")
244          (describe TELEPHONE "")
245          (describe TIME "") )
246
247                                (group
248                                        (procedure "(set-locale-category! CATEGORY LOCALE-COMPONENTS)"
249                                                (p "Sets the specified " (tt "CATEGORY") " to the specified "
250                                                (tt "LOCALE-COMPONENTS") " object.") )
251
252                                        (procedure "(locale-category-ref CATEGORY)"
253                                                (p "Returns the specified " (tt "CATEGORY") " locale-components object, or "
254                                                (code "#f") " if the category is not valued.") )
255
256                                )
257                        )
258                )
259
260    (section "Issues"
261
262                        (p "NOTE: This is a work in progress. Currently only the Posix locale "
263                        "information is supported. Plans are to support the native MacOS X and Windows locale "
264                        "APIs. Changes to this API are almost certain.")
265    )
266
267    #;(examples ,examples)
268
269                (history
270                        (version "0.4.0" "Added \"default\" timezone & locale")
271                        (version "0.3.3" "Removed use of 'critical-section'")
272                        (version "0.3.2" "Dropped :optional")
273                        (version "0.3.1" "Bug fix for default dst offset")
274                        (version "0.3" "Reverts to defaults for timezone & locale when parse errors")
275                        (version "0.2" "Exports")
276                        (version "0.1" "Initial release"))
277
278                (section "License" (pre ,license))
279        )
280))
281
282(eggdoc->html doc)
Note: See TracBrowser for help on using the repository browser.