0001: @c This is part of the Emacs manual.
0002: @c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2018 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: @end table
0387: 
0388: @node Command Example
0389: @appendixsec Command Argument Example
0390: 
0391:   Here is an example of using Emacs with arguments and options.  It
0392: assumes you have a Lisp program file called @file{hack-c.el} which, when
0393: loaded, performs some useful operation on the current buffer, expected
0394: to be a C program.
0395: 
0396: @example
0397: emacs --batch foo.c -l hack-c -f save-buffer >& log
0398: @end example
0399: 
0400: @noindent
0401: This says to visit @file{foo.c}, load @file{hack-c.el} (which makes
0402: changes in the visited file), save @file{foo.c} (note that
0403: @code{save-buffer} is the function that @kbd{C-x C-s} is bound to), and
0404: then exit back to the shell (because of @samp{--batch}).  @samp{--batch}
0405: also guarantees there will be no problem redirecting output to
0406: @file{log}, because Emacs will not assume that it has a display terminal
0407: to work with.
0408: 
0409: @node Environment
0410: @appendixsec Environment Variables
0411: @cindex environment variables
0412: 
0413:   The @dfn{environment} is a feature of the operating system; it
0414: consists of a collection of variables with names and values.  Each
0415: variable is called an @dfn{environment variable}; environment variable
0416: names are case-sensitive, and it is conventional to use upper case
0417: letters only.  The values are all text strings.
0418: 
0419:   What makes the environment useful is that subprocesses inherit the
0420: environment automatically from their parent process.  This means you
0421: can set up an environment variable in your login shell, and all the
0422: programs you run (including Emacs) will automatically see it.
0423: Subprocesses of Emacs (such as shells, compilers, and version control
0424: programs) inherit the environment from Emacs, too.
0425: 
0426: @findex setenv
0427: @findex getenv
0428: @vindex initial-environment
0429:   Inside Emacs, the command @kbd{M-x getenv} reads the name of an
0430: environment variable, and prints its value in the echo area.  @kbd{M-x
0431: setenv} sets a variable in the Emacs environment, and @kbd{C-u M-x
0432: setenv} removes a variable.  (Environment variable substitutions with
0433: @samp{$} work in the value just as in file names; see @ref{File Names
0434: with $}.)  The variable @code{initial-environment} stores the initial
0435: environment inherited by Emacs.
0436: 
0437:   The way to set environment variables outside of Emacs depends on the
0438: operating system, and especially the shell that you are using.  For
0439: example, here's how to set the environment variable @env{ORGANIZATION}
0440: to @samp{not very much} using Bash:
0441: 
0442: @example
0443: export ORGANIZATION="not very much"
0444: @end example
0445: 
0446: @noindent
0447: and here's how to do it in csh or tcsh:
0448: 
0449: @example
0450: setenv ORGANIZATION "not very much"
0451: @end example
0452: 
0453:   When Emacs is using the X Window System, various environment
0454: variables that control X work for Emacs as well.  See the X
0455: documentation for more information.
0456: 
0457: @menu
0458: * General Variables::   Environment variables that all versions of Emacs use.
0459: * Misc Variables::      Certain system-specific variables.
0460: * MS-Windows Registry:: An alternative to the environment on MS-Windows.
0461: @end menu
0462: 
0463: @node General Variables
0464: @appendixsubsec General Variables
0465: 
0466:   Here is an alphabetical list of environment variables that have
0467: special meanings in Emacs.  Most of these variables are also used by
0468: some other programs.  Emacs does not require any of these environment
0469: variables to be set, but it uses their values if they are set.
0470: 
0471: @c This used to be @vtable, but that enters the variables alone into
0472: @c the Variable Index, which in some cases, like HOME, might be
0473: @c confused with keys by that name, and other cases, like NAME,
0474: @c might be confused with general-purpose phrases.
0475: @table @env
0476: @item CDPATH
0477: @vindex CDPATH@r{, environment variable}
0478: Used by the @code{cd} command to search for the directory you specify,
0479: when you specify a relative directory,
0480: @item DBUS_SESSION_BUS_ADDRESS
0481: @vindex DBUS_SESSION_BUS_ADDRESS@r{, environment variable}
0482: Used by D-Bus when Emacs is compiled with it.  Usually, there is no
0483: need to change it.  Setting it to a dummy address, like
0484: @samp{unix:path=/dev/null}, suppresses connections to the D-Bus session
0485: bus as well as autolaunching the D-Bus session bus if not running yet.
0486: @item EMACSDATA
0487: @vindex EMACSDATA@r{, environment variable}
0488: Directory for the architecture-independent files that come with Emacs.
0489: This is used to initialize the variable @code{data-directory}.
0490: @item EMACSDOC
0491: @vindex EMACSDOC@r{, environment variable}
0492: Directory for the documentation string file, which is used to
0493: initialize the Lisp variable @code{doc-directory}.
0494: @item EMACSLOADPATH
0495: @vindex EMACSLOADPATH@r{, environment variable}
0496: A colon-separated list of directories@footnote{Here and below,
0497: whenever we say ``colon-separated list of directories'', it pertains
0498: to Unix and GNU/Linux systems.  On MS-DOS and MS-Windows, the
0499: directories are separated by semi-colons instead, since DOS/Windows
0500: file names might include a colon after a drive letter.} to search for
0501: Emacs Lisp files.  If set, it modifies the usual initial value of the
0502: @code{load-path} variable (@pxref{Lisp Libraries}).  An empty element
0503: stands for the default value of @code{load-path}; e.g., using
0504: @samp{EMACSLOADPATH="/tmp:"} adds @file{/tmp} to the front of
0505: the default @code{load-path}.  To specify an empty element in the
0506: middle of the list, use 2 colons in a row, as in
0507: @samp{EMACSLOADPATH="/tmp::/foo"}.
0508: @item EMACSPATH
0509: @vindex EMACSPATH@r{, environment variable}
0510: A colon-separated list of directories to search for executable files.
0511: If set, Emacs uses this in addition to @env{PATH} (see below) when
0512: initializing the variable @code{exec-path} (@pxref{Shell}).
0513: @item EMAIL
0514: @vindex EMAIL@r{, environment variable}
0515: @vindex user-mail-address@r{, initialization}
0516: Your email address; used to initialize the Lisp variable
0517: @code{user-mail-address}, which the Emacs mail interface puts into the
0518: @samp{From} header of outgoing messages (@pxref{Mail Headers}).
0519: @item ESHELL
0520: @vindex ESHELL@r{, environment variable}
0521: Used for shell-mode to override the @env{SHELL} environment variable
0522: (@pxref{Interactive Shell}).
0523: @item HISTFILE
0524: @vindex HISTFILE@r{, environment variable}
0525: The name of the file that shell commands are saved in between logins.
0526: This variable defaults to @file{~/.bash_history} if you use Bash, to
0527: @file{~/.sh_history} if you use ksh, and to @file{~/.history}
0528: otherwise.
0529: @item HOME
0530: @vindex HOME@r{, environment variable}
0531: The location of your files in the directory tree; used for
0532: expansion of file names starting with a tilde (@file{~}).  On MS-DOS,
0533: it defaults to the directory from which Emacs was started, with
0534: @samp{/bin} removed from the end if it was present.  On Windows, the
0535: default value of @env{HOME} is the @file{Application Data}
0536: subdirectory of the user profile directory (normally, this is
0537: @file{C:/Documents and Settings/@var{username}/Application Data},
0538: where @var{username} is your user name), though for backwards
0539: compatibility @file{C:/} will be used instead if a @file{.emacs} file
0540: is found there.
0541: @item HOSTNAME
0542: @vindex HOSTNAME@r{, environment variable}
0543: The name of the machine that Emacs is running on.
0544: @c complete.el is obsolete since 24.1.
0545: @ignore
0546: @item INCPATH
0547: A colon-separated list of directories.  Used by the @code{complete} package
0548: to search for files.
0549: @end ignore
0550: @item INFOPATH
0551: @vindex INFOPATH@r{, environment variable}
0552: A colon-separated list of directories in which to search for Info files.
0553: @item LC_ALL
0554: @vindex LC_ALL@r{, environment variable}
0555: @itemx LC_COLLATE
0556: @vindex LC_COLLATE@r{, environment variable}
0557: @itemx LC_CTYPE
0558: @vindex LC_CTYPE@r{, environment variable}
0559: @itemx LC_MESSAGES
0560: @vindex LC_MESSAGES@r{, environment variable}
0561: @itemx LC_MONETARY
0562: @vindex LC_MONETARY@r{, environment variable}
0563: @itemx LC_NUMERIC
0564: @vindex LC_NUMERIC@r{, environment variable}
0565: @itemx LC_TIME
0566: @vindex LC_TIME@r{, environment variable}
0567: @itemx LANG
0568: @vindex LANG@r{, environment variable}
0569: The user's preferred locale.  The locale has six categories, specified
0570: by the environment variables @env{LC_COLLATE} for sorting,
0571: @env{LC_CTYPE} for character encoding, @env{LC_MESSAGES} for system
0572: messages, @env{LC_MONETARY} for monetary formats, @env{LC_NUMERIC} for
0573: numbers, and @env{LC_TIME} for dates and times.  If one of these
0574: variables is not set, the category defaults to the value of the
0575: @env{LANG} environment variable, or to the default @samp{C} locale if
0576: @env{LANG} is not set.  But if @env{LC_ALL} is specified, it overrides
0577: the settings of all the other locale environment variables.
0578: 
0579: On MS-Windows and macOS, if @env{LANG} is not already set in the
0580: environment, Emacs sets it based on the system-wide default.  You can
0581: set this in the ``Regional Settings'' Control Panel on some versions
0582: of MS-Windows, and in the ``Language and Region'' System Preference on
0583: macOS.
0584: 
0585: The value of the @env{LC_CTYPE} category is
0586: matched against entries in @code{locale-language-names},
0587: @code{locale-charset-language-names}, and
0588: @code{locale-preferred-coding-systems}, to select a default language
0589: environment and coding system.  @xref{Language Environments}.
0590: @item LOGNAME
0591: @vindex LOGNAME@r{, environment variable}
0592: The user's login name.  See also @env{USER}.
0593: @item MAIL
0594: @vindex MAIL@r{, environment variable}
0595: The name of your system mail inbox.
0596: @ifnottex
0597: @item MH
0598: @vindex MH@r{, environment variable}
0599: Name of setup file for the mh system.  @xref{Top,,MH-E,mh-e, The Emacs
0600: Interface to MH}.
0601: @end ifnottex
0602: @item NAME
0603: @vindex NAME@r{, environment variable}
0604: Your real-world name.  This is used to initialize the variable
0605: @code{user-full-name} (@pxref{Mail Headers}).
0606: @item NNTPSERVER
0607: @vindex NNTPSERVER@r{, environment variable}
0608: The name of the news server.  Used by the mh and Gnus packages.
0609: @item ORGANIZATION
0610: @vindex ORGANIZATION@r{, environment variable}
0611: The name of the organization to which you belong.  Used for setting the
0612: @samp{Organization:} header in your posts from the Gnus package.
0613: @item PATH
0614: @vindex PATH@r{, environment variable}
0615: A colon-separated list of directories containing executable files.
0616: This is used to initialize the variable @code{exec-path}
0617: (@pxref{Shell}).
0618: @item PWD
0619: @vindex PWD@r{, environment variable}
0620: If set, this should be the default directory when Emacs was started.
0621: @item REPLYTO
0622: @vindex REPLYTO@r{, environment variable}
0623: If set, this specifies an initial value for the variable
0624: @code{mail-default-reply-to} (@pxref{Mail Headers}).
0625: @item SAVEDIR
0626: @vindex SAVEDIR@r{, environment variable}
0627: The name of a directory in which news articles are saved by default.
0628: Used by the Gnus package.
0629: @item SHELL
0630: @vindex SHELL@r{, environment variable}
0631: The name of an interpreter used to parse and execute programs run from
0632: inside Emacs.
0633: @item SMTPSERVER
0634: @vindex SMTPSERVER@r{, environment variable}
0635: The name of the outgoing mail server.  This is used to initialize the
0636: variable @code{smtpmail-smtp-server} (@pxref{Mail Sending}).
0637: @cindex background mode, on @command{xterm}
0638: @item TERM
0639: @vindex TERM@r{, environment variable}
0640: The type of the terminal that Emacs is using.  This variable must be
0641: set unless Emacs is run in batch mode.  On MS-DOS, it defaults to
0642: @samp{internal}, which specifies a built-in terminal emulation that
0643: handles the machine's own display.
0644: @item TERMCAP
0645: @vindex TERMCAP@r{, environment variable}
0646: The name of the termcap library file describing how to program the
0647: terminal specified by @env{TERM}.  This defaults to
0648: @file{/etc/termcap}.
0649: @item TMPDIR
0650: @vindex TMPDIR@r{, environment variable}
0651: @itemx TMP
0652: @vindex TMP@r{, environment variable}
0653: @itemx TEMP
0654: @vindex TEMP@r{, environment variable}
0655: These environment variables are used to initialize the variable
0656: @code{temporary-file-directory}, which specifies a directory in which
0657: to put temporary files (@pxref{Backup}).  Emacs tries to use
0658: @env{TMPDIR} first.  If that is unset, Emacs normally falls back on
0659: @file{/tmp}, but on MS-Windows and MS-DOS it instead falls back on
0660: @env{TMP}, then @env{TEMP}, and finally @file{c:/temp}.
0661: @item TZ
0662: @vindex TZ@r{, environment variable}
0663: This specifies the default time zone and possibly also daylight
0664: saving time information.  @xref{Time Zone Rules,,, elisp, The GNU
0665: Emacs Lisp Reference Manual}.  On MS-DOS, if @env{TZ} is not set in the
0666: environment when Emacs starts, Emacs defines a default value as
0667: appropriate for the country code returned by DOS@.  On MS-Windows, Emacs
0668: does not use @env{TZ} at all.
0669: @item USER
0670: @vindex USER@r{, environment variable}
0671: The user's login name.  See also @env{LOGNAME}.  On MS-DOS, this
0672: defaults to @samp{root}.
0673: @item VERSION_CONTROL
0674: @vindex VERSION_CONTROL@r{, environment variable}
0675: Used to initialize the @code{version-control} variable (@pxref{Backup
0676: Names}).
0677: @end table
0678: 
0679: @node Misc Variables
0680: @appendixsubsec Miscellaneous Variables
0681: 
0682: These variables are used only on particular configurations:
0683: 
0684: @vtable @env
0685: @item COMSPEC
0686: On MS-DOS and MS-Windows, the name of the command interpreter to use
0687: when invoking batch files and commands internal to the shell.  On MS-DOS
0688: this is also used to make a default value for the @env{SHELL} environment
0689: variable.
0690: 
0691: @item NAME
0692: On MS-DOS, this variable defaults to the value of the @env{USER}
0693: variable.
0694: 
0695: @item EMACSTEST
0696: On MS-DOS, this specifies a file to use to log the operation of the
0697: internal terminal emulator.  This feature is useful for submitting bug
0698: reports.
0699: 
0700: @item EMACSCOLORS
0701: On MS-DOS, this specifies the screen colors.  It is useful to set them
0702: this way, since otherwise Emacs would display the default colors
0703: momentarily when it starts up.
0704: 
0705: The value of this variable should be the two-character encoding of the
0706: foreground (the first character) and the background (the second
0707: character) colors of the default face.  Each character should be the
0708: hexadecimal code for the desired color on a standard PC text-mode
0709: display.  For example, to get blue text on a light gray background,
0710: specify @samp{EMACSCOLORS=17}, since 1 is the code of the blue color and
0711: 7 is the code of the light gray color.
0712: 
0713: The PC display usually supports only eight background colors.  However,
0714: Emacs switches the DOS display to a mode where all 16 colors can be used
0715: for the background, so all four bits of the background color are
0716: actually used.
0717: 
0718: @item PRELOAD_WINSOCK
0719: On MS-Windows, if you set this variable, Emacs will load and initialize
0720: the network library at startup, instead of waiting until the first
0721: time it is required.
0722: 
0723: @item emacs_dir
0724: On MS-Windows, @env{emacs_dir} is a special environment variable, which
0725: indicates the full path of the directory in which Emacs is installed.
0726: If Emacs is installed in the standard directory structure, it
0727: calculates this value automatically.  It is not much use setting this
0728: variable yourself unless your installation is non-standard, since
0729: unlike other environment variables, it will be overridden by Emacs at
0730: startup.  When setting other environment variables, such as
0731: @env{EMACSLOADPATH}, you may find it useful to use @env{emacs_dir}
0732: rather than hard-coding an absolute path.  This allows multiple
0733: versions of Emacs to share the same environment variable settings, and
0734: it allows you to move the Emacs installation directory, without
0735: changing any environment or registry settings.
0736: @end vtable
0737: 
0738: @node MS-Windows Registry
0739: @appendixsubsec The MS-Windows System Registry
0740: @pindex addpm, MS-Windows installation program
0741: @cindex registry, setting environment variables (MS-Windows)
0742: 
0743: On MS-Windows, the installation program @command{addpm.exe} adds
0744: values for @env{emacs_dir}, @env{EMACSLOADPATH}, @env{EMACSDATA},
0745: @env{EMACSPATH}, @env{EMACSDOC}, @env{SHELL} and @env{TERM} to the
0746: @file{HKEY_LOCAL_MACHINE} section of the system registry, under
0747: @file{/Software/GNU/Emacs}.  It does this because there is no standard
0748: place to set environment variables across different versions of
0749: Windows.  Running @command{addpm.exe} is no longer strictly necessary
0750: in recent versions of Emacs, but if you are upgrading from an older
0751: version, running @command{addpm.exe} ensures that you do not have
0752: older registry entries from a previous installation, which may not be
0753: compatible with the latest version of Emacs.
0754: 
0755: When Emacs starts, as well as checking the environment, it also checks
0756: the System Registry for those variables and for @env{HOME}, @env{LANG}
0757: and @env{PRELOAD_WINSOCK}.
0758: 
0759: To determine the value of those variables, Emacs goes through the
0760: following procedure.  First, the environment is checked.  If the
0761: variable is not found there, Emacs looks for registry keys by that
0762: name under @file{/Software/GNU/Emacs}; first in the
0763: @file{HKEY_CURRENT_USER} section of the registry, and if not found
0764: there, in the @file{HKEY_LOCAL_MACHINE} section.  Finally, if Emacs
0765: still cannot determine the values, compiled-in defaults are used.
0766: 
0767: In addition to the environment variables above, you can also add
0768: settings to the @file{/Software/GNU/Emacs} registry key to specify X
0769: resources (@pxref{X Resources}).  Most of the settings you can specify
0770: in your @file{.Xdefaults} file can be set from that registry key.
0771: 
0772: @node Display X
0773: @appendixsec Specifying the Display Name
0774: @cindex display name (X Window System)
0775: @cindex @env{DISPLAY} environment variable
0776: 
0777:   The environment variable @env{DISPLAY} tells all X clients,
0778: including Emacs, where to display their windows.  Its value is set by
0779: default in ordinary circumstances, when you start an X server and run
0780: jobs locally.  You can specify the display yourself; one reason to do
0781: this is if you want to log into another system and run Emacs there,
0782: and have the window displayed at your local terminal.
0783: 
0784:   @env{DISPLAY} has the syntax
0785: @samp{@var{host}:@var{display}.@var{screen}}, where @var{host} is the
0786: host name of the X Window System server machine, @var{display} is an
0787: arbitrarily-assigned number that distinguishes your server (X
0788: terminal) from other servers on the same machine, and @var{screen} is
0789: a field that allows an X server to control multiple terminal screens.
0790: The period and the @var{screen} field are optional.  If included,
0791: @var{screen} is usually zero.
0792: 
0793:   For example, if your host is named @samp{glasperle} and your server is
0794: the first (or perhaps the only) server listed in the configuration, your
0795: @env{DISPLAY} is @samp{glasperle:0.0}.
0796: 
0797:   You can specify the display name explicitly when you run Emacs, either
0798: by changing the @env{DISPLAY} variable, or with the option @samp{-d
0799: @var{display}} or @samp{--display=@var{display}}.  Here is an example:
0800: 
0801: @smallexample
0802: emacs --display=glasperle:0 &
0803: @end smallexample
0804: 
0805:   You can inhibit the use of the X window system with the @samp{-nw}
0806: option.  Then Emacs uses its controlling text terminal for display.
0807: @xref{Initial Options}.
0808: 
0809:   Sometimes, security arrangements prevent a program on a remote system
0810: from displaying on your local system.  In this case, trying to run Emacs
0811: produces messages like this:
0812: 
0813: @smallexample
0814: Xlib:  connection to "glasperle:0.0" refused by server
0815: @end smallexample
0816: 
0817: @noindent
0818: You might be able to overcome this problem by using the @command{xhost}
0819: command on the local system to give permission for access from your
0820: remote machine.
0821: 
0822: @node Font X
0823: @appendixsec Font Specification Options
0824: @cindex font name (X Window System)
0825: 
0826: You can use the command line option @samp{-fn @var{font}} (or
0827: @samp{--font}, which is an alias for @samp{-fn}) to specify a default
0828: font:
0829: 
0830: @table @samp
0831: @item -fn @var{font}
0832: @opindex -fn
0833: @itemx --font=@var{font}
0834: @opindex --font
0835: @cindex specify default font from the command line
0836: Use @var{font} as the default font.
0837: @end table
0838: 
0839: When passing a font name to Emacs on the command line, you may need to
0840: quote it, by enclosing it in quotation marks, if it contains
0841: characters that the shell treats specially (e.g., spaces).  For
0842: example:
0843: 
0844: @smallexample
0845: emacs -fn "DejaVu Sans Mono-12"
0846: @end smallexample
0847: 
0848: @xref{Fonts}, for details about font names and other ways to specify
0849: the default font.
0850: 
0851: @node Colors X
0852: @appendixsec Window Color Options
0853: @cindex color of window, from command line
0854: @cindex text colors, from command line
0855: 
0856:   You can use the following command-line options to specify the colors
0857: to use for various parts of the Emacs display.  Colors may be
0858: specified using either color names or RGB triplets (@pxref{Colors}).
0859: 
0860: @table @samp
0861: @item -fg @var{color}
0862: @opindex -fg
0863: @itemx --foreground-color=@var{color}
0864: @opindex --foreground-color
0865: @cindex foreground color, command-line argument
0866: Specify the foreground color, overriding the color specified by the
0867: @code{default} face (@pxref{Faces}).
0868: @item -bg @var{color}
0869: @opindex -bg
0870: @itemx --background-color=@var{color}
0871: @opindex --background-color
0872: @cindex background color, command-line argument
0873: Specify the background color, overriding the color specified by the
0874: @code{default} face.
0875: @item -bd @var{color}
0876: @opindex -bd
0877: @itemx --border-color=@var{color}
0878: @opindex --border-color
0879: @cindex border color, command-line argument
0880: Specify the color of the border of the X window.  This has no effect
0881: if Emacs is compiled with GTK+ support.
0882: @item -cr @var{color}
0883: @opindex -cr
0884: @itemx --cursor-color=@var{color}
0885: @opindex --cursor-color
0886: @cindex cursor color, command-line argument
0887: Specify the color of the Emacs cursor which indicates where point is.
0888: @item -ms @var{color}
0889: @opindex -ms
0890: @itemx --mouse-color=@var{color}
0891: @opindex --mouse-color
0892: @cindex mouse pointer color, command-line argument
0893: Specify the color for the mouse cursor when the mouse is in the Emacs window.
0894: @item -r
0895: @opindex -r
0896: @itemx -rv
0897: @opindex -rv
0898: @itemx --reverse-video
0899: @opindex --reverse-video
0900: @cindex reverse video, command-line argument
0901: Reverse video: swap the foreground and background colors.
0902: @item --color=@var{mode}
0903: @opindex --color
0904: @cindex standard colors on a character terminal
0905: @cindex override character terminal color support
0906: Set the @dfn{color support mode} when Emacs is run on a text terminal.
0907: This option overrides the number of supported colors that the
0908: character terminal advertises in its @code{termcap} or @code{terminfo}
0909: database.  The parameter @var{mode} can be one of the following:
0910: @table @samp
0911: @item never
0912: @itemx no
0913: Don't use colors even if the terminal's capabilities specify color
0914: support.
0915: @item default
0916: @itemx auto
0917: Same as when @option{--color} is not used at all: Emacs detects at
0918: startup whether the terminal supports colors, and if it does, turns on
0919: colored display.
0920: @item always
0921: @itemx yes
0922: @itemx ansi8
0923: Turn on the color support unconditionally, and use color commands
0924: specified by the ANSI escape sequences for the 8 standard colors.
0925: @item @var{num}
0926: Use color mode for @var{num} colors.  If @var{num} is @minus{}1, turn off
0927: color support (equivalent to @samp{never}); if it is 0, use the
0928: default color support for this terminal (equivalent to @samp{auto});
0929: otherwise use an appropriate standard mode for @var{num} colors.
0930: Depending on your terminal's capabilities, Emacs might be able to turn
0931: on a color mode for 8, 16, 88, or 256 as the value of @var{num}.  If
0932: there is no mode that supports @var{num} colors, Emacs acts as if
0933: @var{num} were 0, i.e., it uses the terminal's default color support
0934: mode.
0935: @end table
0936: If @var{mode} is omitted, it defaults to @var{ansi8}.
0937: @end table
0938: 
0939:   For example, to use a coral mouse cursor and a slate blue text cursor,
0940: enter:
0941: 
0942: @example
0943: emacs -ms coral -cr 'slate blue' &
0944: @end example
0945: 
0946:   You can reverse the foreground and background colors through the
0947: @samp{-rv} option or with the X resource @samp{reverseVideo}.
0948: 
0949:   The @samp{-fg}, @samp{-bg}, and @samp{-rv} options function on text
0950: terminals as well as on graphical displays.
0951: 
0952: @node Window Size X
0953: @appendixsec Options for Window Size and Position
0954: @cindex geometry of Emacs window
0955: @cindex position and size of Emacs frame
0956: @cindex width and height of Emacs frame
0957: @cindex specifying fullscreen for Emacs frame
0958: 
0959:   Here is a list of the command-line options for specifying size and
0960: position of the initial Emacs frame:
0961: 
0962: @table @samp
0963: @item -g @var{width}x@var{height}@r{[@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}@r{]]}
0964: @opindex -g
0965: @itemx --geometry=@var{width}x@var{height}@r{[@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}@r{]]}
0966: @opindex --geometry
0967: @cindex geometry, command-line argument
0968: Specify the size @var{width} and @var{height} (measured in character
0969: columns and lines), and positions @var{xoffset} and @var{yoffset}
0970: (measured in pixels).  The @var{width} and @var{height} parameters
0971: apply to all frames, whereas @var{xoffset} and @var{yoffset} only to
0972: the initial frame.
0973: 
0974: @item -fs
0975: @opindex -fs
0976: @itemx --fullscreen
0977: @opindex --fullscreen
0978: @cindex fullscreen, command-line argument
0979: Specify that width and height should be that of the screen.  Normally
0980: no window manager decorations are shown.  (After starting Emacs,
0981: you can toggle this state using @key{F11}, @code{toggle-frame-fullscreen}.)
0982: 
0983: @item -mm
0984: @opindex -mm
0985: @itemx --maximized
0986: @opindex --maximized
0987: @cindex maximized, command-line argument
0988: Specify that the Emacs frame should be maximized.  This normally
0989: means that the frame has window manager decorations.
0990: (After starting Emacs, you can toggle this state using @kbd{M-F10},
0991: @code{toggle-frame-maximized}.)
0992: 
0993: @item -fh
0994: @opindex -fh
0995: @itemx --fullheight
0996: @opindex --fullheight
0997: @cindex fullheight, command-line argument
0998: Specify that the height should be the height of the screen.
0999: 
1000: @item -fw
1001: @opindex -fw
1002: @itemx --fullwidth
1003: @opindex --fullwidth
1004: @cindex fullwidth, command-line argument
1005: Specify that the width should be the width of the screen.
1006: @end table
1007: 
1008: @noindent
1009: In the @samp{--geometry} option, @code{@r{@{}+-@r{@}}} means either a plus
1010:  sign or a minus sign.  A plus
1011: sign before @var{xoffset} means it is the distance from the left side of
1012: the screen; a minus sign means it counts from the right side.  A plus
1013: sign before @var{yoffset} means it is the distance from the top of the
1014: screen, and a minus sign there indicates the distance from the bottom.
1015: The values @var{xoffset} and @var{yoffset} may themselves be positive or
1016: negative, but that doesn't change their meaning, only their direction.
1017: 
1018:   Emacs uses the same units as @command{xterm} does to interpret the geometry.
1019: The @var{width} and @var{height} are measured in characters, so a large font
1020: creates a larger frame than a small font.  (If you specify a proportional
1021: font, Emacs uses its maximum bounds width as the width unit.)  The
1022: @var{xoffset} and @var{yoffset} are measured in pixels.
1023: 
1024:   You do not have to specify all of the fields in the geometry
1025: specification.  If you omit both @var{xoffset} and @var{yoffset}, the
1026: window manager decides where to put the Emacs frame, possibly by
1027: letting you place it with the mouse.  For example, @samp{164x55}
1028: specifies a window 164 columns wide, enough for two ordinary width
1029: windows side by side, and 55 lines tall.
1030: 
1031:   The default frame width is 80 characters and the default height is
1032: 40 lines.  You can omit either the width or the height or both.  If
1033: you start the geometry with an integer, Emacs interprets it as the
1034: width.  If you start with an @samp{x} followed by an integer, Emacs
1035: interprets it as the height.  Thus, @samp{81} specifies just the
1036: width; @samp{x45} specifies just the height.
1037: 
1038:   If you start the geometry with @samp{+} or @samp{-}, that introduces
1039: an offset, which means both sizes are omitted.  Thus, @samp{-3}
1040: specifies the @var{xoffset} only.  (If you give just one offset, it is
1041: always @var{xoffset}.)  @samp{+3-3} specifies both the @var{xoffset}
1042: and the @var{yoffset}, placing the frame near the bottom left of the
1043: screen.
1044: 
1045:   You can specify a default for any or all of the fields in your X
1046: resource file (@pxref{Resources}), and then override selected fields
1047: with a @samp{--geometry} option.
1048: 
1049:   Since the mode line and the echo area occupy the last 2 lines of the
1050: frame, the height of the initial text window is 2 less than the height
1051: specified in your geometry.  In non-X-toolkit versions of Emacs, the
1052: menu bar also takes one line of the specified number.  But in the X
1053: toolkit version, the menu bar is additional and does not count against
1054: the specified height.  The tool bar, if present, is also additional.
1055: 
1056:   Enabling or disabling the menu bar or tool bar alters the amount of
1057: space available for ordinary text.  Therefore, if Emacs starts up with
1058: a tool bar (which is the default), and handles the geometry
1059: specification assuming there is a tool bar, and then your
1060: initialization file disables the tool bar, you will end up with a
1061: frame geometry different from what you asked for.  To get the intended
1062: size with no tool bar, use an X resource to specify ``no tool bar''
1063: (@pxref{Table of Resources}); then Emacs will already know there's no
1064: tool bar when it processes the specified geometry.
1065: 
1066:   When using one of @samp{--fullscreen}, @samp{--maximized},
1067: @samp{--fullwidth} or @samp{--fullheight}, some window managers require
1068: you to set the variable @code{frame-resize-pixelwise} to a non-@code{nil}
1069: value to make a frame appear truly maximized or full-screen.
1070: 
1071:  Some window managers have options that can make them ignore both
1072: program-specified and user-specified positions.  If these are set,
1073: Emacs fails to position the window correctly.
1074: 
1075: @node Borders X
1076: @appendixsec Internal and Outer Borders
1077: @cindex borders (X Window System)
1078: 
1079:   An Emacs frame has an internal border and an outer border.  The
1080: internal border is an extra strip of the background color around the
1081: text portion of the frame.  Emacs itself draws the internal border.  The
1082: outer border is drawn by X outside the tool and menu bars of the frame.
1083: There is also an external border which is drawn by the window manager.
1084: The size of the external border cannot be set from within Emacs.
1085: 
1086: @table @samp
1087: @item -ib @var{width}
1088: @opindex -ib
1089: @itemx --internal-border=@var{width}
1090: @opindex --internal-border
1091: @cindex internal border width, command-line argument
1092: Specify @var{width} as the width of the internal border (around the
1093: frame's text area), in pixels.
1094: 
1095: @item -bw @var{width}
1096: @opindex -bw
1097: @itemx --border-width=@var{width}
1098: @opindex --border-width
1099: @cindex main border width, command-line argument
1100: @cindex outer border width, command-line argument
1101: Specify @var{width} as the width of the outer border, in pixels.
1102: @end table
1103: 
1104:   When you specify the size of the frame, that does not count the
1105: borders.  The frame's position is measured from the outside edge of the
1106: external border.
1107: 
1108:   Use the @samp{-ib @var{n}} option to specify an internal border
1109: @var{n} pixels wide.  The default is 1.  Use @samp{-bw @var{n}} to
1110: specify the width of the outer border (though the window manager may not
1111: pay attention to what you specify).  The default width of the outer
1112: border is 2.
1113: 
1114: @node Title X
1115: @appendixsec Frame Titles
1116: 
1117:   Each Emacs frame always has a title, which appears in window
1118: decorations and icons as the name of the frame.  The default title is
1119: of the form @samp{@var{invocation-name}@@@var{machine}} (if there is
1120: only one frame) or shows the selected window's buffer name (if there
1121: is more than one frame).
1122: 
1123:   You can specify a non-default title for the initial Emacs frame with
1124: a command line option:
1125: 
1126: @table @samp
1127: @item -T @var{title}
1128: @opindex -T
1129: @itemx --title=@var{title}
1130: @opindex --title
1131: @cindex frame title, command-line argument
1132: Specify @var{title} as the title for the initial Emacs frame.
1133: @end table
1134: 
1135:   The @samp{--name} option (@pxref{Resources}) also specifies the title
1136: for the initial Emacs frame.
1137: 
1138: @node Icons X
1139: @appendixsec Icons
1140: @cindex icons (X Window System)
1141: @cindex minimizing a frame at startup
1142: 
1143: @table @samp
1144: @item -iconic
1145: @opindex --iconic
1146: @itemx --iconic
1147: @cindex start iconified, command-line argument
1148: Start Emacs in an iconified state.
1149: 
1150: @item -nbi
1151: @opindex -nbi
1152: @itemx --no-bitmap-icon
1153: @opindex --no-bitmap-icon
1154: @cindex Emacs icon, a gnu
1155: Disable the use of the Emacs icon.
1156: @end table
1157: 
1158:   Most window managers allow you to iconify (or ``minimize'') an
1159: Emacs frame, hiding it from sight.  Some window managers replace
1160: iconified windows with tiny icons, while others remove them
1161: entirely from sight.  The @samp{-iconic} option tells Emacs to begin
1162: running in an iconified state, rather than showing a frame right away.
1163: The text frame doesn't appear until you deiconify (or ``un-minimize'')
1164: it.
1165: 
1166:   By default, Emacs uses an icon containing the Emacs logo.  On
1167: desktop environments such as Gnome, this icon is also displayed in
1168: other contexts, e.g., when switching into an Emacs frame.  The
1169: @samp{-nbi} or @samp{--no-bitmap-icon} option tells Emacs to let the
1170: window manager choose what sort of icon to use---usually just a small
1171: rectangle containing the frame's title.
1172: 
1173: @node Misc X
1174: @appendixsec Other Display Options
1175: 
1176: @table @samp
1177: @c @item -hb
1178: @c @opindex -hb
1179: @c @itemx --horizontal-scroll-bars
1180: @c @opindex --horizontal-scroll-bars
1181: @c @c @cindex horizontal scroll bars, command-line argument
1182: @c Enable horizontal scroll bars.  Since horizontal scroll bars
1183: @c are not yet implemented, this actually does nothing.
1184: 
1185: @item --parent-id @var{id}
1186: Open Emacs as a client X window via the XEmbed protocol, with @var{id}
1187: as the parent X window id.  Currently, this option is mainly useful
1188: for developers.
1189: 
1190: @item -vb
1191: @opindex -vb
1192: @itemx --vertical-scroll-bars
1193: @opindex --vertical-scroll-bars
1194: @cindex vertical scroll bars, command-line argument
1195: Enable vertical scroll bars.
1196: 
1197: @item -lsp @var{pixels}
1198: @opindex -lsp
1199: @itemx --line-spacing=@var{pixels}
1200: @opindex --line-spacing
1201: @cindex line spacing, command-line argument
1202: Specify @var{pixels} as additional space to put between lines, in pixels.
1203: 
1204: @item -nbc
1205: @opindex -nbc
1206: @itemx --no-blinking-cursor
1207: @opindex --no-blinking-cursor
1208: @cindex blinking cursor disable, command-line argument
1209: Disable the blinking cursor on graphical displays.
1210: 
1211: @item -D
1212: @opindex -D
1213: @itemx --basic-display
1214: @opindex --basic-display
1215: Disable the menu-bar, the tool-bar, the scroll-bars, and tool tips,
1216: and turn off the blinking cursor.  This can be useful for making a
1217: test case that simplifies debugging of display problems.
1218: @end table
1219: 
1220:   The @samp{--xrm} option (@pxref{Resources}) specifies additional
1221: X resource values.
1222: