Mercurial > hg > xemacs-beta
annotate man/lispref/internationalization.texi @ 5714:489e76b85828
When an error is encountered while converting a Lisp menu specification
to its internal form, don't fail an assert(). Instead, return 0 to skip
the fault menu and show any errors in *Warnings*.
| author | Jerry James <james@xemacs.org> |
|---|---|
| date | Mon, 21 Jan 2013 10:17:55 -0700 |
| parents | a46c5c8d6564 |
| children | 9fae6227ede5 |
| rev | line source |
|---|---|
| 428 | 1 @c -*-texinfo-*- |
| 2 @c This is part of the XEmacs Lisp Reference Manual. | |
| 444 | 3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. |
| 428 | 4 @c See the file lispref.texi for copying conditions. |
| 5 @setfilename ../../info/internationalization.info | |
| 442 | 6 @node Internationalization, MULE, PostgreSQL Support, top |
| 428 | 7 @chapter Internationalization |
| 8 | |
| 9 @menu | |
| 10 * I18N Levels 1 and 2:: Support for different time, date, and currency formats. | |
| 11 * I18N Level 3:: Support for localized messages. | |
| 12 * I18N Level 4:: Support for Asian languages. | |
| 13 @end menu | |
| 14 | |
| 15 | |
| 16 @node I18N Levels 1 and 2 | |
| 17 @section I18N Levels 1 and 2 | |
| 18 | |
| 19 XEmacs is now compliant with I18N levels 1 and 2. Specifically, this means | |
| 20 that it is 8-bit clean and correctly handles time and date functions. XEmacs | |
| 21 will correctly display the entire ISO-Latin 1 character set. | |
| 22 | |
| 23 The compose key may now be used to create any character in the ISO-Latin 1 | |
| 24 character set not directly available via the keyboard.. In order for the | |
| 25 compose key to work it is necessary to load the file @file{x-compose.el}. | |
| 26 At any time while composing a character, @code{C-h} will display all valid | |
| 27 completions and the character which would be produced. | |
| 28 | |
| 29 | |
| 30 @node I18N Level 3 | |
| 31 @section I18N Level 3 | |
| 32 | |
| 33 @menu | |
| 34 * Level 3 Basics:: | |
| 35 * Level 3 Primitives:: | |
| 36 * Dynamic Messaging:: | |
| 37 * Domain Specification:: | |
| 38 @end menu | |
| 39 | |
| 40 @node Level 3 Basics | |
| 41 @subsection Level 3 Basics | |
| 42 | |
| 43 XEmacs now provides alpha-level functionality for I18N Level 3. This means | |
| 44 that everything necessary for full messaging is available, but not every | |
| 45 file has been converted. | |
| 46 | |
| 47 The two message files which have been created are @file{src/emacs.po} and | |
| 48 @file{lisp/packages/mh-e.po}. Both files need to be converted using | |
| 49 @code{msgfmt}, and the resulting @file{.mo} files placed in some locale's | |
| 50 @code{LC_MESSAGES} directory. The test ``translations'' in these files are | |
| 51 the original messages prefixed by @code{TRNSLT_}. | |
| 52 | |
| 53 The domain for a variable is stored on the variable's property list under | |
| 54 the property name @var{variable-domain}. The function | |
| 55 @code{documentation-property} uses this information when translating a | |
| 56 variable's documentation. | |
| 57 | |
| 58 | |
| 59 @node Level 3 Primitives | |
| 60 @subsection Level 3 Primitives | |
| 61 | |
| 62 @defun gettext string | |
| 63 This function looks up @var{string} in the default message domain and | |
| 64 returns its translation. If @code{I18N3} was not enabled when XEmacs was | |
| 65 compiled, it just returns @var{string}. | |
| 66 @end defun | |
| 67 | |
| 68 @defun dgettext domain string | |
| 69 This function looks up @var{string} in the specified message domain and | |
| 70 returns its translation. If @code{I18N3} was not enabled when XEmacs was | |
| 71 compiled, it just returns @var{string}. | |
| 72 @end defun | |
| 73 | |
| 74 @defun bind-text-domain domain pathname | |
| 75 This function associates a pathname with a message domain. | |
| 76 Here's how the path to message file is constructed under SunOS 5.x: | |
| 77 | |
| 78 @example | |
| 79 @code{@{pathname@}/@{LANG@}/LC_MESSAGES/@{domain@}.mo} | |
| 80 @end example | |
| 81 | |
| 82 If @code{I18N3} was not enabled when XEmacs was compiled, this function does | |
| 83 nothing. | |
| 84 @end defun | |
| 85 | |
|
5547
a46c5c8d6564
Avoid calling various macros "special operators" in the manuals.
Aidan Kehoe <kehoea@parhasard.net>
parents:
5361
diff
changeset
|
86 @defmac domain string |
|
a46c5c8d6564
Avoid calling various macros "special operators" in the manuals.
Aidan Kehoe <kehoea@parhasard.net>
parents:
5361
diff
changeset
|
87 This macro specifies the text domain used for translating documentation |
| 428 | 88 strings and interactive prompts of a function. For example, write: |
| 89 | |
| 90 @example | |
| 91 (defun foo (arg) "Doc string" (domain "emacs-foo") @dots{}) | |
| 92 @end example | |
| 93 | |
| 94 to specify @code{emacs-foo} as the text domain of the function @code{foo}. | |
| 95 The ``call'' to @code{domain} is actually a declaration rather than a | |
| 96 function; when actually called, @code{domain} just returns @code{nil}. | |
|
5547
a46c5c8d6564
Avoid calling various macros "special operators" in the manuals.
Aidan Kehoe <kehoea@parhasard.net>
parents:
5361
diff
changeset
|
97 @end defmac |
| 428 | 98 |
| 99 @defun domain-of function | |
| 100 This function returns the text domain of @var{function}; it returns | |
| 101 @code{nil} if it is the default domain. If @code{I18N3} was not enabled | |
| 102 when XEmacs was compiled, it always returns @code{nil}. | |
| 103 @end defun | |
| 104 | |
| 105 | |
| 106 @node Dynamic Messaging | |
| 107 @subsection Dynamic Messaging | |
| 108 | |
| 109 The @code{format} function has been extended to permit you to change the | |
| 110 order of parameter insertion. For example, the conversion format | |
| 111 @code{%1$s} inserts parameter one as a string, while @code{%2$s} inserts | |
| 112 parameter two. This is useful when creating translations which require you | |
| 113 to change the word order. | |
| 114 | |
| 115 | |
| 116 @node Domain Specification | |
| 117 @subsection Domain Specification | |
| 118 | |
| 119 The default message domain of XEmacs is `emacs'. For add-on packages, it is | |
| 120 best to use a different domain. For example, let us say we want to convert | |
| 121 the ``gorilla'' package to use the domain `emacs-gorilla'. | |
| 122 To translate the message ``What gorilla?'', use @code{dgettext} as follows: | |
| 123 | |
| 124 @example | |
| 125 (dgettext "emacs-gorilla" "What gorilla?") | |
| 126 @end example | |
| 127 | |
| 128 A function (or macro) which has a documentation string or an interactive | |
| 129 prompt needs to be associated with the domain in order for the documentation | |
| 130 or prompt to be translated. This is done with the @code{domain} special | |
| 131 form as follows: | |
| 132 | |
| 133 @page | |
| 134 @example | |
| 135 (defun scratch (location) | |
| 136 "Scratch the specified location." | |
| 137 (domain "emacs-gorilla") | |
| 138 (interactive "sScratch: ") | |
| 139 @dots{} ) | |
| 140 @end example | |
| 141 | |
| 142 It is most efficient to specify the domain in the first line of the | |
| 143 function body, before the @code{interactive} form. | |
| 144 | |
| 145 For variables and constants which have documentation strings, specify the | |
| 146 domain after the documentation. | |
| 147 | |
|
5361
62b9ef1ed4ac
Change "special form" to "special operator" in the manuals, too
Aidan Kehoe <kehoea@parhasard.net>
parents:
4894
diff
changeset
|
148 @deffn {Special Operator} defvar symbol [value [doc-string [domain]]] |
| 428 | 149 Example: |
| 150 @example | |
| 151 (defvar weight 250 "Weight of gorilla, in pounds." "emacs-gorilla") | |
| 152 @end example | |
|
5361
62b9ef1ed4ac
Change "special form" to "special operator" in the manuals, too
Aidan Kehoe <kehoea@parhasard.net>
parents:
4894
diff
changeset
|
153 @end deffn |
| 428 | 154 |
|
5361
62b9ef1ed4ac
Change "special form" to "special operator" in the manuals, too
Aidan Kehoe <kehoea@parhasard.net>
parents:
4894
diff
changeset
|
155 @deffn {Special Operator} defconst symbol [value [doc-string [domain]]] |
| 428 | 156 Example: |
| 157 @example | |
| 158 (defconst limbs 4 "Number of limbs" "emacs-gorilla") | |
| 159 @end example | |
|
5361
62b9ef1ed4ac
Change "special form" to "special operator" in the manuals, too
Aidan Kehoe <kehoea@parhasard.net>
parents:
4894
diff
changeset
|
160 @end deffn |
| 428 | 161 |
| 444 | 162 @defun autoload function filename &optional docstring interactive type |
| 163 This function defines @var{function} to autoload from @var{filename} | |
| 428 | 164 Example: |
| 165 @example | |
| 166 (autoload 'explore "jungle" "Explore the jungle." nil nil "emacs-gorilla") | |
| 167 @end example | |
| 168 @end defun | |
| 169 | |
| 170 @node I18N Level 4 | |
| 171 @section I18N Level 4 | |
| 172 | |
| 173 The Asian-language support in XEmacs is called ``MULE''. @xref{MULE}. |