Commit | Line | Data |
---|---|---|
4d213d5a LT |
1 | \input texinfo @c -*-texinfo-*- |
2 | @comment %**start of header | |
3 | @setfilename ../info/emacs-xtra | |
4 | @settitle Specialized Emacs Features | |
5 | @syncodeindex fn cp | |
6 | @syncodeindex vr cp | |
7 | @syncodeindex ky cp | |
8 | @comment %**end of header | |
9 | ||
10 | @copying | |
331fbb7d | 11 | This manual describes specialized features of Emacs. |
4d213d5a | 12 | |
b223e22d | 13 | Copyright @copyright{} 2004, 2005, 2006 Free Software Foundation, Inc. |
4d213d5a LT |
14 | |
15 | @quotation | |
16 | Permission is granted to copy, distribute and/or modify this document | |
678e7c71 | 17 | under the terms of the GNU Free Documentation License, Version 1.2 or |
4d213d5a LT |
18 | any later version published by the Free Software Foundation; with no |
19 | Invariant Sections, with the Front-Cover texts being ``A GNU | |
20 | Manual'', and with the Back-Cover Texts as in (a) below. A copy of the | |
21 | license is included in the section entitled ``GNU Free Documentation | |
22 | License'' in the Emacs manual. | |
23 | ||
24 | (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify | |
25 | this GNU Manual, like GNU software. Copies published by the Free | |
26 | Software Foundation raise funds for GNU development.'' | |
27 | ||
28 | This document is part of a collection distributed under the GNU Free | |
29 | Documentation License. If you want to distribute this document | |
30 | separately from the collection, you can do so by adding a copy of the | |
31 | license to the document, as described in section 6 of the license. | |
32 | @end quotation | |
33 | @end copying | |
34 | ||
35 | @dircategory Emacs | |
36 | @direntry | |
37 | * Emacs-Xtra: (emacs-xtra). Specialized Emacs features. | |
38 | @end direntry | |
39 | ||
40 | @titlepage | |
41 | @title Specialized Emacs Features | |
42 | @page | |
43 | @vskip 0pt plus 1filll | |
44 | @insertcopying | |
45 | @end titlepage | |
46 | ||
47 | @contents | |
48 | ||
49 | @ifnottex | |
50 | @node Top | |
51 | @top Specialized Emacs Features | |
52 | ||
53 | @insertcopying | |
54 | ||
55 | @end ifnottex | |
56 | ||
57 | @menu | |
58 | * Introduction:: What documentation belongs here? | |
59 | * Autorevert:: Auto Reverting non-file buffers. | |
45ca30f2 | 60 | * Subdir Switches:: Subdirectory switches in Dired. |
24396ac6 | 61 | * Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization. |
327c2cb3 LT |
62 | * Emerge:: A convenient way of merging two versions |
63 | of a program. | |
e0fc8fa2 CY |
64 | * Picture Mode:: Editing pictures made up of characters |
65 | using the quarter-plane screen model. | |
45ca30f2 KB |
66 | |
67 | * Advanced VC Usage:: Advanced VC (version control) features. | |
e0fc8fa2 | 68 | * Fortran:: Fortran mode and its special features. |
e691d082 | 69 | * MS-DOG:: |
4d213d5a LT |
70 | * Index:: |
71 | @end menu | |
72 | ||
73 | @node Introduction | |
74 | @unnumbered Introduction | |
75 | ||
76 | This manual contains detailed information about various features that | |
77 | are too specialized to be included in the Emacs manual. It is | |
78 | intended to be readable by anyone having a basic knowledge of Emacs. | |
79 | However, certain sections may be intended for a more specialized | |
80 | audience, such as Elisp authors. This should be clearly pointed out | |
81 | at the beginning of these sections. | |
82 | ||
83 | This manual is intended as a complement, rather than an alternative, | |
84 | to other ways to gain a more detailed knowledge of Emacs than the | |
85 | Emacs manual can provide, such as browsing packages using @kbd{C-h p}, | |
86 | accessing mode documentation using @kbd{C-h m} and browsing user | |
87 | options using Custom. Also, certain packages, or collections of | |
88 | related features, have their own manuals. The present manual is | |
89 | mainly intended to be a collection of smaller specialized features, | |
90 | too small to get their own manual. | |
91 | ||
92 | Sections intended specifically for Elisp programmers can follow the | |
93 | style of the Elisp manual. Other sections should follow the style of | |
94 | the Emacs manual. | |
95 | ||
96 | @node Autorevert | |
97 | @chapter Auto Reverting non-file Buffers | |
98 | ||
99 | Normally Global Auto Revert Mode only reverts file buffers. There are | |
100 | two ways to auto-revert certain non-file buffers: enabling Auto Revert | |
101 | Mode in those buffers (using @kbd{M-x auto-revert-mode}) and setting | |
102 | @code{global-auto-revert-non-file-buffers} to @code{t}. The latter | |
103 | enables Auto Reverting for all types of buffers for which it is | |
104 | implemented, that is, for the types of buffers listed in the menu | |
105 | below. | |
106 | ||
107 | Like file buffers, non-file buffers should normally not revert while | |
108 | you are working on them, or while they contain information that might | |
109 | get lost after reverting. Therefore, they do not revert if they are | |
110 | ``modified''. This can get tricky, because deciding when a non-file | |
111 | buffer should be marked modified is usually more difficult than for | |
112 | file buffers. | |
113 | ||
114 | Another tricky detail is that, for efficiency reasons, Auto Revert | |
115 | often does not try to detect all possible changes in the buffer, only | |
116 | changes that are ``major'' or easy to detect. Hence, enabling | |
117 | auto-reverting for a non-file buffer does not always guarantee that | |
118 | all information in the buffer is up to date and does not necessarily | |
119 | make manual reverts useless. | |
120 | ||
2626389a LT |
121 | At the other extreme, certain buffers automatically auto-revert every |
122 | @code{auto-revert-interval} seconds. (This currently only applies to | |
123 | the Buffer Menu.) In this case, Auto Revert does not print any | |
124 | messages while reverting, even when @code{auto-revert-verbose} is | |
125 | non-@code{nil}. | |
126 | ||
4d213d5a LT |
127 | The details depend on the particular types of buffers and are |
128 | explained in the corresponding sections. | |
129 | ||
130 | @menu | |
131 | * Auto Reverting the Buffer Menu:: | |
132 | * Auto Reverting Dired:: | |
133 | * Supporting additional buffers:: | |
134 | @end menu | |
135 | ||
136 | @node Auto Reverting the Buffer Menu | |
137 | @section Auto Reverting the Buffer Menu | |
138 | ||
139 | If auto-reverting of non-file buffers is enabled, the Buffer Menu | |
140 | automatically reverts every @code{auto-revert-interval} seconds, | |
141 | whether there is a need for it or not. (It would probably take longer | |
142 | to check whether there is a need than to actually revert.) | |
143 | ||
144 | If the Buffer Menu inappropriately gets marked modified, just revert | |
145 | it manually using @kbd{g} and auto-reverting will resume. However, if | |
146 | you marked certain buffers to get deleted or to be displayed, you have | |
147 | to be careful, because reverting erases all marks. The fact that | |
148 | adding marks sets the buffer's modified flag prevents Auto Revert from | |
149 | automatically erasing the marks. | |
150 | ||
151 | @node Auto Reverting Dired | |
152 | @section Auto Reverting Dired buffers | |
153 | ||
236e9d7e LT |
154 | Auto-reverting Dired buffers currently works on GNU or Unix style |
155 | operating systems. It may not work satisfactorily on some other | |
156 | systems. | |
4d213d5a LT |
157 | |
158 | Dired buffers only auto-revert when the file list of the buffer's main | |
159 | directory changes. They do not auto-revert when information about a | |
160 | particular file changes or when inserted subdirectories change. To be | |
161 | sure that @emph{all} listed information is up to date, you have to | |
162 | manually revert using @kbd{g}, @emph{even} if auto-reverting is | |
163 | enabled in the Dired buffer. Sometimes, you might get the impression | |
164 | that modifying or saving files listed in the main directory actually | |
165 | does cause auto-reverting. This is because making changes to a file, | |
166 | or saving it, very often causes changes in the directory itself, for | |
167 | instance, through backup files or auto-save files. However, this is | |
168 | not guaranteed. | |
169 | ||
170 | If the Dired buffer is marked modified and there are no changes you | |
171 | want to protect, then most of the time you can make auto-reverting | |
172 | resume by manually reverting the buffer using @kbd{g}. There is one | |
236e9d7e LT |
173 | exception. If you flag or mark files, you can safely revert the |
174 | buffer. This will not erase the flags or marks (unless the marked | |
175 | file has been deleted, of course). However, the buffer will stay | |
176 | modified, even after reverting, and auto-reverting will not resume. | |
177 | This is because, if you flag or mark files, you may be working on the | |
178 | buffer and you might not want the buffer to change without warning. | |
179 | If you want auto-reverting to resume in the presence of marks and | |
180 | flags, mark the buffer non-modified using @kbd{M-~}. However, adding, | |
181 | deleting or changing marks or flags will mark it modified again. | |
4d213d5a LT |
182 | |
183 | Remote Dired buffers are not auto-reverted. Neither are Dired buffers | |
184 | for which you used shell wildcards or file arguments to list only some | |
185 | of the files. @samp{*Find*} and @samp{*Locate*} buffers do not | |
186 | auto-revert either. | |
187 | ||
188 | @node Supporting additional buffers | |
189 | @section Adding Support for Auto-Reverting additional Buffers. | |
190 | ||
191 | This section is intended for Elisp programmers who would like to add | |
192 | support for auto-reverting new types of buffers. | |
193 | ||
194 | To support auto-reverting the buffer must first of all have a | |
195 | @code{revert-buffer-function}. @xref{Definition of | |
196 | revert-buffer-function,, Reverting, elisp, the Emacs Lisp Reference Manual}. | |
197 | ||
198 | In addition, it @emph{must} have a @code{buffer-stale-function}. | |
199 | ||
200 | @defvar buffer-stale-function | |
201 | The value of this variable is a function to check whether a non-file | |
202 | buffer needs reverting. This should be a function with one optional | |
203 | argument @var{noconfirm}. The function should return non-@code{nil} | |
204 | if the buffer should be reverted. The buffer is current when this | |
205 | function is called. | |
206 | ||
207 | While this function is mainly intended for use in auto-reverting, it | |
208 | could be used for other purposes as well. For instance, if | |
209 | auto-reverting is not enabled, it could be used to warn the user that | |
210 | the buffer needs reverting. The idea behind the @var{noconfirm} | |
211 | argument is that it should be @code{t} if the buffer is going to be | |
212 | reverted without asking the user and @code{nil} if the function is | |
213 | just going to be used to warn the user that the buffer is out of date. | |
214 | In particular, for use in auto-reverting, @var{noconfirm} is @code{t}. | |
215 | If the function is only going to be used for auto-reverting, you can | |
216 | ignore the @var{noconfirm} argument. | |
217 | ||
218 | If you just want to automatically auto-revert every | |
219 | @code{auto-revert-interval} seconds, use: | |
220 | ||
221 | @example | |
222 | (set (make-local-variable 'buffer-stale-function) | |
223 | #'(lambda (&optional noconfirm) 'fast)) | |
224 | @end example | |
225 | ||
226 | @noindent | |
227 | in the buffer's mode function. | |
228 | ||
2626389a LT |
229 | The special return value @samp{fast} tells the caller that the need |
230 | for reverting was not checked, but that reverting the buffer is fast. | |
231 | It also tells Auto Revert not to print any revert messages, even if | |
232 | @code{auto-revert-verbose} is non-@code{nil}. This is important, as | |
233 | getting revert messages every @code{auto-revert-interval} seconds can | |
234 | be very annoying. The information provided by this return value could | |
235 | also be useful if the function is consulted for purposes other than | |
236 | auto-reverting. | |
4d213d5a LT |
237 | @end defvar |
238 | ||
239 | Once the buffer has a @code{revert-buffer-function} and a | |
240 | @code{buffer-stale-function}, several problems usually remain. | |
241 | ||
242 | The buffer will only auto-revert if it is marked unmodified. Hence, | |
243 | you will have to make sure that various functions mark the buffer | |
244 | modified if and only if either the buffer contains information that | |
245 | might be lost by reverting or there is reason to believe that the user | |
246 | might be inconvenienced by auto-reverting, because he is actively | |
247 | working on the buffer. The user can always override this by manually | |
248 | adjusting the modified status of the buffer. To support this, calling | |
249 | the @code{revert-buffer-function} on a buffer that is marked | |
250 | unmodified should always keep the buffer marked unmodified. | |
251 | ||
252 | It is important to assure that point does not continuously jump around | |
253 | as a consequence of auto-reverting. Of course, moving point might be | |
254 | inevitable if the buffer radically changes. | |
255 | ||
256 | You should make sure that the @code{revert-buffer-function} does not | |
257 | print messages that unnecessarily duplicate Auto Revert's own messages | |
258 | if @code{auto-revert-verbose} is @code{t} and effectively override a | |
259 | @code{nil} value for @code{auto-revert-verbose}. Hence, adapting a | |
260 | mode for auto-reverting often involves getting rid of such messages. | |
2626389a LT |
261 | This is especially important for buffers that automatically |
262 | auto-revert every @code{auto-revert-interval} seconds. | |
4d213d5a | 263 | |
331fbb7d LT |
264 | Also, you may want to update the documentation string of |
265 | @code{global-auto-revert-non-file-buffers}. | |
266 | ||
4d213d5a LT |
267 | @ifinfo |
268 | Finally, you should add a node to this chapter's menu. This node | |
269 | @end ifinfo | |
270 | @ifnotinfo | |
271 | Finally, you should add a section to this chapter. This section | |
272 | @end ifnotinfo | |
273 | should at the very least make clear whether enabling auto-reverting | |
274 | for the buffer reliably assures that all information in the buffer is | |
275 | completely up to date (or will be after @code{auto-revert-interval} | |
276 | seconds). | |
277 | ||
45ca30f2 | 278 | @node Subdir Switches |
4d213d5a LT |
279 | @chapter Subdirectory Switches in Dired |
280 | ||
281 | You can insert subdirectories with specified @code{ls} switches in | |
282 | Dired buffers, using @kbd{C-u i}. You can change the @code{ls} | |
283 | switches of an already inserted subdirectory using @kbd{C-u l}. | |
284 | ||
bf247b6e | 285 | In Emacs versions 22.1 and later, Dired remembers the switches, so |
4d213d5a LT |
286 | that reverting the buffer will not change them back to the main |
287 | directory's switches. Deleting a subdirectory forgets about its | |
288 | switches. | |
289 | ||
290 | Using @code{dired-undo} (usually bound to @kbd{C-_} and @kbd{C-x u}) | |
291 | to reinsert or delete subdirectories, that were inserted with explicit | |
292 | switches, can bypass Dired's machinery for remembering (or forgetting) | |
293 | switches. Deleting a subdirectory using @code{dired-undo} does not | |
294 | forget its switches. When later reinserted using @kbd{i}, it will be | |
295 | reinserted using its old switches. Using @code{dired-undo} to | |
296 | reinsert a subdirectory that was deleted using the regular | |
297 | Dired commands (not @code{dired-undo}) will originally insert it with | |
298 | its old switches. However, reverting the buffer will relist it using | |
299 | the buffer's default switches. If any of this yields problems, you | |
300 | can easily correct the situation using @kbd{C-u i} or @kbd{C-u l}. | |
301 | ||
b6d0a321 LT |
302 | Dired does not remember the @code{R} switch. Inserting a subdirectory |
303 | with switches that include the @code{R} switch is equivalent with | |
304 | inserting each of its subdirectories using all remaining switches. | |
def26fa4 LT |
305 | For instance, updating or killing a subdirectory that was inserted |
306 | with the @code{R} switch will not update or kill its subdirectories. | |
b6d0a321 | 307 | |
4d213d5a LT |
308 | The buffer's default switches do not affect subdirectories that were |
309 | inserted using explicitly specified switches. In particular, | |
310 | commands such as @kbd{s}, that change the buffer's switches do not | |
311 | affect such subdirectories. (They do affect subdirectories without | |
312 | explicitly assigned switches, however.) | |
313 | ||
314 | You can make Dired forget about all subdirectory switches and relist | |
315 | all subdirectories with the buffer's default switches using | |
316 | @kbd{M-x dired-reset-subdir-switches}. This also reverts the Dired buffer. | |
317 | ||
24396ac6 GM |
318 | |
319 | @c Moved here from the Emacs Lisp Reference Manual, 2005-03-26. | |
320 | @node Advanced Calendar/Diary Usage | |
321 | @chapter Customizing the Calendar and Diary | |
322 | ||
323 | There are many customizations that you can use to make the calendar and | |
324 | diary suit your personal tastes. | |
325 | ||
326 | @menu | |
327 | * Calendar Customizing:: Defaults you can set. | |
328 | * Holiday Customizing:: Defining your own holidays. | |
329 | * Date Display Format:: Changing the format. | |
330 | * Time Display Format:: Changing the format. | |
331 | * Daylight Savings:: Changing the default. | |
332 | * Diary Customizing:: Defaults you can set. | |
333 | * Hebrew/Islamic Entries:: How to obtain them. | |
334 | * Fancy Diary Display:: Enhancing the diary display, sorting entries, | |
335 | using included diary files. | |
336 | * Sexp Diary Entries:: Fancy things you can do. | |
24396ac6 GM |
337 | @end menu |
338 | ||
339 | @node Calendar Customizing | |
340 | @section Customizing the Calendar | |
24396ac6 GM |
341 | @vindex calendar-holiday-marker |
342 | @vindex diary-entry-marker | |
343 | The variable @code{calendar-holiday-marker} specifies how to mark a | |
344 | date as being a holiday. Its value may be a single-character string | |
345 | to insert next to the date, or a face name to use for displaying the | |
346 | date. Likewise, the variable @code{diary-entry-marker} specifies how | |
347 | to mark a date that has diary entries. The calendar creates faces | |
348 | named @code{holiday-face} and @code{diary-face} for these purposes; | |
349 | those symbols are the default values of these variables. | |
350 | ||
351 | @vindex calendar-load-hook | |
352 | The variable @code{calendar-load-hook} is a normal hook run when the | |
353 | calendar package is first loaded (before actually starting to display | |
354 | the calendar). | |
355 | ||
356 | @vindex initial-calendar-window-hook | |
357 | Starting the calendar runs the normal hook | |
358 | @code{initial-calendar-window-hook}. Recomputation of the calendar | |
359 | display does not run this hook. But if you leave the calendar with the | |
360 | @kbd{q} command and reenter it, the hook runs again.@refill | |
361 | ||
362 | @vindex today-visible-calendar-hook | |
363 | The variable @code{today-visible-calendar-hook} is a normal hook run | |
364 | after the calendar buffer has been prepared with the calendar when the | |
365 | current date is visible in the window. One use of this hook is to | |
366 | replace today's date with asterisks; to do that, use the hook function | |
367 | @code{calendar-star-date}. | |
368 | ||
369 | @findex calendar-star-date | |
370 | @example | |
371 | (add-hook 'today-visible-calendar-hook 'calendar-star-date) | |
372 | @end example | |
373 | ||
374 | @noindent | |
375 | Another standard hook function marks the current date, either by | |
376 | changing its face or by adding an asterisk. Here's how to use it: | |
377 | ||
378 | @findex calendar-mark-today | |
379 | @example | |
380 | (add-hook 'today-visible-calendar-hook 'calendar-mark-today) | |
381 | @end example | |
382 | ||
383 | @noindent | |
384 | @vindex calendar-today-marker | |
385 | The variable @code{calendar-today-marker} specifies how to mark | |
386 | today's date. Its value should be a single-character string to insert | |
387 | next to the date or a face name to use for displaying the date. A | |
388 | face named @code{calendar-today-face} is provided for this purpose; | |
389 | that symbol is the default for this variable. | |
390 | ||
391 | @vindex today-invisible-calendar-hook | |
392 | @noindent | |
393 | A similar normal hook, @code{today-invisible-calendar-hook} is run if | |
394 | the current date is @emph{not} visible in the window. | |
395 | ||
396 | @vindex calendar-move-hook | |
397 | Each of the calendar cursor motion commands runs the hook | |
398 | @code{calendar-move-hook} after it moves the cursor. | |
399 | ||
400 | @node Holiday Customizing | |
401 | @section Customizing the Holidays | |
402 | ||
403 | @vindex calendar-holidays | |
404 | @vindex christian-holidays | |
405 | @vindex hebrew-holidays | |
406 | @vindex islamic-holidays | |
407 | Emacs knows about holidays defined by entries on one of several lists. | |
408 | You can customize these lists of holidays to your own needs, adding or | |
409 | deleting holidays. The lists of holidays that Emacs uses are for | |
410 | general holidays (@code{general-holidays}), local holidays | |
411 | (@code{local-holidays}), Christian holidays (@code{christian-holidays}), | |
412 | Hebrew (Jewish) holidays (@code{hebrew-holidays}), Islamic (Muslim) | |
413 | holidays (@code{islamic-holidays}), and other holidays | |
414 | (@code{other-holidays}). | |
415 | ||
416 | @vindex general-holidays | |
417 | The general holidays are, by default, holidays common throughout the | |
418 | United States. To eliminate these holidays, set @code{general-holidays} | |
419 | to @code{nil}. | |
420 | ||
421 | @vindex local-holidays | |
422 | There are no default local holidays (but sites may supply some). You | |
423 | can set the variable @code{local-holidays} to any list of holidays, as | |
424 | described below. | |
425 | ||
426 | @vindex all-christian-calendar-holidays | |
427 | @vindex all-hebrew-calendar-holidays | |
428 | @vindex all-islamic-calendar-holidays | |
429 | By default, Emacs does not include all the holidays of the religions | |
430 | that it knows, only those commonly found in secular calendars. For a | |
431 | more extensive collection of religious holidays, you can set any (or | |
432 | all) of the variables @code{all-christian-calendar-holidays}, | |
433 | @code{all-hebrew-calendar-holidays}, or | |
434 | @code{all-islamic-calendar-holidays} to @code{t}. If you want to | |
435 | eliminate the religious holidays, set any or all of the corresponding | |
436 | variables @code{christian-holidays}, @code{hebrew-holidays}, and | |
437 | @code{islamic-holidays} to @code{nil}.@refill | |
438 | ||
439 | @vindex other-holidays | |
440 | You can set the variable @code{other-holidays} to any list of | |
441 | holidays. This list, normally empty, is intended for individual use. | |
442 | ||
443 | @cindex holiday forms | |
444 | Each of the lists (@code{general-holidays}, @code{local-holidays}, | |
445 | @code{christian-holidays}, @code{hebrew-holidays}, | |
446 | @code{islamic-holidays}, and @code{other-holidays}) is a list of | |
447 | @dfn{holiday forms}, each holiday form describing a holiday (or | |
448 | sometimes a list of holidays). | |
449 | ||
450 | Here is a table of the possible kinds of holiday form. Day numbers | |
451 | and month numbers count starting from 1, but ``dayname'' numbers | |
452 | count Sunday as 0. The element @var{string} is always the | |
453 | name of the holiday, as a string. | |
454 | ||
455 | @table @code | |
456 | @item (holiday-fixed @var{month} @var{day} @var{string}) | |
457 | A fixed date on the Gregorian calendar. | |
458 | ||
459 | @item (holiday-float @var{month} @var{dayname} @var{k} @var{string}) | |
460 | The @var{k}th @var{dayname} in @var{month} on the Gregorian calendar | |
461 | (@var{dayname}=0 for Sunday, and so on); negative @var{k} means count back | |
462 | from the end of the month. | |
463 | ||
464 | @item (holiday-hebrew @var{month} @var{day} @var{string}) | |
465 | A fixed date on the Hebrew calendar. | |
466 | ||
467 | @item (holiday-islamic @var{month} @var{day} @var{string}) | |
468 | A fixed date on the Islamic calendar. | |
469 | ||
470 | @item (holiday-julian @var{month} @var{day} @var{string}) | |
471 | A fixed date on the Julian calendar. | |
472 | ||
473 | @item (holiday-sexp @var{sexp} @var{string}) | |
474 | A date calculated by the Lisp expression @var{sexp}. The expression | |
475 | should use the variable @code{year} to compute and return the date of a | |
476 | holiday, or @code{nil} if the holiday doesn't happen this year. The | |
477 | value of @var{sexp} must represent the date as a list of the form | |
478 | @code{(@var{month} @var{day} @var{year})}. | |
479 | ||
480 | @item (if @var{condition} @var{holiday-form}) | |
481 | A holiday that happens only if @var{condition} is true. | |
482 | ||
483 | @item (@var{function} @r{[}@var{args}@r{]}) | |
484 | A list of dates calculated by the function @var{function}, called with | |
485 | arguments @var{args}. | |
486 | @end table | |
487 | ||
488 | For example, suppose you want to add Bastille Day, celebrated in | |
489 | France on July 14. You can do this as follows: | |
490 | ||
491 | @smallexample | |
492 | (setq other-holidays '((holiday-fixed 7 14 "Bastille Day"))) | |
493 | @end smallexample | |
494 | ||
495 | @noindent | |
496 | The holiday form @code{(holiday-fixed 7 14 "Bastille Day")} specifies the | |
497 | fourteenth day of the seventh month (July). | |
498 | ||
499 | Many holidays occur on a specific day of the week, at a specific time | |
500 | of month. Here is a holiday form describing Hurricane Supplication Day, | |
501 | celebrated in the Virgin Islands on the fourth Monday in August: | |
502 | ||
503 | @smallexample | |
504 | (holiday-float 8 1 4 "Hurricane Supplication Day") | |
505 | @end smallexample | |
506 | ||
507 | @noindent | |
508 | Here the 8 specifies August, the 1 specifies Monday (Sunday is 0, | |
509 | Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in | |
510 | the month (1 specifies the first occurrence, 2 the second occurrence, | |
511 | @minus{}1 the last occurrence, @minus{}2 the second-to-last occurrence, and | |
512 | so on). | |
513 | ||
514 | You can specify holidays that occur on fixed days of the Hebrew, | |
515 | Islamic, and Julian calendars too. For example, | |
516 | ||
517 | @smallexample | |
518 | (setq other-holidays | |
519 | '((holiday-hebrew 10 2 "Last day of Hanukkah") | |
520 | (holiday-islamic 3 12 "Mohammed's Birthday") | |
521 | (holiday-julian 4 2 "Jefferson's Birthday"))) | |
522 | @end smallexample | |
523 | ||
524 | @noindent | |
525 | adds the last day of Hanukkah (since the Hebrew months are numbered with | |
526 | 1 starting from Nisan), the Islamic feast celebrating Mohammed's | |
527 | birthday (since the Islamic months are numbered from 1 starting with | |
528 | Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the | |
529 | Julian calendar. | |
530 | ||
531 | To include a holiday conditionally, use either Emacs Lisp's @code{if} or the | |
532 | @code{holiday-sexp} form. For example, American presidential elections | |
533 | occur on the first Tuesday after the first Monday in November of years | |
534 | divisible by 4: | |
535 | ||
536 | @smallexample | |
537 | (holiday-sexp '(if (= 0 (% year 4)) | |
538 | (calendar-gregorian-from-absolute | |
539 | (1+ (calendar-dayname-on-or-before | |
540 | 1 (+ 6 (calendar-absolute-from-gregorian | |
541 | (list 11 1 year))))))) | |
542 | "US Presidential Election") | |
543 | @end smallexample | |
544 | ||
545 | @noindent | |
546 | or | |
547 | ||
548 | @smallexample | |
549 | (if (= 0 (% displayed-year 4)) | |
550 | (fixed 11 | |
551 | (extract-calendar-day | |
552 | (calendar-gregorian-from-absolute | |
553 | (1+ (calendar-dayname-on-or-before | |
554 | 1 (+ 6 (calendar-absolute-from-gregorian | |
555 | (list 11 1 displayed-year))))))) | |
556 | "US Presidential Election")) | |
557 | @end smallexample | |
558 | ||
559 | Some holidays just don't fit into any of these forms because special | |
560 | calculations are involved in their determination. In such cases you | |
561 | must write a Lisp function to do the calculation. To include eclipses, | |
562 | for example, add @code{(eclipses)} to @code{other-holidays} | |
563 | and write an Emacs Lisp function @code{eclipses} that returns a | |
564 | (possibly empty) list of the relevant Gregorian dates among the range | |
565 | visible in the calendar window, with descriptive strings, like this: | |
566 | ||
567 | @smallexample | |
568 | (((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... ) | |
569 | @end smallexample | |
570 | ||
571 | @node Date Display Format | |
572 | @section Date Display Format | |
573 | @vindex calendar-date-display-form | |
574 | ||
575 | You can customize the manner of displaying dates in the diary, in mode | |
576 | lines, and in messages by setting @code{calendar-date-display-form}. | |
577 | This variable holds a list of expressions that can involve the variables | |
578 | @code{month}, @code{day}, and @code{year}, which are all numbers in | |
579 | string form, and @code{monthname} and @code{dayname}, which are both | |
580 | alphabetic strings. In the American style, the default value of this | |
581 | list is as follows: | |
582 | ||
583 | @smallexample | |
584 | ((if dayname (concat dayname ", ")) monthname " " day ", " year) | |
585 | @end smallexample | |
586 | ||
587 | @noindent | |
588 | while in the European style this value is the default: | |
589 | ||
590 | @smallexample | |
591 | ((if dayname (concat dayname ", ")) day " " monthname " " year) | |
592 | @end smallexample | |
593 | ||
594 | @noindent | |
595 | The ISO standard date representation is this: | |
596 | ||
597 | @smallexample | |
598 | (year "-" month "-" day) | |
599 | @end smallexample | |
600 | ||
601 | @noindent | |
602 | This specifies a typical American format: | |
603 | ||
604 | @smallexample | |
605 | (month "/" day "/" (substring year -2)) | |
606 | @end smallexample | |
607 | ||
608 | @node Time Display Format | |
609 | @section Time Display Format | |
610 | @vindex calendar-time-display-form | |
611 | ||
612 | The calendar and diary by default display times of day in the | |
613 | conventional American style with the hours from 1 through 12, minutes, | |
614 | and either @samp{am} or @samp{pm}. If you prefer the European style, | |
615 | also known in the US as military, in which the hours go from 00 to 23, | |
616 | you can alter the variable @code{calendar-time-display-form}. This | |
617 | variable is a list of expressions that can involve the variables | |
618 | @code{12-hours}, @code{24-hours}, and @code{minutes}, which are all | |
619 | numbers in string form, and @code{am-pm} and @code{time-zone}, which are | |
620 | both alphabetic strings. The default value of | |
621 | @code{calendar-time-display-form} is as follows: | |
622 | ||
623 | @smallexample | |
624 | (12-hours ":" minutes am-pm | |
625 | (if time-zone " (") time-zone (if time-zone ")")) | |
626 | @end smallexample | |
627 | ||
628 | @noindent | |
629 | Here is a value that provides European style times: | |
630 | ||
631 | @smallexample | |
632 | (24-hours ":" minutes | |
633 | (if time-zone " (") time-zone (if time-zone ")")) | |
634 | @end smallexample | |
635 | ||
636 | @node Daylight Savings | |
637 | @section Daylight Savings Time | |
638 | @cindex daylight savings time | |
639 | ||
640 | Emacs understands the difference between standard time and daylight | |
641 | savings time---the times given for sunrise, sunset, solstices, | |
642 | equinoxes, and the phases of the moon take that into account. The rules | |
643 | for daylight savings time vary from place to place and have also varied | |
644 | historically from year to year. To do the job properly, Emacs needs to | |
645 | know which rules to use. | |
646 | ||
647 | Some operating systems keep track of the rules that apply to the place | |
648 | where you are; on these systems, Emacs gets the information it needs | |
649 | from the system automatically. If some or all of this information is | |
650 | missing, Emacs fills in the gaps with the rules currently used in | |
651 | Cambridge, Massachusetts, which is the center of GNU's world. | |
652 | ||
653 | ||
654 | @vindex calendar-daylight-savings-starts | |
655 | @vindex calendar-daylight-savings-ends | |
656 | If the default choice of rules is not appropriate for your location, | |
657 | you can tell Emacs the rules to use by setting the variables | |
658 | @code{calendar-daylight-savings-starts} and | |
659 | @code{calendar-daylight-savings-ends}. Their values should be Lisp | |
660 | expressions that refer to the variable @code{year}, and evaluate to the | |
661 | Gregorian date on which daylight savings time starts or (respectively) | |
662 | ends, in the form of a list @code{(@var{month} @var{day} @var{year})}. | |
663 | The values should be @code{nil} if your area does not use daylight | |
664 | savings time. | |
665 | ||
666 | Emacs uses these expressions to determine the start and end dates of | |
667 | daylight savings time as holidays and for correcting times of day in the | |
668 | solar and lunar calculations. | |
669 | ||
670 | The values for Cambridge, Massachusetts are as follows: | |
671 | ||
672 | @example | |
673 | @group | |
674 | (calendar-nth-named-day 1 0 4 year) | |
675 | (calendar-nth-named-day -1 0 10 year) | |
676 | @end group | |
677 | @end example | |
678 | ||
679 | @noindent | |
680 | i.e., the first 0th day (Sunday) of the fourth month (April) in | |
681 | the year specified by @code{year}, and the last Sunday of the tenth month | |
682 | (October) of that year. If daylight savings time were | |
683 | changed to start on October 1, you would set | |
684 | @code{calendar-daylight-savings-starts} to this: | |
685 | ||
686 | @example | |
687 | (list 10 1 year) | |
688 | @end example | |
689 | ||
690 | For a more complex example, suppose daylight savings time begins on | |
691 | the first of Nisan on the Hebrew calendar. You should set | |
692 | @code{calendar-daylight-savings-starts} to this value: | |
693 | ||
694 | @example | |
695 | (calendar-gregorian-from-absolute | |
696 | (calendar-absolute-from-hebrew | |
697 | (list 1 1 (+ year 3760)))) | |
698 | @end example | |
699 | ||
700 | @noindent | |
701 | because Nisan is the first month in the Hebrew calendar and the Hebrew | |
702 | year differs from the Gregorian year by 3760 at Nisan. | |
703 | ||
704 | If there is no daylight savings time at your location, or if you want | |
705 | all times in standard time, set @code{calendar-daylight-savings-starts} | |
706 | and @code{calendar-daylight-savings-ends} to @code{nil}. | |
707 | ||
708 | @vindex calendar-daylight-time-offset | |
709 | The variable @code{calendar-daylight-time-offset} specifies the | |
710 | difference between daylight savings time and standard time, measured in | |
711 | minutes. The value for Cambridge is 60. | |
712 | ||
713 | @vindex calendar-daylight-savings-starts-time | |
714 | @vindex calendar-daylight-savings-ends-time | |
715 | The variable @code{calendar-daylight-savings-starts-time} and the | |
716 | variable @code{calendar-daylight-savings-ends-time} specify the number | |
717 | of minutes after midnight local time when the transition to and from | |
718 | daylight savings time should occur. For Cambridge, both variables' | |
719 | values are 120. | |
720 | ||
721 | @node Diary Customizing | |
722 | @section Customizing the Diary | |
723 | ||
724 | @vindex holidays-in-diary-buffer | |
725 | Ordinarily, the mode line of the diary buffer window indicates any | |
726 | holidays that fall on the date of the diary entries. The process of | |
727 | checking for holidays can take several seconds, so including holiday | |
728 | information delays the display of the diary buffer noticeably. If you'd | |
729 | prefer to have a faster display of the diary buffer but without the | |
730 | holiday information, set the variable @code{holidays-in-diary-buffer} to | |
731 | @code{nil}.@refill | |
732 | ||
733 | @vindex number-of-diary-entries | |
734 | The variable @code{number-of-diary-entries} controls the number of | |
735 | days of diary entries to be displayed at one time. It affects the | |
736 | initial display when @code{view-diary-entries-initially} is @code{t}, as | |
737 | well as the command @kbd{M-x diary}. For example, the default value is | |
738 | 1, which says to display only the current day's diary entries. If the | |
739 | value is 2, both the current day's and the next day's entries are | |
740 | displayed. The value can also be a vector of seven elements: for | |
741 | example, if the value is @code{[0 2 2 2 2 4 1]} then no diary entries | |
742 | appear on Sunday, the current date's and the next day's diary entries | |
743 | appear Monday through Thursday, Friday through Monday's entries appear | |
744 | on Friday, while on Saturday only that day's entries appear. | |
745 | ||
746 | @vindex print-diary-entries-hook | |
747 | @findex print-diary-entries | |
748 | The variable @code{print-diary-entries-hook} is a normal hook run | |
749 | after preparation of a temporary buffer containing just the diary | |
750 | entries currently visible in the diary buffer. (The other, irrelevant | |
751 | diary entries are really absent from the temporary buffer; in the diary | |
752 | buffer, they are merely hidden.) The default value of this hook does | |
753 | the printing with the command @code{lpr-buffer}. If you want to use a | |
754 | different command to do the printing, just change the value of this | |
755 | hook. Other uses might include, for example, rearranging the lines into | |
756 | order by day and time. | |
757 | ||
758 | @vindex diary-date-forms | |
759 | You can customize the form of dates in your diary file, if neither the | |
760 | standard American nor European styles suits your needs, by setting the | |
761 | variable @code{diary-date-forms}. This variable is a list of patterns | |
762 | for recognizing a date. Each date pattern is a list whose elements may | |
763 | be regular expressions (@pxref{Regular Expressions,,, elisp, the Emacs | |
764 | Lisp Reference Manual}) or the symbols @code{month}, @code{day}, | |
765 | @code{year}, @code{monthname}, and @code{dayname}. All these elements | |
766 | serve as patterns that match certain kinds of text in the diary file. | |
767 | In order for the date pattern, as a whole, to match, all of its elements | |
768 | must match consecutively. | |
769 | ||
770 | A regular expression in a date pattern matches in its usual fashion, | |
771 | using the standard syntax table altered so that @samp{*} is a word | |
772 | constituent. | |
773 | ||
774 | The symbols @code{month}, @code{day}, @code{year}, @code{monthname}, | |
775 | and @code{dayname} match the month number, day number, year number, | |
776 | month name, and day name of the date being considered. The symbols that | |
777 | match numbers allow leading zeros; those that match names allow | |
778 | three-letter abbreviations and capitalization. All the symbols can | |
779 | match @samp{*}; since @samp{*} in a diary entry means ``any day'', ``any | |
780 | month'', and so on, it should match regardless of the date being | |
781 | considered. | |
782 | ||
783 | The default value of @code{diary-date-forms} in the American style is | |
784 | this: | |
785 | ||
786 | @example | |
787 | ((month "/" day "[^/0-9]") | |
788 | (month "/" day "/" year "[^0-9]") | |
789 | (monthname " *" day "[^,0-9]") | |
790 | (monthname " *" day ", *" year "[^0-9]") | |
791 | (dayname "\\W")) | |
792 | @end example | |
793 | ||
794 | The date patterns in the list must be @emph{mutually exclusive} and | |
795 | must not match any portion of the diary entry itself, just the date and | |
796 | one character of whitespace. If, to be mutually exclusive, the pattern | |
797 | must match a portion of the diary entry text---beyond the whitespace | |
798 | that ends the date---then the first element of the date pattern | |
799 | @emph{must} be @code{backup}. This causes the date recognizer to back | |
800 | up to the beginning of the current word of the diary entry, after | |
801 | finishing the match. Even if you use @code{backup}, the date pattern | |
802 | must absolutely not match more than a portion of the first word of the | |
803 | diary entry. The default value of @code{diary-date-forms} in the | |
804 | European style is this list: | |
805 | ||
806 | @example | |
807 | ((day "/" month "[^/0-9]") | |
808 | (day "/" month "/" year "[^0-9]") | |
809 | (backup day " *" monthname "\\W+\\<[^*0-9]") | |
810 | (day " *" monthname " *" year "[^0-9]") | |
811 | (dayname "\\W")) | |
812 | @end example | |
813 | ||
814 | @noindent | |
815 | Notice the use of @code{backup} in the third pattern, because it needs | |
816 | to match part of a word beyond the date itself to distinguish it from | |
817 | the fourth pattern. | |
818 | ||
819 | @node Hebrew/Islamic Entries | |
820 | @section Hebrew- and Islamic-Date Diary Entries | |
821 | ||
822 | Your diary file can have entries based on Hebrew or Islamic dates, as | |
823 | well as entries based on the world-standard Gregorian calendar. | |
824 | However, because recognition of such entries is time-consuming and most | |
825 | people don't use them, you must explicitly enable their use. If you | |
826 | want the diary to recognize Hebrew-date diary entries, for example, | |
827 | you must do this: | |
828 | ||
829 | @vindex nongregorian-diary-listing-hook | |
830 | @vindex nongregorian-diary-marking-hook | |
831 | @findex list-hebrew-diary-entries | |
832 | @findex mark-hebrew-diary-entries | |
833 | @smallexample | |
834 | (add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries) | |
835 | (add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries) | |
836 | @end smallexample | |
837 | ||
838 | @noindent | |
839 | If you want Islamic-date entries, do this: | |
840 | ||
841 | @findex list-islamic-diary-entries | |
842 | @findex mark-islamic-diary-entries | |
843 | @smallexample | |
844 | (add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries) | |
845 | (add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-entries) | |
846 | @end smallexample | |
847 | ||
848 | Hebrew- and Islamic-date diary entries have the same formats as | |
849 | Gregorian-date diary entries, except that @samp{H} precedes a Hebrew | |
850 | date and @samp{I} precedes an Islamic date. Moreover, because the | |
851 | Hebrew and Islamic month names are not uniquely specified by the first | |
852 | three letters, you may not abbreviate them. For example, a diary entry | |
853 | for the Hebrew date Heshvan 25 could look like this: | |
854 | ||
855 | @smallexample | |
856 | HHeshvan 25 Happy Hebrew birthday! | |
857 | @end smallexample | |
858 | ||
859 | @noindent | |
860 | and would appear in the diary for any date that corresponds to Heshvan 25 | |
861 | on the Hebrew calendar. And here is an Islamic-date diary entry that matches | |
862 | Dhu al-Qada 25: | |
863 | ||
864 | @smallexample | |
865 | IDhu al-Qada 25 Happy Islamic birthday! | |
866 | @end smallexample | |
867 | ||
868 | As with Gregorian-date diary entries, Hebrew- and Islamic-date entries | |
869 | are nonmarking if they are preceded with an ampersand (@samp{&}). | |
870 | ||
871 | Here is a table of commands used in the calendar to create diary entries | |
872 | that match the selected date and other dates that are similar in the Hebrew | |
873 | or Islamic calendar: | |
874 | ||
875 | @table @kbd | |
876 | @item i h d | |
877 | Add a diary entry for the Hebrew date corresponding to the selected date | |
878 | (@code{insert-hebrew-diary-entry}). | |
879 | @item i h m | |
880 | Add a diary entry for the day of the Hebrew month corresponding to the | |
881 | selected date (@code{insert-monthly-hebrew-diary-entry}). This diary | |
882 | entry matches any date that has the same Hebrew day-within-month as the | |
883 | selected date. | |
884 | @item i h y | |
885 | Add a diary entry for the day of the Hebrew year corresponding to the | |
886 | selected date (@code{insert-yearly-hebrew-diary-entry}). This diary | |
887 | entry matches any date which has the same Hebrew month and day-within-month | |
888 | as the selected date. | |
889 | @item i i d | |
890 | Add a diary entry for the Islamic date corresponding to the selected date | |
891 | (@code{insert-islamic-diary-entry}). | |
892 | @item i i m | |
893 | Add a diary entry for the day of the Islamic month corresponding to the | |
894 | selected date (@code{insert-monthly-islamic-diary-entry}). | |
895 | @item i i y | |
896 | Add a diary entry for the day of the Islamic year corresponding to the | |
897 | selected date (@code{insert-yearly-islamic-diary-entry}). | |
898 | @end table | |
899 | ||
900 | @findex insert-hebrew-diary-entry | |
901 | @findex insert-monthly-hebrew-diary-entry | |
902 | @findex insert-yearly-hebrew-diary-entry | |
903 | @findex insert-islamic-diary-entry | |
904 | @findex insert-monthly-islamic-diary-entry | |
905 | @findex insert-yearly-islamic-diary-entry | |
906 | These commands work much like the corresponding commands for ordinary | |
907 | diary entries: they apply to the date that point is on in the calendar | |
908 | window, and what they do is insert just the date portion of a diary entry | |
909 | at the end of your diary file. You must then insert the rest of the | |
910 | diary entry. | |
911 | ||
912 | @node Fancy Diary Display | |
913 | @section Fancy Diary Display | |
914 | @vindex diary-display-hook | |
915 | @findex simple-diary-display | |
916 | ||
917 | Diary display works by preparing the diary buffer and then running the | |
918 | hook @code{diary-display-hook}. The default value of this hook | |
919 | (@code{simple-diary-display}) hides the irrelevant diary entries and | |
920 | then displays the buffer. However, if you specify the hook as follows, | |
921 | ||
922 | @cindex diary buffer | |
923 | @findex fancy-diary-display | |
924 | @example | |
925 | (add-hook 'diary-display-hook 'fancy-diary-display) | |
926 | @end example | |
927 | ||
928 | @noindent | |
929 | this enables fancy diary display. It displays diary entries and | |
930 | holidays by copying them into a special buffer that exists only for the | |
931 | sake of display. Copying to a separate buffer provides an opportunity | |
932 | to change the displayed text to make it prettier---for example, to sort | |
933 | the entries by the dates they apply to. | |
934 | ||
935 | As with simple diary display, you can print a hard copy of the buffer | |
936 | with @code{print-diary-entries}. To print a hard copy of a day-by-day | |
937 | diary for a week, position point on Sunday of that week, type | |
938 | @kbd{7 d}, and then do @kbd{M-x print-diary-entries}. As usual, the | |
939 | inclusion of the holidays slows down the display slightly; you can speed | |
940 | things up by setting the variable @code{holidays-in-diary-buffer} to | |
941 | @code{nil}. | |
942 | ||
943 | @vindex diary-list-include-blanks | |
944 | Ordinarily, the fancy diary buffer does not show days for which there are | |
945 | no diary entries, even if that day is a holiday. If you want such days to be | |
946 | shown in the fancy diary buffer, set the variable | |
947 | @code{diary-list-include-blanks} to @code{t}.@refill | |
948 | ||
949 | @cindex sorting diary entries | |
950 | If you use the fancy diary display, you can use the normal hook | |
951 | @code{list-diary-entries-hook} to sort each day's diary entries by their | |
952 | time of day. Here's how: | |
953 | ||
954 | @findex sort-diary-entries | |
955 | @example | |
956 | (add-hook 'list-diary-entries-hook 'sort-diary-entries t) | |
957 | @end example | |
958 | ||
959 | @noindent | |
960 | For each day, this sorts diary entries that begin with a recognizable | |
961 | time of day according to their times. Diary entries without times come | |
962 | first within each day. | |
963 | ||
964 | Fancy diary display also has the ability to process included diary | |
965 | files. This permits a group of people to share a diary file for events | |
966 | that apply to all of them. Lines in the diary file of this form: | |
967 | ||
968 | @smallexample | |
969 | #include "@var{filename}" | |
970 | @end smallexample | |
971 | ||
972 | @noindent | |
973 | includes the diary entries from the file @var{filename} in the fancy | |
974 | diary buffer. The include mechanism is recursive, so that included files | |
975 | can include other files, and so on; you must be careful not to have a | |
976 | cycle of inclusions, of course. Here is how to enable the include | |
977 | facility: | |
978 | ||
979 | @vindex list-diary-entries-hook | |
980 | @vindex mark-diary-entries-hook | |
981 | @findex include-other-diary-files | |
982 | @findex mark-included-diary-files | |
983 | @smallexample | |
984 | (add-hook 'list-diary-entries-hook 'include-other-diary-files) | |
985 | (add-hook 'mark-diary-entries-hook 'mark-included-diary-files) | |
986 | @end smallexample | |
987 | ||
988 | The include mechanism works only with the fancy diary display, because | |
989 | ordinary diary display shows the entries directly from your diary file. | |
990 | ||
991 | @node Sexp Diary Entries | |
992 | @section Sexp Entries and the Fancy Diary Display | |
993 | @cindex sexp diary entries | |
994 | ||
995 | Sexp diary entries allow you to do more than just have complicated | |
996 | conditions under which a diary entry applies. If you use the fancy | |
997 | diary display, sexp entries can generate the text of the entry depending | |
998 | on the date itself. For example, an anniversary diary entry can insert | |
999 | the number of years since the anniversary date into the text of the | |
1000 | diary entry. Thus the @samp{%d} in this dairy entry: | |
1001 | ||
1002 | @findex diary-anniversary | |
1003 | @smallexample | |
1004 | %%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old) | |
1005 | @end smallexample | |
1006 | ||
1007 | @noindent | |
1008 | gets replaced by the age, so on October 31, 1990 the entry appears in | |
1009 | the fancy diary buffer like this: | |
1010 | ||
1011 | @smallexample | |
1012 | Arthur's birthday (42 years old) | |
1013 | @end smallexample | |
1014 | ||
1015 | @noindent | |
1016 | If the diary file instead contains this entry: | |
1017 | ||
1018 | @smallexample | |
1019 | %%(diary-anniversary 10 31 1948) Arthur's %d%s birthday | |
1020 | @end smallexample | |
1021 | ||
1022 | @noindent | |
1023 | the entry in the fancy diary buffer for October 31, 1990 appears like this: | |
1024 | ||
1025 | @smallexample | |
1026 | Arthur's 42nd birthday | |
1027 | @end smallexample | |
1028 | ||
1029 | Similarly, cyclic diary entries can interpolate the number of repetitions | |
1030 | that have occurred: | |
1031 | ||
1032 | @findex diary-cyclic | |
1033 | @smallexample | |
1034 | %%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time) | |
1035 | @end smallexample | |
1036 | ||
1037 | @noindent | |
1038 | looks like this: | |
1039 | ||
1040 | @smallexample | |
1041 | Renew medication (5th time) | |
1042 | @end smallexample | |
1043 | ||
1044 | @noindent | |
1045 | in the fancy diary display on September 8, 1990. | |
1046 | ||
1047 | There is an early reminder diary sexp that includes its entry in the | |
1048 | diary not only on the date of occurrence, but also on earlier dates. | |
1049 | For example, if you want a reminder a week before your anniversary, you | |
1050 | can use | |
1051 | ||
1052 | @findex diary-remind | |
1053 | @smallexample | |
1054 | %%(diary-remind '(diary-anniversary 12 22 1968) 7) Ed's anniversary | |
1055 | @end smallexample | |
1056 | ||
1057 | @noindent | |
1058 | and the fancy diary will show | |
1059 | @smallexample | |
1060 | Ed's anniversary | |
1061 | @end smallexample | |
1062 | @noindent | |
1063 | both on December 15 and on December 22. | |
1064 | ||
1065 | @findex diary-date | |
1066 | The function @code{diary-date} applies to dates described by a month, | |
1067 | day, year combination, each of which can be an integer, a list of | |
1068 | integers, or @code{t}. The value @code{t} means all values. For | |
1069 | example, | |
1070 | ||
1071 | @smallexample | |
1072 | %%(diary-date '(10 11 12) 22 t) Rake leaves | |
1073 | @end smallexample | |
1074 | ||
1075 | @noindent | |
1076 | causes the fancy diary to show | |
1077 | ||
1078 | @smallexample | |
1079 | Rake leaves | |
1080 | @end smallexample | |
1081 | ||
1082 | @noindent | |
1083 | on October 22, November 22, and December 22 of every year. | |
1084 | ||
1085 | @findex diary-float | |
1086 | The function @code{diary-float} allows you to describe diary entries | |
1087 | that apply to dates like the third Friday of November, or the last | |
1088 | Tuesday in April. The parameters are the @var{month}, @var{dayname}, | |
1089 | and an index @var{n}. The entry appears on the @var{n}th @var{dayname} | |
1090 | of @var{month}, where @var{dayname}=0 means Sunday, 1 means Monday, and | |
1091 | so on. If @var{n} is negative it counts backward from the end of | |
1092 | @var{month}. The value of @var{month} can be a list of months, a single | |
1093 | month, or @code{t} to specify all months. You can also use an optional | |
1094 | parameter @var{day} to specify the @var{n}th @var{dayname} of | |
1095 | @var{month} on or after/before @var{day}; the value of @var{day} defaults | |
1096 | to 1 if @var{n} is positive and to the last day of @var{month} if | |
1097 | @var{n} is negative. For example, | |
1098 | ||
1099 | @smallexample | |
1100 | %%(diary-float t 1 -1) Pay rent | |
1101 | @end smallexample | |
1102 | ||
1103 | @noindent | |
1104 | causes the fancy diary to show | |
1105 | ||
1106 | @smallexample | |
1107 | Pay rent | |
1108 | @end smallexample | |
1109 | ||
1110 | @noindent | |
1111 | on the last Monday of every month. | |
1112 | ||
1113 | The generality of sexp diary entries lets you specify any diary | |
1114 | entry that you can describe algorithmically. A sexp diary entry | |
1115 | contains an expression that computes whether the entry applies to any | |
1116 | given date. If its value is non-@code{nil}, the entry applies to that | |
1117 | date; otherwise, it does not. The expression can use the variable | |
1118 | @code{date} to find the date being considered; its value is a list | |
1119 | (@var{month} @var{day} @var{year}) that refers to the Gregorian | |
1120 | calendar. | |
1121 | ||
1122 | The sexp diary entry applies to a date when the expression's value | |
1123 | is non-@code{nil}, but some values have more specific meanings. If | |
1124 | the value is a string, that string is a description of the event which | |
1125 | occurs on that date. The value can also have the form | |
1126 | @code{(@var{mark} . @var{string})}; then @var{mark} specifies how to | |
1127 | mark the date in the calendar, and @var{string} is the description of | |
1128 | the event. If @var{mark} is a single-character string, that character | |
1129 | appears next to the date in the calendar. If @var{mark} is a face | |
1130 | name, the date is displayed in that face. If @var{mark} is | |
1131 | @code{nil}, that specifies no particular highlighting for the date. | |
1132 | ||
1133 | Suppose you get paid on the 21st of the month if it is a weekday, and | |
1134 | on the Friday before if the 21st is on a weekend. Here is how to write | |
1135 | a sexp diary entry that matches those dates: | |
1136 | ||
1137 | @smallexample | |
1138 | &%%(let ((dayname (calendar-day-of-week date)) | |
1139 | (day (car (cdr date)))) | |
1140 | (or (and (= day 21) (memq dayname '(1 2 3 4 5))) | |
1141 | (and (memq day '(19 20)) (= dayname 5))) | |
1142 | ) Pay check deposited | |
1143 | @end smallexample | |
1144 | ||
1145 | The following sexp diary entries take advantage of the ability (in the fancy | |
1146 | diary display) to concoct diary entries whose text varies based on the date: | |
1147 | ||
1148 | @findex diary-sunrise-sunset | |
1149 | @findex diary-phases-of-moon | |
1150 | @findex diary-day-of-year | |
1151 | @findex diary-iso-date | |
1152 | @findex diary-julian-date | |
1153 | @findex diary-astro-day-number | |
1154 | @findex diary-hebrew-date | |
1155 | @findex diary-islamic-date | |
1156 | @findex diary-french-date | |
1157 | @findex diary-mayan-date | |
1158 | @table @code | |
1159 | @item %%(diary-sunrise-sunset) | |
1160 | Make a diary entry for the local times of today's sunrise and sunset. | |
1161 | @item %%(diary-phases-of-moon) | |
1162 | Make a diary entry for the phases (quarters) of the moon. | |
1163 | @item %%(diary-day-of-year) | |
1164 | Make a diary entry with today's day number in the current year and the number | |
1165 | of days remaining in the current year. | |
1166 | @item %%(diary-iso-date) | |
1167 | Make a diary entry with today's equivalent ISO commercial date. | |
1168 | @item %%(diary-julian-date) | |
1169 | Make a diary entry with today's equivalent date on the Julian calendar. | |
1170 | @item %%(diary-astro-day-number) | |
1171 | Make a diary entry with today's equivalent astronomical (Julian) day number. | |
1172 | @item %%(diary-hebrew-date) | |
1173 | Make a diary entry with today's equivalent date on the Hebrew calendar. | |
1174 | @item %%(diary-islamic-date) | |
1175 | Make a diary entry with today's equivalent date on the Islamic calendar. | |
1176 | @item %%(diary-french-date) | |
1177 | Make a diary entry with today's equivalent date on the French Revolutionary | |
1178 | calendar. | |
1179 | @item %%(diary-mayan-date) | |
1180 | Make a diary entry with today's equivalent date on the Mayan calendar. | |
1181 | @end table | |
1182 | ||
1183 | @noindent | |
1184 | Thus including the diary entry | |
1185 | ||
1186 | @example | |
1187 | &%%(diary-hebrew-date) | |
1188 | @end example | |
1189 | ||
1190 | @noindent | |
1191 | causes every day's diary display to contain the equivalent date on the | |
1192 | Hebrew calendar, if you are using the fancy diary display. (With simple | |
1193 | diary display, the line @samp{&%%(diary-hebrew-date)} appears in the | |
1194 | diary for any date, but does nothing particularly useful.) | |
1195 | ||
1196 | These functions can be used to construct sexp diary entries based on | |
1197 | the Hebrew calendar in certain standard ways: | |
1198 | ||
1199 | @cindex rosh hodesh | |
1200 | @findex diary-rosh-hodesh | |
1201 | @cindex parasha, weekly | |
1202 | @findex diary-parasha | |
1203 | @cindex candle lighting times | |
1204 | @findex diary-sabbath-candles | |
1205 | @cindex omer count | |
1206 | @findex diary-omer | |
1207 | @cindex yahrzeits | |
1208 | @findex diary-yahrzeit | |
1209 | @table @code | |
1210 | @item %%(diary-rosh-hodesh) | |
1211 | Make a diary entry that tells the occurrence and ritual announcement of each | |
1212 | new Hebrew month. | |
1213 | @item %%(diary-parasha) | |
1214 | Make a Saturday diary entry that tells the weekly synagogue scripture reading. | |
1215 | @item %%(diary-sabbath-candles) | |
1216 | Make a Friday diary entry that tells the @emph{local time} of Sabbath | |
1217 | candle lighting. | |
1218 | @item %%(diary-omer) | |
1219 | Make a diary entry that gives the omer count, when appropriate. | |
1220 | @item %%(diary-yahrzeit @var{month} @var{day} @var{year}) @var{name} | |
1221 | Make a diary entry marking the anniversary of a date of death. The date | |
1222 | is the @emph{Gregorian} (civil) date of death. The diary entry appears | |
1223 | on the proper Hebrew calendar anniversary and on the day before. (In | |
1224 | the European style, the order of the parameters is changed to @var{day}, | |
1225 | @var{month}, @var{year}.) | |
1226 | @end table | |
1227 | ||
1228 | All the functions documented above take an optional argument | |
1229 | @var{mark} which specifies how to mark the date in the calendar display. | |
1230 | If one of these functions decides that it applies to a certain date, | |
1231 | it returns a value that contains @var{mark}. | |
1232 | ||
e0fc8fa2 CY |
1233 | @node Emerge |
1234 | @chapter Merging Files with Emerge | |
1235 | @cindex Emerge | |
1236 | @cindex merging files | |
1237 | ||
1238 | It's not unusual for programmers to get their signals crossed and | |
1239 | modify the same program in two different directions. To recover from | |
1240 | this confusion, you need to merge the two versions. Emerge makes this | |
1241 | easier. For other ways to compare files, see @ref{Comparing Files,,, | |
1242 | emacs, the Emacs Manual} and @ref{Top, Ediff,, ediff, The Ediff | |
1243 | Manual}. | |
1244 | ||
1245 | @menu | |
1246 | * Overview of Emerge:: How to start Emerge. Basic concepts. | |
1247 | * Submodes of Emerge:: Fast mode vs. Edit mode. | |
1248 | Skip Prefers mode and Auto Advance mode. | |
1249 | * State of Difference:: You do the merge by specifying state A or B | |
1250 | for each difference. | |
1251 | * Merge Commands:: Commands for selecting a difference, | |
1252 | changing states of differences, etc. | |
1253 | * Exiting Emerge:: What to do when you've finished the merge. | |
1254 | * Combining in Emerge:: How to keep both alternatives for a difference. | |
1255 | * Fine Points of Emerge:: Misc. | |
1256 | @end menu | |
1257 | ||
1258 | @node Overview of Emerge | |
1259 | @section Overview of Emerge | |
1260 | ||
1261 | To start Emerge, run one of these four commands: | |
1262 | ||
1263 | @table @kbd | |
1264 | @item M-x emerge-files | |
1265 | @findex emerge-files | |
1266 | Merge two specified files. | |
1267 | ||
1268 | @item M-x emerge-files-with-ancestor | |
1269 | @findex emerge-files-with-ancestor | |
1270 | Merge two specified files, with reference to a common ancestor. | |
1271 | ||
1272 | @item M-x emerge-buffers | |
1273 | @findex emerge-buffers | |
1274 | Merge two buffers. | |
1275 | ||
1276 | @item M-x emerge-buffers-with-ancestor | |
1277 | @findex emerge-buffers-with-ancestor | |
1278 | Merge two buffers with reference to a common ancestor in a third | |
1279 | buffer. | |
1280 | @end table | |
1281 | ||
1282 | @cindex merge buffer (Emerge) | |
1283 | @cindex A and B buffers (Emerge) | |
1284 | The Emerge commands compare two files or buffers, and display the | |
1285 | comparison in three buffers: one for each input text (the @dfn{A buffer} | |
1286 | and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging | |
1287 | takes place. The merge buffer shows the full merged text, not just the | |
1288 | differences. Wherever the two input texts differ, you can choose which | |
1289 | one of them to include in the merge buffer. | |
1290 | ||
1291 | The Emerge commands that take input from existing buffers use only | |
1292 | the accessible portions of those buffers, if they are narrowed. | |
1293 | @xref{Narrowing,,, emacs, the Emacs Manual}. | |
1294 | ||
1295 | ||
1296 | If a common ancestor version is available, from which the two texts to | |
1297 | be merged were both derived, Emerge can use it to guess which | |
1298 | alternative is right. Wherever one current version agrees with the | |
1299 | ancestor, Emerge presumes that the other current version is a deliberate | |
1300 | change which should be kept in the merged version. Use the | |
1301 | @samp{with-ancestor} commands if you want to specify a common ancestor | |
1302 | text. These commands read three file or buffer names---variant A, | |
1303 | variant B, and the common ancestor. | |
1304 | ||
1305 | After the comparison is done and the buffers are prepared, the | |
1306 | interactive merging starts. You control the merging by typing special | |
1307 | @dfn{merge commands} in the merge buffer (@pxref{Merge Commands}). | |
1308 | For each run of differences between the input texts, you can choose | |
1309 | which one of them to keep, or edit them both together. | |
1310 | ||
1311 | The merge buffer uses a special major mode, Emerge mode, with commands | |
1312 | for making these choices. But you can also edit the buffer with | |
1313 | ordinary Emacs commands. | |
1314 | ||
1315 | At any given time, the attention of Emerge is focused on one | |
1316 | particular difference, called the @dfn{selected} difference. This | |
1317 | difference is marked off in the three buffers like this: | |
1318 | ||
1319 | @example | |
1320 | vvvvvvvvvvvvvvvvvvvv | |
1321 | @var{text that differs} | |
1322 | ^^^^^^^^^^^^^^^^^^^^ | |
1323 | @end example | |
1324 | ||
1325 | @noindent | |
1326 | Emerge numbers all the differences sequentially and the mode | |
1327 | line always shows the number of the selected difference. | |
1328 | ||
1329 | Normally, the merge buffer starts out with the A version of the text. | |
1330 | But when the A version of a difference agrees with the common ancestor, | |
1331 | then the B version is initially preferred for that difference. | |
1332 | ||
1333 | Emerge leaves the merged text in the merge buffer when you exit. At | |
1334 | that point, you can save it in a file with @kbd{C-x C-w}. If you give a | |
1335 | numeric argument to @code{emerge-files} or | |
1336 | @code{emerge-files-with-ancestor}, it reads the name of the output file | |
1337 | using the minibuffer. (This is the last file name those commands read.) | |
1338 | Then exiting from Emerge saves the merged text in the output file. | |
1339 | ||
1340 | Normally, Emerge commands save the output buffer in its file when you | |
1341 | exit. If you abort Emerge with @kbd{C-]}, the Emerge command does not | |
1342 | save the output buffer, but you can save it yourself if you wish. | |
1343 | ||
1344 | @node Submodes of Emerge | |
1345 | @section Submodes of Emerge | |
1346 | ||
1347 | You can choose between two modes for giving merge commands: Fast mode | |
1348 | and Edit mode. In Fast mode, basic merge commands are single | |
1349 | characters, but ordinary Emacs commands are disabled. This is | |
1350 | convenient if you use only merge commands. In Edit mode, all merge | |
1351 | commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs | |
1352 | commands are also available. This allows editing the merge buffer, but | |
1353 | slows down Emerge operations. | |
1354 | ||
1355 | Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to | |
1356 | Fast mode. The mode line indicates Edit and Fast modes with @samp{E} | |
1357 | and @samp{F}. | |
1358 | ||
1359 | Emerge has two additional submodes that affect how particular merge | |
1360 | commands work: Auto Advance mode and Skip Prefers mode. | |
1361 | ||
1362 | If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands | |
1363 | advance to the next difference. This lets you go through the merge | |
1364 | faster as long as you simply choose one of the alternatives from the | |
1365 | input. The mode line indicates Auto Advance mode with @samp{A}. | |
1366 | ||
1367 | If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands | |
1368 | skip over differences in states prefer-A and prefer-B (@pxref{State of | |
1369 | Difference}). Thus you see only differences for which neither version | |
1370 | is presumed ``correct.'' The mode line indicates Skip Prefers mode with | |
1371 | @samp{S}. | |
1372 | ||
1373 | @findex emerge-auto-advance-mode | |
1374 | @findex emerge-skip-prefers-mode | |
1375 | Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or | |
1376 | clear Auto Advance mode. Use @kbd{s s} | |
1377 | (@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode. | |
1378 | These commands turn on the mode with a positive argument, turns it off | |
1379 | with a negative or zero argument, and toggle the mode with no argument. | |
1380 | ||
1381 | @node State of Difference | |
1382 | @section State of a Difference | |
1383 | ||
1384 | In the merge buffer, a difference is marked with lines of @samp{v} and | |
1385 | @samp{^} characters. Each difference has one of these seven states: | |
1386 | ||
1387 | @table @asis | |
1388 | @item A | |
1389 | The difference is showing the A version. The @kbd{a} command always | |
1390 | produces this state; the mode line indicates it with @samp{A}. | |
1391 | ||
1392 | @item B | |
1393 | The difference is showing the B version. The @kbd{b} command always | |
1394 | produces this state; the mode line indicates it with @samp{B}. | |
1395 | ||
1396 | @item default-A | |
1397 | @itemx default-B | |
1398 | The difference is showing the A or the B state by default, because you | |
1399 | haven't made a choice. All differences start in the default-A state | |
1400 | (and thus the merge buffer is a copy of the A buffer), except those for | |
1401 | which one alternative is ``preferred'' (see below). | |
1402 | ||
1403 | When you select a difference, its state changes from default-A or | |
1404 | default-B to plain A or B. Thus, the selected difference never has | |
1405 | state default-A or default-B, and these states are never displayed in | |
1406 | the mode line. | |
1407 | ||
1408 | The command @kbd{d a} chooses default-A as the default state, and @kbd{d | |
1409 | b} chooses default-B. This chosen default applies to all differences | |
1410 | which you haven't ever selected and for which no alternative is preferred. | |
1411 | If you are moving through the merge sequentially, the differences you | |
1412 | haven't selected are those following the selected one. Thus, while | |
1413 | moving sequentially, you can effectively make the A version the default | |
1414 | for some sections of the merge buffer and the B version the default for | |
1415 | others by using @kbd{d a} and @kbd{d b} between sections. | |
1416 | ||
1417 | @item prefer-A | |
1418 | @itemx prefer-B | |
1419 | The difference is showing the A or B state because it is | |
1420 | @dfn{preferred}. This means that you haven't made an explicit choice, | |
1421 | but one alternative seems likely to be right because the other | |
1422 | alternative agrees with the common ancestor. Thus, where the A buffer | |
1423 | agrees with the common ancestor, the B version is preferred, because | |
1424 | chances are it is the one that was actually changed. | |
1425 | ||
1426 | These two states are displayed in the mode line as @samp{A*} and @samp{B*}. | |
1427 | ||
1428 | @item combined | |
1429 | The difference is showing a combination of the A and B states, as a | |
1430 | result of the @kbd{x c} or @kbd{x C} commands. | |
1431 | ||
1432 | Once a difference is in this state, the @kbd{a} and @kbd{b} commands | |
1433 | don't do anything to it unless you give them a numeric argument. | |
1434 | ||
1435 | The mode line displays this state as @samp{comb}. | |
1436 | @end table | |
1437 | ||
1438 | @node Merge Commands | |
1439 | @section Merge Commands | |
1440 | ||
1441 | Here are the Merge commands for Fast mode; in Edit mode, precede them | |
1442 | with @kbd{C-c C-c}: | |
1443 | ||
1444 | @table @kbd | |
1445 | @item p | |
1446 | Select the previous difference. | |
1447 | ||
1448 | @item n | |
1449 | Select the next difference. | |
1450 | ||
1451 | @item a | |
1452 | Choose the A version of this difference. | |
1453 | ||
1454 | @item b | |
1455 | Choose the B version of this difference. | |
1456 | ||
1457 | @item C-u @var{n} j | |
1458 | Select difference number @var{n}. | |
1459 | ||
1460 | @item . | |
1461 | Select the difference containing point. You can use this command in the | |
1462 | merge buffer or in the A or B buffer. | |
1463 | ||
1464 | @item q | |
1465 | Quit---finish the merge. | |
1466 | ||
1467 | @item C-] | |
1468 | Abort---exit merging and do not save the output. | |
1469 | ||
1470 | @item f | |
1471 | Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.) | |
1472 | ||
1473 | @item e | |
1474 | Go into Edit mode. | |
1475 | ||
1476 | @item l | |
1477 | Recenter (like @kbd{C-l}) all three windows. | |
1478 | ||
1479 | @item - | |
1480 | Specify part of a prefix numeric argument. | |
1481 | ||
1482 | @item @var{digit} | |
1483 | Also specify part of a prefix numeric argument. | |
1484 | ||
1485 | @item d a | |
1486 | Choose the A version as the default from here down in | |
1487 | the merge buffer. | |
1488 | ||
1489 | @item d b | |
1490 | Choose the B version as the default from here down in | |
1491 | the merge buffer. | |
1492 | ||
1493 | @item c a | |
1494 | Copy the A version of this difference into the kill ring. | |
1495 | ||
1496 | @item c b | |
1497 | Copy the B version of this difference into the kill ring. | |
1498 | ||
1499 | @item i a | |
1500 | Insert the A version of this difference at point. | |
1501 | ||
1502 | @item i b | |
1503 | Insert the B version of this difference at point. | |
1504 | ||
1505 | @item m | |
1506 | Put point and mark around the difference. | |
1507 | ||
1508 | @item ^ | |
1509 | Scroll all three windows down (like @kbd{M-v}). | |
1510 | ||
1511 | @item v | |
1512 | Scroll all three windows up (like @kbd{C-v}). | |
1513 | ||
1514 | @item < | |
1515 | Scroll all three windows left (like @kbd{C-x <}). | |
1516 | ||
1517 | @item > | |
1518 | Scroll all three windows right (like @kbd{C-x >}). | |
1519 | ||
1520 | @item | | |
1521 | Reset horizontal scroll on all three windows. | |
1522 | ||
1523 | @item x 1 | |
1524 | Shrink the merge window to one line. (Use @kbd{C-u l} to restore it | |
1525 | to full size.) | |
1526 | ||
1527 | @item x c | |
1528 | Combine the two versions of this difference (@pxref{Combining in | |
1529 | Emerge}). | |
1530 | ||
1531 | @item x f | |
1532 | Show the names of the files/buffers Emerge is operating on, in a Help | |
1533 | window. (Use @kbd{C-u l} to restore windows.) | |
1534 | ||
1535 | @item x j | |
1536 | Join this difference with the following one. | |
1537 | (@kbd{C-u x j} joins this difference with the previous one.) | |
1538 | ||
1539 | @item x s | |
1540 | Split this difference into two differences. Before you use this | |
1541 | command, position point in each of the three buffers at the place where | |
1542 | you want to split the difference. | |
1543 | ||
1544 | @item x t | |
1545 | Trim identical lines off the top and bottom of the difference. | |
1546 | Such lines occur when the A and B versions are | |
1547 | identical but differ from the ancestor version. | |
1548 | @end table | |
1549 | ||
1550 | @node Exiting Emerge | |
1551 | @section Exiting Emerge | |
1552 | ||
1553 | The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing | |
1554 | the results into the output file if you specified one. It restores the | |
1555 | A and B buffers to their proper contents, or kills them if they were | |
1556 | created by Emerge and you haven't changed them. It also disables the | |
1557 | Emerge commands in the merge buffer, since executing them later could | |
1558 | damage the contents of the various buffers. | |
1559 | ||
1560 | @kbd{C-]} aborts the merge. This means exiting without writing the | |
1561 | output file. If you didn't specify an output file, then there is no | |
1562 | real difference between aborting and finishing the merge. | |
1563 | ||
1564 | If the Emerge command was called from another Lisp program, then its | |
1565 | return value is @code{t} for successful completion, or @code{nil} if you | |
1566 | abort. | |
1567 | ||
1568 | @node Combining in Emerge | |
1569 | @section Combining the Two Versions | |
1570 | ||
1571 | Sometimes you want to keep @emph{both} alternatives for a particular | |
1572 | difference. To do this, use @kbd{x c}, which edits the merge buffer | |
1573 | like this: | |
1574 | ||
1575 | @example | |
1576 | @group | |
1577 | #ifdef NEW | |
1578 | @var{version from A buffer} | |
1579 | #else /* not NEW */ | |
1580 | @var{version from B buffer} | |
1581 | #endif /* not NEW */ | |
1582 | @end group | |
1583 | @end example | |
1584 | ||
1585 | @noindent | |
1586 | @vindex emerge-combine-versions-template | |
1587 | While this example shows C preprocessor conditionals delimiting the two | |
1588 | alternative versions, you can specify the strings to use by setting | |
1589 | the variable @code{emerge-combine-versions-template} to a string of your | |
1590 | choice. In the string, @samp{%a} says where to put version A, and | |
1591 | @samp{%b} says where to put version B. The default setting, which | |
1592 | produces the results shown above, looks like this: | |
1593 | ||
1594 | @example | |
1595 | @group | |
1596 | "#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n" | |
1597 | @end group | |
1598 | @end example | |
1599 | ||
1600 | @node Fine Points of Emerge | |
1601 | @section Fine Points of Emerge | |
1602 | ||
1603 | During the merge, you mustn't try to edit the A and B buffers yourself. | |
1604 | Emerge modifies them temporarily, but ultimately puts them back the way | |
1605 | they were. | |
1606 | ||
1607 | You can have any number of merges going at once---just don't use any one | |
1608 | buffer as input to more than one merge at once, since the temporary | |
1609 | changes made in these buffers would get in each other's way. | |
1610 | ||
1611 | Starting Emerge can take a long time because it needs to compare the | |
1612 | files fully. Emacs can't do anything else until @code{diff} finishes. | |
1613 | Perhaps in the future someone will change Emerge to do the comparison in | |
1614 | the background when the input files are large---then you could keep on | |
1615 | doing other things with Emacs until Emerge is ready to accept | |
1616 | commands. | |
1617 | ||
1618 | @vindex emerge-startup-hook | |
1619 | After setting up the merge, Emerge runs the hook | |
1620 | @code{emerge-startup-hook}. @xref{Hooks,,, emacs, the Emacs Manual}. | |
1621 | ||
1622 | @node Picture Mode | |
1623 | @chapter Editing Pictures | |
1624 | @cindex pictures | |
1625 | @cindex making pictures out of text characters | |
1626 | @findex edit-picture | |
1627 | ||
1628 | To edit a picture made out of text characters (for example, a picture | |
1629 | of the division of a register into fields, as a comment in a program), | |
1630 | use the command @kbd{M-x edit-picture} to enter Picture mode. | |
1631 | ||
1632 | In Picture mode, editing is based on the @dfn{quarter-plane} model of | |
1633 | text, according to which the text characters lie studded on an area that | |
1634 | stretches infinitely far to the right and downward. The concept of the end | |
1635 | of a line does not exist in this model; the most you can say is where the | |
1636 | last nonblank character on the line is found. | |
1637 | ||
1638 | Of course, Emacs really always considers text as a sequence of | |
1639 | characters, and lines really do have ends. But Picture mode replaces | |
1640 | the most frequently-used commands with variants that simulate the | |
1641 | quarter-plane model of text. They do this by inserting spaces or by | |
1642 | converting tabs to spaces. | |
1643 | ||
1644 | Most of the basic editing commands of Emacs are redefined by Picture mode | |
1645 | to do essentially the same thing but in a quarter-plane way. In addition, | |
1646 | Picture mode defines various keys starting with the @kbd{C-c} prefix to | |
1647 | run special picture editing commands. | |
1648 | ||
1649 | One of these keys, @kbd{C-c C-c}, is particularly important. Often a | |
1650 | picture is part of a larger file that is usually edited in some other | |
1651 | major mode. @kbd{M-x edit-picture} records the name of the previous | |
1652 | major mode so you can use the @kbd{C-c C-c} command | |
1653 | (@code{picture-mode-exit}) later to go back to that mode. @kbd{C-c C-c} | |
1654 | also deletes spaces from the ends of lines, unless given a numeric | |
1655 | argument. | |
1656 | ||
1657 | The special commands of Picture mode all work in other modes (provided | |
1658 | the @file{picture} library is loaded), but are not bound to keys except | |
1659 | in Picture mode. The descriptions below talk of moving ``one column'' | |
1660 | and so on, but all the picture mode commands handle numeric arguments as | |
1661 | their normal equivalents do. | |
1662 | ||
1663 | @vindex picture-mode-hook | |
1664 | Turning on Picture mode runs the hook @code{picture-mode-hook}. | |
1665 | Additional extensions to Picture mode can be found in | |
1666 | @file{artist.el}. | |
1667 | ||
1668 | @menu | |
1669 | * Basic Picture:: Basic concepts and simple commands of Picture Mode. | |
1670 | * Insert in Picture:: Controlling direction of cursor motion | |
1671 | after "self-inserting" characters. | |
1672 | * Tabs in Picture:: Various features for tab stops and indentation. | |
1673 | * Rectangles in Picture:: Clearing and superimposing rectangles. | |
1674 | @end menu | |
1675 | ||
1676 | @node Basic Picture | |
1677 | @section Basic Editing in Picture Mode | |
1678 | ||
1679 | @findex picture-forward-column | |
1680 | @findex picture-backward-column | |
1681 | @findex picture-move-down | |
1682 | @findex picture-move-up | |
1683 | @cindex editing in Picture mode | |
1684 | ||
1685 | Most keys do the same thing in Picture mode that they usually do, but | |
1686 | do it in a quarter-plane style. For example, @kbd{C-f} is rebound to | |
1687 | run @code{picture-forward-column}, a command which moves point one | |
1688 | column to the right, inserting a space if necessary so that the actual | |
1689 | end of the line makes no difference. @kbd{C-b} is rebound to run | |
1690 | @code{picture-backward-column}, which always moves point left one | |
1691 | column, converting a tab to multiple spaces if necessary. @kbd{C-n} and | |
1692 | @kbd{C-p} are rebound to run @code{picture-move-down} and | |
1693 | @code{picture-move-up}, which can either insert spaces or convert tabs | |
1694 | as necessary to make sure that point stays in exactly the same column. | |
1695 | @kbd{C-e} runs @code{picture-end-of-line}, which moves to after the last | |
1696 | nonblank character on the line. There is no need to change @kbd{C-a}, | |
1697 | as the choice of screen model does not affect beginnings of | |
1698 | lines. | |
1699 | ||
1700 | @findex picture-newline | |
1701 | Insertion of text is adapted to the quarter-plane screen model | |
1702 | through the use of Overwrite mode (@pxref{Minor Modes,,, emacs, the | |
1703 | Emacs Manual}.) Self-inserting characters replace existing text, | |
1704 | column by column, rather than pushing existing text to the right. | |
1705 | @key{RET} runs @code{picture-newline}, which just moves to the | |
1706 | beginning of the following line so that new text will replace that | |
1707 | line. | |
1708 | ||
1709 | @findex picture-backward-clear-column | |
1710 | @findex picture-clear-column | |
1711 | @findex picture-clear-line | |
1712 | In Picture mode, the commands that normally delete or kill text, | |
1713 | instead erase text (replacing it with spaces). @key{DEL} | |
1714 | (@code{picture-backward-clear-column}) replaces the preceding | |
1715 | character with a space rather than removing it; this moves point | |
1716 | backwards. @kbd{C-d} (@code{picture-clear-column}) replaces the next | |
1717 | character or characters with spaces, but does not move point. (If you | |
1718 | want to clear characters to spaces and move forward over them, use | |
1719 | @key{SPC}.) @kbd{C-k} (@code{picture-clear-line}) really kills the | |
1720 | contents of lines, but does not delete the newlines from the buffer. | |
1721 | ||
1722 | @findex picture-open-line | |
1723 | To do actual insertion, you must use special commands. @kbd{C-o} | |
1724 | (@code{picture-open-line}) creates a blank line after the current | |
1725 | line; it never splits a line. @kbd{C-M-o} (@code{split-line}) makes | |
1726 | sense in Picture mode, so it is not changed. @kbd{C-j} | |
1727 | (@code{picture-duplicate-line}) inserts another line with the same | |
1728 | contents below the current line. | |
1729 | ||
1730 | @kindex C-c C-d @r{(Picture mode)} | |
1731 | To do actual deletion in Picture mode, use @kbd{C-w}, @kbd{C-c C-d} | |
1732 | (which is defined as @code{delete-char}, as @kbd{C-d} is in other | |
1733 | modes), or one of the picture rectangle commands (@pxref{Rectangles in | |
1734 | Picture}). | |
1735 | ||
1736 | @node Insert in Picture | |
1737 | @section Controlling Motion after Insert | |
1738 | ||
1739 | @findex picture-movement-up | |
1740 | @findex picture-movement-down | |
1741 | @findex picture-movement-left | |
1742 | @findex picture-movement-right | |
1743 | @findex picture-movement-nw | |
1744 | @findex picture-movement-ne | |
1745 | @findex picture-movement-sw | |
1746 | @findex picture-movement-se | |
1747 | @kindex C-c < @r{(Picture mode)} | |
1748 | @kindex C-c > @r{(Picture mode)} | |
1749 | @kindex C-c ^ @r{(Picture mode)} | |
1750 | @kindex C-c . @r{(Picture mode)} | |
1751 | @kindex C-c ` @r{(Picture mode)} | |
1752 | @kindex C-c ' @r{(Picture mode)} | |
1753 | @kindex C-c / @r{(Picture mode)} | |
1754 | @kindex C-c \ @r{(Picture mode)} | |
1755 | Since ``self-inserting'' characters in Picture mode overwrite and move | |
1756 | point, there is no essential restriction on how point should be moved. | |
1757 | Normally point moves right, but you can specify any of the eight | |
1758 | orthogonal or diagonal directions for motion after a ``self-inserting'' | |
1759 | character. This is useful for drawing lines in the buffer. | |
1760 | ||
1761 | @table @kbd | |
1762 | @item C-c < | |
1763 | @itemx C-c @key{LEFT} | |
1764 | Move left after insertion (@code{picture-movement-left}). | |
1765 | @item C-c > | |
1766 | @itemx C-c @key{RIGHT} | |
1767 | Move right after insertion (@code{picture-movement-right}). | |
1768 | @item C-c ^ | |
1769 | @itemx C-c @key{UP} | |
1770 | Move up after insertion (@code{picture-movement-up}). | |
1771 | @item C-c . | |
1772 | @itemx C-c @key{DOWN} | |
1773 | Move down after insertion (@code{picture-movement-down}). | |
1774 | @item C-c ` | |
1775 | @itemx C-c @key{HOME} | |
1776 | Move up and left (``northwest'') after insertion (@code{picture-movement-nw}). | |
1777 | @item C-c ' | |
1778 | @itemx C-c @key{PAGEUP} | |
1779 | Move up and right (``northeast'') after insertion | |
1780 | (@code{picture-movement-ne}). | |
1781 | @item C-c / | |
1782 | @itemx C-c @key{END} | |
1783 | Move down and left (``southwest'') after insertion | |
1784 | @*(@code{picture-movement-sw}). | |
1785 | @item C-c \ | |
1786 | @itemx C-c @key{PAGEDOWN} | |
1787 | Move down and right (``southeast'') after insertion | |
1788 | @*(@code{picture-movement-se}). | |
1789 | @end table | |
1790 | ||
1791 | @kindex C-c C-f @r{(Picture mode)} | |
1792 | @kindex C-c C-b @r{(Picture mode)} | |
1793 | @findex picture-motion | |
1794 | @findex picture-motion-reverse | |
1795 | Two motion commands move based on the current Picture insertion | |
1796 | direction. The command @kbd{C-c C-f} (@code{picture-motion}) moves in the | |
1797 | same direction as motion after ``insertion'' currently does, while @kbd{C-c | |
1798 | C-b} (@code{picture-motion-reverse}) moves in the opposite direction. | |
1799 | ||
1800 | @node Tabs in Picture | |
1801 | @section Picture Mode Tabs | |
1802 | ||
1803 | @kindex M-TAB @r{(Picture mode)} | |
1804 | @findex picture-tab-search | |
1805 | @vindex picture-tab-chars | |
1806 | Two kinds of tab-like action are provided in Picture mode. Use | |
1807 | @kbd{M-@key{TAB}} (@code{picture-tab-search}) for context-based tabbing. | |
1808 | With no argument, it moves to a point underneath the next | |
1809 | ``interesting'' character that follows whitespace in the previous | |
1810 | nonblank line. ``Next'' here means ``appearing at a horizontal position | |
1811 | greater than the one point starts out at.'' With an argument, as in | |
1812 | @kbd{C-u M-@key{TAB}}, this command moves to the next such interesting | |
1813 | character in the current line. @kbd{M-@key{TAB}} does not change the | |
1814 | text; it only moves point. ``Interesting'' characters are defined by | |
1815 | the variable @code{picture-tab-chars}, which should define a set of | |
1816 | characters. The syntax for this variable is like the syntax used inside | |
1817 | of @samp{[@dots{}]} in a regular expression---but without the @samp{[} | |
1818 | and the @samp{]}. Its default value is @code{"!-~"}. | |
1819 | ||
1820 | @findex picture-tab | |
1821 | @key{TAB} itself runs @code{picture-tab}, which operates based on the | |
1822 | current tab stop settings; it is the Picture mode equivalent of | |
1823 | @code{tab-to-tab-stop}. Normally it just moves point, but with a numeric | |
1824 | argument it clears the text that it moves over. | |
1825 | ||
1826 | @kindex C-c TAB @r{(Picture mode)} | |
1827 | @findex picture-set-tab-stops | |
1828 | The context-based and tab-stop-based forms of tabbing are brought | |
1829 | together by the command @kbd{C-c @key{TAB}} (@code{picture-set-tab-stops}). | |
1830 | This command sets the tab stops to the positions which @kbd{M-@key{TAB}} | |
1831 | would consider significant in the current line. The use of this command, | |
1832 | together with @key{TAB}, can get the effect of context-based tabbing. But | |
1833 | @kbd{M-@key{TAB}} is more convenient in the cases where it is sufficient. | |
1834 | ||
1835 | It may be convenient to prevent use of actual tab characters in | |
1836 | pictures. For example, this prevents @kbd{C-x @key{TAB}} from messing | |
1837 | up the picture. You can do this by setting the variable | |
1838 | @code{indent-tabs-mode} to @code{nil}. | |
1839 | ||
1840 | @node Rectangles in Picture | |
1841 | @section Picture Mode Rectangle Commands | |
1842 | @cindex rectangles and Picture mode | |
1843 | @cindex Picture mode and rectangles | |
1844 | ||
1845 | Picture mode defines commands for working on rectangular pieces of | |
1846 | the text in ways that fit with the quarter-plane model. The standard | |
1847 | rectangle commands may also be useful. @xref{Rectangles,,, emacs, the | |
1848 | Emacs Manual}. | |
1849 | ||
1850 | @table @kbd | |
1851 | @item C-c C-k | |
1852 | Clear out the region-rectangle with spaces | |
1853 | (@code{picture-clear-rectangle}). With argument, delete the text. | |
1854 | @item C-c C-w @var{r} | |
1855 | Similar, but save rectangle contents in register @var{r} first | |
1856 | (@code{picture-clear-rectangle-to-register}). | |
1857 | @item C-c C-y | |
1858 | Copy last killed rectangle into the buffer by overwriting, with upper | |
1859 | left corner at point (@code{picture-yank-rectangle}). With argument, | |
1860 | insert instead. | |
1861 | @item C-c C-x @var{r} | |
1862 | Similar, but use the rectangle in register @var{r} | |
1863 | (@code{picture-yank-rectangle-from-register}). | |
1864 | @end table | |
1865 | ||
1866 | @kindex C-c C-k @r{(Picture mode)} | |
1867 | @kindex C-c C-w @r{(Picture mode)} | |
1868 | @findex picture-clear-rectangle | |
1869 | @findex picture-clear-rectangle-to-register | |
1870 | The picture rectangle commands @kbd{C-c C-k} | |
1871 | (@code{picture-clear-rectangle}) and @kbd{C-c C-w} | |
1872 | (@code{picture-clear-rectangle-to-register}) differ from the standard | |
1873 | rectangle commands in that they normally clear the rectangle instead of | |
1874 | deleting it; this is analogous with the way @kbd{C-d} is changed in Picture | |
1875 | mode. | |
1876 | ||
1877 | However, deletion of rectangles can be useful in Picture mode, so | |
1878 | these commands delete the rectangle if given a numeric argument. | |
1879 | @kbd{C-c C-k} either with or without a numeric argument saves the | |
1880 | rectangle for @kbd{C-c C-y}. | |
1881 | ||
1882 | @kindex C-c C-y @r{(Picture mode)} | |
1883 | @kindex C-c C-x @r{(Picture mode)} | |
1884 | @findex picture-yank-rectangle | |
1885 | @findex picture-yank-rectangle-from-register | |
1886 | The Picture mode commands for yanking rectangles differ from the | |
1887 | standard ones in that they overwrite instead of inserting. This is | |
1888 | the same way that Picture mode insertion of other text differs from | |
1889 | other modes. @kbd{C-c C-y} (@code{picture-yank-rectangle}) inserts | |
1890 | (by overwriting) the rectangle that was most recently killed, while | |
1891 | @kbd{C-c C-x} (@code{picture-yank-rectangle-from-register}) does | |
1892 | likewise for the rectangle found in a specified register. | |
1893 | ||
45ca30f2 KB |
1894 | @node Advanced VC Usage |
1895 | @chapter Advanced VC Usage | |
1896 | ||
1897 | Commonly used features of Emacs' version control (VC) support are | |
1898 | described in the main Emacs manual (@pxref{Version Control,,,emacs, | |
1899 | the Emacs Manual}). This chapter describes more advanced VC usage. | |
1900 | ||
1901 | @menu | |
1902 | * VC Dired Mode:: Listing files managed by version control. | |
1903 | * VC Dired Commands:: Commands to use in a VC Dired buffer. | |
1904 | * Remote Repositories:: Efficient access to remote CVS servers. | |
1905 | * Snapshots:: Sets of file versions treated as a unit. | |
1906 | * Miscellaneous VC:: Various other commands and features of VC. | |
1907 | * Customizing VC:: Variables that change VC's behavior. | |
1908 | @end menu | |
1909 | ||
1910 | @node VC Dired Mode | |
1911 | @section Dired under VC | |
1912 | ||
1913 | @cindex PCL-CVS | |
1914 | @pindex cvs | |
1915 | @cindex CVS Dired Mode | |
1916 | The VC Dired Mode described here works with all the version control | |
1917 | systems that VC supports. Another more powerful facility, designed | |
1918 | specifically for CVS, is called PCL-CVS. @xref{Top, , About PCL-CVS, | |
1919 | pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}. | |
1920 | ||
1921 | @kindex C-x v d | |
1922 | @findex vc-directory | |
1923 | When you are working on a large program, it is often useful to find | |
1924 | out which files have changed within an entire directory tree, or to view | |
1925 | the status of all files under version control at once, and to perform | |
1926 | version control operations on collections of files. You can use the | |
1927 | command @kbd{C-x v d} (@code{vc-directory}) to make a directory listing | |
1928 | that includes only files relevant for version control. | |
1929 | ||
1930 | @vindex vc-dired-terse-display | |
1931 | @kbd{C-x v d} creates a buffer which uses VC Dired Mode. This looks | |
1932 | much like an ordinary Dired buffer (@pxref{Dired,,,emacs, the | |
1933 | Emacs Manual}); however, normally it shows only the noteworthy files | |
1934 | (those locked or not up-to-date). This is called @dfn{terse display}. | |
1935 | If you set the variable @code{vc-dired-terse-display} to @code{nil}, | |
1936 | then VC Dired shows all relevant files---those managed under version | |
1937 | control, plus all subdirectories (@dfn{full display}). The command | |
1938 | @kbd{v t} in a VC Dired buffer toggles between terse display and full | |
1939 | display (@pxref{VC Dired Commands}). | |
1940 | ||
1941 | @vindex vc-dired-recurse | |
1942 | By default, VC Dired produces a recursive listing of noteworthy or | |
1943 | relevant files at or below the given directory. You can change this by | |
1944 | setting the variable @code{vc-dired-recurse} to @code{nil}; then VC | |
1945 | Dired shows only the files in the given directory. | |
1946 | ||
1947 | The line for an individual file shows the version control state in the | |
1948 | place of the hard link count, owner, group, and size of the file. If | |
1949 | the file is unmodified, in sync with the master file, the version | |
1950 | control state shown is blank. Otherwise it consists of text in | |
1951 | parentheses. Under RCS and SCCS, the name of the user locking the file | |
1952 | is shown; under CVS, an abbreviated version of the @samp{cvs status} | |
1953 | output is used. Here is an example using RCS: | |
1954 | ||
1955 | @smallexample | |
1956 | @group | |
1957 | /home/jim/project: | |
1958 | ||
1959 | -rw-r--r-- (jim) Apr 2 23:39 file1 | |
1960 | -r--r--r-- Apr 5 20:21 file2 | |
1961 | @end group | |
1962 | @end smallexample | |
1963 | ||
1964 | @noindent | |
1965 | The files @samp{file1} and @samp{file2} are under version control, | |
1966 | @samp{file1} is locked by user jim, and @samp{file2} is unlocked. | |
1967 | ||
1968 | Here is an example using CVS: | |
1969 | ||
1970 | @smallexample | |
1971 | @group | |
1972 | /home/joe/develop: | |
1973 | ||
1974 | -rw-r--r-- (modified) Aug 2 1997 file1.c | |
1975 | -rw-r--r-- Apr 4 20:09 file2.c | |
1976 | -rw-r--r-- (merge) Sep 13 1996 file3.c | |
1977 | @end group | |
1978 | @end smallexample | |
1979 | ||
1980 | Here @samp{file1.c} is modified with respect to the repository, and | |
1981 | @samp{file2.c} is not. @samp{file3.c} is modified, but other changes | |
1982 | have also been checked in to the repository---you need to merge them | |
1983 | with the work file before you can check it in. | |
1984 | ||
1985 | @vindex vc-stay-local | |
1986 | @vindex vc-cvs-stay-local | |
1987 | In the above, if the repository were on a remote machine, VC would | |
1988 | only contact it when the variable @code{vc-stay-local} (or | |
1989 | @code{vc-cvs-stay-local}) is nil (@pxref{CVS Options}). This is | |
1990 | because access to the repository may be slow, or you may be working | |
1991 | offline and not have access to the repository at all. As a | |
1992 | consequence, VC would not be able to tell you that @samp{file3.c} is | |
1993 | in the ``merge'' state; you would learn that only when you try to | |
1994 | check-in your modified copy of the file, or use a command such as | |
1995 | @kbd{C-x v m}. | |
1996 | ||
1997 | In practice, this is not a problem because CVS handles this case | |
1998 | consistently whenever it arises. In VC, you'll simply get prompted to | |
1999 | merge the remote changes into your work file first. The benefits of | |
2000 | less network communication usually outweigh the disadvantage of not | |
2001 | seeing remote changes immediately. | |
2002 | ||
2003 | @vindex vc-directory-exclusion-list | |
2004 | When VC Dired displays subdirectories (in the ``full'' display mode), | |
2005 | it omits some that should never contain any files under version control. | |
2006 | By default, this includes Version Control subdirectories such as | |
2007 | @samp{RCS} and @samp{CVS}; you can customize this by setting the | |
2008 | variable @code{vc-directory-exclusion-list}. | |
2009 | ||
2010 | You can fine-tune VC Dired's format by typing @kbd{C-u C-x v d}---as in | |
2011 | ordinary Dired, that allows you to specify additional switches for the | |
2012 | @samp{ls} command. | |
2013 | ||
2014 | @node VC Dired Commands | |
2015 | @section VC Dired Commands | |
2016 | ||
2017 | All the usual Dired commands work normally in VC Dired mode, except | |
2018 | for @kbd{v}, which is redefined as the version control prefix. You can | |
2019 | invoke VC commands such as @code{vc-diff} and @code{vc-print-log} by | |
2020 | typing @kbd{v =}, or @kbd{v l}, and so on. Most of these commands apply | |
2021 | to the file name on the current line. | |
2022 | ||
2023 | The command @kbd{v v} (@code{vc-next-action}) operates on all the | |
2024 | marked files, so that you can lock or check in several files at once. | |
2025 | If it operates on more than one file, it handles each file according to | |
2026 | its current state; thus, it might lock one file, but check in another | |
2027 | file. This could be confusing; it is up to you to avoid confusing | |
2028 | behavior by marking a set of files that are in a similar state. If no | |
2029 | files are marked, @kbd{v v} operates on the file in the current line. | |
2030 | ||
2031 | If any files call for check-in, @kbd{v v} reads a single log entry, | |
2032 | then uses it for all the files being checked in. This is convenient for | |
2033 | registering or checking in several files at once, as part of the same | |
2034 | change. | |
2035 | ||
2036 | @findex vc-dired-toggle-terse-mode | |
2037 | @findex vc-dired-mark-locked | |
2038 | You can toggle between terse display (only locked files, or files not | |
2039 | up-to-date) and full display at any time by typing @kbd{v t} | |
2040 | (@code{vc-dired-toggle-terse-mode}). There is also a special command | |
2041 | @kbd{* l} (@code{vc-dired-mark-locked}), which marks all files currently | |
2042 | locked (or, with CVS, all files not up-to-date). Thus, typing @kbd{* l | |
2043 | t k} is another way to delete from the buffer all files except those | |
2044 | currently locked. | |
2045 | ||
2046 | @node Remote Repositories | |
2047 | @section Remote Repositories | |
2048 | @cindex remote repositories (CVS) | |
2049 | ||
2050 | A common way of using CVS is to set up a central CVS repository on | |
2051 | some Internet host, then have each developer check out a personal | |
2052 | working copy of the files on his local machine. Committing changes to | |
2053 | the repository, and picking up changes from other users into one's own | |
2054 | working area, then works by direct interactions with the CVS server. | |
2055 | ||
2056 | One difficulty is that access to the CVS server is often slow, and | |
2057 | that developers might need to work off-line as well. VC is designed | |
2058 | to reduce the amount of network interaction necessary. | |
2059 | ||
2060 | @menu | |
2061 | * Version Backups:: Keeping local copies of repository versions. | |
2062 | * Local Version Control:: Using another version system for local editing. | |
2063 | @end menu | |
2064 | ||
2065 | @node Version Backups | |
2066 | @subsection Version Backups | |
2067 | @cindex version backups | |
2068 | ||
2069 | @cindex automatic version backups | |
2070 | When VC sees that the CVS repository for a file is on a remote | |
2071 | machine, it automatically makes local backups of unmodified versions | |
2072 | of the file---@dfn{automatic version backups}. This means that you | |
2073 | can compare the file to the repository version (@kbd{C-x v =}), or | |
2074 | revert to that version (@kbd{C-x v u}), without any network | |
2075 | interactions. | |
2076 | ||
2077 | The local copy of the unmodified file is called a @dfn{version | |
2078 | backup} to indicate that it corresponds exactly to a version that is | |
2079 | stored in the repository. Note that version backups are not the same | |
2080 | as ordinary Emacs backup files (@pxref{Backup,,,emacs, the Emacs | |
2081 | Manual}). But they follow a similar naming convention. | |
2082 | ||
2083 | For a file that comes from a remote CVS repository, VC makes a | |
2084 | version backup whenever you save the first changes to the file, and | |
2085 | removes it after you have committed your modified version to the | |
2086 | repository. You can disable the making of automatic version backups by | |
2087 | setting @code{vc-cvs-stay-local} to @code{nil} (@pxref{CVS Options}). | |
2088 | ||
2089 | @cindex manual version backups | |
2090 | The name of the automatic version backup for version @var{version} | |
2091 | of file @var{file} is @code{@var{file}.~@var{version}.~}. This is | |
2092 | almost the same as the name used by @kbd{C-x v ~} (@pxref{Old | |
2093 | Versions,,,emacs, the Emacs Manual}), the only difference being | |
2094 | the additional dot (@samp{.}) after the version number. This | |
2095 | similarity is intentional, because both kinds of files store the same | |
2096 | kind of information. The file made by @kbd{C-x v ~} acts as a | |
2097 | @dfn{manual version backup}. | |
2098 | ||
2099 | All the VC commands that operate on old versions of a file can use | |
2100 | both kinds of version backups. For instance, @kbd{C-x v ~} uses | |
2101 | either an automatic or a manual version backup, if possible, to get | |
2102 | the contents of the version you request. Likewise, @kbd{C-x v =} and | |
2103 | @kbd{C-x v u} use either an automatic or a manual version backup, if | |
2104 | one of them exists, to get the contents of a version to compare or | |
2105 | revert to. If you changed a file outside of Emacs, so that no | |
2106 | automatic version backup was created for the previous text, you can | |
2107 | create a manual backup of that version using @kbd{C-x v ~}, and thus | |
2108 | obtain the benefit of the local copy for Emacs commands. | |
2109 | ||
2110 | The only difference in Emacs's handling of manual and automatic | |
2111 | version backups, once they exist, is that Emacs deletes automatic | |
2112 | version backups when you commit to the repository. By contrast, | |
2113 | manual version backups remain until you delete them. | |
2114 | ||
2115 | @node Local Version Control | |
2116 | @subsection Local Version Control | |
2117 | @cindex local version control | |
2118 | @cindex local back end (version control) | |
2119 | ||
2120 | When you make many changes to a file that comes from a remote | |
2121 | repository, it can be convenient to have version control on your local | |
2122 | machine as well. You can then record intermediate versions, revert to | |
2123 | a previous state, etc., before you actually commit your changes to the | |
2124 | remote server. | |
2125 | ||
2126 | VC lets you do this by putting a file under a second, local version | |
2127 | control system, so that the file is effectively registered in two | |
2128 | systems at the same time. For the description here, we will assume | |
2129 | that the remote system is CVS, and you use RCS locally, although the | |
2130 | mechanism works with any combination of version control systems | |
2131 | (@dfn{back ends}). | |
2132 | ||
2133 | To make it work with other back ends, you must make sure that the | |
2134 | ``more local'' back end comes before the ``more remote'' back end in | |
2135 | the setting of @code{vc-handled-backends} (@pxref{Customizing VC}). By | |
2136 | default, this variable is set up so that you can use remote CVS and | |
2137 | local RCS as described here. | |
2138 | ||
2139 | To start using local RCS for a file that comes from a remote CVS | |
2140 | server, you must @emph{register the file in RCS}, by typing @kbd{C-u | |
2141 | C-x v v rcs @key{RET}}. (In other words, use @code{vc-next-action} with a | |
2142 | prefix argument, and specify RCS as the back end.) | |
2143 | ||
2144 | You can do this at any time; it does not matter whether you have | |
2145 | already modified the file with respect to the version in the CVS | |
2146 | repository. If possible, VC tries to make the RCS master start with | |
2147 | the unmodified repository version, then checks in any local changes | |
2148 | as a new version. This works if you have not made any changes yet, or | |
2149 | if the unmodified repository version exists locally as a version | |
2150 | backup (@pxref{Version Backups}). If the unmodified version is not | |
2151 | available locally, the RCS master starts with the modified version; | |
2152 | the only drawback to this is that you cannot compare your changes | |
2153 | locally to what is stored in the repository. | |
2154 | ||
2155 | The version number of the RCS master is derived from the current CVS | |
2156 | version, starting a branch from it. For example, if the current CVS | |
2157 | version is 1.23, the local RCS branch will be 1.23.1. Version 1.23 in | |
2158 | the RCS master will be identical to version 1.23 under CVS; your first | |
2159 | changes are checked in as 1.23.1.1. (If the unmodified file is not | |
2160 | available locally, VC will check in the modified file twice, both as | |
2161 | 1.23 and 1.23.1.1, to make the revision numbers consistent.) | |
2162 | ||
2163 | If you do not use locking under CVS (the default), locking is also | |
2164 | disabled for RCS, so that editing under RCS works exactly as under | |
2165 | CVS. | |
2166 | ||
2167 | When you are done with local editing, you can commit the final version | |
2168 | back to the CVS repository by typing @kbd{C-u C-x v v cvs @key{RET}}. | |
2169 | This initializes the log entry buffer (@pxref{Log Buffer,,,emacs, the | |
2170 | Emacs Manual}) to contain all the log entries you have recorded in the | |
2171 | RCS master; you can edit them as you wish, and then commit in CVS by | |
2172 | typing @kbd{C-c C-c}. If the commit is successful, VC removes the RCS | |
2173 | master, so that the file is once again registered under CVS only. | |
2174 | (The RCS master is not actually deleted, just renamed by appending | |
2175 | @samp{~} to the name, so that you can refer to it later if you wish.) | |
2176 | ||
2177 | While using local RCS, you can pick up recent changes from the CVS | |
2178 | repository into your local file, or commit some of your changes back | |
2179 | to CVS, without terminating local RCS version control. To do this, | |
2180 | switch to the CVS back end temporarily, with the @kbd{C-x v b} command: | |
2181 | ||
2182 | @table @kbd | |
2183 | @item C-x v b | |
2184 | Switch to another back end that the current file is registered | |
2185 | under (@code{vc-switch-backend}). | |
2186 | ||
2187 | @item C-u C-x v b @var{backend} @key{RET} | |
2188 | Switch to @var{backend} for the current file. | |
2189 | @end table | |
2190 | ||
2191 | @kindex C-x v b | |
2192 | @findex vc-switch-backend | |
2193 | @kbd{C-x v b} does not change the buffer contents, or any files; it | |
2194 | only changes VC's perspective on how to handle the file. Any | |
2195 | subsequent VC commands for that file will operate on the back end that | |
2196 | is currently selected. | |
2197 | ||
2198 | If the current file is registered in more than one back end, typing | |
2199 | @kbd{C-x v b} ``cycles'' through all of these back ends. With a | |
2200 | prefix argument, it asks for the back end to use in the minibuffer. | |
2201 | ||
2202 | Thus, if you are using local RCS, and you want to pick up some recent | |
2203 | changes in the file from remote CVS, first visit the file, then type | |
2204 | @kbd{C-x v b} to switch to CVS, and finally use @kbd{C-x v m | |
2205 | @key{RET}} to merge the news (@pxref{Merging,,,emacs, the Emacs | |
2206 | Manual}). You can then switch back to RCS by typing @kbd{C-x v b} | |
2207 | again, and continue to edit locally. | |
2208 | ||
2209 | But if you do this, the revision numbers in the RCS master no longer | |
2210 | correspond to those of CVS. Technically, this is not a problem, but | |
2211 | it can become difficult to keep track of what is in the CVS repository | |
2212 | and what is not. So we suggest that you return from time to time to | |
2213 | CVS-only operation, by committing your local changes back to the | |
2214 | repository using @kbd{C-u C-x v v cvs @key{RET}}. | |
2215 | ||
2216 | @node Snapshots | |
2217 | @section Snapshots | |
2218 | @cindex snapshots and version control | |
2219 | ||
2220 | A @dfn{snapshot} is a named set of file versions (one for each | |
2221 | registered file) that you can treat as a unit. One important kind of | |
2222 | snapshot is a @dfn{release}, a (theoretically) stable version of the | |
2223 | system that is ready for distribution to users. | |
2224 | ||
2225 | @menu | |
2226 | * Making Snapshots:: The snapshot facilities. | |
2227 | * Snapshot Caveats:: Things to be careful of when using snapshots. | |
2228 | @end menu | |
2229 | ||
2230 | @node Making Snapshots | |
2231 | @subsection Making and Using Snapshots | |
2232 | ||
2233 | There are two basic commands for snapshots; one makes a | |
2234 | snapshot with a given name, the other retrieves a named snapshot. | |
2235 | ||
2236 | @table @code | |
2237 | @kindex C-x v s | |
2238 | @findex vc-create-snapshot | |
2239 | @item C-x v s @var{name} @key{RET} | |
2240 | Define the last saved versions of every registered file in or under the | |
2241 | current directory as a snapshot named @var{name} | |
2242 | (@code{vc-create-snapshot}). | |
2243 | ||
2244 | @kindex C-x v r | |
2245 | @findex vc-retrieve-snapshot | |
2246 | @item C-x v r @var{name} @key{RET} | |
2247 | For all registered files at or below the current directory level, select | |
2248 | whatever versions correspond to the snapshot @var{name} | |
2249 | (@code{vc-retrieve-snapshot}). | |
2250 | ||
2251 | This command reports an error if any files are locked at or below the | |
2252 | current directory, without changing anything; this is to avoid | |
2253 | overwriting work in progress. | |
2254 | @end table | |
2255 | ||
2256 | A snapshot uses a very small amount of resources---just enough to record | |
2257 | the list of file names and which version belongs to the snapshot. Thus, | |
2258 | you need not hesitate to create snapshots whenever they are useful. | |
2259 | ||
2260 | You can give a snapshot name as an argument to @kbd{C-x v =} or | |
2261 | @kbd{C-x v ~} (@pxref{Old Versions,,,emacs, the Emacs Manual}). | |
2262 | Thus, you can use it to compare a snapshot against the current files, | |
2263 | or two snapshots against each other, or a snapshot against a named | |
2264 | version. | |
2265 | ||
2266 | @node Snapshot Caveats | |
2267 | @subsection Snapshot Caveats | |
2268 | ||
2269 | @cindex named configurations (RCS) | |
2270 | VC's snapshot facilities are modeled on RCS's named-configuration | |
2271 | support. They use RCS's native facilities for this, so | |
2272 | snapshots made using RCS through VC are visible even when you bypass VC. | |
2273 | ||
2274 | With CVS, Meta-CVS, and Subversion, VC also uses the native | |
2275 | mechanism provided by that back end to make snapshots and retrieve them | |
2276 | (@dfn{tags} for CVS and Meta-CVS, @dfn{copies} for Subversion). | |
2277 | ||
2278 | @c worded verbosely to avoid overfull hbox. | |
2279 | For SCCS, VC implements snapshots itself. The files it uses contain | |
2280 | name/file/version-number triples. These snapshots are visible only | |
2281 | through VC. | |
2282 | ||
2283 | There is no support for VC snapshots using GNU Arch yet. | |
2284 | ||
2285 | A snapshot is a set of checked-in versions. So make sure that all the | |
2286 | files are checked in and not locked when you make a snapshot. | |
2287 | ||
2288 | File renaming and deletion can create some difficulties with snapshots. | |
2289 | This is not a VC-specific problem, but a general design issue in version | |
2290 | control systems that no one has solved very well yet. | |
2291 | ||
2292 | If you rename a registered file, you need to rename its master along | |
2293 | with it (the command @code{vc-rename-file} does this automatically). If | |
2294 | you are using SCCS, you must also update the records of the snapshot, to | |
2295 | mention the file by its new name (@code{vc-rename-file} does this, | |
2296 | too). An old snapshot that refers to a master file that no longer | |
2297 | exists under the recorded name is invalid; VC can no longer retrieve | |
2298 | it. It would be beyond the scope of this manual to explain enough about | |
2299 | RCS and SCCS to explain how to update the snapshots by hand. | |
2300 | ||
2301 | Using @code{vc-rename-file} makes the snapshot remain valid for | |
2302 | retrieval, but it does not solve all problems. For example, some of the | |
2303 | files in your program probably refer to others by name. At the very | |
2304 | least, the makefile probably mentions the file that you renamed. If you | |
2305 | retrieve an old snapshot, the renamed file is retrieved under its new | |
2306 | name, which is not the name that the makefile expects. So the program | |
2307 | won't really work as retrieved. | |
2308 | ||
2309 | @node Miscellaneous VC | |
2310 | @section Miscellaneous Commands and Features of VC | |
2311 | ||
2312 | This section explains the less-frequently-used features of VC. | |
2313 | ||
2314 | @menu | |
2315 | * Change Logs and VC:: Generating a change log file from log entries. | |
2316 | * Renaming and VC:: A command to rename both the source and master | |
2317 | file correctly. | |
2318 | * Version Headers:: Inserting version control headers into working files. | |
2319 | @end menu | |
2320 | ||
2321 | @node Change Logs and VC | |
2322 | @subsection Change Logs and VC | |
2323 | ||
2324 | If you use RCS or CVS for a program and also maintain a change log | |
2325 | file for it (@pxref{Change Log,,,emacs, the Emacs Manual}), you | |
2326 | can generate change log entries automatically from the version control | |
2327 | log entries: | |
2328 | ||
2329 | @table @kbd | |
2330 | @item C-x v a | |
2331 | @kindex C-x v a | |
2332 | @findex vc-update-change-log | |
2333 | Visit the current directory's change log file and, for registered files | |
2334 | in that directory, create new entries for versions checked in since the | |
2335 | most recent entry in the change log file. | |
2336 | (@code{vc-update-change-log}). | |
2337 | ||
2338 | This command works with RCS or CVS only, not with any of the other | |
2339 | back ends. | |
2340 | ||
2341 | @item C-u C-x v a | |
2342 | As above, but only find entries for the current buffer's file. | |
2343 | ||
2344 | @item M-1 C-x v a | |
2345 | As above, but find entries for all the currently visited files that are | |
2346 | maintained with version control. This works only with RCS, and it puts | |
2347 | all entries in the log for the default directory, which may not be | |
2348 | appropriate. | |
2349 | @end table | |
2350 | ||
2351 | For example, suppose the first line of @file{ChangeLog} is dated | |
2352 | 1999-04-10, and that the only check-in since then was by Nathaniel | |
2353 | Bowditch to @file{rcs2log} on 1999-05-22 with log text @samp{Ignore log | |
2354 | messages that start with `#'.}. Then @kbd{C-x v a} visits | |
2355 | @file{ChangeLog} and inserts text like this: | |
2356 | ||
2357 | @iftex | |
2358 | @medbreak | |
2359 | @end iftex | |
2360 | @smallexample | |
2361 | @group | |
2362 | 1999-05-22 Nathaniel Bowditch <nat@@apn.org> | |
2363 | ||
2364 | * rcs2log: Ignore log messages that start with `#'. | |
2365 | @end group | |
2366 | @end smallexample | |
2367 | @iftex | |
2368 | @medbreak | |
2369 | @end iftex | |
2370 | ||
2371 | @noindent | |
2372 | You can then edit the new change log entry further as you wish. | |
2373 | ||
2374 | Some of the new change log entries may duplicate what's already in | |
2375 | ChangeLog. You will have to remove these duplicates by hand. | |
2376 | ||
2377 | Normally, the log entry for file @file{foo} is displayed as @samp{* | |
2378 | foo: @var{text of log entry}}. The @samp{:} after @file{foo} is omitted | |
2379 | if the text of the log entry starts with @w{@samp{(@var{functionname}): | |
2380 | }}. For example, if the log entry for @file{vc.el} is | |
2381 | @samp{(vc-do-command): Check call-process status.}, then the text in | |
2382 | @file{ChangeLog} looks like this: | |
2383 | ||
2384 | @iftex | |
2385 | @medbreak | |
2386 | @end iftex | |
2387 | @smallexample | |
2388 | @group | |
2389 | 1999-05-06 Nathaniel Bowditch <nat@@apn.org> | |
2390 | ||
2391 | * vc.el (vc-do-command): Check call-process status. | |
2392 | @end group | |
2393 | @end smallexample | |
2394 | @iftex | |
2395 | @medbreak | |
2396 | @end iftex | |
2397 | ||
2398 | When @kbd{C-x v a} adds several change log entries at once, it groups | |
2399 | related log entries together if they all are checked in by the same | |
2400 | author at nearly the same time. If the log entries for several such | |
2401 | files all have the same text, it coalesces them into a single entry. | |
2402 | For example, suppose the most recent check-ins have the following log | |
2403 | entries: | |
2404 | ||
2405 | @flushleft | |
2406 | @bullet{} For @file{vc.texinfo}: @samp{Fix expansion typos.} | |
2407 | @bullet{} For @file{vc.el}: @samp{Don't call expand-file-name.} | |
2408 | @bullet{} For @file{vc-hooks.el}: @samp{Don't call expand-file-name.} | |
2409 | @end flushleft | |
2410 | ||
2411 | @noindent | |
2412 | They appear like this in @file{ChangeLog}: | |
2413 | ||
2414 | @iftex | |
2415 | @medbreak | |
2416 | @end iftex | |
2417 | @smallexample | |
2418 | @group | |
2419 | 1999-04-01 Nathaniel Bowditch <nat@@apn.org> | |
2420 | ||
2421 | * vc.texinfo: Fix expansion typos. | |
2422 | ||
2423 | * vc.el, vc-hooks.el: Don't call expand-file-name. | |
2424 | @end group | |
2425 | @end smallexample | |
2426 | @iftex | |
2427 | @medbreak | |
2428 | @end iftex | |
2429 | ||
2430 | Normally, @kbd{C-x v a} separates log entries by a blank line, but you | |
2431 | can mark several related log entries to be clumped together (without an | |
2432 | intervening blank line) by starting the text of each related log entry | |
2433 | with a label of the form @w{@samp{@{@var{clumpname}@} }}. The label | |
2434 | itself is not copied to @file{ChangeLog}. For example, suppose the log | |
2435 | entries are: | |
2436 | ||
2437 | @flushleft | |
2438 | @bullet{} For @file{vc.texinfo}: @samp{@{expand@} Fix expansion typos.} | |
2439 | @bullet{} For @file{vc.el}: @samp{@{expand@} Don't call expand-file-name.} | |
2440 | @bullet{} For @file{vc-hooks.el}: @samp{@{expand@} Don't call expand-file-name.} | |
2441 | @end flushleft | |
2442 | ||
2443 | @noindent | |
2444 | Then the text in @file{ChangeLog} looks like this: | |
2445 | ||
2446 | @iftex | |
2447 | @medbreak | |
2448 | @end iftex | |
2449 | @smallexample | |
2450 | @group | |
2451 | 1999-04-01 Nathaniel Bowditch <nat@@apn.org> | |
2452 | ||
2453 | * vc.texinfo: Fix expansion typos. | |
2454 | * vc.el, vc-hooks.el: Don't call expand-file-name. | |
2455 | @end group | |
2456 | @end smallexample | |
2457 | @iftex | |
2458 | @medbreak | |
2459 | @end iftex | |
2460 | ||
2461 | A log entry whose text begins with @samp{#} is not copied to | |
2462 | @file{ChangeLog}. For example, if you merely fix some misspellings in | |
2463 | comments, you can log the change with an entry beginning with @samp{#} | |
2464 | to avoid putting such trivia into @file{ChangeLog}. | |
2465 | ||
2466 | @node Renaming and VC | |
2467 | @subsection Renaming VC Work Files and Master Files | |
2468 | ||
2469 | @findex vc-rename-file | |
2470 | When you rename a registered file, you must also rename its master | |
2471 | file correspondingly to get proper results. Use @code{vc-rename-file} | |
2472 | to rename the source file as you specify, and rename its master file | |
2473 | accordingly. It also updates any snapshots (@pxref{Snapshots}) that | |
2474 | mention the file, so that they use the new name; despite this, the | |
2475 | snapshot thus modified may not completely work (@pxref{Snapshot | |
2476 | Caveats}). | |
2477 | ||
2478 | Some back ends do not provide an explicit rename operation to their | |
2479 | repositories. After issuing @code{vc-rename-file}, use @kbd{C-x v v} | |
2480 | on the original and renamed buffers and provide the necessary edit | |
2481 | log. | |
2482 | ||
2483 | You cannot use @code{vc-rename-file} on a file that is locked by | |
2484 | someone else. | |
2485 | ||
2486 | @node Version Headers | |
2487 | @subsection Inserting Version Control Headers | |
2488 | ||
2489 | Sometimes it is convenient to put version identification strings | |
2490 | directly into working files. Certain special strings called | |
2491 | @dfn{version headers} are replaced in each successive version by the | |
2492 | number of that version, the name of the user who created it, and other | |
2493 | relevant information. All of the back ends that VC supports have such | |
2494 | a mechanism, except GNU Arch. | |
2495 | ||
2496 | VC does not normally use the information contained in these headers. | |
2497 | The exception is RCS---with RCS, version headers are sometimes more | |
2498 | reliable than the master file to determine which version of the file | |
2499 | you are editing. Note that in a multi-branch environment, version | |
2500 | headers are necessary to make VC behave correctly (@pxref{Multi-User | |
2501 | Branching,,,emacs, the Emacs Manual}). | |
2502 | ||
2503 | Searching for RCS version headers is controlled by the variable | |
2504 | @code{vc-consult-headers}. If it is non-@code{nil} (the default), | |
2505 | Emacs searches for headers to determine the version number you are | |
2506 | editing. Setting it to @code{nil} disables this feature. | |
2507 | ||
2508 | Note that although CVS uses the same kind of version headers as RCS | |
2509 | does, VC never searches for these headers if you are using CVS, | |
2510 | regardless of the above setting. | |
2511 | ||
2512 | @kindex C-x v h | |
2513 | @findex vc-insert-headers | |
2514 | You can use the @kbd{C-x v h} command (@code{vc-insert-headers}) to | |
2515 | insert a suitable header string. | |
2516 | ||
2517 | @table @kbd | |
2518 | @item C-x v h | |
2519 | Insert headers in a file for use with your version-control system. | |
2520 | @end table | |
2521 | ||
2522 | @vindex vc-@var{backend}-header | |
2523 | The default header string is @samp{@w{$}Id$} for RCS and | |
2524 | @samp{@w{%}W%} for SCCS. You can specify other headers to insert by | |
2525 | setting the variables @code{vc-@var{backend}-header} where | |
2526 | @var{backend} is @code{rcs} or @code{sccs}. | |
2527 | ||
2528 | Instead of a single string, you can specify a list of strings; then | |
2529 | each string in the list is inserted as a separate header on a line of | |
2530 | its own. | |
2531 | ||
2532 | It may be necessary to use apparently-superfluous backslashes when | |
2533 | writing the strings that you put in this variable. For instance, you | |
2534 | might write @code{"$Id\$"} rather than @code{"$Id@w{$}"}. The extra | |
2535 | backslash prevents the string constant from being interpreted as a | |
2536 | header, if the Emacs Lisp file containing it is maintained with | |
2537 | version control. | |
2538 | ||
2539 | @vindex vc-comment-alist | |
2540 | Each header is inserted surrounded by tabs, inside comment delimiters, | |
2541 | on a new line at point. Normally the ordinary comment | |
2542 | start and comment end strings of the current mode are used, but for | |
2543 | certain modes, there are special comment delimiters for this purpose; | |
2544 | the variable @code{vc-comment-alist} specifies them. Each element of | |
2545 | this list has the form @code{(@var{mode} @var{starter} @var{ender})}. | |
2546 | ||
2547 | @vindex vc-static-header-alist | |
2548 | The variable @code{vc-static-header-alist} specifies further strings | |
2549 | to add based on the name of the buffer. Its value should be a list of | |
2550 | elements of the form @code{(@var{regexp} . @var{format})}. Whenever | |
2551 | @var{regexp} matches the buffer name, @var{format} is inserted as part | |
2552 | of the header. A header line is inserted for each element that matches | |
2553 | the buffer name, and for each string specified by | |
2554 | @code{vc-@var{backend}-header}. The header line is made by processing the | |
2555 | string from @code{vc-@var{backend}-header} with the format taken from the | |
2556 | element. The default value for @code{vc-static-header-alist} is as follows: | |
2557 | ||
2558 | @example | |
2559 | @group | |
2560 | (("\\.c$" . | |
2561 | "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\ | |
2562 | #endif /* lint */\n")) | |
2563 | @end group | |
2564 | @end example | |
2565 | ||
2566 | @noindent | |
2567 | It specifies insertion of text of this form: | |
2568 | ||
2569 | @example | |
2570 | @group | |
2571 | ||
2572 | #ifndef lint | |
2573 | static char vcid[] = "@var{string}"; | |
2574 | #endif /* lint */ | |
2575 | @end group | |
2576 | @end example | |
2577 | ||
2578 | @noindent | |
2579 | Note that the text above starts with a blank line. | |
2580 | ||
2581 | If you use more than one version header in a file, put them close | |
2582 | together in the file. The mechanism in @code{revert-buffer} that | |
2583 | preserves markers may not handle markers positioned between two version | |
2584 | headers. | |
2585 | ||
2586 | @node Customizing VC | |
2587 | @section Customizing VC | |
2588 | ||
2589 | @vindex vc-handled-backends | |
2590 | The variable @code{vc-handled-backends} determines which version | |
2591 | control systems VC should handle. The default value is @code{(RCS CVS | |
2592 | SVN SCCS Arch MCVS)}, so it contains all six version systems that are | |
2593 | currently supported. If you want VC to ignore one or more of these | |
2594 | systems, exclude its name from the list. To disable VC entirely, set | |
2595 | this variable to @code{nil}. | |
2596 | ||
2597 | The order of systems in the list is significant: when you visit a file | |
2598 | registered in more than one system (@pxref{Local Version Control}), VC | |
2599 | uses the system that comes first in @code{vc-handled-backends} by | |
2600 | default. The order is also significant when you register a file for | |
2601 | the first time, @pxref{Registering,,,emacs, the Emacs Manual} for | |
2602 | details. | |
2603 | ||
2604 | @menu | |
2605 | * General VC Options:: Options that apply to multiple back ends. | |
2606 | * RCS and SCCS:: Options for RCS and SCCS. | |
2607 | * CVS Options:: Options for CVS. | |
2608 | @end menu | |
2609 | ||
2610 | @node General VC Options | |
2611 | @subsection General Options | |
2612 | ||
2613 | @vindex vc-make-backup-files | |
2614 | Emacs normally does not save backup files for source files that are | |
2615 | maintained with version control. If you want to make backup files even | |
2616 | for files that use version control, set the variable | |
2617 | @code{vc-make-backup-files} to a non-@code{nil} value. | |
2618 | ||
2619 | @vindex vc-keep-workfiles | |
2620 | Normally the work file exists all the time, whether it is locked or | |
2621 | not. If you set @code{vc-keep-workfiles} to @code{nil}, then checking | |
2622 | in a new version with @kbd{C-x v v} deletes the work file; but any | |
2623 | attempt to visit the file with Emacs creates it again. (With CVS, work | |
2624 | files are always kept.) | |
2625 | ||
2626 | @vindex vc-follow-symlinks | |
2627 | Editing a version-controlled file through a symbolic link can be | |
2628 | dangerous. It bypasses the version control system---you can edit the | |
2629 | file without locking it, and fail to check your changes in. Also, | |
2630 | your changes might overwrite those of another user. To protect against | |
2631 | this, VC checks each symbolic link that you visit, to see if it points | |
2632 | to a file under version control. | |
2633 | ||
2634 | The variable @code{vc-follow-symlinks} controls what to do when a | |
2635 | symbolic link points to a version-controlled file. If it is @code{nil}, | |
2636 | VC only displays a warning message. If it is @code{t}, VC automatically | |
2637 | follows the link, and visits the real file instead, telling you about | |
2638 | this in the echo area. If the value is @code{ask} (the default), VC | |
2639 | asks you each time whether to follow the link. | |
2640 | ||
2641 | @vindex vc-suppress-confirm | |
2642 | If @code{vc-suppress-confirm} is non-@code{nil}, then @kbd{C-x v v} | |
2643 | and @kbd{C-x v i} can save the current buffer without asking, and | |
2644 | @kbd{C-x v u} also operates without asking for confirmation. (This | |
2645 | variable does not affect @kbd{C-x v c}; that operation is so drastic | |
2646 | that it should always ask for confirmation.) | |
2647 | ||
2648 | @vindex vc-command-messages | |
2649 | VC mode does much of its work by running the shell commands for RCS, | |
2650 | CVS and SCCS. If @code{vc-command-messages} is non-@code{nil}, VC | |
2651 | displays messages to indicate which shell commands it runs, and | |
2652 | additional messages when the commands finish. | |
2653 | ||
2654 | @vindex vc-path | |
2655 | You can specify additional directories to search for version control | |
2656 | programs by setting the variable @code{vc-path}. These directories | |
2657 | are searched before the usual search path. It is rarely necessary to | |
2658 | set this variable, because VC normally finds the proper files | |
2659 | automatically. | |
2660 | ||
2661 | @node RCS and SCCS | |
2662 | @subsection Options for RCS and SCCS | |
2663 | ||
2664 | @cindex non-strict locking (RCS) | |
2665 | @cindex locking, non-strict (RCS) | |
2666 | By default, RCS uses locking to coordinate the activities of several | |
2667 | users, but there is a mode called @dfn{non-strict locking} in which | |
2668 | you can check-in changes without locking the file first. Use | |
2669 | @samp{rcs -U} to switch to non-strict locking for a particular file, | |
2670 | see the @code{rcs} manual page for details. | |
2671 | ||
2672 | When deducing the version control state of an RCS file, VC first | |
2673 | looks for an RCS version header string in the file (@pxref{Version | |
2674 | Headers}). If there is no header string, VC normally looks at the | |
2675 | file permissions of the work file; this is fast. But there might be | |
2676 | situations when the file permissions cannot be trusted. In this case | |
2677 | the master file has to be consulted, which is rather expensive. Also | |
2678 | the master file can only tell you @emph{if} there's any lock on the | |
2679 | file, but not whether your work file really contains that locked | |
2680 | version. | |
2681 | ||
2682 | @vindex vc-consult-headers | |
2683 | You can tell VC not to use version headers to determine the file | |
2684 | status by setting @code{vc-consult-headers} to @code{nil}. VC then | |
2685 | always uses the file permissions (if it is supposed to trust them), or | |
2686 | else checks the master file. | |
2687 | ||
2688 | @vindex vc-mistrust-permissions | |
2689 | You can specify the criterion for whether to trust the file | |
2690 | permissions by setting the variable @code{vc-mistrust-permissions}. | |
2691 | Its value can be @code{t} (always mistrust the file permissions and | |
2692 | check the master file), @code{nil} (always trust the file | |
2693 | permissions), or a function of one argument which makes the decision. | |
2694 | The argument is the directory name of the @file{RCS} subdirectory. A | |
2695 | non-@code{nil} value from the function says to mistrust the file | |
2696 | permissions. If you find that the file permissions of work files are | |
2697 | changed erroneously, set @code{vc-mistrust-permissions} to @code{t}. | |
2698 | Then VC always checks the master file to determine the file's status. | |
2699 | ||
2700 | VC determines the version control state of files under SCCS much as | |
2701 | with RCS. It does not consider SCCS version headers, though. Thus, | |
2702 | the variable @code{vc-mistrust-permissions} affects SCCS use, but | |
2703 | @code{vc-consult-headers} does not. | |
2704 | ||
2705 | @node CVS Options | |
2706 | @subsection Options specific for CVS | |
2707 | ||
2708 | @cindex locking (CVS) | |
2709 | By default, CVS does not use locking to coordinate the activities of | |
2710 | several users; anyone can change a work file at any time. However, | |
2711 | there are ways to restrict this, resulting in behavior that resembles | |
2712 | locking. | |
2713 | ||
2714 | @cindex CVSREAD environment variable (CVS) | |
2715 | For one thing, you can set the @env{CVSREAD} environment variable | |
2716 | (the value you use makes no difference). If this variable is defined, | |
2717 | CVS makes your work files read-only by default. In Emacs, you must | |
2718 | type @kbd{C-x v v} to make the file writable, so that editing works | |
2719 | in fact similar as if locking was used. Note however, that no actual | |
2720 | locking is performed, so several users can make their files writable | |
2721 | at the same time. When setting @env{CVSREAD} for the first time, make | |
2722 | sure to check out all your modules anew, so that the file protections | |
2723 | are set correctly. | |
2724 | ||
2725 | @cindex cvs watch feature | |
2726 | @cindex watching files (CVS) | |
2727 | Another way to achieve something similar to locking is to use the | |
2728 | @dfn{watch} feature of CVS. If a file is being watched, CVS makes it | |
2729 | read-only by default, and you must also use @kbd{C-x v v} in Emacs to | |
2730 | make it writable. VC calls @code{cvs edit} to make the file writable, | |
2731 | and CVS takes care to notify other developers of the fact that you | |
2732 | intend to change the file. See the CVS documentation for details on | |
2733 | using the watch feature. | |
2734 | ||
2735 | @vindex vc-stay-local | |
2736 | @vindex vc-cvs-stay-local | |
2737 | @cindex remote repositories (CVS) | |
2738 | When a file's repository is on a remote machine, VC tries to keep | |
2739 | network interactions to a minimum. This is controlled by the variable | |
2740 | @code{vc-cvs-stay-local}. There is another variable, | |
2741 | @code{vc-stay-local}, which enables the feature also for other back | |
2742 | ends that support it, including CVS. In the following, we will talk | |
2743 | only about @code{vc-cvs-stay-local}, but everything applies to | |
2744 | @code{vc-stay-local} as well. | |
2745 | ||
2746 | If @code{vc-cvs-stay-local} is @code{t} (the default), then VC uses | |
2747 | only the entry in the local CVS subdirectory to determine the file's | |
2748 | state (and possibly information returned by previous CVS commands). | |
2749 | One consequence of this is that when you have modified a file, and | |
2750 | somebody else has already checked in other changes to the file, you | |
2751 | are not notified of it until you actually try to commit. (But you can | |
2752 | try to pick up any recent changes from the repository first, using | |
2753 | @kbd{C-x v m @key{RET}}, @pxref{Merging,,,emacs, the Emacs Manual}). | |
2754 | ||
2755 | When @code{vc-cvs-stay-local} is @code{t}, VC also makes local | |
2756 | version backups, so that simple diff and revert operations are | |
2757 | completely local (@pxref{Version Backups}). | |
2758 | ||
2759 | On the other hand, if you set @code{vc-cvs-stay-local} to @code{nil}, | |
2760 | then VC queries the remote repository @emph{before} it decides what to | |
2761 | do in @code{vc-next-action} (@kbd{C-x v v}), just as it does for local | |
2762 | repositories. It also does not make any version backups. | |
2763 | ||
2764 | You can also set @code{vc-cvs-stay-local} to a regular expression | |
2765 | that is matched against the repository host name; VC then stays local | |
2766 | only for repositories from hosts that match the pattern. | |
2767 | ||
2768 | @vindex vc-cvs-global-switches | |
2769 | You can specify additional command line options to pass to all CVS | |
2770 | operations in the variable @code{vc-cvs-global-switches}. These | |
2771 | switches are inserted immediately after the @code{cvs} command, before | |
2772 | the name of the operation to invoke. | |
2773 | ||
2774 | ||
e0fc8fa2 CY |
2775 | @node Fortran |
2776 | @chapter Fortran Mode | |
2777 | @cindex Fortran mode | |
2778 | @cindex mode, Fortran | |
2779 | ||
2780 | Fortran mode provides special motion commands for Fortran statements | |
2781 | and subprograms, and indentation commands that understand Fortran | |
2782 | conventions of nesting, line numbers and continuation statements. | |
2783 | Fortran mode has support for Auto Fill mode that breaks long lines into | |
2784 | proper Fortran continuation lines. | |
2785 | ||
2786 | Special commands for comments are provided because Fortran comments | |
2787 | are unlike those of other languages. Built-in abbrevs optionally save | |
2788 | typing when you insert Fortran keywords. | |
2789 | ||
2790 | Use @kbd{M-x fortran-mode} to switch to this major mode. This | |
2791 | command runs the hook @code{fortran-mode-hook}. @xref{Hooks,,, emacs, | |
2792 | the Emacs Manual}. | |
2793 | ||
2794 | @cindex Fortran77 and Fortran90 | |
2795 | @findex f90-mode | |
2796 | @findex fortran-mode | |
2797 | Fortran mode is meant for editing Fortran77 ``fixed format'' (and also | |
2798 | ``tab format'') source code. For editing the modern Fortran90 or | |
2799 | Fortran95 ``free format'' source code, use F90 mode (@code{f90-mode}). | |
2800 | Emacs normally uses Fortran mode for files with extension @samp{.f}, | |
2801 | @samp{.F} or @samp{.for}, and F90 mode for the extension @samp{.f90} and | |
2802 | @samp{.f95}. GNU Fortran supports both kinds of format. | |
2803 | ||
2804 | @menu | |
2805 | * Motion: Fortran Motion. Moving point by statements or subprograms. | |
2806 | * Indent: Fortran Indent. Indentation commands for Fortran. | |
2807 | * Comments: Fortran Comments. Inserting and aligning comments. | |
2808 | * Autofill: Fortran Autofill. Auto fill support for Fortran. | |
2809 | * Columns: Fortran Columns. Measuring columns for valid Fortran. | |
2810 | * Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords. | |
2811 | @end menu | |
2812 | ||
2813 | @node Fortran Motion | |
2814 | @section Motion Commands | |
2815 | ||
2816 | In addition to the normal commands for moving by and operating on | |
2817 | ``defuns'' (Fortran subprograms---functions and subroutines, as well as | |
2818 | modules for F90 mode), Fortran mode provides special commands to move by | |
2819 | statements and other program units. | |
2820 | ||
2821 | @table @kbd | |
2822 | @kindex C-c C-n @r{(Fortran mode)} | |
2823 | @findex fortran-next-statement | |
2824 | @findex f90-next-statement | |
2825 | @item C-c C-n | |
2826 | Move to the beginning of the next statement | |
2827 | (@code{fortran-next-statement}/@code{f90-next-statement}). | |
2828 | ||
2829 | @kindex C-c C-p @r{(Fortran mode)} | |
2830 | @findex fortran-previous-statement | |
2831 | @findex f90-previous-statement | |
2832 | @item C-c C-p | |
2833 | Move to the beginning of the previous statement | |
2834 | (@code{fortran-previous-statement}/@code{f90-previous-statement}). | |
2835 | If there is no previous statement (i.e. if called from the first | |
2836 | statement in the buffer), move to the start of the buffer. | |
2837 | ||
2838 | @kindex C-c C-e @r{(F90 mode)} | |
2839 | @findex f90-next-block | |
2840 | @item C-c C-e | |
2841 | Move point forward to the start of the next code block | |
2842 | (@code{f90-next-block}). A code block is a subroutine, | |
2843 | @code{if}--@code{endif} statement, and so forth. This command exists | |
2844 | for F90 mode only, not Fortran mode. With a numeric argument, this | |
2845 | moves forward that many blocks. | |
2846 | ||
2847 | @kindex C-c C-a @r{(F90 mode)} | |
2848 | @findex f90-previous-block | |
2849 | @item C-c C-a | |
2850 | Move point backward to the previous code block | |
2851 | (@code{f90-previous-block}). This is like @code{f90-next-block}, but | |
2852 | moves backwards. | |
2853 | ||
2854 | @kindex C-M-n @r{(Fortran mode)} | |
2855 | @findex fortran-end-of-block | |
2856 | @findex f90-end-of-block | |
2857 | @item C-M-n | |
2858 | Move to the end of the current code block | |
2859 | (@code{fortran-end-of-block}/@code{f90-end-of-block}). With a numeric | |
2860 | agument, move forward that number of blocks. The mark is set before | |
2861 | moving point. The F90 mode version of this command checks for | |
2862 | consistency of block types and labels (if present), but it does not | |
2863 | check the outermost block since that may be incomplete. | |
2864 | ||
2865 | @kindex C-M-p @r{(Fortran mode)} | |
2866 | @findex fortran-beginning-of-block | |
2867 | @findex f90-beginning-of-block | |
2868 | @item C-M-p | |
2869 | Move to the start of the current code block | |
2870 | (@code{fortran-beginning-of-block}/@code{f90-beginning-of-block}). This | |
2871 | is like @code{fortran-end-of-block}, but moves backwards. | |
2872 | @end table | |
2873 | ||
2874 | @node Fortran Indent | |
2875 | @section Fortran Indentation | |
2876 | ||
2877 | Special commands and features are needed for indenting Fortran code in | |
2878 | order to make sure various syntactic entities (line numbers, comment line | |
2879 | indicators and continuation line flags) appear in the columns that are | |
2880 | required for standard, fixed (or tab) format Fortran. | |
2881 | ||
2882 | @menu | |
2883 | * Commands: ForIndent Commands. Commands for indenting and filling Fortran. | |
2884 | * Contline: ForIndent Cont. How continuation lines indent. | |
2885 | * Numbers: ForIndent Num. How line numbers auto-indent. | |
2886 | * Conv: ForIndent Conv. Conventions you must obey to avoid trouble. | |
2887 | * Vars: ForIndent Vars. Variables controlling Fortran indent style. | |
2888 | @end menu | |
2889 | ||
2890 | @node ForIndent Commands | |
2891 | @subsection Fortran Indentation and Filling Commands | |
2892 | ||
2893 | @table @kbd | |
2894 | @item C-M-j | |
2895 | Break the current line at point and set up a continuation line | |
2896 | (@code{fortran-split-line}). | |
2897 | @item M-^ | |
2898 | Join this line to the previous line (@code{fortran-join-line}). | |
2899 | @item C-M-q | |
2900 | Indent all the lines of the subprogram point is in | |
2901 | (@code{fortran-indent-subprogram}). | |
2902 | @item M-q | |
2903 | Fill a comment block or statement. | |
2904 | @end table | |
2905 | ||
2906 | @kindex C-M-q @r{(Fortran mode)} | |
2907 | @findex fortran-indent-subprogram | |
2908 | The key @kbd{C-M-q} runs @code{fortran-indent-subprogram}, a command | |
2909 | to reindent all the lines of the Fortran subprogram (function or | |
2910 | subroutine) containing point. | |
2911 | ||
2912 | @kindex C-M-j @r{(Fortran mode)} | |
2913 | @findex fortran-split-line | |
2914 | The key @kbd{C-M-j} runs @code{fortran-split-line}, which splits | |
2915 | a line in the appropriate fashion for Fortran. In a non-comment line, | |
2916 | the second half becomes a continuation line and is indented | |
2917 | accordingly. In a comment line, both halves become separate comment | |
2918 | lines. | |
2919 | ||
2920 | @kindex M-^ @r{(Fortran mode)} | |
2921 | @kindex C-c C-d @r{(Fortran mode)} | |
2922 | @findex fortran-join-line | |
2923 | @kbd{M-^} or @kbd{C-c C-d} runs the command @code{fortran-join-line}, | |
2924 | which joins a continuation line back to the previous line, roughly as | |
2925 | the inverse of @code{fortran-split-line}. The point must be on a | |
2926 | continuation line when this command is invoked. | |
2927 | ||
2928 | @kindex M-q @r{(Fortran mode)} | |
2929 | @kbd{M-q} in Fortran mode fills the comment block or statement that | |
2930 | point is in. This removes any excess statement continuations. | |
2931 | ||
2932 | @node ForIndent Cont | |
2933 | @subsection Continuation Lines | |
2934 | @cindex Fortran continuation lines | |
2935 | ||
2936 | @vindex fortran-continuation-string | |
2937 | Most Fortran77 compilers allow two ways of writing continuation lines. | |
2938 | If the first non-space character on a line is in column 5, then that | |
2939 | line is a continuation of the previous line. We call this @dfn{fixed | |
2940 | format}. (In GNU Emacs we always count columns from 0; but note that | |
2941 | the Fortran standard counts from 1.) The variable | |
2942 | @code{fortran-continuation-string} specifies what character to put in | |
2943 | column 5. A line that starts with a tab character followed by any digit | |
2944 | except @samp{0} is also a continuation line. We call this style of | |
2945 | continuation @dfn{tab format}. (Fortran90 introduced ``free format'', | |
2946 | with another style of continuation lines). | |
2947 | ||
2948 | @vindex indent-tabs-mode @r{(Fortran mode)} | |
2949 | @vindex fortran-analyze-depth | |
2950 | @vindex fortran-tab-mode-default | |
2951 | Fortran mode can use either style of continuation line. When you | |
2952 | enter Fortran mode, it tries to deduce the proper continuation style | |
2953 | automatically from the buffer contents. It does this by scanning up to | |
2954 | @code{fortran-analyze-depth} (default 100) lines from the start of the | |
2955 | buffer. The first line that begins with either a tab character or six | |
2956 | spaces determines the choice. If the scan fails (for example, if the | |
2957 | buffer is new and therefore empty), the value of | |
2958 | @code{fortran-tab-mode-default} (@code{nil} for fixed format, and | |
2959 | non-@code{nil} for tab format) is used. @samp{/t} in the mode line | |
2960 | indicates tab format is selected. Fortran mode sets the value of | |
2961 | @code{indent-tabs-mode} accordingly. | |
2962 | ||
2963 | If the text on a line starts with the Fortran continuation marker | |
2964 | @samp{$}, or if it begins with any non-whitespace character in column | |
2965 | 5, Fortran mode treats it as a continuation line. When you indent a | |
2966 | continuation line with @key{TAB}, it converts the line to the current | |
2967 | continuation style. When you split a Fortran statement with | |
2968 | @kbd{C-M-j}, the continuation marker on the newline is created according | |
2969 | to the continuation style. | |
2970 | ||
2971 | The setting of continuation style affects several other aspects of | |
2972 | editing in Fortran mode. In fixed format mode, the minimum column | |
2973 | number for the body of a statement is 6. Lines inside of Fortran | |
2974 | blocks that are indented to larger column numbers always use only the | |
2975 | space character for whitespace. In tab format mode, the minimum | |
2976 | column number for the statement body is 8, and the whitespace before | |
2977 | column 8 must always consist of one tab character. | |
2978 | ||
2979 | @node ForIndent Num | |
2980 | @subsection Line Numbers | |
2981 | ||
2982 | If a number is the first non-whitespace in the line, Fortran | |
2983 | indentation assumes it is a line number and moves it to columns 0 | |
2984 | through 4. (Columns always count from 0 in GNU Emacs.) | |
2985 | ||
2986 | @vindex fortran-line-number-indent | |
2987 | Line numbers of four digits or less are normally indented one space. | |
2988 | The variable @code{fortran-line-number-indent} controls this; it | |
2989 | specifies the maximum indentation a line number can have. The default | |
2990 | value of the variable is 1. Fortran mode tries to prevent line number | |
2991 | digits passing column 4, reducing the indentation below the specified | |
2992 | maximum if necessary. If @code{fortran-line-number-indent} has the | |
2993 | value 5, line numbers are right-justified to end in column 4. | |
2994 | ||
2995 | @vindex fortran-electric-line-number | |
2996 | Simply inserting a line number is enough to indent it according to | |
2997 | these rules. As each digit is inserted, the indentation is recomputed. | |
2998 | To turn off this feature, set the variable | |
2999 | @code{fortran-electric-line-number} to @code{nil}. | |
3000 | ||
3001 | ||
3002 | @node ForIndent Conv | |
3003 | @subsection Syntactic Conventions | |
3004 | ||
3005 | Fortran mode assumes that you follow certain conventions that simplify | |
3006 | the task of understanding a Fortran program well enough to indent it | |
3007 | properly: | |
3008 | ||
3009 | @itemize @bullet | |
3010 | @item | |
3011 | Two nested @samp{do} loops never share a @samp{continue} statement. | |
3012 | ||
3013 | @item | |
3014 | Fortran keywords such as @samp{if}, @samp{else}, @samp{then}, @samp{do} | |
3015 | and others are written without embedded whitespace or line breaks. | |
3016 | ||
3017 | Fortran compilers generally ignore whitespace outside of string | |
3018 | constants, but Fortran mode does not recognize these keywords if they | |
3019 | are not contiguous. Constructs such as @samp{else if} or @samp{end do} | |
3020 | are acceptable, but the second word should be on the same line as the | |
3021 | first and not on a continuation line. | |
3022 | @end itemize | |
3023 | ||
3024 | @noindent | |
3025 | If you fail to follow these conventions, the indentation commands may | |
3026 | indent some lines unaesthetically. However, a correct Fortran program | |
3027 | retains its meaning when reindented even if the conventions are not | |
3028 | followed. | |
3029 | ||
3030 | @node ForIndent Vars | |
3031 | @subsection Variables for Fortran Indentation | |
3032 | ||
3033 | @vindex fortran-do-indent | |
3034 | @vindex fortran-if-indent | |
3035 | @vindex fortran-structure-indent | |
3036 | @vindex fortran-continuation-indent | |
3037 | @vindex fortran-check-all-num@dots{} | |
3038 | @vindex fortran-minimum-statement-indent@dots{} | |
3039 | Several additional variables control how Fortran indentation works: | |
3040 | ||
3041 | @table @code | |
3042 | @item fortran-do-indent | |
3043 | Extra indentation within each level of @samp{do} statement (default 3). | |
3044 | ||
3045 | @item fortran-if-indent | |
3046 | Extra indentation within each level of @samp{if}, @samp{select case}, or | |
3047 | @samp{where} statements (default 3). | |
3048 | ||
3049 | @item fortran-structure-indent | |
3050 | Extra indentation within each level of @samp{structure}, @samp{union}, | |
3051 | @samp{map}, or @samp{interface} statements (default 3). | |
3052 | ||
3053 | @item fortran-continuation-indent | |
3054 | Extra indentation for bodies of continuation lines (default 5). | |
3055 | ||
3056 | @item fortran-check-all-num-for-matching-do | |
3057 | In Fortran77, a numbered @samp{do} statement is ended by any statement | |
3058 | with a matching line number. It is common (but not compulsory) to use a | |
3059 | @samp{continue} statement for this purpose. If this variable has a | |
3060 | non-@code{nil} value, indenting any numbered statement must check for a | |
3061 | @samp{do} that ends there. If you always end @samp{do} statements with | |
3062 | a @samp{continue} line (or if you use the more modern @samp{enddo}), | |
3063 | then you can speed up indentation by setting this variable to | |
3064 | @code{nil}. The default is @code{nil}. | |
3065 | ||
3066 | @item fortran-blink-matching-if | |
3067 | If this is @code{t}, indenting an @samp{endif} (or @samp{enddo} | |
3068 | statement moves the cursor momentarily to the matching @samp{if} (or | |
3069 | @samp{do}) statement to show where it is. The default is @code{nil}. | |
3070 | ||
3071 | @item fortran-minimum-statement-indent-fixed | |
3072 | Minimum indentation for Fortran statements when using fixed format | |
3073 | continuation line style. Statement bodies are never indented less than | |
3074 | this much. The default is 6. | |
3075 | ||
3076 | @item fortran-minimum-statement-indent-tab | |
3077 | Minimum indentation for Fortran statements for tab format continuation line | |
3078 | style. Statement bodies are never indented less than this much. The | |
3079 | default is 8. | |
3080 | @end table | |
3081 | ||
3082 | The variables controlling the indentation of comments are described in | |
3083 | the following section. | |
3084 | ||
3085 | @node Fortran Comments | |
3086 | @section Fortran Comments | |
3087 | ||
3088 | The usual Emacs comment commands assume that a comment can follow a | |
3089 | line of code. In Fortran77, the standard comment syntax requires an | |
3090 | entire line to be just a comment. Therefore, Fortran mode replaces the | |
3091 | standard Emacs comment commands and defines some new variables. | |
3092 | ||
3093 | @vindex fortran-comment-line-start | |
3094 | Fortran mode can also handle the Fortran90 comment syntax where comments | |
3095 | start with @samp{!} and can follow other text. Because only some Fortran77 | |
3096 | compilers accept this syntax, Fortran mode will not insert such comments | |
3097 | unless you have said in advance to do so. To do this, set the variable | |
3098 | @code{fortran-comment-line-start} to @samp{"!"}. | |
3099 | ||
3100 | @table @kbd | |
3101 | @item M-; | |
3102 | Align comment or insert new comment (@code{fortran-indent-comment}). | |
3103 | ||
3104 | @item C-x ; | |
3105 | Applies to nonstandard @samp{!} comments only. | |
3106 | ||
3107 | @item C-c ; | |
3108 | Turn all lines of the region into comments, or (with argument) turn them back | |
3109 | into real code (@code{fortran-comment-region}). | |
3110 | @end table | |
3111 | ||
3112 | @findex fortran-indent-comment | |
3113 | @kbd{M-;} in Fortran mode is redefined as the command | |
3114 | @code{fortran-indent-comment}. Like the usual @kbd{M-;} command, this | |
3115 | recognizes any kind of existing comment and aligns its text appropriately; | |
3116 | if there is no existing comment, a comment is inserted and aligned. But | |
3117 | inserting and aligning comments are not the same in Fortran mode as in | |
3118 | other modes. | |
3119 | ||
3120 | When a new comment must be inserted, if the current line is blank, a | |
3121 | full-line comment is inserted. On a non-blank line, a nonstandard @samp{!} | |
3122 | comment is inserted if you have said you want to use them. Otherwise a | |
3123 | full-line comment is inserted on a new line before the current line. | |
3124 | ||
3125 | Nonstandard @samp{!} comments are aligned like comments in other | |
3126 | languages, but full-line comments are different. In a standard full-line | |
3127 | comment, the comment delimiter itself must always appear in column zero. | |
3128 | What can be aligned is the text within the comment. You can choose from | |
3129 | three styles of alignment by setting the variable | |
3130 | @code{fortran-comment-indent-style} to one of these values: | |
3131 | ||
3132 | @vindex fortran-comment-indent-style | |
3133 | @vindex fortran-comment-line-extra-indent | |
3134 | @table @code | |
3135 | @item fixed | |
3136 | Align the text at a fixed column, which is the sum of | |
3137 | @code{fortran-comment-line-extra-indent} and the minimum statement | |
3138 | indentation. This is the default. | |
3139 | ||
3140 | The minimum statement indentation is | |
3141 | @code{fortran-minimum-statement-indent-fixed} for fixed format | |
3142 | continuation line style and @code{fortran-minimum-statement-indent-tab} | |
3143 | for tab format style. | |
3144 | ||
3145 | @item relative | |
3146 | Align the text as if it were a line of code, but with an additional | |
3147 | @code{fortran-comment-line-extra-indent} columns of indentation. | |
3148 | ||
3149 | @item nil | |
3150 | Don't move text in full-line comments automatically. | |
3151 | @end table | |
3152 | ||
3153 | @vindex fortran-comment-indent-char | |
3154 | In addition, you can specify the character to be used to indent within | |
3155 | full-line comments by setting the variable | |
3156 | @code{fortran-comment-indent-char} to the single-character string you want | |
3157 | to use. | |
3158 | ||
3159 | @vindex fortran-directive-re | |
3160 | Compiler directive lines, or preprocessor lines, have much the same | |
3161 | appearance as comment lines. It is important, though, that such lines | |
3162 | never be indented at all, no matter what the value of | |
3163 | @code{fortran-comment-indent-style}. The variable | |
3164 | @code{fortran-directive-re} is a regular expression that specifies which | |
3165 | lines are directives. Matching lines are never indented, and receive | |
3166 | distinctive font-locking. | |
3167 | ||
3168 | The normal Emacs comment command @kbd{C-x ;} has not been redefined. If | |
3169 | you use @samp{!} comments, this command can be used with them. Otherwise | |
3170 | it is useless in Fortran mode. | |
3171 | ||
3172 | @kindex C-c ; @r{(Fortran mode)} | |
3173 | @findex fortran-comment-region | |
3174 | @vindex fortran-comment-region | |
3175 | The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the | |
3176 | lines of the region into comments by inserting the string @samp{C$$$} at | |
3177 | the front of each one. With a numeric argument, it turns the region | |
3178 | back into live code by deleting @samp{C$$$} from the front of each line | |
3179 | in it. The string used for these comments can be controlled by setting | |
3180 | the variable @code{fortran-comment-region}. Note that here we have an | |
3181 | example of a command and a variable with the same name; these two uses | |
3182 | of the name never conflict because in Lisp and in Emacs it is always | |
3183 | clear from the context which one is meant. | |
3184 | ||
3185 | @node Fortran Autofill | |
3186 | @section Auto Fill in Fortran Mode | |
3187 | ||
3188 | Fortran mode has specialized support for Auto Fill mode, which is a | |
3189 | minor mode that automatically splits statements as you insert them | |
3190 | when they become too wide. Splitting a statement involves making | |
3191 | continuation lines using @code{fortran-continuation-string} | |
3192 | (@pxref{ForIndent Cont}). This splitting happens when you type | |
3193 | @key{SPC}, @key{RET}, or @key{TAB}, and also in the Fortran | |
3194 | indentation commands. You activate Auto Fill in Fortran mode in the | |
3195 | normal way. @xref{Auto Fill,,, emacs, the Emacs Manual}. | |
3196 | ||
3197 | @vindex fortran-break-before-delimiters | |
3198 | Auto Fill breaks lines at spaces or delimiters when the lines get | |
3199 | longer than the desired width (the value of @code{fill-column}). The | |
3200 | delimiters (besides whitespace) that Auto Fill can break at are | |
3201 | @samp{+}, @samp{-}, @samp{/}, @samp{*}, @samp{=}, @samp{<}, @samp{>}, | |
3202 | and @samp{,}. The line break comes after the delimiter if the | |
3203 | variable @code{fortran-break-before-delimiters} is @code{nil}. | |
3204 | Otherwise (and by default), the break comes before the delimiter. | |
3205 | ||
3206 | To enable Auto Fill in all Fortran buffers, add | |
3207 | @code{turn-on-auto-fill} to @code{fortran-mode-hook}. @xref{Hooks,,, | |
3208 | emacs, the Emacs Manual}. | |
3209 | ||
3210 | @node Fortran Columns | |
3211 | @section Checking Columns in Fortran | |
3212 | ||
3213 | @table @kbd | |
3214 | @item C-c C-r | |
3215 | Display a ``column ruler'' momentarily above the current line | |
3216 | (@code{fortran-column-ruler}). | |
3217 | @item C-c C-w | |
3218 | Split the current window horizontally temporarily so that it is 72 | |
3219 | columns wide (@code{fortran-window-create-momentarily}). This may | |
3220 | help you avoid making lines longer than the 72-character limit that | |
3221 | some Fortran compilers impose. | |
3222 | @item C-u C-c C-w | |
3223 | Split the current window horizontally so that it is 72 columns wide | |
3224 | (@code{fortran-window-create}). You can then continue editing. | |
3225 | @item M-x fortran-strip-sequence-nos | |
3226 | Delete all text in column 72 and beyond. | |
3227 | @end table | |
3228 | ||
3229 | @kindex C-c C-r @r{(Fortran mode)} | |
3230 | @findex fortran-column-ruler | |
3231 | The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column | |
3232 | ruler momentarily above the current line. The comment ruler is two lines | |
3233 | of text that show you the locations of columns with special significance in | |
3234 | Fortran programs. Square brackets show the limits of the columns for line | |
3235 | numbers, and curly brackets show the limits of the columns for the | |
3236 | statement body. Column numbers appear above them. | |
3237 | ||
3238 | Note that the column numbers count from zero, as always in GNU Emacs. | |
3239 | As a result, the numbers may be one less than those you are familiar | |
3240 | with; but the positions they indicate in the line are standard for | |
3241 | Fortran. | |
3242 | ||
3243 | @vindex fortran-column-ruler-fixed | |
3244 | @vindex fortran-column-ruler-tabs | |
3245 | The text used to display the column ruler depends on the value of the | |
3246 | variable @code{indent-tabs-mode}. If @code{indent-tabs-mode} is | |
3247 | @code{nil}, then the value of the variable | |
3248 | @code{fortran-column-ruler-fixed} is used as the column ruler. | |
3249 | Otherwise, the value of the variable @code{fortran-column-ruler-tab} is | |
3250 | displayed. By changing these variables, you can change the column ruler | |
3251 | display. | |
3252 | ||
3253 | @kindex C-c C-w @r{(Fortran mode)} | |
3254 | @findex fortran-window-create-momentarily | |
3255 | @kbd{C-c C-w} (@code{fortran-window-create-momentarily}) temporarily | |
3256 | splits the current window horizontally, making a window 72 columns | |
3257 | wide, so you can see any lines that are too long. Type a space to | |
3258 | restore the normal width. | |
3259 | ||
3260 | @kindex C-u C-c C-w @r{(Fortran mode)} | |
3261 | @findex fortran-window-create | |
3262 | You can also split the window horizontally and continue editing with | |
3263 | the split in place. To do this, use @kbd{C-u C-c C-w} (@code{M-x | |
3264 | fortran-window-create}). By editing in this window you can | |
3265 | immediately see when you make a line too wide to be correct Fortran. | |
3266 | ||
3267 | @findex fortran-strip-sequence-nos | |
3268 | The command @kbd{M-x fortran-strip-sequence-nos} deletes all text in | |
3269 | column 72 and beyond, on all lines in the current buffer. This is the | |
3270 | easiest way to get rid of old sequence numbers. | |
3271 | ||
3272 | @node Fortran Abbrev | |
3273 | @section Fortran Keyword Abbrevs | |
3274 | ||
3275 | Fortran mode provides many built-in abbrevs for common keywords and | |
3276 | declarations. These are the same sort of abbrev that you can define | |
3277 | yourself. To use them, you must turn on Abbrev mode. | |
3278 | @xref{Abbrevs,,, emacs, the Emacs Manual}. | |
3279 | ||
3280 | The built-in abbrevs are unusual in one way: they all start with a | |
3281 | semicolon. You cannot normally use semicolon in an abbrev, but Fortran | |
3282 | mode makes this possible by changing the syntax of semicolon to ``word | |
3283 | constituent.'' | |
3284 | ||
3285 | For example, one built-in Fortran abbrev is @samp{;c} for | |
3286 | @samp{continue}. If you insert @samp{;c} and then insert a punctuation | |
3287 | character such as a space or a newline, the @samp{;c} expands automatically | |
3288 | to @samp{continue}, provided Abbrev mode is enabled.@refill | |
3289 | ||
3290 | Type @samp{;?} or @samp{;C-h} to display a list of all the built-in | |
3291 | Fortran abbrevs and what they stand for. | |
24396ac6 | 3292 | |
e691d082 KB |
3293 | |
3294 | @node MS-DOG | |
3295 | @chapter Emacs and MS-DOS | |
3296 | @cindex MS-DOG | |
3297 | @cindex MS-DOS peculiarities | |
3298 | ||
3299 | This section briefly describes the peculiarities of using Emacs on | |
3300 | the MS-DOS ``operating system'' (also known as ``MS-DOG''). | |
3301 | Information about Emacs and Microsoft's current operating system | |
3302 | Windows (also known as ``Losedows) is in the main Emacs manual | |
3303 | (@pxref{Emacs and Microsoft Systems,,, emacs, the Emacs Manual}). | |
3304 | ||
3305 | If you build Emacs for MS-DOS, the binary will also run on Windows | |
3306 | 3.X, Windows NT, Windows 9X/ME, Windows 2000, or OS/2 as a DOS | |
3307 | application; all of this chapter applies for all of those systems, if | |
3308 | you use an Emacs that was built for MS-DOS. | |
3309 | ||
3310 | @xref{Text and Binary,,,emacs, the Emacs Manual}, for information | |
3311 | about Emacs' special handling of text files under MS-DOS (and | |
3312 | Windows). | |
3313 | ||
3314 | @menu | |
3315 | * Keyboard: MS-DOS Keyboard. Keyboard conventions on MS-DOS. | |
3316 | * Mouse: MS-DOS Mouse. Mouse conventions on MS-DOS. | |
3317 | * Display: MS-DOS Display. Fonts, frames and display size on MS-DOS. | |
3318 | * Files: MS-DOS File Names. File name conventions on MS-DOS. | |
7dfdf465 | 3319 | * Printing: MS-DOS Printing. Printing specifics on MS-DOS. |
e691d082 KB |
3320 | * I18N: MS-DOS and MULE. Support for internationalization on MS-DOS. |
3321 | * Processes: MS-DOS Processes. Running subprocesses on MS-DOS. | |
3322 | @end menu | |
3323 | ||
3324 | @node MS-DOS Keyboard | |
3325 | @section Keyboard Usage on MS-DOS | |
3326 | ||
3327 | @kindex DEL @r{(MS-DOS)} | |
3328 | @kindex BS @r{(MS-DOS)} | |
3329 | The key that is called @key{DEL} in Emacs (because that's how it is | |
3330 | designated on most workstations) is known as @key{BS} (backspace) on a | |
3331 | PC. That is why the PC-specific terminal initialization remaps the | |
3332 | @key{BS} key to act as @key{DEL}; the @key{DELETE} key is remapped to act | |
3333 | as @kbd{C-d} for the same reasons. | |
3334 | ||
3335 | @kindex C-g @r{(MS-DOS)} | |
3336 | @kindex C-BREAK @r{(MS-DOS)} | |
3337 | @cindex quitting on MS-DOS | |
3338 | Emacs built for MS-DOS recognizes @kbd{C-@key{BREAK}} as a quit | |
3339 | character, just like @kbd{C-g}. This is because Emacs cannot detect | |
3340 | that you have typed @kbd{C-g} until it is ready for more input. As a | |
3341 | consequence, you cannot use @kbd{C-g} to stop a running command | |
3342 | (@pxref{Quitting,,,emacs, the Emacs Manual}). By contrast, | |
3343 | @kbd{C-@key{BREAK}} @emph{is} detected as soon as you type it (as | |
3344 | @kbd{C-g} is on other systems), so it can be used to stop a running | |
3345 | command and for emergency escape (@pxref{Emergency Escape,,,emacs, the | |
3346 | Emacs Manual}). | |
3347 | ||
3348 | @cindex Meta (under MS-DOS) | |
3349 | @cindex Hyper (under MS-DOS) | |
3350 | @cindex Super (under MS-DOS) | |
3351 | @vindex dos-super-key | |
3352 | @vindex dos-hyper-key | |
3353 | The PC keyboard maps use the left @key{ALT} key as the @key{META} key. | |
3354 | You have two choices for emulating the @key{SUPER} and @key{HYPER} keys: | |
3355 | choose either the right @key{CTRL} key or the right @key{ALT} key by | |
3356 | setting the variables @code{dos-hyper-key} and @code{dos-super-key} to 1 | |
3357 | or 2 respectively. If neither @code{dos-super-key} nor | |
3358 | @code{dos-hyper-key} is 1, then by default the right @key{ALT} key is | |
3359 | also mapped to the @key{META} key. However, if the MS-DOS international | |
3360 | keyboard support program @file{KEYB.COM} is installed, Emacs will | |
3361 | @emph{not} map the right @key{ALT} to @key{META}, since it is used for | |
3362 | accessing characters like @kbd{~} and @kbd{@@} on non-US keyboard | |
3363 | layouts; in this case, you may only use the left @key{ALT} as @key{META} | |
3364 | key. | |
3365 | ||
3366 | @kindex C-j @r{(MS-DOS)} | |
3367 | @vindex dos-keypad-mode | |
3368 | The variable @code{dos-keypad-mode} is a flag variable that controls | |
3369 | what key codes are returned by keys in the numeric keypad. You can also | |
3370 | define the keypad @key{ENTER} key to act like @kbd{C-j}, by putting the | |
3371 | following line into your @file{_emacs} file: | |
3372 | ||
3373 | @smallexample | |
3374 | ;; @r{Make the @key{ENTER} key from the numeric keypad act as @kbd{C-j}.} | |
3375 | (define-key function-key-map [kp-enter] [?\C-j]) | |
3376 | @end smallexample | |
3377 | ||
3378 | @node MS-DOS Mouse | |
3379 | @section Mouse Usage on MS-DOS | |
3380 | ||
3381 | @cindex mouse support under MS-DOS | |
3382 | Emacs on MS-DOS supports a mouse (on the default terminal only). | |
3383 | The mouse commands work as documented, including those that use menus | |
3384 | and the menu bar (@pxref{Menu Bar,,,emacs, the Emacs Manual}). Scroll | |
3385 | bars don't work in MS-DOS Emacs. PC mice usually have only two | |
3386 | buttons; these act as @kbd{Mouse-1} and @kbd{Mouse-2}, but if you | |
3387 | press both of them together, that has the effect of @kbd{Mouse-3}. If | |
3388 | the mouse does have 3 buttons, Emacs detects that at startup, and all | |
3389 | the 3 buttons function normally, as on X. | |
3390 | ||
3391 | Help strings for menu-bar and pop-up menus are displayed in the echo | |
3392 | area when the mouse pointer moves across the menu items. Highlighting | |
3393 | of mouse-sensitive text (@pxref{Mouse References,,,emacs, the Emacs | |
3394 | Manual}) is also supported. | |
3395 | ||
3396 | @cindex mouse, set number of buttons | |
3397 | @findex msdos-set-mouse-buttons | |
3398 | Some versions of mouse drivers don't report the number of mouse | |
3399 | buttons correctly. For example, mice with a wheel report that they | |
3400 | have 3 buttons, but only 2 of them are passed to Emacs; the clicks on | |
3401 | the wheel, which serves as the middle button, are not passed. In | |
3402 | these cases, you can use the @kbd{M-x msdos-set-mouse-buttons} command | |
3403 | to tell Emacs how many mouse buttons to expect. You could make such a | |
3404 | setting permanent by adding this fragment to your @file{_emacs} init | |
3405 | file: | |
3406 | ||
3407 | @example | |
3408 | ;; @r{Treat the mouse like a 2-button mouse.} | |
3409 | (msdos-set-mouse-buttons 2) | |
3410 | @end example | |
3411 | ||
3412 | @cindex Windows clipboard support | |
3413 | Emacs built for MS-DOS supports clipboard operations when it runs on | |
3414 | Windows. Commands that put text on the kill ring, or yank text from | |
3415 | the ring, check the Windows clipboard first, just as Emacs does on the | |
3416 | X Window System (@pxref{Mouse Commands,,,emacs, the Emacs Manual}). | |
3417 | Only the primary selection and the cut buffer are supported by MS-DOS | |
3418 | Emacs on Windows; the secondary selection always appears as empty. | |
3419 | ||
3420 | Due to the way clipboard access is implemented by Windows, the | |
3421 | length of text you can put into the clipboard is limited by the amount | |
3422 | of free DOS memory that is available to Emacs. Usually, up to 620KB of | |
3423 | text can be put into the clipboard, but this limit depends on the system | |
3424 | configuration and is lower if you run Emacs as a subprocess of | |
3425 | another program. If the killed text does not fit, Emacs outputs a | |
3426 | message saying so, and does not put the text into the clipboard. | |
3427 | ||
3428 | Null characters also cannot be put into the Windows clipboard. If the | |
3429 | killed text includes null characters, Emacs does not put such text into | |
3430 | the clipboard, and displays in the echo area a message to that effect. | |
3431 | ||
3432 | @vindex dos-display-scancodes | |
3433 | The variable @code{dos-display-scancodes}, when non-@code{nil}, | |
3434 | directs Emacs to display the @acronym{ASCII} value and the keyboard scan code of | |
3435 | each keystroke; this feature serves as a complement to the | |
3436 | @code{view-lossage} command, for debugging. | |
3437 | ||
3438 | @node MS-DOS Display | |
3439 | @section Display on MS-DOS | |
3440 | @cindex faces under MS-DOS | |
3441 | @cindex fonts, emulating under MS-DOS | |
3442 | ||
3443 | Display on MS-DOS cannot use font variants, like bold or italic, but | |
3444 | it does support multiple faces, each of which can specify a foreground | |
3445 | and a background color. Therefore, you can get the full functionality | |
3446 | of Emacs packages that use fonts (such as @code{font-lock}, Enriched | |
3447 | Text mode, and others) by defining the relevant faces to use different | |
3448 | colors. Use the @code{list-colors-display} command (@pxref{Frame | |
3449 | Parameters,,,emacs, the Emacs Manual}) and the | |
3450 | @code{list-faces-display} command (@pxref{Faces,,,emacs, the Emacs | |
3451 | Manual}) to see what colors and faces are available and what they look | |
3452 | like. | |
3453 | ||
3454 | @xref{MS-DOS and MULE}, later in this chapter, for information on | |
3455 | how Emacs displays glyphs and characters that aren't supported by the | |
3456 | native font built into the DOS display. | |
3457 | ||
3458 | @cindex cursor shape on MS-DOS | |
3459 | When Emacs starts, it changes the cursor shape to a solid box. This | |
3460 | is for compatibility with other systems, where the box cursor is the | |
3461 | default in Emacs. This default shape can be changed to a bar by | |
3462 | specifying the @code{cursor-type} parameter in the variable | |
3463 | @code{default-frame-alist} (@pxref{Creating Frames,,,emacs, the Emacs | |
3464 | Manual}). The MS-DOS terminal doesn't support a vertical-bar cursor, | |
3465 | so the bar cursor is horizontal, and the @code{@var{width}} parameter, | |
3466 | if specified by the frame parameters, actually determines its height. | |
3467 | For this reason, the @code{bar} and @code{hbar} cursor types produce | |
3468 | the same effect on MS-DOS. As an extension, the bar cursor | |
3469 | specification can include the starting scan line of the cursor as well | |
3470 | as its width, like this: | |
3471 | ||
3472 | @example | |
3473 | '(cursor-type bar @var{width} . @var{start}) | |
3474 | @end example | |
3475 | ||
3476 | @noindent | |
3477 | In addition, if the @var{width} parameter is negative, the cursor bar | |
3478 | begins at the top of the character cell. | |
3479 | ||
3480 | @cindex frames on MS-DOS | |
3481 | The MS-DOS terminal can only display a single frame at a time. The | |
3482 | Emacs frame facilities work on MS-DOS much as they do on text-only | |
3483 | terminals (@pxref{Frames,,,emacs, the Emacs Manual}). When you run | |
3484 | Emacs from a DOS window on MS-Windows, you can make the visible frame | |
3485 | smaller than the full screen, but Emacs still cannot display more than | |
3486 | a single frame at a time. | |
3487 | ||
3488 | @cindex frame size under MS-DOS | |
3489 | @findex mode4350 | |
3490 | @findex mode25 | |
3491 | The @code{mode4350} command switches the display to 43 or 50 | |
3492 | lines, depending on your hardware; the @code{mode25} command switches | |
3493 | to the default 80x25 screen size. | |
3494 | ||
3495 | By default, Emacs only knows how to set screen sizes of 80 columns by | |
3496 | 25, 28, 35, 40, 43 or 50 rows. However, if your video adapter has | |
3497 | special video modes that will switch the display to other sizes, you can | |
3498 | have Emacs support those too. When you ask Emacs to switch the frame to | |
3499 | @var{n} rows by @var{m} columns dimensions, it checks if there is a | |
3500 | variable called @code{screen-dimensions-@var{n}x@var{m}}, and if so, | |
3501 | uses its value (which must be an integer) as the video mode to switch | |
3502 | to. (Emacs switches to that video mode by calling the BIOS @code{Set | |
3503 | Video Mode} function with the value of | |
3504 | @code{screen-dimensions-@var{n}x@var{m}} in the @code{AL} register.) | |
3505 | For example, suppose your adapter will switch to 66x80 dimensions when | |
3506 | put into video mode 85. Then you can make Emacs support this screen | |
3507 | size by putting the following into your @file{_emacs} file: | |
3508 | ||
3509 | @example | |
3510 | (setq screen-dimensions-66x80 85) | |
3511 | @end example | |
3512 | ||
3513 | Since Emacs on MS-DOS can only set the frame size to specific | |
3514 | supported dimensions, it cannot honor every possible frame resizing | |
3515 | request. When an unsupported size is requested, Emacs chooses the next | |
3516 | larger supported size beyond the specified size. For example, if you | |
3517 | ask for 36x80 frame, you will get 40x80 instead. | |
3518 | ||
3519 | The variables @code{screen-dimensions-@var{n}x@var{m}} are used only | |
3520 | when they exactly match the specified size; the search for the next | |
3521 | larger supported size ignores them. In the above example, even if your | |
3522 | VGA supports 38x80 dimensions and you define a variable | |
3523 | @code{screen-dimensions-38x80} with a suitable value, you will still get | |
3524 | 40x80 screen when you ask for a 36x80 frame. If you want to get the | |
3525 | 38x80 size in this case, you can do it by setting the variable named | |
3526 | @code{screen-dimensions-36x80} with the same video mode value as | |
3527 | @code{screen-dimensions-38x80}. | |
3528 | ||
3529 | Changing frame dimensions on MS-DOS has the effect of changing all the | |
3530 | other frames to the new dimensions. | |
3531 | ||
3532 | @node MS-DOS File Names | |
3533 | @section File Names on MS-DOS | |
3534 | @cindex file names under MS-DOS | |
3535 | @cindex init file, default name under MS-DOS | |
3536 | ||
e691d082 KB |
3537 | On MS-DOS, file names are case-insensitive and limited to eight |
3538 | characters, plus optionally a period and three more characters. Emacs | |
3539 | knows enough about these limitations to handle file names that were | |
3540 | meant for other operating systems. For instance, leading dots | |
3541 | @samp{.} in file names are invalid in MS-DOS, so Emacs transparently | |
3542 | converts them to underscores @samp{_}; thus your default init file | |
3543 | (@pxref{Init File,,,emacs, the Emacs Manual}) is called @file{_emacs} | |
3544 | on MS-DOS. Excess characters before or after the period are generally | |
3545 | ignored by MS-DOS itself; thus, if you visit the file | |
3546 | @file{LongFileName.EvenLongerExtension}, you will silently get | |
3547 | @file{longfile.eve}, but Emacs will still display the long file name | |
3548 | on the mode line. Other than that, it's up to you to specify file | |
3549 | names which are valid under MS-DOS; the transparent conversion as | |
3550 | described above only works on file names built into Emacs. | |
3551 | ||
3552 | @cindex backup file names on MS-DOS | |
3553 | The above restrictions on the file names on MS-DOS make it almost | |
3554 | impossible to construct the name of a backup file (@pxref{Backup | |
3555 | Names,,,emacs, the Emacs Manual}) without losing some of the original | |
3556 | file name characters. For example, the name of a backup file for | |
3557 | @file{docs.txt} is @file{docs.tx~} even if single backup is used. | |
3558 | ||
3559 | @cindex file names under Windows 95/NT | |
3560 | @cindex long file names in DOS box under Windows 95/NT | |
3561 | If you run Emacs as a DOS application under Windows 9X, Windows ME, or | |
3562 | Windows 2000, you can turn on support for long file names. If you do | |
3563 | that, Emacs doesn't truncate file names or convert them to lower case; | |
3564 | instead, it uses the file names that you specify, verbatim. To enable | |
3565 | long file name support, set the environment variable @env{LFN} to | |
3566 | @samp{y} before starting Emacs. Unfortunately, Windows NT doesn't allow | |
3567 | DOS programs to access long file names, so Emacs built for MS-DOS will | |
3568 | only see their short 8+3 aliases. | |
3569 | ||
3570 | @cindex @env{HOME} directory under MS-DOS | |
3571 | MS-DOS has no notion of home directory, so Emacs on MS-DOS pretends | |
3572 | that the directory where it is installed is the value of the @env{HOME} | |
3573 | environment variable. That is, if your Emacs binary, | |
3574 | @file{emacs.exe}, is in the directory @file{c:/utils/emacs/bin}, then | |
3575 | Emacs acts as if @env{HOME} were set to @samp{c:/utils/emacs}. In | |
3576 | particular, that is where Emacs looks for the init file @file{_emacs}. | |
3577 | With this in mind, you can use @samp{~} in file names as an alias for | |
3578 | the home directory, as you would on GNU or Unix. You can also set | |
3579 | @env{HOME} variable in the environment before starting Emacs; its | |
3580 | value will then override the above default behavior. | |
3581 | ||
3582 | Emacs on MS-DOS handles the directory name @file{/dev} specially, | |
3583 | because of a feature in the emulator libraries of DJGPP that pretends | |
3584 | I/O devices have names in that directory. We recommend that you avoid | |
3585 | using an actual directory named @file{/dev} on any disk. | |
3586 | ||
3587 | @node MS-DOS Printing | |
3588 | @section Printing and MS-DOS | |
3589 | ||
3590 | Printing commands, such as @code{lpr-buffer} | |
7dfdf465 | 3591 | (@pxref{Printing,,,emacs, the Emacs Manual}) and |
e691d082 | 3592 | @code{ps-print-buffer} (@pxref{PostScript,,,emacs, the Emacs Manual}) |
7dfdf465 EZ |
3593 | can work on MS-DOS by sending the output to one of the printer ports, |
3594 | if a Posix-style @code{lpr} program is unavailable. The same Emacs | |
3595 | variables control printing on all systems, but in some cases they have | |
3596 | different default values on MS-DOS. | |
3597 | ||
3598 | @xref{MS-Windows Printing,,,emacs, the Emacs Manual}, for details. | |
e691d082 KB |
3599 | |
3600 | Some printers expect DOS codepage encoding of non-@acronym{ASCII} text, even | |
3601 | though they are connected to a Windows machine which uses a different | |
3602 | encoding for the same locale. For example, in the Latin-1 locale, DOS | |
3603 | uses codepage 850 whereas Windows uses codepage 1252. @xref{MS-DOS and | |
3604 | MULE}. When you print to such printers from Windows, you can use the | |
3605 | @kbd{C-x RET c} (@code{universal-coding-system-argument}) command before | |
3606 | @kbd{M-x lpr-buffer}; Emacs will then convert the text to the DOS | |
3607 | codepage that you specify. For example, @kbd{C-x RET c cp850-dos RET | |
3608 | M-x lpr-region RET} will print the region while converting it to the | |
3609 | codepage 850 encoding. You may need to create the @code{cp@var{nnn}} | |
3610 | coding system with @kbd{M-x codepage-setup}. | |
3611 | ||
e691d082 KB |
3612 | @vindex dos-printer |
3613 | @vindex dos-ps-printer | |
3614 | For backwards compatibility, the value of @code{dos-printer} | |
3615 | (@code{dos-ps-printer}), if it has a value, overrides the value of | |
7dfdf465 | 3616 | @code{printer-name} (@code{ps-printer-name}), on MS-DOS. |
e691d082 KB |
3617 | |
3618 | ||
3619 | @node MS-DOS and MULE | |
3620 | @section International Support on MS-DOS | |
3621 | @cindex international support @r{(MS-DOS)} | |
3622 | ||
3623 | Emacs on MS-DOS supports the same international character sets as it | |
3624 | does on GNU, Unix and other platforms (@pxref{International,,,emacs, | |
3625 | the Emacs Manual}), including coding systems for converting between | |
3626 | the different character sets. However, due to incompatibilities | |
3627 | between MS-DOS/MS-Windows and other systems, there are several | |
3628 | DOS-specific aspects of this support that you should be aware of. | |
3629 | This section describes these aspects. | |
3630 | ||
3631 | The description below is largely specific to the MS-DOS port of | |
3632 | Emacs, especially where it talks about practical implications for | |
3633 | Emacs users. For other operating systems, see the @file{code-pages.el} | |
3634 | package, which implements support for MS-DOS- and MS-Windows-specific | |
3635 | encodings for all platforms other than MS-DOS. | |
3636 | ||
3637 | @table @kbd | |
3638 | @item M-x dos-codepage-setup | |
3639 | Set up Emacs display and coding systems as appropriate for the current | |
3640 | DOS codepage. | |
3641 | ||
3642 | @item M-x codepage-setup | |
3643 | Create a coding system for a certain DOS codepage. | |
3644 | @end table | |
3645 | ||
3646 | @cindex codepage, MS-DOS | |
3647 | @cindex DOS codepages | |
3648 | MS-DOS is designed to support one character set of 256 characters at | |
3649 | any given time, but gives you a variety of character sets to choose | |
3650 | from. The alternative character sets are known as @dfn{DOS codepages}. | |
3651 | Each codepage includes all 128 @acronym{ASCII} characters, but the other 128 | |
3652 | characters (codes 128 through 255) vary from one codepage to another. | |
3653 | Each DOS codepage is identified by a 3-digit number, such as 850, 862, | |
3654 | etc. | |
3655 | ||
3656 | In contrast to X, which lets you use several fonts at the same time, | |
3657 | MS-DOS normally doesn't allow use of several codepages in a single | |
3658 | session. MS-DOS was designed to load a single codepage at system | |
3659 | startup, and require you to reboot in order to change | |
3660 | it@footnote{Normally, one particular codepage is burnt into the | |
3661 | display memory, while other codepages can be installed by modifying | |
3662 | system configuration files, such as @file{CONFIG.SYS}, and rebooting. | |
3663 | While there is third-party software that allows changing the codepage | |
3664 | without rebooting, we describe here how a stock MS-DOS system | |
3665 | behaves.}. Much the same limitation applies when you run DOS | |
3666 | executables on other systems such as MS-Windows. | |
3667 | ||
3668 | @cindex unibyte operation @r{(MS-DOS)} | |
3669 | If you invoke Emacs on MS-DOS with the @samp{--unibyte} option | |
3670 | (@pxref{Initial Options,,,emacs, the Emacs Manual}), Emacs does not | |
3671 | perform any conversion of non-@acronym{ASCII} characters. Instead, it | |
3672 | reads and writes any non-@acronym{ASCII} characters verbatim, and | |
3673 | sends their 8-bit codes to the display verbatim. Thus, unibyte Emacs | |
3674 | on MS-DOS supports the current codepage, whatever it may be, but | |
3675 | cannot even represent any other characters. | |
3676 | ||
3677 | @vindex dos-codepage | |
3678 | For multibyte operation on MS-DOS, Emacs needs to know which | |
3679 | characters the chosen DOS codepage can display. So it queries the | |
3680 | system shortly after startup to get the chosen codepage number, and | |
3681 | stores the number in the variable @code{dos-codepage}. Some systems | |
3682 | return the default value 437 for the current codepage, even though the | |
3683 | actual codepage is different. (This typically happens when you use the | |
3684 | codepage built into the display hardware.) You can specify a different | |
3685 | codepage for Emacs to use by setting the variable @code{dos-codepage} in | |
3686 | your init file. | |
3687 | ||
3688 | @cindex language environment, automatic selection on @r{MS-DOS} | |
3689 | Multibyte Emacs supports only certain DOS codepages: those which can | |
3690 | display Far-Eastern scripts, like the Japanese codepage 932, and those | |
3691 | that encode a single ISO 8859 character set. | |
3692 | ||
3693 | The Far-Eastern codepages can directly display one of the MULE | |
3694 | character sets for these countries, so Emacs simply sets up to use the | |
3695 | appropriate terminal coding system that is supported by the codepage. | |
3696 | The special features described in the rest of this section mostly | |
3697 | pertain to codepages that encode ISO 8859 character sets. | |
3698 | ||
3699 | For the codepages which correspond to one of the ISO character sets, | |
3700 | Emacs knows the character set name based on the codepage number. Emacs | |
3701 | automatically creates a coding system to support reading and writing | |
3702 | files that use the current codepage, and uses this coding system by | |
3703 | default. The name of this coding system is @code{cp@var{nnn}}, where | |
3704 | @var{nnn} is the codepage number.@footnote{The standard Emacs coding | |
3705 | systems for ISO 8859 are not quite right for the purpose, because | |
3706 | typically the DOS codepage does not match the standard ISO character | |
3707 | codes. For example, the letter @samp{@,{c}} (@samp{c} with cedilla) has | |
3708 | code 231 in the standard Latin-1 character set, but the corresponding | |
3709 | DOS codepage 850 uses code 135 for this glyph.} | |
3710 | ||
3711 | @cindex mode line @r{(MS-DOS)} | |
3712 | All the @code{cp@var{nnn}} coding systems use the letter @samp{D} | |
3713 | (for ``DOS'') as their mode-line mnemonic. Since both the terminal | |
3714 | coding system and the default coding system for file I/O are set to | |
3715 | the proper @code{cp@var{nnn}} coding system at startup, it is normal | |
3716 | for the mode line on MS-DOS to begin with @samp{-DD\-}. @xref{Mode | |
3717 | Line,,,emacs, the Emacs Manual}. Far-Eastern DOS terminals do not use | |
3718 | the @code{cp@var{nnn}} coding systems, and thus their initial mode | |
3719 | line looks like the Emacs default. | |
3720 | ||
3721 | Since the codepage number also indicates which script you are using, | |
3722 | Emacs automatically runs @code{set-language-environment} to select the | |
3723 | language environment for that script (@pxref{Language | |
3724 | Environments,,,emacs, the Emacs Manual}). | |
3725 | ||
3726 | If a buffer contains a character belonging to some other ISO 8859 | |
3727 | character set, not the one that the chosen DOS codepage supports, Emacs | |
3728 | displays it using a sequence of @acronym{ASCII} characters. For example, if the | |
3729 | current codepage doesn't have a glyph for the letter @samp{@`o} (small | |
3730 | @samp{o} with a grave accent), it is displayed as @samp{@{`o@}}, where | |
3731 | the braces serve as a visual indication that this is a single character. | |
3732 | (This may look awkward for some non-Latin characters, such as those from | |
3733 | Greek or Hebrew alphabets, but it is still readable by a person who | |
3734 | knows the language.) Even though the character may occupy several | |
3735 | columns on the screen, it is really still just a single character, and | |
3736 | all Emacs commands treat it as one. | |
3737 | ||
3738 | @cindex IBM graphics characters (MS-DOS) | |
3739 | @cindex box-drawing characters (MS-DOS) | |
3740 | @cindex line-drawing characters (MS-DOS) | |
3741 | Not all characters in DOS codepages correspond to ISO 8859 | |
3742 | characters---some are used for other purposes, such as box-drawing | |
3743 | characters and other graphics. Emacs maps these characters to two | |
3744 | special character sets called @code{eight-bit-control} and | |
3745 | @code{eight-bit-graphic}, and displays them as their IBM glyphs. | |
3746 | However, you should be aware that other systems might display these | |
3747 | characters differently, so you should avoid them in text that might be | |
3748 | copied to a different operating system, or even to another DOS machine | |
3749 | that uses a different codepage. | |
3750 | ||
3751 | @vindex dos-unsupported-character-glyph | |
3752 | Emacs supports many other characters sets aside from ISO 8859, but it | |
3753 | cannot display them on MS-DOS. So if one of these multibyte characters | |
3754 | appears in a buffer, Emacs on MS-DOS displays them as specified by the | |
3755 | @code{dos-unsupported-character-glyph} variable; by default, this glyph | |
3756 | is an empty triangle. Use the @kbd{C-u C-x =} command to display the | |
3757 | actual code and character set of such characters. @xref{Position | |
3758 | Info,,,emacs, the Emacs Manual}. | |
3759 | ||
3760 | @findex codepage-setup | |
3761 | By default, Emacs defines a coding system to support the current | |
3762 | codepage. To define a coding system for some other codepage (e.g., to | |
3763 | visit a file written on a DOS machine in another country), use the | |
3764 | @kbd{M-x codepage-setup} command. It prompts for the 3-digit code of | |
3765 | the codepage, with completion, then creates the coding system for the | |
3766 | specified codepage. You can then use the new coding system to read and | |
3767 | write files, but you must specify it explicitly for the file command | |
3768 | when you want to use it (@pxref{Text Coding,,,emacs, the Emacs Manual}). | |
3769 | ||
3770 | These coding systems are also useful for visiting a file encoded using | |
3771 | a DOS codepage, using Emacs running on some other operating system. | |
3772 | ||
3773 | @cindex MS-Windows codepages | |
3774 | MS-Windows provides its own codepages, which are different from the | |
3775 | DOS codepages for the same locale. For example, DOS codepage 850 | |
3776 | supports the same character set as Windows codepage 1252; DOS codepage | |
3777 | 855 supports the same character set as Windows codepage 1251, etc. | |
3778 | The MS-Windows version of Emacs uses the current codepage for display | |
3779 | when invoked with the @samp{-nw} option. Support for codepages in the | |
3780 | Windows port of Emacs is part of the @file{code-pages.el} package. | |
3781 | ||
3782 | @node MS-DOS Processes | |
3783 | @section Subprocesses on MS-DOS | |
3784 | ||
3785 | @cindex compilation under MS-DOS | |
3786 | @cindex inferior processes under MS-DOS | |
3787 | @findex compile @r{(MS-DOS)} | |
3788 | @findex grep @r{(MS-DOS)} | |
3789 | Because MS-DOS is a single-process ``operating system,'' | |
3790 | asynchronous subprocesses are not available. In particular, Shell | |
3791 | mode and its variants do not work. Most Emacs features that use | |
3792 | asynchronous subprocesses also don't work on MS-DOS, including | |
3793 | Shell mode and GUD. When in doubt, try and see; commands that | |
3794 | don't work output an error message saying that asynchronous processes | |
3795 | aren't supported. | |
3796 | ||
3797 | Compilation under Emacs with @kbd{M-x compile}, searching files with | |
3798 | @kbd{M-x grep} and displaying differences between files with @kbd{M-x | |
3799 | diff} do work, by running the inferior processes synchronously. This | |
3800 | means you cannot do any more editing until the inferior process | |
3801 | finishes. | |
3802 | ||
3803 | Spell checking also works, by means of special support for synchronous | |
3804 | invocation of the @code{ispell} program. This is slower than the | |
3805 | asynchronous invocation on other platforms | |
3806 | ||
3807 | Instead of the Shell mode, which doesn't work on MS-DOS, you can use | |
3808 | the @kbd{M-x eshell} command. This invokes the Eshell package that | |
3809 | implements a Posix-like shell entirely in Emacs Lisp. | |
3810 | ||
3811 | By contrast, Emacs compiled as a native Windows application | |
3812 | @strong{does} support asynchronous subprocesses. @xref{Windows | |
3813 | Processes,,,emacs, the Emacs Manual}. | |
3814 | ||
3815 | @cindex printing under MS-DOS | |
3816 | Printing commands, such as @code{lpr-buffer} | |
3817 | (@pxref{Printing,,,emacs, the Emacs Manual}) and | |
3818 | @code{ps-print-buffer} (@pxref{PostScript,,,emacs, the Emacs Manual}), | |
3819 | work in MS-DOS by sending the output to one of the printer ports. | |
3820 | @xref{MS-DOS Printing,,,emacs, the Emacs Manual}. | |
3821 | ||
3822 | When you run a subprocess synchronously on MS-DOS, make sure the | |
3823 | program terminates and does not try to read keyboard input. If the | |
3824 | program does not terminate on its own, you will be unable to terminate | |
3825 | it, because MS-DOS provides no general way to terminate a process. | |
3826 | Pressing @kbd{C-c} or @kbd{C-@key{BREAK}} might sometimes help in these | |
3827 | cases. | |
3828 | ||
3829 | Accessing files on other machines is not supported on MS-DOS. Other | |
3830 | network-oriented commands such as sending mail, Web browsing, remote | |
3831 | login, etc., don't work either, unless network access is built into | |
3832 | MS-DOS with some network redirector. | |
3833 | ||
3834 | @cindex directory listing on MS-DOS | |
3835 | @vindex dired-listing-switches @r{(MS-DOS)} | |
3836 | Dired on MS-DOS uses the @code{ls-lisp} package where other | |
3837 | platforms use the system @code{ls} command. Therefore, Dired on | |
3838 | MS-DOS supports only some of the possible options you can mention in | |
3839 | the @code{dired-listing-switches} variable. The options that work are | |
3840 | @samp{-A}, @samp{-a}, @samp{-c}, @samp{-i}, @samp{-r}, @samp{-S}, | |
3841 | @samp{-s}, @samp{-t}, and @samp{-u}. | |
3842 | ||
3843 | ||
4d213d5a LT |
3844 | @node Index |
3845 | @unnumbered Index | |
3846 | ||
3847 | @printindex cp | |
3848 | ||
3849 | @bye | |
93ff1280 MB |
3850 | |
3851 | @ignore | |
3852 | arch-tag: 75c33f13-32c6-41b6-9537-847a312e2e49 | |
3853 | @end ignore |