X-Git-Url: https://git.hcoop.net/bpt/emacs.git/blobdiff_plain/d273439c6a02f669a8d9830723e7e49818985065..e0070075ff06ab67bb2b348e0f265937d6dad48b:/doc/emacs/maintaining.texi diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index 984c65fbf2..a2401e9a59 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -1,14 +1,15 @@ @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, Abbrevs, Building, Top +@node Maintaining @chapter Maintaining Large Programs This chapter describes Emacs features for maintaining large -programs. In addition to the features described here, you may find -the @file{ERT} (``Emacs Lisp Regression Testing'') library useful in -this context (@pxref{Top,,ERT,ert, Emacs Lisp Regression Testing}). +programs. If you are maintaining a large Lisp program, then in +addition to the features described here, you may find +the @file{ERT} (``Emacs Lisp Regression Testing'') library useful +(@pxref{Top,,ERT,ert, Emacs Lisp Regression Testing}). @menu * Version Control:: Using version control systems. @@ -30,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. - 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, @@ -72,8 +73,8 @@ provides a uniform interface for common operations in many version 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 @@ -127,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 -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 -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. @@ -425,7 +426,7 @@ VC fileset is handled individually; for example, a commit generates one revision for each changed file. @table @kbd -@itemx C-x v v +@item C-x v v Perform the next appropriate version control operation on the current VC fileset. @end table @@ -454,7 +455,7 @@ and don't persist across sessions. @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 @@ -466,7 +467,7 @@ files and ``modified'' files; @pxref{Registering}.) @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. @@ -476,7 +477,7 @@ If every work file in the VC fileset is unchanged, do nothing. @item If every work file in the VC fileset has been modified, commit the -changes. To do this, Emacs pops up a @samp{*vc-log*} buffer; type the +changes. To do this, Emacs pops up a @file{*vc-log*} buffer; type the desired log entry for the new revision, followed by @kbd{C-c C-c} to commit. @xref{Log Buffer}. @@ -529,7 +530,7 @@ so that you can begin to edit it. @item If each file is locked by you and contains changes, commit the -changes. To do this, Emacs pops up a @samp{*vc-log*} buffer; type the +changes. To do this, Emacs pops up a @file{*vc-log*} buffer; type the desired log entry for the new revision, followed by @kbd{C-c C-c} to commit (@pxref{Log Buffer}). @@ -567,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 -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 -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. @@ -587,7 +588,7 @@ they use the concept of ``checking out'' individual files. @cindex C-c C-c @r{(Log Edit mode)} @findex log-edit-done When you tell VC to commit a change, it pops up a buffer named -@samp{*vc-log*}. In this buffer, you should write a @dfn{log entry} +@file{*vc-log*}. In this buffer, you should write a @dfn{log entry} describing the changes you have made (@pxref{Why Version Control?}). After you are done, type @kbd{C-c C-c} (@code{log-edit-done}) to exit the buffer and commit the change, together with your log entry. @@ -595,12 +596,12 @@ the buffer and commit the change, together with your log entry. @cindex Log Edit mode @cindex mode, Log Edit @vindex vc-log-mode-hook - The major mode for the @samp{*vc-log*} buffer is Log Edit mode, a + The major mode for the @file{*vc-log*} buffer is Log Edit mode, a variant of Text mode (@pxref{Text Mode}). On entering Log Edit mode, Emacs runs the hooks @code{text-mode-hook} and @code{vc-log-mode-hook} (@pxref{Hooks}). - In the @samp{*vc-log*} buffer, you can write one or more @dfn{header + In the @file{*vc-log*} buffer, you can write one or more @dfn{header lines}, specifying additional information to be supplied to the version control system. Each header line must occupy a single line at the top of the buffer; the first line that is not a header line is @@ -625,7 +626,7 @@ support it, the header is treated as part of the log entry. @findex log-edit-show-files @kindex C-c C-d @r{(Log Edit mode)} @findex log-edit-show-diff - While in the @samp{*vc-log*} buffer, the ``current VC fileset'' is + While in the @file{*vc-log*} buffer, the ``current VC fileset'' is considered to be the fileset that will be committed if you type @w{@kbd{C-c C-c}}. To view a list of the files in the VC fileset, type @w{@kbd{C-c C-f}} (@code{log-edit-show-files}). To view a diff @@ -638,7 +639,7 @@ started editing (@pxref{Old Revisions}), type @kbd{C-c C-d} If the VC fileset includes one or more @file{ChangeLog} files (@pxref{Change Log}), type @kbd{C-c C-a} (@code{log-edit-insert-changelog}) to pull the relevant entries into -the @samp{*vc-log*} buffer. If the topmost item in each +the @file{*vc-log*} buffer. If the topmost item in each @file{ChangeLog} was made under your user name on the current date, this command searches that item for entries matching the file(s) to be committed, and inserts them. @@ -651,7 +652,7 @@ Edit buffer. To abort a commit, just @strong{don't} type @kbd{C-c C-c} in that buffer. You can switch buffers and do other editing. As long as you don't try to make another commit, the entry you were editing remains -in the @samp{*vc-log*} buffer, and you can go back to that buffer at +in the @file{*vc-log*} buffer, and you can go back to that buffer at any time to complete the commit. @kindex M-n @r{(Log Edit mode)} @@ -710,7 +711,7 @@ commit can include both file additions and edits to existing files. On a locking-based version control system (@pxref{VCS Merging}), registering a file leaves it unlocked and read-only. Type @kbd{C-x v -v} if you wish to start editing it. +v} to start editing it. @node Old Revisions @subsection Examining And Comparing Old Revisions @@ -724,7 +725,7 @@ call this command from a Dired buffer (@pxref{Dired}). @ifnottex @item M-x vc-ediff -Like @kbd{C-x v =}, but using Ediff. @xref{Top, Ediff, ediff, The +Like @kbd{C-x v =}, but using Ediff. @xref{Top,, Ediff, ediff, The Ediff Manual}. @end ifnottex @@ -758,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 -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. @@ -776,13 +777,13 @@ current VC fileset. @ifnottex @findex vc-ediff @kbd{M-x vc-ediff} works like @kbd{C-x v =}, except that it uses an -Ediff session. @xref{Top, Ediff, ediff, The Ediff Manual}. +Ediff session. @xref{Top,, Ediff, ediff, The Ediff Manual}. @end ifnottex @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. @@ -794,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, -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}, @@ -834,12 +835,12 @@ view diffs, or view log entries: @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 -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 @@ -892,7 +893,7 @@ Display the change history for the current repository (@code{vc-print-root-log}). @item C-x v I -Display the changes that will be received with a pull operation +Display the changes that a pull operation will retrieve (@code{vc-log-incoming}). @item C-x v O @@ -902,11 +903,11 @@ Display the changes that will be sent by the next push operation @kindex C-x v l @findex vc-print-log - The command @kbd{C-x v l} (@code{vc-print-log}) displays a buffer -named @samp{*vc-change-log*}, showing the history of changes made to -the current file, including who made the changes, the dates, and the -log entry for each change (these are the same log entries you would -enter via the @samp{*vc-log*} buffer; @pxref{Log Buffer}). Point is + @kbd{C-x v l} (@code{vc-print-log}) displays a buffer named +@file{*vc-change-log*}, showing the history of changes made to the +current file, including who made the changes, the dates, and the log +entry for each change (these are the same log entries you would enter +via the @file{*vc-log*} buffer; @pxref{Log Buffer}). Point is centered at the revision of the file currently being visited. With a prefix argument, the command prompts for the revision to center on, and the maximum number of revisions to display. @@ -918,7 +919,7 @@ file listed on the current line. @findex vc-print-root-log @findex log-view-toggle-entry-display @kbd{C-x v L} (@code{vc-print-root-log}) displays a -@samp{*vc-change-log*} buffer showing the history of the entire +@file{*vc-change-log*} buffer showing the history of the entire version-controlled directory tree (RCS, SCCS, and CVS do not support this feature). With a prefix argument, the command prompts for the maximum number of revisions to display. @@ -926,7 +927,7 @@ maximum number of revisions to display. The @kbd{C-x v L} history is shown in a compact form, usually showing only the first line of each log entry. However, you can type @key{RET} (@code{log-view-toggle-entry-display}) in the -@samp{*vc-change-log*} buffer to reveal the entire log entry for the +@file{*vc-change-log*} buffer to reveal the entire log entry for the revision at point. A second @key{RET} hides it again. On a decentralized version control system, the @kbd{C-x v I} @@ -941,7 +942,7 @@ specific repository. Similarly, @kbd{C-x v O} another repository, the next time you run the ``push'' command; with a prefix argument, it prompts for a specific destination repository. - In the @samp{*vc-change-log*} buffer, you can use the following keys + In the @file{*vc-change-log*} buffer, you can use the following keys to move between the logs of revisions and of files, and to examine and compare past revisions (@pxref{Old Revisions}): @@ -985,18 +986,18 @@ earlier revision. This shows the changes to all files made in that 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 @vindex vc-log-show-limit Because fetching many log entries can be slow, the -@samp{*vc-change-log*} buffer displays no more than 2000 revisions by +@file{*vc-change-log*} buffer displays no more than 2000 revisions by default. The variable @code{vc-log-show-limit} specifies this limit; if you set the value to zero, that removes the limit. You can also increase the number of revisions shown in an existing -@samp{*vc-change-log*} buffer by clicking on the @samp{Show 2X +@file{*vc-change-log*} buffer by clicking on the @samp{Show 2X entries} or @samp{Show unlimited entries} buttons at the end of the buffer. However, RCS, SCCS, and CVS do not support this feature. @@ -1044,7 +1045,7 @@ it is used to specify multi-file VC filesets for commands like To use the VC Directory buffer, type @kbd{C-x v d} (@code{vc-dir}). This reads a directory name using the minibuffer, and switches to a VC Directory buffer for that directory. By default, the buffer is named -@samp{*vc-dir*}. Its contents are described +@file{*vc-dir*}. Its contents are described @iftex below. @end iftex @@ -1063,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 -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 @@ -1079,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 -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. @@ -1130,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 -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 @@ -1185,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. -@kindex q @r{(VC Directory)} -@findex quit-window @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 @@ -1204,9 +1202,6 @@ files and directories. @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 @@ -1312,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 -(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. @@ -1325,7 +1320,7 @@ commit will be committed to that specific branch. @subsubsection Pulling Changes into a Branch @table @kbd -@itemx C-x v + +@item C-x v + On a decentralized version control system, update the current branch by ``pulling in'' changes from another location. @@ -1365,7 +1360,7 @@ updates the current VC fileset from the repository. @cindex merging changes @table @kbd -@itemx C-x v m +@item C-x v m On a decentralized version control system, merge changes from another branch into the current one. @@ -1594,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 -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 @@ -1658,7 +1653,7 @@ Tags for variables and functions in classes are named @samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}. @item -In La@TeX{} documents, the arguments for @code{\chapter}, +In @LaTeX{} documents, the arguments for @code{\chapter}, @code{\section}, @code{\subsection}, @code{\subsubsection}, @code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry}, @@ -1701,9 +1696,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 -(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: @@ -1728,7 +1723,7 @@ find-tag @key{RET} bidule @key{RET}} will just search for any tag @code{bidule}. @item -In assembler code, labels appearing at the beginning of a line, +In assembler code, labels appearing at the start of a line, followed by a colon, are tags. @item @@ -2226,7 +2221,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 -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 @@ -2346,7 +2341,7 @@ directory trees. The @dfn{project root} is the topmost directory of a project. To define a new project, visit a file in the desired project root and type @kbd{M-x ede-new}. This command prompts for a @dfn{project type}, which refers to the underlying method that EDE -will use to manage the project (@pxref{Creating a Project, EDE,, ede, +will use to manage the project (@pxref{Creating a project, EDE,, ede, Emacs Development Environment}). The most common project types are @samp{Make}, which uses Makefiles, and @samp{Automake}, which uses GNU Automake (@pxref{Top, Automake,, automake, Automake}). In both cases,