Merge from emacs-24; up to 2012-12-26T16:22:18Z!michael.albinus@gmx.de

[gnu-emacs] / doc / emacs / maintaining.texi

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index c719c483ec825386ddd0ab108b9fcbb5630dfff6..c8d9e9f208798375f3658e47cc712d66e4cdd63e 100644 (file)
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -1,6 +1,6 @@
 @c This is part of the Emacs manual.
 @c This is part of the Emacs manual.

-@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2012
-@c   Free Software Foundation, Inc.
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2013 Free Software
+@c Foundation, Inc.

 @c See file emacs.texi for copying conditions.
 @node Maintaining
 @chapter Maintaining Large Programs
 @c See file emacs.texi for copying conditions.
 @node Maintaining
 @chapter Maintaining Large Programs


@@ -31,7 +31,7 @@ versions of a source file, storing information such as the creation
 time of each version, who made it, and a description of what was
 changed.
 
 time of each version, who made it, and a description of what was
 changed.
 

-  The Emacs version control interface is called @dfn{VC}.  VC commands
+  The Emacs version control interface is called @dfn{VC}@.  VC commands

 work with several different version control systems; currently, it
 supports GNU Arch, Bazaar, CVS, Git, Mercurial, Monotone, RCS,
 SCCS/CSSC, and Subversion.  Of these, the GNU project distributes CVS,
 work with several different version control systems; currently, it
 supports GNU Arch, Bazaar, CVS, Git, Mercurial, Monotone, RCS,
 SCCS/CSSC, and Subversion.  Of these, the GNU project distributes CVS,


@@ -73,8 +73,8 @@ provides a uniform interface for common operations in many version
 control operations.
 
   Some uncommon or intricate version control operations, such as
 control operations.
 
   Some uncommon or intricate version control operations, such as

-altering repository settings, are not supported in VC.  You should
-perform such tasks outside Emacs, e.g.@: via the command line.
+altering repository settings, are not supported in VC@.  You should
+perform such tasks outside Emacs, e.g., via the command line.

 
   This section provides a general overview of version control, and
 describes the version control systems that VC supports.  You can skip
 
   This section provides a general overview of version control, and
 describes the version control systems that VC supports.  You can skip


@@ -128,13 +128,13 @@ which it refers to as @dfn{back ends}:
 @item
 SCCS was the first version control system ever built, and was long ago
 superseded by more advanced ones.  VC compensates for certain features
 @item
 SCCS was the first version control system ever built, and was long ago
 superseded by more advanced ones.  VC compensates for certain features

-missing in SCCS (e.g.@: tag names for releases) by implementing them
+missing in SCCS (e.g., tag names for releases) by implementing them

 itself.  Other VC features, such as multiple branches, are simply
 unavailable.  Since SCCS is non-free, we recommend avoiding it.
 
 @cindex CSSC
 @item
 itself.  Other VC features, such as multiple branches, are simply
 unavailable.  Since SCCS is non-free, we recommend avoiding it.
 
 @cindex CSSC
 @item

-CSSC is a free replacement for SCCS.  You should use CSSC only if, for
+CSSC is a free replacement for SCCS@.  You should use CSSC only if, for

 some reason, you cannot use a more recent and better-designed version
 control system.
 
 some reason, you cannot use a more recent and better-designed version
 control system.
 


@@ -455,7 +455,7 @@ and don't persist across sessions.
 @node VC With A Merging VCS
 @subsubsection Basic Version Control with Merging
 
 @node VC With A Merging VCS
 @subsubsection Basic Version Control with Merging
 

-  On a merging-based version control system (i.e.@: most modern ones;
+  On a merging-based version control system (i.e., most modern ones;

 @pxref{VCS Merging}), @kbd{C-x v v} does the following:
 
 @itemize @bullet
 @pxref{VCS Merging}), @kbd{C-x v v} does the following:
 
 @itemize @bullet


@@ -467,7 +467,7 @@ files and ``modified'' files; @pxref{Registering}.)
 
 @item
 If none of the files in the VC fileset are registered with a version
 
 @item
 If none of the files in the VC fileset are registered with a version

-control system, register the VC fileset, i.e.@: place it under version
+control system, register the VC fileset, i.e., place it under version

 control.  @xref{Registering}.  If Emacs cannot find a system to
 register under, it prompts for a repository type, creates a new
 repository, and registers the VC fileset with it.
 control.  @xref{Registering}.  If Emacs cannot find a system to
 register under, it prompts for a repository type, creates a new
 repository, and registers the VC fileset with it.


@@ -568,13 +568,13 @@ and Emacs fails to detect the correct one.
 Otherwise, if using CVS or RCS, you can specify a revision ID.
 
 If the fileset is modified (or locked), this makes Emacs commit with
 Otherwise, if using CVS or RCS, you can specify a revision ID.
 
 If the fileset is modified (or locked), this makes Emacs commit with

-that revision ID.  You can create a new branch by supplying an
+that revision ID@.  You can create a new branch by supplying an

 appropriate revision ID (@pxref{Branches}).
 
 If the fileset is unmodified (and unlocked), this checks the specified
 revision into the working tree.  You can also specify a revision on
 another branch by giving its revision or branch ID (@pxref{Switching
 appropriate revision ID (@pxref{Branches}).
 
 If the fileset is unmodified (and unlocked), this checks the specified
 revision into the working tree.  You can also specify a revision on
 another branch by giving its revision or branch ID (@pxref{Switching

-Branches}).  An empty argument (i.e.@: @kbd{C-u C-x v v @key{RET}})
+Branches}).  An empty argument (i.e., @kbd{C-u C-x v v @key{RET}})

 checks out the latest (``head'') revision on the current branch.
 
 This signals an error on a decentralized version control system.
 checks out the latest (``head'') revision on the current branch.
 
 This signals an error on a decentralized version control system.


@@ -759,7 +759,7 @@ comparison again, generating a new diff.
 prompts for two revision IDs (@pxref{VCS Concepts}), and displays a
 diff between those versions of the fileset.  This will not work
 reliably for multi-file VC filesets, if the version control system is
 prompts for two revision IDs (@pxref{VCS Concepts}), and displays a
 diff between those versions of the fileset.  This will not work
 reliably for multi-file VC filesets, if the version control system is

-file-based rather than changeset-based (e.g.@: CVS), since then
+file-based rather than changeset-based (e.g., CVS), since then

 revision IDs for different files would not be related in any
 meaningful way.
 
 revision IDs for different files would not be related in any
 meaningful way.
 


@@ -783,7 +783,7 @@ Ediff session.  @xref{Top,, Ediff, ediff, The Ediff Manual}.
 @findex vc-root-diff
 @kindex C-x v D
   @kbd{C-x v D} (@code{vc-root-diff}) is similar to @kbd{C-x v =}, but
 @findex vc-root-diff
 @kindex C-x v D
   @kbd{C-x v D} (@code{vc-root-diff}) is similar to @kbd{C-x v =}, but

-it displays the changes in the entire current working tree (i.e.@: the
+it displays the changes in the entire current working tree (i.e., the

 working tree containing the current VC fileset).  If you invoke this
 command from a Dired buffer, it applies to the working tree containing
 the directory.
 working tree containing the current VC fileset).  If you invoke this
 command from a Dired buffer, it applies to the working tree containing
 the directory.


@@ -795,7 +795,7 @@ from the first non-@code{nil} value amongst the variables
 @code{vc-@var{backend}-diff-switches}, @code{vc-diff-switches}, and
 @code{diff-switches} (@pxref{Comparing Files}), in that order.  Here,
 @var{backend} stands for the relevant version control system,
 @code{vc-@var{backend}-diff-switches}, @code{vc-diff-switches}, and
 @code{diff-switches} (@pxref{Comparing Files}), in that order.  Here,
 @var{backend} stands for the relevant version control system,

-e.g.@: @code{bzr} for Bazaar.  Since @code{nil} means to check the
+e.g., @code{bzr} for Bazaar.  Since @code{nil} means to check the

 next variable in the sequence, either of the first two may use the
 value @code{t} to mean no switches at all.  Most of the
 @code{vc-@var{backend}-diff-switches} variables default to @code{nil},
 next variable in the sequence, either of the first two may use the
 value @code{t} to mean no switches at all.  Most of the
 @code{vc-@var{backend}-diff-switches} variables default to @code{nil},


@@ -835,12 +835,12 @@ view diffs, or view log entries:
 
 @table @kbd
 @item p
 
 @table @kbd
 @item p

-Annotate the previous revision, i.e.@: the revision before the one
+Annotate the previous revision, i.e., the revision before the one

 currently annotated.  A numeric prefix argument is a repeat count, so
 @kbd{C-u 10 p} would take you back 10 revisions.
 
 @item n
 currently annotated.  A numeric prefix argument is a repeat count, so
 @kbd{C-u 10 p} would take you back 10 revisions.
 
 @item n

-Annotate the next revision, i.e.@: the revision after the one
+Annotate the next revision, i.e., the revision after the one

 currently annotated.  A numeric prefix argument is a repeat count.
 
 @item j
 currently annotated.  A numeric prefix argument is a repeat count.
 
 @item j


@@ -986,7 +986,7 @@ earlier revision.  This shows the changes to all files made in that
 revision.
 
 @item @key{RET}
 revision.
 
 @item @key{RET}

-In a compact-style log buffer (e.g.@: the one created by @kbd{C-x v
+In a compact-style log buffer (e.g., the one created by @kbd{C-x v

 L}), toggle between showing and hiding the full log entry for the
 revision at point.
 @end table
 L}), toggle between showing and hiding the full log entry for the
 revision at point.
 @end table


@@ -1064,8 +1064,8 @@ the version control system which the VC Directory buffer should use.
 @pindex cvs
 @cindex CVS directory mode
   In addition to the VC Directory buffer, Emacs has a similar facility
 @pindex cvs
 @cindex CVS directory mode
   In addition to the VC Directory buffer, Emacs has a similar facility

-called PCL-CVS which is specialized for CVS.  @xref{Top, , About
-PCL-CVS, pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}.
+called PCL-CVS which is specialized for CVS@.  @xref{Top, , About
+PCL-CVS, pcl-cvs, PCL-CVS---The Emacs Front-End to CVS}.

 @end ifnottex
 
 @menu
 @end ifnottex
 
 @menu


@@ -1080,7 +1080,7 @@ PCL-CVS, pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}.
 and their version control statuses.  It lists files in the current
 directory (the one specified when you called @kbd{C-x v d}) and its
 subdirectories, but only those with a ``noteworthy'' status.  Files
 and their version control statuses.  It lists files in the current
 directory (the one specified when you called @kbd{C-x v d}) and its
 subdirectories, but only those with a ``noteworthy'' status.  Files

-that are up-to-date (i.e.@: the same as in the repository) are
+that are up-to-date (i.e., the same as in the repository) are

 omitted.  If all the files in a subdirectory are up-to-date, the
 subdirectory is not listed either.  As an exception, if a file has
 become up-to-date as a direct result of a VC command, it is listed.
 omitted.  If all the files in a subdirectory are up-to-date, the
 subdirectory is not listed either.  As an exception, if a file has
 become up-to-date as a direct result of a VC command, it is listed.


@@ -1131,7 +1131,7 @@ updates.  If you change the variable @code{vc-stay-local} or
 @code{vc-cvs-stay-local} (for CVS) to @code{nil} (@pxref{CVS
 Options}), then Emacs avoids contacting a remote repository when
 generating the VC Directory buffer (it will still contact it when
 @code{vc-cvs-stay-local} (for CVS) to @code{nil} (@pxref{CVS
 Options}), then Emacs avoids contacting a remote repository when
 generating the VC Directory buffer (it will still contact it when

-necessary, e.g.@: when doing a commit).  This may be desirable if you
+necessary, e.g., when doing a commit).  This may be desirable if you

 are working offline or the network is slow.
 @end ifnottex
 
 are working offline or the network is slow.
 @end ifnottex
 


@@ -1186,11 +1186,8 @@ point is on a directory entry, mark all files in that directory tree
 (@code{vc-dir-mark-all-files}).  With a prefix argument, mark all
 listed files and directories.
 
 (@code{vc-dir-mark-all-files}).  With a prefix argument, mark all
 listed files and directories.
 

-@kindex q @r{(VC Directory)}
-@findex quit-window

 @item q
 @item q

-Bury the VC Directory buffer, and delete its window if the window was
-created just for that buffer.
+Quit the VC Directory buffer, and bury it (@code{quit-window}).

 
 @item u
 Unmark the file or directory on the current line.  If the region is
 
 @item u
 Unmark the file or directory on the current line.  If the region is


@@ -1205,9 +1202,6 @@ files and directories.
 @item x
 Hide files with @samp{up-to-date} status
 (@code{vc-dir-hide-up-to-date}).
 @item x
 Hide files with @samp{up-to-date} status
 (@code{vc-dir-hide-up-to-date}).

-
-@item q
-Quit the VC Directory buffer, and bury it (@code{quit-window}).

 @end table
 
 @findex vc-dir-mark
 @end table
 
 @findex vc-dir-mark


@@ -1313,7 +1307,7 @@ revision 1.2 has revision IDs 1.2.1.1, 1.2.1.2, @dots{}, the second
 branch created from revision 1.2 has revision IDs 1.2.2.1, 1.2.2.2,
 @dots{}, and so forth.  You can also specify the @dfn{branch ID},
 which is a branch revision ID omitting its final component
 branch created from revision 1.2 has revision IDs 1.2.2.1, 1.2.2.2,
 @dots{}, and so forth.  You can also specify the @dfn{branch ID},
 which is a branch revision ID omitting its final component

-(e.g.@: 1.2.1), to switch to the latest revision on that branch.
+(e.g., 1.2.1), to switch to the latest revision on that branch.

 
   On a locking-based system, switching to a different branch also
 unlocks (write-protects) the working tree.
 
   On a locking-based system, switching to a different branch also
 unlocks (write-protects) the working tree.


@@ -1595,7 +1589,7 @@ source files.
   To produce a tags table, you run the @command{etags} shell command
 on a document or the source code file.  The @samp{etags} program
 writes the tags to a @dfn{tags table file}, or @dfn{tags file} in
   To produce a tags table, you run the @command{etags} shell command
 on a document or the source code file.  The @samp{etags} program
 writes the tags to a @dfn{tags table file}, or @dfn{tags file} in

-short.  The conventional name for a tags file is @file{TAGS}.
+short.  The conventional name for a tags file is @file{TAGS}@.

 @xref{Create Tags Table}.
 
   Emacs provides many commands for searching and replacing using the
 @xref{Create Tags Table}.
 
   Emacs provides many commands for searching and replacing using the


@@ -1682,9 +1676,11 @@ specifies (using Bourne shell syntax) that the commands
 
 @item
 In Lisp code, any function defined with @code{defun}, any variable
 
 @item
 In Lisp code, any function defined with @code{defun}, any variable

-defined with @code{defvar} or @code{defconst}, and in general the first
-argument of any expression that starts with @samp{(def} in column zero is
-a tag.
+defined with @code{defvar} or @code{defconst}, and in general the
+first argument of any expression that starts with @samp{(def} in
+column zero is a tag.  As an exception, expressions of the form
+@code{(defvar @var{foo})} are treated as declarations, and are only
+tagged if the @samp{--declarations} option is given.

 
 @item
 In Scheme code, tags include anything defined with @code{def} or with a
 
 @item
 In Scheme code, tags include anything defined with @code{def} or with a


@@ -1702,9 +1698,9 @@ tags.  Use the @samp{--packages-only} option to create tags for
 packages only.
 
 In Ada, the same name can be used for different kinds of entity
 packages only.
 
 In Ada, the same name can be used for different kinds of entity

-(e.g.@:, for a procedure and for a function).  Also, for things like
-packages, procedures and functions, there is the spec (i.e.@: the
-interface) and the body (i.e.@: the implementation).  To make it
+(e.g., for a procedure and for a function).  Also, for things like
+packages, procedures and functions, there is the spec (i.e., the
+interface) and the body (i.e., the implementation).  To make it

 easier to pick the definition you want, Ada tag name have suffixes
 indicating the type of entity:
 
 easier to pick the definition you want, Ada tag name have suffixes
 indicating the type of entity:
 


@@ -1772,11 +1768,11 @@ the file.
 
 @item
 In Perl code, the tags are the packages, subroutines and variables
 
 @item
 In Perl code, the tags are the packages, subroutines and variables

-defined by the @code{package}, @code{sub}, @code{my} and @code{local}
-keywords.  Use @samp{--globals} if you want to tag global variables.
-Tags for subroutines are named @samp{@var{package}::@var{sub}}.  The
-name for subroutines defined in the default package is
-@samp{main::@var{sub}}.
+defined by the @code{package}, @code{sub}, @code{use constant},
+@code{my}, and @code{local} keywords.  Use @samp{--globals} if you
+want to tag global variables.  Tags for subroutines are named
+@samp{@var{package}::@var{sub}}.  The name for subroutines defined in
+the default package is @samp{main::@var{sub}}.

 
 @item
 In PHP code, tags are functions, classes and defines.  Vars are tags
 
 @item
 In PHP code, tags are functions, classes and defines.  Vars are tags


@@ -2227,7 +2223,7 @@ the current buffer, followed by the remaining files of the tags table.
 reads a regexp to search for and a string to replace with, just like
 ordinary @kbd{M-x query-replace-regexp}.  It searches much like @kbd{M-x
 tags-search}, but repeatedly, processing matches according to your
 reads a regexp to search for and a string to replace with, just like
 ordinary @kbd{M-x query-replace-regexp}.  It searches much like @kbd{M-x
 tags-search}, but repeatedly, processing matches according to your

-input.  @xref{Replace}, for more information on query replace.
+input.  @xref{Query Replace}, for more information on query replace.

 
 @vindex tags-case-fold-search
 @cindex case-sensitivity and tags search
 
 @vindex tags-case-fold-search
 @cindex case-sensitivity and tags search