From e4800522324e4bf968ab3af4c444735e274f1d25 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sun, 30 Jun 2024 17:42:38 +0300 Subject: [PATCH] Fix documentation for Emacs 30 * etc/NEWS: Mark entries and improve wording. * doc/emacs/dired.texi (Operating on Files): Document 'dired-do-open'. Fix indexing. * doc/emacs/files.texi (Diff Mode): Document 'diff-apply-buffer'. Fix indexing. * doc/emacs/maintaining.texi (Project File Commands) (Project Buffer Commands): Document 'project-any-command'. * doc/emacs/building.texi (Other GDB Buffers): Document the user option 'gdb-display-io-buffer'. (Grep Searching): Document 'grep-use-headings'. * doc/emacs/text.texi (Outline Visibility): Document Outline commands that hide/show by heading regexp. * doc/emacs/killing.texi (Kill Options): Document 'kill-ring-deindent-mode'. * doc/emacs/basic.texi (Continuation Lines): Improve wording. (cherry picked from commit 9b294059d71c20b43a35fd4aaa68e78b23e19d7c) --- doc/emacs/basic.texi | 13 +++++------- doc/emacs/building.texi | 12 +++++++++++ doc/emacs/dired.texi | 9 ++++++++- doc/emacs/files.texi | 41 +++++++++++++++++++++----------------- doc/emacs/killing.texi | 7 +++++++ doc/emacs/maintaining.texi | 15 ++++++++++++++ doc/emacs/text.texi | 16 +++++++++++++++ 7 files changed, 86 insertions(+), 27 deletions(-) diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi index a2a934ff243..42f5c971e2f 100644 --- a/doc/emacs/basic.texi +++ b/doc/emacs/basic.texi @@ -643,14 +643,11 @@ long, by using Auto Fill mode. @xref{Filling}. Normally, the first character of each continuation line is positioned at the beginning of the screen line where it is displayed. The minor mode @code{visual-wrap-prefix-mode} and its global -(@pxref{Minor Modes}) counterpart -@code{global-visual-wrap-prefix-mode} arranges that continuation lines -be prefixed by slightly adjusted versions of the fill prefixes -(@pxref{Fill Prefix}) of their respective logical lines, so that -indentation characters or the prefixes of source code comments are -replicated across every continuation line, and the appearance of such -comments or indentation is not broken. These prefixes are only shown -on display, and does not change the buffer text in any way. +counterpart (@pxref{Minor Modes}) @code{global-visual-wrap-prefix-mode} +arranges for continuation lines to be indented on display using a fill +prefix (@pxref{Fill Prefix}) automatically computed from each line's +surrounding context. These prefixes are display-only feature, and do +not change the buffer text in any way. Sometimes, you may need to edit files containing many long logical lines, and it may not be practical to break them all up by adding diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi index 38cc0bb67af..1b079c2cef9 100644 --- a/doc/emacs/building.texi +++ b/doc/emacs/building.texi @@ -477,6 +477,14 @@ non-@code{nil} if the buffer is to be saved). Any other non-@code{nil} value means that all buffers should be saved without asking. The default is @code{ask}. +@vindex grep-use-headings +@vindex grep-heading@r{ face} + By default, grep matches are shown with the file names prefixed to +each line. But if the variable @code{grep-use-headings} is customized +to a non-@code{nil} value, the matches are split into sections, one +section for each file with matches, and the file names are shown in the +section headings using a special face @code{grep-heading}. + @findex grep-find @findex find-grep The command @kbd{M-x grep-find} (also available as @kbd{M-x @@ -1313,6 +1321,10 @@ of output to its standard output, you may wish to separate its I/O from interaction with GDB. Use the command @w{@kbd{M-x gdb-display-io-buffer}} to show a window with a buffer to which Emacs redirects the input and output from the program you are debugging. +However, if the variable @code{gdb-display-io-buffer} is @code{nil}, +Emacs will not create nor display a separate I/O buffer, but will +instead redirect the program's interaction to the GUD interaction +buffer. @findex gdb-display-registers-buffer @item Registers Buffer diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi index c251a6dc2be..cf57350743f 100644 --- a/doc/emacs/dired.texi +++ b/doc/emacs/dired.texi @@ -803,9 +803,9 @@ The @code{dired-keep-marker-copy} user option controls how this command handles file marking. The default is to mark all new copies of files with a @samp{C} mark. -@item D @findex dired-do-delete @kindex D @r{(Dired)} +@item D Delete the specified files (@code{dired-do-delete}). This is like the shell command @code{rm}. @@ -813,6 +813,13 @@ Like the other commands in this section, this command operates on the @emph{marked} files, or the next @var{n} files. By contrast, @kbd{x} (@code{dired-do-flagged-delete}) deletes all @dfn{flagged} files. +@findex dired-do-open +@kindex E @r{(Dired)} +@item E +``Open'' the specified files using an external program. The program is +selected according to the system conventions, as determined by the +variable @code{shell-command-guess-open}. + @findex dired-do-rename @kindex R @r{(Dired)} @cindex renaming files (in Dired) diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index 5c335df0fc6..8c3df9cc226 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -1631,8 +1631,8 @@ commands to visit the corresponding source locations. manipulate and apply parts of patches: @table @kbd -@item M-n @findex diff-hunk-next +@item M-n Move to the next hunk-start (@code{diff-hunk-next}). With prefix argument @var{n}, move forward to the @var{n}th next hunk. @@ -1643,45 +1643,50 @@ you set @code{diff-refine} to the symbol @code{navigation}, Diff mode only refines the hunk you move to with this command or with @code{diff-hunk-prev}. -@item M-p @findex diff-hunk-prev +@item M-p Move to the previous hunk-start (@code{diff-hunk-prev}). With prefix argument @var{n}, move back to the @var{n}th previous hunk. Like @kbd{M-n}, this command refines the hunk you move to if you set @code{diff-refine} to the symbol @code{navigation}. -@item M-@} @findex diff-file-next +@item M-@} Move to the next file-start, in a multi-file patch (@code{diff-file-next}). With prefix argument @var{n}, move forward to the start of the @var{n}th next file. -@item M-@{ @findex diff-file-prev +@item M-@{ Move to the previous file-start, in a multi-file patch (@code{diff-file-prev}). With prefix argument @var{n}, move back to the start of the @var{n}th previous file. -@item M-k @findex diff-hunk-kill +@item M-k Kill the hunk at point (@code{diff-hunk-kill}). -@item M-K @findex diff-file-kill +@item M-K In a multi-file patch, kill the current file part. (@code{diff-file-kill}). -@item C-c C-a @findex diff-apply-hunk @cindex patches, applying +@item C-c C-a Apply this hunk to its target file (@code{diff-apply-hunk}). With a prefix argument of @kbd{C-u}, revert this hunk, i.e.@: apply the reverse of the hunk, which changes the ``new'' version into the ``old'' version. If @code{diff-jump-to-old-file} is non-@code{nil}, apply the hunk to the ``old'' version of the file instead. -@item C-c C-b +@findex diff-apply-buffer +@item C-c @key{RET} a +Apply all the hunks in the buffer (@code{diff-apply-buffer}). If the +diffs were applied successfully, save the changed buffers. + @findex diff-refine-hunk +@item C-c C-b Highlight the changes of the hunk at point with a finer granularity (@code{diff-refine-hunk}). This allows you to see exactly which parts of each changed line were actually changed. @@ -1691,9 +1696,9 @@ By default, Diff mode refines hunks as Emacs displays them, so you may find this command useful if you customize @code{diff-refine} to a non-default value. -@item C-c C-c @findex diff-goto-source @vindex diff-jump-to-old-file +@item C-c C-c Go to the source file and line corresponding to this hunk (@code{diff-goto-source}). By default, this jumps to the ``new'' version of the file, the one shown first on the file header. @@ -1708,20 +1713,20 @@ this jumps to the work file by default. With a prefix argument, jump to the ``old'' revision of the file (@pxref{Old Revisions}), when point is on the old line, or otherwise jump to the ``new'' revision. -@item C-c C-e @findex diff-ediff-patch +@item C-c C-e Start an Ediff session with the patch (@code{diff-ediff-patch}). @xref{Top, Ediff, Ediff, ediff, The Ediff Manual}. -@item C-c C-n @findex diff-restrict-view +@item C-c C-n Restrict the view to the current hunk (@code{diff-restrict-view}). @xref{Narrowing}. With a prefix argument, restrict the view to the current file of a multiple-file patch. To widen again, use @kbd{C-x n w} (@code{widen}). -@item C-c C-r @findex diff-reverse-direction +@item C-c C-r Reverse the direction of comparison for the entire buffer (@code{diff-reverse-direction}). With a prefix argument, reverse the direction only inside the current region (@pxref{Mark}). Reversing @@ -1729,8 +1734,8 @@ the direction means changing the hunks and the file-start headers to produce a patch that would change the ``new'' version into the ``old'' one. -@item C-c C-s @findex diff-split-hunk +@item C-c C-s Split the hunk at point (@code{diff-split-hunk}) into two separate hunks. This inserts a hunk header and modifies the header of the current hunk. This command is useful for manually editing patches, @@ -1741,35 +1746,35 @@ produced by the @option{-c} or @option{--context} options to @command{diff}, first convert the buffer to the unified diff format with @kbd{C-c C-u}. -@item C-c C-d @findex diff-unified->context +@item C-c C-d Convert the entire buffer to the @dfn{context diff format} (@code{diff-unified->context}). With a prefix argument, convert only the hunks within the region. -@item C-c C-u @findex diff-context->unified +@item C-c C-u Convert the entire buffer to unified diff format (@code{diff-context->unified}). With a prefix argument, convert unified format to context format. When the mark is active, convert only the hunks within the region. -@item C-c C-l @findex diff-refresh-hunk +@item C-c C-l Re-generate the current hunk (@code{diff-refresh-hunk}). -@item C-c C-w @vindex diff-ignore-whitespace-switches @findex diff-ignore-whitespace-hunk +@item C-c C-w Re-generate the current hunk, disregarding changes in whitespace. With a non-@code{nil} prefix arg, re-generate all the hunks (@code{diff-ignore-whitespace-hunk}). This calls @code{diff-command} with @code{diff-ignore-whitespace-switches}, which defaults to @samp{-b}, meaning ignore changes in whitespace only. -@item C-x 4 A @findex diff-add-change-log-entries-other-window @findex add-change-log-entry-other-window@r{, in Diff mode} +@item C-x 4 A Generate a ChangeLog entry, like @kbd{C-x 4 a} does (@pxref{Change Log}), for each one of the hunks (@code{diff-add-change-log-entries-other-window}). This creates a diff --git a/doc/emacs/killing.texi b/doc/emacs/killing.texi index 57adc037cb7..62f72763ac6 100644 --- a/doc/emacs/killing.texi +++ b/doc/emacs/killing.texi @@ -302,6 +302,13 @@ a pure white space string to the kill ring, you can say: non-@code{nil} value, identical subsequent kills yield a single kill-ring entry, without duplication. +@findex kill-ring-deindent-mode + If you enable the minor mode @code{kill-ring-deindent-mode}, text +saved to the kill-ring will have its indentation decreased by the amount +of indentation of the first saved line. That is, if the first line of +the saved text was indented @var{n} columns, this mode will remove that +number of columns from the indentation of each saved line. + @node Yanking @section Yanking @cindex moving text diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index 38f66d29fad..bf64b059722 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -1845,6 +1845,9 @@ Run shell command in the current project's root directory @item C-x p & Run shell command asynchronously in the current project's root directory (@code{project-async-shell-command}). +@item C-x p o +Run the next command in the current project +(@code{project-any-command}). @end table Emacs provides commands for handling project files conveniently. @@ -1941,6 +1944,11 @@ directory. @xref{Top,Eshell,Eshell, eshell, Eshell: The Emacs Shell}. The command @kbd{C-x p &} (@code{project-async-shell-command}) runs @code{async-shell-command} in the current project's root directory. +@findex project-any-command + Finally, the command @kbd{C-x p o} (@code{project-any-command}) will +run the next command you type, whether related to files or not, in the +current project. + @node Project Buffer Commands @subsection Project Commands That Operate on Buffers @@ -1953,6 +1961,9 @@ List the project buffers (@code{project-list-buffers}). @item C-x p k Kill all live buffers that belong to the current project (@code{project-kill-buffers}). +@item C-x p o +Run the next command in the current project +(@code{project-any-command}). @end table @findex project-switch-to-buffer @@ -1981,6 +1992,10 @@ project that satisfy any of @code{project-kill-buffer-conditions}. If @code{project-kill-buffers-display-buffer-list} is non-@code{nil}, the buffers to be killed will be displayed first. + Finally, the command @kbd{C-x p o} (@code{project-any-command}) will +run the next command you type, whether related to buffers or not, in the +current project. + @node Switching Projects @subsection Switching Projects diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi index 1d1065c45c2..8abaeafcf33 100644 --- a/doc/emacs/text.texi +++ b/doc/emacs/text.texi @@ -1208,6 +1208,12 @@ Hide everything except the top @var{n} levels of heading lines Hide everything except for the heading or body that point is in, plus the headings leading up from there to the top level of the outline (@code{outline-hide-other}). +@item C-c / h @var{regexp} @key{RET} +Hide bodies of headings that match @var{regexp} +(@code{outline-hide-by-heading-regexp}). +@item C-c / s @var{regexp} @key{RET} +Show bodies of headings that match @var{regexp} +(@code{outline-show-by-heading-regexp}). @end table @findex outline-hide-entry @@ -1253,6 +1259,16 @@ headers leading up from there to top level in the outline) and the top level headings. It also reveals body lines preceding the first heading in the buffer. +@findex outline-hide-by-heading-regexp +@findex outline-show-by-heading-regexp +@kindex C-c / h @r{(Outline mode)} +@kindex C-c / s @r{(Outline mode)} + The command @kbd{C-c / h} (@code{outline-hide-by-heading-regexp}) +prompts for a regular expression, and hides all the body lines of +headings which match the regular expression. The command @kbd{C-c / s} +likewise prompts for a regular expression, and reveals the bodies of +matching headings. + @findex outline-hide-body @findex outline-show-all @kindex C-c C-t @r{(Outline mode)} -- 2.39.2