diff options
| author | Eli Zaretskii <eliz@gnu.org> | 2006-05-06 13:01:14 +0000 |
|---|---|---|
| committer | Eli Zaretskii <eliz@gnu.org> | 2006-05-06 13:01:14 +0000 |
| commit | 240ce8099f86abdfcbaefc8387e8a43218652866 (patch) | |
| tree | e427698cb7469839cafd93fe5f20e4627fca880c | |
| parent | 030409091898c6e5a6c05b4706ab827d0636a0e7 (diff) | |
| download | emacs-240ce8099f86abdfcbaefc8387e8a43218652866.tar.gz | |
(Introduction): Reword to make consistent with printed version only.
(MS-DOS): Renamed from "MS-DOG". All references updated.
(Daylight Savings): Remove this node: it is an exact duplicate of its
name-sake in calendar.texi.
<Top level>: Remove the body of all chapters and move them to the
new *-xtra.texi files. Use @raisesections and @lowersections to
convert sections to chapters etc.
| -rw-r--r-- | man/emacs-xtra.texi | 3774 |
1 files changed, 24 insertions, 3750 deletions
diff --git a/man/emacs-xtra.texi b/man/emacs-xtra.texi index 600748b7c88..65625522298 100644 --- a/man/emacs-xtra.texi +++ b/man/emacs-xtra.texi @@ -56,16 +56,18 @@ license to the document, as described in section 6 of the license. @menu * Introduction:: What documentation belongs here? +@iftex +* Picture Mode:: Editing pictures made up of characters using + the quarter-plane screen model. + * Autorevert:: Auto Reverting non-file buffers. * Subdir Switches:: Subdirectory switches in Dired. * Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization. * Emerge:: A convenient way of merging two versions of a program. -* Picture Mode:: Editing pictures made up of characters using - the quarter-plane screen model. - * Advanced VC Usage:: Advanced VC (version control) features. * Fortran:: Fortran mode and its special features. -* MS-DOS:: Using Emacs on MS-DOS (otherwise known as "MS-DOG"). +* MS-DOS:: Using Emacs on MS-DOS (otherwise known as @dfn{MS-DOG}). +@end iftex * Index:: @end menu @@ -73,3773 +75,45 @@ license to the document, as described in section 6 of the license. @unnumbered Introduction This manual contains detailed information about various features that -are too specialized to be included in the Emacs manual. It is +are too specialized to be included in the printed Emacs manual. It is intended to be readable by anyone having a basic knowledge of Emacs. However, certain sections may be intended for a more specialized audience, such as Elisp authors. This should be clearly pointed out at the beginning of these sections. -This manual is intended as a complement, rather than an alternative, -to other ways to gain a more detailed knowledge of Emacs than the -Emacs manual can provide, such as browsing packages using @kbd{C-h p}, -accessing mode documentation using @kbd{C-h m} and browsing user -options using Custom. Also, certain packages, or collections of -related features, have their own manuals. The present manual is -mainly intended to be a collection of smaller specialized features, -too small to get their own manual. +Certain packages, or collections of related features, have their own +manuals, separate from the main Emacs User's manual. This manual is +intended as a complement, rather than an alternative, to reading those +additional manuals; in a nutshell, it is a collection of smaller +specialized features, too small or too obscure to justify their own +manual. Sections intended specifically for Elisp programmers can follow the style of the Elisp manual. Other sections should follow the style of the Emacs manual. -@node Autorevert -@chapter Auto Reverting non-file Buffers - -Normally Global Auto Revert Mode only reverts file buffers. There are -two ways to auto-revert certain non-file buffers: enabling Auto Revert -Mode in those buffers (using @kbd{M-x auto-revert-mode}) and setting -@code{global-auto-revert-non-file-buffers} to @code{t}. The latter -enables Auto Reverting for all types of buffers for which it is -implemented, that is, for the types of buffers listed in the menu -below. - -Like file buffers, non-file buffers should normally not revert while -you are working on them, or while they contain information that might -get lost after reverting. Therefore, they do not revert if they are -``modified''. This can get tricky, because deciding when a non-file -buffer should be marked modified is usually more difficult than for -file buffers. - -Another tricky detail is that, for efficiency reasons, Auto Revert -often does not try to detect all possible changes in the buffer, only -changes that are ``major'' or easy to detect. Hence, enabling -auto-reverting for a non-file buffer does not always guarantee that -all information in the buffer is up to date and does not necessarily -make manual reverts useless. - -At the other extreme, certain buffers automatically auto-revert every -@code{auto-revert-interval} seconds. (This currently only applies to -the Buffer Menu.) In this case, Auto Revert does not print any -messages while reverting, even when @code{auto-revert-verbose} is -non-@code{nil}. - -The details depend on the particular types of buffers and are -explained in the corresponding sections. - -@menu -* Auto Reverting the Buffer Menu:: -* Auto Reverting Dired:: -* Supporting additional buffers:: -@end menu - -@node Auto Reverting the Buffer Menu -@section Auto Reverting the Buffer Menu - -If auto-reverting of non-file buffers is enabled, the Buffer Menu -automatically reverts every @code{auto-revert-interval} seconds, -whether there is a need for it or not. (It would probably take longer -to check whether there is a need than to actually revert.) - -If the Buffer Menu inappropriately gets marked modified, just revert -it manually using @kbd{g} and auto-reverting will resume. However, if -you marked certain buffers to get deleted or to be displayed, you have -to be careful, because reverting erases all marks. The fact that -adding marks sets the buffer's modified flag prevents Auto Revert from -automatically erasing the marks. - -@node Auto Reverting Dired -@section Auto Reverting Dired buffers - -Auto-reverting Dired buffers currently works on GNU or Unix style -operating systems. It may not work satisfactorily on some other -systems. - -Dired buffers only auto-revert when the file list of the buffer's main -directory changes. They do not auto-revert when information about a -particular file changes or when inserted subdirectories change. To be -sure that @emph{all} listed information is up to date, you have to -manually revert using @kbd{g}, @emph{even} if auto-reverting is -enabled in the Dired buffer. Sometimes, you might get the impression -that modifying or saving files listed in the main directory actually -does cause auto-reverting. This is because making changes to a file, -or saving it, very often causes changes in the directory itself, for -instance, through backup files or auto-save files. However, this is -not guaranteed. - -If the Dired buffer is marked modified and there are no changes you -want to protect, then most of the time you can make auto-reverting -resume by manually reverting the buffer using @kbd{g}. There is one -exception. If you flag or mark files, you can safely revert the -buffer. This will not erase the flags or marks (unless the marked -file has been deleted, of course). However, the buffer will stay -modified, even after reverting, and auto-reverting will not resume. -This is because, if you flag or mark files, you may be working on the -buffer and you might not want the buffer to change without warning. -If you want auto-reverting to resume in the presence of marks and -flags, mark the buffer non-modified using @kbd{M-~}. However, adding, -deleting or changing marks or flags will mark it modified again. - -Remote Dired buffers are not auto-reverted. Neither are Dired buffers -for which you used shell wildcards or file arguments to list only some -of the files. @samp{*Find*} and @samp{*Locate*} buffers do not -auto-revert either. - -@node Supporting additional buffers -@section Adding Support for Auto-Reverting additional Buffers. - -This section is intended for Elisp programmers who would like to add -support for auto-reverting new types of buffers. - -To support auto-reverting the buffer must first of all have a -@code{revert-buffer-function}. @xref{Definition of -revert-buffer-function,, Reverting, elisp, the Emacs Lisp Reference Manual}. - -In addition, it @emph{must} have a @code{buffer-stale-function}. - -@defvar buffer-stale-function -The value of this variable is a function to check whether a non-file -buffer needs reverting. This should be a function with one optional -argument @var{noconfirm}. The function should return non-@code{nil} -if the buffer should be reverted. The buffer is current when this -function is called. - -While this function is mainly intended for use in auto-reverting, it -could be used for other purposes as well. For instance, if -auto-reverting is not enabled, it could be used to warn the user that -the buffer needs reverting. The idea behind the @var{noconfirm} -argument is that it should be @code{t} if the buffer is going to be -reverted without asking the user and @code{nil} if the function is -just going to be used to warn the user that the buffer is out of date. -In particular, for use in auto-reverting, @var{noconfirm} is @code{t}. -If the function is only going to be used for auto-reverting, you can -ignore the @var{noconfirm} argument. - -If you just want to automatically auto-revert every -@code{auto-revert-interval} seconds, use: - -@example -(set (make-local-variable 'buffer-stale-function) - #'(lambda (&optional noconfirm) 'fast)) -@end example - -@noindent -in the buffer's mode function. - -The special return value @samp{fast} tells the caller that the need -for reverting was not checked, but that reverting the buffer is fast. -It also tells Auto Revert not to print any revert messages, even if -@code{auto-revert-verbose} is non-@code{nil}. This is important, as -getting revert messages every @code{auto-revert-interval} seconds can -be very annoying. The information provided by this return value could -also be useful if the function is consulted for purposes other than -auto-reverting. -@end defvar - -Once the buffer has a @code{revert-buffer-function} and a -@code{buffer-stale-function}, several problems usually remain. - -The buffer will only auto-revert if it is marked unmodified. Hence, -you will have to make sure that various functions mark the buffer -modified if and only if either the buffer contains information that -might be lost by reverting or there is reason to believe that the user -might be inconvenienced by auto-reverting, because he is actively -working on the buffer. The user can always override this by manually -adjusting the modified status of the buffer. To support this, calling -the @code{revert-buffer-function} on a buffer that is marked -unmodified should always keep the buffer marked unmodified. - -It is important to assure that point does not continuously jump around -as a consequence of auto-reverting. Of course, moving point might be -inevitable if the buffer radically changes. - -You should make sure that the @code{revert-buffer-function} does not -print messages that unnecessarily duplicate Auto Revert's own messages -if @code{auto-revert-verbose} is @code{t} and effectively override a -@code{nil} value for @code{auto-revert-verbose}. Hence, adapting a -mode for auto-reverting often involves getting rid of such messages. -This is especially important for buffers that automatically -auto-revert every @code{auto-revert-interval} seconds. - -Also, you may want to update the documentation string of -@code{global-auto-revert-non-file-buffers}. - -@ifinfo -Finally, you should add a node to this chapter's menu. This node -@end ifinfo -@ifnotinfo -Finally, you should add a section to this chapter. This section -@end ifnotinfo -should at the very least make clear whether enabling auto-reverting -for the buffer reliably assures that all information in the buffer is -completely up to date (or will be after @code{auto-revert-interval} -seconds). - -@node Subdir Switches -@chapter Subdirectory Switches in Dired - -You can insert subdirectories with specified @code{ls} switches in -Dired buffers, using @kbd{C-u i}. You can change the @code{ls} -switches of an already inserted subdirectory using @kbd{C-u l}. - -In Emacs versions 22.1 and later, Dired remembers the switches, so -that reverting the buffer will not change them back to the main -directory's switches. Deleting a subdirectory forgets about its -switches. - -Using @code{dired-undo} (usually bound to @kbd{C-_} and @kbd{C-x u}) -to reinsert or delete subdirectories, that were inserted with explicit -switches, can bypass Dired's machinery for remembering (or forgetting) -switches. Deleting a subdirectory using @code{dired-undo} does not -forget its switches. When later reinserted using @kbd{i}, it will be -reinserted using its old switches. Using @code{dired-undo} to -reinsert a subdirectory that was deleted using the regular -Dired commands (not @code{dired-undo}) will originally insert it with -its old switches. However, reverting the buffer will relist it using -the buffer's default switches. If any of this yields problems, you -can easily correct the situation using @kbd{C-u i} or @kbd{C-u l}. - -Dired does not remember the @code{R} switch. Inserting a subdirectory -with switches that include the @code{R} switch is equivalent with -inserting each of its subdirectories using all remaining switches. -For instance, updating or killing a subdirectory that was inserted -with the @code{R} switch will not update or kill its subdirectories. - -The buffer's default switches do not affect subdirectories that were -inserted using explicitly specified switches. In particular, -commands such as @kbd{s}, that change the buffer's switches do not -affect such subdirectories. (They do affect subdirectories without -explicitly assigned switches, however.) - -You can make Dired forget about all subdirectory switches and relist -all subdirectories with the buffer's default switches using -@kbd{M-x dired-reset-subdir-switches}. This also reverts the Dired buffer. - - -@c Moved here from the Emacs Lisp Reference Manual, 2005-03-26. -@node Advanced Calendar/Diary Usage -@chapter Customizing the Calendar and Diary - - There are many customizations that you can use to make the calendar and -diary suit your personal tastes. - -@menu -* Calendar Customizing:: Defaults you can set. -* Holiday Customizing:: Defining your own holidays. -* Date Display Format:: Changing the format. -* Time Display Format:: Changing the format. -* Daylight Savings:: Changing the default. -* Diary Customizing:: Defaults you can set. -* Hebrew/Islamic Entries:: How to obtain them. -* Fancy Diary Display:: Enhancing the diary display, sorting entries, - using included diary files. -* Sexp Diary Entries:: Fancy things you can do. -@end menu - -@node Calendar Customizing -@section Customizing the Calendar -@vindex calendar-holiday-marker -@vindex diary-entry-marker - The variable @code{calendar-holiday-marker} specifies how to mark a -date as being a holiday. Its value may be a single-character string -to insert next to the date, or a face name to use for displaying the -date. Likewise, the variable @code{diary-entry-marker} specifies how -to mark a date that has diary entries. The calendar creates faces -named @code{holiday-face} and @code{diary-face} for these purposes; -those symbols are the default values of these variables. - -@vindex calendar-load-hook - The variable @code{calendar-load-hook} is a normal hook run when the -calendar package is first loaded (before actually starting to display -the calendar). - -@vindex initial-calendar-window-hook - Starting the calendar runs the normal hook -@code{initial-calendar-window-hook}. Recomputation of the calendar -display does not run this hook. But if you leave the calendar with the -@kbd{q} command and reenter it, the hook runs again.@refill - -@vindex today-visible-calendar-hook - The variable @code{today-visible-calendar-hook} is a normal hook run -after the calendar buffer has been prepared with the calendar when the -current date is visible in the window. One use of this hook is to -replace today's date with asterisks; to do that, use the hook function -@code{calendar-star-date}. - -@findex calendar-star-date -@example -(add-hook 'today-visible-calendar-hook 'calendar-star-date) -@end example - -@noindent -Another standard hook function marks the current date, either by -changing its face or by adding an asterisk. Here's how to use it: - -@findex calendar-mark-today -@example -(add-hook 'today-visible-calendar-hook 'calendar-mark-today) -@end example - -@noindent -@vindex calendar-today-marker -The variable @code{calendar-today-marker} specifies how to mark -today's date. Its value should be a single-character string to insert -next to the date or a face name to use for displaying the date. A -face named @code{calendar-today-face} is provided for this purpose; -that symbol is the default for this variable. - -@vindex today-invisible-calendar-hook -@noindent - A similar normal hook, @code{today-invisible-calendar-hook} is run if -the current date is @emph{not} visible in the window. - -@vindex calendar-move-hook - Each of the calendar cursor motion commands runs the hook -@code{calendar-move-hook} after it moves the cursor. - -@node Holiday Customizing -@section Customizing the Holidays - -@vindex calendar-holidays -@vindex christian-holidays -@vindex hebrew-holidays -@vindex islamic-holidays - Emacs knows about holidays defined by entries on one of several lists. -You can customize these lists of holidays to your own needs, adding or -deleting holidays. The lists of holidays that Emacs uses are for -general holidays (@code{general-holidays}), local holidays -(@code{local-holidays}), Christian holidays (@code{christian-holidays}), -Hebrew (Jewish) holidays (@code{hebrew-holidays}), Islamic (Muslim) -holidays (@code{islamic-holidays}), and other holidays -(@code{other-holidays}). - -@vindex general-holidays - The general holidays are, by default, holidays common throughout the -United States. To eliminate these holidays, set @code{general-holidays} -to @code{nil}. - -@vindex local-holidays - There are no default local holidays (but sites may supply some). You -can set the variable @code{local-holidays} to any list of holidays, as -described below. - -@vindex all-christian-calendar-holidays -@vindex all-hebrew-calendar-holidays -@vindex all-islamic-calendar-holidays - By default, Emacs does not include all the holidays of the religions -that it knows, only those commonly found in secular calendars. For a -more extensive collection of religious holidays, you can set any (or -all) of the variables @code{all-christian-calendar-holidays}, -@code{all-hebrew-calendar-holidays}, or -@code{all-islamic-calendar-holidays} to @code{t}. If you want to -eliminate the religious holidays, set any or all of the corresponding -variables @code{christian-holidays}, @code{hebrew-holidays}, and -@code{islamic-holidays} to @code{nil}.@refill - -@vindex other-holidays - You can set the variable @code{other-holidays} to any list of -holidays. This list, normally empty, is intended for individual use. - -@cindex holiday forms - Each of the lists (@code{general-holidays}, @code{local-holidays}, -@code{christian-holidays}, @code{hebrew-holidays}, -@code{islamic-holidays}, and @code{other-holidays}) is a list of -@dfn{holiday forms}, each holiday form describing a holiday (or -sometimes a list of holidays). - - Here is a table of the possible kinds of holiday form. Day numbers -and month numbers count starting from 1, but ``dayname'' numbers -count Sunday as 0. The element @var{string} is always the -name of the holiday, as a string. - -@table @code -@item (holiday-fixed @var{month} @var{day} @var{string}) -A fixed date on the Gregorian calendar. - -@item (holiday-float @var{month} @var{dayname} @var{k} @var{string}) -The @var{k}th @var{dayname} in @var{month} on the Gregorian calendar -(@var{dayname}=0 for Sunday, and so on); negative @var{k} means count back -from the end of the month. - -@item (holiday-hebrew @var{month} @var{day} @var{string}) -A fixed date on the Hebrew calendar. - -@item (holiday-islamic @var{month} @var{day} @var{string}) -A fixed date on the Islamic calendar. - -@item (holiday-julian @var{month} @var{day} @var{string}) -A fixed date on the Julian calendar. - -@item (holiday-sexp @var{sexp} @var{string}) -A date calculated by the Lisp expression @var{sexp}. The expression -should use the variable @code{year} to compute and return the date of a -holiday, or @code{nil} if the holiday doesn't happen this year. The -value of @var{sexp} must represent the date as a list of the form -@code{(@var{month} @var{day} @var{year})}. - -@item (if @var{condition} @var{holiday-form}) -A holiday that happens only if @var{condition} is true. - -@item (@var{function} @r{[}@var{args}@r{]}) -A list of dates calculated by the function @var{function}, called with -arguments @var{args}. -@end table - - For example, suppose you want to add Bastille Day, celebrated in -France on July 14. You can do this as follows: - -@smallexample -(setq other-holidays '((holiday-fixed 7 14 "Bastille Day"))) -@end smallexample - -@noindent -The holiday form @code{(holiday-fixed 7 14 "Bastille Day")} specifies the -fourteenth day of the seventh month (July). - - Many holidays occur on a specific day of the week, at a specific time -of month. Here is a holiday form describing Hurricane Supplication Day, -celebrated in the Virgin Islands on the fourth Monday in August: - -@smallexample -(holiday-float 8 1 4 "Hurricane Supplication Day") -@end smallexample - -@noindent -Here the 8 specifies August, the 1 specifies Monday (Sunday is 0, -Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in -the month (1 specifies the first occurrence, 2 the second occurrence, -@minus{}1 the last occurrence, @minus{}2 the second-to-last occurrence, and -so on). - - You can specify holidays that occur on fixed days of the Hebrew, -Islamic, and Julian calendars too. For example, - -@smallexample -(setq other-holidays - '((holiday-hebrew 10 2 "Last day of Hanukkah") - (holiday-islamic 3 12 "Mohammed's Birthday") - (holiday-julian 4 2 "Jefferson's Birthday"))) -@end smallexample - -@noindent -adds the last day of Hanukkah (since the Hebrew months are numbered with -1 starting from Nisan), the Islamic feast celebrating Mohammed's -birthday (since the Islamic months are numbered from 1 starting with -Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the -Julian calendar. - - To include a holiday conditionally, use either Emacs Lisp's @code{if} or the -@code{holiday-sexp} form. For example, American presidential elections -occur on the first Tuesday after the first Monday in November of years -divisible by 4: - -@smallexample -(holiday-sexp '(if (= 0 (% year 4)) - (calendar-gregorian-from-absolute - (1+ (calendar-dayname-on-or-before - 1 (+ 6 (calendar-absolute-from-gregorian - (list 11 1 year))))))) - "US Presidential Election") -@end smallexample - -@noindent -or - -@smallexample -(if (= 0 (% displayed-year 4)) - (fixed 11 - (extract-calendar-day - (calendar-gregorian-from-absolute - (1+ (calendar-dayname-on-or-before - 1 (+ 6 (calendar-absolute-from-gregorian - (list 11 1 displayed-year))))))) - "US Presidential Election")) -@end smallexample - - Some holidays just don't fit into any of these forms because special -calculations are involved in their determination. In such cases you -must write a Lisp function to do the calculation. To include eclipses, -for example, add @code{(eclipses)} to @code{other-holidays} -and write an Emacs Lisp function @code{eclipses} that returns a -(possibly empty) list of the relevant Gregorian dates among the range -visible in the calendar window, with descriptive strings, like this: - -@smallexample -(((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... ) -@end smallexample - -@node Date Display Format -@section Date Display Format -@vindex calendar-date-display-form - - You can customize the manner of displaying dates in the diary, in mode -lines, and in messages by setting @code{calendar-date-display-form}. -This variable holds a list of expressions that can involve the variables -@code{month}, @code{day}, and @code{year}, which are all numbers in -string form, and @code{monthname} and @code{dayname}, which are both -alphabetic strings. In the American style, the default value of this -list is as follows: - -@smallexample -((if dayname (concat dayname ", ")) monthname " " day ", " year) -@end smallexample - -@noindent -while in the European style this value is the default: - -@smallexample -((if dayname (concat dayname ", ")) day " " monthname " " year) -@end smallexample - -@noindent -The ISO standard date representation is this: - -@smallexample -(year "-" month "-" day) -@end smallexample - -@noindent -This specifies a typical American format: - -@smallexample -(month "/" day "/" (substring year -2)) -@end smallexample - -@node Time Display Format -@section Time Display Format -@vindex calendar-time-display-form - - The calendar and diary by default display times of day in the -conventional American style with the hours from 1 through 12, minutes, -and either @samp{am} or @samp{pm}. If you prefer the European style, -also known in the US as military, in which the hours go from 00 to 23, -you can alter the variable @code{calendar-time-display-form}. This -variable is a list of expressions that can involve the variables -@code{12-hours}, @code{24-hours}, and @code{minutes}, which are all -numbers in string form, and @code{am-pm} and @code{time-zone}, which are -both alphabetic strings. The default value of -@code{calendar-time-display-form} is as follows: - -@smallexample -(12-hours ":" minutes am-pm - (if time-zone " (") time-zone (if time-zone ")")) -@end smallexample - -@noindent -Here is a value that provides European style times: - -@smallexample -(24-hours ":" minutes - (if time-zone " (") time-zone (if time-zone ")")) -@end smallexample - -@node Daylight Savings -@section Daylight Savings Time -@cindex daylight savings time - - Emacs understands the difference between standard time and daylight -savings time---the times given for sunrise, sunset, solstices, -equinoxes, and the phases of the moon take that into account. The rules -for daylight savings time vary from place to place and have also varied -historically from year to year. To do the job properly, Emacs needs to -know which rules to use. - - Some operating systems keep track of the rules that apply to the place -where you are; on these systems, Emacs gets the information it needs -from the system automatically. If some or all of this information is -missing, Emacs fills in the gaps with the rules currently used in -Cambridge, Massachusetts, which is the center of GNU's world. - - -@vindex calendar-daylight-savings-starts -@vindex calendar-daylight-savings-ends - If the default choice of rules is not appropriate for your location, -you can tell Emacs the rules to use by setting the variables -@code{calendar-daylight-savings-starts} and -@code{calendar-daylight-savings-ends}. Their values should be Lisp -expressions that refer to the variable @code{year}, and evaluate to the -Gregorian date on which daylight savings time starts or (respectively) -ends, in the form of a list @code{(@var{month} @var{day} @var{year})}. -The values should be @code{nil} if your area does not use daylight -savings time. - - Emacs uses these expressions to determine the start and end dates of -daylight savings time as holidays and for correcting times of day in the -solar and lunar calculations. - - The values for Cambridge, Massachusetts are as follows: - -@example -@group -(calendar-nth-named-day 1 0 4 year) -(calendar-nth-named-day -1 0 10 year) -@end group -@end example - -@noindent -i.e., the first 0th day (Sunday) of the fourth month (April) in -the year specified by @code{year}, and the last Sunday of the tenth month -(October) of that year. If daylight savings time were -changed to start on October 1, you would set -@code{calendar-daylight-savings-starts} to this: - -@example -(list 10 1 year) -@end example - - For a more complex example, suppose daylight savings time begins on -the first of Nisan on the Hebrew calendar. You should set -@code{calendar-daylight-savings-starts} to this value: - -@example -(calendar-gregorian-from-absolute - (calendar-absolute-from-hebrew - (list 1 1 (+ year 3760)))) -@end example - -@noindent -because Nisan is the first month in the Hebrew calendar and the Hebrew -year differs from the Gregorian year by 3760 at Nisan. - - If there is no daylight savings time at your location, or if you want -all times in standard time, set @code{calendar-daylight-savings-starts} -and @code{calendar-daylight-savings-ends} to @code{nil}. - -@vindex calendar-daylight-time-offset - The variable @code{calendar-daylight-time-offset} specifies the -difference between daylight savings time and standard time, measured in -minutes. The value for Cambridge is 60. - -@vindex calendar-daylight-savings-starts-time -@vindex calendar-daylight-savings-ends-time - The variable @code{calendar-daylight-savings-starts-time} and the -variable @code{calendar-daylight-savings-ends-time} specify the number -of minutes after midnight local time when the transition to and from -daylight savings time should occur. For Cambridge, both variables' -values are 120. - -@node Diary Customizing -@section Customizing the Diary - -@vindex holidays-in-diary-buffer - Ordinarily, the mode line of the diary buffer window indicates any -holidays that fall on the date of the diary entries. The process of -checking for holidays can take several seconds, so including holiday -information delays the display of the diary buffer noticeably. If you'd -prefer to have a faster display of the diary buffer but without the -holiday information, set the variable @code{holidays-in-diary-buffer} to -@code{nil}.@refill - -@vindex number-of-diary-entries - The variable @code{number-of-diary-entries} controls the number of -days of diary entries to be displayed at one time. It affects the -initial display when @code{view-diary-entries-initially} is @code{t}, as -well as the command @kbd{M-x diary}. For example, the default value is -1, which says to display only the current day's diary entries. If the -value is 2, both the current day's and the next day's entries are -displayed. The value can also be a vector of seven elements: for -example, if the value is @code{[0 2 2 2 2 4 1]} then no diary entries -appear on Sunday, the current date's and the next day's diary entries -appear Monday through Thursday, Friday through Monday's entries appear -on Friday, while on Saturday only that day's entries appear. - -@vindex print-diary-entries-hook -@findex print-diary-entries - The variable @code{print-diary-entries-hook} is a normal hook run -after preparation of a temporary buffer containing just the diary -entries currently visible in the diary buffer. (The other, irrelevant -diary entries are really absent from the temporary buffer; in the diary -buffer, they are merely hidden.) The default value of this hook does -the printing with the command @code{lpr-buffer}. If you want to use a -different command to do the printing, just change the value of this -hook. Other uses might include, for example, rearranging the lines into -order by day and time. - -@vindex diary-date-forms - You can customize the form of dates in your diary file, if neither the -standard American nor European styles suits your needs, by setting the -variable @code{diary-date-forms}. This variable is a list of patterns -for recognizing a date. Each date pattern is a list whose elements may -be regular expressions (@pxref{Regular Expressions,,, elisp, the Emacs -Lisp Reference Manual}) or the symbols @code{month}, @code{day}, -@code{year}, @code{monthname}, and @code{dayname}. All these elements -serve as patterns that match certain kinds of text in the diary file. -In order for the date pattern, as a whole, to match, all of its elements -must match consecutively. - - A regular expression in a date pattern matches in its usual fashion, -using the standard syntax table altered so that @samp{*} is a word -constituent. - - The symbols @code{month}, @code{day}, @code{year}, @code{monthname}, -and @code{dayname} match the month number, day number, year number, -month name, and day name of the date being considered. The symbols that -match numbers allow leading zeros; those that match names allow -three-letter abbreviations and capitalization. All the symbols can -match @samp{*}; since @samp{*} in a diary entry means ``any day'', ``any -month'', and so on, it should match regardless of the date being -considered. - - The default value of @code{diary-date-forms} in the American style is -this: - -@example -((month "/" day "[^/0-9]") - (month "/" day "/" year "[^0-9]") - (monthname " *" day "[^,0-9]") - (monthname " *" day ", *" year "[^0-9]") - (dayname "\\W")) -@end example - - The date patterns in the list must be @emph{mutually exclusive} and -must not match any portion of the diary entry itself, just the date and -one character of whitespace. If, to be mutually exclusive, the pattern -must match a portion of the diary entry text---beyond the whitespace -that ends the date---then the first element of the date pattern -@emph{must} be @code{backup}. This causes the date recognizer to back -up to the beginning of the current word of the diary entry, after -finishing the match. Even if you use @code{backup}, the date pattern -must absolutely not match more than a portion of the first word of the -diary entry. The default value of @code{diary-date-forms} in the -European style is this list: - -@example -((day "/" month "[^/0-9]") - (day "/" month "/" year "[^0-9]") - (backup day " *" monthname "\\W+\\<[^*0-9]") - (day " *" monthname " *" year "[^0-9]") - (dayname "\\W")) -@end example - -@noindent -Notice the use of @code{backup} in the third pattern, because it needs -to match part of a word beyond the date itself to distinguish it from -the fourth pattern. - -@node Hebrew/Islamic Entries -@section Hebrew- and Islamic-Date Diary Entries - - Your diary file can have entries based on Hebrew or Islamic dates, as -well as entries based on the world-standard Gregorian calendar. -However, because recognition of such entries is time-consuming and most -people don't use them, you must explicitly enable their use. If you -want the diary to recognize Hebrew-date diary entries, for example, -you must do this: - -@vindex nongregorian-diary-listing-hook -@vindex nongregorian-diary-marking-hook -@findex list-hebrew-diary-entries -@findex mark-hebrew-diary-entries -@smallexample -(add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries) -(add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries) -@end smallexample - -@noindent -If you want Islamic-date entries, do this: - -@findex list-islamic-diary-entries -@findex mark-islamic-diary-entries -@smallexample -(add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries) -(add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-entries) -@end smallexample - - Hebrew- and Islamic-date diary entries have the same formats as -Gregorian-date diary entries, except that @samp{H} precedes a Hebrew -date and @samp{I} precedes an Islamic date. Moreover, because the -Hebrew and Islamic month names are not uniquely specified by the first -three letters, you may not abbreviate them. For example, a diary entry -for the Hebrew date Heshvan 25 could look like this: - -@smallexample -HHeshvan 25 Happy Hebrew birthday! -@end smallexample - -@noindent -and would appear in the diary for any date that corresponds to Heshvan 25 -on the Hebrew calendar. And here is an Islamic-date diary entry that matches -Dhu al-Qada 25: - -@smallexample -IDhu al-Qada 25 Happy Islamic birthday! -@end smallexample - - As with Gregorian-date diary entries, Hebrew- and Islamic-date entries -are nonmarking if they are preceded with an ampersand (@samp{&}). - - Here is a table of commands used in the calendar to create diary entries -that match the selected date and other dates that are similar in the Hebrew -or Islamic calendar: - -@table @kbd -@item i h d -Add a diary entry for the Hebrew date corresponding to the selected date -(@code{insert-hebrew-diary-entry}). -@item i h m -Add a diary entry for the day of the Hebrew month corresponding to the -selected date (@code{insert-monthly-hebrew-diary-entry}). This diary -entry matches any date that has the same Hebrew day-within-month as the -selected date. -@item i h y -Add a diary entry for the day of the Hebrew year corresponding to the -selected date (@code{insert-yearly-hebrew-diary-entry}). This diary -entry matches any date which has the same Hebrew month and day-within-month -as the selected date. -@item i i d -Add a diary entry for the Islamic date corresponding to the selected date -(@code{insert-islamic-diary-entry}). -@item i i m -Add a diary entry for the day of the Islamic month corresponding to the -selected date (@code{insert-monthly-islamic-diary-entry}). -@item i i y -Add a diary entry for the day of the Islamic year corresponding to the -selected date (@code{insert-yearly-islamic-diary-entry}). -@end table - -@findex insert-hebrew-diary-entry -@findex insert-monthly-hebrew-diary-entry -@findex insert-yearly-hebrew-diary-entry -@findex insert-islamic-diary-entry -@findex insert-monthly-islamic-diary-entry -@findex insert-yearly-islamic-diary-entry - These commands work much like the corresponding commands for ordinary -diary entries: they apply to the date that point is on in the calendar -window, and what they do is insert just the date portion of a diary entry -at the end of your diary file. You must then insert the rest of the -diary entry. - -@node Fancy Diary Display -@section Fancy Diary Display -@vindex diary-display-hook -@findex simple-diary-display - - Diary display works by preparing the diary buffer and then running the -hook @code{diary-display-hook}. The default value of this hook -(@code{simple-diary-display}) hides the irrelevant diary entries and -then displays the buffer. However, if you specify the hook as follows, - -@cindex diary buffer -@findex fancy-diary-display -@example -(add-hook 'diary-display-hook 'fancy-diary-display) -@end example - -@noindent -this enables fancy diary display. It displays diary entries and -holidays by copying them into a special buffer that exists only for the -sake of display. Copying to a separate buffer provides an opportunity -to change the displayed text to make it prettier---for example, to sort -the entries by the dates they apply to. - - As with simple diary display, you can print a hard copy of the buffer -with @code{print-diary-entries}. To print a hard copy of a day-by-day -diary for a week, position point on Sunday of that week, type -@kbd{7 d}, and then do @kbd{M-x print-diary-entries}. As usual, the -inclusion of the holidays slows down the display slightly; you can speed -things up by setting the variable @code{holidays-in-diary-buffer} to -@code{nil}. - -@vindex diary-list-include-blanks - Ordinarily, the fancy diary buffer does not show days for which there are -no diary entries, even if that day is a holiday. If you want such days to be -shown in the fancy diary buffer, set the variable -@code{diary-list-include-blanks} to @code{t}.@refill - -@cindex sorting diary entries - If you use the fancy diary display, you can use the normal hook -@code{list-diary-entries-hook} to sort each day's diary entries by their -time of day. Here's how: - -@findex sort-diary-entries -@example -(add-hook 'list-diary-entries-hook 'sort-diary-entries t) -@end example - -@noindent -For each day, this sorts diary entries that begin with a recognizable -time of day according to their times. Diary entries without times come -first within each day. - - Fancy diary display also has the ability to process included diary -files. This permits a group of people to share a diary file for events -that apply to all of them. Lines in the diary file of this form: - -@smallexample -#include "@var{filename}" -@end smallexample - -@noindent -includes the diary entries from the file @var{filename} in the fancy -diary buffer. The include mechanism is recursive, so that included files -can include other files, and so on; you must be careful not to have a -cycle of inclusions, of course. Here is how to enable the include -facility: - -@vindex list-diary-entries-hook -@vindex mark-diary-entries-hook -@findex include-other-diary-files -@findex mark-included-diary-files -@smallexample -(add-hook 'list-diary-entries-hook 'include-other-diary-files) -(add-hook 'mark-diary-entries-hook 'mark-included-diary-files) -@end smallexample - -The include mechanism works only with the fancy diary display, because -ordinary diary display shows the entries directly from your diary file. - -@node Sexp Diary Entries -@section Sexp Entries and the Fancy Diary Display -@cindex sexp diary entries - - Sexp diary entries allow you to do more than just have complicated -conditions under which a diary entry applies. If you use the fancy -diary display, sexp entries can generate the text of the entry depending -on the date itself. For example, an anniversary diary entry can insert -the number of years since the anniversary date into the text of the -diary entry. Thus the @samp{%d} in this dairy entry: - -@findex diary-anniversary -@smallexample -%%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old) -@end smallexample - -@noindent -gets replaced by the age, so on October 31, 1990 the entry appears in -the fancy diary buffer like this: - -@smallexample -Arthur's birthday (42 years old) -@end smallexample - -@noindent -If the diary file instead contains this entry: - -@smallexample -%%(diary-anniversary 10 31 1948) Arthur's %d%s birthday -@end smallexample - -@noindent -the entry in the fancy diary buffer for October 31, 1990 appears like this: - -@smallexample -Arthur's 42nd birthday -@end smallexample - - Similarly, cyclic diary entries can interpolate the number of repetitions -that have occurred: - -@findex diary-cyclic -@smallexample -%%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time) -@end smallexample - -@noindent -looks like this: - -@smallexample -Renew medication (5th time) -@end smallexample - -@noindent -in the fancy diary display on September 8, 1990. - - There is an early reminder diary sexp that includes its entry in the -diary not only on the date of occurrence, but also on earlier dates. -For example, if you want a reminder a week before your anniversary, you -can use - -@findex diary-remind -@smallexample -%%(diary-remind '(diary-anniversary 12 22 1968) 7) Ed's anniversary -@end smallexample - -@noindent -and the fancy diary will show -@smallexample -Ed's anniversary -@end smallexample -@noindent -both on December 15 and on December 22. - -@findex diary-date - The function @code{diary-date} applies to dates described by a month, -day, year combination, each of which can be an integer, a list of -integers, or @code{t}. The value @code{t} means all values. For -example, - -@smallexample -%%(diary-date '(10 11 12) 22 t) Rake leaves -@end smallexample - -@noindent -causes the fancy diary to show - -@smallexample -Rake leaves -@end smallexample - -@noindent -on October 22, November 22, and December 22 of every year. - -@findex diary-float - The function @code{diary-float} allows you to describe diary entries -that apply to dates like the third Friday of November, or the last -Tuesday in April. The parameters are the @var{month}, @var{dayname}, -and an index @var{n}. The entry appears on the @var{n}th @var{dayname} -of @var{month}, where @var{dayname}=0 means Sunday, 1 means Monday, and -so on. If @var{n} is negative it counts backward from the end of -@var{month}. The value of @var{month} can be a list of months, a single -month, or @code{t} to specify all months. You can also use an optional -parameter @var{day} to specify the @var{n}th @var{dayname} of -@var{month} on or after/before @var{day}; the value of @var{day} defaults -to 1 if @var{n} is positive and to the last day of @var{month} if -@var{n} is negative. For example, - -@smallexample -%%(diary-float t 1 -1) Pay rent -@end smallexample - -@noindent -causes the fancy diary to show - -@smallexample -Pay rent -@end smallexample - -@noindent -on the last Monday of every month. - - The generality of sexp diary entries lets you specify any diary -entry that you can describe algorithmically. A sexp diary entry -contains an expression that computes whether the entry applies to any -given date. If its value is non-@code{nil}, the entry applies to that -date; otherwise, it does not. The expression can use the variable -@code{date} to find the date being considered; its value is a list -(@var{month} @var{day} @var{year}) that refers to the Gregorian -calendar. - - The sexp diary entry applies to a date when the expression's value -is non-@code{nil}, but some values have more specific meanings. If -the value is a string, that string is a description of the event which -occurs on that date. The value can also have the form -@code{(@var{mark} . @var{string})}; then @var{mark} specifies how to -mark the date in the calendar, and @var{string} is the description of -the event. If @var{mark} is a single-character string, that character -appears next to the date in the calendar. If @var{mark} is a face -name, the date is displayed in that face. If @var{mark} is -@code{nil}, that specifies no particular highlighting for the date. - - Suppose you get paid on the 21st of the month if it is a weekday, and -on the Friday before if the 21st is on a weekend. Here is how to write -a sexp diary entry that matches those dates: - -@smallexample -&%%(let ((dayname (calendar-day-of-week date)) - (day (car (cdr date)))) - (or (and (= day 21) (memq dayname '(1 2 3 4 5))) - (and (memq day '(19 20)) (= dayname 5))) - ) Pay check deposited -@end smallexample - - The following sexp diary entries take advantage of the ability (in the fancy -diary display) to concoct diary entries whose text varies based on the date: - -@findex diary-sunrise-sunset -@findex diary-phases-of-moon -@findex diary-day-of-year -@findex diary-iso-date -@findex diary-julian-date -@findex diary-astro-day-number -@findex diary-hebrew-date -@findex diary-islamic-date -@findex diary-french-date -@findex diary-mayan-date -@table @code -@item %%(diary-sunrise-sunset) -Make a diary entry for the local times of today's sunrise and sunset. -@item %%(diary-phases-of-moon) -Make a diary entry for the phases (quarters) of the moon. -@item %%(diary-day-of-year) -Make a diary entry with today's day number in the current year and the number -of days remaining in the current year. -@item %%(diary-iso-date) -Make a diary entry with today's equivalent ISO commercial date. -@item %%(diary-julian-date) -Make a diary entry with today's equivalent date on the Julian calendar. -@item %%(diary-astro-day-number) -Make a diary entry with today's equivalent astronomical (Julian) day number. -@item %%(diary-hebrew-date) -Make a diary entry with today's equivalent date on the Hebrew calendar. -@item %%(diary-islamic-date) -Make a diary entry with today's equivalent date on the Islamic calendar. -@item %%(diary-french-date) -Make a diary entry with today's equivalent date on the French Revolutionary -calendar. -@item %%(diary-mayan-date) -Make a diary entry with today's equivalent date on the Mayan calendar. -@end table - -@noindent -Thus including the diary entry - -@example -&%%(diary-hebrew-date) -@end example - -@noindent -causes every day's diary display to contain the equivalent date on the -Hebrew calendar, if you are using the fancy diary display. (With simple -diary display, the line @samp{&%%(diary-hebrew-date)} appears in the -diary for any date, but does nothing particularly useful.) - - These functions can be used to construct sexp diary entries based on -the Hebrew calendar in certain standard ways: - -@cindex rosh hodesh -@findex diary-rosh-hodesh -@cindex parasha, weekly -@findex diary-parasha -@cindex candle lighting times -@findex diary-sabbath-candles -@cindex omer count -@findex diary-omer -@cindex yahrzeits -@findex diary-yahrzeit -@table @code -@item %%(diary-rosh-hodesh) -Make a diary entry that tells the occurrence and ritual announcement of each -new Hebrew month. -@item %%(diary-parasha) -Make a Saturday diary entry that tells the weekly synagogue scripture reading. -@item %%(diary-sabbath-candles) -Make a Friday diary entry that tells the @emph{local time} of Sabbath -candle lighting. -@item %%(diary-omer) -Make a diary entry that gives the omer count, when appropriate. -@item %%(diary-yahrzeit @var{month} @var{day} @var{year}) @var{name} -Make a diary entry marking the anniversary of a date of death. The date -is the @emph{Gregorian} (civil) date of death. The diary entry appears -on the proper Hebrew calendar anniversary and on the day before. (In -the European style, the order of the parameters is changed to @var{day}, -@var{month}, @var{year}.) -@end table - - All the functions documented above take an optional argument -@var{mark} which specifies how to mark the date in the calendar display. -If one of these functions decides that it applies to a certain date, -it returns a value that contains @var{mark}. - -@node Emerge -@chapter Merging Files with Emerge -@cindex Emerge -@cindex merging files - - It's not unusual for programmers to get their signals crossed and -modify the same program in two different directions. To recover from -this confusion, you need to merge the two versions. Emerge makes this -easier. For other ways to compare files, see @ref{Comparing Files,,, -emacs, the Emacs Manual} and @ref{Top, Ediff,, ediff, The Ediff -Manual}. - -@menu -* Overview of Emerge:: How to start Emerge. Basic concepts. -* Submodes of Emerge:: Fast mode vs. Edit mode. - Skip Prefers mode and Auto Advance mode. -* State of Difference:: You do the merge by specifying state A or B - for each difference. -* Merge Commands:: Commands for selecting a difference, - changing states of differences, etc. -* Exiting Emerge:: What to do when you've finished the merge. -* Combining in Emerge:: How to keep both alternatives for a difference. -* Fine Points of Emerge:: Misc. -@end menu - -@node Overview of Emerge -@section Overview of Emerge - - To start Emerge, run one of these four commands: - -@table @kbd -@item M-x emerge-files -@findex emerge-files -Merge two specified files. - -@item M-x emerge-files-with-ancestor -@findex emerge-files-with-ancestor -Merge two specified files, with reference to a common ancestor. - -@item M-x emerge-buffers -@findex emerge-buffers -Merge two buffers. - -@item M-x emerge-buffers-with-ancestor -@findex emerge-buffers-with-ancestor -Merge two buffers with reference to a common ancestor in a third -buffer. -@end table - -@cindex merge buffer (Emerge) -@cindex A and B buffers (Emerge) - The Emerge commands compare two files or buffers, and display the -comparison in three buffers: one for each input text (the @dfn{A buffer} -and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging -takes place. The merge buffer shows the full merged text, not just the -differences. Wherever the two input texts differ, you can choose which -one of them to include in the merge buffer. - - The Emerge commands that take input from existing buffers use only -the accessible portions of those buffers, if they are narrowed. -@xref{Narrowing,,, emacs, the Emacs Manual}. - - - If a common ancestor version is available, from which the two texts to -be merged were both derived, Emerge can use it to guess which -alternative is right. Wherever one current version agrees with the -ancestor, Emerge presumes that the other current version is a deliberate -change which should be kept in the merged version. Use the -@samp{with-ancestor} commands if you want to specify a common ancestor -text. These commands read three file or buffer names---variant A, -variant B, and the common ancestor. - - After the comparison is done and the buffers are prepared, the -interactive merging starts. You control the merging by typing special -@dfn{merge commands} in the merge buffer (@pxref{Merge Commands}). -For each run of differences between the input texts, you can choose -which one of them to keep, or edit them both together. - - The merge buffer uses a special major mode, Emerge mode, with commands -for making these choices. But you can also edit the buffer with -ordinary Emacs commands. - - At any given time, the attention of Emerge is focused on one -particular difference, called the @dfn{selected} difference. This -difference is marked off in the three buffers like this: - -@example -vvvvvvvvvvvvvvvvvvvv -@var{text that differs} -^^^^^^^^^^^^^^^^^^^^ -@end example - -@noindent -Emerge numbers all the differences sequentially and the mode -line always shows the number of the selected difference. - - Normally, the merge buffer starts out with the A version of the text. -But when the A version of a difference agrees with the common ancestor, -then the B version is initially preferred for that difference. - - Emerge leaves the merged text in the merge buffer when you exit. At -that point, you can save it in a file with @kbd{C-x C-w}. If you give a -numeric argument to @code{emerge-files} or -@code{emerge-files-with-ancestor}, it reads the name of the output file -using the minibuffer. (This is the last file name those commands read.) -Then exiting from Emerge saves the merged text in the output file. - - Normally, Emerge commands save the output buffer in its file when you -exit. If you abort Emerge with @kbd{C-]}, the Emerge command does not -save the output buffer, but you can save it yourself if you wish. - -@node Submodes of Emerge -@section Submodes of Emerge - - You can choose between two modes for giving merge commands: Fast mode -and Edit mode. In Fast mode, basic merge commands are single -characters, but ordinary Emacs commands are disabled. This is -convenient if you use only merge commands. In Edit mode, all merge -commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs -commands are also available. This allows editing the merge buffer, but -slows down Emerge operations. - - Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to -Fast mode. The mode line indicates Edit and Fast modes with @samp{E} -and @samp{F}. - - Emerge has two additional submodes that affect how particular merge -commands work: Auto Advance mode and Skip Prefers mode. - - If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands -advance to the next difference. This lets you go through the merge -faster as long as you simply choose one of the alternatives from the -input. The mode line indicates Auto Advance mode with @samp{A}. - - If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands -skip over differences in states prefer-A and prefer-B (@pxref{State of -Difference}). Thus you see only differences for which neither version -is presumed ``correct.'' The mode line indicates Skip Prefers mode with -@samp{S}. - -@findex emerge-auto-advance-mode -@findex emerge-skip-prefers-mode - Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or -clear Auto Advance mode. Use @kbd{s s} -(@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode. -These commands turn on the mode with a positive argument, turns it off -with a negative or zero argument, and toggle the mode with no argument. - -@node State of Difference -@section State of a Difference - - In the merge buffer, a difference is marked with lines of @samp{v} and -@samp{^} characters. Each difference has one of these seven states: - -@table @asis -@item A -The difference is showing the A version. The @kbd{a} command always -produces this state; the mode line indicates it with @samp{A}. - -@item B -The difference is showing the B version. The @kbd{b} command always -produces this state; the mode line indicates it with @samp{B}. - -@item default-A -@itemx default-B -The difference is showing the A or the B state by default, because you -haven't made a choice. All differences start in the default-A state -(and thus the merge buffer is a copy of the A buffer), except those for -which one alternative is ``preferred'' (see below). - -When you select a difference, its state changes from default-A or -default-B to plain A or B. Thus, the selected difference never has -state default-A or default-B, and these states are never displayed in -the mode line. - -The command @kbd{d a} chooses default-A as the default state, and @kbd{d -b} chooses default-B. This chosen default applies to all differences -which you haven't ever selected and for which no alternative is preferred. -If you are moving through the merge sequentially, the differences you -haven't selected are those following the selected one. Thus, while -moving sequentially, you can effectively make the A version the default -for some sections of the merge buffer and the B version the default for -others by using @kbd{d a} and @kbd{d b} between sections. - -@item prefer-A -@itemx prefer-B -The difference is showing the A or B state because it is -@dfn{preferred}. This means that you haven't made an explicit choice, -but one alternative seems likely to be right because the other -alternative agrees with the common ancestor. Thus, where the A buffer -agrees with the common ancestor, the B version is preferred, because -chances are it is the one that was actually changed. - -These two states are displayed in the mode line as @samp{A*} and @samp{B*}. - -@item combined -The difference is showing a combination of the A and B states, as a -result of the @kbd{x c} or @kbd{x C} commands. - -Once a difference is in this state, the @kbd{a} and @kbd{b} commands -don't do anything to it unless you give them a numeric argument. - -The mode line displays this state as @samp{comb}. -@end table - -@node Merge Commands -@section Merge Commands - - Here are the Merge commands for Fast mode; in Edit mode, precede them -with @kbd{C-c C-c}: - -@table @kbd -@item p -Select the previous difference. - -@item n -Select the next difference. - -@item a -Choose the A version of this difference. - -@item b -Choose the B version of this difference. - -@item C-u @var{n} j -Select difference number @var{n}. - -@item . -Select the difference containing point. You can use this command in the -merge buffer or in the A or B buffer. - -@item q -Quit---finish the merge. - -@item C-] -Abort---exit merging and do not save the output. - -@item f -Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.) - -@item e -Go into Edit mode. - -@item l -Recenter (like @kbd{C-l}) all three windows. - -@item - -Specify part of a prefix numeric argument. - -@item @var{digit} -Also specify part of a prefix numeric argument. - -@item d a -Choose the A version as the default from here down in -the merge buffer. - -@item d b -Choose the B version as the default from here down in -the merge buffer. - -@item c a -Copy the A version of this difference into the kill ring. - -@item c b -Copy the B version of this difference into the kill ring. - -@item i a -Insert the A version of this difference at point. - -@item i b -Insert the B version of this difference at point. - -@item m -Put point and mark around the difference. - -@item ^ -Scroll all three windows down (like @kbd{M-v}). - -@item v -Scroll all three windows up (like @kbd{C-v}). - -@item < -Scroll all three windows left (like @kbd{C-x <}). - -@item > -Scroll all three windows right (like @kbd{C-x >}). - -@item | -Reset horizontal scroll on all three windows. - -@item x 1 -Shrink the merge window to one line. (Use @kbd{C-u l} to restore it -to full size.) - -@item x c -Combine the two versions of this difference (@pxref{Combining in -Emerge}). - -@item x f -Show the names of the files/buffers Emerge is operating on, in a Help -window. (Use @kbd{C-u l} to restore windows.) - -@item x j -Join this difference with the following one. -(@kbd{C-u x j} joins this difference with the previous one.) - -@item x s -Split this difference into two differences. Before you use this -command, position point in each of the three buffers at the place where -you want to split the difference. - -@item x t -Trim identical lines off the top and bottom of the difference. -Such lines occur when the A and B versions are -identical but differ from the ancestor version. -@end table - -@node Exiting Emerge -@section Exiting Emerge - - The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing -the results into the output file if you specified one. It restores the -A and B buffers to their proper contents, or kills them if they were -created by Emerge and you haven't changed them. It also disables the -Emerge commands in the merge buffer, since executing them later could -damage the contents of the various buffers. - - @kbd{C-]} aborts the merge. This means exiting without writing the -output file. If you didn't specify an output file, then there is no -real difference between aborting and finishing the merge. - - If the Emerge command was called from another Lisp program, then its -return value is @code{t} for successful completion, or @code{nil} if you -abort. - -@node Combining in Emerge -@section Combining the Two Versions - - Sometimes you want to keep @emph{both} alternatives for a particular -difference. To do this, use @kbd{x c}, which edits the merge buffer -like this: - -@example -@group -#ifdef NEW -@var{version from A buffer} -#else /* not NEW */ -@var{version from B buffer} -#endif /* not NEW */ -@end group -@end example - -@noindent -@vindex emerge-combine-versions-template -While this example shows C preprocessor conditionals delimiting the two -alternative versions, you can specify the strings to use by setting -the variable @code{emerge-combine-versions-template} to a string of your -choice. In the string, @samp{%a} says where to put version A, and -@samp{%b} says where to put version B. The default setting, which -produces the results shown above, looks like this: - -@example -@group -"#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n" -@end group -@end example - -@node Fine Points of Emerge -@section Fine Points of Emerge - - During the merge, you mustn't try to edit the A and B buffers yourself. -Emerge modifies them temporarily, but ultimately puts them back the way -they were. - - You can have any number of merges going at once---just don't use any one -buffer as input to more than one merge at once, since the temporary -changes made in these buffers would get in each other's way. - - Starting Emerge can take a long time because it needs to compare the -files fully. Emacs can't do anything else until @code{diff} finishes. -Perhaps in the future someone will change Emerge to do the comparison in -the background when the input files are large---then you could keep on -doing other things with Emacs until Emerge is ready to accept -commands. - -@vindex emerge-startup-hook - After setting up the merge, Emerge runs the hook -@code{emerge-startup-hook}. @xref{Hooks,,, emacs, the Emacs Manual}. - -@node Picture Mode -@chapter Editing Pictures -@cindex pictures -@cindex making pictures out of text characters -@findex edit-picture - - To edit a picture made out of text characters (for example, a picture -of the division of a register into fields, as a comment in a program), -use the command @kbd{M-x edit-picture} to enter Picture mode. - - In Picture mode, editing is based on the @dfn{quarter-plane} model of -text, according to which the text characters lie studded on an area that -stretches infinitely far to the right and downward. The concept of the end -of a line does not exist in this model; the most you can say is where the -last nonblank character on the line is found. - - Of course, Emacs really always considers text as a sequence of -characters, and lines really do have ends. But Picture mode replaces -the most frequently-used commands with variants that simulate the -quarter-plane model of text. They do this by inserting spaces or by -converting tabs to spaces. - - Most of the basic editing commands of Emacs are redefined by Picture mode -to do essentially the same thing but in a quarter-plane way. In addition, -Picture mode defines various keys starting with the @kbd{C-c} prefix to -run special picture editing commands. - - One of these keys, @kbd{C-c C-c}, is particularly important. Often a -picture is part of a larger file that is usually edited in some other -major mode. @kbd{M-x edit-picture} records the name of the previous -major mode so you can use the @kbd{C-c C-c} command -(@code{picture-mode-exit}) later to go back to that mode. @kbd{C-c C-c} -also deletes spaces from the ends of lines, unless given a numeric -argument. - - The special commands of Picture mode all work in other modes (provided -the @file{picture} library is loaded), but are not bound to keys except -in Picture mode. The descriptions below talk of moving ``one column'' -and so on, but all the picture mode commands handle numeric arguments as -their normal equivalents do. - -@vindex picture-mode-hook - Turning on Picture mode runs the hook @code{picture-mode-hook}. -Additional extensions to Picture mode can be found in -@file{artist.el}. - -@menu -* Basic Picture:: Basic concepts and simple commands of Picture Mode. -* Insert in Picture:: Controlling direction of cursor motion - after "self-inserting" characters. -* Tabs in Picture:: Various features for tab stops and indentation. -* Rectangles in Picture:: Clearing and superimposing rectangles. -@end menu - -@node Basic Picture -@section Basic Editing in Picture Mode - -@findex picture-forward-column -@findex picture-backward-column -@findex picture-move-down -@findex picture-move-up -@cindex editing in Picture mode - - Most keys do the same thing in Picture mode that they usually do, but -do it in a quarter-plane style. For example, @kbd{C-f} is rebound to -run @code{picture-forward-column}, a command which moves point one -column to the right, inserting a space if necessary so that the actual -end of the line makes no difference. @kbd{C-b} is rebound to run -@code{picture-backward-column}, which always moves point left one -column, converting a tab to multiple spaces if necessary. @kbd{C-n} and -@kbd{C-p} are rebound to run @code{picture-move-down} and -@code{picture-move-up}, which can either insert spaces or convert tabs -as necessary to make sure that point stays in exactly the same column. -@kbd{C-e} runs @code{picture-end-of-line}, which moves to after the last -nonblank character on the line. There is no need to change @kbd{C-a}, -as the choice of screen model does not affect beginnings of -lines. - -@findex picture-newline - Insertion of text is adapted to the quarter-plane screen model -through the use of Overwrite mode (@pxref{Minor Modes,,, emacs, the -Emacs Manual}.) Self-inserting characters replace existing text, -column by column, rather than pushing existing text to the right. -@key{RET} runs @code{picture-newline}, which just moves to the -beginning of the following line so that new text will replace that -line. - -@findex picture-backward-clear-column -@findex picture-clear-column -@findex picture-clear-line - In Picture mode, the commands that normally delete or kill text, -instead erase text (replacing it with spaces). @key{DEL} -(@code{picture-backward-clear-column}) replaces the preceding -character with a space rather than removing it; this moves point -backwards. @kbd{C-d} (@code{picture-clear-column}) replaces the next -character or characters with spaces, but does not move point. (If you -want to clear characters to spaces and move forward over them, use -@key{SPC}.) @kbd{C-k} (@code{picture-clear-line}) really kills the -contents of lines, but does not delete the newlines from the buffer. - -@findex picture-open-line - To do actual insertion, you must use special commands. @kbd{C-o} -(@code{picture-open-line}) creates a blank line after the current -line; it never splits a line. @kbd{C-M-o} (@code{split-line}) makes -sense in Picture mode, so it is not changed. @kbd{C-j} -(@code{picture-duplicate-line}) inserts another line with the same -contents below the current line. - -@kindex C-c C-d @r{(Picture mode)} - To do actual deletion in Picture mode, use @kbd{C-w}, @kbd{C-c C-d} -(which is defined as @code{delete-char}, as @kbd{C-d} is in other -modes), or one of the picture rectangle commands (@pxref{Rectangles in -Picture}). - -@node Insert in Picture -@section Controlling Motion after Insert - -@findex picture-movement-up -@findex picture-movement-down -@findex picture-movement-left -@findex picture-movement-right -@findex picture-movement-nw -@findex picture-movement-ne -@findex picture-movement-sw -@findex picture-movement-se -@kindex C-c < @r{(Picture mode)} -@kindex C-c > @r{(Picture mode)} -@kindex C-c ^ @r{(Picture mode)} -@kindex C-c . @r{(Picture mode)} -@kindex C-c ` @r{(Picture mode)} -@kindex C-c ' @r{(Picture mode)} -@kindex C-c / @r{(Picture mode)} -@kindex C-c \ @r{(Picture mode)} - Since ``self-inserting'' characters in Picture mode overwrite and move -point, there is no essential restriction on how point should be moved. -Normally point moves right, but you can specify any of the eight -orthogonal or diagonal directions for motion after a ``self-inserting'' -character. This is useful for drawing lines in the buffer. - -@table @kbd -@item C-c < -@itemx C-c @key{LEFT} -Move left after insertion (@code{picture-movement-left}). -@item C-c > -@itemx C-c @key{RIGHT} -Move right after insertion (@code{picture-movement-right}). -@item C-c ^ -@itemx C-c @key{UP} -Move up after insertion (@code{picture-movement-up}). -@item C-c . -@itemx C-c @key{DOWN} -Move down after insertion (@code{picture-movement-down}). -@item C-c ` -@itemx C-c @key{HOME} -Move up and left (``northwest'') after insertion (@code{picture-movement-nw}). -@item C-c ' -@itemx C-c @key{PAGEUP} -Move up and right (``northeast'') after insertion -(@code{picture-movement-ne}). -@item C-c / -@itemx C-c @key{END} -Move down and left (``southwest'') after insertion -@*(@code{picture-movement-sw}). -@item C-c \ -@itemx C-c @key{PAGEDOWN} -Move down and right (``southeast'') after insertion -@*(@code{picture-movement-se}). -@end table - -@kindex C-c C-f @r{(Picture mode)} -@kindex C-c C-b @r{(Picture mode)} -@findex picture-motion -@findex picture-motion-reverse - Two motion commands move based on the current Picture insertion -direction. The command @kbd{C-c C-f} (@code{picture-motion}) moves in the -same direction as motion after ``insertion'' currently does, while @kbd{C-c -C-b} (@code{picture-motion-reverse}) moves in the opposite direction. - -@node Tabs in Picture -@section Picture Mode Tabs - -@kindex M-TAB @r{(Picture mode)} -@findex picture-tab-search -@vindex picture-tab-chars - Two kinds of tab-like action are provided in Picture mode. Use -@kbd{M-@key{TAB}} (@code{picture-tab-search}) for context-based tabbing. -With no argument, it moves to a point underneath the next -``interesting'' character that follows whitespace in the previous -nonblank line. ``Next'' here means ``appearing at a horizontal position -greater than the one point starts out at.'' With an argument, as in -@kbd{C-u M-@key{TAB}}, this command moves to the next such interesting -character in the current line. @kbd{M-@key{TAB}} does not change the -text; it only moves point. ``Interesting'' characters are defined by -the variable @code{picture-tab-chars}, which should define a set of -characters. The syntax for this variable is like the syntax used inside -of @samp{[@dots{}]} in a regular expression---but without the @samp{[} -and the @samp{]}. Its default value is @code{"!-~"}. - -@findex picture-tab - @key{TAB} itself runs @code{picture-tab}, which operates based on the -current tab stop settings; it is the Picture mode equivalent of -@code{tab-to-tab-stop}. Normally it just moves point, but with a numeric -argument it clears the text that it moves over. - -@kindex C-c TAB @r{(Picture mode)} -@findex picture-set-tab-stops - The context-based and tab-stop-based forms of tabbing are brought -together by the command @kbd{C-c @key{TAB}} (@code{picture-set-tab-stops}). -This command sets the tab stops to the positions which @kbd{M-@key{TAB}} -would consider significant in the current line. The use of this command, -together with @key{TAB}, can get the effect of context-based tabbing. But -@kbd{M-@key{TAB}} is more convenient in the cases where it is sufficient. - - It may be convenient to prevent use of actual tab characters in -pictures. For example, this prevents @kbd{C-x @key{TAB}} from messing -up the picture. You can do this by setting the variable -@code{indent-tabs-mode} to @code{nil}. - -@node Rectangles in Picture -@section Picture Mode Rectangle Commands -@cindex rectangles and Picture mode -@cindex Picture mode and rectangles - - Picture mode defines commands for working on rectangular pieces of -the text in ways that fit with the quarter-plane model. The standard -rectangle commands may also be useful. @xref{Rectangles,,, emacs, the -Emacs Manual}. - -@table @kbd -@item C-c C-k -Clear out the region-rectangle with spaces -(@code{picture-clear-rectangle}). With argument, delete the text. -@item C-c C-w @var{r} -Similar, but save rectangle contents in register @var{r} first -(@code{picture-clear-rectangle-to-register}). -@item C-c C-y -Copy last killed rectangle into the buffer by overwriting, with upper -left corner at point (@code{picture-yank-rectangle}). With argument, -insert instead. -@item C-c C-x @var{r} -Similar, but use the rectangle in register @var{r} -(@code{picture-yank-rectangle-from-register}). -@end table - -@kindex C-c C-k @r{(Picture mode)} -@kindex C-c C-w @r{(Picture mode)} -@findex picture-clear-rectangle -@findex picture-clear-rectangle-to-register - The picture rectangle commands @kbd{C-c C-k} -(@code{picture-clear-rectangle}) and @kbd{C-c C-w} -(@code{picture-clear-rectangle-to-register}) differ from the standard -rectangle commands in that they normally clear the rectangle instead of -deleting it; this is analogous with the way @kbd{C-d} is changed in Picture -mode. - - However, deletion of rectangles can be useful in Picture mode, so -these commands delete the rectangle if given a numeric argument. -@kbd{C-c C-k} either with or without a numeric argument saves the -rectangle for @kbd{C-c C-y}. - -@kindex C-c C-y @r{(Picture mode)} -@kindex C-c C-x @r{(Picture mode)} -@findex picture-yank-rectangle -@findex picture-yank-rectangle-from-register - The Picture mode commands for yanking rectangles differ from the -standard ones in that they overwrite instead of inserting. This is -the same way that Picture mode insertion of other text differs from -other modes. @kbd{C-c C-y} (@code{picture-yank-rectangle}) inserts -(by overwriting) the rectangle that was most recently killed, while -@kbd{C-c C-x} (@code{picture-yank-rectangle-from-register}) does -likewise for the rectangle found in a specified register. - -@node Advanced VC Usage -@chapter Advanced VC Usage - - Commonly used features of Emacs' version control (VC) support are -described in the main Emacs manual (@pxref{Version Control,,,emacs, -the Emacs Manual}). This chapter describes more advanced VC usage. - -@menu -* VC Dired Mode:: Listing files managed by version control. -* VC Dired Commands:: Commands to use in a VC Dired buffer. -* Remote Repositories:: Efficient access to remote CVS servers. -* Snapshots:: Sets of file versions treated as a unit. -* Miscellaneous VC:: Various other commands and features of VC. -* Customizing VC:: Variables that change VC's behavior. -@end menu - -@node VC Dired Mode -@section Dired under VC - -@cindex PCL-CVS -@pindex cvs -@cindex CVS Dired Mode - The VC Dired Mode described here works with all the version control -systems that VC supports. Another more powerful facility, designed -specifically for CVS, is called PCL-CVS. @xref{Top, , About PCL-CVS, -pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}. - -@kindex C-x v d -@findex vc-directory - When you are working on a large program, it is often useful to find -out which files have changed within an entire directory tree, or to view -the status of all files under version control at once, and to perform -version control operations on collections of files. You can use the -command @kbd{C-x v d} (@code{vc-directory}) to make a directory listing -that includes only files relevant for version control. - -@vindex vc-dired-terse-display - @kbd{C-x v d} creates a buffer which uses VC Dired Mode. This looks -much like an ordinary Dired buffer (@pxref{Dired,,,emacs, the -Emacs Manual}); however, normally it shows only the noteworthy files -(those locked or not up-to-date). This is called @dfn{terse display}. -If you set the variable @code{vc-dired-terse-display} to @code{nil}, -then VC Dired shows all relevant files---those managed under version -control, plus all subdirectories (@dfn{full display}). The command -@kbd{v t} in a VC Dired buffer toggles between terse display and full -display (@pxref{VC Dired Commands}). - -@vindex vc-dired-recurse - By default, VC Dired produces a recursive listing of noteworthy or -relevant files at or below the given directory. You can change this by -setting the variable @code{vc-dired-recurse} to @code{nil}; then VC -Dired shows only the files in the given directory. - - The line for an individual file shows the version control state in the -place of the hard link count, owner, group, and size of the file. If -the file is unmodified, in sync with the master file, the version -control state shown is blank. Otherwise it consists of text in -parentheses. Under RCS and SCCS, the name of the user locking the file -is shown; under CVS, an abbreviated version of the @samp{cvs status} -output is used. Here is an example using RCS: - -@smallexample -@group - /home/jim/project: - - -rw-r--r-- (jim) Apr 2 23:39 file1 - -r--r--r-- Apr 5 20:21 file2 -@end group -@end smallexample - -@noindent -The files @samp{file1} and @samp{file2} are under version control, -@samp{file1} is locked by user jim, and @samp{file2} is unlocked. - - Here is an example using CVS: - -@smallexample -@group - /home/joe/develop: - - -rw-r--r-- (modified) Aug 2 1997 file1.c - -rw-r--r-- Apr 4 20:09 file2.c - -rw-r--r-- (merge) Sep 13 1996 file3.c -@end group -@end smallexample - - Here @samp{file1.c} is modified with respect to the repository, and -@samp{file2.c} is not. @samp{file3.c} is modified, but other changes -have also been checked in to the repository---you need to merge them -with the work file before you can check it in. - -@vindex vc-stay-local -@vindex vc-cvs-stay-local - In the above, if the repository were on a remote machine, VC would -only contact it when the variable @code{vc-stay-local} (or -@code{vc-cvs-stay-local}) is nil (@pxref{CVS Options}). This is -because access to the repository may be slow, or you may be working -offline and not have access to the repository at all. As a -consequence, VC would not be able to tell you that @samp{file3.c} is -in the ``merge'' state; you would learn that only when you try to -check-in your modified copy of the file, or use a command such as -@kbd{C-x v m}. - - In practice, this is not a problem because CVS handles this case -consistently whenever it arises. In VC, you'll simply get prompted to -merge the remote changes into your work file first. The benefits of -less network communication usually outweigh the disadvantage of not -seeing remote changes immediately. - -@vindex vc-directory-exclusion-list - When VC Dired displays subdirectories (in the ``full'' display mode), -it omits some that should never contain any files under version control. -By default, this includes Version Control subdirectories such as -@samp{RCS} and @samp{CVS}; you can customize this by setting the -variable @code{vc-directory-exclusion-list}. - - You can fine-tune VC Dired's format by typing @kbd{C-u C-x v d}---as in -ordinary Dired, that allows you to specify additional switches for the -@samp{ls} command. - -@node VC Dired Commands -@section VC Dired Commands - - All the usual Dired commands work normally in VC Dired mode, except -for @kbd{v}, which is redefined as the version control prefix. You can -invoke VC commands such as @code{vc-diff} and @code{vc-print-log} by -typing @kbd{v =}, or @kbd{v l}, and so on. Most of these commands apply -to the file name on the current line. - - The command @kbd{v v} (@code{vc-next-action}) operates on all the -marked files, so that you can lock or check in several files at once. -If it operates on more than one file, it handles each file according to -its current state; thus, it might lock one file, but check in another -file. This could be confusing; it is up to you to avoid confusing -behavior by marking a set of files that are in a similar state. If no -files are marked, @kbd{v v} operates on the file in the current line. - - If any files call for check-in, @kbd{v v} reads a single log entry, -then uses it for all the files being checked in. This is convenient for -registering or checking in several files at once, as part of the same -change. - -@findex vc-dired-toggle-terse-mode -@findex vc-dired-mark-locked - You can toggle between terse display (only locked files, or files not -up-to-date) and full display at any time by typing @kbd{v t} -(@code{vc-dired-toggle-terse-mode}). There is also a special command -@kbd{* l} (@code{vc-dired-mark-locked}), which marks all files currently -locked (or, with CVS, all files not up-to-date). Thus, typing @kbd{* l -t k} is another way to delete from the buffer all files except those -currently locked. - -@node Remote Repositories -@section Remote Repositories -@cindex remote repositories (CVS) - - A common way of using CVS is to set up a central CVS repository on -some Internet host, then have each developer check out a personal -working copy of the files on his local machine. Committing changes to -the repository, and picking up changes from other users into one's own -working area, then works by direct interactions with the CVS server. - - One difficulty is that access to the CVS server is often slow, and -that developers might need to work off-line as well. VC is designed -to reduce the amount of network interaction necessary. - -@menu -* Version Backups:: Keeping local copies of repository versions. -* Local Version Control:: Using another version system for local editing. -@end menu - -@node Version Backups -@subsection Version Backups -@cindex version backups - -@cindex automatic version backups - When VC sees that the CVS repository for a file is on a remote -machine, it automatically makes local backups of unmodified versions -of the file---@dfn{automatic version backups}. This means that you -can compare the file to the repository version (@kbd{C-x v =}), or -revert to that version (@kbd{C-x v u}), without any network -interactions. - - The local copy of the unmodified file is called a @dfn{version -backup} to indicate that it corresponds exactly to a version that is -stored in the repository. Note that version backups are not the same -as ordinary Emacs backup files (@pxref{Backup,,,emacs, the Emacs -Manual}). But they follow a similar naming convention. - - For a file that comes from a remote CVS repository, VC makes a -version backup whenever you save the first changes to the file, and -removes it after you have committed your modified version to the -repository. You can disable the making of automatic version backups by -setting @code{vc-cvs-stay-local} to @code{nil} (@pxref{CVS Options}). - -@cindex manual version backups - The name of the automatic version backup for version @var{version} -of file @var{file} is @code{@var{file}.~@var{version}.~}. This is -almost the same as the name used by @kbd{C-x v ~} (@pxref{Old -Versions,,,emacs, the Emacs Manual}), the only difference being -the additional dot (@samp{.}) after the version number. This -similarity is intentional, because both kinds of files store the same -kind of information. The file made by @kbd{C-x v ~} acts as a -@dfn{manual version backup}. - - All the VC commands that operate on old versions of a file can use -both kinds of version backups. For instance, @kbd{C-x v ~} uses -either an automatic or a manual version backup, if possible, to get -the contents of the version you request. Likewise, @kbd{C-x v =} and -@kbd{C-x v u} use either an automatic or a manual version backup, if -one of them exists, to get the contents of a version to compare or -revert to. If you changed a file outside of Emacs, so that no -automatic version backup was created for the previous text, you can -create a manual backup of that version using @kbd{C-x v ~}, and thus -obtain the benefit of the local copy for Emacs commands. - - The only difference in Emacs's handling of manual and automatic -version backups, once they exist, is that Emacs deletes automatic -version backups when you commit to the repository. By contrast, -manual version backups remain until you delete them. - -@node Local Version Control -@subsection Local Version Control -@cindex local version control -@cindex local back end (version control) - -When you make many changes to a file that comes from a remote -repository, it can be convenient to have version control on your local -machine as well. You can then record intermediate versions, revert to -a previous state, etc., before you actually commit your changes to the -remote server. - -VC lets you do this by putting a file under a second, local version -control system, so that the file is effectively registered in two -systems at the same time. For the description here, we will assume -that the remote system is CVS, and you use RCS locally, although the -mechanism works with any combination of version control systems -(@dfn{back ends}). - -To make it work with other back ends, you must make sure that the -``more local'' back end comes before the ``more remote'' back end in -the setting of @code{vc-handled-backends} (@pxref{Customizing VC}). By -default, this variable is set up so that you can use remote CVS and -local RCS as described here. - -To start using local RCS for a file that comes from a remote CVS -server, you must @emph{register the file in RCS}, by typing @kbd{C-u -C-x v v rcs @key{RET}}. (In other words, use @code{vc-next-action} with a -prefix argument, and specify RCS as the back end.) - -You can do this at any time; it does not matter whether you have -already modified the file with respect to the version in the CVS -repository. If possible, VC tries to make the RCS master start with -the unmodified repository version, then checks in any local changes -as a new version. This works if you have not made any changes yet, or -if the unmodified repository version exists locally as a version -backup (@pxref{Version Backups}). If the unmodified version is not -available locally, the RCS master starts with the modified version; -the only drawback to this is that you cannot compare your changes -locally to what is stored in the repository. - -The version number of the RCS master is derived from the current CVS -version, starting a branch from it. For example, if the current CVS -version is 1.23, the local RCS branch will be 1.23.1. Version 1.23 in -the RCS master will be identical to version 1.23 under CVS; your first -changes are checked in as 1.23.1.1. (If the unmodified file is not -available locally, VC will check in the modified file twice, both as -1.23 and 1.23.1.1, to make the revision numbers consistent.) - -If you do not use locking under CVS (the default), locking is also -disabled for RCS, so that editing under RCS works exactly as under -CVS. - -When you are done with local editing, you can commit the final version -back to the CVS repository by typing @kbd{C-u C-x v v cvs @key{RET}}. -This initializes the log entry buffer (@pxref{Log Buffer,,,emacs, the -Emacs Manual}) to contain all the log entries you have recorded in the -RCS master; you can edit them as you wish, and then commit in CVS by -typing @kbd{C-c C-c}. If the commit is successful, VC removes the RCS -master, so that the file is once again registered under CVS only. -(The RCS master is not actually deleted, just renamed by appending -@samp{~} to the name, so that you can refer to it later if you wish.) - -While using local RCS, you can pick up recent changes from the CVS -repository into your local file, or commit some of your changes back -to CVS, without terminating local RCS version control. To do this, -switch to the CVS back end temporarily, with the @kbd{C-x v b} command: - -@table @kbd -@item C-x v b -Switch to another back end that the current file is registered -under (@code{vc-switch-backend}). - -@item C-u C-x v b @var{backend} @key{RET} -Switch to @var{backend} for the current file. -@end table - -@kindex C-x v b -@findex vc-switch-backend -@kbd{C-x v b} does not change the buffer contents, or any files; it -only changes VC's perspective on how to handle the file. Any -subsequent VC commands for that file will operate on the back end that -is currently selected. - -If the current file is registered in more than one back end, typing -@kbd{C-x v b} ``cycles'' through all of these back ends. With a -prefix argument, it asks for the back end to use in the minibuffer. - -Thus, if you are using local RCS, and you want to pick up some recent -changes in the file from remote CVS, first visit the file, then type -@kbd{C-x v b} to switch to CVS, and finally use @kbd{C-x v m -@key{RET}} to merge the news (@pxref{Merging,,,emacs, the Emacs -Manual}). You can then switch back to RCS by typing @kbd{C-x v b} -again, and continue to edit locally. - -But if you do this, the revision numbers in the RCS master no longer -correspond to those of CVS. Technically, this is not a problem, but -it can become difficult to keep track of what is in the CVS repository -and what is not. So we suggest that you return from time to time to -CVS-only operation, by committing your local changes back to the -repository using @kbd{C-u C-x v v cvs @key{RET}}. - -@node Snapshots -@section Snapshots -@cindex snapshots and version control - - A @dfn{snapshot} is a named set of file versions (one for each -registered file) that you can treat as a unit. One important kind of -snapshot is a @dfn{release}, a (theoretically) stable version of the -system that is ready for distribution to users. - -@menu -* Making Snapshots:: The snapshot facilities. -* Snapshot Caveats:: Things to be careful of when using snapshots. -@end menu - -@node Making Snapshots -@subsection Making and Using Snapshots - - There are two basic commands for snapshots; one makes a -snapshot with a given name, the other retrieves a named snapshot. - -@table @code -@kindex C-x v s -@findex vc-create-snapshot -@item C-x v s @var{name} @key{RET} -Define the last saved versions of every registered file in or under the -current directory as a snapshot named @var{name} -(@code{vc-create-snapshot}). - -@kindex C-x v r -@findex vc-retrieve-snapshot -@item C-x v r @var{name} @key{RET} -For all registered files at or below the current directory level, select -whatever versions correspond to the snapshot @var{name} -(@code{vc-retrieve-snapshot}). - -This command reports an error if any files are locked at or below the -current directory, without changing anything; this is to avoid -overwriting work in progress. -@end table - - A snapshot uses a very small amount of resources---just enough to record -the list of file names and which version belongs to the snapshot. Thus, -you need not hesitate to create snapshots whenever they are useful. - - You can give a snapshot name as an argument to @kbd{C-x v =} or -@kbd{C-x v ~} (@pxref{Old Versions,,,emacs, the Emacs Manual}). -Thus, you can use it to compare a snapshot against the current files, -or two snapshots against each other, or a snapshot against a named -version. - -@node Snapshot Caveats -@subsection Snapshot Caveats - -@cindex named configurations (RCS) - VC's snapshot facilities are modeled on RCS's named-configuration -support. They use RCS's native facilities for this, so -snapshots made using RCS through VC are visible even when you bypass VC. - - With CVS, Meta-CVS, and Subversion, VC also uses the native -mechanism provided by that back end to make snapshots and retrieve them -(@dfn{tags} for CVS and Meta-CVS, @dfn{copies} for Subversion). - -@c worded verbosely to avoid overfull hbox. - For SCCS, VC implements snapshots itself. The files it uses contain -name/file/version-number triples. These snapshots are visible only -through VC. - - There is no support for VC snapshots using GNU Arch yet. - - A snapshot is a set of checked-in versions. So make sure that all the -files are checked in and not locked when you make a snapshot. - - File renaming and deletion can create some difficulties with snapshots. -This is not a VC-specific problem, but a general design issue in version -control systems that no one has solved very well yet. - - If you rename a registered file, you need to rename its master along -with it (the command @code{vc-rename-file} does this automatically). If -you are using SCCS, you must also update the records of the snapshot, to -mention the file by its new name (@code{vc-rename-file} does this, -too). An old snapshot that refers to a master file that no longer -exists under the recorded name is invalid; VC can no longer retrieve -it. It would be beyond the scope of this manual to explain enough about -RCS and SCCS to explain how to update the snapshots by hand. - - Using @code{vc-rename-file} makes the snapshot remain valid for -retrieval, but it does not solve all problems. For example, some of the -files in your program probably refer to others by name. At the very -least, the makefile probably mentions the file that you renamed. If you -retrieve an old snapshot, the renamed file is retrieved under its new -name, which is not the name that the makefile expects. So the program -won't really work as retrieved. - -@node Miscellaneous VC -@section Miscellaneous Commands and Features of VC - - This section explains the less-frequently-used features of VC. - -@menu -* Change Logs and VC:: Generating a change log file from log entries. -* Renaming and VC:: A command to rename both the source and master - file correctly. -* Version Headers:: Inserting version control headers into working files. -@end menu - -@node Change Logs and VC -@subsection Change Logs and VC - - If you use RCS or CVS for a program and also maintain a change log -file for it (@pxref{Change Log,,,emacs, the Emacs Manual}), you -can generate change log entries automatically from the version control -log entries: - -@table @kbd -@item C-x v a -@kindex C-x v a -@findex vc-update-change-log -Visit the current directory's change log file and, for registered files -in that directory, create new entries for versions checked in since the -most recent entry in the change log file. -(@code{vc-update-change-log}). - -This command works with RCS or CVS only, not with any of the other -back ends. - -@item C-u C-x v a -As above, but only find entries for the current buffer's file. - -@item M-1 C-x v a -As above, but find entries for all the currently visited files that are -maintained with version control. This works only with RCS, and it puts -all entries in the log for the default directory, which may not be -appropriate. -@end table - - For example, suppose the first line of @file{ChangeLog} is dated -1999-04-10, and that the only check-in since then was by Nathaniel -Bowditch to @file{rcs2log} on 1999-05-22 with log text @samp{Ignore log -messages that start with `#'.}. Then @kbd{C-x v a} visits -@file{ChangeLog} and inserts text like this: - -@iftex -@medbreak -@end iftex -@smallexample -@group -1999-05-22 Nathaniel Bowditch <nat@@apn.org> - - * rcs2log: Ignore log messages that start with `#'. -@end group -@end smallexample @iftex -@medbreak -@end iftex +@c ``Picture Mode'' is a chapter, not a section, so it's outside @raisesections. +@include picture-xtra.texi -@noindent -You can then edit the new change log entry further as you wish. +@raisesections +@include arevert-xtra.texi - Some of the new change log entries may duplicate what's already in -ChangeLog. You will have to remove these duplicates by hand. +@include dired-xtra.texi - Normally, the log entry for file @file{foo} is displayed as @samp{* -foo: @var{text of log entry}}. The @samp{:} after @file{foo} is omitted -if the text of the log entry starts with @w{@samp{(@var{functionname}): -}}. For example, if the log entry for @file{vc.el} is -@samp{(vc-do-command): Check call-process status.}, then the text in -@file{ChangeLog} looks like this: +@include cal-xtra.texi -@iftex -@medbreak -@end iftex -@smallexample -@group -1999-05-06 Nathaniel Bowditch <nat@@apn.org> - - * vc.el (vc-do-command): Check call-process status. -@end group -@end smallexample -@iftex -@medbreak -@end iftex +@include emerge-xtra.texi - When @kbd{C-x v a} adds several change log entries at once, it groups -related log entries together if they all are checked in by the same -author at nearly the same time. If the log entries for several such -files all have the same text, it coalesces them into a single entry. -For example, suppose the most recent check-ins have the following log -entries: +@include vc-xtra.texi -@flushleft -@bullet{} For @file{vc.texinfo}: @samp{Fix expansion typos.} -@bullet{} For @file{vc.el}: @samp{Don't call expand-file-name.} -@bullet{} For @file{vc-hooks.el}: @samp{Don't call expand-file-name.} -@end flushleft +@include fortran-xtra.texi -@noindent -They appear like this in @file{ChangeLog}: +@include msdog-xtra.texi -@iftex -@medbreak -@end iftex -@smallexample -@group -1999-04-01 Nathaniel Bowditch <nat@@apn.org> - - * vc.texinfo: Fix expansion typos. - - * vc.el, vc-hooks.el: Don't call expand-file-name. -@end group -@end smallexample -@iftex -@medbreak +@lowersections @end iftex - Normally, @kbd{C-x v a} separates log entries by a blank line, but you -can mark several related log entries to be clumped together (without an -intervening blank line) by starting the text of each related log entry -with a label of the form @w{@samp{@{@var{clumpname}@} }}. The label -itself is not copied to @file{ChangeLog}. For example, suppose the log -entries are: - -@flushleft -@bullet{} For @file{vc.texinfo}: @samp{@{expand@} Fix expansion typos.} -@bullet{} For @file{vc.el}: @samp{@{expand@} Don't call expand-file-name.} -@bullet{} For @file{vc-hooks.el}: @samp{@{expand@} Don't call expand-file-name.} -@end flushleft - -@noindent -Then the text in @file{ChangeLog} looks like this: - -@iftex -@medbreak -@end iftex -@smallexample -@group -1999-04-01 Nathaniel Bowditch <nat@@apn.org> - - * vc.texinfo: Fix expansion typos. - * vc.el, vc-hooks.el: Don't call expand-file-name. -@end group -@end smallexample -@iftex -@medbreak -@end iftex - - A log entry whose text begins with @samp{#} is not copied to -@file{ChangeLog}. For example, if you merely fix some misspellings in -comments, you can log the change with an entry beginning with @samp{#} -to avoid putting such trivia into @file{ChangeLog}. - -@node Renaming and VC -@subsection Renaming VC Work Files and Master Files - -@findex vc-rename-file - When you rename a registered file, you must also rename its master -file correspondingly to get proper results. Use @code{vc-rename-file} -to rename the source file as you specify, and rename its master file -accordingly. It also updates any snapshots (@pxref{Snapshots}) that -mention the file, so that they use the new name; despite this, the -snapshot thus modified may not completely work (@pxref{Snapshot -Caveats}). - - Some back ends do not provide an explicit rename operation to their -repositories. After issuing @code{vc-rename-file}, use @kbd{C-x v v} -on the original and renamed buffers and provide the necessary edit -log. - - You cannot use @code{vc-rename-file} on a file that is locked by -someone else. - -@node Version Headers -@subsection Inserting Version Control Headers - - Sometimes it is convenient to put version identification strings -directly into working files. Certain special strings called -@dfn{version headers} are replaced in each successive version by the -number of that version, the name of the user who created it, and other -relevant information. All of the back ends that VC supports have such -a mechanism, except GNU Arch. - - VC does not normally use the information contained in these headers. -The exception is RCS---with RCS, version headers are sometimes more -reliable than the master file to determine which version of the file -you are editing. Note that in a multi-branch environment, version -headers are necessary to make VC behave correctly (@pxref{Multi-User -Branching,,,emacs, the Emacs Manual}). - - Searching for RCS version headers is controlled by the variable -@code{vc-consult-headers}. If it is non-@code{nil} (the default), -Emacs searches for headers to determine the version number you are -editing. Setting it to @code{nil} disables this feature. - - Note that although CVS uses the same kind of version headers as RCS -does, VC never searches for these headers if you are using CVS, -regardless of the above setting. - -@kindex C-x v h -@findex vc-insert-headers - You can use the @kbd{C-x v h} command (@code{vc-insert-headers}) to -insert a suitable header string. - -@table @kbd -@item C-x v h -Insert headers in a file for use with your version-control system. -@end table - -@vindex vc-@var{backend}-header - The default header string is @samp{@w{$}Id$} for RCS and -@samp{@w{%}W%} for SCCS. You can specify other headers to insert by -setting the variables @code{vc-@var{backend}-header} where -@var{backend} is @code{rcs} or @code{sccs}. - - Instead of a single string, you can specify a list of strings; then -each string in the list is inserted as a separate header on a line of -its own. - - It may be necessary to use apparently-superfluous backslashes when -writing the strings that you put in this variable. For instance, you -might write @code{"$Id\$"} rather than @code{"$Id@w{$}"}. The extra -backslash prevents the string constant from being interpreted as a -header, if the Emacs Lisp file containing it is maintained with -version control. - -@vindex vc-comment-alist - Each header is inserted surrounded by tabs, inside comment delimiters, -on a new line at point. Normally the ordinary comment -start and comment end strings of the current mode are used, but for -certain modes, there are special comment delimiters for this purpose; -the variable @code{vc-comment-alist} specifies them. Each element of -this list has the form @code{(@var{mode} @var{starter} @var{ender})}. - -@vindex vc-static-header-alist - The variable @code{vc-static-header-alist} specifies further strings -to add based on the name of the buffer. Its value should be a list of -elements of the form @code{(@var{regexp} . @var{format})}. Whenever -@var{regexp} matches the buffer name, @var{format} is inserted as part -of the header. A header line is inserted for each element that matches -the buffer name, and for each string specified by -@code{vc-@var{backend}-header}. The header line is made by processing the -string from @code{vc-@var{backend}-header} with the format taken from the -element. The default value for @code{vc-static-header-alist} is as follows: - -@example -@group -(("\\.c$" . - "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\ -#endif /* lint */\n")) -@end group -@end example - -@noindent -It specifies insertion of text of this form: - -@example -@group - -#ifndef lint -static char vcid[] = "@var{string}"; -#endif /* lint */ -@end group -@end example - -@noindent -Note that the text above starts with a blank line. - - If you use more than one version header in a file, put them close -together in the file. The mechanism in @code{revert-buffer} that -preserves markers may not handle markers positioned between two version -headers. - -@node Customizing VC -@section Customizing VC - -@vindex vc-handled-backends -The variable @code{vc-handled-backends} determines which version -control systems VC should handle. The default value is @code{(RCS CVS -SVN SCCS Arch MCVS)}, so it contains all six version systems that are -currently supported. If you want VC to ignore one or more of these -systems, exclude its name from the list. To disable VC entirely, set -this variable to @code{nil}. - -The order of systems in the list is significant: when you visit a file -registered in more than one system (@pxref{Local Version Control}), VC -uses the system that comes first in @code{vc-handled-backends} by -default. The order is also significant when you register a file for -the first time, @pxref{Registering,,,emacs, the Emacs Manual} for -details. - -@menu -* General VC Options:: Options that apply to multiple back ends. -* RCS and SCCS:: Options for RCS and SCCS. -* CVS Options:: Options for CVS. -@end menu - -@node General VC Options -@subsection General Options - -@vindex vc-make-backup-files - Emacs normally does not save backup files for source files that are -maintained with version control. If you want to make backup files even -for files that use version control, set the variable -@code{vc-make-backup-files} to a non-@code{nil} value. - -@vindex vc-keep-workfiles - Normally the work file exists all the time, whether it is locked or -not. If you set @code{vc-keep-workfiles} to @code{nil}, then checking -in a new version with @kbd{C-x v v} deletes the work file; but any -attempt to visit the file with Emacs creates it again. (With CVS, work -files are always kept.) - -@vindex vc-follow-symlinks - Editing a version-controlled file through a symbolic link can be -dangerous. It bypasses the version control system---you can edit the -file without locking it, and fail to check your changes in. Also, -your changes might overwrite those of another user. To protect against -this, VC checks each symbolic link that you visit, to see if it points -to a file under version control. - - The variable @code{vc-follow-symlinks} controls what to do when a -symbolic link points to a version-controlled file. If it is @code{nil}, -VC only displays a warning message. If it is @code{t}, VC automatically -follows the link, and visits the real file instead, telling you about -this in the echo area. If the value is @code{ask} (the default), VC -asks you each time whether to follow the link. - -@vindex vc-suppress-confirm - If @code{vc-suppress-confirm} is non-@code{nil}, then @kbd{C-x v v} -and @kbd{C-x v i} can save the current buffer without asking, and -@kbd{C-x v u} also operates without asking for confirmation. (This -variable does not affect @kbd{C-x v c}; that operation is so drastic -that it should always ask for confirmation.) - -@vindex vc-command-messages - VC mode does much of its work by running the shell commands for RCS, -CVS and SCCS. If @code{vc-command-messages} is non-@code{nil}, VC -displays messages to indicate which shell commands it runs, and -additional messages when the commands finish. - -@vindex vc-path - You can specify additional directories to search for version control -programs by setting the variable @code{vc-path}. These directories -are searched before the usual search path. It is rarely necessary to -set this variable, because VC normally finds the proper files -automatically. - -@node RCS and SCCS -@subsection Options for RCS and SCCS - -@cindex non-strict locking (RCS) -@cindex locking, non-strict (RCS) - By default, RCS uses locking to coordinate the activities of several -users, but there is a mode called @dfn{non-strict locking} in which -you can check-in changes without locking the file first. Use -@samp{rcs -U} to switch to non-strict locking for a particular file, -see the @code{rcs} manual page for details. - - When deducing the version control state of an RCS file, VC first -looks for an RCS version header string in the file (@pxref{Version -Headers}). If there is no header string, VC normally looks at the -file permissions of the work file; this is fast. But there might be -situations when the file permissions cannot be trusted. In this case -the master file has to be consulted, which is rather expensive. Also -the master file can only tell you @emph{if} there's any lock on the -file, but not whether your work file really contains that locked -version. - -@vindex vc-consult-headers - You can tell VC not to use version headers to determine the file -status by setting @code{vc-consult-headers} to @code{nil}. VC then -always uses the file permissions (if it is supposed to trust them), or -else checks the master file. - -@vindex vc-mistrust-permissions - You can specify the criterion for whether to trust the file -permissions by setting the variable @code{vc-mistrust-permissions}. -Its value can be @code{t} (always mistrust the file permissions and -check the master file), @code{nil} (always trust the file -permissions), or a function of one argument which makes the decision. -The argument is the directory name of the @file{RCS} subdirectory. A -non-@code{nil} value from the function says to mistrust the file -permissions. If you find that the file permissions of work files are -changed erroneously, set @code{vc-mistrust-permissions} to @code{t}. -Then VC always checks the master file to determine the file's status. - - VC determines the version control state of files under SCCS much as -with RCS. It does not consider SCCS version headers, though. Thus, -the variable @code{vc-mistrust-permissions} affects SCCS use, but -@code{vc-consult-headers} does not. - -@node CVS Options -@subsection Options specific for CVS - -@cindex locking (CVS) - By default, CVS does not use locking to coordinate the activities of -several users; anyone can change a work file at any time. However, -there are ways to restrict this, resulting in behavior that resembles -locking. - -@cindex CVSREAD environment variable (CVS) - For one thing, you can set the @env{CVSREAD} environment variable -(the value you use makes no difference). If this variable is defined, -CVS makes your work files read-only by default. In Emacs, you must -type @kbd{C-x v v} to make the file writable, so that editing works -in fact similar as if locking was used. Note however, that no actual -locking is performed, so several users can make their files writable -at the same time. When setting @env{CVSREAD} for the first time, make -sure to check out all your modules anew, so that the file protections -are set correctly. - -@cindex cvs watch feature -@cindex watching files (CVS) - Another way to achieve something similar to locking is to use the -@dfn{watch} feature of CVS. If a file is being watched, CVS makes it -read-only by default, and you must also use @kbd{C-x v v} in Emacs to -make it writable. VC calls @code{cvs edit} to make the file writable, -and CVS takes care to notify other developers of the fact that you -intend to change the file. See the CVS documentation for details on -using the watch feature. - -@vindex vc-stay-local -@vindex vc-cvs-stay-local -@cindex remote repositories (CVS) - When a file's repository is on a remote machine, VC tries to keep -network interactions to a minimum. This is controlled by the variable -@code{vc-cvs-stay-local}. There is another variable, -@code{vc-stay-local}, which enables the feature also for other back -ends that support it, including CVS. In the following, we will talk -only about @code{vc-cvs-stay-local}, but everything applies to -@code{vc-stay-local} as well. - -If @code{vc-cvs-stay-local} is @code{t} (the default), then VC uses -only the entry in the local CVS subdirectory to determine the file's -state (and possibly information returned by previous CVS commands). -One consequence of this is that when you have modified a file, and -somebody else has already checked in other changes to the file, you -are not notified of it until you actually try to commit. (But you can -try to pick up any recent changes from the repository first, using -@kbd{C-x v m @key{RET}}, @pxref{Merging,,,emacs, the Emacs Manual}). - - When @code{vc-cvs-stay-local} is @code{t}, VC also makes local -version backups, so that simple diff and revert operations are -completely local (@pxref{Version Backups}). - - On the other hand, if you set @code{vc-cvs-stay-local} to @code{nil}, -then VC queries the remote repository @emph{before} it decides what to -do in @code{vc-next-action} (@kbd{C-x v v}), just as it does for local -repositories. It also does not make any version backups. - - You can also set @code{vc-cvs-stay-local} to a regular expression -that is matched against the repository host name; VC then stays local -only for repositories from hosts that match the pattern. - -@vindex vc-cvs-global-switches - You can specify additional command line options to pass to all CVS -operations in the variable @code{vc-cvs-global-switches}. These -switches are inserted immediately after the @code{cvs} command, before -the name of the operation to invoke. - - -@node Fortran -@chapter Fortran Mode -@cindex Fortran mode -@cindex mode, Fortran - - Fortran mode provides special motion commands for Fortran statements -and subprograms, and indentation commands that understand Fortran -conventions of nesting, line numbers and continuation statements. -Fortran mode has support for Auto Fill mode that breaks long lines into -proper Fortran continuation lines. - - Special commands for comments are provided because Fortran comments -are unlike those of other languages. Built-in abbrevs optionally save -typing when you insert Fortran keywords. - - Use @kbd{M-x fortran-mode} to switch to this major mode. This -command runs the hook @code{fortran-mode-hook}. @xref{Hooks,,, emacs, -the Emacs Manual}. - -@cindex Fortran77 and Fortran90 -@findex f90-mode -@findex fortran-mode - Fortran mode is meant for editing Fortran77 ``fixed format'' (and also -``tab format'') source code. For editing the modern Fortran90 or -Fortran95 ``free format'' source code, use F90 mode (@code{f90-mode}). -Emacs normally uses Fortran mode for files with extension @samp{.f}, -@samp{.F} or @samp{.for}, and F90 mode for the extension @samp{.f90} and -@samp{.f95}. GNU Fortran supports both kinds of format. - -@menu -* Motion: Fortran Motion. Moving point by statements or subprograms. -* Indent: Fortran Indent. Indentation commands for Fortran. -* Comments: Fortran Comments. Inserting and aligning comments. -* Autofill: Fortran Autofill. Auto fill support for Fortran. -* Columns: Fortran Columns. Measuring columns for valid Fortran. -* Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords. -@end menu - -@node Fortran Motion -@section Motion Commands - - In addition to the normal commands for moving by and operating on -``defuns'' (Fortran subprograms---functions and subroutines, as well as -modules for F90 mode), Fortran mode provides special commands to move by -statements and other program units. - -@table @kbd -@kindex C-c C-n @r{(Fortran mode)} -@findex fortran-next-statement -@findex f90-next-statement -@item C-c C-n -Move to the beginning of the next statement -(@code{fortran-next-statement}/@code{f90-next-statement}). - -@kindex C-c C-p @r{(Fortran mode)} -@findex fortran-previous-statement -@findex f90-previous-statement -@item C-c C-p -Move to the beginning of the previous statement -(@code{fortran-previous-statement}/@code{f90-previous-statement}). -If there is no previous statement (i.e. if called from the first -statement in the buffer), move to the start of the buffer. - -@kindex C-c C-e @r{(F90 mode)} -@findex f90-next-block -@item C-c C-e -Move point forward to the start of the next code block -(@code{f90-next-block}). A code block is a subroutine, -@code{if}--@code{endif} statement, and so forth. This command exists -for F90 mode only, not Fortran mode. With a numeric argument, this -moves forward that many blocks. - -@kindex C-c C-a @r{(F90 mode)} -@findex f90-previous-block -@item C-c C-a -Move point backward to the previous code block -(@code{f90-previous-block}). This is like @code{f90-next-block}, but -moves backwards. - -@kindex C-M-n @r{(Fortran mode)} -@findex fortran-end-of-block -@findex f90-end-of-block -@item C-M-n -Move to the end of the current code block -(@code{fortran-end-of-block}/@code{f90-end-of-block}). With a numeric -agument, move forward that number of blocks. The mark is set before -moving point. The F90 mode version of this command checks for -consistency of block types and labels (if present), but it does not -check the outermost block since that may be incomplete. - -@kindex C-M-p @r{(Fortran mode)} -@findex fortran-beginning-of-block -@findex f90-beginning-of-block -@item C-M-p -Move to the start of the current code block -(@code{fortran-beginning-of-block}/@code{f90-beginning-of-block}). This -is like @code{fortran-end-of-block}, but moves backwards. -@end table - -@node Fortran Indent -@section Fortran Indentation - - Special commands and features are needed for indenting Fortran code in -order to make sure various syntactic entities (line numbers, comment line -indicators and continuation line flags) appear in the columns that are -required for standard, fixed (or tab) format Fortran. - -@menu -* Commands: ForIndent Commands. Commands for indenting and filling Fortran. -* Contline: ForIndent Cont. How continuation lines indent. -* Numbers: ForIndent Num. How line numbers auto-indent. -* Conv: ForIndent Conv. Conventions you must obey to avoid trouble. -* Vars: ForIndent Vars. Variables controlling Fortran indent style. -@end menu - -@node ForIndent Commands -@subsection Fortran Indentation and Filling Commands - -@table @kbd -@item C-M-j -Break the current line at point and set up a continuation line -(@code{fortran-split-line}). -@item M-^ -Join this line to the previous line (@code{fortran-join-line}). -@item C-M-q -Indent all the lines of the subprogram point is in -(@code{fortran-indent-subprogram}). -@item M-q -Fill a comment block or statement. -@end table - -@kindex C-M-q @r{(Fortran mode)} -@findex fortran-indent-subprogram - The key @kbd{C-M-q} runs @code{fortran-indent-subprogram}, a command -to reindent all the lines of the Fortran subprogram (function or -subroutine) containing point. - -@kindex C-M-j @r{(Fortran mode)} -@findex fortran-split-line - The key @kbd{C-M-j} runs @code{fortran-split-line}, which splits -a line in the appropriate fashion for Fortran. In a non-comment line, -the second half becomes a continuation line and is indented -accordingly. In a comment line, both halves become separate comment -lines. - -@kindex M-^ @r{(Fortran mode)} -@kindex C-c C-d @r{(Fortran mode)} -@findex fortran-join-line - @kbd{M-^} or @kbd{C-c C-d} runs the command @code{fortran-join-line}, -which joins a continuation line back to the previous line, roughly as -the inverse of @code{fortran-split-line}. The point must be on a -continuation line when this command is invoked. - -@kindex M-q @r{(Fortran mode)} -@kbd{M-q} in Fortran mode fills the comment block or statement that -point is in. This removes any excess statement continuations. - -@node ForIndent Cont -@subsection Continuation Lines -@cindex Fortran continuation lines - -@vindex fortran-continuation-string - Most Fortran77 compilers allow two ways of writing continuation lines. -If the first non-space character on a line is in column 5, then that -line is a continuation of the previous line. We call this @dfn{fixed -format}. (In GNU Emacs we always count columns from 0; but note that -the Fortran standard counts from 1.) The variable -@code{fortran-continuation-string} specifies what character to put in -column 5. A line that starts with a tab character followed by any digit -except @samp{0} is also a continuation line. We call this style of -continuation @dfn{tab format}. (Fortran90 introduced ``free format'', -with another style of continuation lines). - -@vindex indent-tabs-mode @r{(Fortran mode)} -@vindex fortran-analyze-depth -@vindex fortran-tab-mode-default - Fortran mode can use either style of continuation line. When you -enter Fortran mode, it tries to deduce the proper continuation style -automatically from the buffer contents. It does this by scanning up to -@code{fortran-analyze-depth} (default 100) lines from the start of the -buffer. The first line that begins with either a tab character or six -spaces determines the choice. If the scan fails (for example, if the -buffer is new and therefore empty), the value of -@code{fortran-tab-mode-default} (@code{nil} for fixed format, and -non-@code{nil} for tab format) is used. @samp{/t} in the mode line -indicates tab format is selected. Fortran mode sets the value of -@code{indent-tabs-mode} accordingly. - - If the text on a line starts with the Fortran continuation marker -@samp{$}, or if it begins with any non-whitespace character in column -5, Fortran mode treats it as a continuation line. When you indent a -continuation line with @key{TAB}, it converts the line to the current -continuation style. When you split a Fortran statement with -@kbd{C-M-j}, the continuation marker on the newline is created according -to the continuation style. - - The setting of continuation style affects several other aspects of -editing in Fortran mode. In fixed format mode, the minimum column -number for the body of a statement is 6. Lines inside of Fortran -blocks that are indented to larger column numbers always use only the -space character for whitespace. In tab format mode, the minimum -column number for the statement body is 8, and the whitespace before -column 8 must always consist of one tab character. - -@node ForIndent Num -@subsection Line Numbers - - If a number is the first non-whitespace in the line, Fortran -indentation assumes it is a line number and moves it to columns 0 -through 4. (Columns always count from 0 in GNU Emacs.) - -@vindex fortran-line-number-indent - Line numbers of four digits or less are normally indented one space. -The variable @code{fortran-line-number-indent} controls this; it -specifies the maximum indentation a line number can have. The default -value of the variable is 1. Fortran mode tries to prevent line number -digits passing column 4, reducing the indentation below the specified -maximum if necessary. If @code{fortran-line-number-indent} has the -value 5, line numbers are right-justified to end in column 4. - -@vindex fortran-electric-line-number - Simply inserting a line number is enough to indent it according to -these rules. As each digit is inserted, the indentation is recomputed. -To turn off this feature, set the variable -@code{fortran-electric-line-number} to @code{nil}. - - -@node ForIndent Conv -@subsection Syntactic Conventions - - Fortran mode assumes that you follow certain conventions that simplify -the task of understanding a Fortran program well enough to indent it -properly: - -@itemize @bullet -@item -Two nested @samp{do} loops never share a @samp{continue} statement. - -@item -Fortran keywords such as @samp{if}, @samp{else}, @samp{then}, @samp{do} -and others are written without embedded whitespace or line breaks. - -Fortran compilers generally ignore whitespace outside of string -constants, but Fortran mode does not recognize these keywords if they -are not contiguous. Constructs such as @samp{else if} or @samp{end do} -are acceptable, but the second word should be on the same line as the -first and not on a continuation line. -@end itemize - -@noindent -If you fail to follow these conventions, the indentation commands may -indent some lines unaesthetically. However, a correct Fortran program -retains its meaning when reindented even if the conventions are not -followed. - -@node ForIndent Vars -@subsection Variables for Fortran Indentation - -@vindex fortran-do-indent -@vindex fortran-if-indent -@vindex fortran-structure-indent -@vindex fortran-continuation-indent -@vindex fortran-check-all-num@dots{} -@vindex fortran-minimum-statement-indent@dots{} - Several additional variables control how Fortran indentation works: - -@table @code -@item fortran-do-indent -Extra indentation within each level of @samp{do} statement (default 3). - -@item fortran-if-indent -Extra indentation within each level of @samp{if}, @samp{select case}, or -@samp{where} statements (default 3). - -@item fortran-structure-indent -Extra indentation within each level of @samp{structure}, @samp{union}, -@samp{map}, or @samp{interface} statements (default 3). - -@item fortran-continuation-indent -Extra indentation for bodies of continuation lines (default 5). - -@item fortran-check-all-num-for-matching-do -In Fortran77, a numbered @samp{do} statement is ended by any statement -with a matching line number. It is common (but not compulsory) to use a -@samp{continue} statement for this purpose. If this variable has a -non-@code{nil} value, indenting any numbered statement must check for a -@samp{do} that ends there. If you always end @samp{do} statements with -a @samp{continue} line (or if you use the more modern @samp{enddo}), -then you can speed up indentation by setting this variable to -@code{nil}. The default is @code{nil}. - -@item fortran-blink-matching-if -If this is @code{t}, indenting an @samp{endif} (or @samp{enddo} -statement moves the cursor momentarily to the matching @samp{if} (or -@samp{do}) statement to show where it is. The default is @code{nil}. - -@item fortran-minimum-statement-indent-fixed -Minimum indentation for Fortran statements when using fixed format -continuation line style. Statement bodies are never indented less than -this much. The default is 6. - -@item fortran-minimum-statement-indent-tab -Minimum indentation for Fortran statements for tab format continuation line -style. Statement bodies are never indented less than this much. The -default is 8. -@end table - -The variables controlling the indentation of comments are described in -the following section. - -@node Fortran Comments -@section Fortran Comments - - The usual Emacs comment commands assume that a comment can follow a -line of code. In Fortran77, the standard comment syntax requires an -entire line to be just a comment. Therefore, Fortran mode replaces the -standard Emacs comment commands and defines some new variables. - -@vindex fortran-comment-line-start - Fortran mode can also handle the Fortran90 comment syntax where comments -start with @samp{!} and can follow other text. Because only some Fortran77 -compilers accept this syntax, Fortran mode will not insert such comments -unless you have said in advance to do so. To do this, set the variable -@code{fortran-comment-line-start} to @samp{"!"}. - -@table @kbd -@item M-; -Align comment or insert new comment (@code{fortran-indent-comment}). - -@item C-x ; -Applies to nonstandard @samp{!} comments only. - -@item C-c ; -Turn all lines of the region into comments, or (with argument) turn them back -into real code (@code{fortran-comment-region}). -@end table - -@findex fortran-indent-comment - @kbd{M-;} in Fortran mode is redefined as the command -@code{fortran-indent-comment}. Like the usual @kbd{M-;} command, this -recognizes any kind of existing comment and aligns its text appropriately; -if there is no existing comment, a comment is inserted and aligned. But -inserting and aligning comments are not the same in Fortran mode as in -other modes. - - When a new comment must be inserted, if the current line is blank, a -full-line comment is inserted. On a non-blank line, a nonstandard @samp{!} -comment is inserted if you have said you want to use them. Otherwise a -full-line comment is inserted on a new line before the current line. - - Nonstandard @samp{!} comments are aligned like comments in other -languages, but full-line comments are different. In a standard full-line -comment, the comment delimiter itself must always appear in column zero. -What can be aligned is the text within the comment. You can choose from -three styles of alignment by setting the variable -@code{fortran-comment-indent-style} to one of these values: - -@vindex fortran-comment-indent-style -@vindex fortran-comment-line-extra-indent -@table @code -@item fixed -Align the text at a fixed column, which is the sum of -@code{fortran-comment-line-extra-indent} and the minimum statement -indentation. This is the default. - -The minimum statement indentation is -@code{fortran-minimum-statement-indent-fixed} for fixed format -continuation line style and @code{fortran-minimum-statement-indent-tab} -for tab format style. - -@item relative -Align the text as if it were a line of code, but with an additional -@code{fortran-comment-line-extra-indent} columns of indentation. - -@item nil -Don't move text in full-line comments automatically. -@end table - -@vindex fortran-comment-indent-char - In addition, you can specify the character to be used to indent within -full-line comments by setting the variable -@code{fortran-comment-indent-char} to the single-character string you want -to use. - -@vindex fortran-directive-re - Compiler directive lines, or preprocessor lines, have much the same -appearance as comment lines. It is important, though, that such lines -never be indented at all, no matter what the value of -@code{fortran-comment-indent-style}. The variable -@code{fortran-directive-re} is a regular expression that specifies which -lines are directives. Matching lines are never indented, and receive -distinctive font-locking. - - The normal Emacs comment command @kbd{C-x ;} has not been redefined. If -you use @samp{!} comments, this command can be used with them. Otherwise -it is useless in Fortran mode. - -@kindex C-c ; @r{(Fortran mode)} -@findex fortran-comment-region -@vindex fortran-comment-region - The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the -lines of the region into comments by inserting the string @samp{C$$$} at -the front of each one. With a numeric argument, it turns the region -back into live code by deleting @samp{C$$$} from the front of each line -in it. The string used for these comments can be controlled by setting -the variable @code{fortran-comment-region}. Note that here we have an -example of a command and a variable with the same name; these two uses -of the name never conflict because in Lisp and in Emacs it is always -clear from the context which one is meant. - -@node Fortran Autofill -@section Auto Fill in Fortran Mode - - Fortran mode has specialized support for Auto Fill mode, which is a -minor mode that automatically splits statements as you insert them -when they become too wide. Splitting a statement involves making -continuation lines using @code{fortran-continuation-string} -(@pxref{ForIndent Cont}). This splitting happens when you type -@key{SPC}, @key{RET}, or @key{TAB}, and also in the Fortran -indentation commands. You activate Auto Fill in Fortran mode in the -normal way. @xref{Auto Fill,,, emacs, the Emacs Manual}. - -@vindex fortran-break-before-delimiters - Auto Fill breaks lines at spaces or delimiters when the lines get -longer than the desired width (the value of @code{fill-column}). The -delimiters (besides whitespace) that Auto Fill can break at are -@samp{+}, @samp{-}, @samp{/}, @samp{*}, @samp{=}, @samp{<}, @samp{>}, -and @samp{,}. The line break comes after the delimiter if the -variable @code{fortran-break-before-delimiters} is @code{nil}. -Otherwise (and by default), the break comes before the delimiter. - - To enable Auto Fill in all Fortran buffers, add -@code{turn-on-auto-fill} to @code{fortran-mode-hook}. @xref{Hooks,,, -emacs, the Emacs Manual}. - -@node Fortran Columns -@section Checking Columns in Fortran - -@table @kbd -@item C-c C-r -Display a ``column ruler'' momentarily above the current line -(@code{fortran-column-ruler}). -@item C-c C-w -Split the current window horizontally temporarily so that it is 72 -columns wide (@code{fortran-window-create-momentarily}). This may -help you avoid making lines longer than the 72-character limit that -some Fortran compilers impose. -@item C-u C-c C-w -Split the current window horizontally so that it is 72 columns wide -(@code{fortran-window-create}). You can then continue editing. -@item M-x fortran-strip-sequence-nos -Delete all text in column 72 and beyond. -@end table - -@kindex C-c C-r @r{(Fortran mode)} -@findex fortran-column-ruler - The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column -ruler momentarily above the current line. The comment ruler is two lines -of text that show you the locations of columns with special significance in -Fortran programs. Square brackets show the limits of the columns for line -numbers, and curly brackets show the limits of the columns for the -statement body. Column numbers appear above them. - - Note that the column numbers count from zero, as always in GNU Emacs. -As a result, the numbers may be one less than those you are familiar -with; but the positions they indicate in the line are standard for -Fortran. - -@vindex fortran-column-ruler-fixed -@vindex fortran-column-ruler-tabs - The text used to display the column ruler depends on the value of the -variable @code{indent-tabs-mode}. If @code{indent-tabs-mode} is -@code{nil}, then the value of the variable -@code{fortran-column-ruler-fixed} is used as the column ruler. -Otherwise, the value of the variable @code{fortran-column-ruler-tab} is -displayed. By changing these variables, you can change the column ruler -display. - -@kindex C-c C-w @r{(Fortran mode)} -@findex fortran-window-create-momentarily - @kbd{C-c C-w} (@code{fortran-window-create-momentarily}) temporarily -splits the current window horizontally, making a window 72 columns -wide, so you can see any lines that are too long. Type a space to -restore the normal width. - -@kindex C-u C-c C-w @r{(Fortran mode)} -@findex fortran-window-create - You can also split the window horizontally and continue editing with -the split in place. To do this, use @kbd{C-u C-c C-w} (@code{M-x -fortran-window-create}). By editing in this window you can -immediately see when you make a line too wide to be correct Fortran. - -@findex fortran-strip-sequence-nos - The command @kbd{M-x fortran-strip-sequence-nos} deletes all text in -column 72 and beyond, on all lines in the current buffer. This is the -easiest way to get rid of old sequence numbers. - -@node Fortran Abbrev -@section Fortran Keyword Abbrevs - - Fortran mode provides many built-in abbrevs for common keywords and -declarations. These are the same sort of abbrev that you can define -yourself. To use them, you must turn on Abbrev mode. -@xref{Abbrevs,,, emacs, the Emacs Manual}. - - The built-in abbrevs are unusual in one way: they all start with a -semicolon. You cannot normally use semicolon in an abbrev, but Fortran -mode makes this possible by changing the syntax of semicolon to ``word -constituent.'' - - For example, one built-in Fortran abbrev is @samp{;c} for -@samp{continue}. If you insert @samp{;c} and then insert a punctuation -character such as a space or a newline, the @samp{;c} expands automatically -to @samp{continue}, provided Abbrev mode is enabled.@refill - - Type @samp{;?} or @samp{;C-h} to display a list of all the built-in -Fortran abbrevs and what they stand for. - - -@node MS-DOS -@chapter Emacs and MS-DOS -@cindex MS-DOG -@cindex MS-DOS peculiarities - - This section briefly describes the peculiarities of using Emacs on -the MS-DOS ``operating system'' (also known as ``MS-DOG''). -Information about Emacs and Microsoft's current operating system -Windows (also known as ``Losedows) is in the main Emacs manual -(@pxref{Microsoft Systems,,, emacs, the Emacs Manual}). - - If you build Emacs for MS-DOS, the binary will also run on Windows -3.X, Windows NT, Windows 9X/ME, Windows 2000, or OS/2 as a DOS -application; all of this chapter applies for all of those systems, if -you use an Emacs that was built for MS-DOS. - - @xref{Text and Binary,,,emacs, the Emacs Manual}, for information -about Emacs' special handling of text files under MS-DOS (and -Windows). - -@menu -* Keyboard: MS-DOS Keyboard. Keyboard conventions on MS-DOS. -* Mouse: MS-DOS Mouse. Mouse conventions on MS-DOS. -* Display: MS-DOS Display. Fonts, frames and display size on MS-DOS. -* Files: MS-DOS File Names. File name conventions on MS-DOS. -* Printing: MS-DOS Printing. Printing specifics on MS-DOS. -* I18N: MS-DOS and MULE. Support for internationalization on MS-DOS. -* Processes: MS-DOS Processes. Running subprocesses on MS-DOS. -@end menu - -@node MS-DOS Keyboard -@section Keyboard Usage on MS-DOS - -@kindex DEL @r{(MS-DOS)} -@kindex BS @r{(MS-DOS)} - The key that is called @key{DEL} in Emacs (because that's how it is -designated on most workstations) is known as @key{BS} (backspace) on a -PC. That is why the PC-specific terminal initialization remaps the -@key{BS} key to act as @key{DEL}; the @key{DELETE} key is remapped to act -as @kbd{C-d} for the same reasons. - -@kindex C-g @r{(MS-DOS)} -@kindex C-BREAK @r{(MS-DOS)} -@cindex quitting on MS-DOS - Emacs built for MS-DOS recognizes @kbd{C-@key{BREAK}} as a quit -character, just like @kbd{C-g}. This is because Emacs cannot detect -that you have typed @kbd{C-g} until it is ready for more input. As a -consequence, you cannot use @kbd{C-g} to stop a running command -(@pxref{Quitting,,,emacs, the Emacs Manual}). By contrast, -@kbd{C-@key{BREAK}} @emph{is} detected as soon as you type it (as -@kbd{C-g} is on other systems), so it can be used to stop a running -command and for emergency escape (@pxref{Emergency Escape,,,emacs, the -Emacs Manual}). - -@cindex Meta (under MS-DOS) -@cindex Hyper (under MS-DOS) -@cindex Super (under MS-DOS) -@vindex dos-super-key -@vindex dos-hyper-key - The PC keyboard maps use the left @key{ALT} key as the @key{META} key. -You have two choices for emulating the @key{SUPER} and @key{HYPER} keys: -choose either the right @key{CTRL} key or the right @key{ALT} key by -setting the variables @code{dos-hyper-key} and @code{dos-super-key} to 1 -or 2 respectively. If neither @code{dos-super-key} nor -@code{dos-hyper-key} is 1, then by default the right @key{ALT} key is -also mapped to the @key{META} key. However, if the MS-DOS international -keyboard support program @file{KEYB.COM} is installed, Emacs will -@emph{not} map the right @key{ALT} to @key{META}, since it is used for -accessing characters like @kbd{~} and @kbd{@@} on non-US keyboard -layouts; in this case, you may only use the left @key{ALT} as @key{META} -key. - -@kindex C-j @r{(MS-DOS)} -@vindex dos-keypad-mode - The variable @code{dos-keypad-mode} is a flag variable that controls -what key codes are returned by keys in the numeric keypad. You can also -define the keypad @key{ENTER} key to act like @kbd{C-j}, by putting the -following line into your @file{_emacs} file: - -@smallexample -;; @r{Make the @key{ENTER} key from the numeric keypad act as @kbd{C-j}.} -(define-key function-key-map [kp-enter] [?\C-j]) -@end smallexample - -@node MS-DOS Mouse -@section Mouse Usage on MS-DOS - -@cindex mouse support under MS-DOS - Emacs on MS-DOS supports a mouse (on the default terminal only). -The mouse commands work as documented, including those that use menus -and the menu bar (@pxref{Menu Bar,,,emacs, the Emacs Manual}). Scroll -bars don't work in MS-DOS Emacs. PC mice usually have only two -buttons; these act as @kbd{Mouse-1} and @kbd{Mouse-2}, but if you -press both of them together, that has the effect of @kbd{Mouse-3}. If -the mouse does have 3 buttons, Emacs detects that at startup, and all -the 3 buttons function normally, as on X. - - Help strings for menu-bar and pop-up menus are displayed in the echo -area when the mouse pointer moves across the menu items. Highlighting -of mouse-sensitive text (@pxref{Mouse References,,,emacs, the Emacs -Manual}) is also supported. - -@cindex mouse, set number of buttons -@findex msdos-set-mouse-buttons - Some versions of mouse drivers don't report the number of mouse -buttons correctly. For example, mice with a wheel report that they -have 3 buttons, but only 2 of them are passed to Emacs; the clicks on -the wheel, which serves as the middle button, are not passed. In -these cases, you can use the @kbd{M-x msdos-set-mouse-buttons} command -to tell Emacs how many mouse buttons to expect. You could make such a -setting permanent by adding this fragment to your @file{_emacs} init -file: - -@example -;; @r{Treat the mouse like a 2-button mouse.} -(msdos-set-mouse-buttons 2) -@end example - -@cindex Windows clipboard support - Emacs built for MS-DOS supports clipboard operations when it runs on -Windows. Commands that put text on the kill ring, or yank text from -the ring, check the Windows clipboard first, just as Emacs does on the -X Window System (@pxref{Mouse Commands,,,emacs, the Emacs Manual}). -Only the primary selection and the cut buffer are supported by MS-DOS -Emacs on Windows; the secondary selection always appears as empty. - - Due to the way clipboard access is implemented by Windows, the -length of text you can put into the clipboard is limited by the amount -of free DOS memory that is available to Emacs. Usually, up to 620KB of -text can be put into the clipboard, but this limit depends on the system -configuration and is lower if you run Emacs as a subprocess of -another program. If the killed text does not fit, Emacs outputs a -message saying so, and does not put the text into the clipboard. - - Null characters also cannot be put into the Windows clipboard. If the -killed text includes null characters, Emacs does not put such text into -the clipboard, and displays in the echo area a message to that effect. - -@vindex dos-display-scancodes - The variable @code{dos-display-scancodes}, when non-@code{nil}, -directs Emacs to display the @acronym{ASCII} value and the keyboard scan code of -each keystroke; this feature serves as a complement to the -@code{view-lossage} command, for debugging. - -@node MS-DOS Display -@section Display on MS-DOS -@cindex faces under MS-DOS -@cindex fonts, emulating under MS-DOS - - Display on MS-DOS cannot use font variants, like bold or italic, but -it does support multiple faces, each of which can specify a foreground -and a background color. Therefore, you can get the full functionality -of Emacs packages that use fonts (such as @code{font-lock}, Enriched -Text mode, and others) by defining the relevant faces to use different -colors. Use the @code{list-colors-display} command (@pxref{Frame -Parameters,,,emacs, the Emacs Manual}) and the -@code{list-faces-display} command (@pxref{Faces,,,emacs, the Emacs -Manual}) to see what colors and faces are available and what they look -like. - - @xref{MS-DOS and MULE}, later in this chapter, for information on -how Emacs displays glyphs and characters that aren't supported by the -native font built into the DOS display. - -@cindex cursor shape on MS-DOS - When Emacs starts, it changes the cursor shape to a solid box. This -is for compatibility with other systems, where the box cursor is the -default in Emacs. This default shape can be changed to a bar by -specifying the @code{cursor-type} parameter in the variable -@code{default-frame-alist} (@pxref{Creating Frames,,,emacs, the Emacs -Manual}). The MS-DOS terminal doesn't support a vertical-bar cursor, -so the bar cursor is horizontal, and the @code{@var{width}} parameter, -if specified by the frame parameters, actually determines its height. -For this reason, the @code{bar} and @code{hbar} cursor types produce -the same effect on MS-DOS. As an extension, the bar cursor -specification can include the starting scan line of the cursor as well -as its width, like this: - -@example - '(cursor-type bar @var{width} . @var{start}) -@end example - -@noindent -In addition, if the @var{width} parameter is negative, the cursor bar -begins at the top of the character cell. - -@cindex frames on MS-DOS - The MS-DOS terminal can only display a single frame at a time. The -Emacs frame facilities work on MS-DOS much as they do on text-only -terminals (@pxref{Frames,,,emacs, the Emacs Manual}). When you run -Emacs from a DOS window on MS-Windows, you can make the visible frame -smaller than the full screen, but Emacs still cannot display more than -a single frame at a time. - -@cindex frame size under MS-DOS -@findex mode4350 -@findex mode25 - The @code{mode4350} command switches the display to 43 or 50 -lines, depending on your hardware; the @code{mode25} command switches -to the default 80x25 screen size. - - By default, Emacs only knows how to set screen sizes of 80 columns by -25, 28, 35, 40, 43 or 50 rows. However, if your video adapter has -special video modes that will switch the display to other sizes, you can -have Emacs support those too. When you ask Emacs to switch the frame to -@var{n} rows by @var{m} columns dimensions, it checks if there is a -variable called @code{screen-dimensions-@var{n}x@var{m}}, and if so, -uses its value (which must be an integer) as the video mode to switch -to. (Emacs switches to that video mode by calling the BIOS @code{Set -Video Mode} function with the value of -@code{screen-dimensions-@var{n}x@var{m}} in the @code{AL} register.) -For example, suppose your adapter will switch to 66x80 dimensions when -put into video mode 85. Then you can make Emacs support this screen -size by putting the following into your @file{_emacs} file: - -@example -(setq screen-dimensions-66x80 85) -@end example - - Since Emacs on MS-DOS can only set the frame size to specific -supported dimensions, it cannot honor every possible frame resizing -request. When an unsupported size is requested, Emacs chooses the next -larger supported size beyond the specified size. For example, if you -ask for 36x80 frame, you will get 40x80 instead. - - The variables @code{screen-dimensions-@var{n}x@var{m}} are used only -when they exactly match the specified size; the search for the next -larger supported size ignores them. In the above example, even if your -VGA supports 38x80 dimensions and you define a variable -@code{screen-dimensions-38x80} with a suitable value, you will still get -40x80 screen when you ask for a 36x80 frame. If you want to get the -38x80 size in this case, you can do it by setting the variable named -@code{screen-dimensions-36x80} with the same video mode value as -@code{screen-dimensions-38x80}. - - Changing frame dimensions on MS-DOS has the effect of changing all the -other frames to the new dimensions. - -@node MS-DOS File Names -@section File Names on MS-DOS -@cindex file names under MS-DOS -@cindex init file, default name under MS-DOS - - On MS-DOS, file names are case-insensitive and limited to eight -characters, plus optionally a period and three more characters. Emacs -knows enough about these limitations to handle file names that were -meant for other operating systems. For instance, leading dots -@samp{.} in file names are invalid in MS-DOS, so Emacs transparently -converts them to underscores @samp{_}; thus your default init file -(@pxref{Init File,,,emacs, the Emacs Manual}) is called @file{_emacs} -on MS-DOS. Excess characters before or after the period are generally -ignored by MS-DOS itself; thus, if you visit the file -@file{LongFileName.EvenLongerExtension}, you will silently get -@file{longfile.eve}, but Emacs will still display the long file name -on the mode line. Other than that, it's up to you to specify file -names which are valid under MS-DOS; the transparent conversion as -described above only works on file names built into Emacs. - -@cindex backup file names on MS-DOS - The above restrictions on the file names on MS-DOS make it almost -impossible to construct the name of a backup file (@pxref{Backup -Names,,,emacs, the Emacs Manual}) without losing some of the original -file name characters. For example, the name of a backup file for -@file{docs.txt} is @file{docs.tx~} even if single backup is used. - -@cindex file names under Windows 95/NT -@cindex long file names in DOS box under Windows 95/NT - If you run Emacs as a DOS application under Windows 9X, Windows ME, or -Windows 2000, you can turn on support for long file names. If you do -that, Emacs doesn't truncate file names or convert them to lower case; -instead, it uses the file names that you specify, verbatim. To enable -long file name support, set the environment variable @env{LFN} to -@samp{y} before starting Emacs. Unfortunately, Windows NT doesn't allow -DOS programs to access long file names, so Emacs built for MS-DOS will -only see their short 8+3 aliases. - -@cindex @env{HOME} directory under MS-DOS - MS-DOS has no notion of home directory, so Emacs on MS-DOS pretends -that the directory where it is installed is the value of the @env{HOME} -environment variable. That is, if your Emacs binary, -@file{emacs.exe}, is in the directory @file{c:/utils/emacs/bin}, then -Emacs acts as if @env{HOME} were set to @samp{c:/utils/emacs}. In -particular, that is where Emacs looks for the init file @file{_emacs}. -With this in mind, you can use @samp{~} in file names as an alias for -the home directory, as you would on GNU or Unix. You can also set -@env{HOME} variable in the environment before starting Emacs; its -value will then override the above default behavior. - - Emacs on MS-DOS handles the directory name @file{/dev} specially, -because of a feature in the emulator libraries of DJGPP that pretends -I/O devices have names in that directory. We recommend that you avoid -using an actual directory named @file{/dev} on any disk. - -@node MS-DOS Printing -@section Printing and MS-DOS - - Printing commands, such as @code{lpr-buffer} -(@pxref{Printing,,,emacs, the Emacs Manual}) and -@code{ps-print-buffer} (@pxref{PostScript,,,emacs, the Emacs Manual}) -can work on MS-DOS by sending the output to one of the printer ports, -if a Posix-style @code{lpr} program is unavailable. The same Emacs -variables control printing on all systems, but in some cases they have -different default values on MS-DOS. - -@xref{MS-Windows Printing,,,emacs, the Emacs Manual}, for details. - - Some printers expect DOS codepage encoding of non-@acronym{ASCII} text, even -though they are connected to a Windows machine which uses a different -encoding for the same locale. For example, in the Latin-1 locale, DOS -uses codepage 850 whereas Windows uses codepage 1252. @xref{MS-DOS and -MULE}. When you print to such printers from Windows, you can use the -@kbd{C-x RET c} (@code{universal-coding-system-argument}) command before -@kbd{M-x lpr-buffer}; Emacs will then convert the text to the DOS -codepage that you specify. For example, @kbd{C-x RET c cp850-dos RET -M-x lpr-region RET} will print the region while converting it to the -codepage 850 encoding. You may need to create the @code{cp@var{nnn}} -coding system with @kbd{M-x codepage-setup}. - -@vindex dos-printer -@vindex dos-ps-printer - For backwards compatibility, the value of @code{dos-printer} -(@code{dos-ps-printer}), if it has a value, overrides the value of -@code{printer-name} (@code{ps-printer-name}), on MS-DOS. - - -@node MS-DOS and MULE -@section International Support on MS-DOS -@cindex international support @r{(MS-DOS)} - - Emacs on MS-DOS supports the same international character sets as it -does on GNU, Unix and other platforms (@pxref{International,,,emacs, -the Emacs Manual}), including coding systems for converting between -the different character sets. However, due to incompatibilities -between MS-DOS/MS-Windows and other systems, there are several -DOS-specific aspects of this support that you should be aware of. -This section describes these aspects. - - The description below is largely specific to the MS-DOS port of -Emacs, especially where it talks about practical implications for -Emacs users. For other operating systems, see the @file{code-pages.el} -package, which implements support for MS-DOS- and MS-Windows-specific -encodings for all platforms other than MS-DOS. - -@table @kbd -@item M-x dos-codepage-setup -Set up Emacs display and coding systems as appropriate for the current -DOS codepage. - -@item M-x codepage-setup -Create a coding system for a certain DOS codepage. -@end table - -@cindex codepage, MS-DOS -@cindex DOS codepages - MS-DOS is designed to support one character set of 256 characters at -any given time, but gives you a variety of character sets to choose -from. The alternative character sets are known as @dfn{DOS codepages}. -Each codepage includes all 128 @acronym{ASCII} characters, but the other 128 -characters (codes 128 through 255) vary from one codepage to another. -Each DOS codepage is identified by a 3-digit number, such as 850, 862, -etc. - - In contrast to X, which lets you use several fonts at the same time, -MS-DOS normally doesn't allow use of several codepages in a single -session. MS-DOS was designed to load a single codepage at system -startup, and require you to reboot in order to change -it@footnote{Normally, one particular codepage is burnt into the -display memory, while other codepages can be installed by modifying -system configuration files, such as @file{CONFIG.SYS}, and rebooting. -While there is third-party software that allows changing the codepage -without rebooting, we describe here how a stock MS-DOS system -behaves.}. Much the same limitation applies when you run DOS -executables on other systems such as MS-Windows. - -@cindex unibyte operation @r{(MS-DOS)} - If you invoke Emacs on MS-DOS with the @samp{--unibyte} option -(@pxref{Initial Options,,,emacs, the Emacs Manual}), Emacs does not -perform any conversion of non-@acronym{ASCII} characters. Instead, it -reads and writes any non-@acronym{ASCII} characters verbatim, and -sends their 8-bit codes to the display verbatim. Thus, unibyte Emacs -on MS-DOS supports the current codepage, whatever it may be, but -cannot even represent any other characters. - -@vindex dos-codepage - For multibyte operation on MS-DOS, Emacs needs to know which -characters the chosen DOS codepage can display. So it queries the -system shortly after startup to get the chosen codepage number, and -stores the number in the variable @code{dos-codepage}. Some systems -return the default value 437 for the current codepage, even though the -actual codepage is different. (This typically happens when you use the -codepage built into the display hardware.) You can specify a different -codepage for Emacs to use by setting the variable @code{dos-codepage} in -your init file. - -@cindex language environment, automatic selection on @r{MS-DOS} - Multibyte Emacs supports only certain DOS codepages: those which can -display Far-Eastern scripts, like the Japanese codepage 932, and those -that encode a single ISO 8859 character set. - - The Far-Eastern codepages can directly display one of the MULE -character sets for these countries, so Emacs simply sets up to use the -appropriate terminal coding system that is supported by the codepage. -The special features described in the rest of this section mostly -pertain to codepages that encode ISO 8859 character sets. - - For the codepages which correspond to one of the ISO character sets, -Emacs knows the character set name based on the codepage number. Emacs -automatically creates a coding system to support reading and writing -files that use the current codepage, and uses this coding system by -default. The name of this coding system is @code{cp@var{nnn}}, where -@var{nnn} is the codepage number.@footnote{The standard Emacs coding -systems for ISO 8859 are not quite right for the purpose, because -typically the DOS codepage does not match the standard ISO character -codes. For example, the letter @samp{@,{c}} (@samp{c} with cedilla) has -code 231 in the standard Latin-1 character set, but the corresponding -DOS codepage 850 uses code 135 for this glyph.} - -@cindex mode line @r{(MS-DOS)} - All the @code{cp@var{nnn}} coding systems use the letter @samp{D} -(for ``DOS'') as their mode-line mnemonic. Since both the terminal -coding system and the default coding system for file I/O are set to -the proper @code{cp@var{nnn}} coding system at startup, it is normal -for the mode line on MS-DOS to begin with @samp{-DD\-}. @xref{Mode -Line,,,emacs, the Emacs Manual}. Far-Eastern DOS terminals do not use -the @code{cp@var{nnn}} coding systems, and thus their initial mode -line looks like the Emacs default. - - Since the codepage number also indicates which script you are using, -Emacs automatically runs @code{set-language-environment} to select the -language environment for that script (@pxref{Language -Environments,,,emacs, the Emacs Manual}). - - If a buffer contains a character belonging to some other ISO 8859 -character set, not the one that the chosen DOS codepage supports, Emacs -displays it using a sequence of @acronym{ASCII} characters. For example, if the -current codepage doesn't have a glyph for the letter @samp{@`o} (small -@samp{o} with a grave accent), it is displayed as @samp{@{`o@}}, where -the braces serve as a visual indication that this is a single character. -(This may look awkward for some non-Latin characters, such as those from -Greek or Hebrew alphabets, but it is still readable by a person who -knows the language.) Even though the character may occupy several -columns on the screen, it is really still just a single character, and -all Emacs commands treat it as one. - -@cindex IBM graphics characters (MS-DOS) -@cindex box-drawing characters (MS-DOS) -@cindex line-drawing characters (MS-DOS) - Not all characters in DOS codepages correspond to ISO 8859 -characters---some are used for other purposes, such as box-drawing -characters and other graphics. Emacs maps these characters to two -special character sets called @code{eight-bit-control} and -@code{eight-bit-graphic}, and displays them as their IBM glyphs. -However, you should be aware that other systems might display these -characters differently, so you should avoid them in text that might be -copied to a different operating system, or even to another DOS machine -that uses a different codepage. - -@vindex dos-unsupported-character-glyph - Emacs supports many other characters sets aside from ISO 8859, but it -cannot display them on MS-DOS. So if one of these multibyte characters -appears in a buffer, Emacs on MS-DOS displays them as specified by the -@code{dos-unsupported-character-glyph} variable; by default, this glyph -is an empty triangle. Use the @kbd{C-u C-x =} command to display the -actual code and character set of such characters. @xref{Position -Info,,,emacs, the Emacs Manual}. - -@findex codepage-setup - By default, Emacs defines a coding system to support the current -codepage. To define a coding system for some other codepage (e.g., to -visit a file written on a DOS machine in another country), use the -@kbd{M-x codepage-setup} command. It prompts for the 3-digit code of -the codepage, with completion, then creates the coding system for the -specified codepage. You can then use the new coding system to read and -write files, but you must specify it explicitly for the file command -when you want to use it (@pxref{Text Coding,,,emacs, the Emacs Manual}). - - These coding systems are also useful for visiting a file encoded using -a DOS codepage, using Emacs running on some other operating system. - -@cindex MS-Windows codepages - MS-Windows provides its own codepages, which are different from the -DOS codepages for the same locale. For example, DOS codepage 850 -supports the same character set as Windows codepage 1252; DOS codepage -855 supports the same character set as Windows codepage 1251, etc. -The MS-Windows version of Emacs uses the current codepage for display -when invoked with the @samp{-nw} option. Support for codepages in the -Windows port of Emacs is part of the @file{code-pages.el} package. - -@node MS-DOS Processes -@section Subprocesses on MS-DOS - -@cindex compilation under MS-DOS -@cindex inferior processes under MS-DOS -@findex compile @r{(MS-DOS)} -@findex grep @r{(MS-DOS)} - Because MS-DOS is a single-process ``operating system,'' -asynchronous subprocesses are not available. In particular, Shell -mode and its variants do not work. Most Emacs features that use -asynchronous subprocesses also don't work on MS-DOS, including -Shell mode and GUD. When in doubt, try and see; commands that -don't work output an error message saying that asynchronous processes -aren't supported. - - Compilation under Emacs with @kbd{M-x compile}, searching files with -@kbd{M-x grep} and displaying differences between files with @kbd{M-x -diff} do work, by running the inferior processes synchronously. This -means you cannot do any more editing until the inferior process -finishes. - - Spell checking also works, by means of special support for synchronous -invocation of the @code{ispell} program. This is slower than the -asynchronous invocation on other platforms - - Instead of the Shell mode, which doesn't work on MS-DOS, you can use -the @kbd{M-x eshell} command. This invokes the Eshell package that -implements a Posix-like shell entirely in Emacs Lisp. - - By contrast, Emacs compiled as a native Windows application -@strong{does} support asynchronous subprocesses. @xref{Windows -Processes,,,emacs, the Emacs Manual}. - -@cindex printing under MS-DOS - Printing commands, such as @code{lpr-buffer} -(@pxref{Printing,,,emacs, the Emacs Manual}) and -@code{ps-print-buffer} (@pxref{PostScript,,,emacs, the Emacs Manual}), -work in MS-DOS by sending the output to one of the printer ports. -@xref{MS-DOS Printing,,,emacs, the Emacs Manual}. - - When you run a subprocess synchronously on MS-DOS, make sure the -program terminates and does not try to read keyboard input. If the -program does not terminate on its own, you will be unable to terminate -it, because MS-DOS provides no general way to terminate a process. -Pressing @kbd{C-c} or @kbd{C-@key{BREAK}} might sometimes help in these -cases. - - Accessing files on other machines is not supported on MS-DOS. Other -network-oriented commands such as sending mail, Web browsing, remote -login, etc., don't work either, unless network access is built into -MS-DOS with some network redirector. - -@cindex directory listing on MS-DOS -@vindex dired-listing-switches @r{(MS-DOS)} - Dired on MS-DOS uses the @code{ls-lisp} package where other -platforms use the system @code{ls} command. Therefore, Dired on -MS-DOS supports only some of the possible options you can mention in -the @code{dired-listing-switches} variable. The options that work are -@samp{-A}, @samp{-a}, @samp{-c}, @samp{-i}, @samp{-r}, @samp{-S}, -@samp{-s}, @samp{-t}, and @samp{-u}. - - @node Index @unnumbered Index |