code:
@c This is part of the Emacs manual.
@c Copyright (C) 1997 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Mule, Major Modes, Windows, Top
@chapter World Scripts Support
@cindex MULE
@cindex international scripts
@cindex multibyte characters
@cindex encoding of characters

@cindex Chinese
@cindex Greek
@cindex IPA
@cindex Japanese
@cindex Korean
@cindex Cyrillic
@cindex Russian
  If you compile XEmacs with Mule option, it supports a wide variety of
world scripts, including Latin script, as well as Arabic script,
Simplified Chinese script (for mainland of China), Traditional Chinese
script (for Taiwan and Hong-Kong), Greek script, Hebrew script, IPA
symbols, Japanese scripts (Hiragana, Katakana and Kanji), Korean scripts
(Hangul and Hanja) and Cyrillic script (for Byelorussian, Bulgarian,
Russian, Serbian and Ukrainian).  These features have been merged from
the modified version of Emacs known as MULE (for ``MULti-lingual
Enhancement to GNU Emacs'').

@menu
* Mule Intro::              Basic concepts of Mule.
* Language Environments::   Setting things up for the language you use.
* Input Methods::           Entering text characters not on your keyboard.
* Select Input Method::     Specifying your choice of input methods.
* Mule and Fonts::          Additional font-related issues
* Coding Systems::          Character set conversion when you read and
                              write files, and so on.
* Recognize Coding::        How XEmacs figures out which conversion to use.
* Specify Coding::          Various ways to choose which conversion to use.
@end menu

@node Mule Intro, Language Environments, Mule, Mule
@section What is Mule?

Mule is the MUltiLingual Extension to XEmacs.  It provides facilities
not only for handling text written in many different languages, but in
fact multilingual texts containing several languages in the same buffer.
This goes beyond the simple facilities offered by Unicode for
representation of multilingual text.  Mule also supports input methods,
composing display using fonts in various different encodings, changing
character syntax and other editing facilities to correspond to local
language usage, and more.

The most obvious problem is that of the different character coding
systems used by different languages.  ASCII supplies all the characters
needed for most computer programming languages and US English (it lacks
the currency symbol for British English), but other Western European
languages (French, Spanish, German) require more than 96 code positions
for accented characters.  In fact, even with 8 bits to represent 96 more
character (including accented characters and symbols such as currency
symbols), some languages' alphabets remain incomplete (Croatian,
Polish).  (The 64 "missing characters" are reserved for control
characters.)  Furthermore, many European languages have their own
alphabets, which must conflict with the accented characters since the
ASCII characters are needed for computer interaction (error and log
messages are typically in ASCII).

For economy of space, historical practice has been for each language to
establish its own encoding for the characters it needs.  This allows
most European languages to represented with one octet (byte) per
character.  However, many Asian languages have thousands of characters
and require two or more octets per character.  For multilingual
purposes, the ISO 2022 standard establishes escape codes that allow
switching encodings in midstream.  (It's also ISO 2022 that establishes
the standard that code points 0-31 and 128-159 are control codes.)

However, this is error-prone and complex for internal processing.  For
this reason XEmacs uses an internal coding system which can encode all
of the world's scripts.  Unfortunately, for historical reasons, this
code is not Unicode, although we are moving in that direction.

XEmacs translates between the internal character encoding and various
other coding systems when reading and writing files, when exchanging
data with subprocesses, and (in some cases) in the @kbd{C-q} command
(see below).  The internal encoding is never visible to the user in a
production XEmacs, but unfortunately the process cannot be completely
transparent to the user.  This is because the same ranges of octets may
represent 1-octet ISO-8859-1 (which is satisfactory for most Western
European use prior to the introduction of the Euro currency), 1-octet
ISO-8859-15 (which substitutes the Euro for the rarely used "generic
currency" symbol), 1-octet ISO-8859-5 (Cyrillic), or multioctet EUC-JP
(Japanese).  There's no way to tell without being able to read!

A number of heuristics are incorporated in Mule for automatic
recognition, there are facilities for the user to set defaults, and
where necessary (rarely, we hope) to set coding systems directly.

@kindex C-h h
@findex view-hello-file
  The command @kbd{C-h h} (@code{view-hello-file}) displays the file
@file{etc/HELLO}, which shows how to say ``hello'' in many languages.
This illustrates various scripts.

  Keyboards, even in the countries where these character sets are used,
generally don't have keys for all the characters in them.  So XEmacs
supports various @dfn{input methods}, typically one for each script or
language, to make it convenient to type them.

@kindex C-x RET
  The prefix key @kbd{C-x @key{RET}} is used for commands that pertain
to world scripts, coding systems, and input methods.

@node Language Environments, Input Methods, Mule Intro, Mule
@section Language Environments
@cindex language environments

  All supported character sets are supported in XEmacs buffers if it is
compiled with Mule; there is no need to select a particular language in
order to display its characters in an XEmacs buffer.  However, it is
important to select a @dfn{language environment} in order to set various
defaults.  The language environment really represents a choice of
preferred script (more or less) rather that a choice of language.

  The language environment controls which coding systems to recognize
when reading text (@pxref{Recognize Coding}).  This applies to files,
incoming mail, netnews, and any other text you read into XEmacs.  It may
also specify the default coding system to use when you create a file.
Each language environment also specifies a default input method.

@findex set-language-environment
  The command to select a language environment is @kbd{M-x
set-language-environment}.  It makes no difference which buffer is
current when you use this command, because the effects apply globally to
the XEmacs session.  The supported language environments include:

@quotation
ASCII, Chinese-BIG5, Chinese-GB, Croatian, Cyrillic-ALT, Cyrillic-ISO,
Cyrillic-KOI8, Cyrillic-Win, Czech, English, Ethiopic, French, German,
Greek, Hebrew, IPA, Japanese, Korean, Latin-1, Latin-2, Latin-3, Latin-4,
Latin-5, Norwegian, Polish, Romanian, Slovenian, Thai-XTIS, Vietnamese.
@end quotation

  Some operating systems let you specify the language you are using by
setting locale environment variables.  XEmacs handles one common special
case of this: if your locale name for character types contains the
string @samp{8859-@var{n}}, XEmacs automatically selects the
corresponding language environment.

@kindex C-h L
@findex describe-language-environment
  To display information about the effects of a certain language
environment @var{lang-env}, use the command @kbd{C-h L @var{lang-env}
@key{RET}} (@code{describe-language-environment}).  This tells you which
languages this language environment is useful for, and lists the
character sets, coding systems, and input methods that go with it.  It
also shows some sample text to illustrate scripts used in this language
environment.  By default, this command describes the chosen language
environment.

@node Input Methods, Select Input Method, Language Environments, Mule
@section Input Methods

@cindex input methods
  An @dfn{input method} is a kind of character conversion designed
specifically for interactive input.  In XEmacs, typically each language
has its own input method; sometimes several languages which use the same
characters can share one input method.  A few languages support several
input methods.

  The simplest kind of input method works by mapping ASCII letters into
another alphabet.  This is how the Greek and Russian input methods work.

  A more powerful technique is composition: converting sequences of
characters into one letter.  Many European input methods use composition
to produce a single non-ASCII letter from a sequence that consists of a
letter followed by accent characters.  For example, some methods convert
the sequence @kbd{'a} into a single accented letter.

  The input methods for syllabic scripts typically use mapping followed
by composition.  The input methods for Thai and Korean work this way.
First, letters are mapped into symbols for particular sounds or tone
marks; then, sequences of these which make up a whole syllable are
mapped into one syllable sign.

  Chinese and Japanese require more complex methods.  In Chinese input
methods, first you enter the phonetic spelling of a Chinese word (in
input method @code{chinese-py}, among others), or a sequence of portions
of the character (input methods @code{chinese-4corner} and
@code{chinese-sw}, and others).  Since one phonetic spelling typically
corresponds to many different Chinese characters, you must select one of
the alternatives using special XEmacs commands.  Keys such as @kbd{C-f},
@kbd{C-b}, @kbd{C-n}, @kbd{C-p}, and digits have special definitions in
this situation, used for selecting among the alternatives.  @key{TAB}
displays a buffer showing all the possibilities.

   In Japanese input methods, first you input a whole word using
phonetic spelling; then, after the word is in the buffer, XEmacs
converts it into one or more characters using a large dictionary.  One
phonetic spelling corresponds to many differently written Japanese
words, so you must select one of them; use @kbd{C-n} and @kbd{C-p} to
cycle through the alternatives.

  Sometimes it is useful to cut off input method processing so that the
characters you have just entered will not combine with subsequent
characters.  For example, in input method @code{latin-1-postfix}, the
sequence @kbd{e '} combines to form an @samp{e} with an accent.  What if
you want to enter them as separate characters?

  One way is to type the accent twice; that is a special feature for
entering the separate letter and accent.  For example, @kbd{e ' '} gives
you the two characters @samp{e'}.  Another way is to type another letter
after the @kbd{e}---something that won't combine with that---and
immediately delete it.  For example, you could type @kbd{e e @key{DEL}
'} to get separate @samp{e} and @samp{'}.

  Another method, more general but not quite as easy to type, is to use
@kbd{C-\ C-\} between two characters to stop them from combining.  This
is the command @kbd{C-\} (@code{toggle-input-method}) used twice.
@ifinfo
@xref{Select Input Method}.
@end ifinfo

  @kbd{C-\ C-\} is especially useful inside an incremental search,
because stops waiting for more characters to combine, and starts
searching for what you have already entered.

@vindex input-method-verbose-flag
@vindex input-method-highlight-flag
  The variables @code{input-method-highlight-flag} and
@code{input-method-verbose-flag} control how input methods explain what
is happening.  If @code{input-method-highlight-flag} is non-@code{nil},
the partial sequence is highlighted in the buffer.  If
@code{input-method-verbose-flag} is non-@code{nil}, the list of possible
characters to type next is displayed in the echo area (but not when you
are in the minibuffer).

@node Select Input Method, Mule and Fonts, Input Methods, Mule
@section Selecting an Input Method

@table @kbd
@item C-\
Enable or disable use of the selected input method.

@item C-x @key{RET} C-\ @var{method} @key{RET}
Select a new input method for the current buffer.

@item C-h I @var{method} @key{RET}
@itemx C-h C-\ @var{method} @key{RET}
@findex describe-input-method
@kindex C-h I
@kindex C-h C-\
Describe the input method @var{method} (@code{describe-input-method}).
By default, it describes the current input method (if any).

@item M-x list-input-methods
Display a list of all the supported input methods.
@end table

@findex select-input-method
@vindex current-input-method
@kindex C-x RET C-\
  To choose an input method for the current buffer, use @kbd{C-x
@key{RET} C-\} (@code{select-input-method}).  This command reads the
input method name with the minibuffer; the name normally starts with the
language environment that it is meant to be used with.  The variable
@code{current-input-method} records which input method is selected.

@findex toggle-input-method
@kindex C-\
  Input methods use various sequences of ASCII characters to stand for
non-ASCII characters.  Sometimes it is useful to turn off the input
method temporarily.  To do this, type @kbd{C-\}
(@code{toggle-input-method}).  To reenable the input method, type
@kbd{C-\} again.

  If you type @kbd{C-\} and you have not yet selected an input method,
it prompts for you to specify one.  This has the same effect as using
@kbd{C-x @key{RET} C-\} to specify an input method.

@vindex default-input-method
  Selecting a language environment specifies a default input method for
use in various buffers.  When you have a default input method, you can
select it in the current buffer by typing @kbd{C-\}.  The variable
@code{default-input-method} specifies the default input method
(@code{nil} means there is none).

@findex quail-set-keyboard-layout
  Some input methods for alphabetic scripts work by (in effect)
remapping the keyboard to emulate various keyboard layouts commonly used
for those scripts.  How to do this remapping properly depends on your
actual keyboard layout.  To specify which layout your keyboard has, use
the command @kbd{M-x quail-set-keyboard-layout}.

@findex list-input-methods
  To display a list of all the supported input methods, type @kbd{M-x
list-input-methods}.  The list gives information about each input
method, including the string that stands for it in the mode line.

@node Mule and Fonts, Coding Systems, Select Input Method, Mule
@section Mule and Fonts
@cindex fonts
@cindex font registry
@cindex font encoding
@cindex CCL programs

(This section is X11-specific.)

Text in XEmacs buffers is displayed using various faces.  In addition to
specifying properties of a face, such as font and color, there are some
additional properties of Mule charsets that are used in text.

There is currently two properties of a charset that could be adjusted by
user: font registry and so called @dfn{ccl-program}.

Font registry is a regular expression matching the font registry field
for this character set.  For example, both the @code{ascii} and
@w{@code{latin-iso8859-1}} charsets use the registry @code{"ISO8859-1"}.
This field is used to choose an appropriate font when the user gives a
general font specification such as @w{@samp{-*-courier-medium-r-*-140-*}},
i.e. a 14-point upright medium-weight Courier font.

You can set font registry for a charset using
@samp{set-charset-registry} function in one of your startup files.  This
function takes two arguments: character set (as a symbol) and font
registry (as a string).

E.@w{ }g., for Cyrillic texts Mule uses @w{@code{cyrillic-iso8859-5}}
charset with @samp{"ISO8859-5"} as a default registry, and we want to
use @samp{"koi8-r"} instead, because fonts in that encoding are
installed on our system.  Use:

@example
(set-charset-registry 'cyrillic-iso8859-5 "koi8-r")
@end example

(Please note that you probably also want to set font registry for
@samp{ascii} charset so that mixed English/Cyrillic texts be displayed
using the same font.)

"CCL-programs" are a little special-purpose scripts defined within
XEmacs or in some package.  Those scripts allow XEmacs to use fonts that
are in different encoding from the encoding that is used by Mule for
text in buffer.  Returning to the above example, we need to somehow tell
XEmacs that we have different encodings of fonts and text and so it
needs to convert characters between those encodings when displaying.
That's what @samp{set-charset-ccl-program} function is used for.  There
are quite a few various CCL programs defined within XEmacs, and there is
no comprehensive list of them, so you currently have to consult sources.
@c FIXME: there must be a list of CCL programs

We know that there is a CCL program called @samp{ccl-encode-koi8-r-font}
that is used exactly for needed purpose: to convert characters between
@samp{ISO8859-5} encoding and @samp{koi8-r}.  Use:

@example
(set-charset-ccl-program 'cyrillic-iso8859-5 'ccl-encode-koi8-r-font)
@end example

There are several more uses for CCL programs, not related to fonts, but
those uses are not described here.

@node Coding Systems, Recognize Coding, Mule and Fonts, Mule
@section Coding Systems
@cindex coding systems

  Users of various languages have established many more-or-less standard
coding systems for representing them.  XEmacs does not use these coding
systems internally; instead, it converts from various coding systems to
its own system when reading data, and converts the internal coding
system to other coding systems when writing data.  Conversion is
possible in reading or writing files, in sending or receiving from the
terminal, and in exchanging data with subprocesses.

  XEmacs assigns a name to each coding system.  Most coding systems are
used for one language, and the name of the coding system starts with the
language name.  Some coding systems are used for several languages;
their names usually start with @samp{iso}.  There are also special
coding systems @code{binary} and @code{no-conversion} which do not
convert printing characters at all.

  In addition to converting various representations of non-ASCII
characters, a coding system can perform end-of-line conversion.  XEmacs
handles three different conventions for how to separate lines in a file:
newline, carriage-return linefeed, and just carriage-return.

@table @kbd
@item C-h C @var{coding} @key{RET}
Describe coding system @var{coding}.

@item C-h C @key{RET}
Describe the coding systems currently in use.

@item M-x list-coding-systems
Display a list of all the supported coding systems.

@item C-u M-x list-coding-systems
Display comprehensive list of specific details of all supported coding
systems.
@end table

@kindex C-x @key{RET} C
@findex describe-coding-system
  The command @kbd{C-x RET C} (@code{describe-coding-system}) displays
information about particular coding systems.  You can specify a coding
system name as argument; alternatively, with an empty argument, it
describes the coding systems currently selected for various purposes,
both in the current buffer and as the defaults, and the priority list
for recognizing coding systems (@pxref{Recognize Coding}).

@findex list-coding-systems
  To display a list of all the supported coding systems, type @kbd{M-x
list-coding-systems}.  The list gives information about each coding
system, including the letter that stands for it in the mode line
(@pxref{Mode Line}).

  Each of the coding systems that appear in this list---except for
@code{binary}, which means no conversion of any kind---specifies how and
whether to convert printing characters, but leaves the choice of
end-of-line conversion to be decided based on the contents of each file.
For example, if the file appears to use carriage-return linefeed between
lines, that end-of-line conversion will be used.

  Each of the listed coding systems has three variants which specify
exactly what to do for end-of-line conversion:

@table @code
@item @dots{}-unix
Don't do any end-of-line conversion; assume the file uses
newline to separate lines.  (This is the convention normally used
on Unix and GNU systems.)

@item @dots{}-dos
Assume the file uses carriage-return linefeed to separate lines,
and do the appropriate conversion.  (This is the convention normally used
on Microsoft systems.)

@item @dots{}-mac
Assume the file uses carriage-return to separate lines, and do the
appropriate conversion.  (This is the convention normally used on the
Macintosh system.)
@end table

  These variant coding systems are omitted from the
@code{list-coding-systems} display for brevity, since they are entirely
predictable.  For example, the coding system @code{iso-8859-1} has
variants @code{iso-8859-1-unix}, @code{iso-8859-1-dos} and
@code{iso-8859-1-mac}.

  In contrast, the coding system @code{binary} specifies no character
code conversion at all---none for non-Latin-1 byte values and none for
end of line.  This is useful for reading or writing binary files, tar
files, and other files that must be examined verbatim.

  The easiest way to edit a file with no conversion of any kind is with
the @kbd{M-x find-file-literally} command.  This uses @code{binary}, and
also suppresses other XEmacs features that might convert the file
contents before you see them.  @xref{Visiting}.

  The coding system @code{no-conversion} means that the file contains
non-Latin-1 characters stored with the internal XEmacs encoding.  It
handles end-of-line conversion based on the data encountered, and has
the usual three variants to specify the kind of end-of-line conversion.

@node Recognize Coding, Specify Coding, Coding Systems, Mule
@section Recognizing Coding Systems

@c #### This section is out of date.  The following set-*-coding-system
@c functions are known:

@c set-buffer-file-coding-system
@c set-buffer-file-coding-system-for-read
@c set-buffer-process-coding-system
@c set-console-tty-coding-system
@c set-console-tty-input-coding-system
@c set-console-tty-output-coding-system
@c set-default-buffer-file-coding-system
@c set-default-coding-systems
@c set-default-file-coding-system
@c set-file-coding-system
@c set-file-coding-system-for-read
@c set-keyboard-coding-system
@c set-pathname-coding-system
@c set-process-coding-system
@c set-process-input-coding-system
@c set-process-output-coding-system
@c set-terminal-coding-system

@c Some are marked as broken.  Agenda: (1) Update this section using
@c docstrings.  Note that they may be inaccurate.  (2) Correct the
@c documentation here, updating docstrings at the same time.

@c Document this.

@c set-language-environment-coding-systems

@c What are these?

@c dontusethis-set-value-file-name-coding-system-handler
@c dontusethis-set-value-keyboard-coding-system-handler
@c dontusethis-set-value-terminal-coding-system-handler

  Most of the time, XEmacs can recognize which coding system to use for
any given file--once you have specified your preferences.

  Some coding systems can be recognized or distinguished by which byte
sequences appear in the data.  However, there are coding systems that
cannot be distinguished, not even potentially.  For example, there is no
way to distinguish between Latin-1 and Latin-2; they use the same byte
values with different meanings.

  XEmacs handles this situation by means of a priority list of coding
systems.  Whenever XEmacs reads a file, if you do not specify the coding
system to use, XEmacs checks the data against each coding system,
starting with the first in priority and working down the list, until it
finds a coding system that fits the data.  Then it converts the file
contents assuming that they are represented in this coding system.

  The priority list of coding systems depends on the selected language
environment (@pxref{Language Environments}).  For example, if you use
French, you probably want XEmacs to prefer Latin-1 to Latin-2; if you
use Czech, you probably want Latin-2 to be preferred.  This is one of
the reasons to specify a language environment.

@findex prefer-coding-system
  However, you can alter the priority list in detail with the command
@kbd{M-x prefer-coding-system}.  This command reads the name of a coding
system from the minibuffer, and adds it to the front of the priority
list, so that it is preferred to all others.  If you use this command
several times, each use adds one element to the front of the priority
list.

@vindex file-coding-system-alist
  Sometimes a file name indicates which coding system to use for the
file.  The variable @code{file-coding-system-alist} specifies this
correspondence.  There is a special function
@code{modify-coding-system-alist} for adding elements to this list.  For
example, to read and write all @samp{.txt} using the coding system
@code{china-iso-8bit}, you can execute this Lisp expression:

@smallexample
(modify-coding-system-alist 'file "\\.txt\\'" 'china-iso-8bit)
@end smallexample

@noindent
The first argument should be @code{file}, the second argument should be
a regular expression that determines which files this applies to, and
the third argument says which coding system to use for these files.

@vindex coding
  You can specify the coding system for a particular file using the
@samp{-*-@dots{}-*-} construct at the beginning of a file, or a local
variables list at the end (@pxref{File Variables}).  You do this by
defining a value for the ``variable'' named @code{coding}.  XEmacs does
not really have a variable @code{coding}; instead of setting a variable,
it uses the specified coding system for the file.  For example,
@samp{-*-mode: C; coding: iso-8859-1;-*-} specifies use of the
iso-8859-1 coding system, as well as C mode.

@vindex buffer-file-coding-system
  Once XEmacs has chosen a coding system for a buffer, it stores that
coding system in @code{buffer-file-coding-system} and uses that coding
system, by default, for operations that write from this buffer into a
file.  This includes the commands @code{save-buffer} and
@code{write-region}.  If you want to write files from this buffer using
a different coding system, you can specify a different coding system for
the buffer using @code{set-buffer-file-coding-system} (@pxref{Specify
Coding}).

@node Specify Coding,  , Recognize Coding, Mule
@section Specifying a Coding System

  In cases where XEmacs does not automatically choose the right coding
system, you can use these commands to specify one:

@table @kbd
@item C-x @key{RET} f @var{coding} @key{RET}
Use coding system @var{coding} for the visited file
in the current buffer.

@item C-x @key{RET} c @var{coding} @key{RET}
Specify coding system @var{coding} for the immediately following
command.

@item C-x @key{RET} k @var{coding} @key{RET}
Use coding system @var{coding} for keyboard input.  (This feature is
non-functional and is temporarily disabled.)

@item C-x @key{RET} t @var{coding} @key{RET}
Use coding system @var{coding} for terminal output.

@item C-x @key{RET} p @var{coding} @key{RET}
Use coding system @var{coding} for subprocess input and output
in the current buffer.
@end table

@kindex C-x RET f
@findex set-buffer-file-coding-system
  The command @kbd{C-x RET f} (@code{set-buffer-file-coding-system})
specifies the file coding system for the current buffer---in other
words, which coding system to use when saving or rereading the visited
file.  You specify which coding system using the minibuffer.  Since this
command applies to a file you have already visited, it affects only the
way the file is saved.

@kindex C-x RET c
@findex universal-coding-system-argument
  Another way to specify the coding system for a file is when you visit
the file.  First use the command @kbd{C-x @key{RET} c}
(@code{universal-coding-system-argument}); this command uses the
minibuffer to read a coding system name.  After you exit the minibuffer,
the specified coding system is used for @emph{the immediately following
command}.

  So if the immediately following command is @kbd{C-x C-f}, for example,
it reads the file using that coding system (and records the coding
system for when the file is saved).  Or if the immediately following
command is @kbd{C-x C-w}, it writes the file using that coding system.
Other file commands affected by a specified coding system include
@kbd{C-x C-i} and @kbd{C-x C-v}, as well as the other-window variants of
@kbd{C-x C-f}.

  In addition, if you run some file input commands with the precedent
@kbd{C-u}, you can specify coding system to read from minibuffer.  So if
the immediately following command is @kbd{C-x C-f}, for example, it
reads the file using that coding system (and records the coding system
for when the file is saved).  Other file commands affected by a
specified coding system include @kbd{C-x C-i} and @kbd{C-x C-v}, as well
as the other-window variants of @kbd{C-x C-f}.

@vindex default-buffer-file-coding-system
  The variable @code{default-buffer-file-coding-system} specifies the
choice of coding system to use when you create a new file.  It applies
when you find a new file, and when you create a buffer and then save it
in a file.  Selecting a language environment typically sets this
variable to a good choice of default coding system for that language
environment.

@kindex C-x RET t
@findex set-terminal-coding-system
  The command @kbd{C-x @key{RET} t} (@code{set-terminal-coding-system})
specifies the coding system for terminal output.  If you specify a
character code for terminal output, all characters output to the
terminal are translated into that coding system.

  This feature is useful for certain character-only terminals built to
support specific languages or character sets---for example, European
terminals that support one of the ISO Latin character sets.

  By default, output to the terminal is not translated at all.

@kindex C-x RET k
@findex set-keyboard-coding-system
  The command @kbd{C-x @key{RET} k} (@code{set-keyboard-coding-system})
specifies the coding system for keyboard input.  Character-code
translation of keyboard input is useful for terminals with keys that
send non-ASCII graphic characters---for example, some terminals designed
for ISO Latin-1 or subsets of it.

  By default, keyboard input is not translated at all.

  There is a similarity between using a coding system translation for
keyboard input, and using an input method: both define sequences of
keyboard input that translate into single characters.  However, input
methods are designed to be convenient for interactive use by humans, and
the sequences that are translated are typically sequences of ASCII
printing characters.  Coding systems typically translate sequences of
non-graphic characters.

(This feature is non-functional and is temporarily disabled.)

@kindex C-x RET p
@findex set-buffer-process-coding-system
  The command @kbd{C-x @key{RET} p} (@code{set-buffer-process-coding-system})
specifies the coding system for input and output to a subprocess.  This
command applies to the current buffer; normally, each subprocess has its
own buffer, and thus you can use this command to specify translation to
and from a particular subprocess by giving the command in the
corresponding buffer.

  By default, process input and output are not translated at all.

@vindex file-name-coding-system
  The variable @code{file-name-coding-system} specifies a coding system
to use for encoding file names.  If you set the variable to a coding
system name (as a Lisp symbol or a string), XEmacs encodes file names
using that coding system for all file operations.  This makes it
possible to use non-Latin-1 characters in file names---or, at least,
those non-Latin-1 characters which the specified coding system can
encode.  By default, this variable is @code{nil}, which implies that you
cannot use non-Latin-1 characters in file names.


code:
@iftex
@unnumbered XEmacs Features

This section describes the difference between Emacs Version 18 and
XEmacs.

@unnumberedsec General Changes

@itemize @bullet
@ignore
@item
XEmacs has a new vi emulation mode called evi mode.  To
start evi mode in Emacs, type the command @kbd{M-x evi}.  If you want
Emacs to automatically put you in evi-mode all the time, include this
line in your init file:
@example
(setq term-setup-hook 'evi)
@end example
@xref{evi Mode} for a brief discussion.
@xref{Init File}.
@end ignore

@item
XEmacs has a new vi emulation mode called ``viper'' mode.  To start
viper mode in XEmacs, type the command @kbd{M-x viper-mode}.  If you
want XEmacs to automatically put you in viper-mode all the time, include
this line in your init file:
@example
(viper-mode)
@end example
@xref{Init File}.

@item
Earlier versions of Emacs only allowed keybindings to ASCII character
sequences.  XEmacs has greatly expanded this by allowing you to
use a vector of key sequences which are in turn composed of a modifier
and a keysym. @xref{Keystrokes} for more information.

@item
The keymap data structure has been reimplemented to allow the use of a
character set larger than ASCII. Keymaps are no longer alists and/or
vectors; they are a new primary data type.  Consequently, code which
manipulated keymaps with list or array manipulation functions will no
longer work.  It must use the functions @code{define-key} or
@code{map-keymap} and @code{set-keymap-parent} (the new keymap
functions).  @xref{Key Bindings} for more information.

@item
Input and display of all ISO-8859-1 characters is supported.

@item
Multiple fonts, including variable-width fonts, and fonts of differing
heights, are supported.

@item
There is a new @file{tags} package and a new UNIX manual browsing
package. They are similar to earlier versions; for more information look
at the source code.

@item
There is a new implementation of Dired, with many new features. The
online info for Dired, @i{not} the Dired node of Emacs info, provides
more detail.

@item
GNUS (a network news reader), VM (an alternative mail reader), ILISP (a
package for interacting with inferior Lisp processes), ANGE-FTP (a package
for making FTP-accessible files appear just like files on the local disk,
even to Dired), Calendar (an Emacs-based calendar and appointment-
management tool), and W3 (an interface to the World Wide Web) are a part
of the XEmacs Lisp library.  See the related documentation in the
online info browser.

@item
Emacs now supports floating-point numbers.

@item
When you send mail, mail aliases are now expanded in the buffer. In
earlier versions, they were expanded after the mail-sending command was
executed.

@item
The initial value of @code{load-path} is computed when Emacs starts up,
instead of being hardcoded in when Emacs is compiled. As a result, you
can now move the Emacs executable and Lisp library to a
different location in the file system without having to recompile.

@item
Any existing subdirectories of the Emacs Lisp directory are now added to the
@code{load-path} by default.

@item
On some machines, you can change the audible bell using the
@code{sound-alist} variable. @xref{Audible Bell} for more information.

@item
You can use multiple X windows to display multiple Emacs frames.

@item
You can use the X selection mechanism to copy material from other
applications and into other applications.  You can also use all Emacs
region commands on a region selected with the mouse. @xref{Mouse
Selection} for more information.

@item
By default, the variable @code{zmacs-regions} is set to highlight the region
between point and the mark.  This unifies X selection and Emacs selection
behavior.

@item
XEmacs has a menu bar for mouse-controlled operations in addition to
keystrokes.  @xref{Pull-down Menus}.

@item
You can look in the file @file{/usr/local/lib/xemacs-19.11/etc/Emacs.ad} for
a list of Emacs X resources.  You can set these resources in your X
environment to set your preferences for color, fonts, location, and the size
of XEmacs frames.  Refer to your X documentation for more information
about resources.

@unnumberedsec New Commands and Variables

There are many new functions in XEmacs, and many existing functions
whose semantics have been expanded.  Most of these are only of interest
to the Emacs-Lisp programmer; see the NEWS file @kbd{C-h n} for a complete
list.  What follows is a partial list of the new interactive commands:

@findex byte-compile-and-load-file
@findex byte-compile-buffer
@item
@code{byte-compile-and-load-file} and @code{byte-compile-buffer}
byte-compile the contents of a file or buffer.

@findex conx
The new @code{conx} function lets you generate random sentences for your
amusement.

@findex compile-defun
@item
@code{compile-defun} compiles and evaluates the current top-level
form.

@findex find-this-file
@findex find-this-file-other-window
@item
@code{find-this-file} and @code{find-this-file-other-window} can be used
interactively with a prefix argument to switch to the filename at point
in the buffer.  @code{find-this-file-other-window} displays the file in
another window.

@findex invert-face
@findex make-face-bold
@findex make-face-bold-italic
@findex make-face-italic
@findex make-face-unbold
@findex make-face-unitalic
@findex set-face-background
@findex set-face-background-pixmap
@findex set-face-font
@findex set-face-foreground
@findex set-face-underline-p
@item
Several new functions have been added that allow you to customize the
color and font attributes of a region of text: @code{invert-face},
@code{make-face-bold}, @code{make-face-bold-italic},
@code{make-face-italic}, @code{make-face-unbold},
@code{make-face-unitalic}, @code{set-face-background},
@code{set-face-background-pixmap}, @code{set-face-font},
@code{set-face-foreground}, and @code{set-face-underline-p}.

@findex load-default-sounds
@findex load-sound-file
@findex play-sound
@item
@code{load-default-sounds} and @code{load-sound-file} allow you to
customize the audible bell sound.  @code{load-default-sounds} loads and
installs sound files.  @code{load-sound-file} reads in audio files and
adds them to the sound alist. @code{play-sound} plays the specified
sound type.

@findex locate-library
@item
@code{locate-library} finds the file that the function
@code{load-library} loads, and it displays the file's full pathname.

@findex make-directory
@findex remove-directory
@item
@code{make-directory} creates a directory, while @code{remove-directory}
removes a directory.

@findex mark-beginning-of-buffer
@findex mark-end-of-buffer
@item
@code{mark-beginning-of-buffer} and @code{mark-end-of-buffer} push the
mark to the beginning or end of a buffer, respectively.

@findex mouse-del-char
@findex mouse-delete-window
@findex mouse-keep-one-window
@findex mouse-kill-line
@findex mouse-line-length
@findex mouse-scroll
@findex mouse-select
@findex mouse-select-and-split
@findex mouse-set-mark
@findex mouse-set-point
@findex mouse-track
@findex mouse-track-adjust
@findex mouse-track-and-copy-to-cutbuffer
@findex mouse-track-delete-and-insert
@findex mouse-track-insert
@findex mouse-window-to-region
Several functions have been added that allow you to perform various
editing, region, and window operations using the mouse:
@code{mouse-del-char}, @code{mouse-delete-window},
@code{mouse-keep-one-window}, @code{mouse-kill-line},
@code{mouse-line-length}, @code{mouse-scroll}, @code{mouse-select},
@code{mouse-select-and-split}, @code{mouse-set-mark},
@code{mouse-set-point}, @code{mouse-track}, @code{mouse-track-adjust},
@code{mouse-track-and-copy-to-cutbuffer},
@code{mouse-track-delete-and-insert}, @code{mouse-track-insert}, and
@code{mouse-window-to-region}.

@findex compare-windows
@item
@code{compare-windows} takes an argument @var{ignore-whitespace}.
The argument means ignore changes in whitespace.

@end itemize

You can conditionalize your @file{.emacs} file as follows so that XEmacs
commands are invoked only when you are in XEmacs:

@cindex version number
@example
(cond ((string-match "Lucid" emacs-version)
       ;;
       ;; Code for any version of Lucid Emacs or XEmacs goes here
       ;;
       ))

(cond ((and (string-match "XEmacs" emacs-version)
            (or (> emacs-major-version 19)
                (>= emacs-minor-version 12)))
       ;;
       ;; Code which requires XEmacs version 19.12 or newer goes here
       ;;
       ))

(cond ((>= emacs-major-version 19)
       ;;
       ;; Code for any vintage-19 emacs goes here
       ;;
       ))

(cond ((and (not (string-match "Lucid" emacs-version))
            (= emacs-major-version 19))
       ;;
       ;; Code specific to FSF Emacs 19 (not XEmacs) goes here
       ;;
       ))

(cond ((< emacs-major-version 19)
       ;;
       ;; Code specific to emacs 18 goes here
       ;;
       ))
@end example

Alternatively, use @file{.xemacs/init.el} for an init file.  @xref{Init File}.

Of particular interest for use in  files are:

@itemize @bullet
@findex add-menu
@findex add-menu-item
@findex delete-menu-item
@findex disable-menu-item
@findex enable-menu-item
@findex relabel-menu-item
@item
@code{add-menu} lets you add a new menu to the menubar or a submenu to a
pull-down menu.  @code{add-menu-item}, @code{disable-menu-item},
@code{delete-menu-item}, @code{enable-menu-item}, and
@code{relabel-menu-item} allow you to customize the XEmacs
pull-down menus.

@findex make-frame
@item
@code{make-frame} creates a new Emacs frame (X window).

@end itemize

These new variables are only present in XEmacs:

@itemize @bullet

@vindex minibuffer-confirm-incomplete
@item
@code{minibuffer-confirm-incomplete} prompts for confirmation in
contexts where @code{completing-read} allows answers that are not valid
completions.

@vindex x-mode-pointer-shape
@vindex x-nontext-pointer-shape
@vindex x-pointer-background-color
@vindex x-pointer-foreground-color
@vindex x-pointer-shape
@item
Several variables have been added that allow you to customize the color
and shape of the mouse pointer: @code{x-pointer-background-color},
@code{x-pointer-foreground-color}, @code{x-mode-pointer-shape},
@code{x-pointer-shape}, and @* @code{x-nontext-pointer-shape}.

@vindex zmacs-regions
@item
@code{zmacs-regions} determines whether LISPM-style active regions
should be used.
@end itemize

@unnumberedsec Changes in Key Bindings

XEmacs has the following new default function keybindings:

@table @kbd
@item @key{HELP}
Same as @kbd{C-h}.

@item @key{UNDO}
Same as @kbd{M-x undo}.

@item @key{CUT}
Same as the Cut menu item; that is, it copies the selected text to
the X Clipboard selection.

@item @key{COPY}
Same as the Copy menu item.

@item @key{PASTE}
Same as the Paste menu item.

@item @key{PGUP}
Same as @kbd{M-v}.

@item @key{PGDN}
Same as @kbd{C-v}.

@item @key{HOME}
Same as @kbd{M-<}.

@item @key{END}
Same as @kbd{M->}.

@item @key{LEFT-ARROW}
Same as the function @code{backward-char}.

@item @key{RIGHT-ARROW}
Same as the function @code{forward-char}.

@item @key{UP-ARROW}
Same as the function @code{previous-line}.

@item @key{DOWN-ARROW}
Same as the function @code{next-line}.

@end table

@end iftex

repo_name: mthl/texinfo

license: mit


code:
@c This is part of the XEmacs manual.
@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
@c See file xemacs.texi for copying conditions.
@node Packages, Basic, Startup Paths, Top
@comment  node-name,  next,  previous,  up

@section Packages
@cindex packages

The XEmacs 21 distribution comes only with a very basic set of
built-in modes and packages.  Most of the packages that were part of
the distribution of earlier versions of XEmacs are now available
separately.  The installer as well as the user can choose which
packages to install; the actual installation process is easy.
This gives an installer the ability to tailor an XEmacs installation for
local needs with safe removal of unnecessary code.

@menu
* Package Terminology:: Understanding different kinds of packages.
* Installing Packages:: How to install packages.
* Building Packages::   Building packages from CVS sources.
* Local.rules File::    This is an important file that you must create.
* Creating Packages::   The basics.
* Available Packages::  A brief directory of packaged LISP.
@end menu

@node Package Terminology, Installing Packages, , Packages
@comment  node-name,  next,  previous,  up
@heading Package Terminology:
@subsection Package Flavors

There are two main flavors of packages.

@itemize @bullet
@item
Regular Packages
@cindex regular packages
A regular package is one in which multiple files are involved and one
may not in general safely remove any of them.

@item
Single-File Packages
@cindex single-file packages
A single-file package is an aggregate collection of thematically
related but otherwise independent lisp files.  These files are bundled
together for download convenience and individual files may be deleted at
will without any loss of functionality.  However, we would recommend
that you follow this rule of thumb: "When in doubt, don't delete".
@end itemize

@subsection Package Distributions
@cindex package distributions
XEmacs Lisp packages are distributed in two ways, depending on the
intended use.  Binary Packages are for installers and end-users that can
be installed directly into an XEmacs package directory.  Source Packages
are for developers and include all files necessary for rebuilding
bytecompiled lisp and creating tarballs for distribution.

@subsection Binary Packages
@cindex binary packages
Binary packages may be installed directly into an XEmacs package
hierarchy.

@subsection Source Packages
@cindex source packages
Source packages contain all of the Package author's (where appropriate
in regular packages) source code plus all of the files necessary to
build distribution tarballs (Unix Tar format files, gzipped for space
savings).

Currently, source packages are only available via CVS.  See
@url{http://cvs.xemacs.org/} for details.
@node Installing Packages, Building Packages, Package Terminology, Packages
@comment  node-name,  next,  previous,  up
@cindex installing packages
@cindex install
@heading Installing Packages:
@subsection Getting Started

When you first download XEmacs 21, you will usually first grab the
@dfn{core distribution},
@cindex core distribution
a file called
@file{xemacs-21.x.x.tar.gz}. (Replace the @t{21.x.x} by the current version
number.)  The core distribution contains the sources of XEmacs and a
minimal set of Emacs Lisp files, which are in the subdirectory named
@file{lisp}.  This subdirectory used to contain all Emacs Lisp files
distributed with XEmacs.  Now, to conserve disk space, most
non-essential packages were made optional.

@subsection Choosing the Packages You Need
@cindex choosing packages
The @ref{Available Packages} can currently be found in the same ftp directory
where you grabbed the core distribution from, and are located in the
subdirectory @file{packages}.  Package file names follow
the naming convention @file{<package-name>-<version>-pkg.tar.gz}.

If you have @ref{(EFS)}, packages can be installed over the network.
Alternatively, if you have copies of the packages locally, you can
install packages from a local disk or CDROM.

The file @file{etc/PACKAGES} in the core distribution contains a list of
the @ref{Available Packages} at the time of the XEmacs release.

You can also get a list of available packages, and whether or not they
are installed, using the visual package browser and installer.  You can
access it via the menus:

@example
        Tools -> Packages -> List and Install
@end example

Or, you can get to it via the keyboard:

@example
M-x pui-list-packages
@end example

Hint to system administrators of multi-user systems: it might be a good
idea to install all packages and not interfere with the wishes of your
users.

If you can't find which package provides the feature you require, try
using the @code{package-get-package-provider} function. Eg., if you know
that you need @code{thingatpt}, type:

@example
M-x package-get-package-provider RET thingatpt
@end example

which will return something like (fsf-compat "1.08"). You can the use
one of the methods above for installing the package you want.

@subsection XEmacs and Installing Packages

There are three main ways to install packages:

@menu
* Sumo::              All at once, using the 'Sumo Tarball'.
* Manually::          Using individual package tarballs.
* Automatically::     Using the package tools from XEmacs.
* Which Packages::    Which packages to install.
* Removing Packages:: Removing packages.
@end menu

But regardless of the method you use to install packages, they can only
be used by XEmacs after a restart.

@node Sumo, Manually, ,Installing Packages
@comment  node-name,  next,  previous,  up
@cindex sumo package install
@heading Installing the Sumo Packages:
Those with little time, cheap connections and plenty of disk space can
install all the packages at once using the sumo tarballs.
Download the file: @file{xemacs-sumo.tar.gz}

For an XEmacs compiled with Mule you also need: @file{xemacs-mule-sumo.tar.gz}

N.B. They are called 'Sumo Tarballs' for good reason. They are
currently about 19MB and 4.5MB (gzipped) respectively.

Install them by:

@code{cd $prefix/lib/xemacs ; gunzip -c <tarballname> | tar xvf - RET}

Or, if you have GNU tar:

@code{cd $prefix/lib/xemacs ; tar zxvf /path/to/<tarballname> RET}

As the Sumo tarballs are not regenerated as often as the individual
packages, it is recommended that you use the automatic package tools
afterwards to pick up any recent updates.

@node Manually, Automatically, Sumo, Installing Packages
@comment  node-name,  next,  previous,  up
@cindex manual package install
@heading Manual Package Installation:
Fetch the packages from the FTP site, CD-ROM whatever. The filenames
have the form @file{name-<version>-pkg.tar.gz} and are gzipped tar files. For
a fresh install it is sufficient to untar the file at the top of the
package hierarchy.

Note: If you are upgrading packages already installed, it's best to
remove the old package first @ref{Removing Packages}.

For example if we are installing the @file{xemacs-base}
package (version 1.48):

@example
   mkdir $prefix/lib/xemacs/xemacs-packages RET # if it does not exist yet
   cd $prefix/lib/xemacs/xemacs-packages RET
   gunzip -c /path/to/xemacs-base-1.48-pkg.tar.gz | tar xvf - RET

Or if you have GNU tar, the last step can be:

   tar zxvf /path/to/xemacs-base-1.48-pkg.tar.gz RET
@end example

For MULE related packages, it is best to untar into the mule-packages
hierarchy, i.e. for the @file{mule-base} package, version 1.37:

@example
   mkdir $prefix/lib/xemacs/mule-packages RET # if it does not exist yet
   cd $prefix/lib/xemacs/mule-packages RET
   gunzip -c /path/to/mule-base-1.37-pkg.tar.gz | tar xvf - RET

Or if you have GNU tar, the last step can be:

   tar zxvf /path/to/mule-base-1.37-pkg.tar.gz RET
@end example

@node Automatically, Which Packages ,Manually, Installing Packages
@comment  node-name,  next,  previous,  up
@cindex automatic package install
@cindex package tools
@heading Automatic Package Installation:
XEmacs comes with some tools to make the periodic updating and
installing easier. It will notice if new packages or versions are
available and will fetch them from the FTP site.

Unfortunately this requires that a few packages are already in place.
You will have to install them by hand as above or use a SUMO tarball.
This requirement will hopefully go away in the future. The packages
you need are:

@example
   efs          - To fetch the files from the FTP site or mirrors.
   xemacs-base  - Needed by efs.

and optionally:

   mule-base    - Needed if you want to use XEmacs with MULE.
@end example

After installing these by hand, fire up XEmacs and follow these
steps.

@enumerate 1
@item
Choose a download site.
via menu: Tools -> Packages -> Add Download Site
via keyb: @code{M-x customize-variable RET package-get-remote RET}
(put in the details of remote host and directory)

If the package tarballs _AND_ the package-index file are in a
local directory, you can: @code{M-x pui-add-install-directory RET}

@item
Obtain a list of packages and display the list in a buffer named
@file{*Packages*}.
menu: Tools -> Packages -> List & Install
keyb: @code{M-x pui-list-packages RET}

XEmacs will now connect to the remote site and download the
latest package-index file.  If you see an error about the
package-index entries not being PGP signed, you can safely
ignore this because PGP has not been integrated into the XEmacs
package tools yet.

The visual package browser will then display a list of all packages.
Help information will be displayed at the very bottom of the buffer; you
may have to scroll down to see it.  You can also press @kbd{?} to get
the same help.  From this buffer, you can tell the package status by the
character in the first column:

@table @kbd
@item -
The package has not been installed.
@item *
The package has been installed, but a newer version is available.  The
current version is out-of-date.
@item +
The package has been marked for installation/update.
@end table

If there is no character in the first column, the package has been
installed and is up to date.

From here, you can select or unselect packages for installation using
the @key{RET} key, the @kbd{Mouse-2} button or selecting "Select" from
the (Popup) Menu.
Once you've finished selecting the packages, you can
press the @kbd{x} key (or use the menu) to actually install the
packages. Note that you will have to restart XEmacs for XEmacs to
recognize any new packages.

Key summary:

@table @kbd
@item ?
Display simple help.
@item @key{RET}
@itemx @key{Mouse-2}
Toggle between selecting and unselecting a package for installation.
@item x
Install selected packages.
@item @key{SPC}
View, in the minibuffer, additional information about the package, such
as the package date (not the build date) and the package author.  Moving
the mouse over a package name will also do the same thing.
@item v
Toggle between verbose and non-verbose package display.
@item g
Refresh the package display.
@item q
Kill the package buffer.
@end table

Moving the mouse over a package will also cause additional information
about the package to be displayed in the minibuffer.

@item
Choose the packages you wish to install.
mouse: Click button 2 on the package name.
 keyb: @kbd{RET} on the package name

@item
Make sure you have everything you need.
menu: Packages -> Add Required
keyb: @kbd{r}

XEmacs will now search for packages that are required by the
ones that you have chosen to install and offer to select
those packages also.

For novices and gurus alike, this step can save your bacon.
It's easy to forget to install a critical package.

@item
Download and install the packages.
menu: Packages -> Install/Remove Selected
keyb: @kbd{x}
@end enumerate

You can also install packages using a semi-manual interface:

@example
M-x package-get-all <return>
@end example

Enter the name of the package (e.g., @code{prog-modes}), and XEmacs
will search for the latest version and install it and any packages that
it depends upon.

@node Which Packages, Removing Packages, Automatically, Installing Packages
@comment  node-name,  next,  previous,  up
@cindex which packages
@cindex choosing packages
@heading Which Packages to Install:
This is difficult to say. When in doubt install a package. If you
administrate a big site it might be a good idea to just install
everything. A good minimal set of packages for XEmacs-latin1 would be

xemacs-base, xemacs-devel, c-support, cc-mode, debug, dired, efs,
edit-utils, fsf-compat, mail-lib, net-utils, os-utils, prog-modes,
text-modes, time

If you are using the XEmacs package tools, don't forget to do:

	Packages -> Add Required

To make sure you have everything that the packages you have chosen to
install need.

See also @ref{Available Packages} for further descriptions of the individual
packages.

@node Removing Packages, ,Which Packages, Installing Packages
@comment  node-name,  next,  previous,  up
@cindex removing packages
@cindex deleting packages
@heading Removing Packages:
Because the exact files and their locations contained in a package may
change it is recommended to remove a package first before installing a
new version. In order to facilitate removal each package contains an
@file{pgkinfo/MANIFEST.pkgname} file which list all the files belonging
to the package.

No need to panic, you don't have to go through the
@file{pkinfo/MANIFEST.pkgname} and manually delete the files.  Instead, use
@code{M-x package-get-delete-package RET}.

Note that the interactive package tools included with XEmacs already do
this for you.

@node Building Packages, Local.rules File, Installing Packages, Packages
@comment  node-name,  next,  previous,  up
@cindex building packages
@cindex package building
@heading Building Packages:
Currently, source packages are only available via anonymous CVS.  See
@url{http://cvs.xemacs.org/} for details of checking out the
@file{xemacs-packages} module.

@subsection Prerequisites for Building Source Packages

@table @code
@item GNU cp
@item GNU install
(or a BSD compatible install program).
@item GNU make
(3.75 or later preferred).
@item makeinfo
(1.68 from texinfo-3.11 or later required).
@item GNU tar
(or equivalent).
@item GNU gzip
(or equivalent).
@item A properly configured @file{Local.rules} file.
@ref{Local.rules File}.
@end table
And of course, XEmacs 21.0 or higher.

@subsection What You Can Do With Source Packages

The packages CVS sources are most useful for creating XEmacs package
tarballs for installation into your own XEmacs installations or for
distributing to others.

Supported operations from @file{make} are:

@table @code
@item all
Bytecompile all files, build and bytecompile byproduct files like
@file{auto-autoloads.el} and @file{custom-load.el}.  Create info version
of TeXinfo documentation if present.

@item bindist
Does a @code{make all} as well as create a binary package tarball in the
staging directory.

@item install
Bytecompile all files, build and bytecompile byproduct files like
@file{auto-autoloads.el} and @file{custom-load.el}.  Create info version
of TeXinfo documentation if present.  And install everything into the
staging directory.

@item srckit
Usually aliased to @code{srckit-std}.  This does a @code{make
distclean} and creates a package source tarball in the staging
directory.  This is generally only of use for package maintainers.

@item binkit
May be aliased to @code{binkit-sourceonly}, @code{binkit-sourceinfo},
@code{binkit-sourcedata}, or
@code{binkit-sourcedatainfo}. @code{sourceonly} indicates there is
nothing to install in a data directory or info directory.
@code{sourceinfo} indicates that source and info files are to be
installed.  @code{sourcedata} indicates that source and etc (data) files
are to be installed.  @code{sourcedatainfo} indicates source, etc
(data), and info files are to be installed.  A few packages have needs
beyond the basic templates so this is not yet complete.

@item dist
Runs the rules @code{srckit} followed by @code{binkit}.  This is
primarily of use by XEmacs maintainers producing files for distribution.

@item clean
Remove all built files except @file{auto-autoloads.el} and @file{custom-load.el}.

@item distclean
Remove all created files.
@end table

@node Local.rules File, Creating Packages, Building Packages, Packages
@comment  node-name,  next,  previous,  up
@cindex local.rules
@heading The Local.rules File:
This file is used when building and installing packages from source.  In
the top level of the CVS module, @file{xemacs-packages}, contains the
file, @file{Local.rules.template}.  Simply copy that to
@file{Local.rules} and edit it to suit your needs.

These are the variables in 'Local.rules' that you will need to
address.

@table @var
@item symlink =
Set this to 't' if you want to do a "run in place".
Setting this doesn't work well with 'make bindist'

@item XEMACS_PACKAGES =
This is where you set the normal packages that you
want to install. eg:
@example
      XEMACS_PACKAGES = xemacs-packages/xemacs-base xemacs-packages/bbdb
@end example

@item XEMACS_STAGING = $@{XEMACS_PACKAGES_BASE@}/../Packages
Set this to where you want normal packages to be
installed to.

@item PACKAGE_INDEX = package-index
If you want the package-index file to have a different
name, change this.

@item BUILD_WITHOUT_MULE =
Building from CVS defaults to building the Mule
packages.  Set this to 't' if you don't want/have Mule

@item MULE_PACKAGES =
Same as for 'XEMACS_PACKAGES' except you list the Mule
packages you want to install here. eg:
@example
      MULE_PACKAGES = mule-packages/mule-base mule-packages/skk
@end example

@item MULE_STAGING = $@{XEMACS_PACKAGES_BASE@}/../Mule-Packages
Set this to where you want Mule packages installed
to.  Note:  'make bindist' does not use this variable.

@item XEMACS = xemacs
If your XEmacs isn't in your path, change this.

@item XEMACS_NATIVE_NT =
Set this to 't' if you are building on WinNT.

@item INSTALL = install -c
The path to your BSD compatible install program.

@item TAR = tar
The path to your tar program

@item BZIP2 =
If you want bzip2 tarballs, set this.

@item MAKEINFO = makeinfo
The path to your makeinfo program
@end table

@node Creating Packages, Available Packages, Local.rules File, Packages
@comment  node-name,  next,  previous,  up
@cindex creating packages
@heading Creating Packages:
Creating a package from an existing Lisp library is not very difficult.

In addition to the Lisp libraries themselves, you need a
@file{package-info.in} file and a simple @file{Makefile}.  The rest is
done by @file{XEmacs.rules}, part of the packaging system
infrastructure.

@file{package-info.in} contains a single Lisp form like this:

@example
(name                               ; your package's name
  (standards-version 1.1
   version VERSION
   author-version AUTHOR_VERSION
   date DATE
   build-date BUILD_DATE
   maintainer MAINTAINER
   distribution xemacs              ; change to "mule" if MULE is needed
   priority high
   category CATEGORY
   dump nil
   description "description"        ; a one-line description string
   filename FILENAME
   md5sum MD5SUM
   size SIZE
   provides (feature1 feature2)     ; one for every `provides' form
   requires (REQUIRES)
   type regular
))
@end example

You must fill in the four commented lines.  The value of @code{name} is
the name of your package as an unquoted symbol.  Normally it is the name
of the main Lisp file or principal feature provided.  The allowed values
for distribution are @code{xemacs} and @code{mule}.  Write them as
unquoted symbols.  The @code{description} is a quoted Lisp string; use
the usual conventions.  The value for @code{provides} is a list of
feature symbols (written unquoted).  All of the features provided by
libraries in your package should be elements of this list.  Implementing
an automatic method for generating the @file{provides} line is
desirable, but as yet undone.

The variables in upper-case are references to variables set in the
@file{Makefile} or automatically generated.  Do not change them; they
are automatically filled in by the build process.

The remaining lines refer to implementation constants
(@code{standards-version}), or features that are unimplemented or have
been removed (@code{priority} and @code{dump}).  The @code{type} line is
not normally relevant to external maintainers; the alternate value is
@code{single-file}, which refers to packages consed up out of a number
of single-file libraries that are more or less thematically related.  An
example is @code{prog-modes}.  Single-file packages are basically for
administrative convenience, and new packages should generally be created
as regular packages.

The @file{Makefile} is quite stylized.  The idea is similar to an
@file{Imakefile} or an @code{automake} file: the complexity is hidden in
generic rules files, in this case the @file{XEmacs.rules} include file
in the top directory of the packages hierarchy.  Although a number of
facilities are available for complex libraries, most simple packages'
@file{Makefile}s contain a copyright notice, a few variable definitions,
an include for @file{XEmacs.rules}, and a couple of standard targets.

The first few @code{make} variables defined are @code{VERSION},
@code{AUTHOR_VERSION}, @code{MAINTAINER}, @code{PACKAGE},
@code{PKG_TYPE}, @code{REQUIRES}, and @code{CATEGORY}.  All but one were
described in the description of @file{package-info.in}.  The last is an
administrative grouping.  Current categories include @code{standard},
and @code{mule}.

Next, define the variable @code{ELCS}.  This contains the list of the
byte-compiled Lisp files used by the package.  These files and their
@file{.el} versions will be included in the binary package.  If there
are other files (such as extra Lisp sources or an upstream
@file{Makefile}) that are normally placed in the installed Lisp
directory, but not byte-compiled, they can be listed as the value of
@code{EXTRA_SOURCES}.

The include is simply
@example
include ../../XEmacs.rules
@end example

The standard targets follow.  These are

@example
all:: $(ELCS) auto-autoloads.elc

srckit: srckit-alias

binkit: binkit-alias
@end example

Other targets (such as Texinfo sources) may need to be added as
dependencies for the @code{all} target.  Dependencies for @code{srckit}
and @code{binkit} (that is, values for @var{srckit-alias} and
@var{binkit-alias}) are defined in @file{XEmacs.rules}.  The most useful
of these values are given in the following table.

@table @var
@item srckit-alias
Usually set to @code{srckit-std}.

@item binkit-alias
May be set to @code{binkit-sourceonly}, @code{binkit-sourceinfo},
@code{binkit-sourcedata}, or
@code{binkit-sourcedatainfo}.  @code{sourceonly} indicates there is
nothing to install in a data directory or info directory.
@code{sourceinfo} indicates that source and info files are to be
installed.  @code{sourcedata} indicates that source and etc (data) files
are to be installed.  @code{sourcedatainfo} indicates source, etc
(data), and info files are to be installed.
@end table

Data files include things like pixmaps for a package-specific toolbar,
and are normally installed in @file{etc/@var{PACKAGE_NAME}}.  A few
packages have needs beyond the basic templates.  See @file{XEmacs.rules}
or a future revision of this manual for details.

@node Available Packages,  , Creating Packages, Packages
@comment  node-name,  next,  previous,  up
@cindex available packages
@cindex packages
@heading Available Packages:
This section lists the Lisp packages that are currently available from
xemacs.org and it's mirrors.  If a particular package that you are
looking for isn't here, please send a message to the
@email{xemacs-beta@@xemacs.org, XEmacs Beta list}.

This data is up to date as of September 22, 2002.

@subsection Normal Packages
A very broad selection of elisp packages.

@table @file
@item Sun
Support for Sparcworks.

@item ada
Ada language support.

@item apel
A Portable Emacs Library.  Used by XEmacs MIME support.

@item auctex
Basic TeX/LaTeX support.

@item bbdb
The Big Brother Data Base: a rolodex-like database program.

@item build
Build XEmacs using custom widgets.

@item c-support
Basic single-file add-ons for editing C code.

@item calc
Emacs calculator.

@item calendar
Calendar and diary support.

@item cc-mode
C, C++ and Java language support.

@item clearcase
Support for the Clearcase version control system.

@item cookie
"Fortune cookie"-style messages. Includes Spook (suspicious phrases)
and Yow (Zippy quotes).

@item crisp
Crisp/Brief emulation.

@item debug
GUD, gdb, dbx debugging support.

@item dictionary
Interface to RFC2229 dictionary servers.

@item dired
The DIRectory EDitor is for manipulating, and running commands on
files in a directory.

@item docbookide
DocBook editing support.

@item ecrypto
Crypto functionality in Emacs Lisp.

@item edebug
A Lisp debugger.

@item ediff
Interface over patch.

@item edit-utils
Single file lisp packages for various XEmacs goodies.  Load this and
weed out the junk you don't want.

@item edt
DEC EDIT/EDT emulation.

@item efs
Treat files on remote systems the same as local files.

@item eieio
Enhanced Implementation of Emacs Interpreted Objects.

@item elib
Portable Emacs Lisp utilities library.

@item emerge
Another interface over patch.

@item eshell
Command shell implemented entirely in Emacs Lisp.

@item ess
ESS: Emacs Speaks Statistics.

@item eterm
Terminal emulator.

@item eudc
Emacs Unified Directory Client (LDAP, PH).

@item footnote
Footnoting in mail message editing modes.

@item forms
Forms editing support (obsolete, use the built-in Widget instead).

@item fortran-modes
Fortran language support.

@item frame-icon
Provide a WM icon based on major mode.

@item fsf-compat
GNU Emacs compatibility files.

@item games
Tetris, Sokoban, and Snake.

@item gnats
XEmacs bug reports.

@item gnus
The Gnus Newsreader and Mailreader.

@item haskell-mode
Haskell language support.

@item hm--html-menus
HTML editing.

@item ibuffer
Advanced replacement for buffer-menu.

@item idlwave
Editing and Shell mode for the Interactive Data Language.

@item igrep
Enhanced front-end for Grep.

@item ilisp
Front-end for interacting with Inferior Lisp (external lisps).

@item ispell
Spell-checking with ispell.

@item jde
Java language and development support.

@item liece
IRC (Internet Relay Chat) client for Emacs.

@item mail-lib
Fundamental lisp files for providing email support.

@item mailcrypt
Support for messaging encryption with PGP.

@item mew
Messaging in an Emacs World; a MIME-based email program.

@item mh-e
Front end support for MH.

@item mine
Elisp implementation of the game 'Minehunt'.

@item misc-games
Other amusements and diversions.

@item mmm-mode
Support for Multiple Major Modes within a single buffer.

@item net-utils
Miscellaneous Networking Utilities.  This is a single-file package and
files may be deleted at will.

@item os-utils
Miscellaneous single-file O/S utilities, for printing, archiving,
compression, remote shells, etc.

@item ocaml
Objective Caml language support.

@item pc
PC style interface emulation.

@item pcl-cvs
CVS frontend.

@item pcomplete
Provides programmatic completion.

@item perl-modes
Perl language support.

@item prog-modes
Miscellaneous single-file lisp files for various programming languages.

@item ps-print
Print buffers to PostScript printers.

@item psgml
Validated HTML/SGML editing.

@item psgml-dtds
A collection of DTDs for psgml.  Note that this package is deprecated
and will be removed in the future, most likely Q2/2003.  Instead of using
this, you should install needed DTDs yourself.

@item python-modes
Python language support.

@item reftex
Emacs support for LaTeX cross-references, citations.

@item rmail
An obsolete Emacs mailer.  If you do not already use it don't start.

@item ruby-modes
Ruby language support.

@item sasl
Simple Authentication and Security Layer (SASL) library.

@item scheme
Front-end support for Inferior Scheme.

@item semantic
Semantic bovinator.

@item sgml
SGML/Linuxdoc-SGML editing.

@item sh-script
Support for editing shell scripts.

@item sieve
Manage Sieve email filtering scripts.

@item slider
User interface tool.

@item sml-mode
Standard ML editing support.

@item sounds-au
XEmacs Sun sound files.

@item sounds-wav
XEmacs Microsoft sound files.

@item speedbar
Provides a separate frame with convenient references.

@item strokes
Mouse enhancement utility.

@item supercite
An Emacs citation tool.  Useful with all Emacs Mailers and Newsreaders.

@item texinfo
XEmacs TeXinfo support.

@item text-modes
Various single file lisp packages for editing text files.

@item textools
Single-file TeX support.

@item time
Display time & date on the modeline.

@item tm
Emacs MIME support. Not needed for Gnus >= 5.8.0

@item tooltalk
Support for building with Tooltalk.

@item tpu
DEC EDIT/TPU support.

@item tramp
Remote shell-based file editing.  This is similar to EFS or Ange-FTP,
but works with rsh/ssh and rcp/scp.

@item vc
Version Control for Free systems.

@item vc-cc
Version Control for ClearCase.  This package will shortly be
replaced with clearcase.el

@item vhdl
Support for VHDL.

@item view-process
A Unix process browsing tool.

@item viper
VI emulation support.

@item vm
An Emacs mailer.

@item w3
A Web browser.

@item xemacs-base
Fundamental XEmacs support.  Install this unless you wish a totally
naked XEmacs.

@item xemacs-devel
XEmacs Lisp developer support.  This package contains utilities for
supporting Lisp development.  It is a single-file package so it may be
tailored.

@item xslide
XSL editing support.

@item xslt-process
A minor mode for (X)Emacs which allows running an XSLT processor on a
buffer.

@item zenirc
ZENIRC IRC Client.
@end table

@subsection Mule Support (mule)

MULti-lingual Enhancement.  Support for world scripts such as
Latin, Arabic, Cyrillic, Chinese, Japanese, Greek, Hebrew etc.
To use these packages your XEmacs must be compiled with Mule
support.

@table @file
@item edict
Lisp Interface to EDICT, Kanji Dictionary.

@item egg-its
Wnn (4.2 and 6) support.  SJ3 support.  Must be installed prior to
XEmacs build.

@item latin-unity
Unify character sets in a buffer. When characters belong to disjoint
character sets, this attempts to translate the characters so
that they belong to one character set. If the buffer coding system is
not sufficient, this suggests different coding systems.

@item leim
Quail.  Used for everything other than English and Japanese.

@item locale
Used for localized menubars (French and Japanese) and localized splash
screens (Japanese).

@item lookup
Dictionary support. (This isn't an English dictionary program)

@item mule-base
Basic Mule support.  Must be installed prior to building with Mule.

@item mule-ucs
Extended coding systems (including Unicode) for XEmacs.

@item skk
Another Japanese Language Input Method.  Can be used without a
separate process running as a dictionary server.
@end table


code:
@node Picture, Sending Mail, Abbrevs, Top
@chapter Editing Pictures
@cindex pictures
@findex edit-picture

  If you want to create a picture made out of text characters (for example,
a picture of the division of a register into fields, as a comment in a
program), use the command @code{edit-picture} to enter Picture mode.

  In Picture mode, editing is based on the @dfn{quarter-plane} model of
text.  In this model, the text characters lie studded on an area that
stretches infinitely far to the right and downward.  The concept of the end
of a line does not exist in this model; the most you can say is where the
last non-blank character on the line is found.

  Of course, Emacs really always considers text as a sequence of
characters, and lines really do have ends.  But in Picture mode most
frequently-used keys are rebound to commands that simulate the
quarter-plane model of text.  They do this by inserting spaces or by
converting tabs to spaces.

  Most of the basic editing commands of Emacs are redefined by Picture mode
to do essentially the same thing but in a quarter-plane way.  In addition,
Picture mode defines various keys starting with the @kbd{C-c} prefix to
run special picture editing commands.

  One of these keys, @kbd{C-c C-c}, is pretty important.  Often a picture
is part of a larger file that is usually edited in some other major mode.
@kbd{M-x edit-picture} records the name of the previous major mode.
You can then use the @kbd{C-c C-c} command (@code{picture-mode-exit}) to
restore that mode.  @kbd{C-c C-c} also deletes spaces from the ends of
lines, unless you give it a numeric argument.

  The commands used in Picture mode all work in other modes (provided the
@file{picture} library is loaded), but are only  bound to keys in
Picture mode.  Note that the descriptions below talk of moving ``one
column'' and so on, but all the picture mode commands handle numeric
arguments as their normal equivalents do.

@vindex picture-mode-hook
  Turning on Picture mode calls the value of the variable
@code{picture-mode-hook} as a function, with no arguments, if that value
exists and is non-@code{nil}.

@menu
* Basic Picture::         Basic concepts and simple commands of Picture Mode.
* Insert in Picture::     Controlling direction of cursor motion
                           after "self-inserting" characters.
* Tabs in Picture::       Various features for tab stops and indentation.
* Rectangles in Picture:: Clearing and superimposing rectangles.
@end menu

@node Basic Picture, Insert in Picture, Picture, Picture
@section Basic Editing in Picture Mode

@findex picture-forward-column
@findex picture-backward-column
@findex picture-move-down
@findex picture-move-up
  Most keys do the same thing in Picture mode that they usually do, but do
it in a quarter-plane style.  For example, @kbd{C-f} is rebound to run
@code{picture-forward-column}, which moves point one column to
the right, by inserting a space if necessary, so that the actual end of the
line makes no difference.  @kbd{C-b} is rebound to run
@code{picture-backward-column}, which always moves point left one column,
converting a tab to multiple spaces if necessary.  @kbd{C-n} and @kbd{C-p}
are rebound to run @code{picture-move-down} and @code{picture-move-up},
which can either insert spaces or convert tabs as necessary to make sure
that point stays in exactly the same column.  @kbd{C-e} runs
@code{picture-end-of-line}, which moves to after the last non-blank
character on the line.  There was no need to change @kbd{C-a}, as the choice
of screen model does not affect beginnings of lines.@refill

@findex picture-newline
  Insertion of text is adapted to the quarter-plane screen model through
the use of Overwrite mode (@pxref{Minor Modes}).  Self-inserting characters
replace existing text, column by column, rather than pushing existing text
to the right.  @key{RET} runs @code{picture-newline}, which just moves to
the beginning of the following line so that new text will replace that
line.

@findex picture-backward-clear-column
@findex picture-clear-column
@findex picture-clear-line
  Text is erased instead of deleted and killed.  @key{DEL}
(@code{picture-backward-clear-column}) replaces the preceding character
with a space rather than removing it.  @kbd{C-d}
(@code{picture-clear-column}) does the same in a forward direction.
@kbd{C-k} (@code{picture-clear-line}) really kills the contents of lines,
but never removes the newlines from a buffer.@refill

@findex picture-open-line
  To do actual insertion, you must use special commands.  @kbd{C-o}
(@code{picture-open-line}) creates a blank line, but does so after
the current line; it never splits a line.  @kbd{C-M-o}, @code{split-line},
makes sense in Picture mode, so it remains unchanged.  @key{LFD}
(@code{picture-duplicate-line}) inserts another line
with the same contents below the current line.@refill

@kindex C-c C-d (Picture mode)
@findex delete-char

  To actually delete parts of the picture, use @kbd{C-w}, or with
@kbd{C-c C-d} (which is defined as @code{delete-char}, as @kbd{C-d} is
in other modes), or with one of the picture rectangle commands
(@pxref{Rectangles in Picture}).

@node Insert in Picture, Tabs in Picture, Basic Picture, Picture
@section Controlling Motion After Insert

@findex picture-movement-up
@findex picture-movement-down
@findex picture-movement-left
@findex picture-movement-right
@findex picture-movement-nw
@findex picture-movement-ne
@findex picture-movement-sw
@findex picture-movement-se
@kindex C-c < (Picture mode)
@kindex C-c > (Picture mode)
@kindex C-c ^ (Picture mode)
@kindex C-c . (Picture mode)
@kindex C-c ` (Picture mode)
@kindex C-c ' (Picture mode)
@kindex C-c / (Picture mode)
@kindex C-c \ (Picture mode)
  Since ``self-inserting'' characters just overwrite and move point in
Picture mode, there is no essential restriction on how point should be
moved.  Normally point moves right, but you can specify any of the eight
orthogonal or diagonal directions for motion after a ``self-inserting''
character.  This is useful for drawing lines in the buffer.

@table @kbd
@item C-c <
Move left after insertion (@code{picture-movement-left}).
@item C-c >
Move right after insertion (@code{picture-movement-right}).
@item C-c ^
Move up after insertion (@code{picture-movement-up}).
@item C-c .
Move down after insertion (@code{picture-movement-down}).
@item C-c `
Move up and left (``northwest'') after insertion @*(@code{picture-movement-nw}).
@item C-c '
Move up and right (``northeast'') after insertion @*
(@code{picture-movement-ne}).
@item C-c /
Move down and left (``southwest'') after insertion
@*(@code{picture-movement-sw}).
@item C-c \
Move down and right (``southeast'') after insertion
@*(@code{picture-movement-se}).
@end table

@kindex C-c C-f (Picture mode)
@kindex C-c C-b (Picture mode)
@findex picture-motion
@findex picture-motion-reverse
  Two motion commands move based on the current Picture insertion
direction.  The command @kbd{C-c C-f} (@code{picture-motion}) moves in the
same direction as motion after ``insertion'' currently does, while @kbd{C-c
C-b} (@code{picture-motion-reverse}) moves in the opposite direction.

@node Tabs in Picture, Rectangles in Picture, Insert in Picture, Picture
@section Picture Mode Tabs

@kindex M-TAB
@findex picture-tab-search
@vindex picture-tab-chars
  Two kinds of tab-like action are provided in Picture mode.
Context-based tabbing is done with @kbd{M-@key{TAB}}
(@code{picture-tab-search}).  With no argument, it moves to a point
underneath the next ``interesting'' character that follows whitespace in
the previous non-blank line.  ``Next'' here means ``appearing at a
horizontal position greater than the one point starts out at''.  With an
argument, as in @kbd{C-u M-@key{TAB}}, the command moves to the next such
interesting character in the current line.  @kbd{M-@key{TAB}} does not
change the text; it only moves point.  ``Interesting'' characters are
defined by the variable @code{picture-tab-chars}, which contains a string
of characters considered interesting.  Its default value is
@code{"!-~"}.@refill

@findex picture-tab
  @key{TAB} itself runs @code{picture-tab}, which operates based on the
current tab stop settings; it is the Picture mode equivalent of
@code{tab-to-tab-stop}.  Without arguments it just moves point, but with
a numeric argument it clears the text that it moves over.

@kindex C-c TAB (Picture mode)
@findex picture-set-tab-stops
  The context-based and tab-stop-based forms of tabbing are brought
together by the command @kbd{C-c @key{TAB}} (@code{picture-set-tab-stops}.)
This command sets the tab stops to the positions which @kbd{M-@key{TAB}}
would consider significant in the current line.  If you use this command
with @key{TAB}, you can get the effect of context-based tabbing.  But
@kbd{M-@key{TAB}} is more convenient in the cases where it is sufficient.

@node Rectangles in Picture,, Tabs in Picture, Picture
@section Picture Mode Rectangle Commands
@cindex rectangle

  Picture mode defines commands for working on rectangular pieces of the
text in ways that fit with the quarter-plane model.  The standard rectangle
commands may also be useful (@pxref{Rectangles}).

@table @kbd
@item C-c C-k
Clear out the region-rectangle (@code{picture-clear-rectangle}).  With
argument, kill it.
@item C-c C-w @var{r}
Similar but save rectangle contents in register @var{r} first
(@code{picture-clear-rectangle-to-register}).
@item C-c C-y
Copy last killed rectangle into the buffer by overwriting, with upper
left corner at point (@code{picture-yank-rectangle}).  With argument,
insert instead.
@item C-c C-x @var{r}
Similar, but use the rectangle in register @var{r}@*
(@code{picture-yank-rectangle-from-register}).
@end table

@kindex C-c C-k (Picture mode)
@kindex C-c C-w (Picture mode)
@findex picture-clear-rectangle
@findex picture-clear-rectangle-to-register
  The picture rectangle commands @kbd{C-c C-k}
(@code{picture-clear-rectangle}) and @kbd{C-c C-w}
(@code{picture-clear-rectangle-to-register}) differ from the standard
rectangle commands in that they normally clear the rectangle instead of
deleting it; this is analogous with the way @kbd{C-d} is changed in Picture
mode.@refill

  However, deletion of rectangles can be useful in Picture mode, so these
commands delete the rectangle if given a numeric argument.

@kindex C-c C-y (Picture mode)
@kindex C-c C-x (Picture mode)
@findex picture-yank-rectangle
@findex picture-yank-rectangle-from-register
  The Picture mode commands for yanking rectangles differ from the standard
ones in overwriting instead of inserting.  This is the same way that
Picture mode insertion of other text is different from other modes.
@kbd{C-c C-y} (@code{picture-yank-rectangle}) inserts (by overwriting) the
rectangle that was most recently killed, while @kbd{C-c C-x}
(@code{picture-yank-rectangle-from-register}) does for the
rectangle found in a specified register.

Since most region commands in Picture mode operate on rectangles, when you
select a region of text with the mouse in Picture mode, it is highlighted
as a rectangle.