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