Mercurial > hg > xemacs-beta
annotate man/xemacs/cmdargs.texi @ 4448:fd8a9a4d81d9
Support #!, to allow XEmacs to be called as a script interpreter.
ChangeLog addition:
2008-01-20 Aidan Kehoe <kehoea@parhasard.net>
* Makefile.in.in (SHEBANG_PROGNAME):
New variable; a symbol link to the XEmacs binary to tell it it
should read a script from stdin.
* configure.ac (XE_EXPAND_VARIABLE):
Set SHEBANG_PROGNAME.
* configure:
Regenerate.
src/ChangeLog addition:
2008-01-20 Aidan Kehoe <kehoea@parhasard.net>
* config.h.in: Add SHEBANG_PROGNAME.
* emacs.c (main_1):
If we've been called using SHEBANG_PROGNAME, rewrite our arguments
to add a --script argument.
Also, handle the --script argument by setting noninteractive and
vanilla.
* lread.c (Fload_internal):
If the first two characters of a file are #!, replace them with ;!
before they get to the Lisp reader.
lisp/ChangeLog addition:
2008-01-20 Aidan Kehoe <kehoea@parhasard.net>
* startup.el (command-line-do-script): New.
(command-switch-alist): Use command-line-do-script.
New argument, compatible with GNU; --script or -script says "treat
the following argument as a file to load in batch mode".
man/ChangeLog addition:
2008-01-20 Aidan Kehoe <kehoea@parhasard.net>
* xemacs/cmdargs.texi (Command Switches):
Describe --script, -script.
| author | Aidan Kehoe <kehoea@parhasard.net> |
|---|---|
| date | Sun, 20 Jan 2008 19:53:54 +0100 |
| parents | 1ccc32a20af4 |
| children |
| rev | line source |
|---|---|
| 428 | 1 |
| 2 @node Command Switches, Startup Paths, Exiting, Top | |
| 3 @section Command Line Switches and Arguments | |
| 4 @cindex command line arguments | |
| 5 @cindex arguments (from shell) | |
| 6 | |
| 7 XEmacs supports command line arguments you can use to request | |
| 8 various actions when invoking Emacs. The commands are for compatibility | |
| 9 with other editors and for sophisticated activities. If you are using | |
| 10 XEmacs under the X window system, you can also use a number of | |
| 11 standard Xt command line arguments. Command line arguments are not usually | |
| 12 needed for editing with Emacs; new users can skip this section. | |
| 13 | |
| 446 | 14 Many editors are designed to be started afresh each time you want to |
| 428 | 15 edit. You start the editor to edit one file; then exit the editor. The |
| 16 next time you want to edit either another file or the same one, you | |
| 17 start the editor again. Under these circumstances, it makes sense to use a | |
| 18 command line argument to say which file to edit. | |
| 19 | |
| 20 The recommended way to use XEmacs is to start it only once, just | |
| 21 after you log in, and do all your editing in the same Emacs process. | |
| 22 Each time you want to edit a file, you visit it using the existing | |
| 23 Emacs. Emacs creates a new buffer for each file, and (unless you kill | |
| 24 some of the buffers) Emacs eventually has many files in it ready for | |
| 25 editing. Usually you do not kill the Emacs process until you are about | |
| 26 to log out. Since you usually read files by typing commands to Emacs, | |
| 27 command line arguments for specifying a file when Emacs is started are seldom | |
| 28 needed. | |
| 29 | |
| 30 Emacs accepts command-line arguments that specify files to visit, | |
| 446 | 31 functions to call, and other activities and operating modes. If you |
| 32 are running XEmacs under the X window system, a number of standard Xt | |
| 33 command line arguments are available, as well as a few X parameters | |
| 34 that are XEmacs-specific. | |
| 35 | |
| 36 Options with long names with a single initial hyphen are also | |
| 37 recognized with the GNU double initial hyphen syntax. (The reverse | |
| 38 is not true.) | |
| 428 | 39 |
| 40 The following subsections list: | |
| 41 @itemize @bullet | |
| 42 @item | |
| 43 Command line arguments that you can always use | |
| 44 @item | |
| 45 Command line arguments that have to appear at the beginning of the | |
| 46 argument list | |
| 47 @item | |
| 48 Command line arguments that are only relevant if you are running XEmacs | |
| 49 under X | |
| 50 @end itemize | |
| 51 | |
| 52 @subsection Command Line Arguments for Any Position | |
| 53 Command line arguments are processed in the order they appear on the | |
| 54 command line; however, certain arguments (the ones in the | |
| 55 second table) must be at the front of the list if they are used. | |
| 56 | |
| 57 Here are the arguments allowed: | |
| 58 | |
| 59 @table @samp | |
| 60 @item @var{file} | |
| 61 Visit @var{file} using @code{find-file}. @xref{Visiting}. | |
| 62 | |
| 63 @item +@var{linenum} @var{file} | |
| 64 Visit @var{file} using @code{find-file}, then go to line number | |
| 65 @var{linenum} in it. | |
| 66 | |
| 67 @item -load @var{file} | |
| 68 @itemx -l @var{file} | |
| 69 Load a file @var{file} of Lisp code with the function @code{load}. | |
| 70 @xref{Lisp Libraries}. | |
| 71 | |
| 72 @item -funcall @var{function} | |
| 73 @itemx -f @var{function} | |
| 74 Call Lisp function @var{function} with no arguments. | |
| 75 | |
| 76 @item -eval @var{function} | |
| 77 Interpret the next argument as a Lisp expression, and evaluate it. | |
| 78 You must be very careful of the shell quoting here. | |
| 79 | |
| 80 @item -insert @var{file} | |
| 81 @itemx -i @var{file} | |
| 82 Insert the contents of @var{file} into the current buffer. This is like | |
| 83 what @kbd{M-x insert-buffer} does; @xref{Misc File Ops}. | |
| 84 | |
| 85 @item -kill | |
| 446 | 86 Exit from Emacs without asking for confirmation. Always the last |
| 87 argument processed, no matter where it appears in the command line. | |
| 428 | 88 |
| 89 @item -version | |
| 90 @itemx -V | |
| 91 Prints version information. This implies @samp{-batch}. | |
| 92 | |
| 93 @example | |
| 94 % xemacs -version | |
| 95 XEmacs 19.13 of Mon Aug 21 1995 on willow (usg-unix-v) [formerly Lucid Emacs] | |
| 96 @end example | |
| 97 | |
| 98 @item -help | |
| 99 Prints a summary of command-line options and then exits. | |
| 100 @end table | |
| 101 | |
| 102 @subsection Command Line Arguments (Beginning of Line Only) | |
| 103 The following arguments are recognized only at the beginning of the | |
| 104 command line. If more than one of them appears, they must appear in the | |
| 105 order in which they appear in this table. | |
| 106 | |
| 107 @table @samp | |
| 446 | 108 @item --show-dump-id |
| 109 @itemx -sd | |
| 110 Print the ID for the new portable dumper's dump file on the terminal and | |
| 111 exit. (Prints an error message and exits if XEmacs was not configured | |
| 112 @samp{--pdump}.) | |
| 113 | |
| 114 @item --no-dump-file | |
| 115 @itemx -nd | |
| 116 Don't load the dump file. Roughly equivalent to old temacs. (Ignored if | |
| 117 XEmacs was not configured @samp{--pdump}.) | |
| 118 | |
| 119 @item --terminal @var{file} | |
| 120 @itemx -t @var{file} | |
| 428 | 121 Use @var{file} instead of the terminal for input and output. This |
| 122 implies the @samp{-nw} option, documented below. | |
| 123 | |
| 124 @cindex batch mode | |
| 125 @item -batch | |
| 126 Run Emacs in @dfn{batch mode}, which means that the text being edited is | |
| 127 not displayed and the standard Unix interrupt characters such as | |
| 128 @kbd{C-z} and @kbd{C-c} continue to have their normal effect. Emacs in | |
| 129 batch mode outputs to @code{stderr} only what would normally be printed | |
| 130 in the echo area under program control. | |
| 131 | |
| 132 Batch mode is used for running programs written in Emacs Lisp from shell | |
| 133 scripts, makefiles, and so on. Normally the @samp{-l} switch or | |
| 134 @samp{-f} switch will be used as well, to invoke a Lisp program to do | |
| 135 the batch processing. | |
| 136 | |
| 137 @samp{-batch} implies @samp{-q} (do not load an init file). It also | |
| 138 causes Emacs to kill itself after all command switches have been | |
| 139 processed. In addition, auto-saving is not done except in buffers for | |
| 140 which it has been explicitly requested. | |
| 141 | |
| 446 | 142 @item --no-windows |
| 143 @itemx -nw | |
| 428 | 144 Start up XEmacs in TTY mode (using the TTY XEmacs was started from), |
| 145 rather than trying to connect to an X display. Note that this happens | |
| 146 automatically if the @samp{DISPLAY} environment variable is not set. | |
| 147 | |
| 148 @item -debug-init | |
| 149 Enter the debugger if an error in the init file occurs. | |
| 150 | |
| 151 @item -debug-paths | |
| 152 Displays information on how XEmacs constructs the various paths into its | |
| 153 hierarchy on startup. (See also @pxref{Startup Paths}.) | |
| 154 | |
| 155 @item -unmapped | |
| 156 Do not map the initial frame. This is useful if you want to start up | |
| 157 XEmacs as a server (e.g. for gnuserv screens or external client widgets). | |
| 158 | |
| 159 @item -no-init-file | |
| 160 @itemx -q | |
| 442 | 161 Do not load your Emacs init file. @xref{Init File}. |
| 428 | 162 |
| 163 @item -no-site-file | |
| 164 Do not load the site-specific init file @file{lisp/site-start.el}. | |
| 165 | |
| 166 @item -no-autoloads | |
| 167 Do not load global symbol files (@file{auto-autoloads}) at startup. | |
| 168 This implies @samp{-vanilla}. | |
| 169 | |
| 170 @item -no-early-packages | |
| 171 Do not process early packages. (For more information on startup issues | |
| 172 concerning the package system, @xref{Startup Paths}.) | |
| 173 | |
|
4448
fd8a9a4d81d9
Support #!, to allow XEmacs to be called as a script interpreter.
Aidan Kehoe <kehoea@parhasard.net>
parents:
446
diff
changeset
|
174 @item -script @var{file} |
|
fd8a9a4d81d9
Support #!, to allow XEmacs to be called as a script interpreter.
Aidan Kehoe <kehoea@parhasard.net>
parents:
446
diff
changeset
|
175 @item --script @var{file} |
|
fd8a9a4d81d9
Support #!, to allow XEmacs to be called as a script interpreter.
Aidan Kehoe <kehoea@parhasard.net>
parents:
446
diff
changeset
|
176 Load @var{file} as a (compiled or interpreted) Lisp file; do not load |
|
fd8a9a4d81d9
Support #!, to allow XEmacs to be called as a script interpreter.
Aidan Kehoe <kehoea@parhasard.net>
parents:
446
diff
changeset
|
177 any window-system or TTY code, do not load the user init file, the site |
|
fd8a9a4d81d9
Support #!, to allow XEmacs to be called as a script interpreter.
Aidan Kehoe <kehoea@parhasard.net>
parents:
446
diff
changeset
|
178 file, or the early packages. This is comparable to running |
|
fd8a9a4d81d9
Support #!, to allow XEmacs to be called as a script interpreter.
Aidan Kehoe <kehoea@parhasard.net>
parents:
446
diff
changeset
|
179 @samp{xemacs} @samp{-batch} @samp{-l} @var{file}. |
|
fd8a9a4d81d9
Support #!, to allow XEmacs to be called as a script interpreter.
Aidan Kehoe <kehoea@parhasard.net>
parents:
446
diff
changeset
|
180 |
|
fd8a9a4d81d9
Support #!, to allow XEmacs to be called as a script interpreter.
Aidan Kehoe <kehoea@parhasard.net>
parents:
446
diff
changeset
|
181 You can also specify this flag implicitly by calling the XEmacs binary |
|
fd8a9a4d81d9
Support #!, to allow XEmacs to be called as a script interpreter.
Aidan Kehoe <kehoea@parhasard.net>
parents:
446
diff
changeset
|
182 with a value for @samp{argv[0]} of @samp{xemacs-script}, normally by |
|
fd8a9a4d81d9
Support #!, to allow XEmacs to be called as a script interpreter.
Aidan Kehoe <kehoea@parhasard.net>
parents:
446
diff
changeset
|
183 means of a symbolic link. On a POSIX system, this means that adding the |
|
fd8a9a4d81d9
Support #!, to allow XEmacs to be called as a script interpreter.
Aidan Kehoe <kehoea@parhasard.net>
parents:
446
diff
changeset
|
184 line: |
|
fd8a9a4d81d9
Support #!, to allow XEmacs to be called as a script interpreter.
Aidan Kehoe <kehoea@parhasard.net>
parents:
446
diff
changeset
|
185 |
|
fd8a9a4d81d9
Support #!, to allow XEmacs to be called as a script interpreter.
Aidan Kehoe <kehoea@parhasard.net>
parents:
446
diff
changeset
|
186 @example |
|
fd8a9a4d81d9
Support #!, to allow XEmacs to be called as a script interpreter.
Aidan Kehoe <kehoea@parhasard.net>
parents:
446
diff
changeset
|
187 #!/usr/bin/env xemacs-script |
|
fd8a9a4d81d9
Support #!, to allow XEmacs to be called as a script interpreter.
Aidan Kehoe <kehoea@parhasard.net>
parents:
446
diff
changeset
|
188 @end example |
|
fd8a9a4d81d9
Support #!, to allow XEmacs to be called as a script interpreter.
Aidan Kehoe <kehoea@parhasard.net>
parents:
446
diff
changeset
|
189 |
|
fd8a9a4d81d9
Support #!, to allow XEmacs to be called as a script interpreter.
Aidan Kehoe <kehoea@parhasard.net>
parents:
446
diff
changeset
|
190 at the start of an XEmacs Lisp file, and changing that file's |
|
fd8a9a4d81d9
Support #!, to allow XEmacs to be called as a script interpreter.
Aidan Kehoe <kehoea@parhasard.net>
parents:
446
diff
changeset
|
191 permissions to executable, creates a script that can be invoked by |
|
fd8a9a4d81d9
Support #!, to allow XEmacs to be called as a script interpreter.
Aidan Kehoe <kehoea@parhasard.net>
parents:
446
diff
changeset
|
192 typing the path to the file. XEmacs has logic to ignore the #! line at |
|
fd8a9a4d81d9
Support #!, to allow XEmacs to be called as a script interpreter.
Aidan Kehoe <kehoea@parhasard.net>
parents:
446
diff
changeset
|
193 the start of the script, so that won't cause an error. |
|
fd8a9a4d81d9
Support #!, to allow XEmacs to be called as a script interpreter.
Aidan Kehoe <kehoea@parhasard.net>
parents:
446
diff
changeset
|
194 |
| 428 | 195 @item -vanilla |
| 196 This is equivalent to @samp{-q -no-site-file -no-early-packages}. | |
| 197 | |
| 198 @item -user-init-file @var{file} | |
| 442 | 199 Load @var{file} as your Emacs init file instead of |
| 200 @file{~/.xemacs/init.el}/@file{~/.emacs}. | |
| 428 | 201 |
| 202 @item -user-init-directory @var{directory} | |
| 203 Use @var{directory} as the location of your early package hierarchies | |
| 204 and the various user-specific initialization files. | |
| 205 | |
| 206 @item -user @var{user} | |
| 207 @itemx -u @var{user} | |
| 442 | 208 Equivalent to @samp{-user-init-file ~@var{user}/.xemacs/init.el |
| 209 -user-init-directory ~@var{user}/.xemacs}, or @samp{-user-init-file | |
| 446 | 210 ~@var{user}/.emacs -user-init-directory ~@var{user}/.xemacs}, whichever |
| 442 | 211 init file comes first. @xref{Init File}. |
| 428 | 212 |
| 213 @end table | |
| 214 | |
| 215 @vindex command-line-args | |
| 216 Note that the init file can get access to the command line argument | |
| 217 values as the elements of a list in the variable | |
| 218 @code{command-line-args}. (The arguments in the second table above will | |
| 219 already have been processed and will not be in the list.) The init file | |
| 220 can override the normal processing of the other arguments by setting | |
| 221 this variable. | |
| 222 | |
| 223 One way to use command switches is to visit many files automatically: | |
| 224 | |
| 225 @example | |
| 226 xemacs *.c | |
| 227 @end example | |
| 228 | |
| 229 @noindent | |
| 230 passes each @code{.c} file as a separate argument to Emacs, so that | |
| 231 Emacs visits each file (@pxref{Visiting}). | |
| 232 | |
| 233 Here is an advanced example that assumes you have a Lisp program file | |
| 234 called @file{hack-c-program.el} which, when loaded, performs some useful | |
| 235 operation on the current buffer, expected to be a C program. | |
| 236 | |
| 237 @example | |
| 238 xemacs -batch foo.c -l hack-c-program -f save-buffer -kill > log | |
| 239 @end example | |
| 240 | |
| 241 @noindent | |
| 242 Here Emacs is told to visit @file{foo.c}, load @file{hack-c-program.el} | |
| 243 (which makes changes in the visited file), save @file{foo.c} (note that | |
| 244 @code{save-buffer} is the function that @kbd{C-x C-s} is bound to), and | |
| 245 then exit to the shell from which the command was executed. @samp{-batch} | |
| 246 guarantees there will be no problem redirecting output to @file{log}, | |
| 247 because Emacs will not assume that it has a display terminal to work | |
| 248 with. | |
| 249 | |
| 250 @subsection Command Line Arguments (for XEmacs Under X) | |
| 251 @vindex frame-title-format | |
| 252 @vindex frame-icon-title-format | |
| 253 If you are running XEmacs under X, a number of options are | |
| 254 available to control color, border, and window title and icon name: | |
| 255 | |
| 256 @table @samp | |
| 257 @item -title @var{title} | |
| 258 @itemx -wn @var{title} | |
| 259 @itemx -T @var{title} | |
| 260 Use @var{title} as the window title. This sets the | |
| 261 @code{frame-title-format} variable, which controls the title of the X | |
| 262 window corresponding to the selected frame. This is the same format as | |
| 263 @code{mode-line-format}. | |
| 264 | |
| 265 @item -iconname @var{title} | |
| 266 @itemx -in @var{title} | |
| 267 Use @var{title} as the icon name. This sets the | |
| 268 @code{frame-icon-title-format} variable, which controls the title of | |
| 269 the icon corresponding to the selected frame. | |
| 270 | |
| 271 @item -mc @var{color} | |
| 272 Use @var{color} as the mouse color. | |
| 273 | |
| 274 @item -cr @var{color} | |
| 275 Use @var{color} as the text-cursor foreground color. | |
| 276 | |
| 277 @item -private | |
| 278 Install a private colormap for XEmacs. | |
| 279 @end table | |
| 280 | |
| 281 In addition, XEmacs allows you to use a number of standard Xt | |
| 282 command line arguments. | |
| 283 | |
| 284 @table @samp | |
| 285 | |
| 286 @item -background @var{color} | |
| 287 @itemx -bg @var{color} | |
| 288 Use @var{color} as the background color. | |
| 289 | |
| 290 @item -bordercolor @var{color} | |
| 291 @itemx -bd @var{color} | |
| 292 Use @var{color} as the border color. | |
| 293 | |
| 294 @item -borderwidth @var{width} | |
| 295 @itemx -bw @var{width} | |
| 296 Use @var{width} as the border width. | |
| 297 | |
| 298 @item -display @var{display} | |
| 299 @itemx -d @var{display} | |
| 300 When running under the X window system, create the window containing the | |
| 301 Emacs frame on the display named @var{display}. | |
| 302 | |
| 303 @item -foreground @var{color} | |
| 304 @itemx -fg @var{color} | |
| 305 Use @var{color} as the foreground color. | |
| 306 | |
| 307 @item -font @var{name} | |
| 308 @itemx -fn @var{name} | |
| 309 Use @var{name} as the default font. | |
| 310 | |
| 311 @item -geometry @var{spec} | |
| 312 @itemx -geom @var{spec} | |
| 313 @itemx -g @var{spec} | |
| 314 Use the geometry (window size and/or position) specified by @var{spec}. | |
| 315 | |
| 316 @item -iconic | |
| 317 Start up iconified. | |
| 318 | |
| 319 @item -rv | |
| 320 Bring up Emacs in reverse video. | |
| 321 | |
| 322 @item -name @var{name} | |
| 323 Use the resource manager resources specified by @var{name}. | |
| 324 The default is to use the name of the program (@code{argv[0]}) as | |
| 325 the resource manager name. | |
| 326 | |
| 327 @item -xrm | |
| 328 Read something into the resource database for this invocation of Emacs only. | |
| 329 | |
| 330 @end table |