dmbcs/guile
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve documentation of supported encoding names.

Browse source 
* 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'.
This commit is contained in:
Ludovic Courtès 2009-11-15 14:46:33 +01:00
commit 4c7b997519
2 changed files with 28 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

33
doc/ref/api-evaluation.texi
View file

@ -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

12
doc/ref/api-io.texi
View file

@ -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