[Emacs-diffs] emacs/doc/lispref nonascii.texi

[Eli Zaretskii]

CVSROOT:        /cvsroot/emacs
Module name:    emacs
Changes by:     Eli Zaretskii <eliz>    09/05/09 09:09:33

Modified files:
        doc/lispref    : nonascii.texi 

Log message:
        (Default Coding Systems): Document find-auto-coding, set-auto-coding, 
and
        auto-coding-alist.  Add indexing.
        (Lisp and Coding Systems): Add index entries.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/nonascii.texi?cvsroot=emacs&r1=1.24&r2=1.25

Patches:
Index: nonascii.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/doc/lispref/nonascii.texi,v
retrieving revision 1.24
retrieving revision 1.25
diff -u -b -r1.24 -r1.25
--- nonascii.texi       10 Apr 2009 01:16:28 -0000      1.24
+++ nonascii.texi       9 May 2009 09:09:32 -0000       1.25
@@ -1001,6 +1001,7 @@
 
   Here are the Lisp facilities for working with coding systems:
 
address@hidden list all coding systems
 @defun coding-system-list &optional base-only
 This function returns a list of all coding system names (symbols).  If
 @var{base-only} is address@hidden, the value includes only the
@@ -1013,6 +1014,8 @@
 name or @code{nil}.
 @end defun
 
address@hidden validity of coding system
address@hidden coding system, validity check
 @defun check-coding-system coding-system
 This function checks the validity of @var{coding-system}.  If that is
 valid, it returns @var{coding-system}.  If @var{coding-system} is
@@ -1021,6 +1024,7 @@
 (@pxref{Signaling Errors, signal}).
 @end defun
 
address@hidden eol type of coding system
 @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}
@@ -1047,6 +1051,7 @@
 appropriate for the underlying platform.
 @end defun
 
address@hidden eol conversion of coding system
 @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}.
@@ -1058,6 +1063,7 @@
 @code{dos} and @code{mac}, respectively.
 @end defun
 
address@hidden text conversion of coding system
 @defun coding-system-change-text-conversion eol-coding text-coding
 This function returns a coding system which uses the end-of-line
 conversion of @var{eol-coding}, and the text conversion of
@@ -1065,6 +1071,8 @@
 @code{undecided}, or one of its variants according to @var{eol-coding}.
 @end defun
 
address@hidden safely encode region
address@hidden coding systems for encoding region
 @defun find-coding-systems-region from to
 This function returns a list of coding systems that could be used to
 encode a text between @var{from} and @var{to}.  All coding systems in
@@ -1075,6 +1083,8 @@
 list @code{(undecided)}.
 @end defun
 
address@hidden safely encode a string
address@hidden coding systems for encoding a string
 @defun find-coding-systems-string string
 This function returns a list of coding systems that could be used to
 encode the text of @var{string}.  All coding systems in the list can
@@ -1083,6 +1093,8 @@
 @code{(undecided)}.
 @end defun
 
address@hidden charset, coding systems to encode
address@hidden safely encode characters in a charset
 @defun find-coding-systems-for-charsets charsets
 This function returns a list of coding systems that could be used to
 encode all the character sets in the list @var{charsets}.
@@ -1130,6 +1142,7 @@
 operates on the contents of @var{string} instead of bytes in the buffer.
 @end defun
 
address@hidden null bytes, and decoding text
 @defvar inhibit-null-byte-detection
 If this variable has a address@hidden value, null bytes are ignored
 when detecting the encoding of a region or a string.  This allows to
@@ -1146,6 +1159,7 @@
 because many files in the Emacs distribution use ISO-2022 encoding.}
 @end defvar
 
address@hidden charsets supported by a coding system
 @defun coding-system-charset-list coding-system
 This function returns the list of character sets (@pxref{Character
 Sets}) supported by @var{coding-system}.  Some coding systems that
@@ -1255,6 +1269,8 @@
 
 @node Default Coding Systems
 @subsection Default Coding Systems
address@hidden default coding system
address@hidden coding system, automatically determined
 
   This section describes variables that specify the default coding
 system for certain files or when running certain subprograms, and the
@@ -1267,6 +1283,7 @@
 @code{coding-system-for-read} and @code{coding-system-for-write}
 (@pxref{Specifying Coding Systems}).
 
address@hidden file contents, and default coding system
 @defvar auto-coding-regexp-alist
 This variable is an alist of text patterns and corresponding coding
 systems. Each element has the form @code{(@var{regexp}
@@ -1279,6 +1296,7 @@
 reads them with no code conversions.
 @end defvar
 
address@hidden file name, and default coding system
 @defvar file-coding-system-alist
 This variable is an alist that specifies the coding systems to use for
 reading and writing particular files.  Each element has the form
@@ -1304,6 +1322,14 @@
 @code{undecided}, the normal code-detection is performed.
 @end defvar
 
address@hidden auto-coding-alist
+This variable is an alist that specifies the coding systems to use for
+reading and writing particular files.  Its form is like that of
address@hidden, but, unlike the latter, this variable
+takes priority over any @code{coding:} tags in the file.
address@hidden defvar
+
address@hidden program name, and default coding system
 @defvar process-coding-system-alist
 This variable is an alist specifying which coding systems to use for a
 subprocess, depending on which program is running in the subprocess.  It
@@ -1327,6 +1353,8 @@
 the end of line conversion---that is, one like @code{latin-1-unix},
 rather than @code{undecided} or @code{latin-1}.
 
address@hidden port number, and default coding system
address@hidden network service name, and default coding system
 @defvar network-coding-system-alist
 This variable is an alist that specifies the coding system to use for
 network streams.  It works much like @code{file-coding-system-alist},
@@ -1346,6 +1374,7 @@
 the subprocess, and @var{output-coding} applies to output to it.
 @end defvar
 
address@hidden default coding system, functions to determine
 @defvar auto-coding-functions
 This variable holds a list of functions that try to determine a
 coding system for a file based on its undecoded contents.
@@ -1362,6 +1391,39 @@
 functions won't be called.
 @end defvar
 
address@hidden find-auto-coding filename size
+This function tries to determine a suitable coding system for
address@hidden  It examines the buffer visiting the named file, using
+the variables documented above in sequence, until it finds a match for
+one of the rules specified by these variables.  It then returns a cons
+cell of the form @code{(@var{coding} . @var{source})}, where
address@hidden is the coding system to use and @var{source} is a symbol,
+one of @code{auto-coding-alist}, @code{auto-coding-regexp-alist},
address@hidden:coding}, or @code{auto-coding-functions}, indicating which one
+supplied the matching rule.  The value @code{:coding} means the coding
+system was specified by the @code{coding:} tag in the file
+(@pxref{Specify Coding,, coding tag, emacs, The GNU Emacs Manual}).
+The order of looking for a matching rule is @code{auto-coding-alist}
+first, then @code{auto-coding-regexp-alist}, then the @code{coding:}
+tag, and lastly @code{auto-coding-functions}.  If no matching rule was
+found, the function returns @code{nil}.
+
+The second argument @var{size} is the size of text, in characters,
+following point.  The function examines text only within @var{size}
+characters after point.  Normally, the buffer should be positioned at
+the beginning when this function is called, because one of the places
+for the @code{coding:} tag is the first one or two lines of the file;
+in that case, @var{size} should be the size of the buffer.
address@hidden defun
+
address@hidden set-auto-coding filename size
+This function returns a suitable coding system for file
address@hidden  It uses @code{find-auto-coding} to find the coding
+system.  If no coding system could be determined, the function returns
address@hidden  The meaning of the argument @var{size} is like in
address@hidden
address@hidden defun
+
 @defun find-operation-coding-system operation &rest arguments
 This function returns the coding system to use (by default) for
 performing @var{operation} with @var{arguments}.  The value has this