2004-06-15 20:55:24 +00:00
|
|
|
\input texinfo @c -*-texinfo-*-
|
|
|
|
@comment %**start of header
|
|
|
|
@setfilename ../info/emacs-xtra
|
|
|
|
@settitle Specialized Emacs Features
|
|
|
|
@syncodeindex fn cp
|
|
|
|
@syncodeindex vr cp
|
|
|
|
@syncodeindex ky cp
|
|
|
|
@comment %**end of header
|
|
|
|
|
|
|
|
@copying
|
2004-06-19 00:59:28 +00:00
|
|
|
This manual describes specialized features of Emacs.
|
2004-06-15 20:55:24 +00:00
|
|
|
|
2006-03-25 23:15:32 +00:00
|
|
|
Copyright @copyright{} 2004, 2005, 2006 Free Software Foundation, Inc.
|
2004-06-15 20:55:24 +00:00
|
|
|
|
|
|
|
@quotation
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
2005-09-16 22:11:06 +00:00
|
|
|
under the terms of the GNU Free Documentation License, Version 1.2 or
|
2004-06-15 20:55:24 +00:00
|
|
|
any later version published by the Free Software Foundation; with no
|
|
|
|
Invariant Sections, with the Front-Cover texts being ``A GNU
|
|
|
|
Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
|
|
|
|
license is included in the section entitled ``GNU Free Documentation
|
|
|
|
License'' in the Emacs manual.
|
|
|
|
|
|
|
|
(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
|
|
|
|
this GNU Manual, like GNU software. Copies published by the Free
|
|
|
|
Software Foundation raise funds for GNU development.''
|
|
|
|
|
|
|
|
This document is part of a collection distributed under the GNU Free
|
|
|
|
Documentation License. If you want to distribute this document
|
|
|
|
separately from the collection, you can do so by adding a copy of the
|
|
|
|
license to the document, as described in section 6 of the license.
|
|
|
|
@end quotation
|
|
|
|
@end copying
|
|
|
|
|
|
|
|
@dircategory Emacs
|
|
|
|
@direntry
|
|
|
|
* Emacs-Xtra: (emacs-xtra). Specialized Emacs features.
|
|
|
|
@end direntry
|
|
|
|
|
|
|
|
@titlepage
|
|
|
|
@title Specialized Emacs Features
|
|
|
|
@page
|
|
|
|
@vskip 0pt plus 1filll
|
|
|
|
@insertcopying
|
|
|
|
@end titlepage
|
|
|
|
|
|
|
|
@contents
|
|
|
|
|
|
|
|
@ifnottex
|
|
|
|
@node Top
|
|
|
|
@top Specialized Emacs Features
|
|
|
|
|
|
|
|
@insertcopying
|
|
|
|
|
|
|
|
@end ifnottex
|
|
|
|
|
|
|
|
@menu
|
|
|
|
* Introduction:: What documentation belongs here?
|
|
|
|
* Autorevert:: Auto Reverting non-file buffers.
|
2006-04-12 00:27:50 +00:00
|
|
|
* Subdir Switches:: Subdirectory switches in Dired.
|
2005-03-26 17:45:40 +00:00
|
|
|
* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization.
|
2006-03-17 00:59:05 +00:00
|
|
|
* Emerge:: A convenient way of merging two versions
|
|
|
|
of a program.
|
2006-03-16 03:19:56 +00:00
|
|
|
* Picture Mode:: Editing pictures made up of characters
|
|
|
|
using the quarter-plane screen model.
|
2006-04-12 00:27:50 +00:00
|
|
|
|
|
|
|
* Advanced VC Usage:: Advanced VC (version control) features.
|
2006-03-16 03:19:56 +00:00
|
|
|
* Fortran:: Fortran mode and its special features.
|
2006-04-09 22:40:34 +00:00
|
|
|
* MS-DOG::
|
2004-06-15 20:55:24 +00:00
|
|
|
* Index::
|
|
|
|
@end menu
|
|
|
|
|
|
|
|
@node Introduction
|
|
|
|
@unnumbered Introduction
|
|
|
|
|
|
|
|
This manual contains detailed information about various features that
|
|
|
|
are too specialized to be included in the 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.
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
2004-06-16 01:24:00 +00:00
|
|
|
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}.
|
|
|
|
|
2004-06-15 20:55:24 +00:00
|
|
|
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
|
|
|
|
|
2004-06-17 17:16:36 +00:00
|
|
|
Auto-reverting Dired buffers currently works on GNU or Unix style
|
|
|
|
operating systems. It may not work satisfactorily on some other
|
|
|
|
systems.
|
2004-06-15 20:55:24 +00:00
|
|
|
|
|
|
|
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
|
2004-06-17 17:16:36 +00:00
|
|
|
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.
|
2004-06-15 20:55:24 +00:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
2004-06-16 01:24:00 +00:00
|
|
|
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.
|
2004-06-15 20:55:24 +00:00
|
|
|
@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.
|
2004-06-16 01:24:00 +00:00
|
|
|
This is especially important for buffers that automatically
|
|
|
|
auto-revert every @code{auto-revert-interval} seconds.
|
2004-06-15 20:55:24 +00:00
|
|
|
|
2004-06-19 00:59:28 +00:00
|
|
|
Also, you may want to update the documentation string of
|
|
|
|
@code{global-auto-revert-non-file-buffers}.
|
|
|
|
|
2004-06-15 20:55:24 +00:00
|
|
|
@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).
|
|
|
|
|
2006-04-12 00:27:50 +00:00
|
|
|
@node Subdir Switches
|
2004-06-15 20:55:24 +00:00
|
|
|
@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}.
|
|
|
|
|
2005-02-09 15:50:47 +00:00
|
|
|
In Emacs versions 22.1 and later, Dired remembers the switches, so
|
2004-06-15 20:55:24 +00:00
|
|
|
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}.
|
|
|
|
|
2004-07-18 16:00:16 +00:00
|
|
|
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.
|
2004-07-18 16:23:45 +00:00
|
|
|
For instance, updating or killing a subdirectory that was inserted
|
|
|
|
with the @code{R} switch will not update or kill its subdirectories.
|
2004-07-18 16:00:16 +00:00
|
|
|
|
2004-06-15 20:55:24 +00:00
|
|
|
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.
|
|
|
|
|
2005-03-26 17:45:40 +00:00
|
|
|
|
|
|
|
@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}.
|
|
|
|
|
2006-03-16 03:19:56 +00:00
|
|
|
@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.
|
|
|
|
|
2006-04-12 00:27:50 +00:00
|
|
|
@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
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
You can then edit the new change log entry further as you wish.
|
|
|
|
|
|
|
|
Some of the new change log entries may duplicate what's already in
|
|
|
|
ChangeLog. You will have to remove these duplicates by hand.
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
@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
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
@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
|
|
|
|
|
|
|
|
@noindent
|
|
|
|
They appear like this in @file{ChangeLog}:
|
|
|
|
|
|
|
|
@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
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
2006-03-16 03:19:56 +00:00
|
|
|
@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.
|
2005-03-26 17:45:40 +00:00
|
|
|
|
2006-04-09 22:40:34 +00:00
|
|
|
|
|
|
|
@node MS-DOG
|
|
|
|
@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{Emacs and 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.
|
2006-04-21 11:42:01 +00:00
|
|
|
* Printing: MS-DOS Printing. Printing specifics on MS-DOS.
|
2006-04-09 22:40:34 +00:00
|
|
|
* 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}
|
2006-04-21 11:42:01 +00:00
|
|
|
(@pxref{Printing,,,emacs, the Emacs Manual}) and
|
2006-04-09 22:40:34 +00:00
|
|
|
@code{ps-print-buffer} (@pxref{PostScript,,,emacs, the Emacs Manual})
|
2006-04-21 11:42:01 +00:00
|
|
|
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.
|
2006-04-09 22:40:34 +00:00
|
|
|
|
|
|
|
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
|
2006-04-21 11:42:01 +00:00
|
|
|
@code{printer-name} (@code{ps-printer-name}), on MS-DOS.
|
2006-04-09 22:40:34 +00:00
|
|
|
|
|
|
|
|
|
|
|
@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}.
|
|
|
|
|
|
|
|
|
2004-06-15 20:55:24 +00:00
|
|
|
@node Index
|
|
|
|
@unnumbered Index
|
|
|
|
|
|
|
|
@printindex cp
|
|
|
|
|
|
|
|
@bye
|
2004-06-16 02:44:20 +00:00
|
|
|
|
|
|
|
@ignore
|
|
|
|
arch-tag: 75c33f13-32c6-41b6-9537-847a312e2e49
|
|
|
|
@end ignore
|