0001: @c This is part of the Emacs manual.
0002: @c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2019 Free Software
0003: @c Foundation, Inc.
0004: @c See file emacs.texi for copying conditions.
0005: @node Emacs Invocation
0006: @appendix Command Line Arguments for Emacs Invocation
0007: @cindex command line arguments
0008: @cindex arguments (command line)
0009: @cindex options (command line)
0010: @cindex switches (command line)
0011: @cindex startup (command line arguments)
0012: @cindex invocation (command line arguments)
0013: @c FIXME: Document '--smid'?  --xfq
0014: 
0015:   Emacs supports command line arguments to request various actions
0016: when invoking Emacs.  These are for compatibility with other editors
0017: and for sophisticated activities.  We don't recommend using them for
0018: ordinary editing (@xref{Emacs Server}, for a way to access an existing
0019: Emacs job from the command line).
0020: 
0021:   Arguments starting with @samp{-} are @dfn{options}, and so is
0022: @samp{+@var{linenum}}.  All other arguments specify files to visit.
0023: Emacs visits the specified files while it starts up.  The last file
0024: specified on the command line becomes the current buffer; the other
0025: files are also visited in other buffers.  As with most programs, the
0026: special argument @samp{--} says that all subsequent arguments are file
0027: names, not options, even if they start with @samp{-}.
0028: 
0029:   Emacs command options can specify many things, such as the size and
0030: position of the X window Emacs uses, its colors, and so on.  A few
0031: options support advanced usage, such as running Lisp functions on files
0032: in batch mode.  The sections of this chapter describe the available
0033: options, arranged according to their purpose.
0034: 
0035:   There are two ways of writing options: the short forms that start with
0036: a single @samp{-}, and the long forms that start with @samp{--}.  For
0037: example, @samp{-d} is a short form and @samp{--display} is the
0038: corresponding long form.
0039: 
0040:   The long forms with @samp{--} are easier to remember, but longer to
0041: type.  However, you don't have to spell out the whole option name; any
0042: unambiguous abbreviation is enough.  When a long option takes an
0043: argument, you can use either a space or an equal sign to separate the
0044: option name and the argument.  Thus, for the option @samp{--display},
0045: you can write either @samp{--display sugar-bombs:0.0} or
0046: @samp{--display=sugar-bombs:0.0}.  We recommend an equal sign because
0047: it makes the relationship clearer, and the tables below always show an
0048: equal sign.
0049: 
0050: @cindex initial options (command line)
0051: @cindex action options (command line)
0052: @vindex command-line-args
0053:   Most options specify how to initialize Emacs, or set parameters for
0054: the Emacs session.  We call them @dfn{initial options}.  A few options
0055: specify things to do, such as loading libraries or calling Lisp
0056: functions.  These are called @dfn{action options}.  These and file
0057: names together are called @dfn{action arguments}.  The action
0058: arguments are stored as a list of strings in the variable
0059: @code{command-line-args}.  (Actually, when Emacs starts up,
0060: @code{command-line-args} contains all the arguments passed from the
0061: command line; during initialization, the initial arguments are removed
0062: from this list when they are processed, leaving only the action
0063: arguments.)
0064: 
0065: @menu
0066: * Action Arguments::    Arguments to visit files, load libraries,
0067:                           and call functions.
0068: * Initial Options::     Arguments that take effect while starting Emacs.
0069: * Command Example::     Examples of using command line arguments.
0070: * Environment::         Environment variables that Emacs uses.
0071: * Display X::           Changing the default display and using remote login.
0072: * Font X::              Choosing a font for text, under X.
0073: * Colors X::            Choosing display colors.
0074: * Window Size X::       Start-up window size, under X.
0075: * Borders X::           Internal and outer borders, under X.
0076: * Title X::             Specifying the initial frame's title.
0077: * Icons X::             Choosing what sort of icon to use, under X.
0078: * Misc X::              Other display options.
0079: @end menu
0080: 
0081: @node Action Arguments
0082: @appendixsec Action Arguments
0083: 
0084:   Here is a table of action arguments:
0085: 
0086: @table @samp
0087: @item @var{file}
0088: @opindex --file
0089: @itemx --file=@var{file}
0090: @opindex --find-file
0091: @itemx --find-file=@var{file}
0092: @opindex --visit
0093: @itemx --visit=@var{file}
0094: @cindex visiting files, command-line argument
0095: @vindex inhibit-startup-buffer-menu
0096: Visit the specified @var{file}.  @xref{Visiting}.
0097: 
0098: When Emacs starts up, it displays the startup buffer in one window,
0099: and the buffer visiting @var{file} in another window
0100: (@pxref{Windows}).  If you supply more than one file argument, the
0101: displayed file is the last one specified on the command line; the
0102: other files are visited but their buffers are not shown.
0103: 
0104: If the startup buffer is disabled (@pxref{Entering Emacs}), then
0105: starting Emacs with one file argument displays the buffer visiting
0106: @var{file} in a single window.  With two file arguments, Emacs
0107: displays the files in two different windows.  With more than two file
0108: arguments, Emacs displays the last file specified in one window, plus
0109: another window with a Buffer Menu showing all the other files
0110: (@pxref{Several Buffers}).  To inhibit using the Buffer Menu for this,
0111: change the variable @code{inhibit-startup-buffer-menu} to @code{t}.
0112: 
0113: @item +@var{linenum} @var{file}
0114: @opindex +@var{linenum}
0115: Visit the specified @var{file}, then go to line number @var{linenum}
0116: in it.
0117: 
0118: @item +@var{linenum}:@var{columnnum} @var{file}
0119: Visit the specified @var{file}, then go to line number @var{linenum}
0120: and put point at column number @var{columnnum}.
0121: 
0122: @item -l @var{file}
0123: @opindex -l
0124: @itemx --load=@var{file}
0125: @opindex --load
0126: @cindex loading Lisp libraries, command-line argument
0127: Load a Lisp library named @var{file} with the function @code{load}.
0128: If @var{file} is not an absolute file name, Emacs first looks for it
0129: in the current directory, then in the directories listed in
0130: @code{load-path} (@pxref{Lisp Libraries}).
0131: 
0132: @strong{Warning:} If previous command-line arguments have visited
0133: files, the current directory is the directory of the last file
0134: visited.
0135: 
0136: @item -L @var{dir}
0137: @opindex -L
0138: @itemx --directory=@var{dir}
0139: @opindex --directory
0140: Prepend directory @var{dir} to the variable @code{load-path}.
0141: If you specify multiple @samp{-L} options, Emacs preserves the
0142: relative order; i.e., using @samp{-L /foo -L /bar} results in
0143: a @code{load-path} of the form @code{("/foo" "/bar" @dots{})}.
0144: If @var{dir} begins with @samp{:}, Emacs removes the @samp{:} and
0145: appends (rather than prepends) the remainder to @code{load-path}.
0146: (On MS Windows, use @samp{;} instead of @samp{:}; i.e., use
0147: the value of @code{path-separator}.)
0148: 
0149: @item -f @var{function}
0150: @opindex -f
0151: @itemx --funcall=@var{function}
0152: @opindex --funcall
0153: @cindex call Lisp functions, command-line argument
0154: Call Lisp function @var{function}.  If it is an interactive function
0155: (a command), it reads the arguments interactively just as if you had
0156: called the same function with a key sequence.  Otherwise, it calls the
0157: function with no arguments.
0158: 
0159: @item --eval=@var{expression}
0160: @opindex --eval
0161: @itemx --execute=@var{expression}
0162: @opindex --execute
0163: @cindex evaluate expression, command-line argument
0164: Evaluate Lisp expression @var{expression}.
0165: 
0166: @item --insert=@var{file}
0167: @opindex --insert
0168: @cindex insert file contents, command-line argument
0169: Insert the contents of @var{file} into the buffer that is current when
0170: this command-line argument is processed.  Usually, this is the
0171: @file{*scratch*} buffer (@pxref{Lisp Interaction}), but if arguments
0172: earlier on the command line visit files or switch buffers, that might
0173: be a different buffer.  The effect of this command-line argument is
0174: like what @kbd{M-x insert-file} does (@pxref{Misc File Ops}).
0175: 
0176: @item --kill
0177: @opindex --kill
0178: Exit from Emacs without asking for confirmation.
0179: 
0180: @item --help
0181: @opindex --help
0182: Print a usage message listing all available options, then exit
0183: successfully.
0184: 
0185: @item --version
0186: @opindex --version
0187: Print Emacs version, then exit successfully.
0188: @end table
0189: 
0190: @node Initial Options
0191: @appendixsec Initial Options
0192: 
0193:   The initial options specify parameters for the Emacs session.  This
0194: section describes the more general initial options; some other options
0195: specifically related to the X Window System appear in the following
0196: sections.
0197: 
0198:   Some initial options affect the loading of the initialization file.
0199: Normally, Emacs first loads @file{site-start.el} if it exists, then
0200: your own initialization file if it exists, and finally the default
0201: initialization file @file{default.el} if it exists (@pxref{Init
0202: File}).  Certain options prevent loading of some of these files or
0203: substitute other files for them.
0204: 
0205: @table @samp
0206: @item -chdir @var{directory}
0207: @opindex -chdir
0208: @itemx --chdir=@var{directory}
0209: @opindex --chdir
0210: @cindex change Emacs directory
0211: Change to @var{directory} before doing anything else.  This is mainly used
0212: by session management in X so that Emacs starts in the same directory as it
0213: stopped.  This makes desktop saving and restoring easier.
0214: 
0215: @item -t @var{device}
0216: @opindex -t
0217: @itemx --terminal=@var{device}
0218: @opindex --terminal
0219: @cindex device for Emacs terminal I/O
0220: Use @var{device} as the device for terminal input and output.  This
0221: option implies @samp{--no-window-system}.
0222: 
0223: @item -d @var{display}
0224: @opindex -d
0225: @itemx --display=@var{display}
0226: @opindex --display
0227: @cindex display for Emacs frame
0228: Use the X Window System and use the display named @var{display} to open
0229: the initial Emacs frame.  @xref{Display X}, for more details.
0230: 
0231: @item -nw
0232: @opindex -nw
0233: @itemx --no-window-system
0234: @opindex --no-window-system
0235: @cindex disable window system
0236: Don't communicate directly with the window system, disregarding the
0237: @env{DISPLAY} environment variable even if it is set.  This means that
0238: Emacs uses the terminal from which it was launched for all its display
0239: and input.
0240: 
0241: @cindex batch mode
0242: @item -batch
0243: @opindex --batch
0244: @itemx --batch
0245: Run Emacs in @dfn{batch mode}.  Batch mode is used for running
0246: programs written in Emacs Lisp from shell scripts, makefiles, and so
0247: on.  To invoke a Lisp program, use the @samp{-batch} option in
0248: conjunction with one or more of @samp{-l}, @samp{-f} or @samp{--eval}
0249: (@pxref{Action Arguments}).  @xref{Command Example}, for an example.
0250: 
0251: In batch mode, Emacs does not display the text being edited, and the
0252: standard terminal interrupt characters such as @kbd{C-z} and @kbd{C-c}
0253: have their usual effect.  Emacs functions that normally print a
0254: message in the echo area will print to either the standard output
0255: stream (@code{stdout}) or the standard error stream (@code{stderr})
0256: instead.  (To be precise, functions like @code{prin1}, @code{princ}
0257: and @code{print} print to @code{stdout}, while @code{message} and
0258: @code{error} print to @code{stderr}.)  Functions that normally read
0259: keyboard input from the minibuffer take their input from the
0260: terminal's standard input stream (@code{stdin}) instead.
0261: 
0262: @samp{--batch} implies @samp{-q} (do not load an initialization file),
0263: but @file{site-start.el} is loaded nonetheless.  It also causes Emacs
0264: to exit after processing all the command options.  In addition, it
0265: disables auto-saving except in buffers for which auto-saving is
0266: explicitly requested, and when saving files it omits the @code{fsync}
0267: system call unless otherwise requested.
0268: 
0269: @item --script @var{file}
0270: @opindex --script
0271: @cindex script mode
0272: Run Emacs in batch mode, like @samp{--batch}, and then read and
0273: execute the Lisp code in @var{file}.
0274: 
0275: The normal use of this option is in executable script files that run
0276: Emacs.  They can start with this text on the first line
0277: 
0278: @example
0279: #!/usr/bin/emacs --script
0280: @end example
0281: 
0282: @noindent
0283: which will invoke Emacs with @samp{--script} and supply the name of
0284: the script file as @var{file}.  Emacs Lisp then treats the @samp{#!}
0285: on this first line as a comment delimiter.
0286: 
0287: @item --no-build-details
0288: @opindex --no-build-details
0289: @cindex build details
0290: @cindex deterministic build
0291: Omit details like system name and build time from the Emacs executable,
0292: so that builds are more deterministic.
0293: 
0294: @item -q
0295: @opindex -q
0296: @itemx --no-init-file
0297: @opindex --no-init-file
0298: @cindex bypassing init and @file{default.el} file
0299: @cindex init file, not loading
0300: @cindex @file{default.el} file, not loading
0301: Do not load any initialization file (@pxref{Init File}).  When Emacs
0302: is invoked with this option, the Customize facility does not allow
0303: options to be saved (@pxref{Easy Customization}).  This option does
0304: not disable loading @file{site-start.el}.
0305: 
0306: @item --no-site-file
0307: @opindex --no-site-file
0308: @itemx -nsl
0309: @opindex -nsl
0310: @cindex @file{site-start.el} file, not loading
0311: Do not load @file{site-start.el} (@pxref{Init File}).  The @samp{-Q}
0312: option does this too, but other options like @samp{-q} do not.
0313: 
0314: @item --no-site-lisp
0315: @opindex --no-site-lisp
0316: @cindex @file{site-lisp} files, not loading
0317: Do not include the @file{site-lisp} directories in @code{load-path}
0318: (@pxref{Init File}).  The @samp{-Q} option does this too.
0319: 
0320: @item --no-splash
0321: @opindex --no-splash
0322: @cindex splash screen
0323: @cindex startup message
0324: Do not display a startup screen.  You can also achieve this effect by
0325: setting the variable @code{inhibit-startup-screen} to non-@code{nil}
0326: in your initialization file (@pxref{Entering Emacs}).
0327: 
0328: @item --no-x-resources
0329: @opindex --no-x-resources
0330: @cindex X resources, not loading
0331: Do not load X resources.  You can also achieve this effect by setting
0332: the variable @code{inhibit-x-resources} to @code{t} in your
0333: initialization file (@pxref{Resources}).
0334: 
0335: @item -Q
0336: @opindex -Q
0337: @itemx --quick
0338: @opindex --quick
0339: Start Emacs with minimum customizations.  This is similar to using
0340: @samp{-q}, @samp{--no-site-file}, @samp{--no-site-lisp},
0341: @samp{--no-x-resources}, and @samp{--no-splash} together..
0342: 
0343: @item -daemon
0344: @opindex -daemon
0345: @itemx --daemon[=@var{name}]
0346: @opindex --daemon
0347: @itemx --bg-daemon[=@var{name}]
0348: @itemx --fg-daemon[=@var{name}]
0349: Start Emacs as a daemon: after Emacs starts up, it starts the Emacs
0350: server without opening any frames.
0351: (Optionally, you can specify an explicit @var{name} for the server.)
0352: You can then use the @command{emacsclient} command to connect to Emacs
0353: for editing.  @xref{Emacs Server}, for information about using Emacs
0354: as a daemon.  A ``background'' daemon disconnects from the terminal
0355: and runs in the background (@samp{--daemon} is an alias for
0356: @samp{--bg-daemon}).
0357: 
0358: @item --no-desktop
0359: @opindex --no-desktop
0360: Do not reload any saved desktop.  @xref{Saving Emacs Sessions}.
0361: 
0362: @item -u @var{user}
0363: @opindex -u
0364: @itemx --user=@var{user}
0365: @opindex --user
0366: @cindex load init file of another user
0367: Load @var{user}'s initialization file instead of your
0368: own@footnote{This option has no effect on MS-Windows.}.
0369: 
0370: @item --debug-init
0371: @opindex --debug-init
0372: @cindex errors in init file
0373: Enable the Emacs Lisp debugger for errors in the init file.
0374: @xref{Error Debugging,, Entering the Debugger on an Error, elisp, The
0375: GNU Emacs Lisp Reference Manual}.
0376: 
0377: @item --module-assertions
0378: @opindex --module-assertions
0379: @cindex module verification
0380: Enable expensive correctness checks when dealing with dynamically
0381: loadable modules.  This is intended for module authors that wish to
0382: verify that their module conforms to the module API requirements.  The
0383: option makes Emacs abort if a module-related assertion triggers.
0384: @xref{Writing Dynamic Modules,, Writing Dynamically-Loaded Modules,
0385: elisp, The GNU Emacs Lisp Reference Manual}.
0386: 
0387: @item --dump-file=@var{file}
0388: @opindex --dump-file
0389: @cindex specify dump file
0390: Load the dumped Emacs state from the named @var{file}.  By default, an
0391: installed Emacs will look for its dump state in a file named
0392: @file{@var{emacs}.pdmp} in the directory where the Emacs installation
0393: puts the architecture-dependent files; the variable
0394: @code{exec-directory} holds the name of that directory.  @var{emacs}
0395: is the name of the Emacs executable file, normally just @file{emacs}.
0396: (When you invoke Emacs from the @file{src} directory where it was
0397: built without installing it, it will look for the dump file in the
0398: directory of the executable.)  If you rename or move the dump file to
0399: a different place, you can use this option to tell Emacs where to find
0400: that file.
0401: @end table
0402: 
0403: @node Command Example
0404: @appendixsec Command Argument Example
0405: 
0406:   Here is an example of using Emacs with arguments and options.  It
0407: assumes you have a Lisp program file called @file{hack-c.el} which, when
0408: loaded, performs some useful operation on the current buffer, expected
0409: to be a C program.
0410: 
0411: @example
0412: emacs --batch foo.c -l hack-c -f save-buffer >& log
0413: @end example
0414: 
0415: @noindent
0416: This says to visit @file{foo.c}, load @file{hack-c.el} (which makes
0417: changes in the visited file), save @file{foo.c} (note that
0418: @code{save-buffer} is the function that @kbd{C-x C-s} is bound to), and
0419: then exit back to the shell (because of @samp{--batch}).  @samp{--batch}
0420: also guarantees there will be no problem redirecting output to
0421: @file{log}, because Emacs will not assume that it has a display terminal
0422: to work with.
0423: 
0424: @node Environment
0425: @appendixsec Environment Variables
0426: @cindex environment variables
0427: 
0428:   The @dfn{environment} is a feature of the operating system; it
0429: consists of a collection of variables with names and values.  Each
0430: variable is called an @dfn{environment variable}; environment variable
0431: names are case-sensitive, and it is conventional to use upper case
0432: letters only.  The values are all text strings.
0433: 
0434:   What makes the environment useful is that subprocesses inherit the
0435: environment automatically from their parent process.  This means you
0436: can set up an environment variable in your login shell, and all the
0437: programs you run (including Emacs) will automatically see it.
0438: Subprocesses of Emacs (such as shells, compilers, and version control
0439: programs) inherit the environment from Emacs, too.
0440: 
0441: @findex setenv
0442: @findex getenv
0443: @vindex initial-environment
0444:   Inside Emacs, the command @kbd{M-x getenv} reads the name of an
0445: environment variable, and prints its value in the echo area.  @kbd{M-x
0446: setenv} sets a variable in the Emacs environment, and @kbd{C-u M-x
0447: setenv} removes a variable.  (Environment variable substitutions with
0448: @samp{$} work in the value just as in file names; see @ref{File Names
0449: with $}.)  The variable @code{initial-environment} stores the initial
0450: environment inherited by Emacs.
0451: 
0452:   The way to set environment variables outside of Emacs depends on the
0453: operating system, and especially the shell that you are using.  For
0454: example, here's how to set the environment variable @env{ORGANIZATION}
0455: to @samp{not very much} using Bash:
0456: 
0457: @example
0458: export ORGANIZATION="not very much"
0459: @end example
0460: 
0461: @noindent
0462: and here's how to do it in csh or tcsh:
0463: 
0464: @example
0465: setenv ORGANIZATION "not very much"
0466: @end example
0467: 
0468:   When Emacs is using the X Window System, various environment
0469: variables that control X work for Emacs as well.  See the X
0470: documentation for more information.
0471: 
0472: @menu
0473: * General Variables::   Environment variables that all versions of Emacs use.
0474: * Misc Variables::      Certain system-specific variables.
0475: * MS-Windows Registry:: An alternative to the environment on MS-Windows.
0476: @end menu
0477: 
0478: @node General Variables
0479: @appendixsubsec General Variables
0480: 
0481:   Here is an alphabetical list of environment variables that have
0482: special meanings in Emacs.  Most of these variables are also used by
0483: some other programs.  Emacs does not require any of these environment
0484: variables to be set, but it uses their values if they are set.
0485: 
0486: @c This used to be @vtable, but that enters the variables alone into
0487: @c the Variable Index, which in some cases, like HOME, might be
0488: @c confused with keys by that name, and other cases, like NAME,
0489: @c might be confused with general-purpose phrases.
0490: @table @env
0491: @item CDPATH
0492: @vindex CDPATH@r{, environment variable}
0493: Used by the @code{cd} command to search for the directory you specify,
0494: when you specify a relative directory,
0495: @item DBUS_SESSION_BUS_ADDRESS
0496: @vindex DBUS_SESSION_BUS_ADDRESS@r{, environment variable}
0497: Used by D-Bus when Emacs is compiled with it.  Usually, there is no
0498: need to change it.  Setting it to a dummy address, like
0499: @samp{unix:path=/dev/null}, suppresses connections to the D-Bus session
0500: bus as well as autolaunching the D-Bus session bus if not running yet.
0501: @item EMACSDATA
0502: @vindex EMACSDATA@r{, environment variable}
0503: Directory for the architecture-independent files that come with Emacs.
0504: This is used to initialize the variable @code{data-directory}.
0505: @item EMACSDOC
0506: @vindex EMACSDOC@r{, environment variable}
0507: Directory for the documentation string file, which is used to
0508: initialize the Lisp variable @code{doc-directory}.
0509: @item EMACSLOADPATH
0510: @vindex EMACSLOADPATH@r{, environment variable}
0511: A colon-separated list of directories@footnote{Here and below,
0512: whenever we say ``colon-separated list of directories'', it pertains
0513: to Unix and GNU/Linux systems.  On MS-DOS and MS-Windows, the
0514: directories are separated by semi-colons instead, since DOS/Windows
0515: file names might include a colon after a drive letter.} to search for
0516: Emacs Lisp files.  If set, it modifies the usual initial value of the
0517: @code{load-path} variable (@pxref{Lisp Libraries}).  An empty element
0518: stands for the default value of @code{load-path}; e.g., using
0519: @samp{EMACSLOADPATH="/tmp:"} adds @file{/tmp} to the front of
0520: the default @code{load-path}.  To specify an empty element in the
0521: middle of the list, use 2 colons in a row, as in
0522: @samp{EMACSLOADPATH="/tmp::/foo"}.
0523: @item EMACSPATH
0524: @vindex EMACSPATH@r{, environment variable}
0525: A colon-separated list of directories to search for executable files.
0526: If set, Emacs uses this in addition to @env{PATH} (see below) when
0527: initializing the variable @code{exec-path} (@pxref{Shell}).
0528: @item EMAIL
0529: @vindex EMAIL@r{, environment variable}
0530: @vindex user-mail-address@r{, initialization}
0531: Your email address; used to initialize the Lisp variable
0532: @code{user-mail-address}, which the Emacs mail interface puts into the
0533: @samp{From} header of outgoing messages (@pxref{Mail Headers}).
0534: @item ESHELL
0535: @vindex ESHELL@r{, environment variable}
0536: Used for shell-mode to override the @env{SHELL} environment variable
0537: (@pxref{Interactive Shell}).
0538: @item HISTFILE
0539: @vindex HISTFILE@r{, environment variable}
0540: The name of the file that shell commands are saved in between logins.
0541: This variable defaults to @file{~/.bash_history} if you use Bash, to
0542: @file{~/.sh_history} if you use ksh, and to @file{~/.history}
0543: otherwise.
0544: @item HOME
0545: @vindex HOME@r{, environment variable}
0546: The location of your files in the directory tree; used for expansion
0547: of file names starting with a tilde (@file{~}).  If set, it should be
0548: set to an absolute file name.  (If set to a relative file name, Emacs
0549: interprets it relative to the directory where Emacs was started, but
0550: we don't recommend to use this feature.)  If unset, @env{HOME}
0551: normally defaults to the home directory of the user given by
0552: @env{LOGNAME}, @env{USER} or your user ID, or to @file{/} if all else
0553: fails.  On MS-DOS, it defaults to the directory from which Emacs was
0554: started, with @samp{/bin} removed from the end if it was present.  On
0555: Windows, the default value of @env{HOME} is the @file{Application
0556: Data} subdirectory of the user profile directory (normally, this is
0557: @file{C:/Documents and Settings/@var{username}/Application Data},
0558: where @var{username} is your user name), though for backwards
0559: compatibility @file{C:/} will be used instead if a @file{.emacs} file
0560: is found there.
0561: @item HOSTNAME
0562: @vindex HOSTNAME@r{, environment variable}
0563: The name of the machine that Emacs is running on.
0564: @c complete.el is obsolete since 24.1.
0565: @ignore
0566: @item INCPATH
0567: A colon-separated list of directories.  Used by the @code{complete} package
0568: to search for files.
0569: @end ignore
0570: @item INFOPATH
0571: @vindex INFOPATH@r{, environment variable}
0572: A colon-separated list of directories in which to search for Info files.
0573: @item LC_ALL
0574: @vindex LC_ALL@r{, environment variable}
0575: @itemx LC_COLLATE
0576: @vindex LC_COLLATE@r{, environment variable}
0577: @itemx LC_CTYPE
0578: @vindex LC_CTYPE@r{, environment variable}
0579: @itemx LC_MESSAGES
0580: @vindex LC_MESSAGES@r{, environment variable}
0581: @itemx LC_MONETARY
0582: @vindex LC_MONETARY@r{, environment variable}
0583: @itemx LC_NUMERIC
0584: @vindex LC_NUMERIC@r{, environment variable}
0585: @itemx LC_TIME
0586: @vindex LC_TIME@r{, environment variable}
0587: @itemx LANG
0588: @vindex LANG@r{, environment variable}
0589: The user's preferred locale.  The locale has six categories, specified
0590: by the environment variables @env{LC_COLLATE} for sorting,
0591: @env{LC_CTYPE} for character encoding, @env{LC_MESSAGES} for system
0592: messages, @env{LC_MONETARY} for monetary formats, @env{LC_NUMERIC} for
0593: numbers, and @env{LC_TIME} for dates and times.  If one of these
0594: variables is not set, the category defaults to the value of the
0595: @env{LANG} environment variable, or to the default @samp{C} locale if
0596: @env{LANG} is not set.  But if @env{LC_ALL} is specified, it overrides
0597: the settings of all the other locale environment variables.
0598: 
0599: On MS-Windows and macOS, if @env{LANG} is not already set in the
0600: environment, Emacs sets it based on the system-wide default.  You can
0601: set this in the ``Regional Settings'' Control Panel on some versions
0602: of MS-Windows, and in the ``Language and Region'' System Preference on
0603: macOS.
0604: 
0605: The value of the @env{LC_CTYPE} category is
0606: matched against entries in @code{locale-language-names},
0607: @code{locale-charset-language-names}, and
0608: @code{locale-preferred-coding-systems}, to select a default language
0609: environment and coding system.  @xref{Language Environments}.
0610: @item LOGNAME
0611: @vindex LOGNAME@r{, environment variable}
0612: The user's login name.  See also @env{USER}.
0613: @item MAIL
0614: @vindex MAIL@r{, environment variable}
0615: The name of your system mail inbox.
0616: @ifnottex
0617: @item MH
0618: @vindex MH@r{, environment variable}
0619: Name of setup file for the mh system.  @xref{Top,,MH-E,mh-e, The Emacs
0620: Interface to MH}.
0621: @end ifnottex
0622: @item NAME
0623: @vindex NAME@r{, environment variable}
0624: Your real-world name.  This is used to initialize the variable
0625: @code{user-full-name} (@pxref{Mail Headers}).
0626: @item NNTPSERVER
0627: @vindex NNTPSERVER@r{, environment variable}
0628: The name of the news server.  Used by the mh and Gnus packages.
0629: @item ORGANIZATION
0630: @vindex ORGANIZATION@r{, environment variable}
0631: The name of the organization to which you belong.  Used for setting the
0632: @samp{Organization:} header in your posts from the Gnus package.
0633: @item PATH
0634: @vindex PATH@r{, environment variable}
0635: A colon-separated list of directories containing executable files.
0636: This is used to initialize the variable @code{exec-path}
0637: (@pxref{Shell}).
0638: @item PWD
0639: @vindex PWD@r{, environment variable}
0640: If set, this should be the default directory when Emacs was started.
0641: @item REPLYTO
0642: @vindex REPLYTO@r{, environment variable}
0643: If set, this specifies an initial value for the variable
0644: @code{mail-default-reply-to} (@pxref{Mail Headers}).
0645: @item SAVEDIR
0646: @vindex SAVEDIR@r{, environment variable}
0647: The name of a directory in which news articles are saved by default.
0648: Used by the Gnus package.
0649: @item SHELL
0650: @vindex SHELL@r{, environment variable}
0651: The name of an interpreter used to parse and execute programs run from
0652: inside Emacs.
0653: @item SMTPSERVER
0654: @vindex SMTPSERVER@r{, environment variable}
0655: The name of the outgoing mail server.  This is used to initialize the
0656: variable @code{smtpmail-smtp-server} (@pxref{Mail Sending}).
0657: @cindex background mode, on @command{xterm}
0658: @item TERM
0659: @vindex TERM@r{, environment variable}
0660: The type of the terminal that Emacs is using.  This variable must be
0661: set unless Emacs is run in batch mode.  On MS-DOS, it defaults to
0662: @samp{internal}, which specifies a built-in terminal emulation that
0663: handles the machine's own display.
0664: @item TERMCAP
0665: @vindex TERMCAP@r{, environment variable}
0666: The name of the termcap library file describing how to program the
0667: terminal specified by @env{TERM}.  This defaults to
0668: @file{/etc/termcap}.
0669: @item TMPDIR
0670: @vindex TMPDIR@r{, environment variable}
0671: @itemx TMP
0672: @vindex TMP@r{, environment variable}
0673: @itemx TEMP
0674: @vindex TEMP@r{, environment variable}
0675: These environment variables are used to initialize the variable
0676: @code{temporary-file-directory}, which specifies a directory in which
0677: to put temporary files (@pxref{Backup}).  Emacs tries to use
0678: @env{TMPDIR} first.  If that is unset, Emacs normally falls back on
0679: @file{/tmp}, but on MS-Windows and MS-DOS it instead falls back on
0680: @env{TMP}, then @env{TEMP}, and finally @file{c:/temp}.
0681: @item TZ
0682: @vindex TZ@r{, environment variable}
0683: This specifies the default time zone and possibly also daylight
0684: saving time information.  @xref{Time Zone Rules,,, elisp, The GNU
0685: Emacs Lisp Reference Manual}.  On MS-DOS, if @env{TZ} is not set in the
0686: environment when Emacs starts, Emacs defines a default value as
0687: appropriate for the country code returned by DOS@.  On MS-Windows, Emacs
0688: does not use @env{TZ} at all.
0689: @item USER
0690: @vindex USER@r{, environment variable}
0691: The user's login name.  See also @env{LOGNAME}.  On MS-DOS, this
0692: defaults to @samp{root}.
0693: @item VERSION_CONTROL
0694: @vindex VERSION_CONTROL@r{, environment variable}
0695: Used to initialize the @code{version-control} variable (@pxref{Backup
0696: Names}).
0697: @end table
0698: 
0699: @node Misc Variables
0700: @appendixsubsec Miscellaneous Variables
0701: 
0702: These variables are used only on particular configurations:
0703: 
0704: @vtable @env
0705: @item COMSPEC
0706: On MS-DOS and MS-Windows, the name of the command interpreter to use
0707: when invoking batch files and commands internal to the shell.  On MS-DOS
0708: this is also used to make a default value for the @env{SHELL} environment
0709: variable.
0710: 
0711: @item NAME
0712: On MS-DOS, this variable defaults to the value of the @env{USER}
0713: variable.
0714: 
0715: @item EMACSTEST
0716: On MS-DOS, this specifies a file to use to log the operation of the
0717: internal terminal emulator.  This feature is useful for submitting bug
0718: reports.
0719: 
0720: @item EMACSCOLORS
0721: On MS-DOS, this specifies the screen colors.  It is useful to set them
0722: this way, since otherwise Emacs would display the default colors
0723: momentarily when it starts up.
0724: 
0725: The value of this variable should be the two-character encoding of the
0726: foreground (the first character) and the background (the second
0727: character) colors of the default face.  Each character should be the
0728: hexadecimal code for the desired color on a standard PC text-mode
0729: display.  For example, to get blue text on a light gray background,
0730: specify @samp{EMACSCOLORS=17}, since 1 is the code of the blue color and
0731: 7 is the code of the light gray color.
0732: 
0733: The PC display usually supports only eight background colors.  However,
0734: Emacs switches the DOS display to a mode where all 16 colors can be used
0735: for the background, so all four bits of the background color are
0736: actually used.
0737: 
0738: @item PRELOAD_WINSOCK
0739: On MS-Windows, if you set this variable, Emacs will load and initialize
0740: the network library at startup, instead of waiting until the first
0741: time it is required.
0742: 
0743: @item emacs_dir
0744: On MS-Windows, @env{emacs_dir} is a special environment variable, which
0745: indicates the full path of the directory in which Emacs is installed.
0746: If Emacs is installed in the standard directory structure, it
0747: calculates this value automatically.  It is not much use setting this
0748: variable yourself unless your installation is non-standard, since
0749: unlike other environment variables, it will be overridden by Emacs at
0750: startup.  When setting other environment variables, such as
0751: @env{EMACSLOADPATH}, you may find it useful to use @env{emacs_dir}
0752: rather than hard-coding an absolute path.  This allows multiple
0753: versions of Emacs to share the same environment variable settings, and
0754: it allows you to move the Emacs installation directory, without
0755: changing any environment or registry settings.
0756: @end vtable
0757: 
0758: @node MS-Windows Registry
0759: @appendixsubsec The MS-Windows System Registry
0760: @pindex addpm, MS-Windows installation program
0761: @cindex registry, setting environment variables (MS-Windows)
0762: 
0763: On MS-Windows, the installation program @command{addpm.exe} adds
0764: values for @env{emacs_dir}, @env{EMACSLOADPATH}, @env{EMACSDATA},
0765: @env{EMACSPATH}, @env{EMACSDOC}, @env{SHELL} and @env{TERM} to the
0766: @file{HKEY_LOCAL_MACHINE} section of the system registry, under
0767: @file{/Software/GNU/Emacs}.  It does this because there is no standard
0768: place to set environment variables across different versions of
0769: Windows.  Running @command{addpm.exe} is no longer strictly necessary
0770: in recent versions of Emacs, but if you are upgrading from an older
0771: version, running @command{addpm.exe} ensures that you do not have
0772: older registry entries from a previous installation, which may not be
0773: compatible with the latest version of Emacs.
0774: 
0775: When Emacs starts, as well as checking the environment, it also checks
0776: the System Registry for those variables and for @env{HOME}, @env{LANG}
0777: and @env{PRELOAD_WINSOCK}.
0778: 
0779: To determine the value of those variables, Emacs goes through the
0780: following procedure.  First, the environment is checked.  If the
0781: variable is not found there, Emacs looks for registry keys by that
0782: name under @file{/Software/GNU/Emacs}; first in the
0783: @file{HKEY_CURRENT_USER} section of the registry, and if not found
0784: there, in the @file{HKEY_LOCAL_MACHINE} section.  Finally, if Emacs
0785: still cannot determine the values, compiled-in defaults are used.
0786: 
0787: In addition to the environment variables above, you can also add
0788: settings to the @file{/Software/GNU/Emacs} registry key to specify X
0789: resources (@pxref{X Resources}).  Most of the settings you can specify
0790: in your @file{.Xdefaults} file can be set from that registry key.
0791: 
0792: @node Display X
0793: @appendixsec Specifying the Display Name
0794: @cindex display name (X Window System)
0795: @cindex @env{DISPLAY} environment variable
0796: 
0797:   The environment variable @env{DISPLAY} tells all X clients,
0798: including Emacs, where to display their windows.  Its value is set by
0799: default in ordinary circumstances, when you start an X server and run
0800: jobs locally.  You can specify the display yourself; one reason to do
0801: this is if you want to log into another system and run Emacs there,
0802: and have the window displayed at your local terminal.
0803: 
0804:   @env{DISPLAY} has the syntax
0805: @samp{@var{host}:@var{display}.@var{screen}}, where @var{host} is the
0806: host name of the X Window System server machine, @var{display} is an
0807: arbitrarily-assigned number that distinguishes your server (X
0808: terminal) from other servers on the same machine, and @var{screen} is
0809: a field that allows an X server to control multiple terminal screens.
0810: The period and the @var{screen} field are optional.  If included,
0811: @var{screen} is usually zero.
0812: 
0813:   For example, if your host is named @samp{glasperle} and your server is
0814: the first (or perhaps the only) server listed in the configuration, your
0815: @env{DISPLAY} is @samp{glasperle:0.0}.
0816: 
0817:   You can specify the display name explicitly when you run Emacs, either
0818: by changing the @env{DISPLAY} variable, or with the option @samp{-d
0819: @var{display}} or @samp{--display=@var{display}}.  Here is an example:
0820: 
0821: @smallexample
0822: emacs --display=glasperle:0 &
0823: @end smallexample
0824: 
0825:   You can inhibit the use of the X window system with the @samp{-nw}
0826: option.  Then Emacs uses its controlling text terminal for display.
0827: @xref{Initial Options}.
0828: 
0829:   Sometimes, security arrangements prevent a program on a remote system
0830: from displaying on your local system.  In this case, trying to run Emacs
0831: produces messages like this:
0832: 
0833: @smallexample
0834: Xlib:  connection to "glasperle:0.0" refused by server
0835: @end smallexample
0836: 
0837: @noindent
0838: You might be able to overcome this problem by using the @command{xhost}
0839: command on the local system to give permission for access from your
0840: remote machine.
0841: 
0842: @node Font X
0843: @appendixsec Font Specification Options
0844: @cindex font name (X Window System)
0845: 
0846: You can use the command line option @samp{-fn @var{font}} (or
0847: @samp{--font}, which is an alias for @samp{-fn}) to specify a default
0848: font:
0849: 
0850: @table @samp
0851: @item -fn @var{font}
0852: @opindex -fn
0853: @itemx --font=@var{font}
0854: @opindex --font
0855: @cindex specify default font from the command line
0856: Use @var{font} as the default font.
0857: @end table
0858: 
0859: When passing a font name to Emacs on the command line, you may need to
0860: quote it, by enclosing it in quotation marks, if it contains
0861: characters that the shell treats specially (e.g., spaces).  For
0862: example:
0863: 
0864: @smallexample
0865: emacs -fn "DejaVu Sans Mono-12"
0866: @end smallexample
0867: 
0868: @xref{Fonts}, for details about font names and other ways to specify
0869: the default font.
0870: 
0871: @node Colors X
0872: @appendixsec Window Color Options
0873: @cindex color of window, from command line
0874: @cindex text colors, from command line
0875: 
0876:   You can use the following command-line options to specify the colors
0877: to use for various parts of the Emacs display.  Colors may be
0878: specified using either color names or RGB triplets (@pxref{Colors}).
0879: 
0880: @table @samp
0881: @item -fg @var{color}
0882: @opindex -fg
0883: @itemx --foreground-color=@var{color}
0884: @opindex --foreground-color
0885: @cindex foreground color, command-line argument
0886: Specify the foreground color, overriding the color specified by the
0887: @code{default} face (@pxref{Faces}).
0888: @item -bg @var{color}
0889: @opindex -bg
0890: @itemx --background-color=@var{color}
0891: @opindex --background-color
0892: @cindex background color, command-line argument
0893: Specify the background color, overriding the color specified by the
0894: @code{default} face.
0895: @item -bd @var{color}
0896: @opindex -bd
0897: @itemx --border-color=@var{color}
0898: @opindex --border-color
0899: @cindex border color, command-line argument
0900: Specify the color of the border of the X window.  This has no effect
0901: if Emacs is compiled with GTK+ support.
0902: @item -cr @var{color}
0903: @opindex -cr
0904: @itemx --cursor-color=@var{color}
0905: @opindex --cursor-color
0906: @cindex cursor color, command-line argument
0907: Specify the color of the Emacs cursor which indicates where point is.
0908: @item -ms @var{color}
0909: @opindex -ms
0910: @itemx --mouse-color=@var{color}
0911: @opindex --mouse-color
0912: @cindex mouse pointer color, command-line argument
0913: Specify the color for the mouse cursor when the mouse is in the Emacs window.
0914: @item -r
0915: @opindex -r
0916: @itemx -rv
0917: @opindex -rv
0918: @itemx --reverse-video
0919: @opindex --reverse-video
0920: @cindex reverse video, command-line argument
0921: Reverse video: swap the foreground and background colors.
0922: @item --color=@var{mode}
0923: @opindex --color
0924: @cindex standard colors on a character terminal
0925: @cindex override character terminal color support
0926: Set the @dfn{color support mode} when Emacs is run on a text terminal.
0927: This option overrides the number of supported colors that the
0928: character terminal advertises in its @code{termcap} or @code{terminfo}
0929: database.  The parameter @var{mode} can be one of the following:
0930: @table @samp
0931: @item never
0932: @itemx no
0933: Don't use colors even if the terminal's capabilities specify color
0934: support.
0935: @item default
0936: @itemx auto
0937: Same as when @option{--color} is not used at all: Emacs detects at
0938: startup whether the terminal supports colors, and if it does, turns on
0939: colored display.
0940: @item always
0941: @itemx yes
0942: @itemx ansi8
0943: Turn on the color support unconditionally, and use color commands
0944: specified by the ANSI escape sequences for the 8 standard colors.
0945: @item @var{num}
0946: Use color mode for @var{num} colors.  If @var{num} is @minus{}1, turn off
0947: color support (equivalent to @samp{never}); if it is 0, use the
0948: default color support for this terminal (equivalent to @samp{auto});
0949: otherwise use an appropriate standard mode for @var{num} colors.
0950: Depending on your terminal's capabilities, Emacs might be able to turn
0951: on a color mode for 8, 16, 88, or 256 as the value of @var{num}.  If
0952: there is no mode that supports @var{num} colors, Emacs acts as if
0953: @var{num} were 0, i.e., it uses the terminal's default color support
0954: mode.
0955: @end table
0956: If @var{mode} is omitted, it defaults to @var{ansi8}.
0957: @end table
0958: 
0959:   For example, to use a coral mouse cursor and a slate blue text cursor,
0960: enter:
0961: 
0962: @example
0963: emacs -ms coral -cr 'slate blue' &
0964: @end example
0965: 
0966:   You can reverse the foreground and background colors through the
0967: @samp{-rv} option or with the X resource @samp{reverseVideo}.
0968: 
0969:   The @samp{-fg}, @samp{-bg}, and @samp{-rv} options function on text
0970: terminals as well as on graphical displays.
0971: 
0972: @node Window Size X
0973: @appendixsec Options for Window Size and Position
0974: @cindex geometry of Emacs window
0975: @cindex position and size of Emacs frame
0976: @cindex width and height of Emacs frame
0977: @cindex specifying fullscreen for Emacs frame
0978: 
0979:   Here is a list of the command-line options for specifying size and
0980: position of the initial Emacs frame:
0981: 
0982: @table @samp
0983: @item -g @var{width}x@var{height}@r{[@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}@r{]]}
0984: @opindex -g
0985: @itemx --geometry=@var{width}x@var{height}@r{[@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}@r{]]}
0986: @opindex --geometry
0987: @cindex geometry, command-line argument
0988: Specify the size @var{width} and @var{height} (measured in character
0989: columns and lines), and positions @var{xoffset} and @var{yoffset}
0990: (measured in pixels).  The @var{width} and @var{height} parameters
0991: apply to all frames, whereas @var{xoffset} and @var{yoffset} only to
0992: the initial frame.
0993: 
0994: @item -fs
0995: @opindex -fs
0996: @itemx --fullscreen
0997: @opindex --fullscreen
0998: @cindex fullscreen, command-line argument
0999: Specify that width and height should be that of the screen.  Normally
1000: no window manager decorations are shown.  (After starting Emacs,
1001: you can toggle this state using @key{F11}, @code{toggle-frame-fullscreen}.)
1002: 
1003: @item -mm
1004: @opindex -mm
1005: @itemx --maximized
1006: @opindex --maximized
1007: @cindex maximized, command-line argument
1008: Specify that the Emacs frame should be maximized.  This normally
1009: means that the frame has window manager decorations.
1010: (After starting Emacs, you can toggle this state using @kbd{M-F10},
1011: @code{toggle-frame-maximized}.)
1012: 
1013: @item -fh
1014: @opindex -fh
1015: @itemx --fullheight
1016: @opindex --fullheight
1017: @cindex fullheight, command-line argument
1018: Specify that the height should be the height of the screen.
1019: 
1020: @item -fw
1021: @opindex -fw
1022: @itemx --fullwidth
1023: @opindex --fullwidth
1024: @cindex fullwidth, command-line argument
1025: Specify that the width should be the width of the screen.
1026: @end table
1027: 
1028: @noindent
1029: In the @samp{--geometry} option, @code{@r{@{}+-@r{@}}} means either a plus
1030:  sign or a minus sign.  A plus
1031: sign before @var{xoffset} means it is the distance from the left side of
1032: the screen; a minus sign means it counts from the right side.  A plus
1033: sign before @var{yoffset} means it is the distance from the top of the
1034: screen, and a minus sign there indicates the distance from the bottom.
1035: The values @var{xoffset} and @var{yoffset} may themselves be positive or
1036: negative, but that doesn't change their meaning, only their direction.
1037: 
1038:   Emacs uses the same units as @command{xterm} does to interpret the geometry.
1039: The @var{width} and @var{height} are measured in characters, so a large font
1040: creates a larger frame than a small font.  (If you specify a proportional
1041: font, Emacs uses its maximum bounds width as the width unit.)  The
1042: @var{xoffset} and @var{yoffset} are measured in pixels.
1043: 
1044:   You do not have to specify all of the fields in the geometry
1045: specification.  If you omit both @var{xoffset} and @var{yoffset}, the
1046: window manager decides where to put the Emacs frame, possibly by
1047: letting you place it with the mouse.  For example, @samp{164x55}
1048: specifies a window 164 columns wide, enough for two ordinary width
1049: windows side by side, and 55 lines tall.
1050: 
1051:   The default frame width is 80 characters and the default height is
1052: 36 lines.  You can omit either the width or the height or both.  If
1053: you start the geometry with an integer, Emacs interprets it as the
1054: width.  If you start with an @samp{x} followed by an integer, Emacs
1055: interprets it as the height.  Thus, @samp{81} specifies just the
1056: width; @samp{x45} specifies just the height.
1057: 
1058:   If you start the geometry with @samp{+} or @samp{-}, that introduces
1059: an offset, which means both sizes are omitted.  Thus, @samp{-3}
1060: specifies the @var{xoffset} only.  (If you give just one offset, it is
1061: always @var{xoffset}.)  @samp{+3-3} specifies both the @var{xoffset}
1062: and the @var{yoffset}, placing the frame near the bottom left of the
1063: screen.
1064: 
1065:   You can specify a default for any or all of the fields in your X
1066: resource file (@pxref{Resources}), and then override selected fields
1067: with a @samp{--geometry} option.
1068: 
1069:   Since the mode line and the echo area occupy the last 2 lines of the
1070: frame, the height of the initial text window is 2 less than the height
1071: specified in your geometry.  In non-X-toolkit versions of Emacs, the
1072: menu bar also takes one line of the specified number.  But in the X
1073: toolkit version, the menu bar is additional and does not count against
1074: the specified height.  The tool bar, if present, is also additional.
1075: 
1076:   Enabling or disabling the menu bar or tool bar alters the amount of
1077: space available for ordinary text.  Therefore, if Emacs starts up with
1078: a tool bar (which is the default), and handles the geometry
1079: specification assuming there is a tool bar, and then your
1080: initialization file disables the tool bar, you will end up with a
1081: frame geometry different from what you asked for.  To get the intended
1082: size with no tool bar, use an X resource to specify ``no tool bar''
1083: (@pxref{Table of Resources}); then Emacs will already know there's no
1084: tool bar when it processes the specified geometry.
1085: 
1086:   When using one of @samp{--fullscreen}, @samp{--maximized},
1087: @samp{--fullwidth} or @samp{--fullheight}, some window managers require
1088: you to set the variable @code{frame-resize-pixelwise} to a non-@code{nil}
1089: value to make a frame appear truly maximized or full-screen.
1090: 
1091:  Some window managers have options that can make them ignore both
1092: program-specified and user-specified positions.  If these are set,
1093: Emacs fails to position the window correctly.
1094: 
1095: @node Borders X
1096: @appendixsec Internal and Outer Borders
1097: @cindex borders (X Window System)
1098: 
1099:   An Emacs frame has an internal border and an outer border.  The
1100: internal border is an extra strip of the background color around the
1101: text portion of the frame.  Emacs itself draws the internal border.  The
1102: outer border is drawn by X outside the tool and menu bars of the frame.
1103: There is also an external border which is drawn by the window manager.
1104: The size of the external border cannot be set from within Emacs.
1105: 
1106: @table @samp
1107: @item -ib @var{width}
1108: @opindex -ib
1109: @itemx --internal-border=@var{width}
1110: @opindex --internal-border
1111: @cindex internal border width, command-line argument
1112: Specify @var{width} as the width of the internal border (around the
1113: frame's text area), in pixels.
1114: 
1115: @item -bw @var{width}
1116: @opindex -bw
1117: @itemx --border-width=@var{width}
1118: @opindex --border-width
1119: @cindex main border width, command-line argument
1120: @cindex outer border width, command-line argument
1121: Specify @var{width} as the width of the outer border, in pixels.
1122: @end table
1123: 
1124:   When you specify the size of the frame, that does not count the
1125: borders.  The frame's position is measured from the outside edge of the
1126: external border.
1127: 
1128:   Use the @samp{-ib @var{n}} option to specify an internal border
1129: @var{n} pixels wide.  The default is 1.  Use @samp{-bw @var{n}} to
1130: specify the width of the outer border (though the window manager may not
1131: pay attention to what you specify).  The default width of the outer
1132: border is 2.
1133: 
1134: @node Title X
1135: @appendixsec Frame Titles
1136: 
1137:   Each Emacs frame always has a title, which appears in window
1138: decorations and icons as the name of the frame.  The default title is
1139: of the form @samp{@var{invocation-name}@@@var{machine}} (if there is
1140: only one frame) or shows the selected window's buffer name (if there
1141: is more than one frame).
1142: 
1143:   You can specify a non-default title for the initial Emacs frame with
1144: a command line option:
1145: 
1146: @table @samp
1147: @item -T @var{title}
1148: @opindex -T
1149: @itemx --title=@var{title}
1150: @opindex --title
1151: @cindex frame title, command-line argument
1152: Specify @var{title} as the title for the initial Emacs frame.
1153: @end table
1154: 
1155:   The @samp{--name} option (@pxref{Resources}) also specifies the title
1156: for the initial Emacs frame.
1157: 
1158: @node Icons X
1159: @appendixsec Icons
1160: @cindex icons (X Window System)
1161: @cindex minimizing a frame at startup
1162: 
1163: @table @samp
1164: @item -iconic
1165: @opindex --iconic
1166: @itemx --iconic
1167: @cindex start iconified, command-line argument
1168: Start Emacs in an iconified state.
1169: 
1170: @item -nbi
1171: @opindex -nbi
1172: @itemx --no-bitmap-icon
1173: @opindex --no-bitmap-icon
1174: @cindex Emacs icon, a gnu
1175: Disable the use of the Emacs icon.
1176: @end table
1177: 
1178:   Most window managers allow you to iconify (or ``minimize'') an
1179: Emacs frame, hiding it from sight.  Some window managers replace
1180: iconified windows with tiny icons, while others remove them
1181: entirely from sight.  The @samp{-iconic} option tells Emacs to begin
1182: running in an iconified state, rather than showing a frame right away.
1183: The text frame doesn't appear until you deiconify (or ``un-minimize'')
1184: it.
1185: 
1186:   By default, Emacs uses an icon containing the Emacs logo.  On
1187: desktop environments such as Gnome, this icon is also displayed in
1188: other contexts, e.g., when switching into an Emacs frame.  The
1189: @samp{-nbi} or @samp{--no-bitmap-icon} option tells Emacs to let the
1190: window manager choose what sort of icon to use---usually just a small
1191: rectangle containing the frame's title.
1192: 
1193: @node Misc X
1194: @appendixsec Other Display Options
1195: 
1196: @table @samp
1197: @c @item -hb
1198: @c @opindex -hb
1199: @c @itemx --horizontal-scroll-bars
1200: @c @opindex --horizontal-scroll-bars
1201: @c @c @cindex horizontal scroll bars, command-line argument
1202: @c Enable horizontal scroll bars.  Since horizontal scroll bars
1203: @c are not yet implemented, this actually does nothing.
1204: 
1205: @item --parent-id @var{id}
1206: Open Emacs as a client X window via the XEmbed protocol, with @var{id}
1207: as the parent X window id.  Currently, this option is mainly useful
1208: for developers.
1209: 
1210: @item -vb
1211: @opindex -vb
1212: @itemx --vertical-scroll-bars
1213: @opindex --vertical-scroll-bars
1214: @cindex vertical scroll bars, command-line argument
1215: Enable vertical scroll bars.
1216: 
1217: @item -lsp @var{pixels}
1218: @opindex -lsp
1219: @itemx --line-spacing=@var{pixels}
1220: @opindex --line-spacing
1221: @cindex line spacing, command-line argument
1222: Specify @var{pixels} as additional space to put between lines, in pixels.
1223: 
1224: @item -nbc
1225: @opindex -nbc
1226: @itemx --no-blinking-cursor
1227: @opindex --no-blinking-cursor
1228: @cindex blinking cursor disable, command-line argument
1229: Disable the blinking cursor on graphical displays.
1230: 
1231: @item -D
1232: @opindex -D
1233: @itemx --basic-display
1234: @opindex --basic-display
1235: Disable the menu-bar, the tool-bar, the scroll-bars, and tool tips,
1236: and turn off the blinking cursor.  This can be useful for making a
1237: test case that simplifies debugging of display problems.
1238: @end table
1239: 
1240:   The @samp{--xrm} option (@pxref{Resources}) specifies additional
1241: X resource values.
1242: