diff options
author | Ludovic Courtès <ludo@gnu.org> | 2009-11-15 14:46:33 +0100 |
---|---|---|
committer | Ludovic Courtès <ludo@gnu.org> | 2009-11-16 09:23:45 +0100 |
commit | 4c7b997519050243fa5474b03f8164da03be04d8 (patch) | |
tree | 2c094729171859285c3b1763dbd88d9b1eeeb497 | |
parent | b9fd657add26c7936fdfda80fc382630181cb113 (diff) | |
download | guile-4c7b997519050243fa5474b03f8164da03be04d8.tar.gz |
Improve documentation of supported encoding names.
* doc/ref/api-evaluation.texi (Character Encoding of Source Files):
Mention IANA as the list of supported character encodings. Thanks to
Bruno Haible for pointing this out.
* doc/ref/api-io.texi (Ports): Likewise. Improve documentation of
`%default-port-encoding'.
-rw-r--r-- | doc/ref/api-evaluation.texi | 33 | ||||
-rw-r--r-- | doc/ref/api-io.texi | 12 |
2 files changed, 28 insertions, 17 deletions
diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi index cd5a6588a..c2c3a4ab5 100644 --- a/doc/ref/api-evaluation.texi +++ b/doc/ref/api-evaluation.texi @@ -637,6 +637,7 @@ list @code{("" ".scm")}. @node Character Encoding of Source Files @subsection Character Encoding of Source Files +@cindex source file encoding @cindex primitive-load @cindex load Scheme source code files are usually encoded in ASCII, but, the @@ -652,10 +653,19 @@ scheme comment. It can either be a semicolon-initiated comment or a block @code{#!} comment. The name of the character encoding in the coding declaration is -typically lower case and containing only letters, numbers, and -hyphens. The most common examples of character encodings are -@code{utf-8} and @code{iso-8859-1}. This allows the coding -declaration to be compatible with EMACS. +typically lower case and containing only letters, numbers, and hyphens, +as recognized by @code{set-port-encoding!} (@pxref{Ports, +@code{set-port-encoding!}}). Common examples of character encoding +names are @code{utf-8} and @code{iso-8859-1}, +@url{http://www.iana.org/assignments/character-sets, as defined by +IANA}. Thus, the coding declaration is mostly compatible with Emacs. + +However, there are some differences in encoding names recognized by +Emacs and encoding names defined by IANA, the latter being essentially a +subset of the former. For instance, @code{latin-1} is a valid encoding +name for Emacs, but it's not according to the IANA standard, which Guile +follows; instead, you should use @code{latin1}, which is both understood +by Emacs and dubbed by IANA. For source code, only a subset of all possible character encodings can be interpreted by the built-in source code reader. Only those @@ -690,14 +700,13 @@ by @code{file-encoding}, if any, again by using @deffn {Scheme Procedure} file-encoding port @deffnx {C Function} scm_file_encoding port -Scans the port for an EMACS-like character coding declaration near the -top of the contents of a port with random-accessible contents. The -coding declaration is of the form @code{coding: XXXXX} and must appear -in a scheme comment. - -Returns a string containing the character encoding of the file -if a declaration was found, or @code{#f} otherwise. The port is -rewound. +Scan the port for an Emacs-like character coding declaration near the +top of the contents of a port with random-accessible contents +(@pxref{Recognize Coding, how Emacs recognizes file encoding,, emacs, +The GNU Emacs Reference Manual}). The coding declaration is of the form +@code{coding: XXXXX} and must appear in a Scheme comment. Return a +string containing the character encoding of the file if a declaration +was found, or @code{#f} otherwise. The port is rewound. @end deffn diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi index a5ffa2319..b64ff6719 100644 --- a/doc/ref/api-io.texi +++ b/doc/ref/api-io.texi @@ -107,19 +107,21 @@ Equivalent to @code{(or (input-port? @var{x}) (output-port? @deffn {Scheme Procedure} set-port-encoding! port enc @deffnx {C Function} scm_set_port_encoding_x (port, enc) -Sets the character encoding that will be used to interpret all port -I/O. @var{enc} is a string containing the name of an encoding. +Sets the character encoding that will be used to interpret all port I/O. +@var{enc} is a string containing the name of an encoding. Valid +encoding names are those +@url{http://www.iana.org/assignments/character-sets, defined by IANA}. @end deffn @defvr {Scheme Variable} %default-port-encoding A fluid containing containing @code{#f} or the name of the encoding to be used by default for newly created ports (@pxref{Fluids and Dynamic States}). The value @code{#f} is equivalent to @code{"ISO-8859-1"}. -@end defvr New ports are created with the encoding appropriate for the current -locale if @code{setlocale} has been called or ISO-8859-1 otherwise, -and this procedure can be used to modify that encoding. +locale if @code{setlocale} has been called or the value specified by +this fluid otherwise. +@end defvr @deffn {Scheme Procedure} port-encoding port @deffnx {C Function} scm_port_encoding |