annotate man/cmdargs.texi @ 36170:0fd801cdb9fd

Clarify undisplayable characters, --unibyte, locales. Clarify self-insertion of non-ASCII 8-bit chars. Clarify coding system detection of escape sequences. Clarify keyboard input methods and coding systems. Comment out the commands to inquire about character sets. Misc cleanups.
author Richard M. Stallman <rms@gnu.org>
date Sat, 17 Feb 2001 18:12:07 +0000
parents 885408f5ce84
children e391cbe3a2fe
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1 @c This is part of the Emacs manual.
Dave Love <fx@gnu.org>
parents:
diff changeset
2 @c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc.
Dave Love <fx@gnu.org>
parents:
diff changeset
3 @c See file emacs.texi for copying conditions.
Dave Love <fx@gnu.org>
parents:
diff changeset
4 @node Command Arguments, Antinews, Service, Top
Dave Love <fx@gnu.org>
parents:
diff changeset
5 @appendix Command Line Arguments
Dave Love <fx@gnu.org>
parents:
diff changeset
6 @cindex command line arguments
Dave Love <fx@gnu.org>
parents:
diff changeset
7 @cindex arguments (command line)
Dave Love <fx@gnu.org>
parents:
diff changeset
8 @cindex options (command line)
Dave Love <fx@gnu.org>
parents:
diff changeset
9 @cindex switches (command line)
Dave Love <fx@gnu.org>
parents:
diff changeset
10 @cindex startup (command line arguments)
Dave Love <fx@gnu.org>
parents:
diff changeset
11
Dave Love <fx@gnu.org>
parents:
diff changeset
12 GNU Emacs supports command line arguments to request various actions
Dave Love <fx@gnu.org>
parents:
diff changeset
13 when invoking Emacs. These are for compatibility with other editors and
Dave Love <fx@gnu.org>
parents:
diff changeset
14 for sophisticated activities. We don't recommend using them for
Dave Love <fx@gnu.org>
parents:
diff changeset
15 ordinary editing.
Dave Love <fx@gnu.org>
parents:
diff changeset
16
Dave Love <fx@gnu.org>
parents:
diff changeset
17 Arguments starting with @samp{-} are @dfn{options}. Other arguments
Dave Love <fx@gnu.org>
parents:
diff changeset
18 specify files to visit. Emacs visits the specified files while it
Dave Love <fx@gnu.org>
parents:
diff changeset
19 starts up. The last file name on your command line becomes the current
Dave Love <fx@gnu.org>
parents:
diff changeset
20 buffer; the other files are also present in other buffers. As usual,
Dave Love <fx@gnu.org>
parents:
diff changeset
21 the special argument @samp{--} says that all subsequent arguments
Dave Love <fx@gnu.org>
parents:
diff changeset
22 are file names, not options, even if they start with @samp{-}.
Dave Love <fx@gnu.org>
parents:
diff changeset
23
Dave Love <fx@gnu.org>
parents:
diff changeset
24 Emacs command options can specify many things, such as the size and
Dave Love <fx@gnu.org>
parents:
diff changeset
25 position of the X window Emacs uses, its colors, and so on. A few
Dave Love <fx@gnu.org>
parents:
diff changeset
26 options support advanced usage, such as running Lisp functions on files
Dave Love <fx@gnu.org>
parents:
diff changeset
27 in batch mode. The sections of this chapter describe the available
Dave Love <fx@gnu.org>
parents:
diff changeset
28 options, arranged according to their purpose.
Dave Love <fx@gnu.org>
parents:
diff changeset
29
Dave Love <fx@gnu.org>
parents:
diff changeset
30 There are two ways of writing options: the short forms that start with
Dave Love <fx@gnu.org>
parents:
diff changeset
31 a single @samp{-}, and the long forms that start with @samp{--}. For
Dave Love <fx@gnu.org>
parents:
diff changeset
32 example, @samp{-d} is a short form and @samp{--display} is the
Dave Love <fx@gnu.org>
parents:
diff changeset
33 corresponding long form.
Dave Love <fx@gnu.org>
parents:
diff changeset
34
Dave Love <fx@gnu.org>
parents:
diff changeset
35 The long forms with @samp{--} are easier to remember, but longer to
Dave Love <fx@gnu.org>
parents:
diff changeset
36 type. However, you don't have to spell out the whole option name; any
Dave Love <fx@gnu.org>
parents:
diff changeset
37 unambiguous abbreviation is enough. When a long option takes an
Dave Love <fx@gnu.org>
parents:
diff changeset
38 argument, you can use either a space or an equal sign to separate the
Dave Love <fx@gnu.org>
parents:
diff changeset
39 option name and the argument. Thus, you can write either
Dave Love <fx@gnu.org>
parents:
diff changeset
40 @samp{--display sugar-bombs:0.0} or @samp{--display=sugar-bombs:0.0}.
Dave Love <fx@gnu.org>
parents:
diff changeset
41 We recommend an equal sign because it makes the relationship clearer,
Dave Love <fx@gnu.org>
parents:
diff changeset
42 and the tables below always show an equal sign.
Dave Love <fx@gnu.org>
parents:
diff changeset
43
Dave Love <fx@gnu.org>
parents:
diff changeset
44 @cindex initial options (command line)
Dave Love <fx@gnu.org>
parents:
diff changeset
45 @cindex action options (command line)
Dave Love <fx@gnu.org>
parents:
diff changeset
46 Most options specify how to initialize Emacs, or set parameters for
Dave Love <fx@gnu.org>
parents:
diff changeset
47 the Emacs session. We call them @dfn{initial options}. A few options
Dave Love <fx@gnu.org>
parents:
diff changeset
48 specify things to do: for example, load libraries, call functions, or
Dave Love <fx@gnu.org>
parents:
diff changeset
49 exit Emacs. These are called @dfn{action options}. These and file
Dave Love <fx@gnu.org>
parents:
diff changeset
50 names together are called @dfn{action arguments}. Emacs processes all
Dave Love <fx@gnu.org>
parents:
diff changeset
51 the action arguments in the order they are written.
Dave Love <fx@gnu.org>
parents:
diff changeset
52
Dave Love <fx@gnu.org>
parents:
diff changeset
53 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
54 * Action Arguments:: Arguments to visit files, load libraries,
Dave Love <fx@gnu.org>
parents:
diff changeset
55 and call functions.
Dave Love <fx@gnu.org>
parents:
diff changeset
56 * Initial Options:: Arguments that take effect while starting Emacs.
Dave Love <fx@gnu.org>
parents:
diff changeset
57 * Command Example:: Examples of using command line arguments.
Dave Love <fx@gnu.org>
parents:
diff changeset
58 * Resume Arguments:: Specifying arguments when you resume a running Emacs.
Dave Love <fx@gnu.org>
parents:
diff changeset
59 * Environment:: Environment variables that Emacs uses.
Dave Love <fx@gnu.org>
parents:
diff changeset
60
Dave Love <fx@gnu.org>
parents:
diff changeset
61 * Display X:: Changing the default display and using remote login.
Dave Love <fx@gnu.org>
parents:
diff changeset
62 * Font X:: Choosing a font for text, under X.
Dave Love <fx@gnu.org>
parents:
diff changeset
63 * Colors X:: Choosing colors, under X.
Dave Love <fx@gnu.org>
parents:
diff changeset
64 * Window Size X:: Start-up window size, under X.
Dave Love <fx@gnu.org>
parents:
diff changeset
65 * Borders X:: Internal and external borders, under X.
Dave Love <fx@gnu.org>
parents:
diff changeset
66 * Title X:: Specifying the initial frame's title.
Dave Love <fx@gnu.org>
parents:
diff changeset
67 * Icons X:: Choosing what sort of icon to use, under X.
Dave Love <fx@gnu.org>
parents:
diff changeset
68 * Resources X:: Advanced use of classes and resources, under X.
Dave Love <fx@gnu.org>
parents:
diff changeset
69 * Lucid Resources:: X resources for Lucid menus.
Dave Love <fx@gnu.org>
parents:
diff changeset
70 * Motif Resources:: X resources for Motif menus.
Dave Love <fx@gnu.org>
parents:
diff changeset
71 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
72
Dave Love <fx@gnu.org>
parents:
diff changeset
73 @node Action Arguments
Dave Love <fx@gnu.org>
parents:
diff changeset
74 @appendixsec Action Arguments
Dave Love <fx@gnu.org>
parents:
diff changeset
75
Dave Love <fx@gnu.org>
parents:
diff changeset
76 Here is a table of the action arguments and options:
Dave Love <fx@gnu.org>
parents:
diff changeset
77
Dave Love <fx@gnu.org>
parents:
diff changeset
78 @table @samp
Dave Love <fx@gnu.org>
parents:
diff changeset
79 @item @var{file}
26236
4f74d4393e52 Add description of --execute and --file.
Gerd Moellmann <gerd@gnu.org>
parents: 26140
diff changeset
80 @itemx --visit @var{file}
4f74d4393e52 Add description of --execute and --file.
Gerd Moellmann <gerd@gnu.org>
parents: 26140
diff changeset
81 @itemx --file @var{file}
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
82 Visit @var{file} using @code{find-file}. @xref{Visiting}.
Dave Love <fx@gnu.org>
parents:
diff changeset
83
Dave Love <fx@gnu.org>
parents:
diff changeset
84 @item +@var{linenum} @var{file}
Dave Love <fx@gnu.org>
parents:
diff changeset
85 Visit @var{file} using @code{find-file}, then go to line number
Dave Love <fx@gnu.org>
parents:
diff changeset
86 @var{linenum} in it.
Dave Love <fx@gnu.org>
parents:
diff changeset
87
Dave Love <fx@gnu.org>
parents:
diff changeset
88 @need 3000
Dave Love <fx@gnu.org>
parents:
diff changeset
89 @item -l @var{file}
Dave Love <fx@gnu.org>
parents:
diff changeset
90 @itemx --load=@var{file}
Dave Love <fx@gnu.org>
parents:
diff changeset
91 Load a Lisp library named @var{file} with the function @code{load}.
Dave Love <fx@gnu.org>
parents:
diff changeset
92 @xref{Lisp Libraries}. The library can be found either in the current
Dave Love <fx@gnu.org>
parents:
diff changeset
93 directory, or in the Emacs library search path as specified
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26236
diff changeset
94 with @env{EMACSLOADPATH} (@pxref{General Variables}).
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
95
Dave Love <fx@gnu.org>
parents:
diff changeset
96 @item -f @var{function}
Dave Love <fx@gnu.org>
parents:
diff changeset
97 @itemx --funcall=@var{function}
Dave Love <fx@gnu.org>
parents:
diff changeset
98 Call Lisp function @var{function} with no arguments.
Dave Love <fx@gnu.org>
parents:
diff changeset
99
Dave Love <fx@gnu.org>
parents:
diff changeset
100 @item --eval @var{expression}
26236
4f74d4393e52 Add description of --execute and --file.
Gerd Moellmann <gerd@gnu.org>
parents: 26140
diff changeset
101 @itemx --execute @var{expression}
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
102 Evaluate Lisp expression @var{expression}.
Dave Love <fx@gnu.org>
parents:
diff changeset
103
Dave Love <fx@gnu.org>
parents:
diff changeset
104 @item --insert=@var{file}
Dave Love <fx@gnu.org>
parents:
diff changeset
105 Insert the contents of @var{file} into the current buffer. This is like
Dave Love <fx@gnu.org>
parents:
diff changeset
106 what @kbd{M-x insert-file} does. @xref{Misc File Ops}.
Dave Love <fx@gnu.org>
parents:
diff changeset
107
Dave Love <fx@gnu.org>
parents:
diff changeset
108 @item --kill
Dave Love <fx@gnu.org>
parents:
diff changeset
109 Exit from Emacs without asking for confirmation.
Dave Love <fx@gnu.org>
parents:
diff changeset
110 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
111
Dave Love <fx@gnu.org>
parents:
diff changeset
112 @vindex command-line-args
Dave Love <fx@gnu.org>
parents:
diff changeset
113 The init file can access the values of the action arguments as the
Dave Love <fx@gnu.org>
parents:
diff changeset
114 elements of a list in the variable @code{command-line-args}. The init
Dave Love <fx@gnu.org>
parents:
diff changeset
115 file can override the normal processing of the action arguments, or
Dave Love <fx@gnu.org>
parents:
diff changeset
116 define new ones, by reading and setting this variable.
Dave Love <fx@gnu.org>
parents:
diff changeset
117
Dave Love <fx@gnu.org>
parents:
diff changeset
118 @node Initial Options
Dave Love <fx@gnu.org>
parents:
diff changeset
119 @appendixsec Initial Options
Dave Love <fx@gnu.org>
parents:
diff changeset
120
Dave Love <fx@gnu.org>
parents:
diff changeset
121 The initial options specify parameters for the Emacs session. This
Dave Love <fx@gnu.org>
parents:
diff changeset
122 section describes the more general initial options; some other options
35188
94d46968a93f Don't say "X Windows". From Colin Walters <walters@cis.ohio-state.edu>.
Eli Zaretskii <eliz@gnu.org>
parents: 34221
diff changeset
123 specifically related to the X Window System appear in the following
94d46968a93f Don't say "X Windows". From Colin Walters <walters@cis.ohio-state.edu>.
Eli Zaretskii <eliz@gnu.org>
parents: 34221
diff changeset
124 sections.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
125
Dave Love <fx@gnu.org>
parents:
diff changeset
126 Some initial options affect the loading of init files. The normal
Dave Love <fx@gnu.org>
parents:
diff changeset
127 actions of Emacs are to first load @file{site-start.el} if it exists,
Dave Love <fx@gnu.org>
parents:
diff changeset
128 then your own init file @file{~/.emacs} if it exists, and finally
Dave Love <fx@gnu.org>
parents:
diff changeset
129 @file{default.el} if it exists; certain options prevent loading of some
Dave Love <fx@gnu.org>
parents:
diff changeset
130 of these files or substitute other files for them.
Dave Love <fx@gnu.org>
parents:
diff changeset
131
Dave Love <fx@gnu.org>
parents:
diff changeset
132 @table @samp
Dave Love <fx@gnu.org>
parents:
diff changeset
133 @item -t @var{device}
Dave Love <fx@gnu.org>
parents:
diff changeset
134 @itemx --terminal=@var{device}
Dave Love <fx@gnu.org>
parents:
diff changeset
135 Use @var{device} as the device for terminal input and output.
Dave Love <fx@gnu.org>
parents:
diff changeset
136
Dave Love <fx@gnu.org>
parents:
diff changeset
137 @item -d @var{display}
Dave Love <fx@gnu.org>
parents:
diff changeset
138 @itemx --display=@var{display}
Dave Love <fx@gnu.org>
parents:
diff changeset
139 Use the X Window System and use the display named @var{display} to open
Dave Love <fx@gnu.org>
parents:
diff changeset
140 the initial Emacs frame.
Dave Love <fx@gnu.org>
parents:
diff changeset
141
Dave Love <fx@gnu.org>
parents:
diff changeset
142 @item -nw
Dave Love <fx@gnu.org>
parents:
diff changeset
143 @itemx --no-windows
33012
df207c5f631f (Colors X): Document support for -fg, -bg, and -rv
Eli Zaretskii <eliz@gnu.org>
parents: 31169
diff changeset
144 Don't communicate directly with the window system, disregarding the
df207c5f631f (Colors X): Document support for -fg, -bg, and -rv
Eli Zaretskii <eliz@gnu.org>
parents: 31169
diff changeset
145 @env{DISPLAY} environment variable even if it is set. This forces Emacs
df207c5f631f (Colors X): Document support for -fg, -bg, and -rv
Eli Zaretskii <eliz@gnu.org>
parents: 31169
diff changeset
146 to run as if the display were a character terminal.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
147
Dave Love <fx@gnu.org>
parents:
diff changeset
148 @need 3000
Dave Love <fx@gnu.org>
parents:
diff changeset
149 @cindex batch mode
Dave Love <fx@gnu.org>
parents:
diff changeset
150 @item -batch
Dave Love <fx@gnu.org>
parents:
diff changeset
151 @itemx --batch
Dave Love <fx@gnu.org>
parents:
diff changeset
152 Run Emacs in @dfn{batch mode}, which means that the text being edited is
Dave Love <fx@gnu.org>
parents:
diff changeset
153 not displayed and the standard terminal interrupt characters such as
Dave Love <fx@gnu.org>
parents:
diff changeset
154 @kbd{C-z} and @kbd{C-c} continue to have their normal effect. Emacs in
Dave Love <fx@gnu.org>
parents:
diff changeset
155 batch mode outputs to @code{stderr} only what would normally be printed
Dave Love <fx@gnu.org>
parents:
diff changeset
156 in the echo area under program control.
Dave Love <fx@gnu.org>
parents:
diff changeset
157
Dave Love <fx@gnu.org>
parents:
diff changeset
158 Batch mode is used for running programs written in Emacs Lisp from
Dave Love <fx@gnu.org>
parents:
diff changeset
159 shell scripts, makefiles, and so on. Normally the @samp{-l} option
Dave Love <fx@gnu.org>
parents:
diff changeset
160 or @samp{-f} option will be used as well, to invoke a Lisp program
Dave Love <fx@gnu.org>
parents:
diff changeset
161 to do the batch processing.
Dave Love <fx@gnu.org>
parents:
diff changeset
162
Dave Love <fx@gnu.org>
parents:
diff changeset
163 @samp{-batch} implies @samp{-q} (do not load an init file). It also causes
Dave Love <fx@gnu.org>
parents:
diff changeset
164 Emacs to kill itself after all command options have been processed. In
Dave Love <fx@gnu.org>
parents:
diff changeset
165 addition, auto-saving is not done except in buffers for which it has been
Dave Love <fx@gnu.org>
parents:
diff changeset
166 explicitly requested.
Dave Love <fx@gnu.org>
parents:
diff changeset
167
Dave Love <fx@gnu.org>
parents:
diff changeset
168 @item -q
Dave Love <fx@gnu.org>
parents:
diff changeset
169 @itemx --no-init-file
Dave Love <fx@gnu.org>
parents:
diff changeset
170 Do not load your Emacs init file @file{~/.emacs}, or @file{default.el}
Dave Love <fx@gnu.org>
parents:
diff changeset
171 either.
Dave Love <fx@gnu.org>
parents:
diff changeset
172
Dave Love <fx@gnu.org>
parents:
diff changeset
173 @item --no-site-file
Dave Love <fx@gnu.org>
parents:
diff changeset
174 Do not load @file{site-start.el}. The options @samp{-q}, @samp{-u}
Dave Love <fx@gnu.org>
parents:
diff changeset
175 and @samp{-batch} have no effect on the loading of this file---this is
Dave Love <fx@gnu.org>
parents:
diff changeset
176 the only option that blocks it.
Dave Love <fx@gnu.org>
parents:
diff changeset
177
Dave Love <fx@gnu.org>
parents:
diff changeset
178 @item -u @var{user}
Dave Love <fx@gnu.org>
parents:
diff changeset
179 @itemx --user=@var{user}
Dave Love <fx@gnu.org>
parents:
diff changeset
180 Load @var{user}'s Emacs init file @file{~@var{user}/.emacs} instead of
Dave Love <fx@gnu.org>
parents:
diff changeset
181 your own.
Dave Love <fx@gnu.org>
parents:
diff changeset
182
Dave Love <fx@gnu.org>
parents:
diff changeset
183 @item --debug-init
Dave Love <fx@gnu.org>
parents:
diff changeset
184 Enable the Emacs Lisp debugger for errors in the init file.
Dave Love <fx@gnu.org>
parents:
diff changeset
185
Dave Love <fx@gnu.org>
parents:
diff changeset
186 @item --unibyte
31142
7d0a8b91a6c0 Mention that Lisp files are normally read as multibyte.
Eli Zaretskii <eliz@gnu.org>
parents: 30967
diff changeset
187 @cindex unibyte operation, command-line argument
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
188 Set up to do almost everything with single-byte buffers and strings.
Dave Love <fx@gnu.org>
parents:
diff changeset
189 All buffers and strings are unibyte unless you (or a Lisp program)
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
190 explicitly ask for a multibyte buffer or string. (Note that Emacs
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
191 always loads Lisp files in multibyte mode, even if @samp{--unibyte} is
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
192 specified; see @ref{Enabling Multibyte}.) Setting the environment
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
193 variable @env{EMACS_UNIBYTE} has the same effect.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
194
Dave Love <fx@gnu.org>
parents:
diff changeset
195 @item --multibyte
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26236
diff changeset
196 Inhibit the effect of @env{EMACS_UNIBYTE}, so that Emacs
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
197 uses multibyte characters by default, as usual.
Dave Love <fx@gnu.org>
parents:
diff changeset
198 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
199
Dave Love <fx@gnu.org>
parents:
diff changeset
200 @node Command Example
Dave Love <fx@gnu.org>
parents:
diff changeset
201 @appendixsec Command Argument Example
Dave Love <fx@gnu.org>
parents:
diff changeset
202
Dave Love <fx@gnu.org>
parents:
diff changeset
203 Here is an example of using Emacs with arguments and options. It
Dave Love <fx@gnu.org>
parents:
diff changeset
204 assumes you have a Lisp program file called @file{hack-c.el} which, when
Dave Love <fx@gnu.org>
parents:
diff changeset
205 loaded, performs some useful operation on the current buffer, expected
Dave Love <fx@gnu.org>
parents:
diff changeset
206 to be a C program.
Dave Love <fx@gnu.org>
parents:
diff changeset
207
Dave Love <fx@gnu.org>
parents:
diff changeset
208 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
209 emacs -batch foo.c -l hack-c -f save-buffer >& log
Dave Love <fx@gnu.org>
parents:
diff changeset
210 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
211
Dave Love <fx@gnu.org>
parents:
diff changeset
212 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
213 This says to visit @file{foo.c}, load @file{hack-c.el} (which makes
Dave Love <fx@gnu.org>
parents:
diff changeset
214 changes in the visited file), save @file{foo.c} (note that
Dave Love <fx@gnu.org>
parents:
diff changeset
215 @code{save-buffer} is the function that @kbd{C-x C-s} is bound to), and
Dave Love <fx@gnu.org>
parents:
diff changeset
216 then exit back to the shell (because of @samp{-batch}). @samp{-batch}
Dave Love <fx@gnu.org>
parents:
diff changeset
217 also guarantees there will be no problem redirecting output to
Dave Love <fx@gnu.org>
parents:
diff changeset
218 @file{log}, because Emacs will not assume that it has a display terminal
Dave Love <fx@gnu.org>
parents:
diff changeset
219 to work with.
Dave Love <fx@gnu.org>
parents:
diff changeset
220
Dave Love <fx@gnu.org>
parents:
diff changeset
221 @node Resume Arguments
Dave Love <fx@gnu.org>
parents:
diff changeset
222 @appendixsec Resuming Emacs with Arguments
Dave Love <fx@gnu.org>
parents:
diff changeset
223
Dave Love <fx@gnu.org>
parents:
diff changeset
224 You can specify action arguments for Emacs when you resume it after
Dave Love <fx@gnu.org>
parents:
diff changeset
225 a suspension. To prepare for this, put the following code in your
Dave Love <fx@gnu.org>
parents:
diff changeset
226 @file{.emacs} file (@pxref{Hooks}):
Dave Love <fx@gnu.org>
parents:
diff changeset
227
Dave Love <fx@gnu.org>
parents:
diff changeset
228 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
229 (add-hook 'suspend-hook 'resume-suspend-hook)
Dave Love <fx@gnu.org>
parents:
diff changeset
230 (add-hook 'suspend-resume-hook 'resume-process-args)
Dave Love <fx@gnu.org>
parents:
diff changeset
231 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
232
Dave Love <fx@gnu.org>
parents:
diff changeset
233 As further preparation, you must execute the shell script
Dave Love <fx@gnu.org>
parents:
diff changeset
234 @file{emacs.csh} (if you use csh as your shell) or @file{emacs.bash} (if
Dave Love <fx@gnu.org>
parents:
diff changeset
235 you use bash as your shell). These scripts define an alias named
Dave Love <fx@gnu.org>
parents:
diff changeset
236 @code{edit}, which will resume Emacs giving it new command line
Dave Love <fx@gnu.org>
parents:
diff changeset
237 arguments such as files to visit.
Dave Love <fx@gnu.org>
parents:
diff changeset
238
Dave Love <fx@gnu.org>
parents:
diff changeset
239 Only action arguments work properly when you resume Emacs. Initial
Dave Love <fx@gnu.org>
parents:
diff changeset
240 arguments are not recognized---it's too late to execute them anyway.
Dave Love <fx@gnu.org>
parents:
diff changeset
241
Dave Love <fx@gnu.org>
parents:
diff changeset
242 Note that resuming Emacs (with or without arguments) must be done from
Dave Love <fx@gnu.org>
parents:
diff changeset
243 within the shell that is the parent of the Emacs job. This is why
Dave Love <fx@gnu.org>
parents:
diff changeset
244 @code{edit} is an alias rather than a program or a shell script. It is
Dave Love <fx@gnu.org>
parents:
diff changeset
245 not possible to implement a resumption command that could be run from
Dave Love <fx@gnu.org>
parents:
diff changeset
246 other subjobs of the shell; no way to define a command that could be
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26236
diff changeset
247 made the value of @env{EDITOR}, for example. Therefore, this feature
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
248 does not take the place of the Emacs Server feature (@pxref{Emacs
Dave Love <fx@gnu.org>
parents:
diff changeset
249 Server}).
Dave Love <fx@gnu.org>
parents:
diff changeset
250
Dave Love <fx@gnu.org>
parents:
diff changeset
251 The aliases use the Emacs Server feature if you appear to have a
Dave Love <fx@gnu.org>
parents:
diff changeset
252 server Emacs running. However, they cannot determine this with complete
Dave Love <fx@gnu.org>
parents:
diff changeset
253 accuracy. They may think that a server is still running when in
Dave Love <fx@gnu.org>
parents:
diff changeset
254 actuality you have killed that Emacs, because the file
Dave Love <fx@gnu.org>
parents:
diff changeset
255 @file{/tmp/.esrv@dots{}} still exists. If this happens, find that
Dave Love <fx@gnu.org>
parents:
diff changeset
256 file and delete it.
Dave Love <fx@gnu.org>
parents:
diff changeset
257
Dave Love <fx@gnu.org>
parents:
diff changeset
258 @node Environment
Dave Love <fx@gnu.org>
parents:
diff changeset
259 @appendixsec Environment Variables
Dave Love <fx@gnu.org>
parents:
diff changeset
260 @cindex environment variables
Dave Love <fx@gnu.org>
parents:
diff changeset
261
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
262 The @dfn{environment} is a feature of the operating system; it
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
263 consists of a collection of variables with names and values. Each
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
264 variable is called an @dfn{environment variable}; environment variable
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
265 names are case-sensitive, and it is conventional to use upper case
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
266 letters only. The values are all text strings.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
267
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
268 What makes the environment useful is that subprocesses inherit the
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
269 environment automatically from their parent process. This means you
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
270 can set up an environment variable in your login shell, and all the
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
271 programs you run (including Emacs) will automatically see it.
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
272 Subprocesses of Emacs (such as shells, compilers, and version-control
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
273 software) inherit the environment from Emacs, too.
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
274
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
275 @findex setenv
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
276 @findex getenv
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
277 Inside Emacs, the command @kbd{M-x getenv} gets the value of an
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
278 environment variable. @kbd{M-x setenv} sets a variable in the Emacs
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
279 environment. The way to set environment variables outside of Emacs
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
280 depends on the operating system, and especially the shell that you are
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
281 using. For example, here's how to set the environment variable
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
282 @env{ORGANIZATION} to @samp{not very much} using Bash:
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
283
Dave Love <fx@gnu.org>
parents:
diff changeset
284 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
285 export ORGANIZATION="not very much"
Dave Love <fx@gnu.org>
parents:
diff changeset
286 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
287
Dave Love <fx@gnu.org>
parents:
diff changeset
288 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
289 and here's how to do it in csh or tcsh:
Dave Love <fx@gnu.org>
parents:
diff changeset
290
Dave Love <fx@gnu.org>
parents:
diff changeset
291 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
292 setenv ORGANIZATION "not very much"
Dave Love <fx@gnu.org>
parents:
diff changeset
293 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
294
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
295 When Emacs is set-up to use the X Window System, it inherits the use
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
296 of a large number of environment variables from the X libraries. See
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
297 the X documentation for more information.
Dave Love <fx@gnu.org>
parents:
diff changeset
298
Dave Love <fx@gnu.org>
parents:
diff changeset
299 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
300 * General Variables:: Environment variables that all versions of Emacs use.
Dave Love <fx@gnu.org>
parents:
diff changeset
301 * Misc Variables:: Certain system-specific variables.
Dave Love <fx@gnu.org>
parents:
diff changeset
302 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
303
Dave Love <fx@gnu.org>
parents:
diff changeset
304 @node General Variables
Dave Love <fx@gnu.org>
parents:
diff changeset
305 @appendixsubsec General Variables
Dave Love <fx@gnu.org>
parents:
diff changeset
306
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
307 Here is an alphabetical list of specific environment variables that
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
308 have special meanings in Emacs, giving the name of each variable and
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
309 its meaning. Most of these variables are also used by some other
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
310 programs. Emacs does not require any of these environment variables
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
311 to be set, but it uses their values if they are set.
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
312
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26236
diff changeset
313 @table @env
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
314 @item AUTHORCOPY
Dave Love <fx@gnu.org>
parents:
diff changeset
315 The name of a file used to archive news articles posted with the @sc{gnus}
Dave Love <fx@gnu.org>
parents:
diff changeset
316 package.
Dave Love <fx@gnu.org>
parents:
diff changeset
317 @item CDPATH
Dave Love <fx@gnu.org>
parents:
diff changeset
318 Used by the @code{cd} command to search for the directory you specify,
Dave Love <fx@gnu.org>
parents:
diff changeset
319 when you specify a relative directory name.
Dave Love <fx@gnu.org>
parents:
diff changeset
320 @item DOMAINNAME
Dave Love <fx@gnu.org>
parents:
diff changeset
321 The name of the Internet domain that the machine running Emacs is
Dave Love <fx@gnu.org>
parents:
diff changeset
322 located in. Used by the @sc{gnus} package.
Dave Love <fx@gnu.org>
parents:
diff changeset
323 @item EMACS_UNIBYTE
31142
7d0a8b91a6c0 Mention that Lisp files are normally read as multibyte.
Eli Zaretskii <eliz@gnu.org>
parents: 30967
diff changeset
324 @cindex unibyte operation, environment variable
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
325 Defining this environment variable with a nonempty value directs Emacs
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
326 to do almost everything with single-byte buffers and strings. It is
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
327 equivalent to using the @samp{--unibyte} command-line option on each
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
328 invocation. @xref{Initial Options}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
329 @item EMACSDATA
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
330 Directory for the architecture-independent files that come with Emacs.
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
331 This is used to initialize the Lisp variable @code{data-directory}.
35490
2e4bf60771ea (General Variables): Document $EMACSDOC.
Eli Zaretskii <eliz@gnu.org>
parents: 35188
diff changeset
332 @item EMACSDOC
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
333 Directory for the documentation string file,
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
334 @file{DOC-@var{emacsversion}}. This is used to initialize the Lisp
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
335 variable @code{data-directory}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
336 @item EMACSLOADPATH
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
337 A colon-separated list of directories to search for Emacs Lisp
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
338 files---used to initialize @code{load-path}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
339 @item EMACSPATH
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
340 A colon-separated list of directories to search for executable
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
341 files---used to initialize @code{exec-path}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
342 @item ESHELL
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26236
diff changeset
343 Used for shell-mode to override the @env{SHELL} environment variable.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
344 @item HISTFILE
Dave Love <fx@gnu.org>
parents:
diff changeset
345 The name of the file that shell commands are saved in between logins.
Dave Love <fx@gnu.org>
parents:
diff changeset
346 This variable defaults to @file{~/.history} if you use (t)csh as shell,
Dave Love <fx@gnu.org>
parents:
diff changeset
347 to @file{~/.bash_history} if you use bash, to @file{~/.sh_history} if
Dave Love <fx@gnu.org>
parents:
diff changeset
348 you use ksh, and to @file{~/.history} otherwise.
Dave Love <fx@gnu.org>
parents:
diff changeset
349 @item HOME
Dave Love <fx@gnu.org>
parents:
diff changeset
350 The location of the user's files in the directory tree; used for
Dave Love <fx@gnu.org>
parents:
diff changeset
351 expansion of file names starting with a tilde (@file{~}). On MS-DOS, it
Dave Love <fx@gnu.org>
parents:
diff changeset
352 defaults to the directory from which Emacs was started, with @samp{/bin}
Dave Love <fx@gnu.org>
parents:
diff changeset
353 removed from the end if it was present.
Dave Love <fx@gnu.org>
parents:
diff changeset
354 @item HOSTNAME
Dave Love <fx@gnu.org>
parents:
diff changeset
355 The name of the machine that Emacs is running on.
Dave Love <fx@gnu.org>
parents:
diff changeset
356 @item INCPATH
Dave Love <fx@gnu.org>
parents:
diff changeset
357 A colon-separated list of directories. Used by the @code{complete} package
Dave Love <fx@gnu.org>
parents:
diff changeset
358 to search for files.
Dave Love <fx@gnu.org>
parents:
diff changeset
359 @item INFOPATH
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
360 A colon-separated list of directories to search for Info files in.
26140
068f7ad41d40 Describe new functions and variables for locales.
Paul Eggert <eggert@twinsun.com>
parents: 25829
diff changeset
361 @item LC_ALL
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
362 @itemx LC_CTYPE
26140
068f7ad41d40 Describe new functions and variables for locales.
Paul Eggert <eggert@twinsun.com>
parents: 25829
diff changeset
363 @itemx LANG
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
364 The user's preferred locale. (The first of these environment
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
365 variables with a nonempty value specifies the locale.) A locale name
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
366 which contains @samp{8859-@var{n}}, @samp{8859_@var{n}} or
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
367 @samp{8859@var{n}}, where @var{n} is between 1 and 4, automatically
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
368 specifies the @samp{Latin-@var{n}} language environment when Emacs
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
369 starts up. If @var{n} is 9, that specifies @samp{Latin-5}.
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
370
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
371 The locale value you specify with one of these three variables is
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
372 matched against entries in @code{locale-language-names},
26140
068f7ad41d40 Describe new functions and variables for locales.
Paul Eggert <eggert@twinsun.com>
parents: 25829
diff changeset
373 @code{locale-charset-language-names}, and
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
374 @code{locale-preferred-coding-systems}, to select a default language
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
375 environment and coding system. @xref{Language Environments}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
376 @item LOGNAME
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26236
diff changeset
377 The user's login name. See also @env{USER}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
378 @item MAIL
Dave Love <fx@gnu.org>
parents:
diff changeset
379 The name of the user's system mail inbox.
Dave Love <fx@gnu.org>
parents:
diff changeset
380 @item MAILRC
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
381 Name of file containing mail aliases. (The default is
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
382 @file{~/.mailrc}.)
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
383 @item MH
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
384 Name of setup file for the mh system. (The default is @file{~/.mh_profile}.)
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
385 @item NAME
Dave Love <fx@gnu.org>
parents:
diff changeset
386 The real-world name of the user.
Dave Love <fx@gnu.org>
parents:
diff changeset
387 @item NNTPSERVER
Dave Love <fx@gnu.org>
parents:
diff changeset
388 The name of the news server. Used by the mh and @sc{gnus} packages.
Dave Love <fx@gnu.org>
parents:
diff changeset
389 @item ORGANIZATION
Dave Love <fx@gnu.org>
parents:
diff changeset
390 The name of the organization to which you belong. Used for setting the
Dave Love <fx@gnu.org>
parents:
diff changeset
391 `Organization:' header in your posts from the @sc{gnus} package.
Dave Love <fx@gnu.org>
parents:
diff changeset
392 @item PATH
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
393 A colon-separated list of directories in which executables reside.
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
394 (On MS-DOS, it is semicolon-separated instead.) This is used to
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
395 initialize the Emacs Lisp variable @code{exec-path}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
396 @item PWD
Dave Love <fx@gnu.org>
parents:
diff changeset
397 If set, this should be the default directory when Emacs was started.
Dave Love <fx@gnu.org>
parents:
diff changeset
398 @item REPLYTO
Dave Love <fx@gnu.org>
parents:
diff changeset
399 If set, this specifies an initial value for the variable
Dave Love <fx@gnu.org>
parents:
diff changeset
400 @code{mail-default-reply-to}. @xref{Mail Headers}.
Dave Love <fx@gnu.org>
parents:
diff changeset
401 @item SAVEDIR
Dave Love <fx@gnu.org>
parents:
diff changeset
402 The name of a directory in which news articles are saved by default.
Dave Love <fx@gnu.org>
parents:
diff changeset
403 Used by the @sc{gnus} package.
Dave Love <fx@gnu.org>
parents:
diff changeset
404 @item SHELL
Dave Love <fx@gnu.org>
parents:
diff changeset
405 The name of an interpreter used to parse and execute programs run from
Dave Love <fx@gnu.org>
parents:
diff changeset
406 inside Emacs.
33017
4c7241b226fc Document that if $TERM says we are on xterm, the default background
Eli Zaretskii <eliz@gnu.org>
parents: 33012
diff changeset
407 @cindex background mode, on @code{xterm}
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
408 @item TERM
Dave Love <fx@gnu.org>
parents:
diff changeset
409 The name of the terminal that Emacs is running on. The variable must be
Dave Love <fx@gnu.org>
parents:
diff changeset
410 set unless Emacs is run in batch mode. On MS-DOS, it defaults to
Dave Love <fx@gnu.org>
parents:
diff changeset
411 @samp{internal}, which specifies a built-in terminal emulation that
33017
4c7241b226fc Document that if $TERM says we are on xterm, the default background
Eli Zaretskii <eliz@gnu.org>
parents: 33012
diff changeset
412 handles the machine's own display. If the value of @env{TERM} indicates
4c7241b226fc Document that if $TERM says we are on xterm, the default background
Eli Zaretskii <eliz@gnu.org>
parents: 33012
diff changeset
413 that Emacs runs in non-windowed mode from @code{xterm} or a similar
4c7241b226fc Document that if $TERM says we are on xterm, the default background
Eli Zaretskii <eliz@gnu.org>
parents: 33012
diff changeset
414 terminal emulator, the background mode defaults to @samp{light}, and
4c7241b226fc Document that if $TERM says we are on xterm, the default background
Eli Zaretskii <eliz@gnu.org>
parents: 33012
diff changeset
415 Emacs will choose colors that are appropriate for a light background.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
416 @item TERMCAP
Dave Love <fx@gnu.org>
parents:
diff changeset
417 The name of the termcap library file describing how to program the
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26236
diff changeset
418 terminal specified by the @env{TERM} variable. This defaults to
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
419 @file{/etc/termcap}.
Dave Love <fx@gnu.org>
parents:
diff changeset
420 @item TMPDIR
Dave Love <fx@gnu.org>
parents:
diff changeset
421 Used by the Emerge package as a prefix for temporary files.
Dave Love <fx@gnu.org>
parents:
diff changeset
422 @item TZ
Dave Love <fx@gnu.org>
parents:
diff changeset
423 This specifies the current time zone and possibly also daylight savings
Dave Love <fx@gnu.org>
parents:
diff changeset
424 information. On MS-DOS, the default is based on country code; see the
Dave Love <fx@gnu.org>
parents:
diff changeset
425 file @file{msdos.c} for details.
Dave Love <fx@gnu.org>
parents:
diff changeset
426 @item USER
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26236
diff changeset
427 The user's login name. See also @env{LOGNAME}. On MS-DOS, this
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
428 defaults to @samp{root}.
Dave Love <fx@gnu.org>
parents:
diff changeset
429 @item VERSION_CONTROL
Dave Love <fx@gnu.org>
parents:
diff changeset
430 Used to initialize the @code{version-control} variable (@pxref{Backup
Dave Love <fx@gnu.org>
parents:
diff changeset
431 Names}).
Dave Love <fx@gnu.org>
parents:
diff changeset
432 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
433
Dave Love <fx@gnu.org>
parents:
diff changeset
434 @node Misc Variables
Dave Love <fx@gnu.org>
parents:
diff changeset
435 @appendixsubsec Miscellaneous Variables
Dave Love <fx@gnu.org>
parents:
diff changeset
436
Dave Love <fx@gnu.org>
parents:
diff changeset
437 These variables are used only on particular configurations:
Dave Love <fx@gnu.org>
parents:
diff changeset
438
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26236
diff changeset
439 @table @env
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
440 @item COMSPEC
Dave Love <fx@gnu.org>
parents:
diff changeset
441 On MS-DOS, the name of the command interpreter to use. This is used to
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26236
diff changeset
442 make a default value for the @env{SHELL} environment variable.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
443
Dave Love <fx@gnu.org>
parents:
diff changeset
444 @item NAME
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26236
diff changeset
445 On MS-DOS, this variable defaults to the value of the @env{USER}
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
446 variable.
Dave Love <fx@gnu.org>
parents:
diff changeset
447
Dave Love <fx@gnu.org>
parents:
diff changeset
448 @item TEMP
Dave Love <fx@gnu.org>
parents:
diff changeset
449 @itemx TMP
Dave Love <fx@gnu.org>
parents:
diff changeset
450 On MS-DOS, these specify the name of the directory for storing temporary
Dave Love <fx@gnu.org>
parents:
diff changeset
451 files in.
Dave Love <fx@gnu.org>
parents:
diff changeset
452
Dave Love <fx@gnu.org>
parents:
diff changeset
453 @item EMACSTEST
Dave Love <fx@gnu.org>
parents:
diff changeset
454 On MS-DOS, this specifies a file to use to log the operation of the
Dave Love <fx@gnu.org>
parents:
diff changeset
455 internal terminal emulator. This feature is useful for submitting bug
Dave Love <fx@gnu.org>
parents:
diff changeset
456 reports.
Dave Love <fx@gnu.org>
parents:
diff changeset
457
Dave Love <fx@gnu.org>
parents:
diff changeset
458 @item EMACSCOLORS
Dave Love <fx@gnu.org>
parents:
diff changeset
459 Used on MS-DOS systems to set screen colors early, so that the screen
Dave Love <fx@gnu.org>
parents:
diff changeset
460 won't momentarily flash the default colors when Emacs starts up. The
Dave Love <fx@gnu.org>
parents:
diff changeset
461 value of this variable should be two-character encoding of the
Dave Love <fx@gnu.org>
parents:
diff changeset
462 foreground (the first character) and the background (the second
Dave Love <fx@gnu.org>
parents:
diff changeset
463 character) colors of the default face. Each character should be the
Dave Love <fx@gnu.org>
parents:
diff changeset
464 hexadecimal code for the desired color on a standard PC text-mode
Dave Love <fx@gnu.org>
parents:
diff changeset
465 display.
Dave Love <fx@gnu.org>
parents:
diff changeset
466
Dave Love <fx@gnu.org>
parents:
diff changeset
467 The PC display usually supports only eight background colors. However,
Dave Love <fx@gnu.org>
parents:
diff changeset
468 Emacs switches the DOS display to a mode where all 16 colors can be used
Dave Love <fx@gnu.org>
parents:
diff changeset
469 for the background, so all four bits of the background color are
Dave Love <fx@gnu.org>
parents:
diff changeset
470 actually used.
Dave Love <fx@gnu.org>
parents:
diff changeset
471
Dave Love <fx@gnu.org>
parents:
diff changeset
472 @item WINDOW_GFX
Dave Love <fx@gnu.org>
parents:
diff changeset
473 Used when initializing the Sun windows system.
Dave Love <fx@gnu.org>
parents:
diff changeset
474 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
475
Dave Love <fx@gnu.org>
parents:
diff changeset
476 @node Display X
Dave Love <fx@gnu.org>
parents:
diff changeset
477 @appendixsec Specifying the Display Name
35188
94d46968a93f Don't say "X Windows". From Colin Walters <walters@cis.ohio-state.edu>.
Eli Zaretskii <eliz@gnu.org>
parents: 34221
diff changeset
478 @cindex display name (X Window System)
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26236
diff changeset
479 @cindex @env{DISPLAY} environment variable
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
480
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26236
diff changeset
481 The environment variable @env{DISPLAY} tells all X clients, including
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
482 Emacs, where to display their windows. Its value is set up by default
Dave Love <fx@gnu.org>
parents:
diff changeset
483 in ordinary circumstances, when you start an X server and run jobs
Dave Love <fx@gnu.org>
parents:
diff changeset
484 locally. Occasionally you may need to specify the display yourself; for
Dave Love <fx@gnu.org>
parents:
diff changeset
485 example, if you do a remote login and want to run a client program
Dave Love <fx@gnu.org>
parents:
diff changeset
486 remotely, displaying on your local screen.
Dave Love <fx@gnu.org>
parents:
diff changeset
487
Dave Love <fx@gnu.org>
parents:
diff changeset
488 With Emacs, the main reason people change the default display is to
Dave Love <fx@gnu.org>
parents:
diff changeset
489 let them log into another system, run Emacs on that system, but have the
Dave Love <fx@gnu.org>
parents:
diff changeset
490 window displayed at their local terminal. You might need to use login
Dave Love <fx@gnu.org>
parents:
diff changeset
491 to another system because the files you want to edit are there, or
Dave Love <fx@gnu.org>
parents:
diff changeset
492 because the Emacs executable file you want to run is there.
Dave Love <fx@gnu.org>
parents:
diff changeset
493
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26236
diff changeset
494 The syntax of the @env{DISPLAY} environment variable is
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
495 @samp{@var{host}:@var{display}.@var{screen}}, where @var{host} is the
Dave Love <fx@gnu.org>
parents:
diff changeset
496 host name of the X Window System server machine, @var{display} is an
Dave Love <fx@gnu.org>
parents:
diff changeset
497 arbitrarily-assigned number that distinguishes your server (X terminal)
Dave Love <fx@gnu.org>
parents:
diff changeset
498 from other servers on the same machine, and @var{screen} is a
Dave Love <fx@gnu.org>
parents:
diff changeset
499 rarely-used field that allows an X server to control multiple terminal
Dave Love <fx@gnu.org>
parents:
diff changeset
500 screens. The period and the @var{screen} field are optional. If
Dave Love <fx@gnu.org>
parents:
diff changeset
501 included, @var{screen} is usually zero.
Dave Love <fx@gnu.org>
parents:
diff changeset
502
Dave Love <fx@gnu.org>
parents:
diff changeset
503 For example, if your host is named @samp{glasperle} and your server is
Dave Love <fx@gnu.org>
parents:
diff changeset
504 the first (or perhaps the only) server listed in the configuration, your
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26236
diff changeset
505 @env{DISPLAY} is @samp{glasperle:0.0}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
506
Dave Love <fx@gnu.org>
parents:
diff changeset
507 You can specify the display name explicitly when you run Emacs, either
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 26236
diff changeset
508 by changing the @env{DISPLAY} variable, or with the option @samp{-d
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
509 @var{display}} or @samp{--display=@var{display}}. Here is an example:
Dave Love <fx@gnu.org>
parents:
diff changeset
510
Dave Love <fx@gnu.org>
parents:
diff changeset
511 @smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
512 emacs --display=glasperle:0 &
Dave Love <fx@gnu.org>
parents:
diff changeset
513 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
514
Dave Love <fx@gnu.org>
parents:
diff changeset
515 You can inhibit the direct use of X with the @samp{-nw} option. This
Dave Love <fx@gnu.org>
parents:
diff changeset
516 is also an initial option. It tells Emacs to display using ordinary
Dave Love <fx@gnu.org>
parents:
diff changeset
517 ASCII on its controlling terminal.
Dave Love <fx@gnu.org>
parents:
diff changeset
518
Dave Love <fx@gnu.org>
parents:
diff changeset
519 Sometimes, security arrangements prevent a program on a remote system
Dave Love <fx@gnu.org>
parents:
diff changeset
520 from displaying on your local system. In this case, trying to run Emacs
Dave Love <fx@gnu.org>
parents:
diff changeset
521 produces messages like this:
Dave Love <fx@gnu.org>
parents:
diff changeset
522
Dave Love <fx@gnu.org>
parents:
diff changeset
523 @smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
524 Xlib: connection to "glasperle:0.0" refused by server
Dave Love <fx@gnu.org>
parents:
diff changeset
525 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
526
Dave Love <fx@gnu.org>
parents:
diff changeset
527 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
528 You might be able to overcome this problem by using the @code{xhost}
Dave Love <fx@gnu.org>
parents:
diff changeset
529 command on the local system to give permission for access from your
Dave Love <fx@gnu.org>
parents:
diff changeset
530 remote machine.
Dave Love <fx@gnu.org>
parents:
diff changeset
531
Dave Love <fx@gnu.org>
parents:
diff changeset
532 @node Font X
Dave Love <fx@gnu.org>
parents:
diff changeset
533 @appendixsec Font Specification Options
35188
94d46968a93f Don't say "X Windows". From Colin Walters <walters@cis.ohio-state.edu>.
Eli Zaretskii <eliz@gnu.org>
parents: 34221
diff changeset
534 @cindex font name (X Window System)
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
535
Dave Love <fx@gnu.org>
parents:
diff changeset
536 By default, Emacs displays text in the font named @samp{9x15}, which
Dave Love <fx@gnu.org>
parents:
diff changeset
537 makes each character nine pixels wide and fifteen pixels high. You can
Dave Love <fx@gnu.org>
parents:
diff changeset
538 specify a different font on your command line through the option
Dave Love <fx@gnu.org>
parents:
diff changeset
539 @samp{-fn @var{name}}.
Dave Love <fx@gnu.org>
parents:
diff changeset
540
Dave Love <fx@gnu.org>
parents:
diff changeset
541 @table @samp
Dave Love <fx@gnu.org>
parents:
diff changeset
542 @item -fn @var{name}
Dave Love <fx@gnu.org>
parents:
diff changeset
543 Use font @var{name} as the default font.
Dave Love <fx@gnu.org>
parents:
diff changeset
544
Dave Love <fx@gnu.org>
parents:
diff changeset
545 @item --font=@var{name}
Dave Love <fx@gnu.org>
parents:
diff changeset
546 @samp{--font} is an alias for @samp{-fn}.
Dave Love <fx@gnu.org>
parents:
diff changeset
547 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
548
Dave Love <fx@gnu.org>
parents:
diff changeset
549 Under X, each font has a long name which consists of eleven words or
Dave Love <fx@gnu.org>
parents:
diff changeset
550 numbers, separated by dashes. Some fonts also have shorter
Dave Love <fx@gnu.org>
parents:
diff changeset
551 nicknames---@samp{9x15} is such a nickname. You can use either kind of
Dave Love <fx@gnu.org>
parents:
diff changeset
552 name. You can use wildcard patterns for the font name; then Emacs lets
Dave Love <fx@gnu.org>
parents:
diff changeset
553 X choose one of the fonts that match the pattern. Here is an example,
Dave Love <fx@gnu.org>
parents:
diff changeset
554 which happens to specify the font whose nickname is @samp{6x13}:
Dave Love <fx@gnu.org>
parents:
diff changeset
555
Dave Love <fx@gnu.org>
parents:
diff changeset
556 @smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
557 emacs -fn "-misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1" &
Dave Love <fx@gnu.org>
parents:
diff changeset
558 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
559
Dave Love <fx@gnu.org>
parents:
diff changeset
560 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
561 You can also specify the font in your @file{.Xdefaults} file:
Dave Love <fx@gnu.org>
parents:
diff changeset
562
Dave Love <fx@gnu.org>
parents:
diff changeset
563 @smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
564 emacs.font: -misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1
Dave Love <fx@gnu.org>
parents:
diff changeset
565 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
566
Dave Love <fx@gnu.org>
parents:
diff changeset
567 A long font name has the following form:
Dave Love <fx@gnu.org>
parents:
diff changeset
568
Dave Love <fx@gnu.org>
parents:
diff changeset
569 @smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
570 -@var{maker}-@var{family}-@var{weight}-@var{slant}-@var{widthtype}-@var{style}@dots{}
Dave Love <fx@gnu.org>
parents:
diff changeset
571 @dots{}-@var{pixels}-@var{height}-@var{horiz}-@var{vert}-@var{spacing}-@var{width}-@var{charset}
Dave Love <fx@gnu.org>
parents:
diff changeset
572 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
573
Dave Love <fx@gnu.org>
parents:
diff changeset
574 @table @var
Dave Love <fx@gnu.org>
parents:
diff changeset
575 @item family
Dave Love <fx@gnu.org>
parents:
diff changeset
576 This is the name of the font family---for example, @samp{courier}.
Dave Love <fx@gnu.org>
parents:
diff changeset
577 @item weight
Dave Love <fx@gnu.org>
parents:
diff changeset
578 This is normally @samp{bold}, @samp{medium} or @samp{light}. Other
Dave Love <fx@gnu.org>
parents:
diff changeset
579 words may appear here in some font names.
Dave Love <fx@gnu.org>
parents:
diff changeset
580 @item slant
Dave Love <fx@gnu.org>
parents:
diff changeset
581 This is @samp{r} (roman), @samp{i} (italic), @samp{o} (oblique),
Dave Love <fx@gnu.org>
parents:
diff changeset
582 @samp{ri} (reverse italic), or @samp{ot} (other).
Dave Love <fx@gnu.org>
parents:
diff changeset
583 @item widthtype
Dave Love <fx@gnu.org>
parents:
diff changeset
584 This is normally @samp{condensed}, @samp{extended}, @samp{semicondensed}
Dave Love <fx@gnu.org>
parents:
diff changeset
585 or @samp{normal}. Other words may appear here in some font names.
Dave Love <fx@gnu.org>
parents:
diff changeset
586 @item style
Dave Love <fx@gnu.org>
parents:
diff changeset
587 This is an optional additional style name. Usually it is empty---most
Dave Love <fx@gnu.org>
parents:
diff changeset
588 long font names have two hyphens in a row at this point.
Dave Love <fx@gnu.org>
parents:
diff changeset
589 @item pixels
Dave Love <fx@gnu.org>
parents:
diff changeset
590 This is the font height, in pixels.
Dave Love <fx@gnu.org>
parents:
diff changeset
591 @item height
Dave Love <fx@gnu.org>
parents:
diff changeset
592 This is the font height on the screen, measured in tenths of a printer's
Dave Love <fx@gnu.org>
parents:
diff changeset
593 point---approximately 1/720 of an inch. In other words, it is the point
Dave Love <fx@gnu.org>
parents:
diff changeset
594 size of the font, times ten. For a given vertical resolution,
Dave Love <fx@gnu.org>
parents:
diff changeset
595 @var{height} and @var{pixels} are proportional; therefore, it is common
Dave Love <fx@gnu.org>
parents:
diff changeset
596 to specify just one of them and use @samp{*} for the other.
Dave Love <fx@gnu.org>
parents:
diff changeset
597 @item horiz
Dave Love <fx@gnu.org>
parents:
diff changeset
598 This is the horizontal resolution, in pixels per inch, of the screen for
Dave Love <fx@gnu.org>
parents:
diff changeset
599 which the font is intended.
Dave Love <fx@gnu.org>
parents:
diff changeset
600 @item vert
Dave Love <fx@gnu.org>
parents:
diff changeset
601 This is the vertical resolution, in dots per inch, of the screen for
Dave Love <fx@gnu.org>
parents:
diff changeset
602 which the font is intended. Normally the resolution of the fonts on
Dave Love <fx@gnu.org>
parents:
diff changeset
603 your system is the right value for your screen; therefore, you normally
Dave Love <fx@gnu.org>
parents:
diff changeset
604 specify @samp{*} for this and @var{horiz}.
Dave Love <fx@gnu.org>
parents:
diff changeset
605 @item spacing
Dave Love <fx@gnu.org>
parents:
diff changeset
606 This is @samp{m} (monospace), @samp{p} (proportional) or @samp{c}
Dave Love <fx@gnu.org>
parents:
diff changeset
607 (character cell). Emacs can use @samp{m} and @samp{c} fonts.
Dave Love <fx@gnu.org>
parents:
diff changeset
608 @item width
Dave Love <fx@gnu.org>
parents:
diff changeset
609 This is the average character width, in pixels, multiplied by ten.
Dave Love <fx@gnu.org>
parents:
diff changeset
610 @item charset
Dave Love <fx@gnu.org>
parents:
diff changeset
611 This is the character set that the font depicts.
Dave Love <fx@gnu.org>
parents:
diff changeset
612 Normally you should use @samp{iso8859-1}.
Dave Love <fx@gnu.org>
parents:
diff changeset
613 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
614
Dave Love <fx@gnu.org>
parents:
diff changeset
615 Use only fixed-width fonts---that is, fonts in which all characters
Dave Love <fx@gnu.org>
parents:
diff changeset
616 have the same width; Emacs cannot yet handle display properly for
Dave Love <fx@gnu.org>
parents:
diff changeset
617 variable-width fonts. Any font with @samp{m} or @samp{c} in the
Dave Love <fx@gnu.org>
parents:
diff changeset
618 @var{spacing} field of the long name is a fixed-width font. Here's how
Dave Love <fx@gnu.org>
parents:
diff changeset
619 to use the @code{xlsfonts} program to list all the fixed-width fonts
Dave Love <fx@gnu.org>
parents:
diff changeset
620 available on your system:
Dave Love <fx@gnu.org>
parents:
diff changeset
621
Dave Love <fx@gnu.org>
parents:
diff changeset
622 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
623 xlsfonts -fn '*x*' | egrep "^[0-9]+x[0-9]+"
Dave Love <fx@gnu.org>
parents:
diff changeset
624 xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-m*'
Dave Love <fx@gnu.org>
parents:
diff changeset
625 xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-c*'
Dave Love <fx@gnu.org>
parents:
diff changeset
626 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
627
Dave Love <fx@gnu.org>
parents:
diff changeset
628 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
629 To see what a particular font looks like, use the @code{xfd} command.
Dave Love <fx@gnu.org>
parents:
diff changeset
630 For example:
Dave Love <fx@gnu.org>
parents:
diff changeset
631
Dave Love <fx@gnu.org>
parents:
diff changeset
632 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
633 xfd -fn 6x13
Dave Love <fx@gnu.org>
parents:
diff changeset
634 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
635
Dave Love <fx@gnu.org>
parents:
diff changeset
636 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
637 displays the entire font @samp{6x13}.
Dave Love <fx@gnu.org>
parents:
diff changeset
638
Dave Love <fx@gnu.org>
parents:
diff changeset
639 While running Emacs, you can set the font of the current frame
Dave Love <fx@gnu.org>
parents:
diff changeset
640 (@pxref{Frame Parameters}) or for a specific kind of text
Dave Love <fx@gnu.org>
parents:
diff changeset
641 (@pxref{Faces}).
Dave Love <fx@gnu.org>
parents:
diff changeset
642
Dave Love <fx@gnu.org>
parents:
diff changeset
643 @node Colors X
Dave Love <fx@gnu.org>
parents:
diff changeset
644 @appendixsec Window Color Options
35188
94d46968a93f Don't say "X Windows". From Colin Walters <walters@cis.ohio-state.edu>.
Eli Zaretskii <eliz@gnu.org>
parents: 34221
diff changeset
645 @cindex color of window (X Window System)
33012
df207c5f631f (Colors X): Document support for -fg, -bg, and -rv
Eli Zaretskii <eliz@gnu.org>
parents: 31169
diff changeset
646 @cindex text colors, from command line
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
647
33012
df207c5f631f (Colors X): Document support for -fg, -bg, and -rv
Eli Zaretskii <eliz@gnu.org>
parents: 31169
diff changeset
648 @findex list-colors-display
df207c5f631f (Colors X): Document support for -fg, -bg, and -rv
Eli Zaretskii <eliz@gnu.org>
parents: 31169
diff changeset
649 @cindex available colors
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
650 On a color display, you can specify which color to use for various
Dave Love <fx@gnu.org>
parents:
diff changeset
651 parts of the Emacs display. To find out what colors are available on
33012
df207c5f631f (Colors X): Document support for -fg, -bg, and -rv
Eli Zaretskii <eliz@gnu.org>
parents: 31169
diff changeset
652 your system, type @kbd{M-x list-colors-display}, or press
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
653 @kbd{C-Mouse-2} and select @samp{Display Colors} from the pop-up menu.
33012
df207c5f631f (Colors X): Document support for -fg, -bg, and -rv
Eli Zaretskii <eliz@gnu.org>
parents: 31169
diff changeset
654 If you do not specify colors, on windowed displays the default for the
df207c5f631f (Colors X): Document support for -fg, -bg, and -rv
Eli Zaretskii <eliz@gnu.org>
parents: 31169
diff changeset
655 background is white and the default for all other colors is black. On a
df207c5f631f (Colors X): Document support for -fg, -bg, and -rv
Eli Zaretskii <eliz@gnu.org>
parents: 31169
diff changeset
656 monochrome display, the foreground is black, the background is white,
df207c5f631f (Colors X): Document support for -fg, -bg, and -rv
Eli Zaretskii <eliz@gnu.org>
parents: 31169
diff changeset
657 and the border is gray if the display supports that. On terminals, the
df207c5f631f (Colors X): Document support for -fg, -bg, and -rv
Eli Zaretskii <eliz@gnu.org>
parents: 31169
diff changeset
658 background is usually black and the foreground is white.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
659
33012
df207c5f631f (Colors X): Document support for -fg, -bg, and -rv
Eli Zaretskii <eliz@gnu.org>
parents: 31169
diff changeset
660 Here is a list of the command-line options for specifying colors:
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
661
Dave Love <fx@gnu.org>
parents:
diff changeset
662 @table @samp
Dave Love <fx@gnu.org>
parents:
diff changeset
663 @item -fg @var{color}
Dave Love <fx@gnu.org>
parents:
diff changeset
664 @itemx --foreground-color=@var{color}
Dave Love <fx@gnu.org>
parents:
diff changeset
665 Specify the foreground color.
Dave Love <fx@gnu.org>
parents:
diff changeset
666 @item -bg @var{color}
Dave Love <fx@gnu.org>
parents:
diff changeset
667 @itemx --background-color=@var{color}
Dave Love <fx@gnu.org>
parents:
diff changeset
668 Specify the background color.
Dave Love <fx@gnu.org>
parents:
diff changeset
669 @item -bd @var{color}
Dave Love <fx@gnu.org>
parents:
diff changeset
670 @itemx --border-color=@var{color}
Dave Love <fx@gnu.org>
parents:
diff changeset
671 Specify the color of the border of the X window.
Dave Love <fx@gnu.org>
parents:
diff changeset
672 @item -cr @var{color}
Dave Love <fx@gnu.org>
parents:
diff changeset
673 @itemx --cursor-color=@var{color}
Dave Love <fx@gnu.org>
parents:
diff changeset
674 Specify the color of the Emacs cursor which indicates where point is.
Dave Love <fx@gnu.org>
parents:
diff changeset
675 @item -ms @var{color}
Dave Love <fx@gnu.org>
parents:
diff changeset
676 @itemx --mouse-color=@var{color}
Dave Love <fx@gnu.org>
parents:
diff changeset
677 Specify the color for the mouse cursor when the mouse is in the Emacs window.
Dave Love <fx@gnu.org>
parents:
diff changeset
678 @item -r
Dave Love <fx@gnu.org>
parents:
diff changeset
679 @itemx --reverse-video
Dave Love <fx@gnu.org>
parents:
diff changeset
680 Reverse video---swap the foreground and background colors.
Dave Love <fx@gnu.org>
parents:
diff changeset
681 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
682
Dave Love <fx@gnu.org>
parents:
diff changeset
683 For example, to use a coral mouse cursor and a slate blue text cursor,
Dave Love <fx@gnu.org>
parents:
diff changeset
684 enter:
Dave Love <fx@gnu.org>
parents:
diff changeset
685
Dave Love <fx@gnu.org>
parents:
diff changeset
686 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
687 emacs -ms coral -cr 'slate blue' &
Dave Love <fx@gnu.org>
parents:
diff changeset
688 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
689
Dave Love <fx@gnu.org>
parents:
diff changeset
690 You can reverse the foreground and background colors through the
Dave Love <fx@gnu.org>
parents:
diff changeset
691 @samp{-r} option or with the X resource @samp{reverseVideo}.
Dave Love <fx@gnu.org>
parents:
diff changeset
692
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
693 The @samp{-fg}, @code{-bg}, and @code{-rv} options function on
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
694 character terminals as well as on window systems.
33012
df207c5f631f (Colors X): Document support for -fg, -bg, and -rv
Eli Zaretskii <eliz@gnu.org>
parents: 31169
diff changeset
695
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
696 @node Window Size X
Dave Love <fx@gnu.org>
parents:
diff changeset
697 @appendixsec Options for Window Geometry
35188
94d46968a93f Don't say "X Windows". From Colin Walters <walters@cis.ohio-state.edu>.
Eli Zaretskii <eliz@gnu.org>
parents: 34221
diff changeset
698 @cindex geometry (X Window System)
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
699
Dave Love <fx@gnu.org>
parents:
diff changeset
700 The @samp{-geometry} option controls the size and position of the
Dave Love <fx@gnu.org>
parents:
diff changeset
701 initial Emacs frame. Here is the format for specifying the window
Dave Love <fx@gnu.org>
parents:
diff changeset
702 geometry:
Dave Love <fx@gnu.org>
parents:
diff changeset
703
Dave Love <fx@gnu.org>
parents:
diff changeset
704 @table @samp
Dave Love <fx@gnu.org>
parents:
diff changeset
705 @item -g @var{width}x@var{height}@r{@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}
Dave Love <fx@gnu.org>
parents:
diff changeset
706 Specify window size @var{width} and @var{height} (measured in character
Dave Love <fx@gnu.org>
parents:
diff changeset
707 columns and lines), and positions @var{xoffset} and @var{yoffset}
Dave Love <fx@gnu.org>
parents:
diff changeset
708 (measured in pixels).
Dave Love <fx@gnu.org>
parents:
diff changeset
709
Dave Love <fx@gnu.org>
parents:
diff changeset
710 @item --geometry=@var{width}x@var{height}@r{@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}
Dave Love <fx@gnu.org>
parents:
diff changeset
711 This is another way of writing the same thing.
Dave Love <fx@gnu.org>
parents:
diff changeset
712 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
713
Dave Love <fx@gnu.org>
parents:
diff changeset
714 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
715 @code{@r{@{}+-@r{@}}} means either a plus sign or a minus sign. A plus
Dave Love <fx@gnu.org>
parents:
diff changeset
716 sign before @var{xoffset} means it is the distance from the left side of
Dave Love <fx@gnu.org>
parents:
diff changeset
717 the screen; a minus sign means it counts from the right side. A plus
Dave Love <fx@gnu.org>
parents:
diff changeset
718 sign before @var{yoffset} means it is the distance from the top of the
Dave Love <fx@gnu.org>
parents:
diff changeset
719 screen, and a minus sign there indicates the distance from the bottom.
Dave Love <fx@gnu.org>
parents:
diff changeset
720 The values @var{xoffset} and @var{yoffset} may themselves be positive or
Dave Love <fx@gnu.org>
parents:
diff changeset
721 negative, but that doesn't change their meaning, only their direction.
Dave Love <fx@gnu.org>
parents:
diff changeset
722
Dave Love <fx@gnu.org>
parents:
diff changeset
723 Emacs uses the same units as @code{xterm} does to interpret the geometry.
Dave Love <fx@gnu.org>
parents:
diff changeset
724 The @var{width} and @var{height} are measured in characters, so a large font
Dave Love <fx@gnu.org>
parents:
diff changeset
725 creates a larger frame than a small font. The @var{xoffset} and
Dave Love <fx@gnu.org>
parents:
diff changeset
726 @var{yoffset} are measured in pixels.
Dave Love <fx@gnu.org>
parents:
diff changeset
727
Dave Love <fx@gnu.org>
parents:
diff changeset
728 Since the mode line and the echo area occupy the last 2 lines of the
Dave Love <fx@gnu.org>
parents:
diff changeset
729 frame, the height of the initial text window is 2 less than the height
Dave Love <fx@gnu.org>
parents:
diff changeset
730 specified in your geometry. In non-X-toolkit versions of Emacs,
Dave Love <fx@gnu.org>
parents:
diff changeset
731 the menu bar also takes one line of the specified number.
Dave Love <fx@gnu.org>
parents:
diff changeset
732
Dave Love <fx@gnu.org>
parents:
diff changeset
733 You do not have to specify all of the fields in the geometry
Dave Love <fx@gnu.org>
parents:
diff changeset
734 specification.
Dave Love <fx@gnu.org>
parents:
diff changeset
735
Dave Love <fx@gnu.org>
parents:
diff changeset
736 If you omit both @var{xoffset} and @var{yoffset}, the window manager
Dave Love <fx@gnu.org>
parents:
diff changeset
737 decides where to put the Emacs frame, possibly by letting you place
Dave Love <fx@gnu.org>
parents:
diff changeset
738 it with the mouse. For example, @samp{164x55} specifies a window 164
Dave Love <fx@gnu.org>
parents:
diff changeset
739 columns wide, enough for two ordinary width windows side by side, and 55
Dave Love <fx@gnu.org>
parents:
diff changeset
740 lines tall.
Dave Love <fx@gnu.org>
parents:
diff changeset
741
Dave Love <fx@gnu.org>
parents:
diff changeset
742 The default width for Emacs is 80 characters and the default height is
Dave Love <fx@gnu.org>
parents:
diff changeset
743 40 lines. You can omit either the width or the height or both. If
Dave Love <fx@gnu.org>
parents:
diff changeset
744 you start the geometry with an integer, Emacs interprets it as the
Dave Love <fx@gnu.org>
parents:
diff changeset
745 width. If you start with an @samp{x} followed by an integer, Emacs
Dave Love <fx@gnu.org>
parents:
diff changeset
746 interprets it as the height. Thus, @samp{81} specifies just the width;
Dave Love <fx@gnu.org>
parents:
diff changeset
747 @samp{x45} specifies just the height.
Dave Love <fx@gnu.org>
parents:
diff changeset
748
Dave Love <fx@gnu.org>
parents:
diff changeset
749 If you start with @samp{+} or @samp{-}, that introduces an offset,
Dave Love <fx@gnu.org>
parents:
diff changeset
750 which means both sizes are omitted. Thus, @samp{-3} specifies the
Dave Love <fx@gnu.org>
parents:
diff changeset
751 @var{xoffset} only. (If you give just one offset, it is always
Dave Love <fx@gnu.org>
parents:
diff changeset
752 @var{xoffset}.) @samp{+3-3} specifies both the @var{xoffset} and the
Dave Love <fx@gnu.org>
parents:
diff changeset
753 @var{yoffset}, placing the frame near the bottom left of the screen.
Dave Love <fx@gnu.org>
parents:
diff changeset
754
Dave Love <fx@gnu.org>
parents:
diff changeset
755 You can specify a default for any or all of the fields in
Dave Love <fx@gnu.org>
parents:
diff changeset
756 @file{.Xdefaults} file, and then override selected fields with a
Dave Love <fx@gnu.org>
parents:
diff changeset
757 @samp{--geometry} option.
Dave Love <fx@gnu.org>
parents:
diff changeset
758
Dave Love <fx@gnu.org>
parents:
diff changeset
759 @node Borders X
Dave Love <fx@gnu.org>
parents:
diff changeset
760 @appendixsec Internal and External Borders
35188
94d46968a93f Don't say "X Windows". From Colin Walters <walters@cis.ohio-state.edu>.
Eli Zaretskii <eliz@gnu.org>
parents: 34221
diff changeset
761 @cindex borders (X Window System)
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
762
Dave Love <fx@gnu.org>
parents:
diff changeset
763 An Emacs frame has an internal border and an external border. The
Dave Love <fx@gnu.org>
parents:
diff changeset
764 internal border is an extra strip of the background color around all
Dave Love <fx@gnu.org>
parents:
diff changeset
765 four edges of the frame. Emacs itself adds the internal border. The
Dave Love <fx@gnu.org>
parents:
diff changeset
766 external border is added by the window manager outside the internal
Dave Love <fx@gnu.org>
parents:
diff changeset
767 border; it may contain various boxes you can click on to move or iconify
Dave Love <fx@gnu.org>
parents:
diff changeset
768 the window.
Dave Love <fx@gnu.org>
parents:
diff changeset
769
Dave Love <fx@gnu.org>
parents:
diff changeset
770 @table @samp
Dave Love <fx@gnu.org>
parents:
diff changeset
771 @item -ib @var{width}
Dave Love <fx@gnu.org>
parents:
diff changeset
772 @itemx --internal-border=@var{width}
Dave Love <fx@gnu.org>
parents:
diff changeset
773 Specify @var{width} as the width of the internal border.
Dave Love <fx@gnu.org>
parents:
diff changeset
774
Dave Love <fx@gnu.org>
parents:
diff changeset
775 @item -bw @var{width}
Dave Love <fx@gnu.org>
parents:
diff changeset
776 @itemx --border-width=@var{width}
Dave Love <fx@gnu.org>
parents:
diff changeset
777 Specify @var{width} as the width of the main border.
Dave Love <fx@gnu.org>
parents:
diff changeset
778 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
779
Dave Love <fx@gnu.org>
parents:
diff changeset
780 When you specify the size of the frame, that does not count the
Dave Love <fx@gnu.org>
parents:
diff changeset
781 borders. The frame's position is measured from the outside edge of the
Dave Love <fx@gnu.org>
parents:
diff changeset
782 external border.
Dave Love <fx@gnu.org>
parents:
diff changeset
783
Dave Love <fx@gnu.org>
parents:
diff changeset
784 Use the @samp{-ib @var{n}} option to specify an internal border
Dave Love <fx@gnu.org>
parents:
diff changeset
785 @var{n} pixels wide. The default is 1. Use @samp{-bw @var{n}} to
Dave Love <fx@gnu.org>
parents:
diff changeset
786 specify the width of the external border (though the window manager may
Dave Love <fx@gnu.org>
parents:
diff changeset
787 not pay attention to what you specify). The default width of the
Dave Love <fx@gnu.org>
parents:
diff changeset
788 external border is 2.
Dave Love <fx@gnu.org>
parents:
diff changeset
789
Dave Love <fx@gnu.org>
parents:
diff changeset
790 @node Title X
Dave Love <fx@gnu.org>
parents:
diff changeset
791 @appendixsec Frame Titles
Dave Love <fx@gnu.org>
parents:
diff changeset
792
Dave Love <fx@gnu.org>
parents:
diff changeset
793 An Emacs frame may or may not have a specified title. The frame
Dave Love <fx@gnu.org>
parents:
diff changeset
794 title, if specified, appears in window decorations and icons as the name
Dave Love <fx@gnu.org>
parents:
diff changeset
795 of the frame. If an Emacs frame has no specified title, the default
Dave Love <fx@gnu.org>
parents:
diff changeset
796 title is the name of the executable program (if there is only one frame)
Dave Love <fx@gnu.org>
parents:
diff changeset
797 or the selected window's buffer name (if there is more than one frame).
Dave Love <fx@gnu.org>
parents:
diff changeset
798
Dave Love <fx@gnu.org>
parents:
diff changeset
799 You can specify a title for the initial Emacs frame with a command
Dave Love <fx@gnu.org>
parents:
diff changeset
800 line option:
Dave Love <fx@gnu.org>
parents:
diff changeset
801
Dave Love <fx@gnu.org>
parents:
diff changeset
802 @table @samp
Dave Love <fx@gnu.org>
parents:
diff changeset
803 @item -title @var{title}
Dave Love <fx@gnu.org>
parents:
diff changeset
804 @itemx --title=@var{title}
Dave Love <fx@gnu.org>
parents:
diff changeset
805 @itemx -T @var{title}
Dave Love <fx@gnu.org>
parents:
diff changeset
806 Specify @var{title} as the title for the initial Emacs frame.
Dave Love <fx@gnu.org>
parents:
diff changeset
807 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
808
Dave Love <fx@gnu.org>
parents:
diff changeset
809 The @samp{--name} option (@pxref{Resources X}) also specifies the title
Dave Love <fx@gnu.org>
parents:
diff changeset
810 for the initial Emacs frame.
Dave Love <fx@gnu.org>
parents:
diff changeset
811
Dave Love <fx@gnu.org>
parents:
diff changeset
812 @node Icons X
Dave Love <fx@gnu.org>
parents:
diff changeset
813 @appendixsec Icons
35188
94d46968a93f Don't say "X Windows". From Colin Walters <walters@cis.ohio-state.edu>.
Eli Zaretskii <eliz@gnu.org>
parents: 34221
diff changeset
814 @cindex icons (X Window System)
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
815
Dave Love <fx@gnu.org>
parents:
diff changeset
816 Most window managers allow the user to ``iconify'' a frame, removing
Dave Love <fx@gnu.org>
parents:
diff changeset
817 it from sight, and leaving a small, distinctive ``icon'' window in its
Dave Love <fx@gnu.org>
parents:
diff changeset
818 place. Clicking on the icon window makes the frame itself appear again.
Dave Love <fx@gnu.org>
parents:
diff changeset
819 If you have many clients running at once, you can avoid cluttering up
Dave Love <fx@gnu.org>
parents:
diff changeset
820 the screen by iconifying most of the clients.
Dave Love <fx@gnu.org>
parents:
diff changeset
821
Dave Love <fx@gnu.org>
parents:
diff changeset
822 @table @samp
Dave Love <fx@gnu.org>
parents:
diff changeset
823 @item -i
Dave Love <fx@gnu.org>
parents:
diff changeset
824 @itemx --icon-type
Dave Love <fx@gnu.org>
parents:
diff changeset
825 Use a picture of a gnu as the Emacs icon.
Dave Love <fx@gnu.org>
parents:
diff changeset
826
Dave Love <fx@gnu.org>
parents:
diff changeset
827 @item -iconic
Dave Love <fx@gnu.org>
parents:
diff changeset
828 @itemx --iconic
Dave Love <fx@gnu.org>
parents:
diff changeset
829 Start Emacs in iconified state.
Dave Love <fx@gnu.org>
parents:
diff changeset
830 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
831
Dave Love <fx@gnu.org>
parents:
diff changeset
832 The @samp{-i} or @samp{--icon-type} option tells Emacs to use an icon
Dave Love <fx@gnu.org>
parents:
diff changeset
833 window containing a picture of the GNU gnu. If omitted, Emacs lets the
Dave Love <fx@gnu.org>
parents:
diff changeset
834 window manager choose what sort of icon to use---usually just a small
Dave Love <fx@gnu.org>
parents:
diff changeset
835 rectangle containing the frame's title.
Dave Love <fx@gnu.org>
parents:
diff changeset
836
Dave Love <fx@gnu.org>
parents:
diff changeset
837 The @samp{-iconic} option tells Emacs to begin running as an icon,
Dave Love <fx@gnu.org>
parents:
diff changeset
838 rather than opening a frame right away. In this situation, the icon
Dave Love <fx@gnu.org>
parents:
diff changeset
839 window provides only indication that Emacs has started; the usual text
Dave Love <fx@gnu.org>
parents:
diff changeset
840 frame doesn't appear until you deiconify it.
Dave Love <fx@gnu.org>
parents:
diff changeset
841
Dave Love <fx@gnu.org>
parents:
diff changeset
842 @node Resources X
Dave Love <fx@gnu.org>
parents:
diff changeset
843 @appendixsec X Resources
Dave Love <fx@gnu.org>
parents:
diff changeset
844 @cindex resources
Dave Love <fx@gnu.org>
parents:
diff changeset
845
Dave Love <fx@gnu.org>
parents:
diff changeset
846 Programs running under the X Window System organize their user options
Dave Love <fx@gnu.org>
parents:
diff changeset
847 under a hierarchy of classes and resources. You can specify default
Dave Love <fx@gnu.org>
parents:
diff changeset
848 values for these options in your X resources file, usually named
Dave Love <fx@gnu.org>
parents:
diff changeset
849 @file{~/.Xdefaults}.
Dave Love <fx@gnu.org>
parents:
diff changeset
850
Dave Love <fx@gnu.org>
parents:
diff changeset
851 Each line in the file specifies a value for one option or for a
Dave Love <fx@gnu.org>
parents:
diff changeset
852 collection of related options, for one program or for several programs
Dave Love <fx@gnu.org>
parents:
diff changeset
853 (optionally even for all programs).
Dave Love <fx@gnu.org>
parents:
diff changeset
854
Dave Love <fx@gnu.org>
parents:
diff changeset
855 Programs define named resources with particular meanings. They also
Dave Love <fx@gnu.org>
parents:
diff changeset
856 define how to group resources into named classes. For instance, in
Dave Love <fx@gnu.org>
parents:
diff changeset
857 Emacs, the @samp{internalBorder} resource controls the width of the
Dave Love <fx@gnu.org>
parents:
diff changeset
858 internal border, and the @samp{borderWidth} resource controls the width
Dave Love <fx@gnu.org>
parents:
diff changeset
859 of the external border. Both of these resources are part of the
Dave Love <fx@gnu.org>
parents:
diff changeset
860 @samp{BorderWidth} class. Case distinctions are significant in these
Dave Love <fx@gnu.org>
parents:
diff changeset
861 names.
Dave Love <fx@gnu.org>
parents:
diff changeset
862
Dave Love <fx@gnu.org>
parents:
diff changeset
863 In @file{~/.Xdefaults}, you can specify a value for a single resource
Dave Love <fx@gnu.org>
parents:
diff changeset
864 on one line, like this:
Dave Love <fx@gnu.org>
parents:
diff changeset
865
Dave Love <fx@gnu.org>
parents:
diff changeset
866 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
867 emacs.borderWidth: 2
Dave Love <fx@gnu.org>
parents:
diff changeset
868 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
869
Dave Love <fx@gnu.org>
parents:
diff changeset
870 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
871 Or you can use a class name to specify the same value for all resources
Dave Love <fx@gnu.org>
parents:
diff changeset
872 in that class. Here's an example:
Dave Love <fx@gnu.org>
parents:
diff changeset
873
Dave Love <fx@gnu.org>
parents:
diff changeset
874 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
875 emacs.BorderWidth: 2
Dave Love <fx@gnu.org>
parents:
diff changeset
876 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
877
Dave Love <fx@gnu.org>
parents:
diff changeset
878 If you specify a value for a class, it becomes the default for all
Dave Love <fx@gnu.org>
parents:
diff changeset
879 resources in that class. You can specify values for individual
Dave Love <fx@gnu.org>
parents:
diff changeset
880 resources as well; these override the class value, for those particular
Dave Love <fx@gnu.org>
parents:
diff changeset
881 resources. Thus, this example specifies 2 as the default width for all
Dave Love <fx@gnu.org>
parents:
diff changeset
882 borders, but overrides this value with 4 for the external border:
Dave Love <fx@gnu.org>
parents:
diff changeset
883
Dave Love <fx@gnu.org>
parents:
diff changeset
884 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
885 emacs.Borderwidth: 2
Dave Love <fx@gnu.org>
parents:
diff changeset
886 emacs.borderwidth: 4
Dave Love <fx@gnu.org>
parents:
diff changeset
887 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
888
Dave Love <fx@gnu.org>
parents:
diff changeset
889 The order in which the lines appear in the file does not matter.
Dave Love <fx@gnu.org>
parents:
diff changeset
890 Also, command-line options always override the X resources file.
Dave Love <fx@gnu.org>
parents:
diff changeset
891
Dave Love <fx@gnu.org>
parents:
diff changeset
892 The string @samp{emacs} in the examples above is also a resource
Dave Love <fx@gnu.org>
parents:
diff changeset
893 name. It actually represents the name of the executable file that you
Dave Love <fx@gnu.org>
parents:
diff changeset
894 invoke to run Emacs. If Emacs is installed under a different name, it
Dave Love <fx@gnu.org>
parents:
diff changeset
895 looks for resources under that name instead of @samp{emacs}.
Dave Love <fx@gnu.org>
parents:
diff changeset
896
Dave Love <fx@gnu.org>
parents:
diff changeset
897 @table @samp
Dave Love <fx@gnu.org>
parents:
diff changeset
898 @item -name @var{name}
Dave Love <fx@gnu.org>
parents:
diff changeset
899 @itemx --name=@var{name}
Dave Love <fx@gnu.org>
parents:
diff changeset
900 Use @var{name} as the resource name (and the title) for the initial
Dave Love <fx@gnu.org>
parents:
diff changeset
901 Emacs frame. This option does not affect subsequent frames, but Lisp
Dave Love <fx@gnu.org>
parents:
diff changeset
902 programs can specify frame names when they create frames.
Dave Love <fx@gnu.org>
parents:
diff changeset
903
Dave Love <fx@gnu.org>
parents:
diff changeset
904 If you don't specify this option, the default is to use the Emacs
Dave Love <fx@gnu.org>
parents:
diff changeset
905 executable's name as the resource name.
Dave Love <fx@gnu.org>
parents:
diff changeset
906
Dave Love <fx@gnu.org>
parents:
diff changeset
907 @item -xrm @var{resource-values}
Dave Love <fx@gnu.org>
parents:
diff changeset
908 @itemx --xrm=@var{resource-values}
Dave Love <fx@gnu.org>
parents:
diff changeset
909 Specify X resource values for this Emacs job (see below).
Dave Love <fx@gnu.org>
parents:
diff changeset
910 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
911
Dave Love <fx@gnu.org>
parents:
diff changeset
912 For consistency, @samp{-name} also specifies the name to use for
Dave Love <fx@gnu.org>
parents:
diff changeset
913 other resource values that do not belong to any particular frame.
Dave Love <fx@gnu.org>
parents:
diff changeset
914
Dave Love <fx@gnu.org>
parents:
diff changeset
915 The resources that name Emacs invocations also belong to a class; its
Dave Love <fx@gnu.org>
parents:
diff changeset
916 name is @samp{Emacs}. If you write @samp{Emacs} instead of
Dave Love <fx@gnu.org>
parents:
diff changeset
917 @samp{emacs}, the resource applies to all frames in all Emacs jobs,
Dave Love <fx@gnu.org>
parents:
diff changeset
918 regardless of frame titles and regardless of the name of the executable
Dave Love <fx@gnu.org>
parents:
diff changeset
919 file. Here is an example:
Dave Love <fx@gnu.org>
parents:
diff changeset
920
Dave Love <fx@gnu.org>
parents:
diff changeset
921 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
922 Emacs.BorderWidth: 2
Dave Love <fx@gnu.org>
parents:
diff changeset
923 Emacs.borderWidth: 4
Dave Love <fx@gnu.org>
parents:
diff changeset
924 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
925
Dave Love <fx@gnu.org>
parents:
diff changeset
926 You can specify a string of additional resource values for Emacs to
Dave Love <fx@gnu.org>
parents:
diff changeset
927 use with the command line option @samp{-xrm @var{resources}}. The text
Dave Love <fx@gnu.org>
parents:
diff changeset
928 @var{resources} should have the same format that you would use inside a file
Dave Love <fx@gnu.org>
parents:
diff changeset
929 of X resources. To include multiple resource specifications in
Dave Love <fx@gnu.org>
parents:
diff changeset
930 @var{data}, put a newline between them, just as you would in a file.
Dave Love <fx@gnu.org>
parents:
diff changeset
931 You can also use @samp{#include "@var{filename}"} to include a file full
Dave Love <fx@gnu.org>
parents:
diff changeset
932 of resource specifications. Resource values specified with @samp{-xrm}
Dave Love <fx@gnu.org>
parents:
diff changeset
933 take precedence over all other resource specifications.
Dave Love <fx@gnu.org>
parents:
diff changeset
934
Dave Love <fx@gnu.org>
parents:
diff changeset
935 The following table lists the resource names that designate options
Dave Love <fx@gnu.org>
parents:
diff changeset
936 for Emacs, each with the class that it belongs to:
Dave Love <fx@gnu.org>
parents:
diff changeset
937
Dave Love <fx@gnu.org>
parents:
diff changeset
938 @table @asis
Dave Love <fx@gnu.org>
parents:
diff changeset
939 @item @code{background} (class @code{Background})
Dave Love <fx@gnu.org>
parents:
diff changeset
940 Background color name.
Dave Love <fx@gnu.org>
parents:
diff changeset
941
Dave Love <fx@gnu.org>
parents:
diff changeset
942 @item @code{bitmapIcon} (class @code{BitmapIcon})
Dave Love <fx@gnu.org>
parents:
diff changeset
943 Use a bitmap icon (a picture of a gnu) if @samp{on}, let the window
Dave Love <fx@gnu.org>
parents:
diff changeset
944 manager choose an icon if @samp{off}.
Dave Love <fx@gnu.org>
parents:
diff changeset
945
Dave Love <fx@gnu.org>
parents:
diff changeset
946 @item @code{borderColor} (class @code{BorderColor})
Dave Love <fx@gnu.org>
parents:
diff changeset
947 Color name for the external border.
Dave Love <fx@gnu.org>
parents:
diff changeset
948
Dave Love <fx@gnu.org>
parents:
diff changeset
949 @item @code{borderWidth} (class @code{BorderWidth})
Dave Love <fx@gnu.org>
parents:
diff changeset
950 Width in pixels of the external border.
Dave Love <fx@gnu.org>
parents:
diff changeset
951
Dave Love <fx@gnu.org>
parents:
diff changeset
952 @item @code{cursorColor} (class @code{Foreground})
Dave Love <fx@gnu.org>
parents:
diff changeset
953 Color name for text cursor (point).
Dave Love <fx@gnu.org>
parents:
diff changeset
954
Dave Love <fx@gnu.org>
parents:
diff changeset
955 @item @code{font} (class @code{Font})
Dave Love <fx@gnu.org>
parents:
diff changeset
956 Font name for text (or fontset name, @pxref{Fontsets}).
Dave Love <fx@gnu.org>
parents:
diff changeset
957
Dave Love <fx@gnu.org>
parents:
diff changeset
958 @item @code{foreground} (class @code{Foreground})
Dave Love <fx@gnu.org>
parents:
diff changeset
959 Color name for text.
Dave Love <fx@gnu.org>
parents:
diff changeset
960
Dave Love <fx@gnu.org>
parents:
diff changeset
961 @item @code{geometry} (class @code{Geometry})
Dave Love <fx@gnu.org>
parents:
diff changeset
962 Window size and position. Be careful not to specify this resource as
Dave Love <fx@gnu.org>
parents:
diff changeset
963 @samp{emacs*geometry}, because that may affect individual menus as well
Dave Love <fx@gnu.org>
parents:
diff changeset
964 as the Emacs frame itself.
Dave Love <fx@gnu.org>
parents:
diff changeset
965
Dave Love <fx@gnu.org>
parents:
diff changeset
966 If this resource specifies a position, that position applies only to the
Dave Love <fx@gnu.org>
parents:
diff changeset
967 initial Emacs frame (or, in the case of a resource for a specific frame
Dave Love <fx@gnu.org>
parents:
diff changeset
968 name, only that frame). However, the size if specified here applies to
Dave Love <fx@gnu.org>
parents:
diff changeset
969 all frames.
Dave Love <fx@gnu.org>
parents:
diff changeset
970
Dave Love <fx@gnu.org>
parents:
diff changeset
971 @item @code{iconName} (class @code{Title})
Dave Love <fx@gnu.org>
parents:
diff changeset
972 Name to display in the icon.
Dave Love <fx@gnu.org>
parents:
diff changeset
973
Dave Love <fx@gnu.org>
parents:
diff changeset
974 @item @code{internalBorder} (class @code{BorderWidth})
Dave Love <fx@gnu.org>
parents:
diff changeset
975 Width in pixels of the internal border.
Dave Love <fx@gnu.org>
parents:
diff changeset
976
30861
3a8f23672286 (Environment): setenv.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
977 @item @code{lineSpacing} (class LineSpacing)
3a8f23672286 (Environment): setenv.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
978 @cindex line spacing
3a8f23672286 (Environment): setenv.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
979 @cindex leading
3a8f23672286 (Environment): setenv.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
980 Additional space (@dfn{leading}) between lines in pixels.
3a8f23672286 (Environment): setenv.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
981
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
982 @item @code{menuBar} (class @code{MenuBar})
Dave Love <fx@gnu.org>
parents:
diff changeset
983 Give frames menu bars if @samp{on}; don't have menu bars if @samp{off}.
Dave Love <fx@gnu.org>
parents:
diff changeset
984
34221
e31ac0d22ff8 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 33017
diff changeset
985 @item @code{toolBar} (class @code{ToolBar})
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
986 Number of lines to reserve for the tool bar. A zero value suppresses
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
987 the tool bar. If the value is non-zero and
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
988 @code{auto-resize-tool-bars} is non-@code{nil}, the tool bar's size
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
989 will be changed automatically so that all tool bar items are visible.
34221
e31ac0d22ff8 *** empty log message ***
Dave Love <fx@gnu.org>
parents: 33017
diff changeset
990
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
991 @item @code{minibuffer} (class @code{Minibuffer})
Dave Love <fx@gnu.org>
parents:
diff changeset
992 If @samp{none}, don't make a minibuffer in this frame.
Dave Love <fx@gnu.org>
parents:
diff changeset
993 It will use a separate minibuffer frame instead.
Dave Love <fx@gnu.org>
parents:
diff changeset
994
Dave Love <fx@gnu.org>
parents:
diff changeset
995 @item @code{paneFont} (class @code{Font})
Dave Love <fx@gnu.org>
parents:
diff changeset
996 Font name for menu pane titles, in non-toolkit versions of Emacs.
Dave Love <fx@gnu.org>
parents:
diff changeset
997
Dave Love <fx@gnu.org>
parents:
diff changeset
998 @item @code{pointerColor} (class @code{Foreground})
Dave Love <fx@gnu.org>
parents:
diff changeset
999 Color of the mouse cursor.
Dave Love <fx@gnu.org>
parents:
diff changeset
1000
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
1001 @ignore
30861
3a8f23672286 (Environment): setenv.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
1002 @item @code{privateColormap} (class @code{PrivateColormap})
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
1003 If @samp{on}, use a private colormap, in the case where the ``default
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
1004 visual'' of class PseudoColor and Emacs is using it.
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
1005 @end ignore
30861
3a8f23672286 (Environment): setenv.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
1006
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1007 @item @code{reverseVideo} (class @code{ReverseVideo})
Dave Love <fx@gnu.org>
parents:
diff changeset
1008 Switch foreground and background default colors if @samp{on}, use colors as
Dave Love <fx@gnu.org>
parents:
diff changeset
1009 specified if @samp{off}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1010
30861
3a8f23672286 (Environment): setenv.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
1011 @item @code{screenGamma} (class @code{ScreenGamma})
3a8f23672286 (Environment): setenv.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
1012 @cindex gamma correction
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
1013 Gamma correction for colors, equivalent to the frame parameter
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
1014 @code{screen-gamma}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1015
Dave Love <fx@gnu.org>
parents:
diff changeset
1016 @item @code{selectionFont} (class @code{Font})
Dave Love <fx@gnu.org>
parents:
diff changeset
1017 Font name for pop-up menu items, in non-toolkit versions of Emacs. (For
Dave Love <fx@gnu.org>
parents:
diff changeset
1018 toolkit versions, see @ref{Lucid Resources}, also see @ref{Motif
Dave Love <fx@gnu.org>
parents:
diff changeset
1019 Resources}.)
Dave Love <fx@gnu.org>
parents:
diff changeset
1020
30861
3a8f23672286 (Environment): setenv.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
1021 @item @code{synchronous} (class @code{Synchronous})
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
1022 Run Emacs in synchronous mode if @samp{on}. Synchronous mode is
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
1023 useful for debugging X problems.
30861
3a8f23672286 (Environment): setenv.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
1024
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1025 @item @code{title} (class @code{Title})
Dave Love <fx@gnu.org>
parents:
diff changeset
1026 Name to display in the title bar of the initial Emacs frame.
30861
3a8f23672286 (Environment): setenv.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
1027
3a8f23672286 (Environment): setenv.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
1028 @item @code{verticalScrollBars} (class @code{ScrollBars})
3a8f23672286 (Environment): setenv.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
1029 Give frames scroll bars if @samp{on}; don't have scroll bars if
3a8f23672286 (Environment): setenv.
Dave Love <fx@gnu.org>
parents: 29107
diff changeset
1030 @samp{off}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1031 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1032
Dave Love <fx@gnu.org>
parents:
diff changeset
1033 Here are resources for controlling the appearance of particular faces
Dave Love <fx@gnu.org>
parents:
diff changeset
1034 (@pxref{Faces}):
Dave Love <fx@gnu.org>
parents:
diff changeset
1035
Dave Love <fx@gnu.org>
parents:
diff changeset
1036 @table @code
Dave Love <fx@gnu.org>
parents:
diff changeset
1037 @item @var{face}.attributeFont
Dave Love <fx@gnu.org>
parents:
diff changeset
1038 Font for face @var{face}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1039 @item @var{face}.attributeForeground
Dave Love <fx@gnu.org>
parents:
diff changeset
1040 Foreground color for face @var{face}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1041 @item @var{face}.attributeBackground
Dave Love <fx@gnu.org>
parents:
diff changeset
1042 Background color for face @var{face}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1043 @item @var{face}.attributeUnderline
Dave Love <fx@gnu.org>
parents:
diff changeset
1044 Underline flag for face @var{face}. Use @samp{on} or @samp{true} for
Dave Love <fx@gnu.org>
parents:
diff changeset
1045 yes.
Dave Love <fx@gnu.org>
parents:
diff changeset
1046 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1047
Dave Love <fx@gnu.org>
parents:
diff changeset
1048 @node Lucid Resources
Dave Love <fx@gnu.org>
parents:
diff changeset
1049 @section Lucid Menu X Resources
Dave Love <fx@gnu.org>
parents:
diff changeset
1050 @cindex Menu X Resources (Lucid widgets)
Dave Love <fx@gnu.org>
parents:
diff changeset
1051 @cindex Lucid Widget X Resources
Dave Love <fx@gnu.org>
parents:
diff changeset
1052
Dave Love <fx@gnu.org>
parents:
diff changeset
1053 If the Emacs installed at your site was built to use the X toolkit
Dave Love <fx@gnu.org>
parents:
diff changeset
1054 with the Lucid menu widgets, then the menu bar is a separate widget and
Dave Love <fx@gnu.org>
parents:
diff changeset
1055 has its own resources. The resource names contain @samp{pane.menubar}
Dave Love <fx@gnu.org>
parents:
diff changeset
1056 (following, as always, the name of the Emacs invocation or @samp{Emacs}
Dave Love <fx@gnu.org>
parents:
diff changeset
1057 which stands for all Emacs invocations). Specify them like this:
Dave Love <fx@gnu.org>
parents:
diff changeset
1058
Dave Love <fx@gnu.org>
parents:
diff changeset
1059 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
1060 Emacs.pane.menubar.@var{resource}: @var{value}
Dave Love <fx@gnu.org>
parents:
diff changeset
1061 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
1062
Dave Love <fx@gnu.org>
parents:
diff changeset
1063 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
1064 For example, to specify the font @samp{8x16} for the menu-bar items,
Dave Love <fx@gnu.org>
parents:
diff changeset
1065 write this:
Dave Love <fx@gnu.org>
parents:
diff changeset
1066
Dave Love <fx@gnu.org>
parents:
diff changeset
1067 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
1068 Emacs.pane.menubar.font: 8x16
Dave Love <fx@gnu.org>
parents:
diff changeset
1069 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
1070
Dave Love <fx@gnu.org>
parents:
diff changeset
1071 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
1072 Resources for @emph{non-menubar} toolkit pop-up menus have
Dave Love <fx@gnu.org>
parents:
diff changeset
1073 @samp{menu*}, in like fashion. For example, to specify the font
Dave Love <fx@gnu.org>
parents:
diff changeset
1074 @samp{8x16} for the pop-up menu items, write this:
Dave Love <fx@gnu.org>
parents:
diff changeset
1075
Dave Love <fx@gnu.org>
parents:
diff changeset
1076 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
1077 Emacs.menu*.font: 8x16
Dave Love <fx@gnu.org>
parents:
diff changeset
1078 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
1079
Dave Love <fx@gnu.org>
parents:
diff changeset
1080 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
1081 For dialog boxes, use @samp{dialog} instead of @samp{menu}:
Dave Love <fx@gnu.org>
parents:
diff changeset
1082
Dave Love <fx@gnu.org>
parents:
diff changeset
1083 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
1084 Emacs.dialog*.font: 8x16
Dave Love <fx@gnu.org>
parents:
diff changeset
1085 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
1086
Dave Love <fx@gnu.org>
parents:
diff changeset
1087 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
1088 Experience shows that on some systems you may need to add
Dave Love <fx@gnu.org>
parents:
diff changeset
1089 @samp{shell.}@: before the @samp{pane.menubar} or @samp{menu*}. On
Dave Love <fx@gnu.org>
parents:
diff changeset
1090 some other systems, you must not add @samp{shell.}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1091
Dave Love <fx@gnu.org>
parents:
diff changeset
1092 Here is a list of the specific resources for menu bars and pop-up menus:
Dave Love <fx@gnu.org>
parents:
diff changeset
1093
Dave Love <fx@gnu.org>
parents:
diff changeset
1094 @table @code
Dave Love <fx@gnu.org>
parents:
diff changeset
1095 @item font
Dave Love <fx@gnu.org>
parents:
diff changeset
1096 Font for menu item text.
Dave Love <fx@gnu.org>
parents:
diff changeset
1097 @item foreground
Dave Love <fx@gnu.org>
parents:
diff changeset
1098 Color of the foreground.
Dave Love <fx@gnu.org>
parents:
diff changeset
1099 @item background
Dave Love <fx@gnu.org>
parents:
diff changeset
1100 Color of the background.
Dave Love <fx@gnu.org>
parents:
diff changeset
1101 @item buttonForeground
Dave Love <fx@gnu.org>
parents:
diff changeset
1102 In the menu bar, the color of the foreground for a selected item.
Dave Love <fx@gnu.org>
parents:
diff changeset
1103 @item horizontalSpacing
Dave Love <fx@gnu.org>
parents:
diff changeset
1104 Horizontal spacing in pixels between items. Default is 3.
Dave Love <fx@gnu.org>
parents:
diff changeset
1105 @item verticalSpacing
Dave Love <fx@gnu.org>
parents:
diff changeset
1106 Vertical spacing in pixels between items. Default is 1.
Dave Love <fx@gnu.org>
parents:
diff changeset
1107 @item arrowSpacing
Dave Love <fx@gnu.org>
parents:
diff changeset
1108 Horizontal spacing between the arrow (which indicates a submenu) and
Dave Love <fx@gnu.org>
parents:
diff changeset
1109 the associated text. Default is 10.
Dave Love <fx@gnu.org>
parents:
diff changeset
1110 @item shadowThickness
Dave Love <fx@gnu.org>
parents:
diff changeset
1111 Thickness of shadow line around the widget.
30923
110ddcc483b6 margin resource
Dave Love <fx@gnu.org>
parents: 30861
diff changeset
1112 @item margin
36146
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
1113 The margin of the menu bar, in characters. The default of 4 makes the
885408f5ce84 New general discussion of the environment.
Richard M. Stallman <rms@gnu.org>
parents: 35490
diff changeset
1114 menu bar appear like the LessTif/Motif one.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1115 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1116
Dave Love <fx@gnu.org>
parents:
diff changeset
1117 @node Motif Resources
Dave Love <fx@gnu.org>
parents:
diff changeset
1118 @section Motif Menu X Resources
Dave Love <fx@gnu.org>
parents:
diff changeset
1119 @cindex Menu X Resources (Motif widgets)
Dave Love <fx@gnu.org>
parents:
diff changeset
1120 @cindex Motif Widget X Resources
Dave Love <fx@gnu.org>
parents:
diff changeset
1121
Dave Love <fx@gnu.org>
parents:
diff changeset
1122 If the Emacs installed at your site was built to use the X toolkit
Dave Love <fx@gnu.org>
parents:
diff changeset
1123 with the Motif widgets, then the menu bar is a separate widget and has
Dave Love <fx@gnu.org>
parents:
diff changeset
1124 its own resources. The resource names contain @samp{pane.menubar}
Dave Love <fx@gnu.org>
parents:
diff changeset
1125 (following, as always, the name of the Emacs invocation or @samp{Emacs}
Dave Love <fx@gnu.org>
parents:
diff changeset
1126 which stands for all Emacs invocations). Specify them like this:
Dave Love <fx@gnu.org>
parents:
diff changeset
1127
Dave Love <fx@gnu.org>
parents:
diff changeset
1128 @smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1129 Emacs.pane.menubar.@var{subwidget}.@var{resource}: @var{value}
Dave Love <fx@gnu.org>
parents:
diff changeset
1130 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1131
Dave Love <fx@gnu.org>
parents:
diff changeset
1132 Each individual string in the menu bar is a subwidget; the subwidget's
Dave Love <fx@gnu.org>
parents:
diff changeset
1133 name is the same as the menu item string. For example, the word
Dave Love <fx@gnu.org>
parents:
diff changeset
1134 @samp{Files} in the menu bar is part of a subwidget named
Dave Love <fx@gnu.org>
parents:
diff changeset
1135 @samp{emacs.pane.menubar.Files}. Most likely, you want to specify the
Dave Love <fx@gnu.org>
parents:
diff changeset
1136 same resources for the whole menu bar. To do this, use @samp{*} instead
Dave Love <fx@gnu.org>
parents:
diff changeset
1137 of a specific subwidget name. For example, to specify the font
Dave Love <fx@gnu.org>
parents:
diff changeset
1138 @samp{8x16} for the menu-bar items, write this:
Dave Love <fx@gnu.org>
parents:
diff changeset
1139
Dave Love <fx@gnu.org>
parents:
diff changeset
1140 @smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1141 Emacs.pane.menubar.*.fontList: 8x16
Dave Love <fx@gnu.org>
parents:
diff changeset
1142 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1143
Dave Love <fx@gnu.org>
parents:
diff changeset
1144 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
1145 This also specifies the resource value for submenus.
Dave Love <fx@gnu.org>
parents:
diff changeset
1146
Dave Love <fx@gnu.org>
parents:
diff changeset
1147 Each item in a submenu in the menu bar also has its own name for X
Dave Love <fx@gnu.org>
parents:
diff changeset
1148 resources; for example, the @samp{Files} submenu has an item named
Dave Love <fx@gnu.org>
parents:
diff changeset
1149 @samp{Save Buffer}. A resource specification for a submenu item looks
Dave Love <fx@gnu.org>
parents:
diff changeset
1150 like this:
Dave Love <fx@gnu.org>
parents:
diff changeset
1151
Dave Love <fx@gnu.org>
parents:
diff changeset
1152 @smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1153 Emacs.pane.menubar.popup_*.@var{menu}.@var{item}.@var{resource}: @var{value}
Dave Love <fx@gnu.org>
parents:
diff changeset
1154 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1155
Dave Love <fx@gnu.org>
parents:
diff changeset
1156 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
1157 For example, here's how to specify the font for the @samp{Save Buffer}
Dave Love <fx@gnu.org>
parents:
diff changeset
1158 item:
Dave Love <fx@gnu.org>
parents:
diff changeset
1159
Dave Love <fx@gnu.org>
parents:
diff changeset
1160 @smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1161 Emacs.pane.menubar.popup_*.Files.Save Buffer.fontList: 8x16
Dave Love <fx@gnu.org>
parents:
diff changeset
1162 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1163
Dave Love <fx@gnu.org>
parents:
diff changeset
1164 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
1165 For an item in a second-level submenu, such as @samp{Check Message}
Dave Love <fx@gnu.org>
parents:
diff changeset
1166 under @samp{Spell} under @samp{Edit}, the resource fits this template:
Dave Love <fx@gnu.org>
parents:
diff changeset
1167
Dave Love <fx@gnu.org>
parents:
diff changeset
1168 @smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1169 Emacs.pane.menubar.popup_*.popup_*.@var{menu}.@var{resource}: @var{value}
Dave Love <fx@gnu.org>
parents:
diff changeset
1170 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1171
Dave Love <fx@gnu.org>
parents:
diff changeset
1172 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
1173 For example,
Dave Love <fx@gnu.org>
parents:
diff changeset
1174
Dave Love <fx@gnu.org>
parents:
diff changeset
1175 @smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1176 Emacs.pane.menubar.popup_*.popup_*.Spell.Check Message: @var{value}
Dave Love <fx@gnu.org>
parents:
diff changeset
1177 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1178
Dave Love <fx@gnu.org>
parents:
diff changeset
1179 It's impossible to specify a resource for all the menu-bar items
Dave Love <fx@gnu.org>
parents:
diff changeset
1180 without also specifying it for the submenus as well. So if you want the
Dave Love <fx@gnu.org>
parents:
diff changeset
1181 submenu items to look different from the menu bar itself, you must ask
Dave Love <fx@gnu.org>
parents:
diff changeset
1182 for that in two steps. First, specify the resource for all of them;
Dave Love <fx@gnu.org>
parents:
diff changeset
1183 then, override the value for submenus alone. Here is an example:
Dave Love <fx@gnu.org>
parents:
diff changeset
1184
Dave Love <fx@gnu.org>
parents:
diff changeset
1185 @smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1186 Emacs.pane.menubar.*.fontList: 8x16
Dave Love <fx@gnu.org>
parents:
diff changeset
1187 Emacs.pane.menubar.popup_*.fontList: 8x16
Dave Love <fx@gnu.org>
parents:
diff changeset
1188 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1189
Dave Love <fx@gnu.org>
parents:
diff changeset
1190 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
1191 For toolkit pop-up menus, use @samp{menu*} instead of
Dave Love <fx@gnu.org>
parents:
diff changeset
1192 @samp{pane.menubar}. For example, to specify the font @samp{8x16} for
Dave Love <fx@gnu.org>
parents:
diff changeset
1193 the pop-up menu items, write this:
Dave Love <fx@gnu.org>
parents:
diff changeset
1194
Dave Love <fx@gnu.org>
parents:
diff changeset
1195 @smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1196 Emacs.menu*.fontList: 8x16
Dave Love <fx@gnu.org>
parents:
diff changeset
1197 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1198
Dave Love <fx@gnu.org>
parents:
diff changeset
1199 @iftex
Dave Love <fx@gnu.org>
parents:
diff changeset
1200 @medbreak
Dave Love <fx@gnu.org>
parents:
diff changeset
1201 @end iftex
Dave Love <fx@gnu.org>
parents:
diff changeset
1202 Here is a list of the specific resources for menu bars and pop-up menus:
Dave Love <fx@gnu.org>
parents:
diff changeset
1203
Dave Love <fx@gnu.org>
parents:
diff changeset
1204 @table @code
Dave Love <fx@gnu.org>
parents:
diff changeset
1205 @item armColor
Dave Love <fx@gnu.org>
parents:
diff changeset
1206 The color to show in an armed button.
Dave Love <fx@gnu.org>
parents:
diff changeset
1207 @item fontList
Dave Love <fx@gnu.org>
parents:
diff changeset
1208 The font to use.
Dave Love <fx@gnu.org>
parents:
diff changeset
1209 @item marginBottom
Dave Love <fx@gnu.org>
parents:
diff changeset
1210 @itemx marginHeight
Dave Love <fx@gnu.org>
parents:
diff changeset
1211 @itemx marginLeft
Dave Love <fx@gnu.org>
parents:
diff changeset
1212 @itemx marginRight
Dave Love <fx@gnu.org>
parents:
diff changeset
1213 @itemx marginTop
Dave Love <fx@gnu.org>
parents:
diff changeset
1214 @itemx marginWidth
Dave Love <fx@gnu.org>
parents:
diff changeset
1215 Amount of space to leave around the item, within the border.
Dave Love <fx@gnu.org>
parents:
diff changeset
1216 @item borderWidth
Dave Love <fx@gnu.org>
parents:
diff changeset
1217 The width of border around the menu item, on all sides.
Dave Love <fx@gnu.org>
parents:
diff changeset
1218 @item shadowThickness
Dave Love <fx@gnu.org>
parents:
diff changeset
1219 The width of the border shadow.
Dave Love <fx@gnu.org>
parents:
diff changeset
1220 @item bottomShadowColor
Dave Love <fx@gnu.org>
parents:
diff changeset
1221 The color for the border shadow, on the bottom and the right.
Dave Love <fx@gnu.org>
parents:
diff changeset
1222 @item topShadowColor
Dave Love <fx@gnu.org>
parents:
diff changeset
1223 The color for the border shadow, on the top and the left.
Dave Love <fx@gnu.org>
parents:
diff changeset
1224 @end table