*** empty log message ***

[bpt/emacs.git] / lispref / nonascii.texi

diff --git a/lispref/nonascii.texi b/lispref/nonascii.texi
index 9683156..ba001ca 100644 (file)
--- a/lispref/nonascii.texi
+++ b/lispref/nonascii.texi
@@ -1,6 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.

-@c Copyright (C) 1998, 1999 Free Software Foundation, Inc.
+@c Copyright (C) 1998, 1999, 2002, 2003, 2004,
+@c   2005, 2006 Free Software Foundation, Inc.

 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/characters
 @node Non-ASCII Characters, Searching and Matching, Text, Top
 @c See the file elisp.texi for copying conditions.
 @setfilename ../info/characters
 @node Non-ASCII Characters, Searching and Matching, Text, Top


@@ -94,7 +95,6 @@ default value to @code{nil} early in startup.
 @end defvar
 
 @defun position-bytes position
 @end defvar
 
 @defun position-bytes position

-@tindex position-bytes

 Return the byte-position corresponding to buffer position
 @var{position} in the current buffer.  This is 1 at the start of the
 buffer, and counts upward in bytes.  If @var{position} is out of
 Return the byte-position corresponding to buffer position
 @var{position} in the current buffer.  This is 1 at the start of the
 buffer, and counts upward in bytes.  If @var{position} is out of


@@ -102,7 +102,6 @@ range, the value is @code{nil}.
 @end defun
 
 @defun byte-to-position byte-position
 @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.  If @var{byte-position} is
 out of range, the value is @code{nil}.
 Return the buffer position corresponding to byte-position
 @var{byte-position} in the current buffer.  If @var{byte-position} is
 out of range, the value is @code{nil}.


@@ -353,7 +352,6 @@ valid character.
 @end defun
 
 @defun charset-plist charset
 @end defun
 
 @defun charset-plist charset

-@tindex charset-plist

 This function returns the charset property list of the character set
 @var{charset}.  Although @var{charset} is a symbol, this is not the same
 as the property list of that symbol.  Charset properties are used for
 This function returns the charset property list of the character set
 @var{charset}.  Although @var{charset} is a symbol, this is not the same
 as the property list of that symbol.  Charset properties are used for


@@ -388,7 +386,6 @@ dimension is always 1 or 2.
 @end defun
 
 @defun charset-bytes charset
 @end defun
 
 @defun charset-bytes charset

-@tindex charset-bytes

 This function returns the number of bytes used to represent a character
 in character set @var{charset}.
 @end defun
 This function returns the number of bytes used to represent a character
 in character set @var{charset}.
 @end defun


@@ -483,7 +480,7 @@ of the text in question.
 @defun charset-after &optional pos
 This function return the charset of a character in the current buffer
 at position @var{pos}.  If @var{pos} is omitted or @code{nil}, it
 @defun charset-after &optional pos
 This function return the charset of a character in the current buffer
 at position @var{pos}.  If @var{pos} is omitted or @code{nil}, it

-defauls to the current value of point.  If @var{pos} is out of range,
+defaults to the current value of point.  If @var{pos} is out of range,

 the value is @code{nil}.
 @end defun
 
 the value is @code{nil}.
 @end defun
 


@@ -577,12 +574,14 @@ coding systems that don't specify any other translation table.
 
 @defvar translation-table-for-input
 Self-inserting characters are translated through this translation
 
 @defvar translation-table-for-input
 Self-inserting characters are translated through this translation

-table before they are inserted.  This variable automatically becomes
-buffer-local when set.
+table before they are inserted.  Search commands also translate their
+input through this table, so they can compare more reliably with
+what's in the buffer.

 
 @code{set-buffer-file-coding-system} sets this variable so that your
 keyboard input gets translated into the character sets that the buffer
 
 @code{set-buffer-file-coding-system} sets this variable so that your
 keyboard input gets translated into the character sets that the buffer

-is likely to contain.
+is likely to contain.  This variable automatically becomes
+buffer-local when set.

 @end defvar
 
 @node Coding Systems
 @end defvar
 
 @node Coding Systems


@@ -716,8 +715,8 @@ operation finishes the job of choosing a coding system.  Very often
 you will want to find out afterwards which coding system was chosen.
 
 @defvar buffer-file-coding-system
 you will want to find out afterwards which coding system was chosen.
 
 @defvar buffer-file-coding-system

-This variable records the coding system that was used for visiting the
-current buffer.  It is used for saving the buffer, and for writing part
+This buffer-local variable records the coding system that was used to visit
+the current buffer.  It is used for saving the buffer, and for writing part

 of the buffer with @code{write-region}.  If the text to be written
 cannot be safely encoded using the coding system specified by this
 variable, these operations select an alternative encoding by calling
 of the buffer with @code{write-region}.  If the text to be written
 cannot be safely encoded using the coding system specified by this
 variable, these operations select an alternative encoding by calling


@@ -802,6 +801,35 @@ If that is valid, it returns @var{coding-system}.
 Otherwise it signals an error with condition @code{coding-system-error}.
 @end defun
 
 Otherwise it signals an error with condition @code{coding-system-error}.
 @end defun
 

+@cindex EOL conversion
+@cindex end-of-line conversion
+@cindex line end conversion
+@defun coding-system-eol-type coding-system
+This function returns the type of end-of-line (a.k.a.@: @dfn{eol})
+conversion used by @var{coding-system}.  If @var{coding-system}
+specifies a certain eol conversion, the return value is an integer 0,
+1, or 2, standing for @code{unix}, @code{dos}, and @code{mac},
+respectively.  If @var{coding-system} doesn't specify eol conversion
+explicitly, the return value is a vector of coding systems, each one
+with one of the possible eol conversion types, like this:
+
+@lisp
+(coding-system-eol-type 'latin-1)
+     @result{} [latin-1-unix latin-1-dos latin-1-mac]
+@end lisp
+
+@noindent
+If this function returns a vector, Emacs will decide, as part of the
+text encoding or decoding process, what eol conversion to use.  For
+decoding, the end-of-line format of the text is auto-detected, and the
+eol conversion is set to match it (e.g., DOS-style CRLF format will
+imply @code{dos} eol conversion).  For encoding, the eol conversion is
+taken from the appropriate default coding system (e.g.,
+@code{default-buffer-file-coding-system} for
+@code{buffer-file-coding-system}), or from the default eol conversion
+appropriate for the underlying platform.
+@end defun
+

 @defun coding-system-change-eol-conversion coding-system eol-type
 This function returns a coding system which is like @var{coding-system}
 except for its eol conversion, which is specified by @code{eol-type}.
 @defun coding-system-change-eol-conversion coding-system eol-type
 This function returns a coding system which is like @var{coding-system}
 except for its eol conversion, which is specified by @code{eol-type}.


@@ -854,8 +882,9 @@ decreasing priority.  But if @var{highest} is non-@code{nil}, then the
 return value is just one coding system, the one that is highest in
 priority.
 
 return value is just one coding system, the one that is highest in
 priority.
 

-If the region contains only @acronym{ASCII} characters, the value
-is @code{undecided} or @code{(undecided)}, or a variant specifying
+If the region contains only @acronym{ASCII} characters except for such
+ISO-2022 control characters ISO-2022 as @code{ESC}, the value is
+@code{undecided} or @code{(undecided)}, or a variant specifying

 end-of-line conversion, if that can be deduced from the text.
 @end defun
 
 end-of-line conversion, if that can be deduced from the text.
 @end defun
 


@@ -1071,11 +1100,11 @@ The argument @var{operation} should be a symbol, any one of
 @code{insert-file-contents}, @code{write-region},
 @code{start-process}, @code{call-process}, @code{call-process-region},
 or @code{open-network-stream}.  These are the names of the Emacs I/O
 @code{insert-file-contents}, @code{write-region},
 @code{start-process}, @code{call-process}, @code{call-process-region},
 or @code{open-network-stream}.  These are the names of the Emacs I/O

-primitives that can do coding system conversion.
+primitives that can do character code and eol conversion.

 
 The remaining arguments should be the same arguments that might be given
 
 The remaining arguments should be the same arguments that might be given

-to that I/O primitive.  Depending on the primitive, one of those
-arguments is selected as the @dfn{target}.  For example, if
+to the corresponding I/O primitive.  Depending on the primitive, one
+of those arguments is selected as the @dfn{target}.  For example, if

 @var{operation} does file I/O, whichever argument specifies the file
 name is the target.  For subprocess primitives, the process name is the
 target.  For @code{open-network-stream}, the target is the service name
 @var{operation} does file I/O, whichever argument specifies the file
 name is the target.  For subprocess primitives, the process name is the
 target.  For @code{open-network-stream}, the target is the service name


@@ -1083,7 +1112,19 @@ or port number.
 
 Depending on @var{operation}, this function looks up the target in
 @code{file-coding-system-alist}, @code{process-coding-system-alist},
 
 Depending on @var{operation}, this function looks up the target in
 @code{file-coding-system-alist}, @code{process-coding-system-alist},

-or @code{network-coding-system-alist}.
+or @code{network-coding-system-alist}.  If the target is found in the
+alist, @code{find-operation-coding-system} returns its association in
+the alist; otherwise it returns @code{nil}.
+
+If @var{operation} is @code{insert-file-contents}, the argument
+corresponding to the target may be a cons cell of the form
+@code{(@var{filename} . @var{buffer})}).  In that case, @var{filename}
+is a file name to look up in @code{file-coding-system-alist}, and
+@var{buffer} is a buffer that contains the file's contents (not yet
+decoded).  If @code{file-coding-system-alist} specifies a function to
+call for this file, and that function needs to examine the file's
+contents (as it usually does), it should examine the contents of
+@var{buffer} instead of reading the file.

 @end defun
 
 @node Specifying Coding Systems
 @end defun
 
 @node Specifying Coding Systems


@@ -1171,7 +1212,7 @@ encoding by binding @code{coding-system-for-write} to
 @code{no-conversion}.
 
   Here are the functions to perform explicit encoding or decoding.  The
 @code{no-conversion}.
 
   Here are the functions to perform explicit encoding or decoding.  The

-decoding functions produce sequences of bytes; the encoding functions
+encoding functions produce sequences of bytes; the decoding functions

 are meant to operate on sequences of bytes.  All of these functions
 discard text properties.
 
 are meant to operate on sequences of bytes.  All of these functions
 discard text properties.
 


@@ -1395,7 +1436,6 @@ to use in language-related features.  These Emacs variables control
 how Emacs interacts with these features.
 
 @defvar locale-coding-system
 how Emacs interacts with these features.
 
 @defvar locale-coding-system

-@tindex locale-coding-system

 @cindex keyboard input decoding on X
 This variable specifies the coding system to use for decoding system
 error messages and---on X Window system only---keyboard input, for
 @cindex keyboard input decoding on X
 This variable specifies the coding system to use for decoding system
 error messages and---on X Window system only---keyboard input, for


@@ -1404,7 +1444,6 @@ decoding the return value of @code{format-time-string}.
 @end defvar
 
 @defvar system-messages-locale
 @end defvar
 
 @defvar system-messages-locale

-@tindex system-messages-locale

 This variable specifies the locale to use for generating system error
 messages.  Changing the locale can cause messages to come out in a
 different language or in a different orthography.  If the variable is
 This variable specifies the locale to use for generating system error
 messages.  Changing the locale can cause messages to come out in a
 different language or in a different orthography.  If the variable is


@@ -1413,7 +1452,6 @@ usual POSIX fashion.
 @end defvar
 
 @defvar system-time-locale
 @end defvar
 
 @defvar system-time-locale

-@tindex system-time-locale

 This variable specifies the locale to use for formatting time values.
 Changing the locale can cause messages to appear according to the
 conventions of a different language.  If the variable is @code{nil}, the
 This variable specifies the locale to use for formatting time values.
 Changing the locale can cause messages to appear according to the
 conventions of a different language.  If the variable is @code{nil}, the