From 2e589c00422e68624024c8a77799d54964e7b3a2 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Tue, 24 May 2016 21:24:45 +0300 Subject: [PATCH] Fix cross-references between manuals * doc/misc/viper.texi (Viper Specials): * doc/misc/url.texi (Tramp): * doc/misc/sem-user.texi (Smart Jump): * doc/lispintro/emacs-lisp-intro.texi (Finding More): * doc/misc/efaq.texi (Replacing text across multiple files): Fix cross-references between manuals. (Bug#23612) * doc/lispintro/emacs-lisp-intro.texi (etags): Node deleted: no longer relevant to Emacs Lisp programming. --- doc/lispintro/emacs-lisp-intro.texi | 189 +++------------------------- doc/misc/efaq.texi | 4 +- doc/misc/sem-user.texi | 6 +- doc/misc/url.texi | 4 +- doc/misc/viper.texi | 2 +- 5 files changed, 23 insertions(+), 182 deletions(-) diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index eea46af6b19..10162b35467 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -584,7 +584,6 @@ Regular Expression Searches * re-search-forward:: Very similar to @code{search-forward}. * forward-sentence:: A straightforward example of regexp search. * forward-paragraph:: A somewhat complex example. -* etags:: How to create your own @file{TAGS} table. * Regexp Review:: * re-search Exercises:: @@ -4583,54 +4582,21 @@ definition. @end ignore More generally, if you want to see a function in its original source -file, you can use the @code{find-tag} function to jump to it. -@code{find-tag} works with a wide variety of languages, not just -Lisp, and C, and it works with non-programming text as well. For -example, @code{find-tag} will jump to the various nodes in the -Texinfo source file of this document. -The @code{find-tag} function depends on @dfn{tags tables} that record -the locations of the functions, variables, and other items to which -@code{find-tag} jumps. - -To use the @code{find-tag} command, type @kbd{M-.} (i.e., press the -period key while holding down the @key{META} key, or else type the -@key{ESC} key and then type the period key), and then, at the prompt, -type in the name of the function whose source code you want to see, -such as @code{mark-whole-buffer}, and then type @key{RET}. Emacs will -switch buffers and display the source code for the function on your -screen. To switch back to your current buffer, type @kbd{C-x b -@key{RET}}. (On some keyboards, the @key{META} key is labeled -@key{ALT}.) - -@c !!! 22.1.1 tags table location in this paragraph -@cindex TAGS table, specifying -@findex find-tag -Depending on how the initial default values of your copy of Emacs are -set, you may also need to specify the location of your tags table, -which is a file called @file{TAGS}. For example, if you are -interested in Emacs sources, the tags table you will most likely want, -if it has already been created for you, will be in a subdirectory of -the @file{/usr/local/share/emacs/} directory; thus you would use the -@code{M-x visit-tags-table} command and specify a pathname such as -@file{/usr/local/share/emacs/22.1.1/lisp/TAGS}. If the tags table -has not already been created, you will have to create it yourself. It -will be in a file such as @file{/usr/local/src/emacs/src/TAGS}. - -@need 1250 -To create a @file{TAGS} file in a specific directory, switch to that -directory in Emacs using @kbd{M-x cd} command, or list the directory -with @kbd{C-x d} (@code{dired}). Then run the compile command, with -@w{@code{etags *.el}} as the command to execute: - -@smallexample -M-x compile RET etags *.el RET -@end smallexample - -For more information, see @ref{etags, , Create Your Own @file{TAGS} File}. - -After you become more familiar with Emacs Lisp, you will find that you will -frequently use @code{find-tag} to navigate your way around source code; -and you will create your own @file{TAGS} tables. +file, you can use the @code{xref-find-definitions} function to jump to +it. @code{xref-find-definitions} works with a wide variety of +languages, not just Lisp, and C, and it works with non-programming +text as well. For example, @code{xref-find-definitions} will jump to +the various nodes in the Texinfo source file of this document. + +To use the @code{xref-find-definitions} command, type @kbd{M-.} +(i.e., press the period key while holding down the @key{META} key, or +else type the @key{ESC} key and then type the period key), and then, +at the prompt, type in the name of the function whose source code you +want to see, such as @code{mark-whole-buffer}, and then type +@key{RET}. Emacs will switch buffers and display the source code for +the function on your screen. To switch back to your current buffer, +type @kbd{C-x b @key{RET}}. (On some keyboards, the @key{META} key is +labeled @key{ALT}.) @cindex Library, as term for ``file'' Incidentally, the files that contain Lisp code are conventionally @@ -12142,7 +12108,6 @@ introduces several new features. * re-search-forward:: Very similar to @code{search-forward}. * forward-sentence:: A straightforward example of regexp search. * forward-paragraph:: A somewhat complex example. -* etags:: How to create your own @file{TAGS} table. * Regexp Review:: * re-search Exercises:: @end menu @@ -13294,130 +13259,6 @@ key; you will be taken directly to the source. (Be sure to install your sources! Without them, you are like a person who tries to drive a car with his eyes shut!) -@node etags -@section Create Your Own @file{TAGS} File -@findex etags -@cindex @file{TAGS} file, create own - -Besides @kbd{C-h f} (@code{describe-function}), another way to see the -source of a function is to type @kbd{M-.} (@code{find-tag}) and the -name of the function when prompted for it. This is a good habit to -get into. The @kbd{M-.} (@code{find-tag}) command takes you directly -to the source for a function, variable, or node. The function depends -on tags tables to tell it where to go. - -If the @code{find-tag} function first asks you for the name of a -@file{TAGS} table, give it the name of a @file{TAGS} file such as -@file{/usr/local/src/emacs/src/TAGS}. (The exact path to your -@file{TAGS} file depends on how your copy of Emacs was installed. I -just told you the location that provides both my C and my Emacs Lisp -sources.) - -You can also create your own @file{TAGS} file for directories that -lack one. - -You often need to build and install tags tables yourself. They are -not built automatically. A tags table is called a @file{TAGS} file; -the name is in upper case letters. - -You can create a @file{TAGS} file by calling the @code{etags} program -that comes as a part of the Emacs distribution. Usually, @code{etags} -is compiled and installed when Emacs is built. (@code{etags} is not -an Emacs Lisp function or a part of Emacs; it is a C program.) - -@need 1250 -To create a @file{TAGS} file, first switch to the directory in which -you want to create the file. In Emacs you can do this with the -@kbd{M-x cd} command, or by visiting a file in the directory, or by -listing the directory with @kbd{C-x d} (@code{dired}). Then run the -compile command, with @w{@code{etags *.el}} as the command to execute - -@smallexample -M-x compile RET etags *.el RET -@end smallexample - -@noindent -to create a @file{TAGS} file for Emacs Lisp. - -For example, if you have a large number of files in your -@file{~/emacs} directory, as I do---I have 137 @file{.el} files in it, -of which I load 12---you can create a @file{TAGS} file for the Emacs -Lisp files in that directory. - -@need 1250 -The @code{etags} program takes all the usual shell wildcards. For -example, if you have two directories for which you want a single -@file{TAGS} file, type @w{@code{etags *.el ../elisp/*.el}}, where -@file{../elisp/} is the second directory: - -@smallexample -M-x compile RET etags *.el ../elisp/*.el RET -@end smallexample - -@need 1250 -Type - -@smallexample -M-x compile RET etags --help RET -@end smallexample - -@noindent -to see a list of the options accepted by @code{etags} as well as a -list of supported languages. - -The @code{etags} program handles more than 20 languages, including -Emacs Lisp, Common Lisp, Scheme, C, C++, Ada, Fortran, HTML, Java, -LaTeX, Pascal, Perl, PostScript, Python, TeX, Texinfo, makefiles, and -most assemblers. The program has no switches for specifying the -language; it recognizes the language in an input file according to its -file name and contents. - -@file{etags} is very helpful when you are writing code yourself and -want to refer back to functions you have already written. Just run -@code{etags} again at intervals as you write new functions, so they -become part of the @file{TAGS} file. - -If you think an appropriate @file{TAGS} file already exists for what -you want, but do not know where it is, you can use the @code{locate} -program to attempt to find it. - -Type @w{@kbd{M-x locate @key{RET} TAGS @key{RET}}} and Emacs will list -for you the full path names of all your @file{TAGS} files. On my -system, this command lists 34 @file{TAGS} files. On the other hand, a -plain vanilla system I recently installed did not contain any -@file{TAGS} files. - -If the tags table you want has been created, you can use the @code{M-x -visit-tags-table} command to specify it. Otherwise, you will need to -create the tag table yourself and then use @code{M-x -visit-tags-table}. - -@subsubheading Building Tags in the Emacs sources -@cindex Building Tags in the Emacs sources -@cindex Tags in the Emacs sources -@findex make tags - -The GNU Emacs sources come with a @file{Makefile} that contains a -sophisticated @code{etags} command that creates, collects, and merges -tags tables from all over the Emacs sources and puts the information -into one @file{TAGS} file in the @file{src/} directory. (The -@file{src/} directory is below the top level of your Emacs directory.) - -@need 1250 -To build this @file{TAGS} file, go to the top level of your Emacs -source directory and run the compile command @code{make tags}: - -@smallexample -M-x compile RET make tags RET -@end smallexample - -@noindent -(The @code{make tags} command works well with the GNU Emacs sources, -as well as with some other source packages.) - -For more information, see @ref{Tags, , Tag Tables, emacs, The GNU Emacs -Manual}. - @node Regexp Review @section Review diff --git a/doc/misc/efaq.texi b/doc/misc/efaq.texi index fd4fd4f3798..8eee9e1d869 100644 --- a/doc/misc/efaq.texi +++ b/doc/misc/efaq.texi @@ -2290,7 +2290,7 @@ is actually typical for regexp syntax.) @cindex Recursive search/replace operations Dired mode (@kbd{M-x dired @key{RET}}, or @kbd{C-x d}) supports the -command @code{dired-do-query-replace-regexp} (@kbd{Q}), which allows +command @code{dired-do-find-regexp-and-replace} (@kbd{Q}), which allows users to replace regular expressions in multiple files. You can use this command to perform search/replace operations on @@ -2315,7 +2315,7 @@ To accept all replacements in each file, hit @kbd{!}. Another way to do the same thing is to use the ``tags'' feature of Emacs: it includes the command @code{tags-query-replace} which performs a query-replace across all the files mentioned in the @file{TAGS} file. -@xref{Tags Search,,, emacs, The GNU Emacs Manual}. +@xref{Identifier Search,,, emacs, The GNU Emacs Manual}. @node Documentation for etags @section Where is the documentation for @code{etags}? diff --git a/doc/misc/sem-user.texi b/doc/misc/sem-user.texi index a8684a40b3a..fd88c88c7eb 100644 --- a/doc/misc/sem-user.texi +++ b/doc/misc/sem-user.texi @@ -874,9 +874,9 @@ command, like this: @end example @end defun -These commands are often more accurate than the @code{find-tag} -command (@pxref{Tags,,,emacs,Emacs manual}), because the Semantic -Analyzer is context-sensitive. +These commands are often more accurate than the @code{xref-find-definitions} +command (@pxref{Looking Up Identifiers,,,emacs,Emacs manual}), because +the Semantic Analyzer is context-sensitive. You can also use @kbd{C-c , j} (@code{semantic-complete-jump-local}) and @kbd{C-c , J} (@code{semantic-complete-jump}) to navigate tags. diff --git a/doc/misc/url.texi b/doc/misc/url.texi index a3c6b88ea05..91cb6b54a84 100644 --- a/doc/misc/url.texi +++ b/doc/misc/url.texi @@ -820,12 +820,12 @@ The file transfer protocol. @xref{file/ftp}. @item ssh @cindex ssh -The secure shell protocol. @xref{Inline Methods,,, tramp, The Tramp +The secure shell protocol. @xref{Inline methods,,, tramp, The Tramp Manual}. @item scp @cindex scp -The secure file copy protocol. @xref{External Methods,,, tramp, The +The secure file copy protocol. @xref{External methods,,, tramp, The Tramp Manual}. @item rsync diff --git a/doc/misc/viper.texi b/doc/misc/viper.texi index 6b169f3c8e6..6b82653c629 100644 --- a/doc/misc/viper.texi +++ b/doc/misc/viper.texi @@ -2568,7 +2568,7 @@ above block should be commented out. Even though these commands are sometimes useful, they are no substitute for the powerful @emph{tag table} facility of Emacs. Viper's @kbd{:tag} command -in a primitive interface to Emacs tags. @xref{Tags,Tags,Tags,emacs, +in a primitive interface to Emacs tags. @xref{Tags Tables,,,emacs, The GNU Emacs Manual}, for more information on tags. The following two commands are normally bound to a mouse click and are part -- 2.39.2