diff options
Diffstat (limited to 'doc')
70 files changed, 1999 insertions, 701 deletions
diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi index abb385f53d5..0b685fafe9c 100644 --- a/doc/emacs/basic.texi +++ b/doc/emacs/basic.texi @@ -115,7 +115,7 @@ just like digits. Case is ignored. starting with @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, @kbd{C-x 8 ]}, @kbd{C-x 8 @{} and @kbd{C-x 8 @}} insert the +Similarly, @w{@kbd{C-x 8 ]}}, @kbd{C-x 8 @{} and @kbd{C-x 8 @}} insert the curved quotes @t{’}, @t{“} and @t{”}, respectively. Also, a working @key{Alt} key acts like @kbd{C-x 8} (unless followed by @key{RET}); e.g., @kbd{A-[} acts like @kbd{C-x 8 [} and inserts @t{‘}. To see diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi index fa60ce26621..7074bd45d71 100644 --- a/doc/emacs/building.texi +++ b/doc/emacs/building.texi @@ -975,9 +975,27 @@ displays the following frame layout: @end group @end smallexample +@findex gdb-save-window-configuration +@findex gdb-load-window-configuration +@vindex gdb-default-window-configuration-file +@vindex gdb-window-configuration-directory + You can customize the window layout based on the one above and save +that layout to a file using @code{gdb-save-window-configuration}. +Then you can later load this layout back using +@code{gdb-load-window-configuration}. (Internally, Emacs uses the +term window configuration instead of window layout.) You can set your +custom layout as the default one used by @code{gdb-many-windows} by +customizing @code{gdb-default-window-configuration-file}. If it is +not an absolute file name, GDB looks under +@code{gdb-window-configuration-directory} for the file. +@code{gdb-window-configuration-directory} defaults to +@code{user-emacs-directory} (@pxref{Find Init}). + + @findex gdb-restore-windows @findex gdb-many-windows - If you ever change the window layout, you can restore the many-windows +@vindex gdb-restore-window-configuration-after-quit + If you ever change the window layout, you can restore the default layout by typing @kbd{M-x gdb-restore-windows}. To toggle between the many windows layout and a simple layout with just the GUD interaction buffer and a source file, type @kbd{M-x gdb-many-windows}. @@ -988,7 +1006,13 @@ interaction buffer and a source file, type @kbd{M-x gdb-many-windows}. of windows on your original frame will not be affected. A separate frame for GDB sessions can come in especially handy if you work on a text-mode terminal, where the screen estate for windows could be at a -premium. +premium. If you choose to start GDB in the same frame, consider +setting @code{gdb-restore-window-configuration-after-quit} to a +non-@code{nil} value. Your original layout will then be restored +after GDB quits. Use @code{t} to always restore; use +@code{if-gdb-many-windows} to restore only when +@code{gdb-many-windows} is non-@code{nil}; use @code{if-gdb-show-main} +to restore only when @code{gdb-show-main} is non-@code{nil}. You may also specify additional GDB-related buffers to display, either in the same frame or a different one. Select the buffers you @@ -998,6 +1022,14 @@ is the relevant buffer type, such as @samp{breakpoints}. You can do the same with the menu bar, with the @samp{GDB-Windows} and @samp{GDB-Frames} sub-menus of the @samp{GUD} menu. +@vindex gdb-max-source-window-count +@vindex gdb-display-source-buffer-action +By default, GDB uses at most one window to display the source file. +You can make it use more windows by customizing +@code{gdb-max-source-window-count}. You can also customize +@code{gdb-display-source-buffer-action} to control how GDB displays +source files. + When you finish debugging, kill the GUD interaction buffer with @kbd{C-x k}, which will also kill all the buffers associated with the session. However you need not do this if, after editing and @@ -1536,13 +1568,6 @@ Automatic loading also occurs when completing names for prefix being completed. To disable this feature, change the variable @code{help-enable-completion-autoload} to @code{nil}. -@vindex load-dangerous-libraries -@cindex Lisp files byte-compiled by XEmacs - By default, Emacs refuses to load compiled Lisp files which were -compiled with XEmacs, a modified version of Emacs---they can cause -Emacs to crash. Set the variable @code{load-dangerous-libraries} to -@code{t} if you want to try loading them. - Once you put your library in a directory where Emacs can find and load it, you may wish to make it available at startup. This is useful when the library defines features that should be available diff --git a/doc/emacs/calendar.texi b/doc/emacs/calendar.texi index fe51ad35d77..e5ee7e94bcf 100644 --- a/doc/emacs/calendar.texi +++ b/doc/emacs/calendar.texi @@ -625,6 +625,10 @@ your time zone. Emacs displays the times of sunrise and sunset @emph{corrected for daylight saving time}. @xref{Daylight Saving}, for how daylight saving time is determined. +@vindex calendar-time-zone-style + If you want to display numerical time zones (like @samp{"+0100"}) +instead of symbolic ones (like @samp{"CET"}), set this to @code{numeric}. + As a user, you might find it convenient to set the calendar location variables for your usual physical location in your @file{.emacs} file. If you are a system administrator, you may want to set these variables diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi index 850a802753d..3dd1fe9a308 100644 --- a/doc/emacs/cmdargs.texi +++ b/doc/emacs/cmdargs.texi @@ -495,7 +495,14 @@ variables to be set, but it uses their values if they are set. @item CDPATH @vindex CDPATH@r{, environment variable} Used by the @code{cd} command to search for the directory you specify, -when you specify a relative directory, +when you specify a relative directory. +@item COLORTERM +@vindex COLORTERM@r{, environment variable} +If this variable is set to the value @samp{truecolor}, it tells Emacs +to use 24-bit true color on text-mode displays even if the terminfo +database is not installed. Emacs will use built-in commands to +request true color by RGB values instead of the missing terminfo +information. @item DBUS_SESSION_BUS_ADDRESS @vindex DBUS_SESSION_BUS_ADDRESS@r{, environment variable} Used by D-Bus when Emacs is compiled with it. Usually, there is no @@ -565,12 +572,6 @@ is found there. @item HOSTNAME @vindex HOSTNAME@r{, environment variable} The name of the machine that Emacs is running on. -@c complete.el is obsolete since 24.1. -@ignore -@item INCPATH -A colon-separated list of directories. Used by the @code{complete} package -to search for files. -@end ignore @item INFOPATH @vindex INFOPATH@r{, environment variable} A colon-separated list of directories in which to search for Info files. diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index 00c8ee4f98b..a512fd14c80 100644 --- a/doc/emacs/custom.texi +++ b/doc/emacs/custom.texi @@ -1630,6 +1630,10 @@ characters are actually defined by this map. @item @vindex mode-specific-map @code{mode-specific-map} is for characters that follow @kbd{C-c}. +@item +@vindex project-prefix-map +@code{project-prefix-map} is for characters that follow @kbd{C-x p}, +used for project-related commands (@pxref{Projects}). @end itemize @node Local Keymaps @@ -2601,6 +2605,7 @@ the function or facility is available, like this: (if (fboundp 'blink-cursor-mode) (blink-cursor-mode 0)) +@c FIXME: Find better example since `set-coding-priority' is removed. (if (boundp 'coding-category-utf-8) (set-coding-priority '(coding-category-utf-8))) @end example diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi index 4ff1dc1bd94..19aaca962da 100644 --- a/doc/emacs/dired.texi +++ b/doc/emacs/dired.texi @@ -79,6 +79,29 @@ The former lists all the files with extension @samp{.el} in directory @samp{foo}. The latter lists the files with extension @samp{.el} in all the subdirectories of @samp{foo}. +@cindex globstar, in Dired +On Posix systems, when the system shell supports @dfn{globstar}, a +recursive globbing feature, and that support is enabled, you can use +recursive globbing in Dired: + +@example +C-x d ~/foo/**/*.el @key{RET} +@end example + +This command produces a directory listing with all the files with +extension @samp{.el}, descending recursively in all the subdirectories +of @samp{foo}. Note that there are small differences in the +implementation of globstar between different shells. Check your shell +manual to know the expected behavior. + +@vindex dired-maybe-use-globstar +@vindex dired-enable-globstar-in-shell +If the shell supports globstar, but that support is disabled by +default, you can still let Dired use this feature by customizing +@code{dired-maybe-use-globstar} to a non-@code{nil} value; then Dired +will enable globstar for those shells for which it knows how (see +@code{dired-enable-globstar-in-shell} for the list of those shells). + The usual history and completion commands can be used in the minibuffer; in particular, @kbd{M-n} puts the name of the visited file (if any) in the minibuffer (@pxref{Minibuffer History}). @@ -694,6 +717,14 @@ The variable @code{dired-recursive-copies} controls whether to copy directories recursively (like @samp{cp -r}). The default is @code{top}, which means to ask before recursively copying a directory. +@vindex dired-copy-dereference +@cindex follow symbolic links +@cindex dereference symbolic links +The variable @code{dired-copy-dereference} controls whether to copy +symbolic links as links or after dereferencing (like @samp{cp -L}). +The default is @code{nil}, which means that the symbolic links are +copied by creating new ones. + @item D @findex dired-do-delete @kindex D @r{(Dired)} diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi index a4040d986e1..e7b8745a044 100644 --- a/doc/emacs/display.texi +++ b/doc/emacs/display.texi @@ -1334,6 +1334,10 @@ customize the variable @code{whitespace-line-column}. @item newline Highlight newlines. +@item missing-newline-at-eof +Highlight the final character if the buffer doesn't end with a newline +character. + @item empty Highlight empty lines at the beginning and/or end of the buffer. @@ -1667,6 +1671,8 @@ Customization}). (The other attributes of this face have no effect; the text shown under the cursor is drawn using the frame's background color.) To change its shape, customize the buffer-local variable @code{cursor-type}; possible values are @code{box} (the default), +@code{(box . @var{size})} (box cursor becoming a hollow box under +masked images larger than @var{size} pixels in either dimension), @code{hollow} (a hollow box), @code{bar} (a vertical bar), @code{(bar . @var{n})} (a vertical bar @var{n} pixels wide), @code{hbar} (a horizontal bar), @code{(hbar . @var{n})} (a horizontal bar @var{n} @@ -1802,6 +1808,29 @@ logical lines, so having a fringe indicator for each wrapped line would be visually distracting. You can change this by customizing the variable @code{visual-line-fringe-indicators}. +@vindex word-wrap-by-category +@findex modify-category-entry +@findex char-category-set +@findex category-set-mnemonics + By default, Emacs only breaks lines after whitespace characters. +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 +(@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 +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 +report. You can add categories to a character using the command +@code{modify-category-entry}. + @node Display Custom @section Customization of Display diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index 6b82aeb8234..6aed7bd92a5 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -857,6 +857,12 @@ Customizing VC * CVS Options:: Options for CVS. @end ifnottex +Projects + +* Project File Commands:: Commands for handling project files. +* Project Buffer Commands:: Commands for handling project buffers. +* Switching Projects:: Switching between projects. + Change Logs * Change Log Commands:: Commands for editing change log files. @@ -1279,11 +1285,12 @@ programmer, but if you are not interested in customizing, you can ignore the customization hints. This is primarily a reference manual, but can also be used as a -primer. If you are new to Emacs, we recommend you start with -the integrated, learn-by-doing tutorial, before reading the manual. To -run the tutorial, start Emacs and type @kbd{C-h t}. The tutorial -describes commands, tells you when to try them, and explains the -results. The tutorial is available in several languages. +primer. If you are new to Emacs, we recommend you start with the +integrated, learn-by-doing tutorial, before reading the manual. To +run the tutorial, start Emacs and type @kbd{C-h t} (which is ``control +h and then t''). The tutorial describes commands, tells you when to +try them, and explains the results. The tutorial is available in +several languages. On first reading, just skim chapters 1 and 2, which describe the notational conventions of the manual and the general appearance of the diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index 5998326ffef..2fa1ecc003d 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -2149,7 +2149,12 @@ To reset all transformations to the initial state, use @findex image-previous-file You can press @kbd{n} (@code{image-next-file}) and @kbd{p} (@code{image-previous-file}) to visit the next image file and the -previous image file in the same directory, respectively. +previous image file in the same directory, respectively. These +commands will consult the ``parent'' dired buffer to determine what +the next/previous image file is. These commands also work when +opening a file from archive files (like zip or tar files), and will +then instead consult the archive mode buffer. If neither an archive +nor a dired ``parent'' buffer can be found, a dired buffer is opened. @findex image-mode-mark-file @findex image-mode-unmark-file diff --git a/doc/emacs/fixit.texi b/doc/emacs/fixit.texi index dc643e19a4b..db77ae4ec26 100644 --- a/doc/emacs/fixit.texi +++ b/doc/emacs/fixit.texi @@ -66,6 +66,7 @@ changes have already been undone, the undo command signals an error. @cindex redo @findex undo-only +@findex undo-redo Any command other than an undo command breaks the sequence of undo commands. Starting from that moment, the entire sequence of undo commands that you have just performed are themselves placed into the @@ -76,7 +77,9 @@ undo commands. Alternatively, if you want to resume undoing, without redoing previous undo commands, use @kbd{M-x undo-only}. This is like -@code{undo}, but will not redo changes you have just undone. +@code{undo}, but will not redo changes you have just undone. To +complement it, @kbd{M-x undo-redo} will undo previous undo commands +(and will not record itself as an undoable command). If you notice that a buffer has been modified accidentally, the easiest way to recover is to type @kbd{C-/} repeatedly until the stars @@ -274,6 +277,10 @@ Check and correct spelling in the region. @item M-x ispell-message Check and correct spelling in a draft mail message, excluding cited material. +@item M-x ispell-comments-and-strings +Check and correct spelling of comments and strings in the buffer or region. +@item M-x ispell-comment-or-string-at-point +Check the comment or string at point. @item M-x ispell-change-dictionary @key{RET} @var{dict} @key{RET} Restart the spell-checker process, using @var{dict} as the dictionary. @item M-x ispell-kill-ispell @@ -301,6 +308,8 @@ region; @pxref{Disabled Transient Mark}.) @findex ispell @findex ispell-buffer @findex ispell-region +@findex ispell-comments-and-strings +@findex ispell-comment-or-string-at-point @cindex spell-checking the active region Similarly, the command @kbd{M-x ispell} performs spell-checking in the region if one is active, or in the entire buffer otherwise. The @@ -309,7 +318,10 @@ explicitly perform spell-checking on the entire buffer or the region respectively. To check spelling in an email message you are writing, use @w{@kbd{M-x ispell-message}}; that command checks the whole buffer, except for material that is indented or appears to be cited from other -messages. @xref{Sending Mail}. +messages. @xref{Sending Mail}. When dealing with source code, you +can use @kbd{M-x ispell-comments-and-strings} or @w{@kbd{M-x +ispell-comment-or-string-at-point}} to check only comments or string +literals. When one of these commands encounters what appears to be an incorrect word, it asks you what to do. It usually displays a list of @@ -442,12 +454,14 @@ use @code{flyspell-region} or @code{flyspell-buffer} for that. @findex flyspell-correct-word-before-point When Flyspell mode highlights a word as misspelled, you can click on it with @kbd{mouse-2} (@code{flyspell-correct-word}) to display a menu -of possible corrections and actions. In addition, @kbd{C-.} or +of possible corrections and actions. If you want this menu on +@kbd{mouse-3} instead, customize the variable +@code{flyspell-use-mouse-3-for-menu}. In addition, @kbd{C-.} or @kbd{@key{ESC}-@key{TAB}} (@code{flyspell-auto-correct-word}) will propose various successive corrections for the word at point, and -@w{@kbd{C-c $}} (@code{flyspell-correct-word-before-point}) will pop up a -menu of possible corrections. Of course, you can always correct the -misspelled word by editing it manually in any way you like. +@w{@kbd{C-c $}} (@code{flyspell-correct-word-before-point}) will pop +up a menu of possible corrections. Of course, you can always correct +the misspelled word by editing it manually in any way you like. @findex flyspell-prog-mode Flyspell Prog mode works just like ordinary Flyspell mode, except diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi index e0eabe38d06..b74887612b9 100644 --- a/doc/emacs/frames.texi +++ b/doc/emacs/frames.texi @@ -366,9 +366,13 @@ 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}): -@c FIXME: `mouse-popup-menubar-stuff' is obsolete since 23.1. @smallexample -(global-set-key [mouse-3] 'mouse-popup-menubar-stuff) +(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 @node Mode Line Mouse @@ -439,29 +443,40 @@ buffer to select: @kindex C-x 5 2 @findex make-frame-command Create a new frame (@code{make-frame-command}). + @item C-x 5 b @var{bufname} @key{RET} Select buffer @var{bufname} in another frame. This runs @code{switch-to-buffer-other-frame}. + @item C-x 5 f @var{filename} @key{RET} Visit file @var{filename} and select its buffer in another frame. This runs @code{find-file-other-frame}. @xref{Visiting}. + @item C-x 5 d @var{directory} @key{RET} Select a Dired buffer for directory @var{directory} in another frame. This runs @code{dired-other-frame}. @xref{Dired}. + @item C-x 5 m Start composing a mail message in another frame. This runs @code{compose-mail-other-frame}. It is the other-frame variant of @kbd{C-x m}. @xref{Sending Mail}. + @item C-x 5 . Find the definition of an identifier in another frame. This runs @code{xref-find-definitions-other-frame}, the multiple-frame variant of @kbd{M-.}. @xref{Xref}. + @item C-x 5 r @var{filename} @key{RET} @kindex C-x 5 r @findex find-file-read-only-other-frame Visit file @var{filename} read-only, and select its buffer in another 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. @end table You can control the appearance and behavior of the newly-created @@ -1316,6 +1331,11 @@ runs @code{find-file-other-tab}. @xref{Visiting}. @item C-x t d @var{directory} @key{RET} Select a Dired buffer for directory @var{directory} in another tab. This runs @code{dired-other-tab}. @xref{Dired}. + +@item C-x t t +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 tab. @end table @vindex tab-bar-new-tab-choice diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi index 06ddc11158b..06ad5a583d2 100644 --- a/doc/emacs/help.texi +++ b/doc/emacs/help.texi @@ -220,6 +220,16 @@ documentation string of the command it runs. command is not on any key, that means you must use @kbd{M-x} to run it. @kbd{C-h w} runs the command @code{where-is}. +@findex button-describe +@findex widget-describe + Some modes in Emacs use various buttons (@pxref{Buttons,,,elisp, The +Emacs Lisp Reference Manual}) and widgets +(@pxref{Introduction,,,widget, Emacs Widgets}) that can be clicked to +perform some action. To find out what function is ultimately invoked +by these buttons, Emacs provides the @code{button-describe} and +@code{widget-describe} commands, that should be run with point over +the button. + @node Name Help @section Help by Command or Variable Name @@ -607,6 +617,11 @@ 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.) +@findex describe-keymap +Finally, @kbd{M-x describe-keymap} prompts for the name of a keymap, +with completion, and displays a listing of all key bindings in that +keymap. + @node Help Files @section Help Files diff --git a/doc/emacs/killing.texi b/doc/emacs/killing.texi index 6b1f35e6158..bd7dbb6f515 100644 --- a/doc/emacs/killing.texi +++ b/doc/emacs/killing.texi @@ -577,7 +577,9 @@ regions to the primary selection entirely. To insert the primary selection into an Emacs buffer, click @kbd{mouse-2} (@code{mouse-yank-primary}) where you want to insert it. -@xref{Mouse Commands}. +@xref{Mouse Commands}. You can also use the normal Emacs yank command +(@kbd{C-y}) to insert this text if @code{select-enable-primary} is set +(@pxref{Clipboard}). @cindex MS-Windows, and primary selection MS-Windows provides no primary selection, but Emacs emulates it diff --git a/doc/emacs/m-x.texi b/doc/emacs/m-x.texi index fc2d2d8c84d..b18c334acf4 100644 --- a/doc/emacs/m-x.texi +++ b/doc/emacs/m-x.texi @@ -72,6 +72,10 @@ number, in which case Emacs will show the binding for that many seconds before removing it from display. The default behavior is to display the binding for 2 seconds. +Additionally, when @code{suggest-key-bindings} is non-@code{nil}, the +completion list of @kbd{M-x} shows equivalent key bindings for all +commands that have them. + @vindex extended-command-suggest-shorter Commands that don't have key bindings, can still be invoked after typing less than their full name at the @samp{M-x} prompt. Emacs diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index ebcdddfcae3..a9b0da5aff6 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -1656,8 +1656,53 @@ support additional types of projects. the project back-end. For example, the VC back-end doesn't consider ``ignored'' files (@pxref{VC Ignore}) to be part of the project. +@menu +* Project File Commands:: Commands for handling project files. +* Project Buffer Commands:: Commands for handling project buffers. +* Switching Projects:: Switching between projects. +@end menu + +@node Project File Commands +@subsection Project Commands That Operate on Files + +@table @kbd +@item C-x p f +Visit a file that belongs to the current project +(@code{project-find-file}). +@item C-x p g +Find matches for a regexp in all files that belong to the current +project (@code{project-find-regexp}). +@item M-x project-search +Interactively search for regexp matches in all files that belong to +the current project. +@item C-x p r +Perform query-replace for a regexp in all files that belong to the +current project (@code{project-query-replace-regexp}). +@item C-x p d +Run Dired in the current project's root directory +(@code{project-dired}). +@item C-x p v +Run @code{vc-dir} in the current project's root directory +(@code{project-vc-dir}). +@item C-x p s +Start an inferior shell in the current project's root directory +(@code{project-shell}). +@item C-x p e +Start Eshell in the current project's root directory +(@code{project-eshell}). +@item C-x p c +Run compilation in the current project's root directory +(@code{project-compile}). +@item C-x p ! +Run shell command in the current project's root directory +(@code{project-shell-command}). +@item C-x p & +Run shell command asynchronously in the current project's root +directory (@code{project-async-shell-command}). +@end table + Emacs provides commands for handling project files conveniently. -This section describes these commands. +This subsection describes these commands. @cindex current project All of the commands described here share the notion of the @@ -1668,25 +1713,26 @@ doesn't seem to belong to a recognizable project, these commands prompt you for the project directory. @findex project-find-file - The command @code{project-find-file} is a convenient way of visiting -files (@pxref{Visiting}) that belong to the current project. Unlike -@kbd{C-x C-f}, this command doesn't require to type the full file name -of the file to visit, you can type only the file's base name (i.e., -omit the leading directories). In addition, the completion candidates -considered by the command include only the files belonging to the -current project, and nothing else. If there's a file name at point, -this command offers that file as the default to visit. + The command @kbd{C-x p f} (@code{project-find-file}) is a convenient +way of visiting files (@pxref{Visiting}) that belong to the current +project. Unlike @kbd{C-x C-f}, this command doesn't require to type +the full file name of the file to visit, you can type only the file's +base name (i.e., omit the leading directories). In addition, the +completion candidates considered by the command include only the files +belonging to the current project, and nothing else. If there's a file +name at point, this command offers that file as the default to visit. @findex project-find-regexp - The command @code{project-find-regexp} is similar to @code{rgrep} -(@pxref{Grep Searching}), but it searches only the files that belong -to the current project. The command prompts for the regular -expression to search, and pops up an Xref mode buffer with the search -results, where you can select a match using the Xref mode commands -(@pxref{Xref Commands}). When invoked with a prefix argument, this -command additionally prompts for the base directory from which to -start the search; this allows, for example, to limit the search only -to project files under a certain subdirectory of the project root. + The command @kbd{C-x p g} (@code{project-find-regexp}) is similar to +@code{rgrep} (@pxref{Grep Searching}), but it searches only the files +that belong to the current project. The command prompts for the +regular expression to search, and pops up an Xref mode buffer with the +search results, where you can select a match using the Xref mode +commands (@pxref{Xref Commands}). When invoked with a prefix +argument, this command additionally prompts for the base directory +from which to start the search; this allows, for example, to limit the +search only to project files under a certain subdirectory of the +project root. @findex project-search @kbd{M-x project-search} is an interactive variant of @@ -1698,13 +1744,101 @@ matched file. To find the rest of the matches, type @w{@kbd{M-x fileloop-continue @key{RET}}}. @findex project-query-replace-regexp - @kbd{M-x project-query-replace-regexp} is similar to + @kbd{C-x p r} (@code{project-query-replace-regexp}) is similar to @code{project-search}, but it prompts you for whether to replace each match it finds, like @code{query-replace} does (@pxref{Query Replace}), and continues to the next match after you respond. If your response causes Emacs to exit the query-replace loop, you can later continue with @w{@kbd{M-x fileloop-continue @key{RET}}}. +@findex project-dired + The command @kbd{C-x p d} (@code{project-dired}) opens a Dired +buffer (@pxref{Dired}) listing the files in the current project's root +directory. + +@findex project-vc-dir + The command @kbd{C-x p v} (@code{project-vc-dir}) opens a VC +Directory buffer (@pxref{VC Directory Mode}) listing the version +control statuses of the files in a directory tree under the current +project's root directory. + +@findex project-shell + The command @kbd{C-x p s} (@code{project-shell}) starts a shell +session (@pxref{Shell}) in a new buffer with the current project's +root as the working directory. + +@findex project-eshell + The command @kbd{C-x p e} (@code{project-eshell}) starts an Eshell +session in a new buffer with the current project's root as the working +directory. @xref{Top,Eshell,Eshell, eshell, Eshell: The Emacs Shell}. + +@findex project-compile + The command @kbd{C-x p c} (@code{project-compile}) runs compilation +(@pxref{Compilation}) in the current project's root directory. + +@findex project-shell-command + The command @kbd{C-x p !} (@code{project-shell-command}) runs +@code{shell-command} in the current project's root directory. + +@findex project-async-shell-command + The command @kbd{C-x p &} (@code{project-async-shell-command}) runs +@code{async-shell-command} in the current project's root directory. + +@node Project Buffer Commands +@subsection Project Commands That Operate on Buffers + +@table @kbd +@item C-x p b +Switch to another buffer belonging to the current project +(@code{project-switch-to-buffer}). +@item C-x p k +Kill all live buffers that belong to the current project +(@code{project-kill-buffers}). +@end table + +@findex project-switch-to-buffer + Working on a project could potentially involve having many buffers +visiting files that belong to the project, and also buffers that +belong to the project, but don't visit any files (like the +@file{*compilation*} buffer created by @code{project-compile}). The +command @kbd{C-x p b} (@code{project-switch-to-buffer}) helps you +switch between buffers that belong to the current project by prompting +for a buffer to switch and considering only the current project's +buffers as candidates for completion. + +@findex project-kill-buffers +@vindex project-kill-buffer-conditions + When you finish working on the project, you may wish to kill all the +buffers that belong to the project, to keep your Emacs session +smaller. The command @kbd{C-x p k} (@code{project-kill-buffers}) +accomplishes that: it kills all the buffers that belong to the current +project that satisfy any of @code{project-kill-buffer-conditions}. + +@node Switching Projects +@subsection Switching Projects + +@table @kbd +@item C-x p p +Run an Emacs command for another project (@code{project-switch-project}). +@end table + +@findex project-switch-project +@vindex project-switch-commands + Commands that operate on project files (@pxref{Project File +Commands}) will conveniently prompt you for a project directory when +no project is current. When you are inside some project, but you want +to operate on a different project, use the @kbd{C-x p p} command +(@code{project-switch-project}). This command prompts you to choose a +directory among known project roots, and then displays the menu of +available commands to operate on the project you choose. The variable +@code{project-switch-commands} controls which commands are available +in the menu, and which key invokes each command. + +@vindex project-list-file + The variable @code{project-list-file} names the file in which Emacs +records the list of known projects. It defaults to the file +@file{projects} in @code{user-emacs-directory} (@pxref{Find Init}). + @node Change Log @section Change Logs diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi index 2f02c702512..c8b21e701c7 100644 --- a/doc/emacs/misc.texi +++ b/doc/emacs/misc.texi @@ -245,13 +245,13 @@ Do an incremental search on the selected article buffer (@code{gnus-summary-isearch-article}), as if you switched to the buffer and typed @kbd{C-s} (@pxref{Incremental Search}). -@kindex M-s @r{(Gnus Summary mode)} +@kindex M-s M-s @r{(Gnus Summary mode)} @findex gnus-summary-search-article-forward @item M-s @var{regexp} @key{RET} Search forward for articles containing a match for @var{regexp} (@code{gnus-summary-search-article-forward}). -@kindex M-r @r{(Gnus Summary mode)} +@kindex M-s M-r @r{(Gnus Summary mode)} @findex gnus-summary-search-article-backward @item M-r @var{regexp} @key{RET} Search back for articles containing a match for @var{regexp} @@ -724,12 +724,13 @@ See the Eshell Info manual, which is distributed with Emacs. @kindex M-! @findex shell-command +@vindex shell-command-buffer-name @kbd{M-!} (@code{shell-command}) reads a line of text using the minibuffer and executes it as a shell command, in a subshell made just for that command. Standard input for the command comes from the null device. If the shell command produces any output, the output appears -either in the echo area (if it is short), or in an Emacs buffer named -@file{*Shell Command Output*}, displayed in another window (if the +either in the echo area (if it is short), or in the @samp{"*Shell +Command Output*"} (@code{shell-command-buffer-name}) buffer (if the output is long). The variables @code{resize-mini-windows} and @code{max-mini-window-height} (@pxref{Minibuffer Edit}) control when Emacs should consider the output to be too long for the echo area. @@ -758,15 +759,17 @@ which is impossible to ignore. @kindex M-& @findex async-shell-command +@vindex shell-command-buffer-name-async A shell command that ends in @samp{&} is executed @dfn{asynchronously}, and you can continue to use Emacs as it runs. You can also type @kbd{M-&} (@code{async-shell-command}) to execute a shell command asynchronously; this is exactly like calling @kbd{M-!} with a trailing @samp{&}, except that you do not need the @samp{&}. -The default output buffer for asynchronous shell commands is named -@samp{*Async Shell Command*}. Emacs inserts the output into this -buffer as it comes in, whether or not the buffer is visible in a -window. +The output from asynchronous shell commands, by default, goes into the +@samp{"*Async Shell Command*"} buffer +(@code{shell-command-buffer-name-async}). Emacs inserts the output +into this buffer as it comes in, whether or not the buffer is visible +in a window. @vindex async-shell-command-buffer If you want to run more than one asynchronous shell command at the @@ -804,7 +807,7 @@ old region and replaces it with the output from the shell command. see what keys are in the buffer. If the buffer contains a GnuPG key, type @kbd{C-x h M-| gpg @key{RET}} to feed the entire buffer contents to @command{gpg}. This will output the list of keys to the -@file{*Shell Command Output*} buffer. +buffer whose name is the value of @code{shell-command-buffer-name}. @vindex shell-file-name The above commands use the shell specified by the variable @@ -2920,9 +2923,17 @@ you might like to bind to keys, such as @code{browse-url-at-point} and You can customize Browse-URL's behavior via various options in the @code{browse-url} Customize group. In particular, the option @code{browse-url-mailto-function} lets you define how to follow -@samp{mailto:} URLs, while @code{browse-url-browser-function} lets you -define how to follow other types of URLs. For more information, view -the package commentary by typing @kbd{C-h P browse-url @key{RET}}. +@samp{mailto:} URLs, while @code{browse-url-browser-function} +specifies your default browser. + +@vindex browse-url-handlers + You can define that certain URLs are browsed with other functions by +customizing @code{browse-url-handlers}, an alist of regular +expressions or predicates paired with functions to browse matching +URLs. + +For more information, view the package commentary by typing @kbd{C-h P +browse-url @key{RET}}. @node Goto Address mode @subsection Activating URLs @@ -2934,6 +2945,9 @@ the package commentary by typing @kbd{C-h P browse-url @key{RET}}. @table @kbd @item M-x goto-address-mode Activate URLs and e-mail addresses in the current buffer. + +@item M-x global-goto-address-mode +Activate @code{goto-address-mode} in all buffers. @end table @kindex C-c RET @r{(Goto Address mode)} diff --git a/doc/emacs/msdos.texi b/doc/emacs/msdos.texi index 3275fded565..48492ab2f22 100644 --- a/doc/emacs/msdos.texi +++ b/doc/emacs/msdos.texi @@ -712,6 +712,21 @@ is @code{t}, which means these keys produce @code{AltGr}; setting it to @code{nil} causes @key{AltGr} or the equivalent key combination to be interpreted as the combination of @key{Ctrl} and @key{Meta} modifiers. + +@cindex IME, MS-Windows +@findex w32-set-ime-open-status + Some versions of MS-Windows, typically East Asian localized Windows, +enable the Input Method Manager (@acronym{IMM}) that allows +applications to communicate with the Input Method Editor +(@acronym{IME}), the native Windows input method service. Emacs uses +the @acronym{IME} when available to allow users to input East Asian +non-@acronym{ASCII} characters, similarly to Emacs's built-in input +methods (@pxref{Input Methods}). However, in some situations the +@acronym{IME} can get in the way if it interprets simple +@acronym{ASCII} keys you input as part of a key sequence that +designates a non-@acronym{ASCII} character. The @acronym{IME} can be +temporarily turned off and then on again by using the +@code{w32-set-ime-open-status} function. @end ifnottex @node Windows Mouse diff --git a/doc/emacs/mule.texi b/doc/emacs/mule.texi index 0f07d286cda..6eff0ca0d22 100644 --- a/doc/emacs/mule.texi +++ b/doc/emacs/mule.texi @@ -202,7 +202,7 @@ terminal, the code(s) sent to the terminal. @item If the character was composed on display with any following characters to form one or more grapheme clusters, the composition information: -the font glyphs if the frame is on a graphical display, else the +the font glyphs if the frame is on a graphical display, and the characters that were composed. @item diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi index 517d2b75aa2..453d9eb4010 100644 --- a/doc/emacs/package.texi +++ b/doc/emacs/package.texi @@ -165,27 +165,6 @@ Refresh the package list (@code{revert-buffer}). This fetches the list of available packages from the package archive again, and redisplays the package list. -@item / k -@kindex / k @r{(Package Menu)} -@findex package-menu-filter-by-keyword -Filter the package list by keyword -(@code{package-menu-filter-by-keyword}). This prompts for a keyword -(e.g., @samp{games}), then shows only the packages that relate to that -keyword. - -@item / n -@kindex / n @r{(Package Menu)} -@findex package-menu-filter-by-name -Filter the package list by name (@code{package-menu-filter-by-name}). -This prompts for a string, then shows only the packages whose names -match a regexp with that value. - -@item / / -@kindex / / @r{(Package Menu)} -@findex package-menu-clear-filter -Clear filter currently applied to the package list -(@code{package-menu-clear-filter}). - @item H @kindex H @r{(Package Menu)} @findex package-menu-hide-package @@ -200,6 +179,54 @@ pressing @key{RET} to the prompt will hide the current package. @findex package-menu-toggle-hiding Toggle visibility of old versions of packages and also of versions from lower-priority archives (@code{package-menu-toggle-hiding}). + +@item / a +@kindex / a @r{(Package Menu)} +@findex package-menu-filter-by-archive +Filter package list by archive (@code{package-menu-filter-by-archive}). +This prompts for a package archive (e.g., @samp{gnu}), then shows only +packages from that archive. + +@item / k +@kindex / k @r{(Package Menu)} +@findex package-menu-filter-by-keyword +Filter package list by keyword (@code{package-menu-filter-by-keyword}). +This prompts for a keyword (e.g., @samp{games}), then shows only +packages with that keyword. + +@item / n +@kindex / n @r{(Package Menu)} +@findex package-menu-filter-by-name +Filter package list by name (@code{package-menu-filter-by-name}). +This prompts for a regular expression, then shows only packages +with names matching that regexp. + +@item / s +@kindex / s @r{(Package Menu)} +@findex package-menu-filter-by-status +Filter package list by status (@code{package-menu-filter-by-status}). +This prompts for one or more statuses (e.g., @samp{available}), then +shows only packages with matching status. + +@item / v +@kindex / v @r{(Package Menu)} +@findex package-menu-filter-by-version +Filter package list by version (@code{package-menu-filter-by-version}). +This prompts first for one of the qualifiers @samp{<}, @samp{>} or +@samp{=}, and then a package version, and shows packages that has a +lower, equal or higher version than the one specified. + +@item / m +@kindex / m @r{(Package Menu)} +@findex package-menu-filter-marked +Filter package list by non-empty mark (@code{package-menu-filter-marked}). +This shows only the packages that have been marked to be installed or deleted. + +@item / / +@kindex / / @r{(Package Menu)} +@findex package-menu-filter-clear +Clear filter currently applied to the package list +(@code{package-menu-filter-clear}). @end table @noindent diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi index b976f2e7b12..1c33d7dccc7 100644 --- a/doc/emacs/programs.texi +++ b/doc/emacs/programs.texi @@ -1269,9 +1269,29 @@ information whenever there is a Lisp function or variable at point; for a function, it shows the argument list, and for a variable it shows the first line of the variable's documentation string. To toggle ElDoc mode, type @kbd{M-x eldoc-mode}. There's also a Global -ElDoc mode, which is turned on by default, and affects buffers, such -as @samp{*scratch*}, whose major mode is Emacs Lisp or Lisp -Interaction (@w{@kbd{M-x global-eldoc-mode}} to turn it off globally). +ElDoc mode, which is turned on by default, and affects buffers whose +major mode sets the variables described below. Use @w{@kbd{M-x +global-eldoc-mode}} to turn it off globally. + +@vindex eldoc-documentation-strategy +@vindex eldoc-documentation-functions + These variables can be used to configure ElDoc mode: + +@table @code +@item eldoc-documentation-strategy +This variable holds the function which is used to retrieve +documentation for the item at point from the functions in the hook +@code{eldoc-documentation-functions}. By default, +@code{eldoc-documentation-strategy} returns the first documentation +string produced by the @code{eldoc-documentation-functions} hook, but +it may be customized to compose those functions' results in other +ways. + +@item eldoc-documentation-functions +This abnormal hook holds documentation functions. It acts as a +collection of backends for ElDoc. This is what modes should use to +register their documentation functions with ElDoc. +@end table @node Hideshow @section Hideshow minor mode diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi index 4c67660b92d..bc1dcd7f419 100644 --- a/doc/emacs/windows.texi +++ b/doc/emacs/windows.texi @@ -251,9 +251,19 @@ Mail}), but in another window (@code{compose-mail-other-window}). Find the definition of an identifier, similar to @kbd{M-.} (@pxref{Xref}), but in another window (@code{xref-find-definitions-other-window}). + @item C-x 4 r @var{filename} @key{RET} Visit file @var{filename} read-only, and select its buffer in another window (@code{find-file-read-only-other-window}). @xref{Visiting}. + +@item C-x 4 4 +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 window. + +@item C-x 4 1 +This general prefix command requests the buffer of the next command +to be displayed in the same window. @end table @node Change Window diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index e6c54efba73..9aefe1da17a 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -929,7 +929,7 @@ GNU Emacs Lisp is largely inspired by Maclisp, which was written at MIT in the 1960s. It is somewhat inspired by Common Lisp, which became a standard in the 1980s. However, Emacs Lisp is much simpler than Common Lisp. (The standard Emacs distribution contains an optional extensions -file, @file{cl.el}, that adds many Common Lisp features to Emacs Lisp.) +file, @file{cl-lib.el}, that adds many Common Lisp features to Emacs Lisp.) @node Note for Novices @unnumberedsec A Note for Novices diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi index 4ed1a10fcf6..379279575ca 100644 --- a/doc/lispref/backups.texi +++ b/doc/lispref/backups.texi @@ -414,10 +414,16 @@ version that the caller should consider deleting now. @end smallexample @end defun -@c Emacs 19 feature +@defun file-backup-file-names filename +This function returns a list of all the backup file names for +@var{filename}, or @code{nil} if there are none. The files are sorted +by modification time, descending, so that the most recent files are +first. +@end defun + @defun file-newest-backup filename -This function returns the name of the most recent backup file for -@var{filename}, or @code{nil} if that file has no backup files. +This function returns the first element of the list returned by +@code{file-backup-file-names}. Some file comparison commands use this function so that they can automatically compare a file with its most recent backup. @@ -460,6 +466,32 @@ Auto Save mode is enabled if @code{buffer-auto-save-file-name} is non-@code{nil} and @code{buffer-saved-size} (see below) is non-zero. @end deffn +@defvar auto-save-file-name-transforms +This variable lists transforms to apply to buffer's file name before +making the auto-save file name. + +Each transform is a list of the form @w{@code{(@var{regexp} +@var{replacement} [@var{uniquify}])}}. @var{regexp} is a regular +expression to match against the file name; if it matches, +@code{replace-match} is used to replace the matching part with +@var{replacement}. If the optional element @var{uniquify} is non-nil, +the auto-save file name is constructed by concatenating the directory +part of the transformed file name with the buffer's file name in which +all directory separators were changed to @samp{!} to prevent clashes. +(This will not work correctly if your filesystem truncates the +resulting name.) + +All the transforms in the list are tried, in the order they are listed. +When one transform applies, its result is final; +no further transforms are tried. + +The default value is set up to put the auto-save files of remote files +into the temporary directory (@pxref{Unique File Names}). + +On MS-DOS filesystems without long names this variable is always +ignored. +@end defvar + @defun auto-save-file-name-p filename This function returns a non-@code{nil} value if @var{filename} is a string that could be the name of an auto-save file. It assumes @@ -481,21 +513,6 @@ name. The argument @var{filename} should not contain a directory part. @result{} nil @end group @end example - -The standard definition of this function is as follows: - -@example -@group -(defun auto-save-file-name-p (filename) - "Return non-nil if FILENAME can be yielded by..." - (string-match "^#.*#$" filename)) -@end group -@end example - -This function exists so that you can customize it if you wish to -change the naming convention for auto-save files. If you redefine it, -be sure to redefine the function @code{make-auto-save-file-name} -correspondingly. @end defun @defun make-auto-save-file-name @@ -511,31 +528,6 @@ function should check that variable first. @result{} "/xcssun/users/rms/lewis/#backups.texi#" @end group @end example - -Here is a simplified version of the standard definition of this -function: - -@example -@group -(defun make-auto-save-file-name () - "Return file name to use for auto-saves \ -of current buffer.." - (if buffer-file-name -@end group -@group - (concat - (file-name-directory buffer-file-name) - "#" - (file-name-nondirectory buffer-file-name) - "#") - (expand-file-name - (concat "#%" (buffer-name) "#")))) -@end group -@end example - -This exists as a separate function so that you can redefine it to -customize the naming convention for auto-save files. Be sure to -change @code{auto-save-file-name-p} in a corresponding way. @end defun @defopt auto-save-visited-file-name diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 2ef27c00b8e..d3adb62c1bd 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1318,12 +1318,6 @@ the buffer specified by @var{buffer-or-name} current for running @var{body}. @end defmac -@defmac with-displayed-buffer-window buffer-or-name action quit-function &rest body -This macro is like @code{with-current-buffer-window} but unlike that -displays the buffer specified by @var{buffer-or-name} @emph{before} -running @var{body}. -@end defmac - A window showing a temporary buffer can be fitted to the size of that buffer using the following mode: @@ -2459,12 +2453,15 @@ Draw a box with lines of width 1, in the foreground color. @item @var{color} Draw a box with lines of width 1, in color @var{color}. -@item @code{(:line-width @var{width} :color @var{color} :style @var{style})} -This way you can explicitly specify all aspects of the box. The value -@var{width} specifies the width of the lines to draw; it defaults to -1. A negative width @minus{}@var{n} means to draw a line of width @var{n} -whose top and bottom parts occupy the space of the underlying text, -thus avoiding any increase in the character height. +@item @code{(:line-width (@var{vwidth} . @var{hwidth}) :color @var{color} :style @var{style})} +This way you can explicitly specify all aspects of the box. The values +@var{vwidth} and @var{hwidth} specifies respectively the width of the +vertical and horizontal lines to draw; they default to (1 . 1). +A negative horizontal or vertical width @minus{}@var{n} means to draw a line +of width @var{n} that occupies the space of the underlying text, thus +avoiding any increase in the character height or width. For simplification +the width could be specified with only a single number @var{n} instead +of a list, such case is equivalent to @code{((abs @var{n}) . @var{n})}. The value @var{color} specifies the color to draw with. The default is the foreground color of the face for simple boxes, and the background @@ -5575,6 +5572,15 @@ The value, @var{width}, specifies the width of the image, in pixels. @item :height @var{height} The value, @var{height}, specifies the height of the image, in pixels. +Note that @code{:width} and @code{:height} can only be used if passing +in data that doesn't specify the width and height (e.g., a string or a +vector containing the bits of the image). @acronym{XBM} files usually +specify this themselves, and it's an error to use these two properties +on these files. Also note that @code{:width} and @code{:height} are +used by most other image formats to specify what the displayed image +is supposed to be, which usually means performing some sort of +scaling. This isn't supported for @acronym{XBM} images. + @item :stride @var{stride} The number of bool vector entries stored for each row; the smallest multiple of 8 greater than or equal to @var{width}. diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi index b5b5ea0a645..6404e068dae 100644 --- a/doc/lispref/edebug.texi +++ b/doc/lispref/edebug.texi @@ -1362,6 +1362,11 @@ while matching the remainder of the specifications at this level. This is primarily used to generate more specific syntax error messages. See @ref{Backtracking}, for more details. Also see the @code{let} example. +@item &error +@code{&error} should be followed by a string, an error message, in the +edebug-spec; it aborts the instrumentation, displaying the message in +the minibuffer. + @item @var{other-symbol} @cindex indirect specifications Any other symbol in a specification list may be a predicate or an @@ -1433,6 +1438,16 @@ name component for the definition. You can use this to add a unique, static component to the name of the definition. It may be used more than once. +@item :unique +This construct is like @code{:name}, but generates unique names. It +does not match an argument. The element following @code{:unique} +should be a string; it is used as the prefix for an additional name +component for the definition. You can use this to add a unique, +dynamic component to the name of the definition. This is useful for +macros that can define the same symbol multiple times in different +scopes, such as @code{cl-flet}; @ref{Function Bindings,,,cl}. It may +be used more than once. + @item arg The argument, a symbol, is the name of an argument of the defining form. However, lambda-list keywords (symbols starting with @samp{&}) diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 6ca2834fbd4..090c54f8cd9 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -928,7 +928,7 @@ also checks that the file's group would be unchanged. This function does not follow symbolic links. @end defun -@defun file-modes filename +@defun file-modes filename &optional flag @cindex mode bits @cindex file permissions @cindex permissions, file @@ -946,12 +946,19 @@ The highest possible value is 4095 (7777 octal), meaning that everyone has read, write, and execute permission, the @acronym{SUID} bit is set for both others and group, and the sticky bit is set. +By default this function follows symbolic links. However, if the +optional argument @var{flag} is the symbol @code{nofollow}, this +function does not follow @var{filename} if it is a symbolic link; +this can help prevent inadvertently obtaining the mode bits of a file +somewhere else, and is more consistent with @code{file-attributes} +(@pxref{File Attributes}). + @xref{Changing Files}, for the @code{set-file-modes} function, which can be used to set these permissions. @example @group -(file-modes "~/junk/diffs") +(file-modes "~/junk/diffs" 'nofollow) @result{} 492 ; @r{Decimal integer.} @end group @group @@ -960,7 +967,7 @@ can be used to set these permissions. @end group @group -(set-file-modes "~/junk/diffs" #o666) +(set-file-modes "~/junk/diffs" #o666 'nofollow) @result{} nil @end group @@ -1801,9 +1808,17 @@ See also @code{delete-directory} in @ref{Create/Delete Dirs}. @cindex file permissions, setting @cindex permissions, file @cindex file modes, setting -@deffn Command set-file-modes filename mode +@deffn Command set-file-modes filename mode &optional flag This function sets the @dfn{file mode} (or @dfn{permissions}) of -@var{filename} to @var{mode}. This function follows symbolic links. +@var{filename} to @var{mode}. + +By default this function follows symbolic links. However, if the +optional argument @var{flag} is the symbol @code{nofollow}, this +function does not follow @var{filename} if it is a symbolic link; +this can help prevent inadvertently changing the mode bits of a file +somewhere else. On platforms that do not support changing mode bits +on a symbolic link, this function signals an error when @var{filename} +is a symbolic link and @var{flag} is @code{nofollow}. If called non-interactively, @var{mode} must be an integer. Only the lowest 12 bits of the integer are used; on most systems, only the @@ -1811,7 +1826,7 @@ lowest 9 bits are meaningful. You can use the Lisp construct for octal numbers to enter @var{mode}. For example, @example -(set-file-modes #o644) +(set-file-modes "myfile" #o644 'nofollow) @end example @noindent @@ -1894,11 +1909,24 @@ omitted or @code{nil}, it defaults to 0, i.e., no access rights at all. @end defun -@defun set-file-times filename &optional time +@defun file-modes-number-to-symbolic modes +This function converts a numeric file mode specification in +@var{modes} into the equivalent symbolic form. +@end defun + +@defun set-file-times filename &optional time flag This function sets the access and modification times of @var{filename} to @var{time}. The return value is @code{t} if the times are successfully set, otherwise it is @code{nil}. @var{time} defaults to the current time and must be a time value (@pxref{Time of Day}). + +By default this function follows symbolic links. However, if the +optional argument @var{flag} is the symbol @code{nofollow}, this +function does not follow @var{filename} if it is a symbolic link; +this can help prevent inadvertently changing the times of a file +somewhere else. On platforms that do not support changing times +on a symbolic link, this function signals an error when @var{filename} +is a symbolic link and @var{flag} is @code{nofollow}. @end defun @defun set-file-extended-attributes filename attribute-alist @@ -2410,14 +2438,26 @@ This is for the sake of filesystems that have the concept of a superroot above the root directory @file{/}. On other filesystems, @file{/../} is interpreted exactly the same as @file{/}. +If a filename must be that of a directory, its expansion must be too. +For example, if a filename ends in @samp{/} or @samp{/.} or @samp{/..} +then its expansion ends in @samp{/} so that it cannot be +misinterpreted as the name of a symbolic link: + +@example +@group +(expand-file-name "/a///b//.") + @result{} "/a/b/" +@end group +@end example + Expanding @file{.} or the empty string returns the default directory: @example @group (expand-file-name "." "/usr/spool/") - @result{} "/usr/spool" + @result{} "/usr/spool/" (expand-file-name "" "/usr/spool/") - @result{} "/usr/spool" + @result{} "/usr/spool/" @end group @end example diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index ae61b269520..22d32c00d9b 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -2193,10 +2193,11 @@ it and see if it works.) @vindex ns-appearance@r{, a frame parameter} @item ns-appearance Only available on macOS, if set to @code{dark} draw this frame's -window-system window using the ``vibrant dark'' theme, otherwise use -the system default. The ``vibrant dark'' theme can be used to set the -toolbar and scrollbars to a dark appearance when using an Emacs theme -with a dark background. +window-system window using the ``vibrant dark'' theme, and if set to +@code{light} use the ``aqua'' theme, otherwise use the system default. +The ``vibrant dark'' theme can be used to set the toolbar and +scrollbars to a dark appearance when using an Emacs theme with a dark +background. @vindex ns-transparent-titlebar@r{, a frame parameter} @item ns-transparent-titlebar @@ -2220,6 +2221,9 @@ How to display the cursor. Legitimate values are: @table @code @item box Display a filled box. (This is the default.) +@item (box . @var{size}) +Display a filled box. However, display it as a hollow box if point is +under masked image larger than @var{size} pixels in either dimension. @item hollow Display a hollow box. @item nil @@ -3872,13 +3876,15 @@ detailed knowledge of what types other applications use for drag and drop. @vindex dnd-protocol-alist +@vindex browse-url-handlers +@vindex browse-url-default-handlers When an URL is dropped on Emacs it may be a file, but it may also be another URL type (https, etc.). Emacs first checks @code{dnd-protocol-alist} to determine what to do with the URL@. If -there is no match there and if @code{browse-url-browser-function} is -an alist, Emacs looks for a match there. If no match is found the -text for the URL is inserted. If you want to alter Emacs behavior, -you can customize these variables. +there is no match there, Emacs looks for a match in +@code{browse-url-handlers} and @code{browse-url-default-handlers}. If +still no match has been found, the text for the URL is inserted. If +you want to alter Emacs behavior, you can customize these variables. @node Color Names @section Color Names @@ -3970,11 +3976,11 @@ If @var{color} is not defined, the value is @code{nil}. (color-values "black") @result{} (0 0 0) (color-values "white") - @result{} (65280 65280 65280) + @result{} (65535 65535 65535) (color-values "red") - @result{} (65280 0 0) + @result{} (65535 0 0) (color-values "pink") - @result{} (65280 49152 51968) + @result{} (65535 49344 52171) (color-values "hungry") @result{} nil @end example diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 2898cb4d2b4..26b212d05eb 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -2163,15 +2163,24 @@ the backquote (@pxref{Backquote}), but quotes code and accepts only @end defmac @defmac inline-letevals (bindings@dots{}) body@dots{} -This is similar to @code{let} (@pxref{Local Variables}): it sets up -local variables as specified by @var{bindings}, and then evaluates -@var{body} with those bindings in effect. Each element of -@var{bindings} should be either a symbol or a list of the form -@w{@code{(@var{var} @var{expr})}}; the result is to evaluate -@var{expr} and bind @var{var} to the result. The tail of -@var{bindings} can be either @code{nil} or a symbol which should hold -a list of arguments, in which case each argument is evaluated, and the -symbol is bound to the resulting list. +This provides a convenient way to ensure that the arguments to an +inlined function are evaluated exactly once, as well as to create +local variables. + +It's similar to @code{let} (@pxref{Local Variables}): It sets up local +variables as specified by @var{bindings}, and then evaluates +@var{body} with those bindings in effect. + +Each element of @var{bindings} should be either a symbol or a list of +the form @w{@code{(@var{var} @var{expr})}}; the result is to evaluate +@var{expr} and bind @var{var} to the result. However, when an element +of @var{bindings} is just a symbol @var{var}, the result of evaluating +@var{var} is re-bound to @var{var} (which is quite different from the +way @code{let} works). + +The tail of @var{bindings} can be either @code{nil} or a symbol which +should hold a list of arguments, in which case each argument is +evaluated, and the symbol is bound to the resulting list. @end defmac @defmac inline-const-p expression diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index 9b3c4fcb23d..d4505d5c3ff 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -220,7 +220,8 @@ in the *Help* buffer." @group ;; @r{Display the data.} - (help-setup-xref (list 'describe-symbols pattern) (interactive-p)) + (help-setup-xref (list 'describe-symbols pattern) + (called-interactively-p 'interactive)) (with-help-window (help-buffer) (mapcar describe-func (sort sym-list 'string<))))) @end group diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index 325841d8f8a..d70c3543f2a 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -1228,9 +1228,9 @@ the @var{runtime} structure with the value compiled into the module: @example int -emacs_module_init (struct emacs_runtime *ert) +emacs_module_init (struct emacs_runtime *runtime) @{ - if (ert->size < sizeof (*ert)) + if (runtime->size < sizeof (*runtime)) return 1; @} @end example @@ -1247,7 +1247,7 @@ assumes it is part of the @code{emacs_module_init} function shown above: @example - emacs_env *env = ert->get_environment (ert); + emacs_env *env = runtime->get_environment (runtime); if (env->size < sizeof (*env)) return 2; @end example @@ -1264,7 +1264,7 @@ Emacs, by comparing the size of the environment passed by Emacs with known sizes, like this: @example - emacs_env *env = ert->get_environment (ert); + emacs_env *env = runtime->get_environment (runtime); if (env->size >= sizeof (struct emacs_env_26)) emacs_version = 26; /* Emacs 26 or later. */ else if (env->size >= sizeof (struct emacs_env_25)) @@ -1314,7 +1314,8 @@ subsection describes how to write such @dfn{module functions}. A module function has the following general form and signature: -@deftypefn Function emacs_value module_func (emacs_env *@var{env}, ptrdiff_t @var{nargs}, emacs_value *@var{args}, void *@var{data}) +@deftypefn Function emacs_value emacs_function (emacs_env *@var{env}, ptrdiff_t @var{nargs}, emacs_value *@var{args}, void *@var{data}) +@tindex emacs_function The @var{env} argument provides a pointer to the @acronym{API} environment, needed to access Emacs objects and functions. The @var{nargs} argument is the required number of arguments, which can be @@ -1323,7 +1324,7 @@ of the argument number), and @var{args} is a pointer to the array of the function arguments. The argument @var{data} points to additional data required by the function, which was arranged when @code{make_function} (see below) was called to create an Emacs -function from @code{module_func}. +function from @code{emacs_function}. Module functions use the type @code{emacs_value} to communicate Lisp objects between Emacs and the module (@pxref{Module Values}). The @@ -1338,6 +1339,10 @@ However, if the user typed @kbd{C-g}, or if the module function or its callees signaled an error or exited nonlocally (@pxref{Module Nonlocal}), Emacs will ignore the returned value and quit or throw as it does when Lisp code encounters the same situations. + +The header @file{emacs-module.h} provides the type +@code{emacs_function} as an alias type for a function pointer to a +module function. @end deftypefn After writing your C code for a module function, you should make a @@ -1348,11 +1353,11 @@ normally done in the module initialization function (@pxref{module initialization function}), after verifying the @acronym{API} compatibility. -@deftypefn Function emacs_value make_function (emacs_env *@var{env}, ptrdiff_t @var{min_arity}, ptrdiff_t @var{max_arity}, subr @var{func}, const char *@var{docstring}, void *@var{data}) +@deftypefn Function emacs_value make_function (emacs_env *@var{env}, ptrdiff_t @var{min_arity}, ptrdiff_t @var{max_arity}, emacs_function @var{func}, const char *@var{docstring}, void *@var{data}) @vindex emacs_variadic_function This returns an Emacs function created from the C function @var{func}, -whose signature is as described for @code{module_func} above (assumed -here to be @code{typedef}'ed as @code{subr}). The arguments +whose signature is as described for @code{emacs_function} above. +The arguments @var{min_arity} and @var{max_arity} specify the minimum and maximum number of arguments that @var{func} can accept. The @var{max_arity} argument can have the special value @code{emacs_variadic_function}, @@ -1388,7 +1393,7 @@ Combining the above steps, code that arranges for a C function look like this, as part of the module initialization function: @example - emacs_env *env = ert->get_environment (ert); + emacs_env *env = runtime->get_environment (runtime); emacs_value func = env->make_function (env, min_arity, max_arity, module_func, docstring, data); emacs_value symbol = env->intern (env, "module-func"); @@ -1442,6 +1447,54 @@ The Lisp package which goes with your module could then load the module using the @code{load} primitive (@pxref{Dynamic Modules}) when the package is loaded into Emacs. +@anchor{Module Function Finalizers} +If you want to run some code when a module function object (i.e., an +object returned by @code{make_function}) is garbage-collected, you can +install a @dfn{function finalizer}. Function finalizers are available +since Emacs 28. For example, if you have passed some heap-allocated +structure to the @var{data} argument of @code{make_function}, you can +use the finalizer to deallocate the structure. @xref{Basic +Allocation,,,libc}, and @pxref{Freeing after Malloc,,,libc}. The +finalizer function has the following signature: + +@example +void finalizer (void *@var{data}) +@end example + +Here, @var{data} receives the value passed to @var{data} when calling +@code{make_function}. Note that the finalizer can't interact with +Emacs in any way. + +Directly after calling @code{make_function}, the newly-created +function doesn't have a finalizer. Use @code{set_function_finalizer} +to add one, if desired. + +@deftypefun void emacs_finalizer (void *@var{ptr}) +The header @file{emacs-module.h} provides the type +@code{emacs_finalizer} as a type alias for an Emacs finalizer +function. +@end deftypefun + +@deftypefun emacs_finalizer get_function_finalizer (emacs_env *@var{env}, emacs_value @var{arg}) +This function, which is available since Emacs 28, returns the function +finalizer associated with the module function represented by +@var{arg}. @var{arg} must refer to a module function, that is, an +object returned by @code{make_function}. If no finalizer is +associated with the function, @code{NULL} is returned. +@end deftypefun + +@deftypefun void set_function_finalizer (emacs_env *@var{env}, emacs_value @var{arg}, emacs_finalizer @var{fin}) +This function, which is available since Emacs 28, sets the function +finalizer associated with the module function represented by @var{arg} +to @var{fin}. @var{arg} must refer to a module function, that is, an +object returned by @code{make_function}. @var{fin} can either be +@code{NULL} to clear @var{arg}'s function finalizer, or a pointer to a +function to be called when the object represented by @var{arg} is +garbage-collected. At most one function finalizer can be set per +function; if @var{arg} already has a finalizer, it is replaced by +@var{fin}. +@end deftypefun + @node Module Values @subsection Conversion Between Lisp and Module Values @cindex module values, conversion @@ -1541,12 +1594,11 @@ This function returns the value of a Lisp float specified by @var{arg}, as a C @code{double} value. @end deftypefn -@deftypefn Function struct timespec extract_time (emacs_env *@var{env}, emacs_value @var{time}) -This function, which is available since Emacs 27, interprets -@var{time} as an Emacs Lisp time value and returns the corresponding -@code{struct timespec}. @xref{Time of Day}. @code{struct timespec} -represents a timestamp with nanosecond precision. It has the -following members: +@deftypefn Function struct timespec extract_time (emacs_env *@var{env}, emacs_value @var{arg}) +This function, which is available since Emacs 27, interprets @var{arg} +as an Emacs Lisp time value and returns the corresponding @code{struct +timespec}. @xref{Time of Day}. @code{struct timespec} represents a +timestamp with nanosecond precision. It has the following members: @table @code @item time_t tv_sec @@ -1744,9 +1796,9 @@ next_prime (emacs_env *env, ptrdiff_t nargs, emacs_value *args, @} int -emacs_module_init (struct emacs_runtime *ert) +emacs_module_init (struct emacs_runtime *runtime) @{ - emacs_env *env = ert->get_environment (ert); + emacs_env *env = runtime->get_environment (runtime); emacs_value symbol = env->intern (env, "next-prime"); emacs_value func = env->make_function (env, 1, 1, next_prime, NULL, NULL); @@ -1773,16 +1825,15 @@ there's no requirement that @var{time} be normalized. This means that @code{@var{time}.tv_nsec} can be negative or larger than 999,999,999. @end deftypefn -@deftypefn Function emacs_value make_string (emacs_env *@var{env}, const char *@var{str}, ptrdiff_t @var{strlen}) +@deftypefn Function emacs_value make_string (emacs_env *@var{env}, const char *@var{str}, ptrdiff_t @var{len}) This function creates an Emacs string from C text string pointed by @var{str} whose length in bytes, not including the terminating null -byte, is @var{strlen}. The original string in @var{str} can be either -an @acronym{ASCII} string or a UTF-8 encoded non-@acronym{ASCII} -string; it can include embedded null bytes, and doesn't have to end in -a terminating null byte at @code{@var{str}[@var{strlen}]}. The -function raises the @code{overflow-error} error condition if -@var{strlen} is negative or exceeds the maximum length of an Emacs -string. +byte, is @var{len}. The original string in @var{str} can be either an +@acronym{ASCII} string or a UTF-8 encoded non-@acronym{ASCII} string; +it can include embedded null bytes, and doesn't have to end in a +terminating null byte at @code{@var{str}[@var{len}]}. The function +raises the @code{overflow-error} error condition if @var{len} is +negative or exceeds the maximum length of an Emacs string. @end deftypefn The @acronym{API} does not provide functions to manipulate Lisp data @@ -1839,27 +1890,32 @@ garbage-collected. Don't run any expensive code in a finalizer, because GC must finish quickly to keep Emacs responsive. @end deftypefn -@deftypefn Function void *get_user_ptr (emacs_env *@var{env}, emacs_value val) +@deftypefn Function void *get_user_ptr (emacs_env *@var{env}, emacs_value @var{arg}) This function extracts the C pointer from the Lisp object represented -by @var{val}. +by @var{arg}. @end deftypefn -@deftypefn Function void set_user_ptr (emacs_env *@var{env}, emacs_value @var{value}, void *@var{ptr}) +@deftypefn Function void set_user_ptr (emacs_env *@var{env}, emacs_value @var{arg}, void *@var{ptr}) This function sets the C pointer embedded in the @code{user-ptr} -object represented by @var{value} to @var{ptr}. +object represented by @var{arg} to @var{ptr}. @end deftypefn -@deftypefn Function emacs_finalizer get_user_finalizer (emacs_env *@var{env}, emacs_value val) +@deftypefn Function emacs_finalizer get_user_finalizer (emacs_env *@var{env}, emacs_value @var{arg}) This function returns the finalizer of the @code{user-ptr} object -represented by @var{val}, or @code{NULL} if it doesn't have a finalizer. +represented by @var{arg}, or @code{NULL} if it doesn't have a +finalizer. @end deftypefn -@deftypefn Function void set_user_finalizer (emacs_env *@var{env}, emacs_value @var{val}, emacs_finalizer @var{fin}) +@deftypefn Function void set_user_finalizer (emacs_env *@var{env}, emacs_value @var{arg}, emacs_finalizer @var{fin}) This function changes the finalizer of the @code{user-ptr} object -represented by @var{val} to be @var{fin}. If @var{fin} is a -@code{NULL} pointer, the @code{user-ptr} object will have no finalizer. +represented by @var{arg} to be @var{fin}. If @var{fin} is a +@code{NULL} pointer, the @code{user-ptr} object will have no +finalizer. @end deftypefn +Note that the @code{emacs_finalizer} type works for both user pointer +an module function finalizers. @xref{Module Function Finalizers}. + @node Module Misc @subsection Miscellaneous Convenience Functions for Modules @@ -1870,20 +1926,20 @@ be called via the @code{emacs_env} pointer. Description of functions that were introduced after Emacs 25 calls out the first version where they became available. -@deftypefn Function bool eq (emacs_env *@var{env}, emacs_value @var{val1}, emacs_value @var{val2}) +@deftypefn Function bool eq (emacs_env *@var{env}, emacs_value @var{a}, emacs_value @var{b}) This function returns @code{true} if the Lisp objects represented by -@var{val1} and @var{val2} are identical, @code{false} otherwise. This -is the same as the Lisp function @code{eq} (@pxref{Equality -Predicates}), but avoids the need to intern the objects represented by -the arguments. +@var{a} and @var{b} are identical, @code{false} otherwise. This is +the same as the Lisp function @code{eq} (@pxref{Equality Predicates}), +but avoids the need to intern the objects represented by the +arguments. There are no @acronym{API} functions for other equality predicates, so you will need to use @code{intern} and @code{funcall}, described below, to perform more complex equality tests. @end deftypefn -@deftypefn Function bool is_not_nil (emacs_env *@var{env}, emacs_value @var{val}) -This function tests whether the Lisp object represented by @var{val} +@deftypefn Function bool is_not_nil (emacs_env *@var{env}, emacs_value @var{arg}) +This function tests whether the Lisp object represented by @var{arg} is non-@code{nil}; it returns @code{true} or @code{false} accordingly. Note that you could implement an equivalent test by using @@ -1892,12 +1948,12 @@ then use @code{eq}, described above, to test for equality. But using this function is more convenient. @end deftypefn -@deftypefn Function emacs_value type_of (emacs_env *@var{env}, emacs_value @code{object}) -This function returns the type of @var{object} as a value that -represents a symbol: @code{string} for a string, @code{integer} for an -integer, @code{process} for a process, etc. @xref{Type Predicates}. -You can use @code{intern} and @code{eq} to compare against known type -symbols, if your code needs to depend on the object type. +@deftypefn Function emacs_value type_of (emacs_env *@var{env}, emacs_value @code{arg}) +This function returns the type of @var{arg} as a value that represents +a symbol: @code{string} for a string, @code{integer} for an integer, +@code{process} for a process, etc. @xref{Type Predicates}. You can +use @code{intern} and @code{eq} to compare against known type symbols, +if your code needs to depend on the object type. @end deftypefn @anchor{intern} @@ -1917,8 +1973,7 @@ calling the more powerful Emacs @code{intern} function emacs_value fintern = env->intern (env, "intern"); emacs_value sym_name = env->make_string (env, name_str, strlen (name_str)); -emacs_value intern_args[] = @{ sym_name, env->intern (env, "nil") @}; -emacs_value symbol = env->funcall (env, fintern, 2, intern_args); +emacs_value symbol = env->funcall (env, fintern, 1, &sym_name); @end example @end deftypefn @@ -1967,6 +2022,20 @@ variable values and buffer content may have been modified in arbitrary ways. @end deftypefn +@anchor{open_channel} +@deftypefun int open_channel (emacs_env *@var{env}, emacs_value @var{pipe_process}) +This function, which is available since Emacs 28, opens a channel to +an existing pipe process. @var{pipe_process} must refer to an +existing pipe process created by @code{make-pipe-process}. @ref{Pipe +Processes}. If successful, the return value will be a new file +descriptor that you can use to write to the pipe. Unlike all other +module functions, you can use the returned file descriptor from +arbitrary threads, even if no module environment is active. You can +use the @code{write} function to write to the file descriptor. Once +done, close the file descriptor using @code{close}. @ref{Low-Level +I/O,,,libc}. +@end deftypefun + @node Module Nonlocal @subsection Nonlocal Exits in Modules @cindex nonlocal exits, in modules @@ -2071,11 +2140,12 @@ One use of this function is when you want to re-throw a non-local exit from one of the called @acronym{API} or Lisp functions. @end deftypefn -@deftypefn Function void non_local_exit_signal (emacs_env *@var{env}, emacs_value @var{error}, emacs_value @var{data}) -This function signals the error represented by @var{error} with the -specified error data @var{data}. The module function should return -soon after calling this function. This function could be useful, -e.g., for signaling errors from module functions to Emacs. +@deftypefn Function void non_local_exit_signal (emacs_env *@var{env}, emacs_value @var{symbol}, emacs_value @var{data}) +This function signals the error represented by the error symbol +@var{symbol} with the specified error data @var{data}. The module +function should return soon after calling this function. This +function could be useful, e.g., for signaling errors from module +functions to Emacs. @end deftypefn diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index 1e81fb1dc52..130ff0d8671 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -1846,8 +1846,11 @@ local map. @cindex scanning keymaps @cindex keymaps, scanning - This section describes functions used to scan all the current keymaps -for the sake of printing help information. + This section describes functions used to scan all the current +keymaps for the sake of printing help information. To display the +bindings in a particular keymap, you can use the +@code{describe-keymap} command (@pxref{Misc Help, , Other Help +Commands, emacs, The GNU Emacs Manual}) @defun accessible-keymaps keymap &optional prefix This function returns a list of all the keymaps that can be reached (via diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index 2739d10ece9..6833af9c262 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -1170,10 +1170,13 @@ extension, a.k.a.@: ``suffix''. This suffix is platform-dependent. @defvar module-file-suffix This variable holds the system-dependent value of the file-name -extension of the module files. Its value is @file{.so} on POSIX hosts -and @file{.dll} on MS-Windows. +extension of the module files. Its value is @file{.so} on POSIX +hosts, @file{.dylib} on macOS, and @file{.dll} on MS-Windows. @end defvar + On macOS, dynamic modules can also have the suffix @file{.so} in +addition to @file{.dylib}. + @findex emacs_module_init @vindex plugin_is_GPL_compatible Every dynamic module should export a C-callable function named diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index c1615993f5e..cca06c70a51 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -411,6 +411,37 @@ following bindings, in addition to those of @code{minibuffer-local-map}: @end table @end defvar +@vindex minibuffer-default-prompt-format +@defun format-prompt prompt default &rest format-args +Format @var{prompt} with default value @var{default} according to the +@code{minibuffer-default-prompt-format} variable. + +@code{minibuffer-default-prompt-format} is a format string (defaulting +to @samp{" (default %s)"} that says how the ``default'' bit in prompts +like @samp{"Local filename (default somefile): "} are to be formatted. + +To allow the users to customize how this is displayed, code that +prompts the user for a value (and has a default) should look something +along the lines of this code snippet: + +@lisp +(read-file-name + (format-prompt "Local filename" file) + nil file) +@end lisp + +If @var{format-args} is @code{nil}, @var{prompt} is used as a literal +string. If @var{format-args} is non-@code{nil}, @var{prompt} is used +as a format control string, and @var{prompt} and @var{format-args} are +passed to @code{format} (@pxref{Formatting Strings}). + +@code{minibuffer-default-prompt-format} can be @samp{""}, in which +case no default values are displayed. + +If @var{default} is @code{nil}, there is no default value, and +therefore no ``default value'' string is included in the result value. +@end defun + @node Object from Minibuffer @section Reading Lisp Objects with the Minibuffer @cindex minibuffer input, reading lisp objects @@ -646,6 +677,15 @@ A history list for variable-name arguments read by @code{read-variable}. @end defvar +@defvar read-number-history +A history list for numbers read by @code{read-number}. +@end defvar + +@defvar goto-line-history +A history list for arguments to @code{goto-line}. This variable is +buffer local. +@end defvar + @c Less common: coding-system-history, input-method-history, @c command-history, grep-history, grep-find-history, @c read-envvar-name-history, setenv-history, yes-or-no-p-history. diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index 4edda793e07..fa5f18e2023 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -469,9 +469,10 @@ variable @code{imenu-generic-expression}, for the two variables @code{imenu-create-index-function} (@pxref{Imenu}). @item -The mode can specify a local value for -@code{eldoc-documentation-function} to tell ElDoc mode how to handle -this mode. +The mode can tell ElDoc mode how to retrieve different types of +documentation for whatever is at point, by adding one or more +buffer-local entries to the special hook +@code{eldoc-documentation-functions}. @item The mode can specify how to complete various keywords by adding one or @@ -1352,19 +1353,11 @@ illustrate how these modes are written. @end smallexample The three modes for Lisp share much of their code. For instance, -each calls the following function to set various variables: - -@smallexample -@group -(defun lisp-mode-variables (&optional syntax keywords-case-insensitive elisp) - (when syntax - (set-syntax-table lisp-mode-syntax-table)) - @dots{} -@end group -@end smallexample +Lisp mode and Emacs Lisp mode inherit from Lisp Data mode and Lisp +Interaction Mode inherits from Emacs Lisp mode. @noindent -Amongst other things, this function sets up the @code{comment-start} +Amongst other things, Lisp Data mode sets up the @code{comment-start} variable to handle Lisp comments: @smallexample @@ -1414,7 +1407,7 @@ Finally, here is the major mode command for Lisp mode: @smallexample @group -(define-derived-mode lisp-mode prog-mode "Lisp" +(define-derived-mode lisp-mode lisp-data-mode "Lisp" "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp. Commands: Delete converts tabs to spaces as it moves back. @@ -1425,10 +1418,9 @@ Note that `run-lisp' may be used either to start an inferior Lisp job or to switch back to an existing one." @end group @group - (lisp-mode-variables nil t) (setq-local find-tag-default-function 'lisp-find-tag-default) (setq-local comment-start-skip - "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *") + "\\(\\(^\\|[^\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *") (setq imenu-case-fold-search t)) @end group @end smallexample @@ -2674,6 +2666,7 @@ Setting this variable makes it buffer-local in the current buffer. @node Font Lock Mode @section Font Lock Mode @cindex Font Lock mode +@cindex syntax highlighting and coloring @dfn{Font Lock mode} is a buffer-local minor mode that automatically attaches @code{face} properties to certain parts of the buffer based on diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index 5c5f89eb433..83066744121 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -2339,8 +2339,12 @@ same sequence of character codes and all these codes are in the range @end group @end example -However, two distinct buffers are never considered @code{equal}, even if -their textual contents are the same. +The @code{equal} function recursively compares the contents of objects +if they are integers, strings, markers, vectors, bool-vectors, +byte-code function objects, char-tables, records, or font objects. +Other objects are considered @code{equal} only if they are @code{eq}. +For example, two distinct buffers are never considered @code{equal}, +even if their textual contents are the same. @end defun For @code{equal}, equality is defined recursively; for example, given diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index b31ab87ff17..504f0dfb23e 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -1701,7 +1701,8 @@ following form: @noindent The format of this list is the same as what @code{decode-time} accepts (@pxref{Time Conversion}), and is described in more detail there. Any -element that cannot be determined from the input will be set to +@code{dst} element that cannot be determined from the input is set to +@minus{}1, and any other unknown element is set to @code{nil}. The argument @var{string} should resemble an RFC 822 (or later) or ISO 8601 string, like ``Fri, 25 Mar 2016 16:24:56 +0100'' or ``1998-09-12T12:21:54-0200'', but this function will attempt to parse @@ -2193,9 +2194,9 @@ cause anything special to happen. @findex list-timers The @code{list-timers} command lists all the currently active timers. -There's only one command available in the buffer displayed: @kbd{c} -(@code{timer-list-cancel}) that will cancel the timer on the line -under point. +The command @kbd{c} (@code{timer-list-cancel}) will cancel the timer +on the line under point. You can sort the list by column using the +command @kbd{S} (@code{tabulated-list-sort}). @node Idle Timers @section Idle Timers @@ -2686,9 +2687,9 @@ Emacs is restarted by the session manager. @group (defun save-yourself-test () - (insert "(save-current-buffer - (switch-to-buffer \"*scratch*\") - (insert \"I am restored\"))") + (insert + (format "%S" '(with-current-buffer "*scratch*" + (insert "I am restored")))) nil) @end group @end example @@ -3137,7 +3138,7 @@ being reported. For example: @end group @group -(set-file-modes "/tmp/foo" (default-file-modes)) +(set-file-modes "/tmp/foo" (default-file-modes) 'nofollow) @result{} Event (35025468 attribute-changed "/tmp/foo") @end group @end example diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi index d7856ce73e3..751adcff5a8 100644 --- a/doc/lispref/positions.texi +++ b/doc/lispref/positions.texi @@ -332,6 +332,8 @@ if provided; otherwise @var{n} defaults to @code{nil}. @node Text Lines @subsection Motion by Text Lines @cindex lines +@cindex logical lines, moving by +@cindex physical lines, moving by Text lines are portions of the buffer delimited by newline characters, which are regarded as part of the previous line. The first text line @@ -411,7 +413,7 @@ function counts that line as one line successfully moved. In an interactive call, @var{count} is the numeric prefix argument. @end deffn -@defun count-lines start end +@defun count-lines start end &optional ignore-invisible-lines @cindex lines in region @anchor{Definition of count-lines} This function returns the number of lines between the positions @@ -420,6 +422,9 @@ This function returns the number of lines between the positions 1, even if @var{start} and @var{end} are on the same line. This is because the text between them, considered in isolation, must contain at least one line unless it is empty. + +If the optional @var{ignore-invisible-lines} is non-@code{nil}, +invisible lines will not be included in the count. @end defun @deffn Command count-words start end @@ -515,6 +520,7 @@ beginning or end of a line. @node Screen Lines @subsection Motion by Screen Lines @cindex screen lines, moving by +@cindex visual lines, moving by The line functions in the previous section count text lines, delimited only by newline characters. By contrast, these functions count screen diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index 6970f718ee0..4002004cd6f 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -477,6 +477,22 @@ You should only ever change this variable with a let-binding; never with @code{setq}. @end defvar +@defopt process-file-return-signal-string +This user option indicates whether a call of @code{process-file} +returns a string describing the signal interrupting a remote process. + +When a process returns an exit code greater than 128, it is +interpreted as a signal. @code{process-file} requires to return a +string describing this signal. + +Since there are processes violating this rule, returning exit codes +greater than 128 which are not bound to a signal, @code{process-file} +returns always the exit code as natural number for remote processes. +Setting this user option to non-nil forces @code{process-file} to +interpret such exit codes as signals, and to return a corresponding +string. +@end defopt + @defun call-process-region start end program &optional delete destination display &rest args This function sends the text from @var{start} to @var{end} as standard input to a process running @var{program}. It deletes the text @@ -743,6 +759,7 @@ Some file name handlers may not support @code{make-process}. In such cases, this function does nothing and returns @code{nil}. @end defun +@anchor{Pipe Processes} @defun make-pipe-process &rest args This function creates a bidirectional pipe which can be attached to a child process. This is useful with the @code{:stderr} keyword of @@ -2426,18 +2443,15 @@ server is stopped; a non-@code{nil} value means yes. @cindex encrypted network connections @cindex @acronym{TLS} network connections @cindex @acronym{STARTTLS} network connections -Emacs can create encrypted network connections, using either built-in -or external support. The built-in support uses the GnuTLS -Transport Layer Security Library; see +Emacs can create encrypted network connections, using the built-in +support for the GnuTLS Transport Layer Security Library; see @uref{https://www.gnu.org/software/gnutls/, the GnuTLS project page}. If your Emacs was compiled with GnuTLS support, the function @code{gnutls-available-p} is defined and returns non-@code{nil}. For more details, @pxref{Top,, Overview, emacs-gnutls, The Emacs-GnuTLS manual}. -The external support uses the @file{starttls.el} library, which -requires a helper utility such as @command{gnutls-cli} to be installed -on the system. The @code{open-network-stream} function can -transparently handle the details of creating encrypted connections for -you, using whatever support is available. +The @code{open-network-stream} function can transparently handle the +details of creating encrypted connections for you, using whatever +support is available. @defun open-network-stream name buffer host service &rest parameters This function opens a TCP connection, with optional encryption, and @@ -2465,6 +2479,12 @@ that are mainly relevant to encrypted connections: @item :nowait @var{boolean} If non-@code{nil}, try to make an asynchronous connection. +@item :coding @var{coding} +Use this to set the coding systems used by the network process, in +preference to binding @code{coding-system-for-read} or +@code{coding-system-for-write}. @xref{Network Processes}, for +details. + @item :type @var{type} The type of connection. Options are: @@ -2491,7 +2511,10 @@ If non-@code{nil}, always ask for the server's capabilities, even when doing a @samp{plain} connection. @item :capability-command @var{capability-command} -Command string to query the host capabilities. +Command to query the host capabilities. This can either be a string +(which will then be sent verbatim to the server), or a function +(called with a single parameter; the "greeting" from the server when +connecting), and should return a string. @item :end-of-command @var{regexp} @itemx :end-of-capability @var{regexp} diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi index c8a12bdd66b..b6242c539b7 100644 --- a/doc/lispref/searching.texi +++ b/doc/lispref/searching.texi @@ -342,7 +342,7 @@ this choice, the rest of the regexp matches successfully. long time, if they lead to ambiguous matching. For example, trying to match the regular expression @samp{\(x+y*\)*a} against the string @samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz} could -take hours before it ultimately fails. Emacs must try each way of +take hours before it ultimately fails. Emacs may try each way of grouping the @samp{x}s before concluding that none of them can work. In general, avoid expressions that can match the same string in multiple ways. diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 0dc47f30c43..8de6255478b 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -1157,7 +1157,7 @@ The function @code{format-spec} described in this section performs a similar function to @code{format}, except it operates on format control strings that use arbitrary specification characters. -@defun format-spec template spec-alist &optional only-present +@defun format-spec template spec-alist &optional ignore-missing This function returns a string produced from the format string @var{template} according to conversions specified in @var{spec-alist}, which is an alist (@pxref{Association Lists}) of the form @@ -1190,12 +1190,15 @@ The order of specifications in @var{template} need not correspond to the order of associations in @var{spec-alist}. @end itemize -The optional argument @var{only-present} indicates how to handle +The optional argument @var{ignore-missing} indicates how to handle specification characters in @var{template} that are not found in @var{spec-alist}. If it is @code{nil} or omitted, the function -signals an error. Otherwise, those format specifications and any -occurrences of @samp{%%} in @var{template} are left verbatim in the -output, including their text properties, if any. +signals an error; if it is @code{ignore}, those format specifications +are left verbatim in the output, including their text properties, if +any; if it is @code{delete}, those format specifications are removed +from the output; any other non-@code{nil} value is handled like +@code{ignore}, but any occurrences of @samp{%%} are also left verbatim +in the output. @end defun The syntax of format specifications accepted by @code{format-spec} is @@ -1243,7 +1246,7 @@ the right rather than the left. @item < This flag causes the substitution to be truncated on the left to the -given width, if specified. +given width and precision, if specified. @item > This flag causes the substitution to be truncated on the right to the @@ -1262,9 +1265,12 @@ The result of using contradictory flags (for instance, both upper and lower case) is undefined. As is the case with @code{format}, a format specification can include -a width, which is a decimal number that appears after any flags. If a -substitution contains fewer characters than its specified width, it is -padded on the left: +a width, which is a decimal number that appears after any flags, and a +precision, which is a decimal-point @samp{.} followed by a decimal +number that appears after any flags and width. + +If a substitution contains fewer characters than its specified width, +it is padded on the left: @example @group @@ -1274,6 +1280,17 @@ padded on the left: @end group @end example +If a substitution contains more characters than its specified +precision, it is truncated on the right: + +@example +@group +(format-spec "%.2a is truncated on the right" + '((?a . "alpha"))) + @result{} "al is truncated on the right" +@end group +@end example + Here is a more complicated example that combines several aforementioned features: diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 5d83e7bd6cc..3a4cf6b5723 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -4813,11 +4813,9 @@ When @var{noerror} is non-@code{nil}, this function silently uses @code{raw-text} coding instead. @item (@code{iv-auto} @var{length}) -This will generate an IV (Initialization Vector) of the specified -length using the GnuTLS @code{GNUTLS_RND_NONCE} generator and pass it -to the function. This ensures that the IV is unpredictable and -unlikely to be reused in the same session. The actual value of the IV -is returned by the function as described below. +This generates a random IV (Initialization Vector) of the specified +length and passes it to the function. This ensures that the IV is +unpredictable and unlikely to be reused in the same session. @end table @@ -5101,6 +5099,9 @@ The following are functions for altering the @acronym{DOM}. @item dom-set-attribute @var{node} @var{attribute} @var{value} Set the @var{attribute} of the node to @var{value}. +@item dom-remove-attribute @var{node} @var{attribute} +Remove @var{attribute} from @var{node}. + @item dom-append-child @var{node} @var{child} Append @var{child} as the last child of @var{node}. @@ -5153,6 +5154,11 @@ Utility functions: @item dom-pp @var{dom} &optional @var{remove-empty} Pretty-print @var{dom} at point. If @var{remove-empty}, don't print textual nodes that just contain white-space. + +@item dom-print @var{dom} &optional @var{pretty} @var{xml} +Print @var{dom} at point. If @var{xml} is non-@code{nil}, print as +@acronym{XML}; otherwise, print as @acronym{HTML}. If @var{pretty} is +non-@code{nil}, indent the @acronym{HTML}/@acronym{XML} logically. @end table diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index 5b09b2ccea6..1826e8f7b42 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -918,29 +918,56 @@ values. It is much better to convert such comments to documentation strings, though. @item ;;; -Comments that start with three semicolons, @samp{;;;}, should start at -the left margin. We use them -for comments which should be considered a -heading by Outline minor mode. By default, comments starting with -at least three semicolons (followed by a single space and a -non-whitespace character) are considered headings, comments starting -with two or fewer are not. Historically, triple-semicolon comments have -also been used for commenting out lines within a function, but this use -is discouraged. - -When commenting out entire functions, use two semicolons. - -@item ;;;; -Comments that start with four (or more) semicolons, @samp{;;;;}, -should be aligned to the left margin and are used for headings of -major sections of a program. For example: + +Comments that start with three (or more) semicolons, @samp{;;;}, +should start at the left margin. We use them for comments that should +be considered a heading by Outline minor mode. By default, comments +starting with at least three semicolons (followed by a single space +and a non-whitespace character) are considered section headings, +comments starting with two or fewer are not. + +(Historically, triple-semicolon comments have also been used for +commenting out lines within a function, but this use is discouraged in +favor of using just two semicolons. This also applies when commenting +out entire functions; when doing that use two semicolons as well.) + +Three semicolons are used for top-level sections, four for +sub-sections, five for sub-sub-sections and so on. + +Typically libraries have at least four top-level sections. For +example when the bodies of all of these sections are hidden: @smallexample -;;;; The kill ring +@group +;;; backquote.el --- implement the ` Lisp construct... +;;; Commentary:... +;;; Code:... +;;; backquote.el ends here +@end group @end smallexample -If you wish to have sub-headings under these heading, use more -semicolons to nest these sub-headings. +(In a sense the last line is not a section heading as it must +never be followed by any text; after all it marks the end of the +file.) + +For longer libraries it is advisable to split the code into multiple +sections. This can be done by splitting the @samp{Code:} section into +multiple sub-sections. Even though that was the only recommended +approach for a long time, many people have chosen to use multiple +top-level code sections instead. You may chose either style. + +Using multiple top-level code sections has the advantage that it +avoids introducing an additional nesting level but it also means that +the section named @samp{Code} does not contain all the code, which is +awkward. To avoid that, you should put no code at all inside that +section; that way it can be considered a seperator instead of a +section heading. + +Finally, we recommend that you don't end headings with a colon or any +other punctuation for that matter. For historic reasons the +@samp{Code:} and @samp{Commentary:} headings end with a colon, but we +recommend that you don't do the same for other headings anyway. + @end table @noindent diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index abcd4bbd0f7..94c8c88796f 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -2585,8 +2585,11 @@ implemented this way: (macroexp-let2* nil ((start from) (end to)) (funcall do `(substring ,getter ,start ,end) (lambda (v) - (funcall setter `(cl--set-substring - ,getter ,start ,end ,v)))))))) + (macroexp-let2 nil v v + `(progn + ,(funcall setter `(cl--set-substring + ,getter ,start ,end ,v)) + ,v)))))))) @end example @end defmac diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index a19f123c658..5ec23a9c876 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -3048,6 +3048,16 @@ since there is no guarantee that an arbitrary caller of @code{display-buffer} will be able to handle the case that no window will display the buffer. @code{display-buffer-no-window} is the only action function that cares about this entry. + +@vindex body-function@r{, a buffer display action alist entry} +@item body-function +The value must be a function taking one argument (a displayed window). +This function can be used to fill the displayed window's body with +some contents that might depend on dimensions of the displayed window. +It is called @emph{after} the buffer is displayed, and @emph{before} +the entries @code{window-height}, @code{window-width} and +@code{preserve-size} are applied that could resize the window to fit +it to the inserted contents. @end table By convention, the entries @code{window-height}, @code{window-width} @@ -5916,10 +5926,6 @@ This function compares two window configurations as regards the structure of windows, but ignores the values of point and the saved scrolling positions---it can return @code{t} even if those aspects differ. - -The function @code{equal} can also compare two window configurations; it -regards configurations as unequal if they differ in any respect, even a -saved point. @end defun @defun window-configuration-frame config diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi index f9196f808e7..1dab29b8a5a 100644 --- a/doc/misc/calc.texi +++ b/doc/misc/calc.texi @@ -35164,16 +35164,7 @@ which are called at various times. Calc defines a number of hooks that help you to customize it in various ways. Calc uses the Lisp function @code{run-hooks} to invoke the hooks shown below. Several other customization-related variables are also described here. - -@defvar calc-load-hook -This hook is called at the end of @file{calc.el}, after the file has -been loaded, before any functions in it have been called, but after -@code{calc-mode-map} and similar variables have been set up. -@end defvar - -@defvar calc-ext-load-hook -This hook is called at the end of @file{calc-ext.el}. -@end defvar +To run code after Calc has loaded, use @code{with-eval-after-load}. @defvar calc-start-hook This hook is called as the last step in a @kbd{M-x calc} command. diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi index 544ff853351..adc233d99dd 100644 --- a/doc/misc/cc-mode.texi +++ b/doc/misc/cc-mode.texi @@ -350,11 +350,12 @@ Line-Up Functions * Misc Line-Up:: -Customizing Macros +Custom Macros * Macro Backslashes:: * Macros with ;:: * Noise Macros:: +* Indenting Directives:: @end detailmenu @end menu @@ -1023,9 +1024,7 @@ These key sequences are not bound in AWK Mode, which doesn't have preprocessor statements. @item @kbd{M-x c-backward-into-nomenclature} -@itemx @kbd{M-x c-forward-into-nomenclature} @findex c-backward-into-nomenclature -@findex c-forward-into-nomenclature @findex backward-into-nomenclature @r{(c-)} @findex forward-into-nomenclature @r{(c-)} A popular programming style, especially for object-oriented languages @@ -2131,6 +2130,11 @@ For Pike autodoc markup, the standard in Pike. @item gtkdoc @cindex GtkDoc markup For GtkDoc markup, widely used in the Gnome community. + +@item doxygen +@cindex Doxygen markup +For Doxygen markup, which can be used with C, C++, Java and variety of +other languages. @end table The above is by no means complete. If you'd like to see support for @@ -6389,6 +6393,26 @@ function is the same as specifying a list @code{(c-lineup-assignments @comment ------------------------------------------------------------ +@defun c-lineup-ternary-bodies +@findex lineup-ternary-bodies @r{(c-)} +Line up true and false branches of a ternary operator +(i.e. @code{?:}). More precisely, if the line starts with a colon +which is a part of a said operator, align it with corresponding +question mark. For example: + +@example +@group +return arg % 2 == 0 ? arg / 2 + : (3 * arg + 1); @hereFn{c-lineup-ternary-bodies} +@end group +@end example + +@workswith @code{arglist-cont}, @code{arglist-cont-nonempty} and +@code{statement-cont}. +@end defun + +@comment ------------------------------------------------------------ + @defun c-lineup-cascaded-calls @findex lineup-cascaded-calls @r{(c-)} Line up ``cascaded calls'' under each other. If the line begins with @@ -6949,6 +6973,10 @@ is @code{nil}, all lines inside macro definitions are analyzed as @code{cpp-macro-cont}. @end defopt +Sometimes you may want to indent particular directives +(e.g. @code{#pragma}) as though they were statements. To do this, see +@ref{Indenting Directives}. + Because a macro can expand into anything at all, near where one is invoked @ccmode{} can only indent and fontify code heuristically. Sometimes it gets it wrong. Usually you should try to design your @@ -6965,6 +6993,7 @@ Macros}. * Macro Backslashes:: * Macros with ;:: * Noise Macros:: +* Indenting Directives:: @end menu @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @@ -7074,7 +7103,7 @@ initialization code, after the mode hooks have run. @end defun @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Noise Macros, , Macros with ;, Custom Macros +@node Noise Macros, Indenting Directives, Macros with ;, Custom Macros @comment node-name, next, previous, up @section Noise Macros @cindex noise macros @@ -7131,6 +7160,48 @@ after the mode hooks have run. @end defun @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Indenting Directives, , Noise Macros, Custom Macros +@comment node-name, next, previous, up +@section Indenting Directives +@cindex Indenting Directives +@cindex Indenting #pragma +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +Sometimes you may want to indent particular preprocessor directives +(e.g. @code{#pragma}) as though they were statements. To do this, +first set up @code{c-cpp-indent-to-body-directives} to include the +directive name(s), then enable the ``indent to body'' feature with +@code{c-toggle-cpp-indent-to-body}. + +@defopt c-cpp-indent-to-body-directives +@vindex cpp-indent-to-body-directives (c-) +This variable is a list of names of CPP directives (not including the +introducing @samp{#}) which will be indented as though statements. +Each element is a string, and must be a valid identifier. The default +value is @code{("pragma")}. + +If you add more directives to this variable, or remove directives from +it, whilst ``indent to body'' is active, you need to re-enable the +feature by calling @code{c-toggle-cpp-indent-to-body} for these +changes to take effect@footnote{Note that the removal of directives +doesn't work satisfactorally on XEmacs or on very old versions of +Emacs}. +@end defopt + +@defun c-toggle-cpp-indent-to-body +@findex toggle-cpp-indent-to-body (c-) +With @kbd{M-x c-toggle-cpp-indent-to-body}, you enable or disable the +``indent to body'' feature. When called programmatically, it takes an +optional numerical argument. A positive value will enable the +feature, a zero or negative value will disable it. + +You should set up @code{c-cpp-indent-to-body-directives} before +calling this function, since the function sets internal state which +depends on that variable. +@end defun + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Odds and Ends, Sample Init File, Custom Macros, Top @comment node-name, next, previous, up @chapter Odds and Ends diff --git a/doc/misc/dired-x.texi b/doc/misc/dired-x.texi index 5965da16bb7..d7497806602 100644 --- a/doc/misc/dired-x.texi +++ b/doc/misc/dired-x.texi @@ -185,13 +185,12 @@ In your @file{~/.emacs} file, or in the system-wide initialization file @file{default.el} in the @file{site-lisp} directory, put @example -(add-hook 'dired-load-hook - (lambda () - (load "dired-x") - ;; Set dired-x global variables here. For example: - ;; (setq dired-guess-shell-gnutar "gtar") - ;; (setq dired-x-hands-off-my-keys nil) - )) +(with-eval-after-load 'dired + (require 'dired-x) + ;; Set dired-x global variables here. For example: + ;; (setq dired-guess-shell-gnutar "gtar") + ;; (setq dired-x-hands-off-my-keys nil) + )) (add-hook 'dired-mode-hook (lambda () ;; Set dired-x buffer-local variables here. For example: @@ -242,12 +241,10 @@ If you choose to have @file{dired-x.el} bind @code{dired-x-find-file} over or call @code{dired-x-bind-find-file} after changing the value. @example -(add-hook 'dired-load-hook - (lambda () - ;; Bind dired-x-find-file. - (setq dired-x-hands-off-my-keys nil) - (load "dired-x") - )) +(with-eval-after-load 'dired + ;; Bind dired-x-find-file. + (setq dired-x-hands-off-my-keys nil) + (require 'dired-x)) @end example @node Omitting Files in Dired @@ -294,8 +291,8 @@ Marked files are never omitted. @end table @noindent -In order to make Dired Omit work you first need to load @file{dired-x.el} -inside @code{dired-load-hook} (@pxref{Installation}) and then evaluate +In order to make Dired Omit work you need to load @file{dired-x} +after loading @file{dired} (@pxref{Installation}) and then evaluate @code{(dired-omit-mode 1)} in some way (@pxref{Omitting Variables}). @ifnottex @@ -410,7 +407,7 @@ The default value is @kbd{C-o}. @item @cindex RCS files, how to omit them in Dired @cindex omitting RCS files in Dired -If you wish to avoid seeing RCS files and the @file{RCS} directory, then put +If you wish to avoid seeing RCS files and the @file{RCS} directory, then use @example (setq dired-omit-files @@ -418,7 +415,7 @@ If you wish to avoid seeing RCS files and the @file{RCS} directory, then put @end example @noindent -in the @code{dired-load-hook} (@pxref{Installation}). This assumes +after loading @file{dired-x} (@pxref{Installation}). This assumes @code{dired-omit-localp} has its default value of @code{no-dir} to make the @code{^}-anchored matches work. As a slower alternative, with @code{dired-omit-localp} set to @code{nil}, you can use @code{/} instead of @@ -429,7 +426,7 @@ in the @code{dired-load-hook} (@pxref{Installation}). This assumes @cindex omitting tib files in Dired If you use @code{tib}, the bibliography program for use with @TeX{} and @LaTeX{}, and you -want to omit the @file{INDEX} and the @file{*-t.tex} files, then put +want to omit the @file{INDEX} and the @file{*-t.tex} files, then use @example (setq dired-omit-files @@ -437,13 +434,13 @@ want to omit the @file{INDEX} and the @file{*-t.tex} files, then put @end example @noindent -in the @code{dired-load-hook} (@pxref{Installation}). +after loading @file{dired-x} (@pxref{Installation}). @item @cindex dot files, how to omit them in Dired @cindex omitting dot files in Dired If you do not wish to see @samp{dot} files (files starting with a @file{.}), -then put +then use @example (setq dired-omit-files @@ -451,7 +448,7 @@ then put @end example @noindent -in the @code{dired-load-hook} (@pxref{Installation}). (Of course, a +after loading @file{dired-x} (@pxref{Installation}). (Of course, a better way to achieve this particular goal is simply to omit @samp{-a} from @code{dired-listing-switches}.) @@ -830,7 +827,7 @@ When installed @file{dired-x} will substitute @code{dired-x-find-file} for (normally bound to @kbd{C-x 4 C-f}). In order to use this feature, you will need to set -@code{dired-x-hands-off-my-keys} to @code{nil} inside @code{dired-load-hook} +@code{dired-x-hands-off-my-keys} to @code{nil} before loading @file{dired-x} (@pxref{Optional Installation File At Point}). @table @code diff --git a/doc/misc/ediff.texi b/doc/misc/ediff.texi index 99ba89b0d7f..1ef13716b11 100644 --- a/doc/misc/ediff.texi +++ b/doc/misc/ediff.texi @@ -1197,10 +1197,6 @@ refer to Emacs manual for the information on how to set Emacs X resources. The bulk of customization can be done via the following hooks: @table @code -@item ediff-load-hook -@vindex ediff-load-hook -This hook can be used to change defaults after Ediff is loaded. - @item ediff-before-setup-hook @vindex ediff-before-setup-hook Hook that is run just before Ediff rearranges windows to its liking. @@ -1211,8 +1207,8 @@ Can be used to save windows configuration. @vindex ediff-mode-map This hook can be used to alter bindings in Ediff's keymap, @code{ediff-mode-map}. These hooks are -run right after the default bindings are set but before -@code{ediff-load-hook}. The regular user needs not be concerned with this +run right after the default bindings are set. +The regular user needs not be concerned with this hook---it is provided for implementers of other Emacs packages built on top of Ediff. @@ -1545,12 +1541,13 @@ directly (using @kbd{j}) to any numbered difference. Users can supply their own functions to specify how Ediff should do -selective browsing. To change the default Ediff function, add a function to -@code{ediff-load-hook} which will do the following assignments: +selective browsing. To change the default Ediff function, use +something like the following: @example -(setq ediff-hide-regexp-matches-function 'your-hide-function) -(setq ediff-focus-on-regexp-matches-function 'your-focus-function) +(with-eval-after-load 'ediff + (setq ediff-hide-regexp-matches-function 'your-hide-function) + (setq ediff-focus-on-regexp-matches-function 'your-focus-function)) @end example @strong{Useful hint}: To specify a regexp that matches everything, don't @@ -1728,23 +1725,17 @@ difference region in buffer A (this face is not a good choice, by the way). If you are unhappy with just @emph{some} of the aspects of the default faces, you can modify them when Ediff is being loaded using -@code{ediff-load-hook}. For instance: +@code{with-eval-after-load}. For instance: @smallexample -(add-hook 'ediff-load-hook - (lambda () - (set-face-foreground - ediff-current-diff-face-B "blue") - (set-face-background - ediff-current-diff-face-B "red") - (make-face-italic - ediff-current-diff-face-B))) +(with-eval-after-load 'ediff + (set-face-foreground + ediff-current-diff-face-B "blue") + (set-face-background + ediff-current-diff-face-B "red") + (make-face-italic ediff-current-diff-face-B)) @end smallexample -@strong{Please note:} to set Ediff's faces, use only @code{copy-face} -or @code{set/make-face-@dots{}} as shown above. Emacs's low-level -face-manipulation functions should be avoided. - @node Narrowing @section Narrowing diff --git a/doc/misc/efaq.texi b/doc/misc/efaq.texi index f948a489f44..3c1244101f4 100644 --- a/doc/misc/efaq.texi +++ b/doc/misc/efaq.texi @@ -1595,6 +1595,10 @@ xterm-direct2 xterm with direct-color indexing (old) xterm-direct xterm with direct-color indexing @end example +If Terminfo database is not available, but 24-bit direct color mode is +supported, it can still be enabled by defining the environment +variable @env{COLORTERM} to @samp{truecolor}. + Terminals with @samp{RGB} capability treat pixels #000001 - #000007 as indexed colors to maintain backward compatibility with applications that are unaware of direct color mode. Therefore the seven darkest @@ -2515,9 +2519,8 @@ To avoid seeing backup files (and other ``uninteresting'' files) in Dired, load @code{dired-x} by adding the following to your @file{.emacs} file: @lisp -(add-hook 'dired-load-hook - (lambda () - (require 'dired-x))) +(with-eval-after-load 'dired + (require 'dired-x)) @end lisp With @code{dired-x} loaded, @kbd{M-o} toggles omitting in each dired buffer. @@ -3461,7 +3464,6 @@ see @ref{Packages that do not come with Emacs}. @cindex Finding other packages @cindex Lisp packages that do not come with Emacs @cindex Packages, those that do not come with Emacs -@cindex Emacs Lisp List @cindex Emacs Lisp Archive The easiest way to add more features to your Emacs is to use the @@ -3497,10 +3499,6 @@ The @uref{https://emacswiki.org, Emacs Wiki} contains pointers to some additional extensions. @uref{https://wikemacs.org, WikEmacs} is an alternative wiki for Emacs. -@uref{http://www.damtp.cam.ac.uk/user/sje30/emacs/ell.html, The Emacs -Lisp List (ELL)}, has pointers to many Emacs Lisp files, but at time -of writing it is no longer being updated. - It is impossible for us to list here all the sites that offer Emacs Lisp packages. If you are interested in a specific feature, then after checking Emacs itself and GNU ELPA, a web search is often the @@ -4189,7 +4187,7 @@ You can get the old behavior by binding @kbd{SPC} to (define-key minibuffer-local-filename-completion-map (kbd "SPC") 'minibuffer-complete-word) -(define-key minibuffer-local-must-match-filename-map (kbd "SPC") +(define-key minibuffer-local-filename-must-match-map (kbd "SPC") 'minibuffer-complete-word) @end lisp diff --git a/doc/misc/eieio.texi b/doc/misc/eieio.texi index aceaff051e3..8dd394cb848 100644 --- a/doc/misc/eieio.texi +++ b/doc/misc/eieio.texi @@ -698,6 +698,27 @@ and argument-order conventions are similar to those used for referencing vectors (@pxref{Vectors,,,elisp,GNU Emacs Lisp Reference Manual}). +@defmac oref obj slot +@anchor{oref} +This macro retrieves the value stored in @var{obj} in the named +@var{slot}. Slot names are determined by @code{defclass} which +creates the slot. + +This is a generalized variable that can be used with @code{setf} to +modify the value stored in @var{slot}. @xref{Generalized +Variables,,,elisp,GNU Emacs Lisp Reference Manual}. +@end defmac + +@defmac oref-default class slot +@anchor{oref-default} +This macro returns the value of the class-allocated @var{slot} from +@var{class}. + +This is a generalized variable that can be used with @code{setf} to +modify the value stored in @var{slot}. @xref{Generalized +Variables,,,elisp,GNU Emacs Lisp Reference Manual}. +@end defmac + @defmac oset object slot value This macro sets the value behind @var{slot} to @var{value} in @var{object}. It returns @var{value}. @@ -716,17 +737,6 @@ changed, this can be arranged by simply executing this bit of code: @end example @end defmac -@defmac oref obj slot -@anchor{oref} -Retrieve the value stored in @var{obj} in the slot named by @var{slot}. -Slot is the name of the slot when created by @dfn{defclass}. -@end defmac - -@defmac oref-default class slot -@anchor{oref-default} -Get the value of the class-allocated @var{slot} from @var{class}. -@end defmac - The following accessors are defined by CLOS to reference or modify slot values, and use the previously mentioned set/ref routines. diff --git a/doc/misc/emacs-gnutls.texi b/doc/misc/emacs-gnutls.texi index 7c57cc032c7..bb13ebdf238 100644 --- a/doc/misc/emacs-gnutls.texi +++ b/doc/misc/emacs-gnutls.texi @@ -190,7 +190,7 @@ the connection process. The optional @var{parameters} argument is a list of keywords and values. The only keywords which currently have any effect are -@code{:client-certificate} and @code{:nowait}. +@code{:client-certificate}, @code{:nowait}, and @code{:coding}. Passing @w{@code{:client certificate t}} triggers looking up of client certificates matching @var{host} and @var{service} using the diff --git a/doc/misc/emacs-mime.texi b/doc/misc/emacs-mime.texi index 42a7750b9ac..9180b4ec205 100644 --- a/doc/misc/emacs-mime.texi +++ b/doc/misc/emacs-mime.texi @@ -472,6 +472,13 @@ the case if you save it to disk and launch it in a different way to launch any external programs, set this variable to @code{nil} or @code{ask}. +@item mm-inline-font-lock +@vindex mm-inline-font-lock +If non-@code{nil}, inlined parts that support font locking (for +instance, patches or code snippets) will be font-locked. This may be +overriden by callers that have their own ways of enabling/inhibiting +font locking. + @end table @node Files and Directories @@ -686,8 +693,17 @@ Valid values are @samp{inline} and @samp{attachment} @item encoding Valid values are @samp{7bit}, @samp{8bit}, @samp{quoted-printable} and -@samp{base64} (@code{Content-Transfer-Encoding}). @xref{Charset -Translation}. +@samp{base64}. @xref{Charset +Translation}. This parameter says what +@code{Content-Transfer-Encoding} to use when sending the part, and is +normally computed automatically. + +@item data-encoding +This parameter says what encoding has been used on the data, and the +data will be decoded before use. Valid values are +@samp{quoted-printable} and @samp{base64}. This is useful when you +have a part with binary data (for instance an image) inserted directly +into the Message buffer inside the @samp{"<#part>...<#/part>"} tags. @item description A description of the part (@code{Content-Description}). @@ -917,7 +933,7 @@ Here's an example: @lisp (add-to-list 'gnus-newsgroup-variables 'mm-coding-system-priorities) (setq gnus-parameters - (nconc + (append ;; Some charsets are just examples! '(("^cn\\." ;; Chinese (mm-coding-system-priorities diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi index 57f713635f8..c33ca0ea02c 100644 --- a/doc/misc/eshell.texi +++ b/doc/misc/eshell.texi @@ -159,6 +159,9 @@ The following persons have made contributions to Eshell. @itemize @bullet @item +John Wiegley is the original author of Eshell. + +@item Eli Zaretskii made it possible for Eshell to run without requiring asynchronous subprocess support. This is important for MS-DOS, which does not have such support. diff --git a/doc/misc/eudc.texi b/doc/misc/eudc.texi index 701340ed6e2..4ead6032b74 100644 --- a/doc/misc/eudc.texi +++ b/doc/misc/eudc.texi @@ -83,6 +83,8 @@ Currently supported back-ends are: LDAP, Lightweight Directory Access Protocol @item BBDB, Big Brother's Insidious Database +@item +macOS Contacts @end itemize The main features of the EUDC interface are: @@ -107,6 +109,7 @@ Interface to BBDB to let you insert server records into your own BBDB database @menu * LDAP:: What is LDAP ? * BBDB:: What is BBDB ? +* macOS Contacts:: What is macOS Contacts ? @end menu @@ -159,6 +162,21 @@ queries on multiple servers. EUDC also offers a means to insert results from directory queries into your own local BBDB (@pxref{Creating BBDB Records}) + +@node macOS Contacts +@section macOS Contacts + +macOS Contacts is the rolodex-like application that ships with the +macOS operating system@footnote{Apple have changed the names of their +operating system and some applications over time. macOS used to be +called Mac OS X in the past, and the Contacts application was +previously called Address Book.}. + +EUDC considers macOS Contacts as a directory server back end just like +LDAP, though the macOS Contacts application always resides locally on +your machine. + + @node Installation @chapter Installation @@ -185,6 +203,7 @@ email composition buffers (@pxref{Inline Query Expansion}) @menu * LDAP Configuration:: EUDC needs external support for LDAP +* macOS Contacts Configuration:: Enable the macOS Contacts backend @end menu @node LDAP Configuration @@ -379,6 +398,39 @@ The @command{ldapsearch} command is formatted such that it can be copied and pasted into a terminal. Set the @command{ldapsearch} debug level to 5 by appending @code{-d 5} to the command line. + +@node macOS Contacts Configuration +@section macOS Contacts Configuration + +macOS Contacts support is added by means of @file{eudcb-mab.el}, or +@file{eudcb-macos-contacts.el} which are part of Emacs. + +To enable a macOS Contacts backend, first `require' the respective +library to load it, and then set the `eudc-server' to localhost in +your init file: +@lisp +(require 'eudcb-macos-contacts) +(eudc-macos-contacts-set-server "localhost") +@end lisp + +@file{eudcb-macos-contacts.el} uses the public scripting interfaces +offered by the Contacts app via the macOS Open Scripting Architecture +(OSA). To accomplish this, @file{eudcb-macos-contacts.el} uses an +external command line utility named osascript, which is included with +all macOS versions since 10.0 (which was released 2001). +@file{eudcb-macos-contacts.el} is hence recommended for all new +configurations. + +@file{eudcb-mab.el} reverse engineers the format of the database file +used by the macOS Contacts app, and accesses its contents directly. +While this may promise some performance advantages, it comes at the +cost of using an undocumented interface. Hence, users of +@file{eudcb-mab.el} are recommended to double check the compatibility +of @file{eudcb-mab.el} before upgrading to a new version of macOS. +@file{eudcb-mab.el} is retained for backwards compatibility with +existing configurations, and may be removed in a future release. + + @node Usage @chapter Usage diff --git a/doc/misc/eww.texi b/doc/misc/eww.texi index e3191cbe48a..85be112402c 100644 --- a/doc/misc/eww.texi +++ b/doc/misc/eww.texi @@ -52,6 +52,7 @@ modify this GNU manual.'' * Overview:: * Basics:: * Advanced:: +* Command Line:: Appendices * History and Acknowledgments:: @@ -135,7 +136,9 @@ HTML-specified colors or not. This sets the @code{shr-use-colors} variable. A URL can be downloaded with @kbd{d} (@code{eww-download}). This will download the link under point if there is one, or else the URL of the current page. The file will be written to the directory specified -in @code{eww-download-directory} (default: @file{~/Downloads/}). +by @code{eww-download-directory} (default: @file{~/Downloads/}, if it +exists; otherwise as specified by the @samp{DOWNLOAD} @acronym{XDG} +directory)). @findex eww-back-url @findex eww-forward-url @@ -283,6 +286,14 @@ contrast. If that is still too low for you, you can customize the variables @code{shr-color-visible-distance-min} and @code{shr-color-visible-luminance-min} to get a better contrast. +@vindex shr-max-width +@vindex shr-width + By default, the max width used when rendering is 120 characters, but +this can be adjusted by changing the @code{shr-max-width} variable. +If a specified width is preferred no matter what the width of the +window is, @code{shr-width} can be set. If both variables are +@code{nil}, the window width will always be used. + @vindex shr-discard-aria-hidden @cindex @code{aria-hidden}, HTML attribute The HTML attribute @code{aria-hidden} is meant to tell screen @@ -327,6 +338,21 @@ thus allowing for the use of the usual substitutions, such as @code{\[eww-reload]} for the current key binding of the @code{eww-reload} command. +@node Command Line +@chapter Command Line Usage + +It can be convenient to start eww directly from the command line. The +@code{eww-browse} function can be used for that: + +@example +emacs -f eww-browse https://gnu.org +@end example + +This also allows registering Emacs as a @acronym{MIME} handler for the +@samp{"text/x-uri"} media type. How to do that varies between +systems, but typically you'd register the handler to call @samp{"emacs +-f eww-browse %u"}. + @node History and Acknowledgments @appendix History and Acknowledgments diff --git a/doc/misc/gnus-coding.texi b/doc/misc/gnus-coding.texi index 55320bf4c32..9a14a95f797 100644 --- a/doc/misc/gnus-coding.texi +++ b/doc/misc/gnus-coding.texi @@ -96,16 +96,6 @@ Read passwords from user, possibly using a password cache. @c As of 2005-10-21... There are no Gnus dependencies in this file. -@item tls.el -TLS/SSL support via wrapper around GnuTLS -@c As of 2005-10-21... -There are no Gnus dependencies in this file. - -@item pgg*.el -Glue for the various PGP implementations. -@c As of 2005-10-21... -There are no Gnus dependencies in these files. - @item sha1.el SHA1 Secure Hash Algorithm. @c As of 2007-08-25... diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi index c8ac7f0a7c2..0bdc2fa297d 100644 --- a/doc/misc/gnus.texi +++ b/doc/misc/gnus.texi @@ -402,6 +402,7 @@ This manual corresponds to Gnus v5.13 @end iftex @menu +* Don't Panic:: Your first 20 minutes with Gnus. * Starting Up:: Finding news can be a pain. * Group Buffer:: Selecting, subscribing and killing groups. * Summary Buffer:: Reading, saving and posting articles. @@ -436,7 +437,7 @@ Starting Gnus * Finding the News:: Choosing a method for getting news. * The Server is Down:: How can I read my mail then? -* Slave Gnusae:: You can have more than one Gnus active at a time. +* Child Gnusae:: You can have more than one Gnus active at a time. * Fetching a Group:: Starting Gnus just to read a group. * New Groups:: What is Gnus supposed to do with new groups? * Changing Servers:: You may want to move from one server to another. @@ -827,6 +828,7 @@ Various * Spam Package:: A package for filtering and processing spam. * The Gnus Registry:: A package for tracking messages by Message-ID. * The Gnus Cloud:: A package for synchronizing Gnus marks. +* D-Bus Integration:: Closing Gnus servers on system sleep. * Other modes:: Interaction with other modes. * Various Various:: Things that are really various. @@ -947,6 +949,140 @@ Emacs for Heathens @end detailmenu @end menu +@node Don't Panic +@chapter Don't Panic +@cindex don't panic +@cindex introduction to Gnus + +Welcome, gentle user, to the Gnus newsreader and email client! Gnus +is unlike most clients, in part because of its endless +configurability, in part because of its historical origins. Gnus is +now a fully-featured email client, but it began life as a Usenet-style +newsreader, and its genes are still newsreader genes. Thus it behaves +a little differently than most mail clients. + +The typical assumptions of a newsreader are: + +@enumerate +@item +The server offers a potentially enormous number of newsgroups on a +variety of subjects. The user may only be interested in some of those +groups, and more interested in some than others. +@item +Many groups see a high volume of articles, and the user won't want to +read all of them. Mechanisms are needed for foregrounding interesting +articles, and backgrounding uninteresting articles. +@item +Once a group has been scanned and dealt with by the user, it's +unlikely to be of further interest until new articles come in. +@end enumerate + +These assumptions lead to certain default Gnus behaviors: + +@enumerate +@item +Not all interesting groups are equally interesting, thus groups have +varying degrees of ``subscribedness'', with different behavior +depending on ``how subscribed'' a group is. +@item +There are many commands and tools for scoring and sorting articles, +or otherwise sweeping them under the rug. +@item +Gnus will only show you groups with unread or ticked articles; +groups with no new articles are hidden. +@item +When entering a group, only unread or ticked articles are shown, +all other articles are hidden. +@end enumerate + +If this seems draconian, think of it as Automatic Inbox Zero. This is +the way Gnus works by default. It is possible to make it work more +like an email client (always showing read groups and read articles), +but that takes some effort on the part of the user. + +The brief introduction below should be enough to get you off the +ground. + +@heading The Basics of Servers, Groups, and Articles +@cindex servers +@cindex groups +@cindex articles + +The fundamental building blocks of Gnus are @dfn{servers}, +@dfn{groups}, and @dfn{articles}. Servers can be local or remote. +Each server maintains a list of groups, and those groups contain +articles. Because Gnus presents a unified interface to a wide variety +of servers, the vocabulary doesn't always quite line up (see @ref{FAQ +- Glossary}, for a more complete glossary). Thus a local maildir is +referred to as a ``server'' (@pxref{Finding the News}) the same as a +Usenet or IMAP server is; ``groups'' (@pxref{Group Buffer}) might mean +an NNTP group, IMAP folder, or local mail directory; and an +``article'' (@pxref{Summary Buffer}) might elsewhere be known as a +message or an email. Gnus employs unified terms for all these things. + +Servers fall into two general categories: ``news-like'', meaning that +the articles are part of a public archive and can't be manipulated by +the user; and ``mail-like'', meaning that the articles are owned by +the user, who can freely edit them, move them around, and delete +them. + +For news-like servers, which typically offer hundreds or thousands of +groups, it's important to be able to subscribe to a subset of those +groups. For mail-like servers, the user is generally automatically +subscribed to all groups (though IMAP, for example, also allows +selective subscription). To change group subscription, enter the +Server buffer (with @kbd{^}) and press @kbd{@key{RET}} on the server +in question. From here, Gnus provides commands to change or toggle +your group subscriptions (@pxref{Browse Foreign Server}). + +A Gnus installation is basically just a list of one or more servers, +plus the user's subscribed groups from those servers, plus articles in +those groups. + +Servers can be added and configured in two places: in the user's +gnus.el startup file, using the @code{gnus-select-method} and +@code{gnus-secondary-select-methods} options, or within Gnus itself +using interactive commands in the Server buffer. @xref{Finding +the News}, for details. + + +@heading Fetching Mail + +New mail has to come from somewhere. Some servers, such as NNTP or +IMAP, are themselves responsible for fetching newly-arrived articles. +Others, such as maildir or mbox servers, only store articles and don't +fetch them from anywhere. + +In the latter case, Gnus provides for @code{mail sources}: places +where new mail is fetched from. A mail source might be a local spool, +or a remote POP server, or some other source of incoming articles. +Mail sources are usually configured globally, but can be specified +per-group (@pxref{Mail Sources} for more information). + +@xref{Scanning New Messages}, for details on fetching new mail. + +@heading Viewing Mail + +By default, Gnus's Group buffer only displays groups with unread +articles. It is always possible to display all the groups temporarily +with @kbd{L}, and to configure Gnus to always display some groups +(@pxref{Listing Groups}). + +@xref{Selecting a Group}, for how to enter a group, and @pxref{Summary +Buffer} for what to do once you're there. + +@heading Sending Mail + +New message composition can be initiated from the Group buffer +(@pxref{Misc Group Stuff}). If you're in a Summary buffer, you can +compose replies and forward emails in addition to starting new +messages, see @ref{Summary Mail Commands}, for details. + +For information about what happens once you've started composing a +message, see @ref{Composing Messages}. For information on setting up +@acronym{SMTP} servers in particular, see @ref{Mail Variables, ,Mail +Variables,message,Message manual}. + @node Starting Up @chapter Starting Gnus @cindex starting up @@ -976,7 +1112,7 @@ terminology section (@pxref{Terminology}). @menu * Finding the News:: Choosing a method for getting news. * The Server is Down:: How can I read my mail then? -* Slave Gnusae:: You can have more than one Gnus active at a time. +* Child Gnusae:: You can have more than one Gnus active at a time. * New Groups:: What is Gnus supposed to do with new groups? * Changing Servers:: You may want to move from one server to another. * Startup Files:: Those pesky startup files---@file{.newsrc}. @@ -1090,9 +1226,9 @@ your primary server---instead, it will just activate all groups on level levels.) Also @pxref{Group Levels}. -@node Slave Gnusae -@section Slave Gnusae -@cindex slave +@node Child Gnusae +@section Child Gnusae +@cindex child You might want to run more than one Emacs with more than one Gnus at the same time. If you are using different @file{.newsrc} files (e.g., if you @@ -1103,31 +1239,27 @@ The problem appears when you want to run two Gnusae that use the same @file{.newsrc} file. To work around that problem some, we here at the Think-Tank at the Gnus -Towers have come up with a new concept: @dfn{Masters} and -@dfn{slaves}. (We have applied for a patent on this concept, and have -taken out a copyright on those words. If you wish to use those words in -conjunction with each other, you have to send $1 per usage instance to -me. Usage of the patent (@dfn{Master/Slave Relationships In Computer -Applications}) will be much more expensive, of course.) - -@findex gnus-slave +Towers have come up with a new concept: @dfn{Parents} and +@dfn{children}. + +@findex gnus-child Anyway, you start one Gnus up the normal way with @kbd{M-x gnus} (or -however you do it). Each subsequent slave Gnusae should be started with -@kbd{M-x gnus-slave}. These slaves won't save normal @file{.newsrc} -files, but instead save @dfn{slave files} that contain information only -on what groups have been read in the slave session. When a master Gnus -starts, it will read (and delete) these slave files, incorporating all -information from them. (The slave files will be read in the sequence +however you do it). Each subsequent child Gnusae should be started with +@kbd{M-x gnus-child}. These children won't save normal @file{.newsrc} +files, but instead save @dfn{child files} that contain information only +on what groups have been read in the child session. When a parent Gnus +starts, it will read (and delete) these child files, incorporating all +information from them. (The child files will be read in the sequence they were created, so the latest changes will have precedence.) -Information from the slave files has, of course, precedence over the -information in the normal (i.e., master) @file{.newsrc} file. +Information from the child files has, of course, precedence over the +information in the normal (i.e., parent) @file{.newsrc} file. -If the @file{.newsrc*} files have not been saved in the master when the -slave starts, you may be prompted as to whether to read an auto-save -file. If you answer ``yes'', the unsaved changes to the master will be -incorporated into the slave. If you answer ``no'', the slave may see some -messages as unread that have been read in the master. +If the @file{.newsrc*} files have not been saved in the parent when the +child starts, you may be prompted as to whether to read an auto-save +file. If you answer ``yes'', the unsaved changes to the parent will be +incorporated into the child. If you answer ``no'', the child may see some +messages as unread that have been read in the parent. @@ -1563,12 +1695,6 @@ secondary select methods. @table @code -@item gnus-load-hook -@vindex gnus-load-hook -A hook run while Gnus is being loaded. Note that this hook will -normally be run just once in each Emacs session, no matter how many -times you start Gnus. - @item gnus-before-startup-hook @vindex gnus-before-startup-hook A hook called as the first thing when Gnus is started. @@ -9070,6 +9196,9 @@ when filling. @findex gnus-article-fill-long-lines Fill long lines (@code{gnus-article-fill-long-lines}). +You can give the command a numerical prefix to specify the width to use +when filling. + @item W C @kindex W C @r{(Summary)} @findex gnus-article-capitalize-sentences @@ -10901,14 +11030,14 @@ Go to the Gnus info node (@code{gnus-info-find-node}). @table @kbd -@item M-s -@kindex M-s @r{(Summary)} +@item M-s M-s +@kindex M-s M-s @r{(Summary)} @findex gnus-summary-search-article-forward Search through all subsequent (raw) articles for a regexp (@code{gnus-summary-search-article-forward}). -@item M-r -@kindex M-r @r{(Summary)} +@item M-s M-r +@kindex M-s M-r @r{(Summary)} @findex gnus-summary-search-article-backward Search through all previous (raw) articles for a regexp (@code{gnus-summary-search-article-backward}). @@ -22205,6 +22334,7 @@ to you, using @kbd{G b u} and updating the group will usually fix this. * Spam Package:: A package for filtering and processing spam. * The Gnus Registry:: A package for tracking messages by Message-ID. * The Gnus Cloud:: A package for synchronizing Gnus marks. +* D-Bus Integration:: Closing Gnus servers on system sleep. * Other modes:: Interaction with other modes. * Various Various:: Things that are really various. @end menu @@ -26276,6 +26406,26 @@ CloudSynchronizationDataPack(TM)s. It's easiest to set this from the Server buffer (@pxref{Gnus Cloud Setup}). @end defvar +@node D-Bus Integration +@section D-Bus Integration +@cindex dbus +@cindex D-Bus +@cindex gnus-dbus +@cindex system sleep +@cindex closing servers automatically +@cindex hung connections + +When using laptops or other systems that have a sleep or hibernate +functionality, it's possible for long-running server connections to +become ``hung'', requiring the user to manually close and re-open the +connections after the system resumes. On systems compiled with D-Bus +support (check the value of @code{(featurep 'dbusbind)}), Gnus can +register a D-Bus signal to automatically close all server connections +before the system goes to sleep. To enable this, set +@code{gnus-dbus-close-on-sleep} to a non-nil value. + +For more information about D-Bus and Emacs, @pxref{Top,,, dbus, D-Bus integration in Emacs}. + @node Other modes @section Interaction with other modes @@ -27917,7 +28067,7 @@ The revised Gnus @acronym{FAQ} is included in the manual, @acronym{TLS} wrapper shipped with Gnus @acronym{TLS}/@acronym{SSL} is now supported in @acronym{IMAP} and -@acronym{NNTP} via @file{tls.el} and GnuTLS. +@acronym{NNTP} via GnuTLS. @item Improved anti-spam features. @@ -28493,9 +28643,9 @@ entry. The format spec @code{%C} for positioning point has changed to @code{%*}. @item -@code{gnus-slave-unplugged} +@code{gnus-child-unplugged} -A new command which starts Gnus offline in slave mode. +A new command which starts Gnus offline in child mode. @end itemize diff --git a/doc/misc/idlwave.texi b/doc/misc/idlwave.texi index 547b16622fc..5cb6b19181c 100644 --- a/doc/misc/idlwave.texi +++ b/doc/misc/idlwave.texi @@ -1805,8 +1805,8 @@ Structure tag completion is not enabled by default. To enable it, simply add the following to your @file{.emacs}: @lisp - (add-hook 'idlwave-load-hook - (lambda () (require 'idlw-complete-structtag))) +(with-eval-after-load 'idlwave + (require 'idlw-complete-structtag)) @end lisp Once enabled, you'll also be able to access online help on the structure @@ -2360,10 +2360,6 @@ is first called. Normal hook. Executed when a buffer is put into @code{idlwave-mode}. @end defopt -@defopt idlwave-load-hook -Normal hook. Executed when @file{idlwave.el} is loaded. -@end defopt - @node The IDLWAVE Shell @chapter The IDLWAVE Shell @cindex IDLWAVE shell diff --git a/doc/misc/ido.texi b/doc/misc/ido.texi index 74d0bdd29fc..7cc4edd2865 100644 --- a/doc/misc/ido.texi +++ b/doc/misc/ido.texi @@ -590,7 +590,7 @@ Now you can customize @code{completion-ignored-extensions} as well. Go ahead and add all the useless object files, backup files, shared library files and other computing flotsam you don't want Ido to show. -@strong{Note:} Ido will still complete the ignored elements +@strong{Please note:} Ido will still complete the ignored elements if it would otherwise not show any other matches. So if you type out the name of an ignored file, Ido will still let you open it just fine. diff --git a/doc/misc/message.texi b/doc/misc/message.texi index bdd31b1fe49..55b166eb8b0 100644 --- a/doc/misc/message.texi +++ b/doc/misc/message.texi @@ -99,6 +99,7 @@ sending it. * Resending:: Resending a mail message. * Bouncing:: Bouncing a mail message. * Mailing Lists:: Send mail to mailing lists. +* System Mailer Setup:: Using Message as the system mailer. @end menu You can customize the Message Mode tool bar, see @kbd{M-x @@ -529,6 +530,29 @@ It is considered good netiquette to honor MFT, as it is assumed the fellow who posted a message knows where the followups need to go better than you do. + +@node System Mailer Setup +@section System Mailer Setup +@cindex mailto: + +Emacs can be set up as the system mailer, so that Emacs is opened when +you click on @samp{mailto:} links in other programs. + +How this is done varies from system to system, but commonly there's a +way to set the default application for a @acronym{MIME} type, and the +relevant type here is @samp{x-scheme-handler/mailto;}. + +The application to start should be @samp{"emacs -f message-mailto %u"}. +This will start Emacs, and then run the @code{message-mailto} +command. It will parse the given @acronym{URL}, and set up a Message +buffer with the given parameters. + +For instance, @samp{mailto:larsi@@gnus.org?subject=This+is+a+test} +will open a Message buffer with the @samp{To:} header filled in with +@samp{"larsi@@gnus.org"} and the @samp{Subject:} header with +@samp{"This is a test"}. + + @node Commands @chapter Commands @@ -883,6 +907,18 @@ is a list, valid members are @code{type}, @code{description} and @code{nil}, don't ask for options. If it is @code{t}, ask the user whether or not to specify options. +@vindex message-screenshot-command +@findex message-insert-screenshot +@cindex screenshots +@kindex C-c C-p +If your system supports it, you can also insert screenshots directly +into the Message buffer. The @kbd{C-c C-p} +(@code{message-insert-screenshot}) command inserts the image into the +buffer as an @acronym{MML} part, and puts an image text property on +top. The @code{message-screenshot-command} variable says what +external command to use to take the screenshot. It defaults to +@code{"import png:-"}, which is an ImageMagick command. + You can also create arbitrarily complex multiparts using the @acronym{MML} language (@pxref{Composing, , Composing, emacs-mime, The Emacs MIME Manual}). @@ -1006,6 +1042,7 @@ and/or encrypted messages as explained in the following. * Signing and encryption:: Signing and encrypting commands. * Using S/MIME:: Using S/MIME * Using OpenPGP:: Using OpenPGP +* OpenPGP Header:: Adding OpenPGP headers to messages. * Passphrase caching:: How to cache passphrases * PGP Compatibility:: Compatibility with older implementations * Encrypt-to-self:: Reading your own encrypted messages @@ -1215,6 +1252,29 @@ according to two different standards, namely @acronym{PGP} or @code{mml-default-sign-method} determine which variant to prefer, @acronym{PGP/MIME} by default. +@node OpenPGP Header +@subsection OpenPGP Header + +The @samp{OpenPGP} header can be used to provide information about the +sender's OpenPGP key. This is a formalization and modernization of +the non-standard @samp{X-PGP-Key} (etc.) headers that have been in use +for a long time. For more details, see +@uref{https://tools.ietf.org/html/draft-josefsson-openpgp-mailnews-header}. + +@vindex message-openpgp-header +To use this in Message, say: + +@lisp +(add-hook 'message-header-setup-hook 'message-add-openpgp-header) +@end lisp + +@noindent +then customize the @code{message-openpgp-header} variable according to +your PGP setup. The variable is a list of the key ID, the key URL or +ASCII armored key, and the protection preference, one of +@samp{"unprotected"}, @samp{"sign"}, @samp{"encrypt"} or +@samp{"signencrypt"}. + @node Passphrase caching @subsection Passphrase caching diff --git a/doc/misc/org.texi b/doc/misc/org.texi index 6f6fcd640d0..495d562f50b 100644 --- a/doc/misc/org.texi +++ b/doc/misc/org.texi @@ -3979,10 +3979,9 @@ key bindings for this are really too long; you might want to bind this also to @kbd{M-n} and @kbd{M-p}. @lisp -(add-hook 'org-load-hook - (lambda () - (define-key org-mode-map "\M-n" 'org-next-link) - (define-key org-mode-map "\M-p" 'org-previous-link))) +(with-eval-after-load 'org + (define-key org-mode-map "\M-n" 'org-next-link) + (define-key org-mode-map "\M-p" 'org-previous-link)) @end lisp @end table diff --git a/doc/misc/reftex.texi b/doc/misc/reftex.texi index 013c5639a1e..0dab5241517 100644 --- a/doc/misc/reftex.texi +++ b/doc/misc/reftex.texi @@ -2896,9 +2896,8 @@ default. If you want to have these key bindings available, set in your Note that this variable has to be set before @RefTeX{} is loaded to have an effect. -@vindex reftex-load-hook -Changing and adding to @RefTeX{}'s key bindings is best done in the hook -@code{reftex-load-hook}. For information on the keymaps +Changing and adding to @RefTeX{}'s key bindings is best done using +@code{with-eval-after-load}. For information on the keymaps which should be used to add keys, see @ref{Keymaps and Hooks}. @node Faces @@ -5320,10 +5319,6 @@ argument. The keymap for @RefTeX{} mode. @end deffn -@deffn {Normal Hook} reftex-load-hook -Normal hook which is being run when loading @file{reftex.el}. -@end deffn - @deffn {Normal Hook} reftex-mode-hook Normal hook which is being run when turning on @RefTeX{} mode. @end deffn diff --git a/doc/misc/sem-user.texi b/doc/misc/sem-user.texi index c02887d104a..d151cee02cc 100644 --- a/doc/misc/sem-user.texi +++ b/doc/misc/sem-user.texi @@ -1068,7 +1068,7 @@ You can integrate @semantic{} with the Speedbar. line to your init file: @example -(add-hook 'speedbar-load-hook (lambda () (require 'semantic/sb))) +(with-eval-after-load 'speedbar (require 'semantic/sb)) @end example @noindent diff --git a/doc/misc/smtpmail.texi b/doc/misc/smtpmail.texi index 99612d5c8fb..f29a5a82e86 100644 --- a/doc/misc/smtpmail.texi +++ b/doc/misc/smtpmail.texi @@ -295,26 +295,11 @@ encrypted connection if the server supports it. Other possible values are: @code{starttls} to insist on STARTTLS; @code{ssl} to use TLS/SSL; and @code{plain} for no encryption. -Use of any form of TLS/SSL requires support in Emacs. You can either -use the built-in support (in Emacs 24.1 and later), or the -@file{starttls.el} Lisp library. The built-in support uses the GnuTLS -@footnote{@url{https://www.gnu.org/software/gnutls/}} library. -If your Emacs has GnuTLS support built-in, the function +Use of any form of TLS/SSL requires support in Emacs. You can use the +built-in support for the GnuTLS +@footnote{@url{https://www.gnu.org/software/gnutls/}} library. If your +Emacs has GnuTLS support built-in, the function @code{gnutls-available-p} is defined and returns non-@code{nil}. -Otherwise, you must use the @file{starttls.el} library (see that file for -more information on customization options, etc.). The Lisp library -requires one of the following external tools to be installed: - -@enumerate -@item -The GnuTLS command line tool @samp{gnutls-cli}, which you can get from -@url{https://www.gnu.org/software/gnutls/}. This is the recommended -tool, mainly because it can verify server certificates. - -@item -The @samp{starttls} external program, which you can get from -@file{starttls-*.tar.gz} from @uref{ftp://ftp.opaopa.org/pub/elisp/}. -@end enumerate @cindex certificates @cindex keys diff --git a/doc/misc/speedbar.texi b/doc/misc/speedbar.texi index 57ad0220103..c9c3daf963b 100644 --- a/doc/misc/speedbar.texi +++ b/doc/misc/speedbar.texi @@ -828,9 +828,6 @@ Hooks run when speedbar visits a file in the selected frame. @cindex @code{speedbar-visiting-tag-hook} @item speedbar-visiting-tag-hook Hooks run when speedbar visits a tag in the selected frame. -@cindex @code{speedbar-load-hook} -@item speedbar-load-hook -Hooks run when speedbar is loaded. @cindex @code{speedbar-reconfigure-keymaps-hook} @item speedbar-reconfigure-keymaps-hook Hooks run when the keymaps are regenerated. Keymaps are reconfigured @@ -913,12 +910,11 @@ bindings: This function creates a special keymap for use in speedbar. @item -Call your install function, or assign it to a hook like this: +Call your install function, like this: @smallexample -(if (featurep 'speedbar) - (@var{name}-install-speedbar-variables) - (add-hook 'speedbar-load-hook '@var{name}-install-speedbar-variables)) +(with-eval-after-load 'speedbar + (@var{name}-install-speedbar-variables)) @end smallexample @item diff --git a/doc/misc/texinfo.tex b/doc/misc/texinfo.tex index 6d9d7113f77..0d2a1fdbc8f 100644 --- a/doc/misc/texinfo.tex +++ b/doc/misc/texinfo.tex @@ -3,9 +3,9 @@ % Load plain if necessary, i.e., if running under initex. \expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi % -\def\texinfoversion{2019-09-24.13} +\def\texinfoversion{2020-06-25.17} % -% Copyright 1985--1986, 1988, 1990--2020 Free Software Foundation, Inc. +% Copyright 1985, 1986, 1988, 1990-2020 Free Software Foundation, Inc. % % This texinfo.tex file is free software: you can redistribute it and/or % modify it under the terms of the GNU General Public License as @@ -33,7 +33,7 @@ % The texinfo.tex in any given distribution could well be out % of date, so if that's what you're using, please check. % -% Send bug reports to bug-texinfo@gnu.org. Please include including a +% Send bug reports to bug-texinfo@gnu.org. Please include a % complete document in each bug report with which we can reproduce the % problem. Patches are, of course, greatly appreciated. % @@ -349,36 +349,21 @@ \ifodd\pageno \advance\hoffset by \bindingoffset \else \advance\hoffset by -\bindingoffset\fi % + \checkchapterpage + % % Retrieve the information for the headings from the marks in the page, % and call Plain TeX's \makeheadline and \makefootline, which use the % values in \headline and \footline. % - % This is used to check if we are on the first page of a chapter. - \ifcase1\the\savedtopmark\fi - \let\prevchaptername\thischaptername - \ifcase0\firstmark\fi - \let\curchaptername\thischaptername - % - \ifodd\pageno \getoddheadingmarks \else \getevenheadingmarks \fi - % - \ifx\curchaptername\prevchaptername - \let\thischapterheading\thischapter - \else - % \thischapterheading is the same as \thischapter except it is blank - % for the first page of a chapter. This is to prevent the chapter name - % being shown twice. - \def\thischapterheading{}% - \fi - % % Common context changes for both heading and footing. % Do this outside of the \shipout so @code etc. will be expanded in % the headline as they should be, not taken literally (outputting ''code). - \def\commmonheadfootline{\let\hsize=\txipagewidth \texinfochars} - % - \global\setbox\headlinebox = \vbox{\commmonheadfootline \makeheadline}% + \def\commonheadfootline{\let\hsize=\txipagewidth \texinfochars} % + \ifodd\pageno \getoddheadingmarks \else \getevenheadingmarks \fi + \global\setbox\headlinebox = \vbox{\commonheadfootline \makeheadline}% \ifodd\pageno \getoddfootingmarks \else \getevenfootingmarks \fi - \global\setbox\footlinebox = \vbox{\commmonheadfootline \makefootline}% + \global\setbox\footlinebox = \vbox{\commonheadfootline \makefootline}% % {% % Set context for writing to auxiliary files like index files. @@ -423,6 +408,22 @@ \ifr@ggedbottom \kern-\dimen@ \vfil \fi} } +% Check if we are on the first page of a chapter. Used for printing headings. +\newif\ifchapterpage +\def\checkchapterpage{% + % Get the chapter that was current at the end of the last page + \ifcase1\the\savedtopmark\fi + \let\prevchaptername\thischaptername + % + \ifodd\pageno \getoddheadingmarks \else \getevenheadingmarks \fi + \let\curchaptername\thischaptername + % + \ifx\curchaptername\prevchaptername + \chapterpagefalse + \else + \chapterpagetrue + \fi +} % Argument parsing @@ -1010,7 +1011,7 @@ where each line of input produces a line of output.} \let\setfilename=\comment % @bye. -\outer\def\bye{\pagealignmacro\tracingstats=1\ptexend} +\outer\def\bye{\chappager\pagelabels\tracingstats=1\ptexend} \message{pdf,} @@ -1137,6 +1138,45 @@ where each line of input produces a line of output.} \fi +% Output page labels information. +% See PDF reference v.1.7 p.594, section 8.3.1. +\ifpdf +\def\pagelabels{% + \def\title{0 << /P (T-) /S /D >>}% + \edef\roman{\the\romancount << /S /r >>}% + \edef\arabic{\the\arabiccount << /S /D >>}% + % + % Page label ranges must be increasing. Remove any duplicates. + % (There is a slight chance of this being wrong if e.g. there is + % a @contents but no @titlepage, etc.) + % + \ifnum\romancount=0 \def\roman{}\fi + \ifnum\arabiccount=0 \def\title{}% + \else + \ifnum\romancount=\arabiccount \def\roman{}\fi + \fi + % + \ifnum\romancount<\arabiccount + \pdfcatalog{/PageLabels << /Nums [\title \roman \arabic ] >> }\relax + \else + \pdfcatalog{/PageLabels << /Nums [\title \arabic \roman ] >> }\relax + \fi +} +\else + \let\pagelabels\relax +\fi + +\newcount\pagecount \pagecount=0 +\newcount\romancount \romancount=0 +\newcount\arabiccount \arabiccount=0 +\ifpdf + \let\ptxadvancepageno\advancepageno + \def\advancepageno{% + \ptxadvancepageno\global\advance\pagecount by 1 + } +\fi + + % PDF uses PostScript string constants for the names of xref targets, % for display in the outlines, and in other places. Thus, we have to % double any backslashes. Otherwise, a name like "\node" will be @@ -1427,7 +1467,13 @@ output) for that.)} % subentries, which we calculated on our first read of the .toc above. % % We use the node names as the destinations. + % + % Currently we prefix the section name with the section number + % for chapter and appendix headings only in order to avoid too much + % horizontal space being required in the PDF viewer. \def\numchapentry##1##2##3##4{% + \dopdfoutline{##2 ##1}{count-\expnumber{chap##2}}{##3}{##4}}% + \def\unnchapentry##1##2##3##4{% \dopdfoutline{##1}{count-\expnumber{chap##2}}{##3}{##4}}% \def\numsecentry##1##2##3##4{% \dopdfoutline{##1}{count-\expnumber{sec##2}}{##3}{##4}}% @@ -1669,9 +1715,13 @@ output) for that.)} % Therefore, we read toc only once. % % We use node names as destinations. + % + % Currently we prefix the section name with the section number + % for chapter and appendix headings only in order to avoid too much + % horizontal space being required in the PDF viewer. \def\partentry##1##2##3##4{}% ignore parts in the outlines \def\numchapentry##1##2##3##4{% - \dopdfoutline{##1}{1}{##3}{##4}}% + \dopdfoutline{##2 ##1}{1}{##3}{##4}}% \def\numsecentry##1##2##3##4{% \dopdfoutline{##1}{2}{##3}{##4}}% \def\numsubsecentry##1##2##3##4{% @@ -1683,7 +1733,8 @@ output) for that.)} \let\appsecentry\numsecentry% \let\appsubsecentry\numsubsecentry% \let\appsubsubsecentry\numsubsubsecentry% - \let\unnchapentry\numchapentry% + \def\unnchapentry##1##2##3##4{% + \dopdfoutline{##1}{1}{##3}{##4}}% \let\unnsecentry\numsecentry% \let\unnsubsecentry\numsubsecentry% \let\unnsubsubsecentry\numsubsubsecentry% @@ -2496,7 +2547,7 @@ end \def\it{\fam=\itfam \setfontstyle{it}} \def\sl{\fam=\slfam \setfontstyle{sl}} \def\bf{\fam=\bffam \setfontstyle{bf}}\def\bfstylename{bf} -\def\tt{\fam=\ttfam \setfontstyle{tt}} +\def\tt{\fam=\ttfam \setfontstyle{tt}}\def\ttstylename{tt} % Texinfo sort of supports the sans serif font style, which plain TeX does not. % So we set up a \sf. @@ -3101,15 +3152,15 @@ end % Allow a ragged right output to aid breaking long URL's. There can % be a break at the \allowbreak with no extra glue (if the existing stretch in -% the line is sufficent), a break at the \penalty100 with extra glue added +% the line is sufficient), a break at the \penalty100 with extra glue added % at the end of the line, or no break at all here. % Changing the value of the penalty and/or the amount of stretch affects how -% preferrable one choice is over the other. +% preferable one choice is over the other. \def\urefallowbreak{% \allowbreak - \hskip 0pt plus 4 em\relax - \penalty100 - \hskip 0pt plus -4 em\relax + \hskip 0pt plus 2 em\relax + \penalty300 + \hskip 0pt plus -2 em\relax } \urefbreakstyle after @@ -3509,7 +3560,7 @@ end % @pounds{} is a sterling sign, which Knuth put in the CM italic font. % -\def\pounds{{\it\$}} +\def\pounds{\ifmonospace{\ecfont\char"BF}\else{\it\$}\fi} % @euro{} comes from a separate font, depending on the current style. % We use the free feym* fonts from the eurosym package by Henrik @@ -3658,11 +3709,19 @@ end \fi % Quotes. -\chardef\quotedblleft="5C -\chardef\quotedblright=`\" \chardef\quoteleft=`\` \chardef\quoteright=`\' +% only change font for tt for correct kerning and to avoid using +% \ecfont unless necessary. +\def\quotedblleft{% + \ifmonospace{\ecfont\char"10}\else{\char"5C}\fi +} + +\def\quotedblright{% + \ifmonospace{\ecfont\char"11}\else{\char`\"}\fi +} + \message{page headings,} @@ -3784,12 +3843,19 @@ end \newtoks\evenheadline % headline on even pages \newtoks\oddheadline % headline on odd pages +\newtoks\evenchapheadline% headline on even pages with a new chapter +\newtoks\oddchapheadline % headline on odd pages with a new chapter \newtoks\evenfootline % footline on even pages \newtoks\oddfootline % footline on odd pages % Now make \makeheadline and \makefootline in Plain TeX use those variables -\headline={{\textfonts\rm \ifodd\pageno \the\oddheadline - \else \the\evenheadline \fi}} +\headline={{\textfonts\rm + \ifchapterpage + \ifodd\pageno\the\oddchapheadline\else\the\evenchapheadline\fi + \else + \ifodd\pageno\the\oddheadline\else\the\evenheadline\fi + \fi}} + \footline={{\textfonts\rm \ifodd\pageno \the\oddfootline \else \the\evenfootline \fi}\HEADINGShook} \let\HEADINGShook=\relax @@ -3805,12 +3871,14 @@ end \def\evenheading{\parsearg\evenheadingxxx} \def\evenheadingxxx #1{\evenheadingyyy #1\|\|\|\|\finish} \def\evenheadingyyy #1\|#2\|#3\|#4\finish{% -\global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + \global\evenheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}} + \global\evenchapheadline=\evenheadline} \def\oddheading{\parsearg\oddheadingxxx} \def\oddheadingxxx #1{\oddheadingyyy #1\|\|\|\|\finish} \def\oddheadingyyy #1\|#2\|#3\|#4\finish{% -\global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}} + \global\oddheadline={\rlap{\centerline{#2}}\line{#1\hfil#3}}% + \global\oddchapheadline=\oddheadline} \parseargdef\everyheading{\oddheadingxxx{#1}\evenheadingxxx{#1}}% @@ -3877,37 +3945,34 @@ end \parseargdef\headings{\csname HEADINGS#1\endcsname} \def\headingsoff{% non-global headings elimination - \evenheadline={\hfil}\evenfootline={\hfil}% - \oddheadline={\hfil}\oddfootline={\hfil}% + \evenheadline={\hfil}\evenfootline={\hfil}\evenchapheadline={\hfil}% + \oddheadline={\hfil}\oddfootline={\hfil}\oddchapheadline={\hfil}% } \def\HEADINGSoff{{\globaldefs=1 \headingsoff}} % global setting \HEADINGSoff % it's the default % When we turn headings on, set the page number to 1. +\def\pageone{ + \global\pageno=1 + \global\arabiccount = \pagecount +} + % For double-sided printing, put current file name in lower left corner, % chapter name on inside top of right hand pages, document % title on inside top of left hand pages, and page numbers on outside top % edge of all pages. \def\HEADINGSdouble{% -\global\pageno=1 -\global\evenfootline={\hfil} -\global\oddfootline={\hfil} -\global\evenheadline={\line{\folio\hfil\thistitle}} -\global\oddheadline={\line{\thischapterheading\hfil\folio}} -\global\let\contentsalignmacro = \chapoddpage +\pageone +\HEADINGSdoublex } \let\contentsalignmacro = \chappager % For single-sided printing, chapter title goes across top left of page, % page number on top right. \def\HEADINGSsingle{% -\global\pageno=1 -\global\evenfootline={\hfil} -\global\oddfootline={\hfil} -\global\evenheadline={\line{\thischapterheading\hfil\folio}} -\global\oddheadline={\line{\thischapterheading\hfil\folio}} -\global\let\contentsalignmacro = \chappager +\pageone +\HEADINGSsinglex } \def\HEADINGSon{\HEADINGSdouble} @@ -3917,7 +3982,9 @@ end \global\evenfootline={\hfil} \global\oddfootline={\hfil} \global\evenheadline={\line{\folio\hfil\thistitle}} -\global\oddheadline={\line{\thischapterheading\hfil\folio}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +\global\evenchapheadline={\line{\folio\hfil}} +\global\oddchapheadline={\line{\hfil\folio}} \global\let\contentsalignmacro = \chapoddpage } @@ -3925,8 +3992,22 @@ end \def\HEADINGSsinglex{% \global\evenfootline={\hfil} \global\oddfootline={\hfil} -\global\evenheadline={\line{\thischapterheading\hfil\folio}} -\global\oddheadline={\line{\thischapterheading\hfil\folio}} +\global\evenheadline={\line{\thischapter\hfil\folio}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +\global\evenchapheadline={\line{\hfil\folio}} +\global\oddchapheadline={\line{\hfil\folio}} +\global\let\contentsalignmacro = \chappager +} + +% for @setchapternewpage off +\def\HEADINGSsinglechapoff{% +\pageone +\global\evenfootline={\hfil} +\global\oddfootline={\hfil} +\global\evenheadline={\line{\thischapter\hfil\folio}} +\global\oddheadline={\line{\thischapter\hfil\folio}} +\global\evenchapheadline=\evenheadline +\global\oddchapheadline=\oddheadline \global\let\contentsalignmacro = \chappager } @@ -4841,7 +4922,7 @@ end % like the previous two, but they put @code around the argument. \def\docodeindex#1{\edef\indexname{#1}\parsearg\docodeindexxxx} -\def\docodeindexxxx #1{\doind{\indexname}{\code{#1}}} +\def\docodeindexxxx #1{\docind{\indexname}{#1}} % Used for the aux, toc and index files to prevent expansion of Texinfo @@ -5117,64 +5198,66 @@ end \let\lbracechar\{% \let\rbracechar\}% % + % + \let\do\indexnofontsdef + % % Non-English letters. - \def\AA{AA}% - \def\AE{AE}% - \def\DH{DZZ}% - \def\L{L}% - \def\OE{OE}% - \def\O{O}% - \def\TH{TH}% - \def\aa{aa}% - \def\ae{ae}% - \def\dh{dzz}% - \def\exclamdown{!}% - \def\l{l}% - \def\oe{oe}% - \def\ordf{a}% - \def\ordm{o}% - \def\o{o}% - \def\questiondown{?}% - \def\ss{ss}% - \def\th{th}% - % - \def\LaTeX{LaTeX}% - \def\TeX{TeX}% - % - % Assorted special characters. \defglyph gives the control sequence a - % definition that removes the {} that follows its use. - \defglyph\atchar{@}% - \defglyph\arrow{->}% - \defglyph\bullet{bullet}% - \defglyph\comma{,}% - \defglyph\copyright{copyright}% - \defglyph\dots{...}% - \defglyph\enddots{...}% - \defglyph\equiv{==}% - \defglyph\error{error}% - \defglyph\euro{euro}% - \defglyph\expansion{==>}% - \defglyph\geq{>=}% - \defglyph\guillemetleft{<<}% - \defglyph\guillemetright{>>}% - \defglyph\guilsinglleft{<}% - \defglyph\guilsinglright{>}% - \defglyph\leq{<=}% - \defglyph\lbracechar{\{}% - \defglyph\minus{-}% - \defglyph\point{.}% - \defglyph\pounds{pounds}% - \defglyph\print{-|}% - \defglyph\quotedblbase{"}% - \defglyph\quotedblleft{"}% - \defglyph\quotedblright{"}% - \defglyph\quoteleft{`}% - \defglyph\quoteright{'}% - \defglyph\quotesinglbase{,}% - \defglyph\rbracechar{\}}% - \defglyph\registeredsymbol{R}% - \defglyph\result{=>}% - \defglyph\textdegree{o}% + \do\AA{AA}% + \do\AE{AE}% + \do\DH{DZZ}% + \do\L{L}% + \do\OE{OE}% + \do\O{O}% + \do\TH{TH}% + \do\aa{aa}% + \do\ae{ae}% + \do\dh{dzz}% + \do\exclamdown{!}% + \do\l{l}% + \do\oe{oe}% + \do\ordf{a}% + \do\ordm{o}% + \do\o{o}% + \do\questiondown{?}% + \do\ss{ss}% + \do\th{th}% + % + \do\LaTeX{LaTeX}% + \do\TeX{TeX}% + % + % Assorted special characters. + \do\atchar{@}% + \do\arrow{->}% + \do\bullet{bullet}% + \do\comma{,}% + \do\copyright{copyright}% + \do\dots{...}% + \do\enddots{...}% + \do\equiv{==}% + \do\error{error}% + \do\euro{euro}% + \do\expansion{==>}% + \do\geq{>=}% + \do\guillemetleft{<<}% + \do\guillemetright{>>}% + \do\guilsinglleft{<}% + \do\guilsinglright{>}% + \do\leq{<=}% + \do\lbracechar{\{}% + \do\minus{-}% + \do\point{.}% + \do\pounds{pounds}% + \do\print{-|}% + \do\quotedblbase{"}% + \do\quotedblleft{"}% + \do\quotedblright{"}% + \do\quoteleft{`}% + \do\quoteright{'}% + \do\quotesinglbase{,}% + \do\rbracechar{\}}% + \do\registeredsymbol{R}% + \do\result{=>}% + \do\textdegree{o}% % % We need to get rid of all macros, leaving only the arguments (if present). % Of course this is not nearly correct, but it is the best we can do for now. @@ -5189,7 +5272,10 @@ end \macrolist \let\value\indexnofontsvalue } -\def\defglyph#1#2{\def#1##1{#2}} % see above + +% Give the control sequence a definition that removes the {} that follows +% its use, e.g. @AA{} -> AA +\def\indexnofontsdef#1#2{\def#1##1{#2}}% @@ -5208,6 +5294,20 @@ end \fi } +% Same as \doind, but for code indices +\def\docind#1#2{% + \iflinks + {% + % + \requireopenindexfile{#1}% + \edef\writeto{\csname#1indfile\endcsname}% + % + \def\indextext{#2}% + \safewhatsit\docindwrite + }% + \fi +} + % Check if an index file has been opened, and if not, open it. \def\requireopenindexfile#1{% \ifnum\csname #1indfile\endcsname=0 @@ -5274,6 +5374,9 @@ end % trim spaces. \edef\trimmed{\segment}% \edef\trimmed{\expandafter\eatspaces\expandafter{\trimmed}}% + \ifincodeindex + \edef\trimmed{\noexpand\code{\trimmed}}% + \fi % \xdef\bracedtext{\bracedtext{\trimmed}}% % @@ -5339,7 +5442,12 @@ end % Write the entry in \indextext to the index file. % -\def\doindwrite{% + +\newif\ifincodeindex +\def\doindwrite{\incodeindexfalse\doindwritex} +\def\docindwrite{\incodeindextrue\doindwritex} + +\def\doindwritex{% \maybemarginindex % \atdummies @@ -5559,7 +5667,11 @@ might help (with 'rm \jobname.?? \jobname.??s')% \else \begindoublecolumns \catcode`\\=0\relax - \catcode`\@=12\relax + % + % Make @ an escape character to give macros a chance to work. This + % should work because we (hopefully) don't otherwise use @ in index files. + %\catcode`\@=12\relax + \catcode`\@=0\relax \input \jobname.\indexname s \enddoublecolumns \fi @@ -6401,18 +6513,16 @@ might help (with 'rm \jobname.?? \jobname.??s')% \def\CHAPPAGoff{% \global\let\contentsalignmacro = \chappager \global\let\pchapsepmacro=\chapbreak -\global\let\pagealignmacro=\chappager} +\global\def\HEADINGSon{\HEADINGSsinglechapoff}} \def\CHAPPAGon{% \global\let\contentsalignmacro = \chappager \global\let\pchapsepmacro=\chappager -\global\let\pagealignmacro=\chappager \global\def\HEADINGSon{\HEADINGSsingle}} \def\CHAPPAGodd{% \global\let\contentsalignmacro = \chapoddpage \global\let\pchapsepmacro=\chapoddpage -\global\let\pagealignmacro=\chapoddpage \global\def\HEADINGSon{\HEADINGSdouble}} \CHAPPAGon @@ -6777,9 +6887,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% % \def\startcontents#1{% % If @setchapternewpage on, and @headings double, the contents should - % start on an odd page, unlike chapters. Thus, we maintain - % \contentsalignmacro in parallel with \pagealignmacro. - % From: Torbjorn Granlund <tege@matematik.su.se> + % start on an odd page, unlike chapters. \contentsalignmacro \immediate\closeout\tocfile % @@ -6794,6 +6902,9 @@ might help (with 'rm \jobname.?? \jobname.??s')% % % Roman numerals for page numbers. \ifnum \pageno>0 \global\pageno = \lastnegativepageno \fi + \def\thistitle{}% no title in double-sided headings + % Record where the Roman numerals started. + \ifnum\romancount=0 \global\romancount=\pagecount \fi } % redefined for the two-volume lispref. We always output on @@ -6816,8 +6927,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% \fi \closein 1 \endgroup - \lastnegativepageno = \pageno - \global\pageno = \savepageno + \contentsendroman } % And just the chapters. @@ -6852,10 +6962,20 @@ might help (with 'rm \jobname.?? \jobname.??s')% \vfill \eject \contentsalignmacro % in case @setchapternewpage odd is in effect \endgroup + \contentsendroman +} +\let\shortcontents = \summarycontents + +% Get ready to use Arabic numerals again +\def\contentsendroman{% \lastnegativepageno = \pageno \global\pageno = \savepageno + % + % If \romancount > \arabiccount, the contents are at the end of the + % document. Otherwise, advance where the Arabic numerals start for + % the page numbers. + \ifnum\romancount>\arabiccount\else\global\arabiccount=\pagecount\fi } -\let\shortcontents = \summarycontents % Typeset the label for a chapter or appendix for the short contents. % The arg is, e.g., `A' for an appendix, or `3' for a chapter. @@ -7444,13 +7564,9 @@ might help (with 'rm \jobname.?? \jobname.??s')% \newdimen\tabw \setbox0=\hbox{\tt\space} \tabw=8\wd0 % tab amount % % We typeset each line of the verbatim in an \hbox, so we can handle -% tabs. The \global is in case the verbatim line starts with an accent, -% or some other command that starts with a begin-group. Otherwise, the -% entire \verbbox would disappear at the corresponding end-group, before -% it is typeset. Meanwhile, we can't have nested verbatim commands -% (can we?), so the \global won't be overwriting itself. +% tabs. \newbox\verbbox -\def\starttabbox{\global\setbox\verbbox=\hbox\bgroup} +\def\starttabbox{\setbox\verbbox=\hbox\bgroup} % \begingroup \catcode`\^^I=\active @@ -7461,7 +7577,8 @@ might help (with 'rm \jobname.?? \jobname.??s')% \divide\dimen\verbbox by\tabw \multiply\dimen\verbbox by\tabw % compute previous multiple of \tabw \advance\dimen\verbbox by\tabw % advance to next multiple of \tabw - \wd\verbbox=\dimen\verbbox \box\verbbox \starttabbox + \wd\verbbox=\dimen\verbbox + \leavevmode\box\verbbox \starttabbox }% } \endgroup @@ -7471,9 +7588,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% \let\nonarrowing = t% \nonfillstart \tt % easiest (and conventionally used) font for verbatim - % The \leavevmode here is for blank lines. Otherwise, we would - % never \starttabbox and the \egroup would end verbatim mode. - \def\par{\leavevmode\egroup\box\verbbox\endgraf}% + \def\par{\egroup\leavevmode\box\verbbox\endgraf\starttabbox}% \tabexpand \setupmarkupstyle{verbatim}% % Respect line breaks, @@ -7481,7 +7596,6 @@ might help (with 'rm \jobname.?? \jobname.??s')% % make each space count. % Must do in this order: \obeylines \uncatcodespecials \sepspaces - \everypar{\starttabbox}% } % Do the @verb magic: verbatim text is quoted by unique @@ -7516,9 +7630,12 @@ might help (with 'rm \jobname.?? \jobname.??s')% % ignore everything up to the first ^^M, that's the newline at the end % of the @verbatim input line itself. Otherwise we get an extra blank % line in the output. - \xdef\doverbatim#1^^M#2@end verbatim{#2\noexpand\end\gobble verbatim}% + \xdef\doverbatim#1^^M#2@end verbatim{% + \starttabbox#2\egroup\noexpand\end\gobble verbatim}% % We really want {...\end verbatim} in the body of the macro, but % without the active space; thus we have to use \xdef and \gobble. + % The \egroup ends the \verbbox started at the end of the last line in + % the block. \endgroup % \envdef\verbatim{% @@ -7540,7 +7657,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% \wlog{texinfo.tex: doing @verbatiminclude of #1^^J}% \edef\tmp{\noexpand\input #1 } \expandafter - }\tmp + }\expandafter\starttabbox\tmp\egroup \afterenvbreak }% } @@ -7690,7 +7807,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% % If SUBTOPIC is present, precede it with a space, and call \doind. % (At some time during the 20th century, this made a two-level entry in an % index such as the operation index. Nobody seemed to notice the change in -% behavior though.) +% behaviour though.) \def\dosubind#1#2#3{% \def\thirdarg{#3}% \ifx\thirdarg\empty @@ -8955,17 +9072,11 @@ might help (with 'rm \jobname.?? \jobname.??s')% \else % Reference within this manual. % - % _ (for example) has to be the character _ for the purposes of the - % control sequence corresponding to the node, but it has to expand - % into the usual \leavevmode...\vrule stuff for purposes of - % printing. So we \turnoffactive for the \refx-snt, back on for the - % printing, back off for the \refx-pg. - {\turnoffactive - % Only output a following space if the -snt ref is nonempty; for - % @unnumbered and @anchor, it won't be. - \setbox2 = \hbox{\ignorespaces \refx{#1-snt}{}}% - \ifdim \wd2 > 0pt \refx{#1-snt}\space\fi - }% + % Only output a following space if the -snt ref is nonempty; for + % @unnumbered and @anchor, it won't be. + \setbox2 = \hbox{\ignorespaces \refx{#1-snt}{}}% + \ifdim \wd2 > 0pt \refx{#1-snt}\space\fi + % % output the `[mynode]' via the macro below so it can be overridden. \xrefprintnodename\printedrefname % @@ -9055,7 +9166,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% \requireauxfile {% \indexnofonts - \otherbackslash + \turnoffactive \def\value##1{##1}% \expandafter\global\expandafter\let\expandafter\thisrefX \csname XR#1\endcsname @@ -10712,6 +10823,8 @@ directory should work if nowhere else does.} \DeclareUnicodeCharacter{0233}{\=y}% \DeclareUnicodeCharacter{0237}{\dotless{j}}% % + \DeclareUnicodeCharacter{02BC}{'}% + % \DeclareUnicodeCharacter{02DB}{\ogonek{ }}% % % Greek letters upper case diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index 97a26421f2f..bdf3b403d80 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -46,7 +46,7 @@ copy and modify this GNU manual.'' @node Top, Overview, (dir), (dir) @top @value{tramp} @value{trampver} User Manual -This file documents @value{tramp} @value{trampver}, a remote file +This file documents @w{@value{tramp} @value{trampver}}, a remote file editing package for Emacs. @value{tramp} stands for ``Transparent Remote (file) Access, Multiple @@ -59,7 +59,7 @@ local and the remote host, whereas @value{tramp} uses a combination of @command{ssh}/@command{scp}. You can find the latest version of this document on the web at -@uref{https://www.gnu.org/software/tramp/}. +@uref{@value{trampurl}}. @ifhtml The latest release of @value{tramp} is available for @@ -141,6 +141,7 @@ Configuring @value{tramp} for use * Remote shell setup:: Remote shell setup hints. * Android shell setup:: Android shell setup hints. * Auto-save and Backup:: Auto-save and Backup. +* Keeping files encrypted:: Protect remote files by encryption. * Windows setup hints:: Issues with Cygwin ssh. Using @value{tramp} @@ -238,7 +239,7 @@ included in the file name portion, @value{tramp} sends the login name followed by a newline. @item -The remote host may then prompt for a password or pass phrase (for +The remote host may then prompt for a password or passphrase (for @command{rsh} or for @command{telnet}). @value{tramp} displays the password prompt in the minibuffer. @value{tramp} then sends whatever is entered to the remote host, followed by a newline. @@ -312,7 +313,7 @@ behind the scenes when you open a file with @value{tramp}. @cindex GNU ELPA @vindex tramp-version -@value{tramp} is included as part of Emacs (since Emacs 22.1). +@value{tramp} is included as part of Emacs (since @w{Emacs 22.1}). @value{tramp} is also freely packaged for download on the Internet at @uref{https://ftp.gnu.org/gnu/tramp/}. The version number of @@ -324,9 +325,9 @@ A @value{tramp} release, which is packaged with Emacs, could differ slightly from the corresponding standalone release. This is because it isn't always possible to synchronize release dates between Emacs and @value{tramp}. Such version numbers have the Emacs version number -as suffix, like ``2.4.3.27.1''. This means @value{tramp} 2.4.3 as -integrated in Emacs 27.1. A complete list of @value{tramp} versions -packaged with Emacs can be retrieved by +as suffix, like ``2.4.3.27.1''. This means @w{@value{tramp} 2.4.3} as +integrated in @w{Emacs 27.1}. A complete list of @value{tramp} +versions packaged with Emacs can be retrieved by @vindex customize-package-emacs-version-alist @lisp @@ -557,13 +558,16 @@ of the local file name is the share exported by the remote host, @cindex method @option{davs} @cindex @option{dav} method @cindex @option{davs} method +@cindex method @option{media} +@cindex @option{media} method On systems, which have installed @acronym{GVFS, the GNOME Virtual File System}, its offered methods could be used by @value{tramp}. Examples are @file{@trampfn{sftp,user@@host,/path/to/file}}, @file{@trampfn{afp,user@@host,/path/to/file}} (accessing Apple's AFP -file system), @file{@trampfn{dav,user@@host,/path/to/file}} and -@file{@trampfn{davs,user@@host,/path/to/file}} (for WebDAV shares). +file system), @file{@trampfn{dav,user@@host,/path/to/file}}, +@file{@trampfn{davs,user@@host,/path/to/file}} (for WebDAV shares) and +@file{@trampfn{media,device,/path/to/file}} (for media devices). @anchor{Quick Start Guide: GNOME Online Accounts based methods} @@ -664,6 +668,7 @@ might be used in your init file: * Remote shell setup:: Remote shell setup hints. * Android shell setup:: Android shell setup hints. * Auto-save and Backup:: Auto-save and Backup. +* Keeping files encrypted:: Protect remote files by encryption. * Windows setup hints:: Issues with Cygwin ssh. @end menu @@ -1126,7 +1131,8 @@ Emacs. @value{tramp} does not require a host name part of the remote file name when a single Android device is connected to @command{adb}. @value{tramp} instead uses @file{@trampfn{adb,,}} as the default name. -@command{adb devices} shows available host names. +@command{adb devices}, run in a shell outside Emacs, shows available +host names. @option{adb} method normally does not need user name to authenticate on the Android device because it runs under the @command{adbd} @@ -1179,9 +1185,6 @@ for accessing the system storage, you shall prefer this. @ref{GVFS-based methods} for example, methods @option{gdrive} and @option{nextcloud}. -@strong{Note}: The @option{rclone} method is experimental, don't use -it in production systems! - @end table @@ -1227,6 +1230,7 @@ supported by these methods. See method @option{nextcloud} for handling them. @item @option{gdrive} +@cindex @acronym{GNOME} Online Accounts @cindex method @option{gdrive} @cindex @option{gdrive} method @cindex google drive @@ -1242,8 +1246,26 @@ Since Google Drive uses cryptic blob file names internally, could produce unexpected behavior in case two files in the same directory have the same @code{display-name}, such a situation must be avoided. +@item @option{media} +@cindex method @option{media} +@cindex @option{media} method +@cindex media + +Media devices, like cell phones, tablets, cameras, can be accessed via +the @option{media} method. Just the device name is needed in order to +specify the host in the file name. However, the device must already +be connected via USB, before accessing it. Possible device names are +visible via host name completion, @ref{File name completion}. + +Depending on the device type, the access could be read-only. Some +devices are accessible under different names in parallel, offering +different parts of their file system. + +@value{tramp} does not require a host name as part of the remote file +name when a single media device is connected. @value{tramp} instead +uses @file{@trampfn{media,,}} as the default name. + @item @option{nextcloud} -@cindex @acronym{GNOME} Online Accounts @cindex method @option{nextcloud} @cindex @option{nextcloud} method @cindex nextcloud @@ -1267,11 +1289,11 @@ that for security reasons refuse @command{ssh} connections. @defopt tramp-gvfs-methods This user option is a list of external methods for @acronym{GVFS}@. By default, this list includes @option{afp}, @option{dav}, -@option{davs}, @option{gdrive}, @option{nextcloud} and @option{sftp}. -Other methods to include are @option{ftp}, @option{http}, -@option{https} and @option{smb}. These methods are not intended to be -used directly as @acronym{GVFS}-based method. Instead, they are added -here for the benefit of @ref{Archive file names}. +@option{davs}, @option{gdrive}, @option{media}, @option{nextcloud} and +@option{sftp}. Other methods to include are @option{ftp}, +@option{http}, @option{https} and @option{smb}. These methods are not +intended to be used directly as @acronym{GVFS}-based method. Instead, +they are added here for the benefit of @ref{Archive file names}. If you want to use @acronym{GVFS}-based @option{ftp} or @option{smb} methods, you must add them to @code{tramp-gvfs-methods}, and you must @@ -1642,7 +1664,7 @@ suitable settings. Refer to the Lisp documentation of that variable, accessible with @kbd{C-h v tramp-methods @key{RET}}. In the ELPA archives, there are several examples of such extensions. -They can be installed with Emacs' Package Manager. This includes +They can be installed with Emacs's Package Manager. This includes @table @samp @c @item anything-tramp @@ -1708,6 +1730,7 @@ Convenience method to access vagrant boxes. It is often used in multi-hop file names like @file{@value{prefix}vagrant@value{postfixhop}box|sudo@value{postfixhop}box@value{postfix}/path/to/file}, where @samp{box} is the name of the vagrant box. + @end table @@ -2030,6 +2053,13 @@ The temporary directory on the remote host. If not specified, the default value is @t{"/data/local/tmp"} for the @option{adb} method, @t{"/C$/Temp"} for the @option{smb} method, and @t{"/tmp"} otherwise. +@item @t{"direct-async-process"} + +When this property is non-@code{nil}, an alternative, more performant +implementation of @code{make-process} and +@code{start-file-process} is applied. @ref{Improving performance of +asynchronous remote processes} for a discussion of constraints. + @item @t{"posix"} Connections using the @option{smb} method check, whether the remote @@ -2075,7 +2105,7 @@ To improve performance and accuracy of remote file access, @file{/usr/bin}, which are reasonable for most hosts. To accommodate differences in hosts and paths, for example, @file{/bin:/usr/bin} on Debian GNU/Linux or -@file{/usr/xpg4/bin:/usr/ccs/bin:/usr/bin:/opt/SUNWspro/bin} on +@file{/usr/xpg4/bin:/usr/ccs/bin:/usr/bin:/opt/developerstudio12.6/bin} on Solaris, @value{tramp} queries the remote host with @command{getconf PATH} and updates the symbol @code{tramp-default-remote-path}. @@ -2102,8 +2132,8 @@ preserves the path value, which can be used to update shell supports the login argument @samp{-l}. @end defopt -Starting with Emacs 26, @code{tramp-remote-path} can be set per host -via connection-local +Starting with @w{Emacs 26}, @code{tramp-remote-path} can be set per +host via connection-local @ifinfo variables, @xref{Connection Variables, , , emacs}. @end ifinfo @@ -2435,10 +2465,9 @@ overwrite as follows: @lisp @group -(add-to-list - 'tramp-connection-properties - `(,(regexp-quote "192.168.0.1") - "remote-copy-args" (("-l") ("%r")))) +(add-to-list 'tramp-connection-properties + `(,(regexp-quote "192.168.0.1") + "remote-copy-args" (("-l") ("%r")))) @end group @end lisp @@ -2457,7 +2486,7 @@ where @samp{192.168.0.1} is the remote host IP address Android devices provide a restricted shell access through an USB connection. The local host must have the @command{adb} program installed. Usually, it is sufficient to open the file -@file{@trampfn{adb,,/}}. Then you can navigate in the filesystem via +@file{@trampfn{adb,,/}}. Then you can navigate in the file system via @code{dired}. Alternatively, applications such as @code{Termux} or @code{SSHDroid} @@ -2632,6 +2661,117 @@ auto-saved files to the same directory as the original file. Alternatively, set the user option @code{tramp-auto-save-directory} to direct all auto saves to that location. + +@node Keeping files encrypted +@section Protect remote files by encryption +@cindex Encrypt remote directories + +@strong{Note}: File encryption in @value{tramp} is experimental, don't +use it in production systems! + +Sometimes, it is desirable to protect files located on remote +directories, like cloud storages. In order to do this, you might +instruct @value{tramp} to encrypt all files copied to a given remote +directory, and to decrypt such files when accessing. This includes +both file contents and file names. + +@value{tramp} does this transparently. Although both files and file +names are encrypted on the remote side, they are accessible inside +Emacs as they wouldn't be transformed as such. + +@cindex @command{encfs} +@cindex @command{encfsctl} +Internally, @value{tramp} uses the @command{encfs} package. +Therefore, this feature is available only if this package is installed +on the local host. @value{tramp} does not keep and @samp{encfs +mountpoint} permanently. Instead, it encrypts / decrypts files and +file names on the fly, using @command{encfsctl}. + +@deffn Command tramp-crypt-add-directory name +This command marks the existing remote directory @var{name} for +encryption. Files in that directory and all subdirectories will be +encrypted before copying to, and decrypted after copying from that +directory. File and directory names will be also encrypted. +@end deffn + +@defopt tramp-crypt-encfs-option +If a remote directory is marked for encryption, it is initialized via +@command{encfs} the very first time a file in this directory is +accessed. This user option controls, which default @command{encfs} +configuration option will be selected, it can be @t{"--standard"} +or @t{"--paranoia"}. See the @samp{encfs(1)} man page for details. + +However, @value{tramp} must adapt these configuration sets. The +@code{chainedNameIV} configuration option must be disabled; otherwise +@value{tramp} couldn't handle file name encryption transparently. +@end defopt + +A password protected @option{encfs} configuration file is created the +very first time you access an encrypted remote directory. It is kept +in your @code{user-emacs-directory} with the url-encoded directory +name as part of the basename, and @file{encfs6.xml} as suffix. If +you, for example, mark the remote directory +@file{@trampfn{nextcloud,user@@host,/path/to/dir}} for encryption, the +configuration file is saved as +@file{tramp-%2Fnextcloud%3Auser%40host%3A%2Fpath%2Fto%2Fdir%2F.encfs6.xml} +in @code{user-emacs-directory}. Do not loose this file and the +corresponding password; otherwise there is no way to decrypt your +encrypted files. + +@defopt tramp-crypt-save-encfs-config-remote +If this user option is non-nil (the default), the @option{encfs} +configuration file @file{.encfs6.xml} is also kept in the encrypted +remote directory. It depends on you, whether you regard the password +protection of this file as sufficient. The advantage would be, that +such a remote directory could be accessed by different Emacs sessions, +different users, without presharing the configuration file between the +users. +@end defopt + +The command @command{encfsctl}, the workhorse for encryption / +decryption, needs the configuration file password every call. +Therefore, it is recommend to cache this password in Emacs. This can +be done using @code{auth-sources}, @ref{Using an authentication file}. +An entry needs the url-encoded directory name as machine, your local +user name as user, and the password. The port is optional, if given +it must be the string @t{"crypt"}. The example above would require +the following entry in the authentication file (@t{"yourname"} is the +result of @code{(user-login-name)}): + +@example +machine %2Fnextcloud%3Auser%40host%3A%2Fpath%2Fto%2Fdir%2F \ + login yourname port crypt password geheim +@end example + +If you use a remote file name with a quoted localname part, this +localname and the corresponding file will not be encrypted / +decrypted. If you have an encrypted remote directory +@file{@trampfn{nextcloud,user@@host,/path/to/dir}}, the command + +@example +@kbd{C-x d @trampfn{nextcloud,user@@host,/path/to/dir}} +@end example + +@noindent +will show the directory listing with the plain file names, and the +command + +@example +@kbd{C-x d @trampfn{nextcloud,user@@host,/:/path/to/dir}} +@end example + +@noindent +will show the directory listing with the encrypted file names, and +visiting a file will show its encrypted contents. However, it is +highly discouraged to mix encrypted and not encrypted files in the +same directory. + +@deffn Command tramp-crypt-add-directory name +If a remote directory shall not include encrypted files anymore, it +must be indicated by this command. +@end deffn + + @node Windows setup hints @section Issues with Cygwin ssh @cindex cygwin, issues @@ -2665,10 +2805,10 @@ Wiki} it is explained how to use the helper program @cindex @option{scpx} method with cygwin When using the @option{scpx} access method, Emacs may call -@command{scp} with MS Windows file naming, such as @code{c:/foo}. But +@command{scp} with MS Windows file naming, such as @file{c:/foo}. But the version of @command{scp} that is installed with Cygwin does not know about MS Windows file naming, which causes it to incorrectly look -for a host named @code{c}. +for a host named @samp{c}. A workaround: write a wrapper script for @option{scp} to convert Windows file names to Cygwin file names. @@ -2944,10 +3084,10 @@ Example: @end example During file name completion, remote directory contents are re-read -regularly to account for any changes in the filesystem that may affect -the completion candidates. Such re-reads can account for changes to -the file system by applications outside Emacs (@pxref{Connection -caching}). +regularly to account for any changes in the file system that may +affect the completion candidates. Such re-reads can account for +changes to the file system by applications outside Emacs +(@pxref{Connection caching}). @defopt tramp-completion-reread-directory-timeout The timeout is number of seconds since last remote command for @@ -3187,8 +3327,8 @@ ensures the correct name of the remote shell program. When @code{explicit-shell-file-name} is equal to @code{nil}, calling @code{shell} interactively will prompt for a shell name. -Starting with Emacs 26, you could use connection-local variables for -setting different values of @code{explicit-shell-file-name} for +Starting with @w{Emacs 26}, you could use connection-local variables +for setting different values of @code{explicit-shell-file-name} for different remote hosts. @ifinfo @xref{Connection Variables, , , emacs}. @@ -3238,8 +3378,8 @@ host. Example: @end group @end example -@command{tail} command outputs continuously to the local buffer, -@file{*Async Shell Command*} +@command{tail} command outputs continuously to the local buffer whose +name is the value of the variable @code{shell-command-buffer-name-async}. @kbd{M-x auto-revert-tail-mode @key{RET}} runs similarly showing continuous output. @@ -3257,10 +3397,10 @@ variables. @vindex async-shell-command-width @vindex COLUMNS@r{, environment variable} If Emacs supports the variable @code{async-shell-command-width} (since -Emacs 27), @value{tramp} cares about its value for asynchronous shell -commands. It specifies the number of display columns for command -output. For synchronous shell commands, a similar effect can be -achieved by adding the environment variable @env{COLUMNS} to +@w{Emacs 27}), @value{tramp} cares about its value for asynchronous +shell commands. It specifies the number of display columns for +command output. For synchronous shell commands, a similar effect can +be achieved by adding the environment variable @env{COLUMNS} to @code{tramp-remote-process-environment}. @@ -3393,6 +3533,77 @@ To open @command{powershell} as a remote shell, use this: @end lisp +@anchor{Improving performance of asynchronous remote processes} +@subsection Improving performance of asynchronous remote processes +@cindex Asynchronous remote processes +@findex make-process +@findex start-file-process + +@value{tramp}'s implementation of @code{make-process} and +@code{start-file-process} requires a serious overhead for +initialization, every process invocation. This is needed for handling +interactive dialogues when connecting the remote host (like providing +a password), and initial environment setup. + +Sometimes, this is not needed. Instead of starting a remote shell and +running the command afterwards, it is sufficient to run the command +directly. @value{tramp} supports this by an alternative +implementation of @code{make-process} and @code{start-file-process}. +This is triggered by the connection property +@t{"direct-async-process"}, @xref{Predefined connection information}, +which must be set to a non-@code{nil} value. Example: + +@lisp +@group +(add-to-list 'tramp-connection-properties + (list (regexp-quote "@trampfn{ssh,user@@host,}") + "direct-async-process" t)) +@end group +@end lisp + +Using direct asynchronous processes in @value{tramp} is not possible, +if the remote host is connected via multiple hops +(@pxref{Multi-hops}). In this case, @value{tramp} falls back to its +classical implementation. + +Furthermore, this approach has the following limitations: + +@itemize +@item +It works only for connection methods defined in @file{tramp-sh.el} and +@file{tramp-adb.el}. + +@item +It does not support interactive user authentication. With +@option{ssh}-based methods, this can be avoided by using a password +agent like @command{ssh-agent}, using public key authentication, or +using @code{ControlMaster} options. + +@item +It cannot be killed via @code{interrupt-process}. + +@item +It does not report the remote terminal name via @code{process-tty-name}. + +@item +It does not set process property @code{remote-pid}. + +@item +It does not use @code{tramp-remote-path} and +@code{tramp-remote-process-environment}. + +@item +It does not set environment variable @env{INSIDE_EMACS}. +@end itemize + +In order to gain even more performance, it is recommended to bind +@code{tramp-verbose} to 0 when running @code{make-process} or +@code{start-file-process}. Furthermore, you might set +@code{tramp-use-ssh-controlmaster-options} to @code{nil} in order to +bypass @value{tramp}'s handling of the @code{ControlMaster} options, +and use your own settings in @file{~/.ssh/config}. + + @node Cleanup remote connections @section Cleanup remote connections @cindex cleanup @@ -3879,8 +4090,8 @@ Where is the latest @value{tramp}? @item Which systems does it work on? -The package works successfully on Emacs 24, Emacs 25, Emacs 26, Emacs -27, and Emacs 28. +The package works successfully on @w{Emacs 25}, @w{Emacs 26}, @w{Emacs +27}, and @w{Emacs 28}. While Unix and Unix-like systems are the primary remote targets, @value{tramp} has equal success connecting to other platforms, such as @@ -4142,8 +4353,8 @@ Host * @end group @end example -Check @command{man ssh_config} whether these options are supported on -your proxy host. +Check the @samp{ssh_config(5)} man page whether these options are +supported on your proxy host. @item @@ -4234,7 +4445,7 @@ Host indication in the mode line? @cindex @value{tramp} theme @vindex tramp-theme-face-remapping-alist -Install @file{tramp-theme} from GNU ELPA via Emacs' Package Manager. +Install @file{tramp-theme} from GNU ELPA via Emacs's Package Manager. Enable it via @kbd{M-x load-theme @key{RET} tramp @key{RET}}. Further customization is explained in user option @code{tramp-theme-face-remapping-alist}. @@ -4421,9 +4632,8 @@ Abbreviation list expansion can be used to reduce typing long file names: @lisp @group -(add-to-list - 'directory-abbrev-alist - '("^/xy" . "@trampfn{ssh,news@@news.my.domain,/opt/news/etc/}")) +(add-to-list 'directory-abbrev-alist + '("^/xy" . "@trampfn{ssh,news@@news.my.domain,/opt/news/etc/}")) @end group @end lisp diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi index cc3c768fe6e..dbebbc36812 100644 --- a/doc/misc/trampver.texi +++ b/doc/misc/trampver.texi @@ -8,9 +8,10 @@ @c In the Tramp GIT, the version numbers are auto-frobbed from @c tramp.el, and the bug report address is auto-frobbed from @c configure.ac. -@set trampver 2.4.5-pre +@set trampver 2.5.0-pre +@set trampurl https://www.gnu.org/software/tramp/ @set tramp-bug-report-address tramp-devel@@gnu.org -@set emacsver 24.4 +@set emacsver 25.1 @c Other flags from configuration. @set instprefix /usr/local diff --git a/doc/misc/url.texi b/doc/misc/url.texi index 8d9b1024070..0304ff4b9f1 100644 --- a/doc/misc/url.texi +++ b/doc/misc/url.texi @@ -1312,8 +1312,6 @@ repeated visits do not require repeated domain lookups. @end defopt @defopt url-max-password-attempts @end defopt -@defopt url-temporary-directory -@end defopt @defopt url-show-status @end defopt @defopt url-confirmation-func diff --git a/doc/misc/viper.texi b/doc/misc/viper.texi index 9ce809e7d4d..661eb7c947a 100644 --- a/doc/misc/viper.texi +++ b/doc/misc/viper.texi @@ -1752,10 +1752,10 @@ state. If @code{nil}, the cursor stays where it was before the switch. @item viper-always t @code{t} means: leave it to Viper to decide when a buffer must be brought up in Vi state, -Insert state, or Emacs state. This heuristics works well in virtually all -cases. @code{nil} means you either has to invoke @code{viper-mode} manually +Insert state, or Emacs state. This heuristic works well in virtually all +cases. @code{nil} means you either have to invoke @code{viper-mode} manually for each buffer (or you can add @code{viper-mode} to the appropriate major mode -hooks using @code{viper-load-hook}). +hooks using @code{with-eval-after-load}). This option must be set in your Viper customization file. @item viper-custom-file-name "~/.emacs.d/viper" @@ -1903,9 +1903,6 @@ List of (parameterless) functions called just after entering Replace state @item viper-emacs-state-hook nil List of (parameterless) functions called just after switching from Vi state to Emacs state. -@item viper-load-hook nil -List of (parameterless) functions called just after loading Viper. This is -the last chance to do customization before Viper is up and running. @end table @noindent You can reset some of these constants in Viper with the Ex command @kbd{:set} |