annotate man/cmdargs.texi @ 30436:9abea5a69fb5

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