* man/files.texi
@ 2005-03-22 3:06 Luc Teirlinck
2005-03-22 20:45 ` man/files.texi Richard Stallman
0 siblings, 1 reply; 6+ messages in thread
From: Luc Teirlinck @ 2005-03-22 3:06 UTC (permalink / raw
The patch below contains some proposed changes to man/files.texi.
Most of these have to do with VC. Small parts of VC have been
relatively recently updated for SVN, GNU Arch and MCVS, but certain
aspects of other parts seemed still out of date. The patch also contains
a few corrections unrelated to VC.
Some parts I was not really sure about:
1. `(emacs)Branches' contains:
Please note, however, that branches are only supported for RCS at
the moment.
I do not use branches myself, but this can not possibly be true, is it?
The patch below replaces it by:
Please note, however, that branches are not supported for SCCS.
Is this correct?
2. (emacs)Local Version Control contains:
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, using `C-u C-x v v cvs <RET>'.
`C-u C-x v v cvs <RET>'? Is that not going to try to commit to the
repository? The patch below replaces it with `C-x v b'. Is this correct?
I can install if desired.
===File ~/man-files-diff====================================
diff -c /home/teirllm/emacscvsdir/emacs/man/ /home/teirllm/files.texi
*** /home/teirllm/emacscvsdir/emacs/man/files.texi Mon Mar 21 20:19:30 2005
--- /home/teirllm/files.texi Mon Mar 21 20:13:12 2005
***************
*** 238,250 ****
of prompting for the file name in the minibuffer. On Unix and
GNU/Linux platforms, Emacs does that when built with GTK, LessTif, and
Motif toolkits; on MS-Windows, the GUI version does that by default.
! For information on how to customize this, see @xref{Dialog Boxes}.
Secondly, Emacs supports the ``drag and drop'' protocol on the X
window system. Dropping a file into an ordinary Emacs window visits
the file using that window. However, dropping a file into a window
displaying a Dired buffer moves or copies the file into the displayed
! directory. For details, see @xref{Drag and Drop} and @xref{Misc Dired
Features}.
@cindex creating files
--- 238,250 ----
of prompting for the file name in the minibuffer. On Unix and
GNU/Linux platforms, Emacs does that when built with GTK, LessTif, and
Motif toolkits; on MS-Windows, the GUI version does that by default.
! For information on how to customize this, see @ref{Dialog Boxes}.
Secondly, Emacs supports the ``drag and drop'' protocol on the X
window system. Dropping a file into an ordinary Emacs window visits
the file using that window. However, dropping a file into a window
displaying a Dired buffer moves or copies the file into the displayed
! directory. For details, see @ref{Drag and Drop}, and @ref{Misc Dired
Features}.
@cindex creating files
***************
*** 1263,1268 ****
--- 1263,1272 ----
SCCS only if for some reason you cannot use RCS, or one of the
higher-level systems such as CVS or GNU Arch.
+ In the following, we discuss mainly RCS, SCCS and CVS. Nearly
+ everything said about CVS applies to Gnu Arch, Subversion and Meta-CVS
+ as well.
+
@node VC Concepts
@subsubsection Concepts of Version Control
***************
*** 1463,1471 ****
since you began editing it, and when this happens, his changes will be
effectively removed when you check in your version (though they will
remain in the master file, so they will not be entirely lost). You must
! therefore verify the current version is unchanged, before you check in your
! changes. We hope to eliminate this risk and provide automatic merging
! with RCS in a future Emacs version.
In addition, locking is possible with RCS even in this mode, although
it is not required; @kbd{C-x v v} with an unmodified file locks the
--- 1467,1475 ----
since you began editing it, and when this happens, his changes will be
effectively removed when you check in your version (though they will
remain in the master file, so they will not be entirely lost). You must
! therefore verify that the current version is unchanged, before you
! check in your changes. We hope to eliminate this risk and provide
! automatic merging with RCS in a future Emacs version.
In addition, locking is possible with RCS even in this mode, although
it is not required; @kbd{C-x v v} with an unmodified file locks the
***************
*** 1689,1701 ****
that appears first in @code{vc-handled-backends} (@pxref{Customizing VC}).
On the other hand, if there are no files already registered,
Emacs uses the first system from @code{vc-handled-backends} that could
! register the file---for example, you cannot register a file under CVS if
! its directory is not already part of a CVS tree.
!
! With the default value of @code{vc-handled-backends}, this means
! that Emacs uses RCS if there are any files under RCS control, CVS if
! there are any files under CVS, SCCS if any files are under SCCS, or
! RCS as the ultimate default.
If locking is in use, @kbd{C-x v i} leaves the file unlocked and
read-only. Type @kbd{C-x v v} if you wish to start editing it. After
--- 1693,1702 ----
that appears first in @code{vc-handled-backends} (@pxref{Customizing VC}).
On the other hand, if there are no files already registered,
Emacs uses the first system from @code{vc-handled-backends} that could
! register the file (for example, you cannot register a file under CVS if
! its directory is not already part of a CVS tree); with the default
! value of @code{vc-handled-backends}, this means that Emacs uses RCS in
! this situation.
If locking is in use, @kbd{C-x v i} leaves the file unlocked and
read-only. Type @kbd{C-x v v} if you wish to start editing it. After
***************
*** 1883,1889 ****
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 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
--- 1884,1891 ----
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
***************
*** 1911,1918 ****
features. Each such independent line of development is called a
@dfn{branch}. VC allows you to create branches, switch between
different branches, and merge changes from one branch to another.
! Please note, however, that branches are only supported for RCS at the
! moment.
A file's main line of development is usually called the @dfn{trunk}.
The versions on the trunk are normally numbered 1.1, 1.2, 1.3, etc. At
--- 1913,1919 ----
features. Each such independent line of development is called a
@dfn{branch}. VC allows you to create branches, switch between
different branches, and merge changes from one branch to another.
! Please note, however, that branches are not supported for SCCS.
A file's main line of development is usually called the @dfn{trunk}.
The versions on the trunk are normally numbered 1.1, 1.2, 1.3, etc. At
***************
*** 2255,2261 ****
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, using @kbd{C-u C-x v v cvs @key{RET}}.
@node Snapshots
@subsection Snapshots
--- 2256,2262 ----
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, using @kbd{C-x v b}.
@node Snapshots
@subsection Snapshots
***************
*** 2543,2555 ****
Insert headers in a file for use with your version-control system.
@end table
! @vindex vc-header-alist
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 variable @code{vc-header-alist}. Its value is a list of
! elements of the form @code{(@var{program} . @var{string})} where
! @var{program} is @code{RCS} or @code{SCCS} and @var{string} is the
! string to use.
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
--- 2544,2554 ----
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
***************
*** 2577,2584 ****
@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-header-alist}. The header line is made by processing the
! string from @code{vc-header-alist} with the format taken from the
element. The default value for @code{vc-static-header-alist} is as follows:
@example
--- 2576,2583 ----
@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
***************
*** 2615,2624 ****
@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
! SCCS)}, so it contains all three 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}),
--- 2614,2623 ----
@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}),
***************
*** 2771,2778 ****
@key{RET}}, @pxref{Merging}).
@vindex vc-cvs-global-switches
! The variable @code{vc-cvs-global-switches} should be a string
! specifying switches to pass to CVS for all CVS operations.
When @code{vc-cvs-stay-local} is @code{t}, VC also makes local
version backups, so that simple diff and revert operations are
--- 2770,2778 ----
@key{RET}}, @pxref{Merging}).
@vindex vc-cvs-global-switches
! The variable @code{vc-cvs-global-switches}, if non-@code{nil},
! should be a string specifying switches to pass to CVS for all CVS
! operations.
When @code{vc-cvs-stay-local} is @code{t}, VC also makes local
version backups, so that simple diff and revert operations are
***************
*** 2891,2897 ****
With a numeric argument, @code{compare-windows} ignores changes in
whitespace. If the variable @code{compare-ignore-case} is
non-@code{nil}, the comparison ignores differences in case as well.
! If the variable @code{compare-ignore-whitespace} is non-nil,
@code{compare-windows} normally ignores changes in whitespace, and a
prefix argument turns that off.
--- 2891,2897 ----
With a numeric argument, @code{compare-windows} ignores changes in
whitespace. If the variable @code{compare-ignore-case} is
non-@code{nil}, the comparison ignores differences in case as well.
! If the variable @code{compare-ignore-whitespace} is non-@code{nil},
@code{compare-windows} normally ignores changes in whitespace, and a
prefix argument turns that off.
Diff finished. Mon Mar 21 20:21:52 2005
============================================================
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: man/files.texi
2005-03-22 3:06 man/files.texi Luc Teirlinck
@ 2005-03-22 20:45 ` Richard Stallman
0 siblings, 0 replies; 6+ messages in thread
From: Richard Stallman @ 2005-03-22 20:45 UTC (permalink / raw
Cc: emacs-devel
Your changes are well-written. I don't know the answers to the
two questions, though.
^ permalink raw reply [flat|nested] 6+ messages in thread
* man/files.texi
@ 2005-03-27 3:51 Luc Teirlinck
2005-03-27 11:00 ` man/files.texi Eli Zaretskii
0 siblings, 1 reply; 6+ messages in thread
From: Luc Teirlinck @ 2005-03-27 3:51 UTC (permalink / raw
The recent addition of auto-revert-check-vc-info to man/files.texi is
somewhat confusing. It seems to suggest that the normal state of any
buffer is to have version control info in the mode line. Just
mentioning VC without reference at that stage is confusing to a reader
reading the manual back to front, because the concept of VC has not
yet been introduced at that stage. What about the following small
change? I can install if desired.
===File ~/man-files.texi-diff===============================
*** files.texi 26 Mar 2005 09:57:37 -0600 1.101
--- files.texi 26 Mar 2005 20:54:06 -0600
***************
*** 941,953 ****
modes do not check or revert remote files.
@vindex auto-revert-check-vc-info
! Whenever Auto Revert mode reverts the buffer, it updates the version
! control information, such as the version control number displayed in
! the mode line. However, this information may not be properly updated
! if the version control state changes outside of Emacs---for example,
! if a new version is checked in from outside the current Emacs session.
! If you set @code{auto-revert-check-vc-info} to @code{t}, Auto Revert
! mode will update the version control status information periodically.
@node Auto Save
@section Auto-Saving: Protection Against Disasters
--- 941,954 ----
modes do not check or revert remote files.
@vindex auto-revert-check-vc-info
! Whenever Auto Revert mode reverts a buffer that is under version
! control (@pxref{Version Control}), it updates the version control
! information, such as the version control number displayed in the mode
! line. However, this information may not be properly updated if the
! version control state changes outside of Emacs---for example, if a new
! version is checked in from outside the current Emacs session. If you
! set @code{auto-revert-check-vc-info} to @code{t}, Auto Revert mode
! will update the version control status information periodically.
@node Auto Save
@section Auto-Saving: Protection Against Disasters
============================================================
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: man/files.texi
2005-03-27 3:51 man/files.texi Luc Teirlinck
@ 2005-03-27 11:00 ` Eli Zaretskii
2005-03-30 3:14 ` man/files.texi Luc Teirlinck
0 siblings, 1 reply; 6+ messages in thread
From: Eli Zaretskii @ 2005-03-27 11:00 UTC (permalink / raw
Cc: emacs-devel
> Date: Sat, 26 Mar 2005 21:51:59 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
>
> The recent addition of auto-revert-check-vc-info to man/files.texi is
> somewhat confusing. It seems to suggest that the normal state of any
> buffer is to have version control info in the mode line. Just
> mentioning VC without reference at that stage is confusing to a reader
> reading the manual back to front, because the concept of VC has not
> yet been introduced at that stage.
Indeed.
> What about the following small change? I can install if desired.
>
> ===File ~/man-files.texi-diff===============================
> *** files.texi 26 Mar 2005 09:57:37 -0600 1.101
> --- files.texi 26 Mar 2005 20:54:06 -0600
How about moving the entire documentation of auto-revert-check-vc-info
to one of the sections that document VC? The section about reverting
could then say something like
xref{..., auto-revert-check-vc-info}, for Auto Revert peculiarities
in buffers that visit files under version control.
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: man/files.texi
2005-03-27 11:00 ` man/files.texi Eli Zaretskii
@ 2005-03-30 3:14 ` Luc Teirlinck
2005-03-30 4:59 ` man/files.texi Eli Zaretskii
0 siblings, 1 reply; 6+ messages in thread
From: Luc Teirlinck @ 2005-03-30 3:14 UTC (permalink / raw
Cc: emacs-devel
Eli Zaretskii wrote:
How about moving the entire documentation of auto-revert-check-vc-info
to one of the sections that document VC?
I indeed believe that it belongs in `(emacs)VC Mode Line'. I also
made some further changes to the text. I propose the following patch,
which I can install, if desired:
===File ~/man-files.texi-diff===============================
diff -c /home/teirllm/emacscvsdir/emacs/man/files.texi /home/teirllm/files-mar29.texi
*** /home/teirllm/emacscvsdir/emacs/man/files.texi Tue Mar 29 20:31:35 2005
--- /home/teirllm/files-mar29.texi Tue Mar 29 20:17:05 2005
***************
*** 940,954 ****
for a changed file. Since checking a remote file is too slow, these
modes do not check or revert remote files.
- @vindex auto-revert-check-vc-info
- Whenever Auto Revert mode reverts the buffer, it updates the version
- control information, such as the version control number displayed in
- the mode line. However, this information may not be properly updated
- if the version control state changes outside of Emacs---for example,
- if a new version is checked in from outside the current Emacs session.
- If you set @code{auto-revert-check-vc-info} to @code{t}, Auto Revert
- mode will update the version control status information periodically.
-
@node Auto Save
@section Auto-Saving: Protection Against Disasters
@cindex Auto Save mode
--- 940,945 ----
***************
*** 1375,1380 ****
--- 1366,1383 ----
that it is modified. If the file is locked by some other user (for
instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}.
+ @vindex auto-revert-check-vc-info
+ When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is
+ under version control, it updates the version control information in
+ the mode line. However, Auto Revert mode may not properly update this
+ information if you change the version control status without changes
+ to the work file, from outside the current Emacs session. If you set
+ @code{auto-revert-check-vc-info} to @code{t}, Auto Revert mode updates
+ the version control status information every
+ @code{auto-revert-interval} seconds, even if the work file itself is
+ unchanged. The resulting CPU usage depends on the version control
+ system, but is usually not excessive.
+
@node Basic VC Editing
@subsection Basic Editing under Version Control
Diff finished. Tue Mar 29 20:32:03 2005
============================================================
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: man/files.texi
2005-03-30 3:14 ` man/files.texi Luc Teirlinck
@ 2005-03-30 4:59 ` Eli Zaretskii
0 siblings, 0 replies; 6+ messages in thread
From: Eli Zaretskii @ 2005-03-30 4:59 UTC (permalink / raw
Cc: emacs-devel
> Date: Tue, 29 Mar 2005 21:14:13 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> CC: emacs-devel@gnu.org
>
> - @vindex auto-revert-check-vc-info
> - Whenever Auto Revert mode reverts the buffer, it updates the version
> - control information, such as the version control number displayed in
> - the mode line. However, this information may not be properly updated
> - if the version control state changes outside of Emacs---for example,
> - if a new version is checked in from outside the current Emacs session.
> - If you set @code{auto-revert-check-vc-info} to @code{t}, Auto Revert
> - mode will update the version control status information periodically.
> -
I suggest to add an xref here to the place where you moved the
description of auto-revert-check-vc-info.
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2005-03-30 4:59 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2005-03-27 3:51 man/files.texi Luc Teirlinck
2005-03-27 11:00 ` man/files.texi Eli Zaretskii
2005-03-30 3:14 ` man/files.texi Luc Teirlinck
2005-03-30 4:59 ` man/files.texi Eli Zaretskii
-- strict thread matches above, loose matches on Subject: below --
2005-03-22 3:06 man/files.texi Luc Teirlinck
2005-03-22 20:45 ` man/files.texi Richard Stallman
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).