diff options
Diffstat (limited to 'doc/emacs')
| -rw-r--r-- | doc/emacs/Makefile.in | 28 | ||||
| -rw-r--r-- | doc/emacs/back.texi | 102 | ||||
| -rw-r--r-- | doc/emacs/basic.texi | 21 | ||||
| -rw-r--r-- | doc/emacs/book-spine.texi | 20 | ||||
| -rw-r--r-- | doc/emacs/buffers.texi | 12 | ||||
| -rw-r--r-- | doc/emacs/building.texi | 7 | ||||
| -rw-r--r-- | doc/emacs/commands.texi | 2 | ||||
| -rw-r--r-- | doc/emacs/custom.texi | 43 | ||||
| -rw-r--r-- | doc/emacs/dired.texi | 43 | ||||
| -rw-r--r-- | doc/emacs/display.texi | 48 | ||||
| -rw-r--r-- | doc/emacs/docstyle.texi | 1 | ||||
| -rw-r--r-- | doc/emacs/emacs.texi | 10 | ||||
| -rw-r--r-- | doc/emacs/files.texi | 39 | ||||
| -rw-r--r-- | doc/emacs/fixit.texi | 9 | ||||
| -rw-r--r-- | doc/emacs/frames.texi | 37 | ||||
| -rw-r--r-- | doc/emacs/help.texi | 59 | ||||
| -rw-r--r-- | doc/emacs/killing.texi | 126 | ||||
| -rw-r--r-- | doc/emacs/m-x.texi | 20 | ||||
| -rw-r--r-- | doc/emacs/maintaining.texi | 207 | ||||
| -rw-r--r-- | doc/emacs/mini.texi | 34 | ||||
| -rw-r--r-- | doc/emacs/misc.texi | 47 | ||||
| -rw-r--r-- | doc/emacs/modes.texi | 10 | ||||
| -rw-r--r-- | doc/emacs/msdos.texi | 9 | ||||
| -rw-r--r-- | doc/emacs/mule.texi | 6 | ||||
| -rw-r--r-- | doc/emacs/package.texi | 30 | ||||
| -rw-r--r-- | doc/emacs/search.texi | 31 | ||||
| -rw-r--r-- | doc/emacs/text.texi | 67 | ||||
| -rw-r--r-- | doc/emacs/windows.texi | 3 |
28 files changed, 843 insertions, 228 deletions
diff --git a/doc/emacs/Makefile.in b/doc/emacs/Makefile.in index 2a3f53f740d..69d39efa8b9 100644 --- a/doc/emacs/Makefile.in +++ b/doc/emacs/Makefile.in @@ -28,6 +28,8 @@ srcdir=@srcdir@ top_srcdir = @top_srcdir@ +top_builddir = @top_builddir@ + version = @version@ ## Where the output files go. @@ -73,13 +75,7 @@ TEXI2DVI = texi2dvi TEXI2PDF = texi2pdf DVIPS = dvips -# 'make' verbosity. -AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ - -AM_V_GEN = $(am__v_GEN_@AM_V@) -am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) -am__v_GEN_0 = @echo " GEN " $@; -am__v_GEN_1 = +-include ${top_builddir}/src/verbose.mk ENVADD = $(AM_V_GEN)TEXINPUTS="$(srcdir):$(texinfodir):$(TEXINPUTS)" \ MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" @@ -224,7 +220,7 @@ infoclean: $(buildinfodir)/emacs.info-[1-9][0-9] bootstrap-clean maintainer-clean: distclean infoclean - rm -f ${srcdir}/emacsver.texi + rm -f ${srcdir}/emacsver.texi TAGS .PHONY: install-dvi install-html install-pdf install-ps install-doc @@ -273,4 +269,20 @@ uninstall-pdf: uninstall-doc: uninstall-dvi uninstall-html uninstall-pdf uninstall-ps +ETAGS = ../../lib-src/etags${EXEEXT} + +${ETAGS}: FORCE + $(MAKE) -C $(dir $@) $(notdir $@) + +texifiles = $(wildcard ${srcdir}/*.texi) + +TAGS: ${ETAGS} $(texifiles) + $(AM_V_GEN)${ETAGS} --include=../lispref/TAGS --include=../misc/TAGS $(texifiles) + +tags: TAGS +.PHONY: tags + +FORCE: +.PHONY: FORCE + ### Makefile ends here diff --git a/doc/emacs/back.texi b/doc/emacs/back.texi new file mode 100644 index 00000000000..dc4e218d378 --- /dev/null +++ b/doc/emacs/back.texi @@ -0,0 +1,102 @@ +\input texinfo @c -*-texinfo-*- +@c This is part of the Emacs manual. +@c Copyright (C) 1985--1987, 1993--1995, 1997, 2001--2021 Free Software +@c Foundation, Inc. +@c See file emacs.texi for copying conditions. +@c +@c %**start of header +@setfilename back-cover +@settitle GNU Emacs Manual +@include docstyle.texi +@c %**end of header +. +@sp 7 +@center @titlefont {GNU Emacs Manual} +@sp 1 + +@quotation +GNU Emacs is much @strong{more than a text editor;} over the years, it +has expanded to become @strong{an entire workflow environment,} +impressing programmers with its integrated debugging and +project-management features. It is also a multi-lingual word +processor, can handle all your email and Usenet news needs, display +web pages, and even has a diary and a calendar for your appointments! + +Features include: + +@itemize @bullet +@item +Special editing modes for @strong{27 programming languages,} including C, +C@t{++}, Fortran, Java, JavaScript, Lisp, Objective C, Pascal, Perl, +and Scheme. + +@item +Special @strong{scripting language modes} for Bash, other common shells, +and creating Makefiles for GNU/Linux, UNIX, Windows/DOS, and VMS +systems. + +@item +Support for typing and displaying in @strong{60 non-English languages,} +including Arabic, Chinese, Czech, Hebrew, Hindi, Japanese, Korean, +Russian, Vietnamese, and all Western European languages. + +@item +The ability to: + +@itemize @minus +@item +Create @strong{PostScript output} from plain-text files (special +editing modes for @LaTeX{} and @TeX{} are included). + + +@item +@strong{Compile} and @strong{debug} from inside Emacs. + +@item +Maintain program @strong{ChangeLogs.} + +@item +Flag, move, and delete files and sub-directories recursively +@strong{(directory navigation).} + +@item +Run @strong{shell commands} from inside Emacs, or even use Emacs itself +as a shell (Eshell). + +@item +Enjoy the use of extensive @strong{merge} and @strong{diff} functions. + +@item +Take advantage of built-in support for many @strong{version control +systems,} including Git, Mercurial, Bazaar, Subversion, and CVS. + +@item +And much more! +@end itemize +@end itemize + +Emacs comes with an introductory online tutorial available in many +languages, and this nineteenth edition of the manual picks up where +that tutorial ends. It explains the full range of the power of Emacs, +now up to @strong[version 27.2,} and contains reference material +useful to expert users. It also includes appendices with specific +material about X and GTK resources, and with details for users of +macOS and Microsoft Windows. + +And when you tire of all the work you can accomplish with Emacs, enjoy +the games that come with it. + +@strong{About the original and principal author:} + +Richard M.@: Stallman developed the first Emacs in 1976 and wrote GNU +Emacs in 1984/85. He has received the ACM Grace Hopper Award, a +MacArthur Foundation fellowship, the Electronic Frontier Foundation's +Pioneer award, the Takeda Award for Social/Economic Betterment, and +the ACM Software and System Award, as well as several doctorates +@emph{honoris causa.} +@end quotation + +@hfil +@bye + ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi index 444b28f24be..ba8d822b18e 100644 --- a/doc/emacs/basic.texi +++ b/doc/emacs/basic.texi @@ -112,7 +112,7 @@ just like digits. Case is ignored. @cindex curly quotes, inserting @cindex curved quotes, inserting A few common Unicode characters can be inserted via a command -starting with @kbd{C-x 8}. For example, @kbd{C-x 8 [} inserts @t{‘} +starting with @w{@kbd{C-x 8}}. For example, @kbd{C-x 8 [} inserts @t{‘} which is Unicode code-point U+2018 @sc{left single quotation mark}, sometimes called a left single ``curved quote'' or ``curly quote''. Similarly, @w{@kbd{C-x 8 ]}}, @kbd{C-x 8 @{} and @kbd{C-x 8 @}} insert the @@ -331,6 +331,11 @@ a plain prefix argument. Alternatively, you can use the command @code{goto-line-relative} to move point to the line relative to the accessible portion of the narrowed buffer. +@code{goto-line} has its own history list (@pxref{Minibuffer +History}). You can have either a single list shared between all +buffers (the default) or a separate list for each buffer, by +customizing the user option @code{goto-line-history-local}. + @item M-g @key{TAB} @kindex M-g TAB @findex move-to-column @@ -880,3 +885,17 @@ characters. You can repeat that command (including its argument) three additional times, to delete a total of 80 characters, by typing @kbd{C-x z z z}. The first @kbd{C-x z} repeats the command once, and each subsequent @kbd{z} repeats it once again. + +@findex repeat-mode + Also you can activate @code{repeat-mode} that temporarily enables +a transient mode with short keys after a limited number of commands. +Currently supported shorter key sequences are @kbd{C-x u u} instead of +@kbd{C-x u C-x u} to undo many changes, @kbd{C-x o o} instead of +@kbd{C-x o C-x o} to switch several windows, @kbd{C-x @{ @{ @} @} ^ ^ +v v} to resize the selected window interactively, @kbd{M-g n n p p} to +navigate @code{next-error} matches. Any other key exits transient mode +and then is executed normally. The user option @code{repeat-exit-key} +defines an additional key to exit this transient mode. Also it's +possible to break the repetition chain automatically after idle time +by customizing the user option @code{repeat-exit-timeout} to a number +of seconds. diff --git a/doc/emacs/book-spine.texi b/doc/emacs/book-spine.texi new file mode 100644 index 00000000000..9634cceedaf --- /dev/null +++ b/doc/emacs/book-spine.texi @@ -0,0 +1,20 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename book-spine +@settitle book-spine +@include docstyle.texi +@c %**end of header + +@include emacsver.texi + +@c need dot in text so first space command works! +. +@sp 7 + +@center @titlefont{GNU Emacs Manual} +@sp 5 +@center @value{EDITION} edition, for Emacs version @value{EMACSVER} +@sp 5 + +@center by Richard M.@: Stallman et al. +@bye diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi index 3a166e404a8..c4e5bc32b7c 100644 --- a/doc/emacs/buffers.texi +++ b/doc/emacs/buffers.texi @@ -586,9 +586,6 @@ every @code{auto-revert-interval} seconds if you enable Auto Revert mode in this buffer, as long as it is not marked modified. Global Auto Revert mode applies to the @file{*Buffer List*} buffer only if @code{global-auto-revert-non-file-buffers} is non-@code{nil}. -@iftex -@inforef{Auto Reverting the Buffer Menu,, emacs-xtra}, for details. -@end iftex @ifnottex @xref{Auto Reverting the Buffer Menu, global-auto-revert-non-file-buffers}, for details. @end ifnottex @@ -765,6 +762,15 @@ your initialization file (@pxref{Init File}): the variable @code{fido-mode} to @code{t} (@pxref{Easy Customization}). +@findex icomplete-vertical-mode +@cindex Icomplete vertical mode + + Icomplete mode and Fido mode display the possible completions on the +same line as the prompt by default. To display the completion candidates +vertically under the prompt, type @kbd{M-x icomplete-vertical-mode}, or +customize the variable @code{icomplete-vertical-mode} to @code{t} +(@pxref{Easy Customization}). + @node Buffer Menus @subsection Customizing Buffer Menus diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi index 7194eb90ca9..8de93867baa 100644 --- a/doc/emacs/building.texi +++ b/doc/emacs/building.texi @@ -1486,6 +1486,13 @@ Emacs Lisp code goes in a separate file whose name ends in @file{foo.elc}. @xref{Byte Compilation,, Byte Compilation, elisp, the Emacs Lisp Reference Manual}. +@cindex native compilation + Emacs Lisp code can also be compiled into @dfn{native code}: machine +code not unlike the one produced by a C or Fortran compiler. Native +code runs even faster than byte-code. Natively-compiled Emacs Lisp +code is stored in files whose names end in @samp{.eln}. @xref{Native +Compilation,, Byte Compilation, elisp, the Emacs Lisp Reference Manual}. + @findex load-file To @dfn{load} an Emacs Lisp file, type @kbd{M-x load-file}. This command reads a file name using the minibuffer, and executes the diff --git a/doc/emacs/commands.texi b/doc/emacs/commands.texi index 82a917ce7d1..f56f820b399 100644 --- a/doc/emacs/commands.texi +++ b/doc/emacs/commands.texi @@ -121,7 +121,7 @@ C-k} is two key sequences, not one. By default, the prefix keys in Emacs are @kbd{C-c}, @kbd{C-h}, @kbd{C-x}, @kbd{C-x @key{RET}}, @kbd{C-x @@}, @kbd{C-x a}, @kbd{C-x n}, @kbd{C-x r}, @kbd{C-x t}, @kbd{C-x v}, @kbd{C-x 4}, @kbd{C-x 5}, -@kbd{C-x 6}, @key{ESC}, @kbd{M-g}, and @kbd{M-o}. (@key{F1} and +@kbd{C-x 6}, @key{ESC}, and @kbd{M-g}. (@key{F1} and @key{F2} are aliases for @kbd{C-h} and @kbd{C-x 6}.) This list is not cast in stone; if you customize Emacs, you can make new prefix keys. You could even eliminate some of the standard ones, though this is not diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index ccf5f1932f9..999234e6d33 100644 --- a/doc/emacs/custom.texi +++ b/doc/emacs/custom.texi @@ -388,15 +388,15 @@ file. For example: Emacs versions, like this: @example -(cond ((< emacs-major-version 22) - ;; @r{Emacs 21 customization.} - (setq custom-file "~/.config/custom-21.el")) - ((and (= emacs-major-version 22) +(cond ((< emacs-major-version 28) + ;; @r{Emacs 27 customization.} + (setq custom-file "~/.config/custom-27.el")) + ((and (= emacs-major-version 26) (< emacs-minor-version 3)) - ;; @r{Emacs 22 customization, before version 22.3.} - (setq custom-file "~/.config/custom-22.el")) + ;; @r{Emacs 26 customization, before version 26.3.} + (setq custom-file "~/.config/custom-26.el")) (t - ;; @r{Emacs version 22.3 or later.} + ;; @r{Emacs version 28.1 or later.} (setq custom-file "~/.config/emacs-custom.el"))) (load custom-file) @@ -519,12 +519,9 @@ Set up a customization buffer for all the settings and groups that match @var{regexp}. @item M-x customize-changed @key{RET} @var{version} @key{RET} -Set up a customization buffer with all the settings and groups -whose meaning has changed since Emacs version @var{version}. - -@item M-x customize-changed-options @key{RET} @var{version} @key{RET} -Set up a customization buffer with all the options whose meaning or -default values have changed since Emacs version @var{version}. +Set up a customization buffer with all the user options, faces and +groups whose meaning has changed since (or been added after) Emacs +version @var{version}. @item M-x customize-saved Set up a customization buffer containing all settings that you @@ -626,7 +623,7 @@ button. the theme file and asks if you really want to load it. Because loading a Custom theme can execute arbitrary Lisp code, you should only say yes if you know that the theme is safe; in that case, Emacs -offers to remember in the future that the theme is safe (this is done +offers to remember in the future that the theme is safe(this is done by saving the theme file's SHA-256 hash to the variable @code{custom-safe-themes}; if you want to treat all themes as safe, change its value to @code{t}). Themes that come with Emacs (in the @@ -1274,7 +1271,13 @@ confirmation prompt. When Emacs encounters these variable/value pairs subsequently, in the same file or others, it will assume they are safe. + You can also tell Emacs to permanently ignore all the variable/value +pairs in the file, by typing @kbd{i} at the confirmation prompt -- +these pairs will thereafter be ignored in this file and in all other +files. + @vindex safe-local-variable-values +@vindex ignored-local-variable-values @cindex risky variable Some variables, such as @code{load-path}, are considered particularly @dfn{risky}: there is seldom any reason to specify them @@ -1286,6 +1289,8 @@ can enter @kbd{!} at the prompt. It applies all the variables, but only marks the non-risky ones as safe for the future. If you really want to record safe values for risky variables, do it directly by customizing @samp{safe-local-variable-values} (@pxref{Easy Customization}). +Similarly, if you want to record values of risky variables that should +be permanently ignored, customize @code{ignored-local-variable-values}. @vindex enable-local-variables The variable @code{enable-local-variables} allows you to change the @@ -1410,6 +1415,16 @@ meanings as they would have in file local variables. @code{coding} cannot be specified as a directory local variable. @xref{File Variables}. +The special key @code{auto-mode-alist} in a @file{.dir-locals.el} lets +you set a file's major mode. It works much like the variable +@code{auto-mode-alist} (@pxref{Choosing Modes}). For example, here is +how you can tell Emacs that @file{.def} source files in this directory +should be in C mode: + +@example +((auto-mode-alist . (("\\.def\\'" . c-mode)))) +@end example + @findex add-dir-local-variable @findex delete-dir-local-variable @findex copy-file-locals-to-dir-locals diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi index 34d12acc349..680b20c5938 100644 --- a/doc/emacs/dired.texi +++ b/doc/emacs/dired.texi @@ -129,6 +129,12 @@ options (that is, single characters) requiring no arguments, and long options (starting with @samp{--}) whose arguments are specified with @samp{=}. + Dired does not handle files that have names with embedded newline +characters well. If you have many such files, you may consider adding +@samp{-b} to @code{dired-listing-switches}. This will quote all +special characters and allow Dired to handle them better. (You can +also use the @kbd{C-u C-x d} command to add @samp{-b} temporarily.) + @vindex dired-switches-in-mode-line Dired displays in the mode line an indication of what were the switches used to invoke @command{ls}. By default, Dired will try to @@ -451,6 +457,15 @@ Visit the parent directory of the current directory for @file{..} and typing @kbd{f} there. @end table +@defopt dired-kill-when-opening-new-dired-buffer + When visiting a new sub-directory in Dired, Emacs will (by default) +open a new buffer to display this new directory, and leave the old +Dired buffer as is. If this user option is non-@code{nil}, the old +Dired buffer will be killed after selecting the new directory. This +means that if you're traversing a directory structure in Dired, you +won't end up with more than a single Dired buffer. +@end defopt + @node Marks vs Flags @section Dired Marks vs.@: Flags @@ -856,21 +871,24 @@ Compress the specified files (@code{dired-do-compress}). If the file appears to be a compressed file already, uncompress it instead. Each marked file is compressed into its own archive; this uses the @command{gzip} program if it is available, otherwise it uses -@command{compress}. On a directory name, this command produces a -compressed @file{.tar.gz} archive containing all of the directory's -files, by running the @command{tar} command with output piped to -@command{gzip}. To allow decompression of compressed directories, -typing @kbd{Z} on a @file{.tar.gz} or @file{.tgz} archive file unpacks -all the files in the archive into a directory whose name is the -archive name with the extension removed. +@command{compress}. + +On a directory name, this command produces a compressed archive +depending on the @code{dired-compress-directory-default-suffix} user +option. The default is a @file{.tar.gz} archive containing all of the +directory's files, by running the @command{tar} command with output +piped to @command{gzip}. To allow decompression of compressed +directories, typing @kbd{Z} on a @file{.tar.gz} or @file{.tgz} archive +file unpacks all the files in the archive into a directory whose name +is the archive name with the extension removed. @findex dired-do-compress-to @kindex c @r{(Dired)} @item c Compress the specified files (@code{dired-do-compress-to}) into a -single archive anywhere on the file system. The compression algorithm -is determined by the extension of the archive, see -@code{dired-compress-files-alist}. +single archive anywhere on the file system. The default archive is +controlled by the @code{dired-compress-directory-default-suffix} user +option. Also see @code{dired-compress-files-alist}. @findex epa-dired-do-decrypt @kindex :d @r{(Dired)} @@ -1535,6 +1553,11 @@ image. You comment a file from the thumbnail buffer by typing @kbd{c}. You will be prompted for a comment. Type @kbd{C-t c} to add a comment from Dired (@code{image-dired-dired-comment-files}). +@vindex image-dired-thumb-visible-marks + Files that are marked in Dired will also be marked in Image-Dired if +@code{image-dired-thumb-visible-marks} is non-@code{nil} (which is the +default). + Image-Dired also provides simple image manipulation. In the thumbnail buffer, type @kbd{L} to rotate the original image 90 degrees anti clockwise, and @kbd{R} to rotate it 90 degrees clockwise. This diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi index 58d08b43c0e..ae345c11df5 100644 --- a/doc/emacs/display.texi +++ b/doc/emacs/display.texi @@ -1189,8 +1189,8 @@ that has some special meaning for formatting the source code of a program. To activate the fill-column indication display, use the minor modes -@w{@kbd{M-x display-fill-column-indicator-mode}} and -@w{@kbd{M-x global-display-fill-column-indicator-mode}}, which enable +@code{display-fill-@-column-indicator-mode} and +@code{global-display-fill-column-indicator-mode}, which enable the indicator locally or globally, respectively. Alternatively, you can set the two buffer-local variables @@ -1220,8 +1220,8 @@ The value @code{nil} disables the indicator. When the mode is enabled through the functions @code{display-fill-column-indicator-mode} or @code{global-display-fill-column-indicator-mode}, they will use the character specified by this variable, if it is non-@code{nil}; -otherwise Emacs will use the character @samp{U+2502 VERTICAL LINE}, -falling back to @samp{|} if @code{U+2502} cannot be displayed. +otherwise Emacs will use the character U+2502 @sc{box drawings light vertical}, +falling back to @samp{|} if U+2502 cannot be displayed. @item fill-column-indicator @vindex fill-column-indicator @@ -1577,8 +1577,8 @@ characters, as well as many non-@acronym{ASCII} characters. @cindex control characters on display The @acronym{ASCII} character set contains non-printing @dfn{control characters}. Two of these are displayed specially: the newline -character (Unicode code point @code{U+000A}) is displayed by starting -a new line, while the tab character (@code{U+0009}) is displayed as a +character (Unicode code point U+000A) is displayed by starting +a new line, while the tab character (U+0009) is displayed as a space that extends to the next tab stop column (normally every 8 columns). The number of spaces per tab is controlled by the buffer-local variable @code{tab-width}, which must have an integer @@ -1587,17 +1587,17 @@ character in the buffer is displayed has nothing to do with the definition of @key{TAB} as a command. Other @acronym{ASCII} control characters, whose codes are below -@code{U+0020} (octal 40, decimal 32), are displayed as a caret +U+0020 (octal 40, decimal 32), are displayed as a caret (@samp{^}) followed by the non-control version of the character, with the @code{escape-glyph} face. For instance, the @samp{control-A} -character, @code{U+0001}, is displayed as @samp{^A}. +character, U+0001, is displayed as @samp{^A}. @cindex octal escapes @vindex ctl-arrow - The raw bytes with codes @code{U+0080} (octal 200) through -@code{U+009F} (octal 237) are displayed as @dfn{octal escape + The raw bytes with codes U+0080 (octal 200) through +U+009F (octal 237) are displayed as @dfn{octal escape sequences}, with the @code{escape-glyph} face. For instance, -character code @code{U+0098} (octal 230) is displayed as @samp{\230}. +character code U+0098 (octal 230) is displayed as @samp{\230}. If you change the buffer-local variable @code{ctl-arrow} to @code{nil}, the @acronym{ASCII} control characters are also displayed as octal escape sequences instead of caret escape sequences. (You can @@ -1616,11 +1616,11 @@ can cause problems if they are entered into a buffer without your realization, e.g., by yanking; for instance, source code compilers typically do not treat non-@acronym{ASCII} spaces as whitespace characters. To deal with this problem, Emacs displays such characters -specially: it displays @code{U+00A0} (no-break space) and other +specially: it displays U+00A0 @sc{no-break space} and other characters from the Unicode horizontal space class with the -@code{nobreak-space} face, and it displays @code{U+00AD} (soft -hyphen), @code{U+2010} (hyphen), and @code{U+2011} (non-breaking -hyphen) with the @code{nobreak-hyphen} face. To disable this, change +@code{nobreak-space} face, and it displays U+00AD @sc{soft +hyphen}, U+2010 @sc{hyphen}, and U+2011 @sc{non-breaking +hyphen} with the @code{nobreak-hyphen} face. To disable this, change the variable @code{nobreak-char-display} to @code{nil}. If you give this variable a non-@code{nil} and non-@code{t} value, Emacs instead displays such characters as a highlighted backslash followed by a @@ -1649,10 +1649,10 @@ for details. @cindex curved quotes, and terminal capabilities @cindex @code{homoglyph} face -Emacs tries to determine if the curved quotes @samp{‘} and @samp{’} +Emacs tries to determine if the curved quotes @t{‘} and @t{’} can be displayed on the current display. By default, if this seems to -be so, then Emacs will translate the @acronym{ASCII} quotes (@samp{`} -and @samp{'}), when they appear in messages and help texts, to these +be so, then Emacs will translate the @acronym{ASCII} quotes @w{(@samp{`} +and @samp{'})}, when they appear in messages and help texts, to these curved quotes. You can influence or inhibit this translation by customizing the user option @code{text-quoting-style} (@pxref{Keys in Documentation,,, elisp, The Emacs Lisp Reference Manual}). @@ -1661,7 +1661,7 @@ Documentation,,, elisp, The Emacs Lisp Reference Manual}). known to look just like @acronym{ASCII} characters, they are shown with the @code{homoglyph} face. Curved quotes that are known not to be displayable are shown as their @acronym{ASCII} approximations -@t{`}, @t{'}, and @t{"} with the @code{homoglyph} face. +@samp{`}, @samp{'}, and @samp{"} with the @code{homoglyph} face. @node Cursor Display @section Displaying the Cursor @@ -1829,15 +1829,15 @@ variable @code{visual-line-fringe-indicators}. That produces incorrect results when CJK and Latin text are mixed together (because CJK characters don't use whitespace to separate words). You can customize the option @code{word-wrap-by-category} to -allow Emacs to break lines after any character with ``|'' category +allow Emacs to break lines after any character with @samp{|} category (@pxref{Categories,,, elisp, the Emacs Lisp Reference Manual}), which provides better support for CJK characters. Also, if this variable is set using Customize, Emacs automatically loads @file{kinsoku.el}. When @file{kinsoku.el} is loaded, Emacs respects kinsoku rules when -breaking lines. That means characters with the ``>'' category don't -appear at the beginning of a line (e.g., U+FF0C FULLWIDTH COMMA), and -characters with the ``<'' category don't appear at the end of a line -(e.g., U+300A LEFT DOUBLE ANGLE BRACKET). You can view the category +breaking lines. That means characters with the @samp{>} category don't +appear at the beginning of a line (e.g., U+FF0C @sc{fullwidth comma}), and +characters with the @samp{<} category don't appear at the end of a line +(e.g., U+300A @sc{left double angle bracket}). You can view the category set of a character using the commands @code{char-category-set} and @code{category-set-mnemonics}, or by typing @kbd{C-u C-x =} with point on the character and looking at the ``category'' section in the diff --git a/doc/emacs/docstyle.texi b/doc/emacs/docstyle.texi index 5bdcd079d91..e7404398d24 100644 --- a/doc/emacs/docstyle.texi +++ b/doc/emacs/docstyle.texi @@ -15,4 +15,5 @@ @hyphenation{work-a-round} @hyphenation{work-a-rounds} @hyphenation{un-marked} +@hyphenation{dic-tion-ary} @end iftex diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index 4054b094def..d2011ebf974 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -92,13 +92,14 @@ developing GNU and promoting software freedom.'' Published by the Free Software Foundation @* 51 Franklin Street, Fifth Floor @* Boston, MA 02110-1301 USA @* -ISBN 978-0-9831592-5-4 +ISBN 978-0-9831592-8-5 @sp 2 -Cover art by Etienne Suvasa; cover design by Matt Lee. +Cover art by Etienne Suvasa; cover design by FSF staff. @end titlepage +@headings double @summarycontents @contents @@ -159,7 +160,7 @@ Fundamental Editing Commands Important Text-Changing Commands * Mark:: The mark: how to delimit a region of text. -* Killing:: Killing (cutting) and yanking (copying) text. +* Killing:: Killing (cutting) and yanking (pasting) text. * Registers:: Saving a text string or a location in the buffer. * Display:: Controlling what text is displayed. * Search:: Finding or replacing occurrences of a string. @@ -794,6 +795,8 @@ Maintaining Large Programs @ifnottex * Emerge:: A convenient way of merging two versions of a program. @end ifnottex +* Bug Reference:: Highlighting references to bug reports and browsing + them in their issue trackers. Version Control @@ -861,6 +864,7 @@ Projects * Project File Commands:: Commands for handling project files. * Project Buffer Commands:: Commands for handling project buffers. * Switching Projects:: Switching between projects. +* Managing Projects:: Managing the project list file. Change Logs diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index 6b3bc430d97..8304e40706a 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -227,6 +227,15 @@ File Names}, for information on how to visit a file whose name actually contains wildcard characters. You can disable the wildcard feature by customizing @code{find-file-wildcards}. +@vindex query-about-changed-file + If you're asking to visit a file that's already visited in a buffer, +but the file has changed externally, Emacs normally asks you whether +you want to re-read the file from disk. But if you set +@code{query-about-changed-file} to @code{nil}, Emacs won't query you, +but will instead just display the buffer's contents before the +changes, and show an echo-area message telling you how to revert the +buffer from the file. + @kindex C-x C-v @findex find-alternate-file If you visit the wrong file unintentionally by typing its name @@ -789,7 +798,9 @@ Emacs buffer visiting it has unsaved changes. @vindex create-lockfiles You can prevent the creation of lock files by setting the variable @code{create-lockfiles} to @code{nil}. @strong{Caution:} by -doing so you will lose the benefits that this feature provides. +doing so you will lose the benefits that this feature provides. You +can also control where lock files are written by using the +@code{lock-file-name-transforms} variable. @cindex collision If you begin to modify the buffer while the visited file is locked by @@ -834,6 +845,14 @@ warning message and asks for confirmation before saving; answer place, one way to compare the buffer to its file is the @kbd{M-x diff-buffer-with-file} command. @xref{Comparing Files}. +@vindex remote-file-name-inhibit-locks + You can prevent the creation of remote lock files by setting the +variable @code{remote-file-name-inhibit-locks} to @code{t}. + +@cindex lock-file-mode + The minor mode @code{lock-file-mode}, called interactively, toggles +the local value of @code{create-lockfiles} in the current buffer. + @node File Shadowing @subsection Shadowing Files @cindex shadow files @@ -929,7 +948,7 @@ Manual}). For customizations, see the Custom group @code{time-stamp}. then change your mind, you can @dfn{revert} the changes and go back to the saved version of the file. To do this, type @kbd{C-x x g}. Since reverting unintentionally could lose a lot of work, Emacs asks for -confirmation first. +confirmation first if the buffer is modified. The @code{revert-buffer} command tries to position point in such a way that, if the file was edited only slightly, you will be at @@ -972,6 +991,17 @@ revert it automatically if it has changed---provided the buffer itself is not modified. (If you have edited the text, it would be wrong to discard your changes.) +@vindex revert-buffer-quick-short-answers +@findex revert-buffer-quick + The @kbd{C-x x g} keystroke is bound to the +@code{revert-buffer-quick} command. This is like the +@code{revert-buffer} command, but prompts less. Unlike +@code{revert-buffer}, it will not prompt if the current buffer visits +a file, and the buffer is not modified. It also respects the +@code{revert-buffer-quick-short-answers} user option. If this option +is non-@code{nil}, use a shorter @kbd{y/n} query instead of a longer +@kbd{yes/no} query. + You can also tell Emacs to revert buffers automatically when their visited files change on disk; @pxref{Auto Revert}. @@ -1670,8 +1700,9 @@ modify the original (``old'') source files rather than the patched (``new'') source files. @vindex diff-font-lock-syntax - If non-@code{nil}, fragments of source in hunks are highlighted -according to the appropriate major mode. + If @code{diff-font-lock-syntax} is non-@code{nil}, fragments of +source in hunks are highlighted according to the appropriate major +mode. @node Copying and Naming @section Copying, Naming and Renaming Files diff --git a/doc/emacs/fixit.texi b/doc/emacs/fixit.texi index 6b41849ccc8..b558ebc3fdc 100644 --- a/doc/emacs/fixit.texi +++ b/doc/emacs/fixit.texi @@ -263,6 +263,13 @@ systems. @xref{Top, Aspell,, aspell, The Aspell Manual}. @end ifnottex +@vindex ispell-program-name + If you have only one of the spelling checker programs installed, +Emacs will find it when you invoke for the first time one of the +commands described here. If you have more than one of them installed, +you can control which one is used by customizing the variable +@code{ispell-program-name}. + @table @kbd @item M-$ Check and correct spelling of the word at point (@code{ispell-word}). @@ -365,7 +372,7 @@ Like @kbd{i}, but you can also specify dictionary completion information. @item u -Insert the lower-case version of this word in your private dic@-tion@-ary +Insert the lower-case version of this word in your private dictionary file. @item l @var{word} @key{RET} diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi index e1a4e64a7d4..5b15e6290d0 100644 --- a/doc/emacs/frames.texi +++ b/doc/emacs/frames.texi @@ -366,20 +366,15 @@ This menu is for changing the default face within the window's buffer. @xref{Text Scale}. @end table +@cindex context menu +@findex context-menu-mode +@vindex context-menu-functions +@kindex Down-mouse-3 Some graphical applications use @kbd{mouse-3} for a mode-specific -menu. If you prefer @kbd{mouse-3} in Emacs to bring up such a menu -instead of running the @code{mouse-save-then-kill} command, rebind -@kbd{mouse-3} by adding the following line to your init file -(@pxref{Init Rebinding}): - -@smallexample -(global-set-key [mouse-3] - '(menu-item "Menu Bar" ignore - :filter (lambda (_) - (if (zerop (or (frame-parameter nil 'menu-bar-lines) 0)) - (mouse-menu-bar-map) - (mouse-menu-major-mode-map))))) -@end smallexample +menu. If you prefer @kbd{mouse-3} in Emacs to bring up such a context +menu instead of running the @code{mouse-save-then-kill} command, +enable @code{context-menu-mode} and customize the variable +@code{context-menu-functions}. @node Mode Line Mouse @section Mode Line Mouse Commands @@ -480,9 +475,10 @@ frame. This runs @code{find-file-read-only-other-frame}. @xref{Visiting}. @item C-x 5 5 -A more general prefix command affects the buffer displayed by the next -command invoked immediately after this prefix command. It requests -the buffer of the next command to be displayed in another frame. +A more general prefix command that affects the buffer displayed by the +next command invoked immediately after this prefix command +(@code{other-frame-prefix}). It requests the buffer of the next +command to be displayed in another frame. @end table You can control the appearance and behavior of the newly-created @@ -614,7 +610,10 @@ If you are running Emacs on the GNOME desktop, you can tell Emacs to use the default system font by setting the variable @code{font-use-system-font} to @code{t} (the default is @code{nil}). For this to work, Emacs must have been compiled with support for -Gsettings (or the older Gconf). +Gsettings (or the older Gconf). (To be specific, the Gsettings +configuration names used are +@samp{org.gnome.desktop.interface monospace-font-name} and +@samp{org.gnome.desktop.interface font-name}.) @item Use the command line option @samp{-fn} (or @samp{--font}). @xref{Font @@ -1214,7 +1213,9 @@ the use of menu bars at startup, customize the variable terminals, where this makes one additional line available for text. If the menu bar is off, you can still pop up a menu of its contents with @kbd{C-mouse-3} on a display which supports pop-up menus. -@xref{Menu Mouse Clicks}. +Or you can enable @code{context-menu-mode} and customize the variable +@code{context-menu-functions} to pop up a context menu with +@kbd{mouse-3}. @xref{Menu Mouse Clicks}. @xref{Menu Bar}, for information on how to invoke commands with the menu bar. @xref{X Resources}, for how to customize the menu bar diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi index 81cdeb4be54..0caab681d34 100644 --- a/doc/emacs/help.texi +++ b/doc/emacs/help.texi @@ -107,8 +107,8 @@ Display the @file{*Messages*} buffer (@code{view-echo-area-messages}). @xref{Misc Help}. @item C-h f @var{function} @key{RET} Display documentation on the Lisp function named @var{function} -(@code{describe-function}). Since commands are Lisp functions, -this works for commands too. @xref{Name Help}. +(@code{describe-function}). Since commands are Lisp functions, this +works for commands too, but you can also use @code{C-h x}. @xref{Name Help}. @item C-h h Display the @file{HELLO} file, which shows examples of various character sets. @@ -154,6 +154,9 @@ Display the documentation of the Lisp variable @var{var} @item C-h w @var{command} @key{RET} Show which keys run the command named @var{command} (@code{where-is}). @xref{Key Help}. +@item C-h x @var{command} @key{RET} +Display documentation on the named @var{command} +(@code{describe-command}). @xref{Name Help}. @item C-h C @var{coding} @key{RET} Describe the coding system @var{coding} (@code{describe-coding-system}). @xref{Coding Systems}. @@ -233,31 +236,31 @@ the button. @node Name Help @section Help by Command or Variable Name -@kindex C-h f -@findex describe-function - @kbd{C-h f @var{function} @key{RET}} (@code{describe-function}) -displays the documentation of Lisp function @var{function}, in a -window. Since commands are Lisp functions, you can use this method to -view the documentation of any command whose name you know. For -example, +@kindex C-h x +@findex describe-command + @kbd{C-h x @var{command} @key{RET}} (@code{describe-command}) +displays the documentation of the named @var{command}, in a +window. For example, @example -C-h f auto-fill-mode @key{RET} +C-h x auto-fill-mode @key{RET} @end example @noindent -displays the documentation of @code{auto-fill-mode}. This is the only -way to get the documentation of a command that is not bound to any key +displays the documentation of @code{auto-fill-mode}. This is how you +would get the documentation of a command that is not bound to any key (one which you would normally run using @kbd{M-x}). - @kbd{C-h f} is also useful for Lisp functions that you use in a Lisp -program. For example, if you have just written the expression +@kindex C-h f +@findex describe-function + @kbd{C-h f @var{function} @key{RET}} (@code{describe-function}) +displays the documentation of Lisp @var{function}. This command is +intended for Lisp functions that you use in a Lisp program. For +example, if you have just written the expression @code{(make-vector len)} and want to check that you are using -@code{make-vector} properly, type @kbd{C-h f make-vector @key{RET}}. -Because @kbd{C-h f} allows all function names, not just command names, -you may find that some of your favorite completion abbreviations that -work in @kbd{M-x} don't work in @kbd{C-h f}. An abbreviation that is -unique among command names may not be unique among all function names. +@code{make-vector} properly, type @w{@kbd{C-h f make-vector @key{RET}}}. +Additionally, since all commands are Lisp functions, you can also use +this command to view the documentation of any command. If you type @kbd{C-h f @key{RET}}, it describes the function called by the innermost Lisp expression in the buffer around point, @@ -265,7 +268,7 @@ by the innermost Lisp expression in the buffer around point, (That name appears as the default while you enter the argument.) For example, if point is located following the text @samp{(make-vector (car x)}, the innermost list containing point is the one that starts -with @samp{(make-vector}, so @kbd{C-h f @key{RET}} describes the +with @samp{(make-vector}, so @w{@kbd{C-h f @key{RET}}} describes the function @code{make-vector}. @kbd{C-h f} is also useful just to verify that you spelled a @@ -448,6 +451,13 @@ Go forward to the next help topic (@code{help-go-forward}). @item C-c C-b @itemx l Go back to the previous help topic (@code{help-go-back}). +@item s +View the source of the current help topic (if any) +(@code{help-view-source}). +@item i +Look up the current topic in the manual(s) (@code{help-goto-info}). +@item c +Customize the variable or the face (@code{help-customize}). @end table @cindex hyperlink @@ -619,13 +629,14 @@ Emacs Lisp Reference Manual}). @findex describe-prefix-bindings You can get a list of subcommands for a particular prefix key by -typing @kbd{C-h}, @kbd{?}, or @key{F1} +typing @kbd{C-h}, @kbd{?}, or @key{f1} (@code{describe-prefix-bindings}) after the prefix key. (There are a few prefix keys for which not all of these keys work---those that provide their own bindings for that key. One of these prefix keys -is @key{ESC}, because @kbd{@key{ESC} C-h} is actually @kbd{C-M-h}, -which marks a defun. However, @w{@kbd{@key{ESC} @key{F1}}} and -@w{@kbd{@key{ESC} ?}} work fine.) +is @key{ESC}, because @kbd{@key{ESC} C-h} and @kbd{@key{ESC} ?} are +actually @kbd{C-M-h} (@code{mark-defun}) and @kbd{M-?} +(@code{xref-find-references}), respectively. However, +@w{@kbd{@key{ESC} @key{f1}}} works fine.) @findex describe-keymap Finally, @kbd{M-x describe-keymap} prompts for the name of a keymap, diff --git a/doc/emacs/killing.texi b/doc/emacs/killing.texi index 8434040bcea..6e4fd77e8b9 100644 --- a/doc/emacs/killing.texi +++ b/doc/emacs/killing.texi @@ -269,6 +269,21 @@ happens. But if you set the variable @code{kill-read-only-ok} to a non-@code{nil} value, they just print a message in the echo area to explain why the text has not been erased. +@vindex kill-transform-function + Before saving the kill to the kill ring, you can transform the +string using @code{kill-transform-function}. It's called with the +string to be killed, and it should return the string you want to be +saved. It can also return @code{nil}, in which case the string won't +be saved to the kill ring. For instance, if you never want to save +a pure white space string to the kill ring, you can say: + +@lisp +(setq kill-transform-function + (lambda (string) + (and (not (string-blank-p string)) + string))) +@end lisp + @vindex kill-do-not-save-duplicates If you change the variable @code{kill-do-not-save-duplicates} to a non-@code{nil} value, identical subsequent kills yield a single @@ -289,8 +304,9 @@ way to move or copy text is to kill it and then yank it elsewhere. @item C-y Yank the last kill into the buffer, at point (@code{yank}). @item M-y -Replace the text just yanked with an earlier batch of killed text -(@code{yank-pop}). @xref{Earlier Kills}. +Either replace the text just yanked with an earlier batch of killed +text (@code{yank-pop}), or allow to select from the list of +previously-killed batches of text. @xref{Earlier Kills}. @item C-M-w Cause the following command, if it is a kill command, to append to the previous kill (@code{append-next-kill}). @xref{Appending Kills}. @@ -310,13 +326,13 @@ the end. Using any other prefix argument specifies an earlier kill; e.g., @kbd{C-u 4 C-y} reinserts the fourth most recent kill. @xref{Earlier Kills}. - On graphical displays, @kbd{C-y} first checks if another application -has placed any text in the system clipboard more recently than the -last Emacs kill. If so, it inserts the clipboard's text instead. -Thus, Emacs effectively treats ``cut'' or ``copy'' clipboard -operations performed in other applications like Emacs kills, except -that they are not recorded in the kill ring. @xref{Cut and Paste}, -for details. + On graphical displays and on capable text-mode displays, @kbd{C-y} +first checks if another application has placed any text in the system +clipboard more recently than the last Emacs kill. If so, it inserts +the clipboard's text instead. Thus, Emacs effectively treats ``cut'' +or ``copy'' clipboard operations performed in other applications like +Emacs kills, except that they are not recorded in the kill ring. +@xref{Cut and Paste}, for details. @menu * Kill Ring:: Where killed text is stored. @@ -354,7 +370,7 @@ with @kbd{C-h v kill-ring}. @kbd{C-y} to yank text that is no longer the most recent kill. This is useful if you remember which kill ring entry you want. If you don't, you can use the @kbd{M-y} (@code{yank-pop}) command to cycle -through the possibilities. +through the possibilities or to select one of the earlier kills. @kindex M-y @findex yank-pop @@ -363,45 +379,64 @@ that was yanked and replaces it with the text from an earlier kill. So, to recover the text of the next-to-the-last kill, first use @kbd{C-y} to yank the last kill, and then use @kbd{M-y} to replace it with the previous kill. This works only after a @kbd{C-y} -or another @kbd{M-y}. - - You can understand @kbd{M-y} in terms of a last-yank pointer which -points at an entry in the kill ring. Each time you kill, the last-yank -pointer moves to the newly made entry at the front of the ring. -@kbd{C-y} yanks the entry which the last-yank pointer points to. -@kbd{M-y} moves the last-yank pointer to a different entry, and the -text in the buffer changes to match. Enough @kbd{M-y} commands can move -the pointer to any entry in the ring, so you can get any entry into the -buffer. Eventually the pointer reaches the end of the ring; the next -@kbd{M-y} loops back around to the first entry again. +or another @kbd{M-y}. (If @kbd{M-y} is invoked after some other +command, it works differently, see below.) + + You can understand this operation mode of @kbd{M-y} in terms of a +last-yank pointer which points at an entry in the kill ring. Each +time you kill, the last-yank pointer moves to the newly made entry at +the front of the ring. @kbd{C-y} yanks the entry which the last-yank +pointer points to. @kbd{M-y} after a @kbd{C-y} or another @kbd{M-y} +moves the last-yank pointer to the previous entry, and the text in the +buffer changes to match. Enough @kbd{M-y} commands one after another +can move the pointer to any entry in the ring, so you can get any +entry into the buffer. Eventually the pointer reaches the end of the +ring; the next @kbd{M-y} loops back around to the first entry again. @kbd{M-y} moves the last-yank pointer around the ring, but it does not change the order of the entries in the ring, which always runs from the most recent kill at the front to the oldest one still remembered. - @kbd{M-y} can take a numeric argument, which tells it how many entries -to advance the last-yank pointer by. A negative argument moves the -pointer toward the front of the ring; from the front of the ring, it -moves around to the last entry and continues forward from there. + When used after @kbd{C-y} or @kbd{M-y}, @kbd{M-y} can take a numeric +argument, which tells it how many entries to advance the last-yank +pointer by. A negative argument moves the pointer toward the front of +the ring; from the front of the ring, it moves around to the last +entry and continues forward from there. - Once the text you are looking for is brought into the buffer, you can -stop doing @kbd{M-y} commands and it will stay there. It's just a copy -of the kill ring entry, so editing it in the buffer does not change -what's in the ring. As long as no new killing is done, the last-yank -pointer remains at the same place in the kill ring, so repeating -@kbd{C-y} will yank another copy of the same previous kill. + Once the text you are looking for is brought into the buffer, you +can stop doing @kbd{M-y} commands and the last yanked text will stay +there. It's just a copy of the kill ring entry, so editing it in the +buffer does not change what's in the ring. As long as no new killing +is done, the last-yank pointer remains at the same place in the kill +ring, so repeating @kbd{C-y} will yank another copy of the same +previous kill. When you call @kbd{C-y} with a numeric argument, that also sets the last-yank pointer to the entry that it yanks. - Alternatively, when the previous command was not a yank command, -@kbd{M-y} activates the minibuffer where you can browse previous kills -using the minibuffer history commands (@pxref{Minibuffer History}), or -you can use completion commands (@pxref{Completion}) on a list of -previously killed blocks of text from the kill ring. Exiting the -minibuffer will insert the selected text to the buffer. With a plain -prefix argument (@kbd{C-u M-y}), this command leaves the cursor in -front of the inserted text, and sets the mark at the end. + You can also invoke @kbd{M-y} after a command that is not a yank +command. In that case, @kbd{M-y} prompts you in the minibuffer for +one of the previous kills. You can use the minibuffer history +commands (@pxref{Minibuffer History}) to navigate or search through +the entries in the kill ring until you find the one you want to +reinsert. Or you can use completion commands (@pxref{Completion +Commands}) to complete on an entry from the list of entries in the +kill ring or pop up the @file{*Completions*} buffer with the candidate +entries from which you can choose. After selecting the kill-ring +entry, you can optionally edit it in the minibuffer. Finally, type +@kbd{RET} to exit the minibuffer and insert the text of the selected +kill-ring entry. Like in case of @kbd{M-y} after another yank +command, the last-yank pointer is left pointing at the text you just +yanked, whether it is one of the previous kills or an entry from the +kill-ring that you edited before inserting it. (In the latter case, +the edited entry is added to the front of the kill-ring.) So here, +too, typing @kbd{C-y} will yank another copy of the text just +inserted. + + When invoked with a plain prefix argument (@kbd{C-u M-y}) after a +command that is not a yank command, @kbd{M-y} leaves the cursor in +front of the inserted text, and sets the mark at the end, like +@kbd{C-y} does. @node Appending Kills @subsection Appending Kills @@ -502,11 +537,14 @@ clipboard. @vindex save-interprogram-paste-before-kill When an Emacs kill command puts text in the clipboard, the existing -clipboard contents are normally lost. Optionally, you can change -@code{save-interprogram-paste-before-kill} to @code{t}. Then Emacs -will first save the clipboard to its kill ring, preventing you from -losing the old clipboard data---at the risk of high memory consumption -if that data turns out to be large. +clipboard contents are normally lost. Optionally, Emacs can save the +existing clipboard contents to the kill ring, preventing you from +losing the old clipboard data. If +@code{save-interprogram-paste-before-kill} changed to a number, then +this data is copied over if it's smaller (in characters) than this +number. If this variable is any other non-@code{nil} value, it's +always copied over---at the risk of high memory consumption if that +data turns out to be large. Yank commands, such as @kbd{C-y} (@code{yank}), also use the clipboard. If another application ``owns'' the clipboard---i.e., if diff --git a/doc/emacs/m-x.texi b/doc/emacs/m-x.texi index 865220fb218..d35a8351541 100644 --- a/doc/emacs/m-x.texi +++ b/doc/emacs/m-x.texi @@ -46,9 +46,25 @@ from running the command by name. @cindex obsolete command When @kbd{M-x} completes on commands, it ignores the commands that are declared @dfn{obsolete}; for these, you will have to type their -full name. Obsolete commands are those for which newer, better +full name. (Obsolete commands are those for which newer, better alternatives exist, and which are slated for removal in some future -Emacs release. +Emacs release.) + +@vindex read-extended-command-predicate + In addition, @kbd{M-x} completion can exclude commands that are not +relevant to, and generally cannot work with, the current buffer's +major mode (@pxref{Major Modes}) and minor modes (@pxref{Minor +Modes}). By default, no commands are excluded, but you can customize +the option @code{read-extended-command-predicate} to exclude those +irrelevant commands from completion results. + +@kindex M-S-x + Conversely, Emacs can exclude all commands except those that are +particularly relevant to the current buffer. The @kbd{M-S-x} (that's +``meta shift x'') command works just like @kbd{M-x}, but instead of +listing all (or most) of the commands Emacs knows about, it will only +list the commands that have been marked as ``belonging'' to the +current major mode, or any enabled minor modes. To cancel the @kbd{M-x} and not run a command, type @kbd{C-g} instead of entering the command name. This takes you back to command level. diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index bc276c49046..3205e6dbdf7 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -32,6 +32,10 @@ symbols (a.k.a.@: ``identifiers'') and their references. A mode for merging changes to program sources made on separate branches of development. @end ifnottex + +@item +A minor-mode for highlighting bug references and visiting the +referenced bug reports in their issue tracker. @end itemize If you are maintaining a large Lisp program, then in addition to the @@ -49,6 +53,8 @@ Lisp Regression Testing}). @ifnottex * Emerge:: A convenient way of merging two versions of a program. @end ifnottex +* Bug Reference:: Highlighting references to bug reports and browsing + them in their issue trackers. @end menu @node Version Control @@ -1611,6 +1617,10 @@ branch ID for a branch starting at the current revision. For example, if the current revision is 2.5, the branch ID should be 2.5.1, 2.5.2, and so on, depending on the number of existing branches at that point. + This procedure will not work for distributed version control systems +like git or Mercurial. For those systems you should use the prefix +argument to @code{vc-create-tag} (@kbd{C-u C-x v s}) instead. + To create a new branch at an older revision (one that is no longer the head of a branch), first select that revision (@pxref{Switching Branches}). Your procedure will then differ depending on whether you @@ -1660,6 +1670,7 @@ the project back-end. For example, the VC back-end doesn't consider * Project File Commands:: Commands for handling project files. * Project Buffer Commands:: Commands for handling project buffers. * Switching Projects:: Switching between projects. +* Managing Projects:: Managing the project list file. @end menu @node Project File Commands @@ -1839,6 +1850,21 @@ in the menu, and which key invokes each command. records the list of known projects. It defaults to the file @file{projects} in @code{user-emacs-directory} (@pxref{Find Init}). +@node Managing Projects +@subsection Managing the Project List File + +@table @kbd +@item M-x project-remove-known-project +Remove a known project from the @code{project-list-file}. +@end table + +@findex project-remove-known-project + Normally Emacs automatically adds and removes projects to and from the +@code{project-list-file}, but sometimes you may want to manually edit +the available projects. @kbd{M-x project-remove-known-project} +prompts you to choose one of the available projects, and then removes +it from the file. + @node Change Log @section Change Logs @@ -2193,7 +2219,8 @@ the special XREF mode: @table @kbd @item @key{RET} @itemx mouse-2 -Display the reference on the current line. +Display the reference on the current line (@code{xref-goto-xref}). +With prefix argument, also bury the @file{*xref*} buffer. @item n @itemx . @@ -2222,11 +2249,6 @@ display it in the other window (@code{xref-prev-group}). Display the reference on the current line in the other window (@code{xref-show-location-at-point}). -@item @key{TAB} -@findex xref-quit-and-goto-xref -Display the reference on the current line and bury the @file{*xref*} -buffer (@code{xref-quit-and-goto-xref}). - @item r @var{pattern} @key{RET} @var{replacement} @key{RET} Perform interactive query-replace on references that match @var{pattern} (@code{xref-query-replace-in-results}), replacing @@ -2641,6 +2663,10 @@ generate a tag. @item In Ruby code, @code{def} or @code{class} or @code{module} at the beginning of a line generate a tag. Constants also generate tags. + +@item +In Rust code, tags anything defined with @code{fn}, @code{enum}, +@code{struct} or @code{macro_rules!}. @end itemize You can also generate tags based on regexp matching (@pxref{Etags @@ -3033,3 +3059,172 @@ the target should be built. @ifnottex @include emerge-xtra.texi @end ifnottex + + +@node Bug Reference +@section Bug Reference +@cindex bug reference + +Most projects with a certain amount of users track bug reports in some +issue tracking software which assigns each report a unique and short +number or identifier. Those are used to reference a given bug, e.g., +in a source code comment above the code fixing some bug, in +documentation files, or in discussions on some mailinglist or IRC +channel. + +@findex bug-reference-mode +@findex bug-reference-prog-mode + The minor modes @code{bug-reference-mode} and +@code{bug-reference-prog-mode} highlight such bug references and make +it possible to follow them to the corresponding bug report on the +project's issue tracker. @code{bug-reference-prog-mode} is a variant +of @code{bug-reference-mode} which highlights bug references only +inside source code comments and strings. + +@vindex bug-reference-bug-regexp +@vindex bug-reference-url-format + For its working, bug reference mode needs to know the syntax of bug +references (@code{bug-reference-bug-regexp}), and the URL of the +tracker where bug reports can be looked up +(@code{bug-reference-url-format}). Since those are typically +different from project to project, it makes sense to specify them in +@pxref{Directory Variables} or @pxref{File Variables}. + +For example, let's assume in our project, we usually write references +to bug reports as bug#1234, or Bug-1234 and that this bug's page on +the issue tracker is @url{https://project.org/issues/1234}, then +these local variables section would do. + +@smallexample +;; Local Variables: +;; bug-reference-bug-regexp: "\\([Bb]ug[#-]\\)\\([0-9]+\\)" +;; bug-reference-url-format: "https://project.org/issues/%s" +;; End: +@end smallexample + +The string captured by the second regexp group in +@code{bug-reference-bug-regexp} is used to replace the @code{%s} +template in the @code{bug-reference-url-format}. + +Note that @code{bug-reference-url-format} may also be a function in +order to cater for more complex scenarios, e.g., when the part before +the actual bug number has to be used to distinguish between issues and +merge requests where each of them has a different URL. + + +@heading Automatic Setup + +@vindex bug-reference-auto-setup-functions +If @code{bug-reference-mode} is activated, +@code{bug-reference-mode-hook} has been run and still +@code{bug-reference-bug-regexp}, and @code{bug-reference-url-format} +aren't both set, it'll try to setup suitable values for these two +variables itself by calling the functions in +@code{bug-reference-auto-setup-functions} one after the other until +one is able to set the variables. + +@vindex bug-reference-setup-from-vc-alist +@vindex bug-reference-setup-from-mail-alist +@vindex bug-reference-setup-from-irc-alist + Right now, there are three types of setup functions. +@enumerate +@item +Setup for version-controlled files configurable by the variable +@code{bug-reference-setup-from-vc-alist}. The default is able to +setup GNU projects where @url{https://debbugs.gnu.org} is used as +issue tracker and issues are usually referenced as @code{bug#13} (but +many different notations are considered, too), Sourcehut projects +where issues are referenced using the notation @code{#17}, Codeberg +and Github projects where both bugs and pull requests are referenced +using the same notation, and GitLab projects where bugs are referenced +with @code{#17}, too, but merge requests use the @code{!18} notation. + +@item +Setup for email guessing from mail folder/mbox names, and mail header +values configurable by the variable +@code{bug-reference-setup-from-mail-alist}. The built-in news- and +mailreader @ref{Gnus} and @ref{Rmail} are supported. + +@item +Setup for IRC channels configurable by the variable +@code{bug-reference-setup-from-irc-alist}. The built-in IRC clients +Rcirc, @xref{Top, Rcirc,, rcirc, The Rcirc Manual}, and ERC, +@xref{Top, ERC,, erc, The ERC Manual}, are supported. +@end enumerate + +For almost all of those modes, it's enough to simply enable +@code{bug-reference-mode}, only Rmail requires a slightly different +setup. + +@smallexample +;; Use VC-based setup if file is under version control. +(add-hook 'prog-mode-hook #'bug-reference-prog-mode) + +;; Gnus (summary & article buffers) +(add-hook 'gnus-mode-hook #'bug-reference-mode) + +;; Rmail +(add-hook 'rmail-show-message-hook #'bug-reference-mode-force-auto-setup) + +;; Rcirc +(add-hook 'rcirc-mode-hook #'bug-reference-mode) + +;; ERC +(add-hook 'erc-mode-hook #'bug-reference-mode) +@end smallexample + +In the Rmail case, instead of the mode hook, the +@code{rmail-show-message-hook} has to be used in combination with the +function @code{bug-reference-mode-force-auto-setup} which activates +@code{bug-reference-mode} and forces auto-setup. The reason is that +with Rmail all messages reside in the same buffer but the setup needs +to be performed whenever another messages is displayed. + + +@heading Adding support for third-party packages + +@vindex bug-reference-auto-setup-functions +Adding support for bug-reference' auto-setup is usually quite +straight-forward: write a setup function of zero arguments which +gathers the required information (e.g., List-Id/To/From/Cc mail header +values in the case of a MUA), and then calls one of the following +helper functions: +@itemize @bullet +@item +@code{bug-reference-maybe-setup-from-vc} which does the setup +according to @code{bug-reference-setup-from-vc-alist}, + +@item +@code{bug-reference-maybe-setup-from-mail} which does the setup +according to @code{bug-reference-setup-from-mail-alist}, + +@item +and @code{bug-reference-maybe-setup-from-irc} which does the setup +according to @code{bug-reference-setup-from-irc-alist}. +@end itemize +A setup function should return non-nil if it could setup bug-reference +mode which is the case if the last thing the function does is calling +one of the helper functions above. + +Finally, the setup function has to be added to +@code{bug-reference-auto-setup-functions}. + +Note that these auto-setup functions should check as a first step if +they are applicable, e.g., by checking the @code{major-mode} value. + + +@heading Integration with the debbugs package + +@findex debbugs-browse-mode +If your project's issues are tracked on the server +@url{https://debbugs.gnu.org}, you can browse and reply to reports +directly in Emacs using the @code{debbugs} package, which can be +downloaded via the Package Menu (@pxref{Packages}). This package adds +the minor mode @code{debbugs-browse-mode}, which can be activated on +top of @code{bug-reference-mode} and @code{bug-reference-prog-mode} as +follows: + +@smallexample +(add-hook 'bug-reference-mode-hook 'debbugs-browse-mode) +(add-hook 'bug-reference-prog-mode-hook 'debbugs-browse-mode) +@end smallexample diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi index f81e64bdf9b..6dcee3fa824 100644 --- a/doc/emacs/mini.texi +++ b/doc/emacs/mini.texi @@ -64,10 +64,10 @@ minibuffer-electric-default-mode}. Since the minibuffer appears in the echo area, it can conflict with other uses of the echo area. If an error message or an informative -message is emitted while the minibuffer is active, the message hides -the minibuffer for a few seconds, or until you type something; then -the minibuffer comes back. While the minibuffer is in use, Emacs does -not echo keystrokes. +message is emitted while the minibuffer is active, the message is +displayed in brackets after the minibuffer text for a few seconds, or +until you type something; then the message disappears. While the +minibuffer is in use, Emacs does not echo keystrokes. @vindex minibuffer-follows-selected-frame While using the minibuffer, you can switch to a different frame, @@ -82,7 +82,9 @@ after a recursive minibuffer has been opened in the current command (@pxref{Recursive Mini,,, elisp}). This option is mainly to retain (approximately) the behavior prior to Emacs 28.1. Note that the effect of the command, when you finally finish using the minibuffer, -always takes place in the frame where you first opened it. +always takes place in the frame where you first opened it. The sole +exception is that when that frame no longer exists, the action takes +place in the currently selected frame. @node Minibuffer File @section Minibuffers for File Names @@ -245,6 +247,9 @@ You might need also to enable @code{minibuffer-depth-indicate-mode} to show the current recursion depth in the minibuffer prompt on recursive use of the minibuffer. + When active, the minibuffer is usually in @code{minibuffer-mode}. +This is an internal Emacs mode without any special features. + @findex minibuffer-inactive-mode When not active, the minibuffer is in @code{minibuffer-inactive-mode}, and clicking @kbd{mouse-1} there shows the @file{*Messages*} buffer. @@ -369,9 +374,9 @@ used with the completion list: @itemx @key{prior} Typing @kbd{M-v}, while in the minibuffer, selects the window showing the completion list (@code{switch-to-completions}). This paves the -way for using the commands below. @key{PageUp} or @key{prior} does -the same. You can also select the window in other ways -(@pxref{Windows}). +way for using the commands below. @key{PageUp}, @key{prior} and +@kbd{M-g M-c} does the same. You can also select the window in other +ways (@pxref{Windows}). @findex choose-completion @item @key{RET} @@ -383,12 +388,14 @@ point (@code{choose-completion}). @findex next-completion @item @key{TAB} @item @key{RIGHT} +@item @key{n} While in the completion list buffer, these keys move point to the following completion alternative (@code{next-completion}). @findex previous-completion @item @key{S-TAB} @item @key{LEFT} +@item @key{p} While in the completion list buffer, these keys move point to the previous completion alternative (@code{previous-completion}). @@ -623,6 +630,14 @@ in a cyclic manner. If you give @code{completion-cycle-threshold} a numeric value @var{n}, completion commands switch to this cycling behavior only when there are @var{n} or fewer alternatives. +@vindex completions-format + When displaying completions, Emacs will normally pop up a new buffer +to display the completions. The completions will (by default) be +sorted in columns horizontally in alphabetical order, but this can be +changed by changing the @code{completions-format} user option. If +@code{vertical}, sort the completions vertically in columns instead, +and if @code{one-column}, just use a single column. + @node Minibuffer History @section Minibuffer History @cindex minibuffer history @@ -800,6 +815,7 @@ can re-execute a command by calling @code{eval} with the @node Passwords @section Entering passwords +@cindex entering passwords Sometimes, you may need to enter a password into Emacs. For instance, when you tell Emacs to visit a file on another machine via a network @@ -810,7 +826,7 @@ access to the machine (@pxref{Remote Files}). displays a prompt in the echo area (such as @samp{Password: }); after you type the required password, press @key{RET} to submit it. To prevent others from seeing your password, every character you type is -displayed as a dot (@samp{.}) instead of its usual form. +displayed as an asterisk (@samp{*}) instead of its usual form. Most of the features and commands associated with the minibuffer @emph{cannot} be used when entering a password. There is no history diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi index fbb8122a1b8..528cfa94c66 100644 --- a/doc/emacs/misc.texi +++ b/doc/emacs/misc.texi @@ -163,14 +163,13 @@ List killed groups (@code{gnus-group-list-killed}). List zombie groups (@code{gnus-group-list-zombies}). @kindex u @r{(Gnus Group mode)} -@findex gnus-group-unsubscribe-current-group +@findex gnus-group-toggle-subscription @cindex subscribe groups @cindex unsubscribe groups @item u Toggle the subscription status of the group -(@code{gnus-group-unsubscribe-current-group}) on the current line -(i.e., turn a subscribed group into an unsubscribed group, or vice -versa). Invoking this on a killed or zombie group turns it into an +(@code{gnus-group-toggle-subscription}) on the current line. +Invoking this on a killed or zombie group turns it into an unsubscribed group. @kindex C-k @r{(Gnus Group mode)} @@ -1021,7 +1020,10 @@ pending in the shell buffer and not yet sent. @findex comint-delete-output Delete the last batch of output from a shell command (@code{comint-delete-output}). This is useful if a shell command spews -out lots of output that just gets in the way. +out lots of output that just gets in the way. With a prefix argument, +this command saves the deleted text in the @code{kill-ring} +(@pxref{Kill Ring}), so that you could later yank it (@pxref{Yanking}) +elsewhere. @item C-c C-s @kindex C-c C-s @r{(Shell mode)} @@ -1757,6 +1759,13 @@ expression @code{(+ 1 2)} on the @samp{foo} server, and returns @code{3}. (If there is no server with that name, an error is signaled.) Currently, this feature is mainly useful for developers. + If your operating system’s desktop environment is +@url{https://www.freedesktop.org/wiki/Specifications/,,freedesktop.org-compatible} +(which is true of most GNU/Linux and other recent Unix-like GUIs), you +may use the @samp{Emacs (Client)} menu entry to connect to an Emacs +server with @command{emacsclient}. The daemon starts if not +already running. + @menu * TCP Emacs server:: Listening to a TCP socket. * Invoking emacsclient:: Connecting to the Emacs server. @@ -1864,6 +1873,12 @@ it to exit. Programs that use @env{EDITOR} usually wait for the editor---in this case @command{emacsclient}---to exit before doing something else. +@findex server-edit-abort + If you want to abandon the edit instead, use the @w{@kbd{M-x +server-edit-abort}} command. This sends a message back to the +@command{emacsclient} program, telling it to exit with abnormal exit +status, and doesn't save any buffers. + You can also call @command{emacsclient} with multiple file name arguments: @samp{emacsclient @var{file1} @var{file2} ...} tells the Emacs server to visit @var{file1}, @var{file2}, and so forth. Emacs @@ -2018,7 +2033,7 @@ evaluation performed is for side-effect rather than result. Connect to the Emacs server named @var{server-name}. (This option is not supported on MS-Windows.) The server name is given by the variable @code{server-name} on the Emacs server. If this option is -omitted, @command{emacsclient} connects to the first server it finds. +omitted, @command{emacsclient} connects to the default socket. If you set @code{server-name} of the Emacs server to an absolute file name, give the same absolute file name as @var{server-name} to this option to instruct @command{emacsclient} to connect to that server. @@ -2576,6 +2591,17 @@ Other Hexl commands let you insert strings (sequences) of binary bytes, move by @code{short}s or @code{int}s, etc.; type @kbd{C-h a hexl-@key{RET}} for details. + Hexl mode can also be used for editing text files. This could come +in handy if the text file includes unusual characters or uses unusual +encoding (@pxref{Coding Systems}). For this purpose, Hexl commands +that insert bytes can also insert @acronym{ASCII} and +non-@acronym{ASCII} characters, including multibyte characters. To +edit a text file with Hexl, visit the file as usual, and then type +@w{@kbd{M-x hexl-mode @key{RET}}} to switch to Hexl mode. You can now +insert text characters by typing them. However, inserting multibyte +characters requires special care, to avoid the danger of creating +invalid multibyte sequences: you should start typing such characters +when point is on the first byte of a multibyte sequence in the file. @node Saving Emacs Sessions @section Saving Emacs Sessions @@ -2947,6 +2973,15 @@ URLs. For more information, view the package commentary by typing @kbd{C-h P browse-url @key{RET}}. +@findex url-handler-mode + Emacs also has a minor mode that has some support for handling +@acronym{URL}s as if they were files. @code{url-handler-mode} is a +global minor mode that affects most of the Emacs commands and +primitives that deal with file names. After switching on this mode, +you can say, for instance, @kbd{C-x C-f https://www.gnu.org/ RET} to +see the @acronym{HTML} for that web page, and you can then edit it and +save it to a local file, for instance. + @node Goto Address mode @subsection Activating URLs @findex goto-address-mode diff --git a/doc/emacs/modes.texi b/doc/emacs/modes.texi index cc25d3e1e33..9014221edff 100644 --- a/doc/emacs/modes.texi +++ b/doc/emacs/modes.texi @@ -357,8 +357,12 @@ preferences. If you personally want to use a minor mode for a particular file type, it is better to enable the minor mode via a major mode hook (@pxref{Major Modes}). + Second, Emacs checks whether the file's extension matches an entry +in any directory-local @code{auto-mode-alist}. These are found using +the @file{.dir-locals.el} facility (@pxref{Directory Variables}). + @vindex interpreter-mode-alist - Second, if there is no file variable specifying a major mode, Emacs + Third, if there is no file variable specifying a major mode, Emacs checks whether the file's contents begin with @samp{#!}. If so, that indicates that the file can serve as an executable shell command, which works by running an interpreter named on the file's first line @@ -376,7 +380,7 @@ same is true for man pages which start with the magic string @samp{'\"} to specify a list of troff preprocessors. @vindex magic-mode-alist - Third, Emacs tries to determine the major mode by looking at the + Fourth, Emacs tries to determine the major mode by looking at the text at the start of the buffer, based on the variable @code{magic-mode-alist}. By default, this variable is @code{nil} (an empty list), so Emacs skips this step; however, you can customize it @@ -404,7 +408,7 @@ where @var{match-function} is a Lisp function that is called at the beginning of the buffer; if the function returns non-@code{nil}, Emacs set the major mode with @var{mode-function}. - Fourth---if Emacs still hasn't found a suitable major mode---it + Fifth---if Emacs still hasn't found a suitable major mode---it looks at the file's name. The correspondence between file names and major modes is controlled by the variable @code{auto-mode-alist}. Its value is a list in which each element has this form, diff --git a/doc/emacs/msdos.texi b/doc/emacs/msdos.texi index 4b58f6aa2f7..33d389acd50 100644 --- a/doc/emacs/msdos.texi +++ b/doc/emacs/msdos.texi @@ -549,10 +549,6 @@ meanings by enabling CUA Mode (@pxref{CUA Bindings}). Another optional feature which will make Emacs behave like other Windows applications is Delete Selection mode (@pxref{Using Region}). -@iftex -@inforef{Windows Keyboard, , emacs}, for information about additional -Windows-specific variables in this category. -@end iftex @ifnottex @vindex w32-alt-is-meta @cindex @code{Alt} key (MS-Windows) @@ -1176,11 +1172,6 @@ the default when such software is detected when running Emacs. When this variable is non-@code{nil}, other variables affecting the cursor display have no effect. -@iftex -@inforef{Windows Misc, , emacs}, for information about additional -Windows-specific variables in this category. -@end iftex - @ifnottex @vindex w32-grab-focus-on-raise @cindex frame focus policy, MS-Windows diff --git a/doc/emacs/mule.texi b/doc/emacs/mule.texi index 922eec7426e..22b3677b5b0 100644 --- a/doc/emacs/mule.texi +++ b/doc/emacs/mule.texi @@ -174,8 +174,10 @@ characters in the range @code{#x0080..#x00FF}. @cindex font of character at point @cindex text properties at point @cindex face at point - With a prefix argument (@kbd{C-u C-x =}), this command displays a -detailed description of the character in a window: +@findex describe-char + With a prefix argument (@kbd{C-u C-x =}), this command additionally +calls the command @code{describe-char}, which displays a detailed +description of the character: @itemize @bullet @item diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi index 038a31a35b9..d419a4e24b5 100644 --- a/doc/emacs/package.texi +++ b/doc/emacs/package.texi @@ -126,6 +126,13 @@ line; typing @kbd{x} (see below) will delete the package. @xref{Package Files}, for information about what package deletion entails. +@item w +@kindex w @r{(Package Menu)} +@findex package-browse-url +Open the home page of the package on the current line in a browser +(@code{package-browse-url}). @code{browse-url} is used to open the +browser. + @item ~ @kindex ~ @r{(Package Menu)} @findex package-menu-mark-obsolete-for-deletion @@ -409,12 +416,12 @@ just make some new commands available, while others have more wide-ranging effects on the Emacs session. For such information, consult the package's help buffer. - After a package is installed, it is automatically made available by -Emacs in all subsequent sessions. This happens at startup, before -processing the init file but after processing the early init file -(@pxref{Early Init File}). As an exception, Emacs does not make -packages available at startup if invoked with the @samp{-q} or -@samp{--no-init-file} options (@pxref{Initial Options}). + Installed packages are automatically made available by Emacs in all +subsequent sessions. This happens at startup, before processing the +init file but after processing the early init file (@pxref{Early Init +File}). As an exception, Emacs does not make packages available at +startup if invoked with the @samp{-q} or @samp{--no-init-file} options +(@pxref{Initial Options}). @vindex package-enable-at-startup To keep Emacs from automatically making packages available at @@ -423,6 +430,17 @@ startup, change the variable @code{package-enable-at-startup} to is read before loading the regular init file. Currently this variable cannot be set via Customize. +@findex package-quickstart-refresh +@vindex package-quickstart + If you have many packages installed, you can improve startup times +by setting the user option @code{package-quickstart} to @code{t}. +Setting this option will make Emacs precompute many things instead of +re-computing them on every Emacs startup. However, if you do this, +then you have to manually run the command +@code{package-quickstart-refresh} when the activations need to be +changed, such as when you change the value of +@code{package-load-list}. + @findex package-activate-all If you have set @code{package-enable-at-startup} to @code{nil}, you can still make packages available either during or after startup. To diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi index f3c42bcea7f..a1760ad66ff 100644 --- a/doc/emacs/search.texi +++ b/doc/emacs/search.texi @@ -201,6 +201,14 @@ something before the starting point, type @kbd{C-r} to switch to a backward search, leaving the search string unchanged. Similarly, @kbd{C-s} in a backward search switches to a forward search. +@cindex search, changing direction +@vindex isearch-repeat-on-direction-change + When you change the direction of a search, the first command you +type will, by default, remain on the same match, and the cursor will +move to the other end of the match. To move to another match +immediately, customize the variable +@code{isearch-repeat-on-direction-change} to @code{t}. + @cindex search, wrapping around @cindex search, overwrapped @cindex wrapped search @@ -293,13 +301,11 @@ from point to the @var{n}th occurrence of the specified character. @findex isearch-yank-x-selection Within incremental search, @kbd{C-y} (@code{isearch-yank-kill}) appends the current kill to the search string. @kbd{M-y} -(@code{isearch-yank-pop}), if called after @kbd{C-y}, replaces that -appended text with an earlier kill, similar to the usual @kbd{M-y} -(@code{yank-pop}) command. When @kbd{M-y} is called not after -@kbd{C-y}, then it activates the minibuffer where you can select -a previous kill to append to the search string (@pxref{Earlier -Kills}). Clicking @kbd{mouse-2} in the echo area appends the current -X selection (@pxref{Primary Selection}) to the search string +(@code{isearch-yank-pop}), if called after @kbd{C-y} during +incremental search, replaces that appended text with an earlier kill, +similar to the usual @kbd{M-y} (@code{yank-pop}) command. Clicking +@kbd{mouse-2} in the echo area appends the current X selection +(@pxref{Primary Selection}) to the search string (@code{isearch-yank-x-selection}). @kindex C-M-d @r{(Incremental search)} @@ -1965,6 +1971,17 @@ it never deletes lines that are only partially contained in the region (a newline that ends a line counts as part of that line). If a match is split across lines, this command keeps all those lines. + +@findex kill-matching-lines +@item M-x kill-matching-lines +Like @code{flush-lines}, but also add the matching lines to the kill +ring. The command adds the matching lines to the kill ring as a +single string, including the newlines that separated the lines. + +@findex copy-matching-lines +@item M-x copy-matching-lines +Like @code{kill-matching-lines}, but the matching lines are not +removed from the buffer. @end table @node Search Customizations diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi index 54e16698a74..dc8ca903b72 100644 --- a/doc/emacs/text.texi +++ b/doc/emacs/text.texi @@ -61,7 +61,7 @@ use Picture mode, a special major mode for editing such pictures. @cindex autotyping @cindex automatic typing The automatic typing features may be useful when writing text. -@inforef{Top,The Autotype Manual,autotype}. +@xref{Top, Autotyping, The Autotype Manual, autotype}. @end ifinfo @menu @@ -421,13 +421,12 @@ beginning of a line. @cindex curved quotes @cindex guillemets @findex electric-quote-mode -@c The funny quoting below is to make the printed version look -@c correct. FIXME. + One common way to quote is the typewriter convention, which quotes -using straight apostrophes @t{'like this'} or double-quotes @t{"like +using straight apostrophes @samp{'like this'} or double-quotes @samp{"like this"}. Another common way is the curved quote convention, which uses -left and right single or double quotation marks `@t{like this}' or -``@t{like this}''@footnote{ +left and right single or double quotation marks @t{‘like this’} or +@t{“like this”}@footnote{ The curved single quote characters are U+2018 @sc{left single quotation mark} and U+2019 @sc{right single quotation mark}; the curved double quotes are U+201C @sc{left double quotation mark} and U+201D @sc{right double @@ -445,7 +444,7 @@ default quotes listed above, by customizing the variable @code{electric-quote-chars}, a list of four characters, where the items correspond to the left single quote, the right single quote, the left double quote and the right double quote, respectively, whose -default value is @code{'(?@r{`} ?@r{'} ?@r{``} ?@r{''})}. +default value is @w{@code{'(@w{?}‘ ?’ ?“ ?”)}}. @vindex electric-quote-paragraph @vindex electric-quote-comment @@ -461,7 +460,7 @@ variables. @vindex electric-quote-replace-double You can also set the option @code{electric-quote-replace-double} to -a non-@code{nil} value. Then, typing @t{"} insert an appropriate +a non-@code{nil} value. Then, typing @kbd{"} insert an appropriate curved double quote depending on context: @t{“} at the beginning of the buffer or after a line break, whitespace, opening parenthesis, or quote character, and @t{”} otherwise. @@ -473,7 +472,7 @@ To toggle it globally, type type @kbd{C-q `} or @kbd{C-q '} instead of @kbd{`} or @kbd{'}. To insert a curved quote even when Electric Quote is disabled or inactive, you can type @kbd{C-x 8 [} for @t{‘}, @kbd{C-x 8 ]} for -@t{’}, @kbd{C-x 8 @{} for ``, and @kbd{C-x 8 @}} for ''. +@t{’}, @kbd{C-x 8 @{} for @t{“}, and @kbd{C-x 8 @}} for @t{”}. @xref{Inserting Text}. Note that the value of @code{electric-quote-chars} does not affect these keybindings, they are not keybindings of @code{electric-quote-mode} but bound in @@ -502,8 +501,8 @@ text. @cindex mode, Auto Fill @dfn{Auto Fill} mode is a buffer-local minor mode (@pxref{Minor -Modes}) in which lines are broken automatically at spaces when the -line becomes too wide. +Modes}) in which lines are broken automatically when the line becomes +too wide and you type @kbd{@key{SPC}} or @kbd{@key{RET}}. @table @kbd @item M-x auto-fill-mode @@ -522,12 +521,21 @@ certain major modes, add @code{auto-fill-mode} to the mode hooks (@pxref{Major Modes}). When Auto Fill mode is enabled, the mode indicator @samp{Fill} appears in the mode line (@pxref{Mode Line}). - Auto Fill mode breaks lines automatically at spaces whenever they -get longer than the desired width. This line breaking occurs only -when you type @key{SPC} or @key{RET}. If you wish to insert a space -or newline without permitting line-breaking, type @kbd{C-q @key{SPC}} -or @kbd{C-q C-j} respectively. Also, @kbd{C-o} inserts a newline -without line breaking. + Auto Fill mode breaks lines automatically at the appropriate places +whenever lines get longer than the desired width. This line breaking +occurs only when you type @kbd{@key{SPC}} or @kbd{@key{RET}}. If you +wish to insert a space or newline without permitting line-breaking, +type @kbd{C-q @key{SPC}} or @kbd{C-q C-j} respectively. Also, +@kbd{C-o} inserts a newline without line breaking. + +@cindex kinsoku line-breaking rules + The place where Auto Fill breaks a line depends on the line's +characters. For characters from @acronym{ASCII}, Latin, and most +other scripts Emacs breaks a line on space characters, to keep the +words intact. But for CJK scripts, a line can be broken between any +two characters. (If you load the @file{kinsoku} library, Emacs will +avoid breaking a line between certain pairs of CJK characters, where +special rules prohibit that.) When Auto Fill mode breaks a line, it tries to obey the @dfn{adaptive fill prefix}: if a fill prefix can be deduced from the @@ -549,6 +557,9 @@ described in the next section. (@pxref{Fill Commands}). @end ifnottex + A similar feature that wraps long lines automatically at display +time is Visual Line Mode (@pxref{Visual Line Mode}). + @node Fill Commands @subsection Explicit Fill Commands @@ -561,7 +572,7 @@ Set the fill column (@code{set-fill-column}). Fill each paragraph in the region (@code{fill-region}). @item M-x fill-region-as-paragraph Fill the region, considering it as one paragraph. -@item M-o M-s +@item M-x center-line Center a line. @end table @@ -571,7 +582,11 @@ Center a line. current paragraph. It redistributes the line breaks within the paragraph, and deletes any excess space and tab characters occurring within the paragraph, in such a way that the lines end up fitting -within a certain maximum width. +within a certain maximum width. Like Auto Fill mode, this and other +filling commands usually break lines at space characters, but for CJK +characters these commands can break a line between almost any two +characters, and they can also obey the kinsoku rules. @xref{Auto +Fill}. @findex fill-region Normally, @kbd{M-q} acts on the paragraph where point is, but if @@ -606,10 +621,9 @@ numeric argument, it uses that as the new fill column. With just @kbd{C-u} as argument, it sets @code{fill-column} to the current horizontal position of point. -@kindex M-o M-s @r{(Text mode)} @cindex centering @findex center-line - The command @kbd{M-o M-s} (@code{center-line}) centers the current line + The command @kbd{M-x center-line} centers the current line within the current fill column. With an argument @var{n}, it centers @var{n} lines individually and moves past them. This binding is made by Text mode and is available only in that and related modes @@ -645,8 +659,8 @@ or before @samp{)}, @samp{:} or @samp{?}); and even if preceded by a non-whitespace character). Emacs can display an indicator in the @code{fill-column} position -using the Display fill column indicator mode -(@pxref{Displaying Boundaries, display-fill-column-indicator}). +using the Display fill column indicator mode (@pxref{Displaying +Boundaries, display-fill-column-indicator}). @node Fill Prefix @subsection The Fill Prefix @@ -982,6 +996,13 @@ specific file (@pxref{File Variables}). major mode's special commands. (The variable @code{outline-minor-mode-prefix} controls the prefix used.) +@vindex outline-minor-mode-cycle + If the @code{outline-minor-mode-cycle} user option is +non-@code{nil}, the @kbd{TAB} and @kbd{S-TAB} keys are enabled on the +outline heading lines. @kbd{TAB} cycles hiding, showing the +sub-heading, and showing all for the current section. @kbd{S-TAB} +does the same for the entire buffer. + @menu * Outline Format:: What the text of an outline looks like. * Outline Motion:: Special commands for moving through outlines. diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi index c66deb77487..facbc7f3ed8 100644 --- a/doc/emacs/windows.texi +++ b/doc/emacs/windows.texi @@ -310,6 +310,9 @@ the space that it occupied is given to an adjacent window (but not the minibuffer window, even if that is active at the time). Deleting the window has no effect on the buffer it used to display; the buffer continues to exist, and you can still switch to it with @kbd{C-x b}. +The option @code{delete-window-choose-selected} allows to choose which +window becomes the new selected window instead (@pxref{Deleting +Windows,,, elisp, The Emacs Lisp Reference Manual}). @findex kill-buffer-and-window @kindex C-x 4 0 |