From 2785d02431f6f90b5013e490f9ad5c21dd51f6de Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Thu, 22 Dec 2011 18:14:41 +0800 Subject: [PATCH] More updates for VC documentation. * doc/emacs/vc1-xtra.texi (Version Headers): Note that these are for Subversion, CVS, etc. only. (General VC Options): De-document vc-keep-workfiles. Fix RCS-isms. * doc/emacs/maintaining.texi (Change Log Commands): Don't specially mention vc-update-change-log which is CVS-only. --- doc/emacs/ChangeLog | 10 +++ doc/emacs/building.texi | 2 +- doc/emacs/maintaining.texi | 24 ++---- doc/emacs/vc1-xtra.texi | 167 +++++++++++-------------------------- 4 files changed, 65 insertions(+), 138 deletions(-) diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index 6cf181199c5..0621fa4e003 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,3 +1,13 @@ +2011-12-22 Chong Yidong + + * maintaining.texi (Change Log Commands): Don't specially mention + vc-update-change-log which is CVS-only. + + * vc1-xtra.texi (Version Headers): Note that these are for + Subversion, CVS, etc. only. + (General VC Options): De-document vc-keep-workfiles. Fix + RCS-isms. + 2011-12-22 Eli Zaretskii * building.texi (Debugger Operation): Fix a typo: "@end iftext" diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi index 880335830bd..963bd510f67 100644 --- a/doc/emacs/building.texi +++ b/doc/emacs/building.texi @@ -565,7 +565,7 @@ Mode}). Completion is available for most debugger commands commands to repeat them. @iftex See the next section -@end iftext +@end iftex @ifnottex @xref{Commands of GUD}, @end ifnottex diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index 488bdf87320..68a34ca3a77 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -1438,13 +1438,11 @@ different revision with @kbd{C-u C-x v v}. @section Change Logs @cindex change log - A change log file contains a chronological record of when and why you -have changed a program, consisting of a sequence of entries describing -individual changes. Normally it is kept in a file called -@file{ChangeLog} in the same directory as the file you are editing, or -one of its parent directories. A single @file{ChangeLog} file can -record changes for all the files in its directory and all its -subdirectories. + Many software projects keep a @dfn{change log}. This is a file, +normally named @file{ChangeLog}, containing a chronological record of +when and how the program was changed. Sometimes, there are several +change log files, each recording the changes in one directory or +directory tree. @menu * Change Log Commands:: Commands for editing change log files. @@ -1476,7 +1474,7 @@ rather than starting a new item. You can combine multiple changes of the same nature. If you don't enter any text after the initial @kbd{C-x 4 a}, any subsequent -@kbd{C-x 4 a} adds another symbol to the change. +@kbd{C-x 4 a} adds another symbol to the change log entry. @vindex add-log-always-start-new-record If @code{add-log-always-start-new-record} is non-@code{nil}, @@ -1514,15 +1512,7 @@ ordering of entries. Version control systems are another way to keep track of changes in your program and keep a change log. In the VC log buffer, typing @kbd{C-c C-a} (@code{log-edit-insert-changelog}) inserts the relevant -Change Log entry, if one exists (@pxref{Log Buffer}). You can also -insert a VC log entry into a Change Log buffer by typing @kbd{C-x v a} -(@code{vc-update-change-log}) in the Change Log buffer -@iftex -(@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Change Logs and VC}). -@end ifnottex +Change Log entry, if one exists. @xref{Log Buffer}. @node Format of ChangeLog @subsection Format of ChangeLog diff --git a/doc/emacs/vc1-xtra.texi b/doc/emacs/vc1-xtra.texi index 700003db58a..8df5bfbd551 100644 --- a/doc/emacs/vc1-xtra.texi +++ b/doc/emacs/vc1-xtra.texi @@ -204,123 +204,63 @@ So the program won't really work as retrieved. @node Version Headers @subsubsection 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. - - 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. + On Subversion, CVS, RCS, and SCCS, you can put certain special +strings called @dfn{version headers} into a work file. When the file +is committed, the version control system automatically puts the +revision number, the name of the user who made the commit, and other +relevant information into the version header. + +@vindex vc-consult-headers + VC does not normally use the information in the version headers. As +an exception, when using RCS, Emacs uses the version header, if there +is one, to determine the file version, since it is often more reliable +than the RCS master file. To inhibit using the version header this +way, change the variable @code{vc-consult-headers} to @code{nil}. @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})}. + To insert a suitable header string into the current buffer, type +@kbd{C-x v h} (@code{vc-insert-headers}). This command works only on +Subversion, CVS, RCS, and SCCS. The variable +@code{vc-@var{backend}-header} contains the list of keywords to insert +into the version header; for instance, CVS uses @code{vc-cvs-header}, +whose default value is @code{'("\$Id\$")}. (The extra backslashes +prevent the string constant from being interpreted as a header, if the +Emacs Lisp file defining it is maintained with version control.) The +@kbd{C-x v h} command inserts each keyword in the list on a new line +at point, surrounded by tabs, and inside comment delimiters if +necessary. @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. +@var{regexp} matches the buffer name, @var{format} is also inserted as +part of the version header. A @samp{%s} in @var{format} is replaced +with the file's version control type. @node Customizing VC @subsection Customizing VC @vindex vc-handled-backends -The variable @code{vc-handled-backends} determines which version + The variable @code{vc-handled-backends} determines which version control systems VC should handle. The default value is @code{(RCS CVS SVN SCCS Bzr Git Hg Mtn Arch)}, so it contains all the 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}. +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, VC uses the system that comes + The order of systems in the list is significant: when you visit a +file registered in more than one system, 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, see +significant when you register a file for the first time @iftex -@ref{Registering,,,emacs, the Emacs Manual}, +(@pxref{Registering,,,emacs, the Emacs Manual}). @end iftex @ifnottex -@ref{Registering}, +(@pxref{Registering}). @end ifnottex -for details. @menu * General VC Options:: Options that apply to multiple back ends. @@ -337,40 +277,27 @@ 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. +@cindex symbolic links (and version control) + Editing a version-controlled file through a symbolic link may cause +unexpected results, if you are unaware that the underlying file is +version-controlled. The variable @code{vc-follow-symlinks} controls +what Emacs does if you try to visit a symbolic link pointing to a +version-controlled file. If the value is @code{ask} (the default), +Emacs asks for confirmation. If it is @code{nil}, Emacs just displays +a warning message. If it is @code{t}, Emacs automatically follows the +link and visits the real file instead. @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.) +@kbd{C-x v u} also operates without asking for confirmation. @vindex vc-command-messages VC mode does much of its work by running the shell commands for the -appropriate backend. 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. +appropriate version control system. 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 -- 2.39.2