diff options
Diffstat (limited to 'doc/ref')
-rw-r--r-- | doc/ref/ChangeLog | 39 | ||||
-rw-r--r-- | doc/ref/Makefile.am | 9 | ||||
-rwxr-xr-x | doc/ref/api-data.texi | 9 | ||||
-rw-r--r-- | doc/ref/api-i18n.texi | 292 | ||||
-rw-r--r-- | doc/ref/guile.texi | 3 | ||||
-rw-r--r-- | doc/ref/posix.texi | 15 |
6 files changed, 351 insertions, 16 deletions
diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog index 0b3444cb5..8b8e0befe 100644 --- a/doc/ref/ChangeLog +++ b/doc/ref/ChangeLog @@ -1,3 +1,23 @@ +2006-11-18 Ludovic Courtès <ludovic.courtes@laas.fr> + + * Makefile.am (BUILT_SOURCES): New variable. + (lib-version.texi): New target. + + * guile.texi: Include `lib-version.texi'. + + * api-data.texi (Conversion): Link to `The ice-9 i18n Module' when + describing `string->number'. + (String Comparison): Likewise. + + * api-i18n.texi (Internationalization)[The ice-9 i18n Module]: New + node. + [Gettext Support]: New node; contains text formerly in + `Internationalization'. + + * posix.texi (Locales): Added a link to the glibc manual + describing the various locale categories. Mention locale objects + and link to `The ice-9 i18n Module' when describing `setlocale'. + 2006-11-17 Neil Jerram <neil@ossau.uklinux.net> * intro.texi (Reporting Bugs): Note need for subscription to @@ -87,7 +107,7 @@ * api-data.texi (Scientific): In sqrt, note it's the positive root which is returned (as per R5RS). -2006-09-20 Ludovic Courtès <ludovic.courtes@laas.fr> +2006-09-20 Ludovic Courtès <ludovic.courtes@laas.fr> * api-data.texi (Standard Character Sets): Documented the charset recomputation upon successful `setlocale'. @@ -214,12 +234,12 @@ * posix.texi (Time): In tm:gmtoff, give example values, note not the same as C tm_gmtoff. -2006-06-16 Ludovic Courtès <ludovic.courtes@laas.fr> +2006-06-16 Ludovic Courtès <ludovic.courtes@laas.fr> * api-utility.texi (Equality): Mentioned the behavior of `equal?' for structures (as suggested by Kevin Ryde). -2006-06-13 Ludovic Courtès <ludovic.courtes@laas.fr> +2006-06-13 Ludovic Courtès <ludovic.courtes@laas.fr> * api-compound.texi (Structure Concepts): Mentioned the behavior of `equal?' for structures. @@ -286,7 +306,7 @@ SCM_SIMPLE_VECTOR_SET not SCM_SIMPLE_VECTOR_SET_X, the former is what's in vector.h. -2006-03-21 Ludovic Courtès <ludovic.courtes@laas.fr> +2006-03-21 Ludovic Courtès <ludovic.courtes@laas.fr> * api-data.texi (Conversion): Add scm_c_locale_stringn_to_number. @@ -338,7 +358,7 @@ contexts. Renamed all functions from scm_frame_ to scm_dynwind_. Updated documentation. -2005-12-19 Ludovic Courtès <ludovic.courtes@laas.fr> +2005-12-19 Ludovic Courtès <ludovic.courtes@laas.fr> * api-data.texi (Operations Related to Symbols): Documented `scm_take_locale_symbol ()'. @@ -380,7 +400,7 @@ 2005-11-06 Kevin Ryde <user42@zip.com.au> - From Ludovic Courtès, partial rework by me: + From Ludovic Courtès, partial rework by me: * doc/ref/api-modules.texi (Creating Guile Modules): In define-module, describe #:re-export, #:export-syntax, #:re-export-syntax, #:replace and #:duplicates. Add re-export. @@ -393,7 +413,7 @@ * posix.texi (Network Socket Address): Add scm_make_socket_address, scm_c_make_socket_address, scm_from_sockaddr, scm_to_sockaddr. This - change by Ludovic Courtès and revised a bit by me. + change by Ludovic Courtès and revised a bit by me. 2005-10-27 Kevin Ryde <user42@zip.com.au> @@ -2499,3 +2519,8 @@ The change log for files in this directory continues backwards from 2001-08-27 in ../ChangeLog, as all the Guile documentation prior to this date was contained in a single directory. + + +;; Local Variables: +;; coding: utf-8 +;; End: diff --git a/doc/ref/Makefile.am b/doc/ref/Makefile.am index 76a66f0c9..7d009ff52 100644 --- a/doc/ref/Makefile.am +++ b/doc/ref/Makefile.am @@ -21,6 +21,9 @@ AUTOMAKE_OPTIONS = gnu +BUILT_SOURCES = lib-version.texi + + info_TEXINFOS = guile.texi guile_TEXINFOS = preface.texi \ @@ -86,4 +89,10 @@ autoconf.texi: autoconf-macros.texi autoconf-macros.texi: $(top_srcdir)/guile-config/guile.m4 $(preinstguiletool)/snarf-guile-m4-docs $< > $(srcdir)/$@ +lib-version.texi: $(top_srcdir)/GUILE-VERSION + cat "$^" | grep '^LIBGUILE_.*_MAJOR' | \ + sed 's/^LIBGUILE_\([A-Z0-9_]*\)_MAJOR=\([0-9]\+\)/@set LIBGUILE_\1_MAJOR \2/' \ + > "$@" + + MAINTAINERCLEANFILES = autoconf-macros.texi diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi index ccd34e38f..abcb28de1 100755 --- a/doc/ref/api-data.texi +++ b/doc/ref/api-data.texi @@ -1012,6 +1012,12 @@ zero. @rnindex number->string @rnindex string->number +The following procedures read and write numbers according to their +external representation as defined by R5RS (@pxref{Lexical structure, +R5RS Lexical Structure,, r5rs, The Revised^5 Report on the Algorithmic +Language Scheme}). @xref{The ice-9 i18n Module, the @code{(ice-9 +i18n)} module}, for locale-dependent number parsing. + @deffn {Scheme Procedure} number->string n [radix] @deffnx {C Function} scm_number_to_string (n, radix) Return a string holding the external representation of the @@ -2943,7 +2949,8 @@ predicates (@pxref{Characters}), but are defined on character sequences. The first set is specified in R5RS and has names that end in @code{?}. The second set is specified in SRFI-13 and the names have no ending @code{?}. The predicates ending in @code{-ci} ignore the character case -when comparing strings. +when comparing strings. @xref{The ice-9 i18n Module, the @code{(ice-9 +i18n)} module}, for locale-dependent string comparison. @rnindex string=? @deffn {Scheme Procedure} string=? s1 s2 diff --git a/doc/ref/api-i18n.texi b/doc/ref/api-i18n.texi index 63884254a..1927a755b 100644 --- a/doc/ref/api-i18n.texi +++ b/doc/ref/api-i18n.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -8,6 +8,292 @@ @node Internationalization @section Support for Internationalization +@cindex internationalization +@cindex i18n + +Guile provides internationalization support for Scheme programs in two +ways. First, procedures to manipulate text and data in a way that +conforms to particular cultural conventions (i.e., in a +``locale-dependent'' way) are provided in the @code{(ice-9 i18n)}. +Second, Guile allows the use of GNU @code{gettext} to translate +program message strings. + +@menu +* The ice-9 i18n Module:: Honoring cultural conventions. +* Gettext Support:: Translating message strings. +@end menu + + +@node The ice-9 i18n Module +@subsection The @code{(ice-9 i18n)} Module + +In order to make use of the following functions, one must import the +@code{(ice-9 i18n)} module in the usual way: + +@example +(use-modules (ice-9 i18n)) +@end example + +@cindex libguile-i18n-v-@value{LIBGUILE_I18N_MAJOR} + +C programs can use the C functions corresponding to the procedures of +this module by including @code{<libguile/i18n.h>} and by linking +against @code{libguile-i18n-v-@value{LIBGUILE_I18N_MAJOR}}. + +@cindex cultural conventions + +The @code{(ice-9 i18n)} module provides procedures to manipulate text +and other data in a way that conforms to the cultural conventions +chosen by the user. Each region of the world or language has its own +customs to, for instance, represent real numbers, classify characters, +collate text, etc. All these aspects comprise the so-called +``cultural conventions'' of that region or language. + +@cindex locale +@cindex locale category + +Computer systems typically refer to a set of cultural conventions as a +@dfn{locale}. For each particular aspect that comprise those cultural +conventions, a @dfn{locale category} is defined. For instance, the +way characters are classified is defined by the @code{LC_CTYPE} +category, while the language in which program messages are issued to +the user is defined by the @code{LC_MESSAGES} category +(@pxref{Locales, General Locale Information} for details). + +@cindex locale object + +The procedures provided by this module allow the development of +programs that adapt automatically to any locale setting. As we will +see later, many of the locale-dependent procedures provided by this +module can optionally take a @dfn{locale object} argument. This +additional argument defines the locale settings that must be followed +by the invoked procedure. When it is omitted, then the current locale +settings of the process are followed (@pxref{Locales, +@code{setlocale}}). + +The following procedures allow the manipulation of such locale +objects. + +@deffn {Scheme Procedure} make-locale category-mask locale-name [base-locale] +@deffnx {C Function} scm_make_locale (category_mask, locale_name, base_locale) +Return a reference to a data structure representing a set of locale +datasets. @var{locale-name} should be a string denoting a particular +locale, e.g., @code{"aa_DJ"}. Unlike for the @var{category} parameter +for @code{setlocale}, the @var{category-mask} parameter here uses a +single bit for each category, made by OR'ing together @code{LC_*_MASK} +bits. The optional @var{base-locale} argument can be used to specify +a locale object whose settings are to be used as a basis for the +locale object being returned. + +The available locale category masks are the following: + +@defvar LC_COLLATE_MASK +Represents the collation locale category. +@end defvar +@defvar LC_CTYPE_MASK +Represents the character classification locale category. +@end defvar +@defvar LC_MESSAGES_MASK +Represents the messages locale category. +@end defvar +@defvar LC_MONETARY_MASK +Represents the monetary locale category. +@end defvar +@defvar LC_NUMERIC_MASK +Represents the way numbers are displayed. +@end defvar +@defvar LC_TIME_MASK +Represents the way date and time are displayed +@end defvar + +The following category masks are also available but will not have any +effect on systems that do not support them: + +@defvar LC_PAPER_MASK +@defvarx LC_NAME_MASK +@defvarx LC_ADDRESS_MASK +@defvarx LC_TELEPHONE_MASK +@defvarx LC_MEASUREMENT_MASK +@defvarx LC_IDENTIFICATION_MASK +@end defvar + +Finally, there is also: + +@defvar LC_ALL_MASK +This represents all the locale categories supported by the system. +@end defvar + +The @code{LC_*_MASK} variables are bound to integers which may be OR'd +together using @code{logior} (@pxref{Primitive Numerics, +@code{logior}}). For instance, the following invocation creates a +locale object that combines the use of Esperanto for messages and +character classification with the default settings for the other +categories (i.e., the settings of the default @code{C} locale which +usually represents conventions in use in the USA): + +@example +(make-locale (logior LC_MESSAGE_MASK LC_CTYPE_MASK) "eo_EO") +@end example + +The following example combines the use of Swedish conventions with +monetary conventions from Croatia: + +@example +(make-locale LC_MONETARY_MASK "hr_HR" + (make-locale LC_ALL_MASK "sv_SE")) +@end example + +A @code{system-error} exception (@pxref{Handling Errors}) is raised by +@code{make-locale} when @var{locale-name} does not match any of the +locales compiled on the system. Note that on non-GNU systems, this +error may be raised later, when the locale object is actually used. + +@end deffn + +@deffn {Scheme Procedure} locale? obj +@deffnx {C Function} scm_locale_p (obj) +Return true if @var{obj} is a locale object. +@end deffn + +The following procedures provide support for text collation. + +@deffn {Scheme Procedure} string-locale<? s1 s2 [locale] +@deffnx {C Function} scm_string_locale_lt (s1, s2, locale) +Compare strings @var{s1} and @var{s2} in a locale-dependent way. If +@var{locale} is provided, it should be locale object (as returned by +@code{make-locale}) and will be used to perform the comparison; +otherwise, the current system locale is used. +@end deffn + +@deffn {Scheme Procedure} string-locale>? s1 s2 [locale] +@deffnx {C Function} scm_string_locale_gt (s1, s2, locale) +Compare strings @var{s1} and @var{s2} in a locale-dependent way. If +@var{locale} is provided, it should be locale object (as returned by +@code{make-locale}) and will be used to perform the comparison; +otherwise, the current system locale is used. +@end deffn + +@deffn {Scheme Procedure} string-locale-ci<? s1 s2 [locale] +@deffnx {C Function} scm_string_locale_ci_lt (s1, s2, locale) +Compare strings @var{s1} and @var{s2} in a case-insensitive, and +locale-dependent way. If @var{locale} is provided, it should be +locale object (as returned by @code{make-locale}) and will be used to +perform the comparison; otherwise, the current system locale is used. +@end deffn + +@deffn {Scheme Procedure} string-locale-ci>? s1 s2 [locale] +@deffnx {C Function} scm_string_locale_ci_gt (s1, s2, locale) +Compare strings @var{s1} and @var{s2} in a case-insensitive, and +locale-dependent way. If @var{locale} is provided, it should be +locale object (as returned by @code{make-locale}) and will be used to +perform the comparison; otherwise, the current system locale is used. +@end deffn + +@deffn {Scheme Procedure} string-locale-ci=? s1 s2 [locale] +@deffnx {C Function} scm_string_locale_ci_eq (s1, s2, locale) +Compare strings @var{s1} and @var{s2} in a case-insensitive, and +locale-dependent way. If @var{locale} is provided, it should be +locale object (as returned by @code{make-locale}) and will be used to +perform the comparison; otherwise, the current system locale is used. +@end deffn + +@deffn {Scheme Procedure} char-locale<? c1 c2 [locale] +@deffnx {C Function} scm_char_locale_lt (c1, c2, locale) +Return true if character @var{c1} is lower than @var{c2} according to +@var{locale} or to the current locale. +@end deffn + +@deffn {Scheme Procedure} char-locale>? c1 c2 [locale] +@deffnx {C Function} scm_char_locale_gt (c1, c2, locale) +Return true if character @var{c1} is greater than @var{c2} according +to @var{locale} or to the current locale. +@end deffn + +@deffn {Scheme Procedure} char-locale-ci<? c1 c2 [locale] +@deffnx {C Function} scm_char_locale_ci_lt (c1, c2, locale) +Return true if character @var{c1} is lower than @var{c2}, in a case +insensitive way according to @var{locale} or to the current locale. +@end deffn + +@deffn {Scheme Procedure} char-locale-ci>? c1 c2 [locale] +@deffnx {C Function} scm_char_locale_ci_gt (c1, c2, locale) +Return true if character @var{c1} is greater than @var{c2}, in a case +insensitive way according to @var{locale} or to the current locale. +@end deffn + +@deffn {Scheme Procedure} char-locale-ci=? c1 c2 [locale] +@deffnx {C Function} scm_char_locale_ci_eq (c1, c2, locale) +Return true if character @var{c1} is equal to @var{c2}, in a case +insensitive way according to @var{locale} or to the current locale. +@end deffn + +The procedures below provide support for ``character case mapping'', +i.e., to convert characters or strings to their upper-case or +lower-case equivalent. Note that SRFI-13 provides procedures that +look similar (@pxref{Alphabetic Case Mapping}). However, the SRFI-13 +procedures are locale-independent. Therefore, they do not take into +account specificities of the customs in use in a particular language +or region of the world. For instance, while most languages using the +Latin alphabet map lower-case letter ``i'' to upper-case letter ``I'', +Turkish maps lower-case ``i'' to ``Latin capital letter I with dot +above''. The following procedures allow to provide idiomatic +character mapping. + +@deffn {Scheme Procedure} char-locale-downcase chr [locale] +@deffnx {C Function} scm_char_locale_upcase (chr, locale) +Return the lowercase character that corresponds to @var{chr} according +to either @var{locale} or the current locale. +@end deffn + +@deffn {Scheme Procedure} char-locale-upcase chr [locale] +@deffnx {C Function} scm_char_locale_downcase (chr, locale) +Return the uppercase character that corresponds to @var{chr} according +to either @var{locale} or the current locale. +@end deffn + +@deffn {Scheme Procedure} string-locale-upcase str [locale] +@deffnx {C Function} scm_string_locale_upcase (str, locale) +Return a new string that is the uppercase version of @var{str} +according to either @var{locale} or the current locale. +@end deffn + +@deffn {Scheme Procedure} string-locale-downcase str [locale] +@deffnx {C Function} scm_string_locale_downcase (str, locale) +Return a new string that is the down-case version of @var{str} +according to either @var{locale} or the current locale. +@end deffn + +Finally, the following procedures allow programs to read numbers +written according to a particular locale. As an example, in English, +``ten thousand and a half'' is usually written @code{10,000.5} while +in French it is written @code{10000,5}. These procedures allow to +account for these differences. + +@deffn {Scheme Procedure} locale-string->integer str [base [locale]] +@deffnx {C Function} scm_locale_string_to_integer (str, base, locale) +Convert string @var{str} into an integer according to either +@var{locale} (a locale object as returned by @code{make-locale}) or +the current process locale. If @var{base} is specified, then it +determines the base of the integer being read (e.g., @code{16} for an +hexadecimal number, @code{10} for a decimal number); by default, +decimal numbers are read. Return two values: an integer (on success) +or @code{#f}, and the number of characters read from @var{str} +(@code{0} on failure). +@end deffn + +@deffn {Scheme Procedure} locale-string->inexact str [locale] +@deffnx {C Function} scm_locale_string_to_inexact (str, locale) +Convert string @var{str} into an inexact number according to either +@var{locale} (a locale object as returned by @code{make-locale}) or +the current process locale. Return two values: an inexact number (on +success) or @code{#f}, and the number of characters read from +@var{str} (@code{0} on failure). +@end deffn + + +@node Gettext Support +@subsection Gettext Support + Guile provides an interface to GNU @code{gettext} for translating message strings (@pxref{Introduction,,, gettext, GNU @code{gettext} utilities}). @@ -19,7 +305,8 @@ catalog filename). When @code{gettext} is not available, or if Guile was configured @samp{--without-nls}, dummy functions doing no translation are -provided. +provided. When @code{gettext} support is available in Guile, the +@code{i18n} feature is provided (@pxref{Feature Tracking}). @deffn {Scheme Procedure} gettext msg [domain [category]] @deffnx {C Function} scm_gettext (msg, domain, category) @@ -155,4 +442,5 @@ future. @c Local Variables: @c TeX-master: "guile.texi" +@c ispell-local-dictionary: "american" @c End: diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi index 992ca28c4..109a50b7f 100644 --- a/doc/ref/guile.texi +++ b/doc/ref/guile.texi @@ -7,6 +7,7 @@ @set MANUAL-EDITION 1.1 @c %**end of header @include version.texi +@include lib-version.texi @copying This reference manual documents Guile, GNU's Ubiquitous Intelligent @@ -137,7 +138,7 @@ x @comment The title is printed in a large font. @title Guile Reference Manual @subtitle Edition @value{MANUAL-EDITION}, for use with Guile @value{VERSION} -@c @subtitle $Id: guile.texi,v 1.47 2006-10-09 22:45:02 kryde Exp $ +@c @subtitle $Id: guile.texi,v 1.48 2006-11-18 18:14:55 civodul Exp $ @c See preface.texi for the list of authors @author The Guile Developers diff --git a/doc/ref/posix.texi b/doc/ref/posix.texi index 0711b9a1e..6f496fe8d 100644 --- a/doc/ref/posix.texi +++ b/doc/ref/posix.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -3139,10 +3139,11 @@ specified. Get or set the current locale, used for various internationalizations. Locales are strings, such as @samp{sv_SE}. -If @var{locale} is given then the locale for the given @var{category} is set -and the new value returned. If @var{locale} is not given then the -current value is returned. @var{category} should be one of the -following values +If @var{locale} is given then the locale for the given @var{category} +is set and the new value returned. If @var{locale} is not given then +the current value is returned. @var{category} should be one of the +following values (@pxref{Locale Categories, Categories of Activities +that Locales Affect,, libc, The GNU C Library Reference Manual}): @defvar LC_ALL @defvarx LC_COLLATE @@ -3159,6 +3160,10 @@ categories based on standard environment variables (@code{LANG} etc). For full details on categories and locale names @pxref{Locales,, Locales and Internationalization, libc, The GNU C Library Reference Manual}. + +Note that @code{setlocale} affects locale settings for the whole +process. @xref{The ice-9 i18n Module, locale objects and +@code{make-locale}}, for a thread-safe alternative. @end deffn @node Encryption |