annotate man/cmdargs.texi @ 33584:1df24dca8931

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