# HG changeset patch # User Luc Teirlinck # Date 1072323278 0 # Node ID 04d2bf306bd2dce2f0d51d2aa2194b8e61b6cc63 # Parent 4cb33bfb540c93ae4e07090363ee9bfab4f515db Various small changes in addition to the following. (Converting Representations): Clarify behavior of `string-make-multibyte' and `string-to-multibyte' for unibyte all ASCII arguments. (Character Sets): Document the variable `charset-list' and adapt the definition of the function `charset-list' accordingly. (Translation of Characters): Clarify use of generic characters in `make-translation-table'. Clarify and correct the description of the use of translation tables in encoding and decoding. (User-Chosen Coding Systems): Correct and clarify the description of `select-safe-coding-system'. (Default Coding Systems): Clarify description of `file-coding-system-alist'. diff -r 4cb33bfb540c -r 04d2bf306bd2 lispref/nonascii.texi --- a/lispref/nonascii.texi Wed Dec 24 23:32:12 2003 +0000 +++ b/lispref/nonascii.texi Thu Dec 25 03:34:38 2003 +0000 @@ -96,13 +96,15 @@ @defun position-bytes position @tindex position-bytes Return the byte-position corresponding to buffer position @var{position} -in the current buffer. +in the current buffer. If @var{position} is out of range, the value +is @code{nil}. @end defun @defun byte-to-position byte-position @tindex byte-to-position Return the buffer position corresponding to byte-position -@var{byte-position} in the current buffer. +@var{byte-position} in the current buffer. If @var{byte-position} is +out of range, the value is @code{nil}. @end defun @defun multibyte-string-p string @@ -173,6 +175,9 @@ If this is non-@code{nil}, it overrides @code{nonascii-insert-offset}. @end defvar +The next three functions either return the argument @var{string}, or a +newly created string with no text properties. + @defun string-make-unibyte string This function converts the text of @var{string} to unibyte representation, if it isn't already, and returns the result. If @@ -186,15 +191,23 @@ @defun string-make-multibyte string This function converts the text of @var{string} to multibyte representation, if it isn't already, and returns the result. If -@var{string} is a multibyte string, it is returned unchanged. -The function @code{unibyte-char-to-multibyte} is used to convert -each unibyte character to a multibyte character. +@var{string} is a multibyte string or consists entirely of +@acronym{ASCII} characters, it is returned unchanged. In particular, +if @var{string} is unibyte and entirely @acronym{ASCII}, the returned +string is unibyte. (When the characters are all @acronym{ASCII}, +Emacs primitives will treat the string the same way whether it is +unibyte or multibyte.) If @var{string} is unibyte and contains +non-@acronym{ASCII} characters, the function +@code{unibyte-char-to-multibyte} is used to convert each unibyte +character to a multibyte character. @end defun @defun string-to-multibyte string This function returns a multibyte string containing the same sequence -of character codes as @var{string}. If @var{string} is a multibyte -string, the value is the equal to @var{string}. +of character codes as @var{string}. Unlike +@code{string-make-multibyte}, this function unconditionally returns a +multibyte string. If @var{string} is a multibyte string, it is +returned unchanged. @end defun @node Selecting a Representation @@ -280,8 +293,8 @@ @end example If the optional argument @var{genericp} is non-@code{nil}, this -function returns @code{t} if @var{charcode} is a generic character -(@pxref{Splitting Characters}). +function also returns @code{t} if @var{charcode} is a generic +character (@pxref{Splitting Characters}). @end defun @node Character Sets @@ -311,13 +324,19 @@ @code{nil} otherwise. @end defun +@defvar charset-list +The value is a list of all defined character set names. +@end defvar + @defun charset-list -This function returns a list of all defined character set names. +This function returns the value of @code{charset-list}. It is only +provided for backward compatibility. @end defun @defun char-charset character This function returns the name of the character set that @var{character} -belongs to. +belongs to, or the symbol @code{unknown} if @var{character} is not a +valid character. @end defun @defun charset-plist charset @@ -378,6 +397,9 @@ identify @var{character} within that character set. The number of byte values is the character set's dimension. +If @var{character} is invalid as a character code, @code{split-char} +returns a list consisting of the symbol @code{unknown} and @var{character}. + @example (split-char 2248) @result{} (latin-iso8859-1 72) @@ -463,11 +485,11 @@ @cindex character translation tables @cindex translation tables - A @dfn{translation table} specifies a mapping of characters -into characters. These tables are used in encoding and decoding, and -for other purposes. Some coding systems specify their own particular -translation tables; there are also default translation tables which -apply to all other coding systems. + A @dfn{translation table} is a char-table that specifies a mapping +of characters into characters. These tables are used in encoding and +decoding, and for other purposes. Some coding systems specify their +own particular translation tables; there are also default translation +tables which apply to all other coding systems. @defun make-translation-table &rest translations This function returns a translation table based on the argument @@ -483,24 +505,30 @@ You can also map one whole character set into another character set with the same dimension. To do this, you specify a generic character (which designates a character set) for @var{from} (@pxref{Splitting Characters}). -In this case, @var{to} should also be a generic character, for another -character set of the same dimension. Then the translation table -translates each character of @var{from}'s character set into the -corresponding character of @var{to}'s character set. +In this case, if @var{to} is also a generic character, its character +set should have the same dimension as @var{from}'s. Then the +translation table translates each character of @var{from}'s character +set into the corresponding character of @var{to}'s character set. If +@var{from} is a generic character and @var{to} is an ordinary +character, then the translation table translates every character of +@var{from}'s character set into @var{to}. @end defun In decoding, the translation table's translations are applied to the characters that result from ordinary decoding. If a coding system has -property @code{character-translation-table-for-decode}, that specifies -the translation table to use. Otherwise, if -@code{standard-translation-table-for-decode} is non-@code{nil}, decoding -uses that table. +property @code{translation-table-for-decode}, that specifies the +translation table to use. (This is a property of the coding system, +as returned by @code{coding-system-get}, not a property of the symbol +that is the coding system's name. @xref{Coding System Basics,, Basic +Concepts of Coding Systems}.) Otherwise, if +@code{standard-translation-table-for-decode} is non-@code{nil}, +decoding uses that table. In encoding, the translation table's translations are applied to the characters in the buffer, and the result of translation is actually encoded. If a coding system has property -@code{character-translation-table-for-encode}, that specifies the -translation table to use. Otherwise the variable +@code{translation-table-for-encode}, that specifies the translation +table to use. Otherwise the variable @code{standard-translation-table-for-encode} specifies the translation table. @@ -516,7 +544,8 @@ @defvar translation-table-for-input Self-inserting characters are translated through this translation -table before they are inserted. +table before they are inserted. This variable automatically becomes +buffer-local when set. @end defvar @node Coding Systems @@ -686,7 +715,7 @@ @defun coding-system-p object This function returns @code{t} if @var{object} is a coding system -name. +name or @code{nil}. @end defun @defun check-coding-system coding-system @@ -701,6 +730,9 @@ @var{eol-type} should be @code{unix}, @code{dos}, @code{mac}, or @code{nil}. If it is @code{nil}, the returned coding system determines the end-of-line conversion from the data. + +@var{eol-type} may also be 0, 1 or 2, standing for @code{unix}, +@code{dos} and @code{mac}, respectively. @end defun @defun coding-system-change-text-conversion eol-coding text-coding @@ -745,55 +777,79 @@ priority. If the region contains only @acronym{ASCII} characters, the value -is @code{undecided} or @code{(undecided)}. +is @code{undecided} or @code{(undecided)}, or a variant specifying +end-of-line conversion, if that can be deduced from the text. @end defun -@defun detect-coding-string string highest +@defun detect-coding-string string &optional highest This function is like @code{detect-coding-region} except that it operates on the contents of @var{string} instead of bytes in the buffer. @end defun - @xref{Process Information}, for how to examine or set the coding -systems used for I/O to a subprocess. + @xref{Coding systems for a subprocess,, Process Information}, in +particular the description of the functions +@code{process-coding-system} and @code{set-process-coding-system}, for +how to examine or set the coding systems used for I/O to a subprocess. @node User-Chosen Coding Systems @subsection User-Chosen Coding Systems @cindex select safe coding system -@defun select-safe-coding-system from to &optional default-coding-system accept-default-p +@defun select-safe-coding-system from to &optional default-coding-system accept-default-p file This function selects a coding system for encoding specified text, asking the user to choose if necessary. Normally the specified text -is the text in the current buffer between @var{from} and @var{to}, -defaulting to the whole buffer if they are @code{nil}. If @var{from} -is a string, the string specifies the text to encode, and @var{to} is -ignored. +is the text in the current buffer between @var{from} and @var{to}. If +@var{from} is a string, the string specifies the text to encode, and +@var{to} is ignored. If @var{default-coding-system} is non-@code{nil}, that is the first coding system to try; if that can handle the text, @code{select-safe-coding-system} returns that coding system. It can also be a list of coding systems; then the function tries each of them -one by one. After trying all of them, it next tries the user's most -preferred coding system (@pxref{Recognize Coding, -prefer-coding-system, the description of @code{prefer-coding-system}, -emacs, GNU Emacs Manual}), and after that the current buffer's value -of @code{buffer-file-coding-system} (if it is not @code{undecided}). +one by one. After trying all of them, it next tries the current +buffer's value of @code{buffer-file-coding-system} (if it is not +@code{undecided}), then the value of +@code{default-buffer-file-coding-system} and finally the user's most +preferred coding system, which the user can set using the command +@code{prefer-coding-system} (@pxref{Recognize Coding,, Recognizing +Coding Systems, emacs, The GNU Emacs Manual}). If one of those coding systems can safely encode all the specified text, @code{select-safe-coding-system} chooses it and returns it. Otherwise, it asks the user to choose from a list of coding systems which can encode all the text, and returns the user's choice. +@var{default-coding-system} can also be a list whose first element is +t and whose other elements are coding systems. Then, if no coding +system in the list can handle the text, @code{select-safe-coding-system} +queries the user immediately, without trying any of the three +alternatives described above. + The optional argument @var{accept-default-p}, if non-@code{nil}, -should be a function to determine whether the coding system selected -without user interaction is acceptable. If this function returns -@code{nil}, the silently selected coding system is rejected, and the -user is asked to select a coding system from a list of possible -candidates. +should be a function to determine whether a coding system selected +without user interaction is acceptable. @code{select-safe-coding-system} +calls this function with one argument, the base coding system of the +selected coding system. If @var{accept-default-p} returns @code{nil}, +@code{select-safe-coding-system} rejects the silently selected coding +system, and asks the user to select a coding system from a list of +possible candidates. @vindex select-safe-coding-system-accept-default-p If the variable @code{select-safe-coding-system-accept-default-p} is non-@code{nil}, its value overrides the value of @var{accept-default-p}. + +As a final step, before returning the chosen coding system, +@code{select-safe-coding-system} checks whether that coding system is +consistent with what would be selected if the contents of the region +were read from a file. (If not, this could lead to data corruption in +a file subsequently re-visited and edited.) Normally, +@code{select-safe-coding-system} uses @code{buffer-file-name} as the +file for this purpose, but if @var{file} is non-@code{nil}, it uses +that file instead (this can be relevant for @code{write-region} and +similar functions). If it detects an apparent inconsistency, +@code{select-safe-coding-system} queries the user before selecting the +coding system. @end defun Here are two functions you can use to let the user specify a coding @@ -846,17 +902,19 @@ expression that matches certain file names. The element applies to file names that match @var{pattern}. -The @acronym{CDR} of the element, @var{coding}, should be either a coding +The @sc{cdr} of the element, @var{coding}, should be either a coding system, a cons cell containing two coding systems, or a function name (a symbol with a function definition). If @var{coding} is a coding system, that coding system is used for both reading the file and writing it. If -@var{coding} is a cons cell containing two coding systems, its @acronym{CAR} -specifies the coding system for decoding, and its @acronym{cdr} specifies the +@var{coding} is a cons cell containing two coding systems, its @sc{car} +specifies the coding system for decoding, and its @sc{cdr} specifies the coding system for encoding. -If @var{coding} is a function name, the function must return a coding -system or a cons cell containing two coding systems. This value is used -as described above. +If @var{coding} is a function name, the function should take one +argument, a list of all arguments passed to +@code{find-operation-coding-system}. It must return a coding system +or a cons cell containing two coding systems. This value has the same +meaning as described above. @end defvar @defvar process-coding-system-alist @@ -923,7 +981,7 @@ form: @example -(@var{decoding-system} @var{encoding-system}) +(@var{decoding-system} . @var{encoding-system}) @end example The first element, @var{decoding-system}, is the coding system to use @@ -948,7 +1006,6 @@ This function looks up the target in @code{file-coding-system-alist}, @code{process-coding-system-alist}, or @code{network-coding-system-alist}, depending on @var{operation}. -@xref{Default Coding Systems}. @end defun @node Specifying Coding Systems @@ -1040,33 +1097,41 @@ are meant to operate on sequences of bytes. All of these functions discard text properties. -@defun encode-coding-region start end coding-system -This function encodes the text from @var{start} to @var{end} according +@deffn Command encode-coding-region start end coding-system +This command encodes the text from @var{start} to @var{end} according to coding system @var{coding-system}. The encoded text replaces the original text in the buffer. The result of encoding is logically a sequence of bytes, but the buffer remains multibyte if it was multibyte before. -@end defun -@defun encode-coding-string string coding-system +This command returns the length of the encoded text. +@end deffn + +@defun encode-coding-string string coding-system &optional nocopy This function encodes the text in @var{string} according to coding system @var{coding-system}. It returns a new string containing the -encoded text. The result of encoding is a unibyte string. +encoded text, except when @var{nocopy} is non-@code{nil}, in which +case the function may return @var{string} itself if the encoding +operation is trivial. The result of encoding is a unibyte string. @end defun -@defun decode-coding-region start end coding-system -This function decodes the text from @var{start} to @var{end} according +@deffn Command decode-coding-region start end coding-system +This command decodes the text from @var{start} to @var{end} according to coding system @var{coding-system}. The decoded text replaces the original text in the buffer. To make explicit decoding useful, the text before decoding ought to be a sequence of byte values, but both multibyte and unibyte buffers are acceptable. -@end defun -@defun decode-coding-string string coding-system +This command returns the length of the decoded text. +@end deffn + +@defun decode-coding-string string coding-system &optional nocopy This function decodes the text in @var{string} according to coding system @var{coding-system}. It returns a new string containing the -decoded text. To make explicit decoding useful, the contents of -@var{string} ought to be a sequence of byte values, but a multibyte +decoded text, except when @var{nocopy} is non-@code{nil}, in which +case the function may return @var{string} itself if the decoding +operation is trivial. To make explicit decoding useful, the contents +of @var{string} ought to be a sequence of byte values, but a multibyte string is acceptable. @end defun @@ -1095,22 +1160,22 @@ keyboard input---or @code{nil} if no coding system is to be used. @end defun -@defun set-keyboard-coding-system coding-system -This function specifies @var{coding-system} as the coding system to +@deffn Command set-keyboard-coding-system coding-system +This command specifies @var{coding-system} as the coding system to use for decoding keyboard input. If @var{coding-system} is @code{nil}, that means do not decode keyboard input. -@end defun +@end deffn @defun terminal-coding-system This function returns the coding system that is in use for encoding terminal output---or @code{nil} for no encoding. @end defun -@defun set-terminal-coding-system coding-system -This function specifies @var{coding-system} as the coding system to use +@deffn Command set-terminal-coding-system coding-system +This command specifies @var{coding-system} as the coding system to use for encoding terminal output. If @var{coding-system} is @code{nil}, that means do not encode terminal output. -@end defun +@end deffn @node MS-DOS File Types @subsection MS-DOS File Types @@ -1193,18 +1258,18 @@ buffer now. @end defvar -@defvar default-input-method +@defopt default-input-method This variable holds the default input method for commands that choose an input method. Unlike @code{current-input-method}, this variable is normally global. -@end defvar +@end defopt -@defun set-input-method input-method -This function activates input method @var{input-method} for the current +@deffn Command set-input-method input-method +This command activates input method @var{input-method} for the current buffer. It also sets @code{default-input-method} to @var{input-method}. -If @var{input-method} is @code{nil}, this function deactivates any input +If @var{input-method} is @code{nil}, this command deactivates any input method for the current buffer. -@end defun +@end deffn @defun read-input-method-name prompt &optional default inhibit-null This function reads an input method name with the minibuffer, prompting @@ -1240,7 +1305,8 @@ @end defvar The fundamental interface to input methods is through the -variable @code{input-method-function}. @xref{Reading One Event}. +variable @code{input-method-function}. @xref{Reading One Event}, +and @ref{Invoking the Input Method}. @node Locales @section Locales @@ -1294,14 +1360,14 @@ @item paper Return a list @code{(@var{width} @var{height})} for the default paper -size measured in milimeters (locale items @code{PAPER_WIDTH} and +size measured in millimeters (locale items @code{PAPER_WIDTH} and @code{PAPER_HEIGHT}). @end table If the system can't provide the requested information, or if @var{item} is not one of those symbols, the value is @code{nil}. All strings in the return value are decoded using -@code{locale-coding-system}. @xref{Locales,,, libc, GNU Libc Manual}, +@code{locale-coding-system}. @xref{Locales,,, libc, The GNU Libc Manual}, for more information about locales and locale items. @end defun