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