[Emacs-diffs] Changes to emacs/man/files.texi

[Andre Spiegel]

Index: emacs/man/files.texi
diff -c emacs/man/files.texi:1.76 emacs/man/files.texi:1.77
*** emacs/man/files.texi:1.76   Mon Jul 15 05:47:14 2002
--- emacs/man/files.texi        Tue Jul 16 14:01:19 2002
***************
*** 276,282 ****
  or that is marked read-only, Emacs makes the buffer read-only too, so
  that you won't go ahead and make changes that you'll have trouble
  saving afterward.  You can make the buffer writable with @kbd{C-x C-q}
! (@code{vc-toggle-read-only}).  @xref{Misc Buffer}.
  
  @kindex C-x C-r
  @findex find-file-read-only
--- 276,282 ----
  or that is marked read-only, Emacs makes the buffer read-only too, so
  that you won't go ahead and make changes that you'll have trouble
  saving afterward.  You can make the buffer writable with @kbd{C-x C-q}
! (@code{toggle-read-only}).  @xref{Misc Buffer}.
  
  @kindex C-x C-r
  @findex find-file-read-only
***************
*** 1285,1314 ****
  either locking or check-in, depending on the situation.
  
  @table @kbd
- @item C-x C-q
  @itemx C-x v v
  Perform the next logical version control operation on this file.
  @end table
  
  @findex vc-next-action
- @findex vc-toggle-read-only
  @kindex C-x v v
- @kindex C-x C-q @r{(Version Control)}
-   Strictly speaking, the command for this job is @code{vc-next-action},
- bound to @kbd{C-x v v}.  However, the normal meaning of @kbd{C-x C-q} is
- to make a read-only buffer writable, or vice versa; we have extended it
- to do the same job properly for files managed by version control, by
- performing the appropriate version control operations.  When you type
- @kbd{C-x C-q} on a registered file, it acts like @kbd{C-x v v}.
- 
    The precise action of this command depends on the state of the file,
  and whether the version control system uses locking or not.  SCCS and
  RCS normally use locking; CVS normally does not use locking.
  
  @menu
  * VC with Locking::     RCS in its default mode, SCCS, and optionally CVS.
  * Without Locking::     Without locking: default mode for CVS.
! * Advanced C-x C-q::    Advanced features available with a prefix argument.
  * Log Buffer::          Features available in log entry buffers.
  @end menu
                 
--- 1285,1313 ----
  either locking or check-in, depending on the situation.
  
  @table @kbd
  @itemx C-x v v
  Perform the next logical version control operation on this file.
  @end table
  
  @findex vc-next-action
  @kindex C-x v v
    The precise action of this command depends on the state of the file,
  and whether the version control system uses locking or not.  SCCS and
  RCS normally use locking; CVS normally does not use locking.
  
+ @findex vc-toggle-read-only
+ @kindex C-x C-q @r{(Version Control)}
+   As a special convenience that is particularly useful for files with
+ locking, you can let Emacs check a file in or out whenever you change
+ its read-only flag.  This means, for example, that you cannot
+ accidentally edit a file without properly checking it out first.  To
+ achieve this, bind the key @kbd{C-x C-q} to @kbd{vc-toggle-read-only}
+ in your @file{~/.emacs} file.  (@xref{Init Rebinding}.)
+ 
  @menu
  * VC with Locking::     RCS in its default mode, SCCS, and optionally CVS.
  * Without Locking::     Without locking: default mode for CVS.
! * Advanced C-x v v::    Advanced features available with a prefix argument.
  * Log Buffer::          Features available in log entry buffers.
  @end menu
                 
***************
*** 1316,1340 ****
  @subsubsection Basic Version Control with Locking
  
    If locking is used for the file (as with SCCS, and RCS in its default
! mode), @kbd{C-x C-q} can either lock a file or check it in:
  
  @itemize @bullet
  @item
! If the file is not locked, @kbd{C-x C-q} locks it, and
  makes it writable so that you can change it.
  
  @item
! If the file is locked by you, and contains changes, @kbd{C-x C-q} checks
  in the changes.  In order to do this, it first reads the log entry
  for the new version.  @xref{Log Buffer}.
  
  @item
  If the file is locked by you, but you have not changed it since you
! locked it, @kbd{C-x C-q} releases the lock and makes the file read-only
  again.
  
  @item
! If the file is locked by some other user, @kbd{C-x C-q} asks you whether
  you want to ``steal the lock'' from that user.  If you say yes, the file
  becomes locked by you, but a message is sent to the person who had
  formerly locked the file, to inform him of what has happened.
--- 1315,1339 ----
  @subsubsection Basic Version Control with Locking
  
    If locking is used for the file (as with SCCS, and RCS in its default
! mode), @kbd{C-x v v} can either lock a file or check it in:
  
  @itemize @bullet
  @item
! If the file is not locked, @kbd{C-x v v} locks it, and
  makes it writable so that you can change it.
  
  @item
! If the file is locked by you, and contains changes, @kbd{C-x v v} checks
  in the changes.  In order to do this, it first reads the log entry
  for the new version.  @xref{Log Buffer}.
  
  @item
  If the file is locked by you, but you have not changed it since you
! locked it, @kbd{C-x v v} releases the lock and makes the file read-only
  again.
  
  @item
! If the file is locked by some other user, @kbd{C-x v v} asks you whether
  you want to ``steal the lock'' from that user.  If you say yes, the file
  becomes locked by you, but a message is sent to the person who had
  formerly locked the file, to inform him of what has happened.
***************
*** 1352,1358 ****
  unmodified; it flips to @samp{:} as soon as you save any changes in the
  work file.
  
!   Here is what @kbd{C-x C-q} does when using CVS:
  
  @itemize @bullet
  @item
--- 1351,1357 ----
  unmodified; it flips to @samp{:} as soon as you save any changes in the
  work file.
  
!   Here is what @kbd{C-x v v} does when using CVS:
  
  @itemize @bullet
  @item
***************
*** 1365,1376 ****
  
  @item
  If there are no new changes in the master file, but you have made
! modifications in your work file, @kbd{C-x C-q} checks in your changes.
  In order to do this, it first reads the log entry for the new version.
  @xref{Log Buffer}.
  
  @item
! If the file is not modified, the @kbd{C-x C-q} does nothing.
  @end itemize
  
    These rules also apply when you use RCS in the mode that does not
--- 1364,1375 ----
  
  @item
  If there are no new changes in the master file, but you have made
! modifications in your work file, @kbd{C-x v v} checks in your changes.
  In order to do this, it first reads the log entry for the new version.
  @xref{Log Buffer}.
  
  @item
! If the file is not modified, the @kbd{C-x v v} does nothing.
  @end itemize
  
    These rules also apply when you use RCS in the mode that does not
***************
*** 1385,1399 ****
  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 C-q} with an unmodified file locks the
  file, just as it does with RCS in its normal (locking) mode.
  
! @node Advanced C-x C-q
! @subsubsection Advanced Control in @kbd{C-x C-q}
  
  @cindex version number to check in/out
    When you give a prefix argument to @code{vc-next-action} (@kbd{C-u
! C-x C-q}), it still performs the next logical version control
  operation, but accepts additional arguments to specify precisely how
  to do the operation.
  
--- 1384,1398 ----
  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
  file, just as it does with RCS in its normal (locking) mode.
  
! @node Advanced C-x v v
! @subsubsection Advanced Control in @kbd{C-x v v}
  
  @cindex version number to check in/out
    When you give a prefix argument to @code{vc-next-action} (@kbd{C-u
! C-x v v}), it still performs the next logical version control
  operation, but accepts additional arguments to specify precisely how
  to do the operation.
  
***************
*** 1408,1414 ****
  version to select; this lets you start working from an older version,
  or on another branch.  If you do not enter any version, that takes you
  to the highest version on the current branch; therefore @kbd{C-u C-x
! C-q @key{RET}} is a convenient way to get the latest version of a file from
  the repository.
  
  @item
--- 1407,1413 ----
  version to select; this lets you start working from an older version,
  or on another branch.  If you do not enter any version, that takes you
  to the highest version on the current branch; therefore @kbd{C-u C-x
! v v @key{RET}} is a convenient way to get the latest version of a file from
  the repository.
  
  @item
***************
*** 1422,1428 ****
  @node Log Buffer
  @subsubsection Features of the Log Entry Buffer
  
!   When you check in changes, @kbd{C-x C-q} first reads a log entry.  It
  pops up a buffer called @samp{*VC-Log*} for you to enter the log entry.
  When you are finished, type @kbd{C-c C-c} in the @samp{*VC-Log*} buffer.
  That is when check-in really happens.
--- 1421,1427 ----
  @node Log Buffer
  @subsubsection Features of the Log Entry Buffer
  
!   When you check in changes, @kbd{C-x v v} first reads a log entry.  It
  pops up a buffer called @samp{*VC-Log*} for you to enter the log entry.
  When you are finished, type @kbd{C-c C-c} in the @samp{*VC-Log*} buffer.
  That is when check-in really happens.
***************
*** 1574,1582 ****
  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 C-q} if you wish to start editing it.  After
  registering a file with CVS, you must subsequently commit the initial
! version by typing @kbd{C-x C-q}.
  
  @vindex vc-default-init-version
  @cindex initial version number to register
--- 1573,1581 ----
  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
  registering a file with CVS, you must subsequently commit the initial
! version by typing @kbd{C-x v v}.
  
  @vindex vc-default-init-version
  @cindex initial version number to register
***************
*** 1815,1821 ****
  @node Switching Branches
  @subsubsection Switching between Branches
  
!   To switch between branches, type @kbd{C-u C-x C-q} and specify the
  version number you want to select.  This version is then visited
  @emph{unlocked} (write-protected), so you can examine it before locking
  it.  Switching branches in this way is allowed only when the file is not
--- 1814,1820 ----
  @node Switching Branches
  @subsubsection Switching between Branches
  
!   To switch between branches, type @kbd{C-u C-x v v} and specify the
  version number you want to select.  This version is then visited
  @emph{unlocked} (write-protected), so you can examine it before locking
  it.  Switching branches in this way is allowed only when the file is not
***************
*** 1834,1841 ****
  
    To create a new branch from a head version (one that is the latest in
  the branch that contains it), first select that version if necessary,
! lock it with @kbd{C-x C-q}, and make whatever changes you want.  Then,
! when you check in the changes, use @kbd{C-u C-x C-q}.  This lets you
  specify the version number for the new version.  You should specify a
  suitable branch number for a branch starting at the current version.
  For example, if the current version is 2.5, the branch number should be
--- 1833,1840 ----
  
    To create a new branch from a head version (one that is the latest in
  the branch that contains it), first select that version if necessary,
! lock it with @kbd{C-x v v}, and make whatever changes you want.  Then,
! when you check in the changes, use @kbd{C-u C-x v v}.  This lets you
  specify the version number for the new version.  You should specify a
  suitable branch number for a branch starting at the current version.
  For example, if the current version is 2.5, the branch number should be
***************
*** 1844,1855 ****
  
    To create a new branch at an older version (one that is no longer the
  head of a branch), first select that version (@pxref{Switching
! Branches}), then lock it with @kbd{C-x C-q}.  You'll be asked to
  confirm, when you lock the old version, that you really mean to create a
  new branch---if you say no, you'll be offered a chance to lock the
  latest version instead.
  
!   Then make your changes and type @kbd{C-x C-q} again to check in a new
  version.  This automatically creates a new branch starting from the
  selected version.  You need not specially request a new branch, because
  that's the only way to add a new version at a point that is not the head
--- 1843,1854 ----
  
    To create a new branch at an older version (one that is no longer the
  head of a branch), first select that version (@pxref{Switching
! Branches}), then lock it with @kbd{C-x v v}.  You'll be asked to
  confirm, when you lock the old version, that you really mean to create a
  new branch---if you say no, you'll be offered a chance to lock the
  latest version instead.
  
!   Then make your changes and type @kbd{C-x v v} again to check in a new
  version.  This automatically creates a new branch starting from the
  selected version.  You need not specially request a new branch, because
  that's the only way to add a new version at a point that is not the head
***************
*** 1858,1864 ****
    After the branch is created, you ``stay'' on it.  That means that
  subsequent check-ins create new versions on that branch.  To leave the
  branch, you must explicitly select a different version with @kbd{C-u C-x
! C-q}.  To transfer changes from one branch to another, use the merge
  command, described in the next section.
  
  @node Merging
--- 1857,1863 ----
    After the branch is created, you ``stay'' on it.  That means that
  subsequent check-ins create new versions on that branch.  To leave the
  branch, you must explicitly select a different version with @kbd{C-u C-x
! v v}.  To transfer changes from one branch to another, use the merge
  command, described in the next section.
  
  @node Merging
***************
*** 1895,1903 ****
    As an example, suppose that you have finished a certain feature on
  branch 1.3.1.  In the meantime, development on the trunk has proceeded
  to version 1.5.  To merge the changes from the branch to the trunk,
! first go to the head version of the trunk, by typing @kbd{C-u C-x C-q
  @key{RET}}.  Version 1.5 is now current.  If locking is used for the file,
! type @kbd{C-x C-q} to lock version 1.5 so that you can change it.  Next,
  type @kbd{C-x v m 1.3.1 @key{RET}}.  This takes the entire set of changes on
  branch 1.3.1 (relative to version 1.3, where the branch started, up to
  the last version on the branch) and merges it into the current version
--- 1894,1902 ----
    As an example, suppose that you have finished a certain feature on
  branch 1.3.1.  In the meantime, development on the trunk has proceeded
  to version 1.5.  To merge the changes from the branch to the trunk,
! first go to the head version of the trunk, by typing @kbd{C-u C-x v v
  @key{RET}}.  Version 1.5 is now current.  If locking is used for the file,
! type @kbd{C-x v v} to lock version 1.5 so that you can change it.  Next,
  type @kbd{C-x v m 1.3.1 @key{RET}}.  This takes the entire set of changes on
  branch 1.3.1 (relative to version 1.3, where the branch started, up to
  the last version on the branch) and merges it into the current version
***************
*** 1961,1967 ****
  
    If the files do not have version headers, you must instead tell Emacs
  explicitly in each session which branch you are working on.  To do this,
! first find the file, then type @kbd{C-u C-x C-q} and specify the correct
  branch number.  This ensures that Emacs knows which branch it is using
  during this particular editing session.
  
--- 1960,1966 ----
  
    If the files do not have version headers, you must instead tell Emacs
  explicitly in each session which branch you are working on.  To do this,
! first find the file, then type @kbd{C-u C-x v v} and specify the correct
  branch number.  This ensures that Emacs knows which branch it is using
  during this particular editing session.
  
***************
*** 2519,2525 ****
  @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 C-q} deletes the work file; but any
  attempt to visit the file with Emacs creates it again.  (With CVS, work
  files are always kept.)
  
--- 2518,2524 ----
  @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.)
  
***************
*** 2539,2545 ****
  asks you each time whether to follow the link.
  
  @vindex vc-suppress-confirm
!   If @code{vc-suppress-confirm} is address@hidden, then @kbd{C-x C-q}
  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
--- 2538,2544 ----
  asks you each time whether to follow the link.
  
  @vindex vc-suppress-confirm
!   If @code{vc-suppress-confirm} is address@hidden, 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
***************
*** 2615,2621 ****
    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 C-q} 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
--- 2614,2620 ----
    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
***************
*** 2626,2632 ****
  @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 C-q} 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
--- 2625,2631 ----
  @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