commit 8224430bd9d71dfcf2524b758d8ac14a1d93b0d5 (HEAD, refs/remotes/origin/master) Author: Alan Mackenzie Date: Sat Feb 17 09:14:54 2018 +0000 Fix the change from 2018-02-15 which didn't mention literals * doc/emacs/programs.texi (Left Margin Paren): Document that opening delimiters at column 0 which are inside strings or comments aren't regarded as defun starts. diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi index d0aa6a03b5..215717864f 100644 --- a/doc/emacs/programs.texi +++ b/doc/emacs/programs.texi @@ -168,10 +168,10 @@ position. the user option @code{open-paren-in-column-0-is-defun-start} to @code{nil}. If this option is set to @code{t} (the default), commands seeking the start of a defun will stop at opening parentheses or -braces at column zero. When it is @code{nil}, defuns are found by -searching for parens or braces at the outermost level. Since -low-level Emacs routines no longer depend on this convention, you -usually won't need to change +braces at column zero which aren't in a comment or string. When it is +@code{nil}, defuns are found by searching for parens or braces at the +outermost level. Since low-level Emacs routines no longer depend on +this convention, you usually won't need to change @code{open-paren-in-column-0-is-defun-start} from its default. @node Moving by Defuns commit 0cb1c59aa891c6a04d3b9701485b20bfd6d8f2aa Author: Glenn Morris Date: Fri Feb 16 19:11:59 2018 -0800 Quieten compilation of icalendar.el * lisp/calendar/icalendar.el (icalendar-import-buffer) (icalendar--convert-ical-to-diary, icalendar--add-diary-entry): Eliminate "Lexical argument shadows the dynamic variable" warning. diff --git a/lisp/calendar/icalendar.el b/lisp/calendar/icalendar.el index a725a4e916..7af1520da4 100644 --- a/lisp/calendar/icalendar.el +++ b/lisp/calendar/icalendar.el @@ -1975,13 +1975,13 @@ P") (icalendar-import-buffer diary-filename t non-marking))) ;;;###autoload -(defun icalendar-import-buffer (&optional diary-file do-not-ask +(defun icalendar-import-buffer (&optional diary-filename do-not-ask non-marking) "Extract iCalendar events from current buffer. This function searches the current buffer for the first iCalendar object, reads it and adds all VEVENT elements to the diary -DIARY-FILE. +DIARY-FILENAME. It will ask for each appointment whether to add it to the diary unless DO-NOT-ASK is non-nil. When called interactively, @@ -2011,10 +2011,10 @@ buffer `*icalendar-errors*'." (message "Converting iCalendar...") (setq ical-errors (icalendar--convert-ical-to-diary ical-contents - diary-file do-not-ask non-marking)) - (when diary-file + diary-filename do-not-ask non-marking)) + (when diary-filename ;; save the diary file if it is visited already - (let ((b (find-buffer-visiting diary-file))) + (let ((b (find-buffer-visiting diary-filename))) (when b (save-current-buffer (set-buffer b) @@ -2066,12 +2066,12 @@ buffer `*icalendar-errors*'." conversion-list) string))) -(defun icalendar--convert-ical-to-diary (ical-list diary-file +(defun icalendar--convert-ical-to-diary (ical-list diary-filename &optional do-not-ask non-marking) "Convert iCalendar data to an Emacs diary file. Import VEVENTS from the iCalendar object ICAL-LIST and saves them to a -DIARY-FILE. If DO-NOT-ASK is nil the user is asked for each event +DIARY-FILENAME. If DO-NOT-ASK is nil the user is asked for each event whether to actually import it. NON-MARKING determines whether diary events are created as non-marking. This function attempts to return t if something goes wrong. In this @@ -2199,8 +2199,8 @@ written into the buffer `*icalendar-errors*'." (if do-not-ask (setq summary nil)) ;; add entry to diary and store actual name of diary ;; file (in case it was nil) - (setq diary-file - (icalendar--add-diary-entry diary-string diary-file + (setq diary-filename + (icalendar--add-diary-entry diary-string diary-filename non-marking summary))) ;; event was not ok (setq found-error t) @@ -2217,8 +2217,8 @@ written into the buffer `*icalendar-errors*'." (message "%s" error-string)))) ;; insert final newline - (if diary-file - (let ((b (find-buffer-visiting diary-file))) + (if diary-filename + (let ((b (find-buffer-visiting diary-filename))) (when b (save-current-buffer (set-buffer b) @@ -2498,9 +2498,9 @@ END-T is the event's end time in diary format." dtstart-dec "/") start-t)))) -(defun icalendar--add-diary-entry (string diary-file non-marking +(defun icalendar--add-diary-entry (string diary-filename non-marking &optional summary) - "Add STRING to the diary file DIARY-FILE. + "Add STRING to the diary file DIARY-FILENAME. STRING must be a properly formatted valid diary entry. NON-MARKING determines whether diary events are created as non-marking. If SUMMARY is not nil it must be a string that gives the summary of the @@ -2513,21 +2513,21 @@ the entry." (setq non-marking (y-or-n-p (format "Make appointment non-marking? ")))) (save-window-excursion - (unless diary-file - (setq diary-file + (unless diary-filename + (setq diary-filename (read-file-name "Add appointment to this diary file: "))) ;; Note: diary-make-entry will add a trailing blank char.... :( (funcall (if (fboundp 'diary-make-entry) 'diary-make-entry 'make-diary-entry) - string non-marking diary-file))) + string non-marking diary-filename))) ;; Würgaround to remove the trailing blank char - (with-current-buffer (find-file diary-file) + (with-current-buffer (find-file diary-filename) (goto-char (point-max)) (if (= (char-before) ? ) (delete-char -1))) - ;; return diary-file in case it has been changed interactively - diary-file) + ;; return diary-filename in case it has been changed interactively + diary-filename) ;; ====================================================================== ;; Examples commit b04fa19119c6db126bf0f80a1d610e21a7a27c23 Author: Glenn Morris Date: Fri Feb 16 18:57:45 2018 -0800 ; * lisp/international/mule-cmds.el (reset-language-environment): Comment. diff --git a/lisp/international/mule-cmds.el b/lisp/international/mule-cmds.el index 3468166263..f737869eef 100644 --- a/lisp/international/mule-cmds.el +++ b/lisp/international/mule-cmds.el @@ -1795,6 +1795,9 @@ The default status is as follows: (setq default-sendmail-coding-system 'iso-latin-1) ;; On Darwin systems, this should be utf-8-unix, but when this file is loaded ;; that is not yet defined, so we set it in set-locale-environment instead. + ;; [Actually, it seems to work fine to use utf-8-unix here, and not just + ;; on Darwin. The previous comment seems to be outdated? + ;; See patch at https://debbugs.gnu.org/15803 ] (setq default-file-name-coding-system 'iso-latin-1-unix) ;; Preserve eol-type from existing default-process-coding-systems. ;; On non-unix-like systems in particular, these may have been set commit 47106da23ac2b19ad994eed95cdcb0d33535281d Merge: 4ba32858d6 a06a8ed5b6 Author: Glenn Morris Date: Fri Feb 16 09:44:04 2018 -0800 Merge from origin/emacs-26 a06a8ed (origin/emacs-26) ; * lisp/vc/vc-git.el (vc-git--program-vers... edc06ad Make 'byte-compile-error-on-warn' a safe file variable 9f5d8da ; * lisp/textmodes/flyspell.el (flyspell-auto-correct-word): ... f73905a Fix the doc string of flyspell-auto-correct-word e9c7ddc Improve the MS-Windows appendix of the Emacs manual 6ddb4bd Fix 'vc-git--program-version' 63c93f7 Fix typos and wording in the Emacs manual 42f15b0 * doc/emacs/programs.texi (Semantic): Order programming langu... b46be29 More improvements for the Emacs manual 874c0ed Minor wording change in Emacs manual 53511f9 Another set of changes for the manual 78426b8 Improvements on tramp.texi 0dca618 Tramp minor doc fixes Conflicts: doc/misc/tramp.texi commit a06a8ed5b66883202ae7182471570dfcabcea973 Author: Eli Zaretskii Date: Fri Feb 16 19:20:29 2018 +0200 ; * lisp/vc/vc-git.el (vc-git--program-version): Fix last change. diff --git a/lisp/vc/vc-git.el b/lisp/vc/vc-git.el index 7ebb72f270..2d0ea9ce60 100644 --- a/lisp/vc/vc-git.el +++ b/lisp/vc/vc-git.el @@ -242,7 +242,7 @@ Should be consistent with the Git config value i18n.logOutputEncoding." ;; Git for Windows appends ".windows.N" to the ;; numerical version reported by Git. (string-match - "git version \\([0-9.]+\\)\\(\.windows.[0-9]+\\)$" + "git version \\([0-9.]+\\)\\(\.windows.[0-9]+\\)?$" version-string)) (match-string 1 version-string) "0"))))) commit 4ba32858d61eee16f17b51aca01c15211a0912f8 Author: Matthias Dahl Date: Fri Feb 16 17:57:40 2018 +0200 Fix wait_reading_process_output wait_proc hang * src/process.c (read_process_output): Track bytes read from a process. (wait_reading_process_output): If called recursively through timers and/or process filters via accept-process-output, it is possible that the output of wait_proc has already been read by one of those recursive calls, leaving the original call hanging forever if no further output arrives through that fd and no timeout has been set. Fix that by using the process read accounting to keep track of how many bytes have been read and use that as a condition to break out of the infinite loop and return to the caller as well as to calculate the proper return value (if a wait_proc is given that is). * src/process.h (struct Lisp_Process): Add nbytes_read to track bytes read from a process. diff --git a/src/process.c b/src/process.c index 2ec10b12ec..496b1f2b70 100644 --- a/src/process.c +++ b/src/process.c @@ -5006,6 +5006,7 @@ wait_reading_process_output (intmax_t time_limit, int nsecs, int read_kbd, struct timespec got_output_end_time = invalid_timespec (); enum { MINIMUM = -1, TIMEOUT, INFINITY } wait; int got_some_output = -1; + uintmax_t prev_wait_proc_nbytes_read = wait_proc ? wait_proc->nbytes_read : 0; #if defined HAVE_GETADDRINFO_A || defined HAVE_GNUTLS bool retry_for_async; #endif @@ -5460,6 +5461,8 @@ wait_reading_process_output (intmax_t time_limit, int nsecs, int read_kbd, if (nfds == 0) { /* Exit the main loop if we've passed the requested timeout, + or have read some bytes from our wait_proc (either directly + in this call or indirectly through timers / process filters), or aren't skipping processes and got some output and haven't lowered our timeout due to timers or SIGIO and have waited a long amount of time due to repeated @@ -5467,7 +5470,9 @@ wait_reading_process_output (intmax_t time_limit, int nsecs, int read_kbd, struct timespec huge_timespec = make_timespec (TYPE_MAXIMUM (time_t), 2 * TIMESPEC_RESOLUTION); struct timespec cmp_time = huge_timespec; - if (wait < TIMEOUT) + if (wait < TIMEOUT + || (wait_proc + && wait_proc->nbytes_read != prev_wait_proc_nbytes_read)) break; if (wait == TIMEOUT) cmp_time = end_time; @@ -5772,6 +5777,15 @@ wait_reading_process_output (intmax_t time_limit, int nsecs, int read_kbd, maybe_quit (); } + /* Timers and/or process filters that we have run could have themselves called + `accept-process-output' (and by that indirectly this function), thus + possibly reading some (or all) output of wait_proc without us noticing it. + This could potentially lead to an endless wait (dealt with earlier in the + function) and/or a wrong return value (dealt with here). */ + if (wait_proc && wait_proc->nbytes_read != prev_wait_proc_nbytes_read) + got_some_output = min (INT_MAX, (wait_proc->nbytes_read + - prev_wait_proc_nbytes_read)); + return got_some_output; } @@ -5890,6 +5904,9 @@ read_process_output (Lisp_Object proc, int channel) coding->mode |= CODING_MODE_LAST_BLOCK; } + /* Ignore carryover, it's been added by a previous iteration already. */ + p->nbytes_read += nbytes; + /* Now set NBYTES how many bytes we must decode. */ nbytes += carryover; diff --git a/src/process.h b/src/process.h index ab468b18c5..6464a8cc61 100644 --- a/src/process.h +++ b/src/process.h @@ -129,6 +129,8 @@ struct Lisp_Process pid_t pid; /* Descriptor by which we read from this process. */ int infd; + /* Byte-count modulo (UINTMAX_MAX + 1) for process output read from `infd'. */ + uintmax_t nbytes_read; /* Descriptor by which we write to this process. */ int outfd; /* Descriptors that were created for this process and that need commit edc06adf96f4aa9d8b707181015acfe61d396edb Author: Robert Cochran Date: Fri Feb 16 17:51:06 2018 +0200 Make 'byte-compile-error-on-warn' a safe file variable * lisp/emacs-lisp/bytecomp.el (byte-compile-error-on-warn): Mark as a safe local variable for boolean values. diff --git a/lisp/emacs-lisp/bytecomp.el b/lisp/emacs-lisp/bytecomp.el index 700a7c16b5..c179ffcafd 100644 --- a/lisp/emacs-lisp/bytecomp.el +++ b/lisp/emacs-lisp/bytecomp.el @@ -295,6 +295,11 @@ The information is logged to `byte-compile-log-buffer'." "If true, the byte-compiler reports warnings with `error'." :group 'bytecomp :type 'boolean) +;; This needs to be autoloaded because it needs to be available to +;; Emacs before the byte compiler is loaded, otherwise Emacs will not +;; know that this variable is marked as safe until it is too late. +;; (See https://lists.gnu.org/archive/html/emacs-devel/2018-01/msg00261.html ) +;;;###autoload(put 'byte-compile-error-on-warn 'safe-local-variable 'booleanp) (defconst byte-compile-warning-types '(redefine callargs free-vars unresolved commit 49fc040077b33bd1e78ee425575e76329b772a41 Author: Aaron Jensen Date: Fri Feb 16 17:43:04 2018 +0200 Don't flash previous buffer when connecting with emacsclient * lisp/server.el (server-execute): Accept lambda for creating frame rather than frame. Ensure newly created tty frame initially shows the correct buffer. (server-process-filter): Pass a lambda to server-execute to create a frame. (Bug#24218) diff --git a/lisp/server.el b/lisp/server.el index d3933883cf..a892203c24 100644 --- a/lisp/server.el +++ b/lisp/server.el @@ -1092,7 +1092,8 @@ The following commands are accepted by the client: tty-type ; string. files filepos - args-left) + args-left + create-frame-func) ;; Remove this line from STRING. (setq string (substring string (match-end 0))) (setq args-left @@ -1244,28 +1245,29 @@ The following commands are accepted by the client: (or files commands) (setq use-current-frame t)) - (setq frame - (cond - ((and use-current-frame - (or (eq use-current-frame 'always) - ;; We can't use the Emacs daemon's - ;; terminal frame. - (not (and (daemonp) - (null (cdr (frame-list))) - (eq (selected-frame) - terminal-frame))))) - (setq tty-name nil tty-type nil) - (if display (server-select-display display))) - ((or (and (eq system-type 'windows-nt) - (daemonp) - (setq display "w32")) - (eq tty-name 'window-system)) - (server-create-window-system-frame display nowait proc - parent-id - frame-parameters)) - ;; When resuming on a tty, tty-name is nil. - (tty-name - (server-create-tty-frame tty-name tty-type proc)))) + (setq create-frame-func + (lambda () + (cond + ((and use-current-frame + (or (eq use-current-frame 'always) + ;; We can't use the Emacs daemon's + ;; terminal frame. + (not (and (daemonp) + (null (cdr (frame-list))) + (eq (selected-frame) + terminal-frame))))) + (setq tty-name nil tty-type nil) + (if display (server-select-display display))) + ((or (and (eq system-type 'windows-nt) + (daemonp) + (setq display "w32")) + (eq tty-name 'window-system)) + (server-create-window-system-frame display nowait proc + parent-id + frame-parameters)) + ;; When resuming on a tty, tty-name is nil. + (tty-name + (server-create-tty-frame tty-name tty-type proc))))) (process-put proc 'continuation @@ -1277,7 +1279,7 @@ The following commands are accepted by the client: (if (and dir (file-directory-p dir)) dir default-directory))) (server-execute proc files nowait commands - dontkill frame tty-name))))) + dontkill create-frame-func tty-name))))) (when (or frame files) (server-goto-toplevel proc)) @@ -1286,7 +1288,7 @@ The following commands are accepted by the client: ;; condition-case (error (server-return-error proc err)))) -(defun server-execute (proc files nowait commands dontkill frame tty-name) +(defun server-execute (proc files nowait commands dontkill create-frame-func tty-name) ;; This is run from timers and process-filters, i.e. "asynchronously". ;; But w.r.t the user, this is not really asynchronous since the timer ;; is run after 0s and the process-filter is run in response to the @@ -1296,21 +1298,29 @@ The following commands are accepted by the client: ;; including code that needs to wait. (with-local-quit (condition-case err - (let ((buffers (server-visit-files files proc nowait))) - (mapc 'funcall (nreverse commands)) + (let* ((buffers (server-visit-files files proc nowait)) + ;; If we were told only to open a new client, obey + ;; `initial-buffer-choice' if it specifies a file + ;; or a function. + (initial-buffer (unless (or files commands) + (let ((buf + (cond ((stringp initial-buffer-choice) + (find-file-noselect initial-buffer-choice)) + ((functionp initial-buffer-choice) + (funcall initial-buffer-choice))))) + (if (buffer-live-p buf) buf (get-buffer-create "*scratch*"))))) + ;; Set current buffer so that newly created tty frames + ;; show the correct buffer initially. + (frame (with-current-buffer (or (car buffers) + initial-buffer + (current-buffer)) + (prog1 + (funcall create-frame-func) + ;; Switch to initial buffer in case the frame was reused. + (when initial-buffer + (switch-to-buffer initial-buffer 'norecord)))))) - ;; If we were told only to open a new client, obey - ;; `initial-buffer-choice' if it specifies a file - ;; or a function. - (unless (or files commands) - (let ((buf - (cond ((stringp initial-buffer-choice) - (find-file-noselect initial-buffer-choice)) - ((functionp initial-buffer-choice) - (funcall initial-buffer-choice))))) - (switch-to-buffer - (if (buffer-live-p buf) buf (get-buffer-create "*scratch*")) - 'norecord))) + (mapc 'funcall (nreverse commands)) ;; Delete the client if necessary. (cond commit 9f5d8da5cce9ec20d9272df60b10efd8a09b94a9 Author: Eli Zaretskii Date: Fri Feb 16 16:30:02 2018 +0200 ; * lisp/textmodes/flyspell.el (flyspell-auto-correct-word): Fix last change. diff --git a/lisp/textmodes/flyspell.el b/lisp/textmodes/flyspell.el index 0d19dbe140..353d4352f6 100644 --- a/lisp/textmodes/flyspell.el +++ b/lisp/textmodes/flyspell.el @@ -1917,9 +1917,10 @@ before point that's highlighted as misspelled." ;;*---------------------------------------------------------------------*/ (defun flyspell-auto-correct-word () "Correct the current word. -This command proposes various successive corrections for the current word. -If invoked repeatedly with point on a word, it cycles through the -possible corrections." +This command proposes various successive corrections for the +current word. If invoked repeatedly on the same position, it +cycles through the possible corrections of the word at or near +that position." (interactive) ;; If we are not in the construct where flyspell should be active, ;; invoke the original binding of M-TAB, if that was recorded. commit f73905af2dc4ae51195b5cad2562a2c523a3ad39 Author: Eli Zaretskii Date: Fri Feb 16 16:23:43 2018 +0200 Fix the doc string of flyspell-auto-correct-word * lisp/textmodes/flyspell.el (flyspell-auto-correct-word): Doc fix. (Bug#30462) diff --git a/lisp/textmodes/flyspell.el b/lisp/textmodes/flyspell.el index 1d7dc9927e..0d19dbe140 100644 --- a/lisp/textmodes/flyspell.el +++ b/lisp/textmodes/flyspell.el @@ -1917,7 +1917,9 @@ before point that's highlighted as misspelled." ;;*---------------------------------------------------------------------*/ (defun flyspell-auto-correct-word () "Correct the current word. -This command proposes various successive corrections for the current word." +This command proposes various successive corrections for the current word. +If invoked repeatedly with point on a word, it cycles through the +possible corrections." (interactive) ;; If we are not in the construct where flyspell should be active, ;; invoke the original binding of M-TAB, if that was recorded. commit e9c7ddc64b676cfd58a2bce301b1014d2f34f254 Author: Eli Zaretskii Date: Fri Feb 16 12:46:32 2018 +0200 Improve the MS-Windows appendix of the Emacs manual * doc/emacs/msdos.texi (Windows Startup): Describe the pinned shortcuts for starting Emacs. (Text and Binary): Minor wording changes. (Windows Files): Mention 'read-file-name-completion-ignore-case'. (ls in Lisp): Update the list of supported 'ls' switches. Document 'ls-lisp-use-string-collate' and 'ls-lisp-UCA-like-collation'. (Windows HOME): Mention warnings displayed at startup when deprecated locations of HOME and/or deprecated names for init files are used. (Windows Keyboard): Mention delete-selection-mode. diff --git a/doc/emacs/msdos.texi b/doc/emacs/msdos.texi index 27f9667e38..2790d56e01 100644 --- a/doc/emacs/msdos.texi +++ b/doc/emacs/msdos.texi @@ -68,6 +68,20 @@ directory specified by the shortcut. To control where that is, right-click on the shortcut, select ``Properties'', and in the ``Shortcut'' tab modify the ``Start in'' field to your liking. +@item +@cindex pinning Emacs to Windows task bar +From a task-bar shortcut icon, by clicking once the left mouse button. +Windows versions since Vista allow you to create such shortcuts by +@dfn{pinning} the icon of a running program that appears in the task +bar. You can do that with Emacs, but afterwards you will have to +change the properties of the pinned shortcut to run +@file{runemacs.exe}, @emph{not} of @file{emacs.exe}. You can also pin +Emacs to the task bar by clicking the right mouse button on its icon +in the Start menu, then selecting @samp{Pin to taskbar}. Once again, +be sure to specify @file{runemacs.exe} as the program to run. You can +control where Emacs starts by setting the ``Start in'' field of the +shortcut's Properties. + @item From the Command Prompt window, by typing @kbd{emacs @key{RET}} at the prompt. The Command Prompt window where you did that will not be @@ -80,6 +94,12 @@ the prompt. The Command Prompt window where you did that will be immediately available for invoking other commands. In this case, Emacs will start in the current directory of the Windows shell. +@item +From the Windows @code{Run} dialog (normally reached by clicking the +@code{Start} button). Typing @kbd{runemacs @key{RET}} into the dialog +will start Emacs in the parent directory of the Windows equivalent of +your user's @code{HOME} directory, see @ref{Windows HOME}. + @item @cindex invoking Emacs from Windows Explorer @pindex emacsclient.exe @@ -204,8 +224,8 @@ designates directory @file{\foo} on drive Z as an untranslated file system. Most often you would use @code{add-untranslated-filesystem} in your -@file{.emacs} file, or in @file{site-start.el} so that all the users at -your site get the benefit of it. +@file{.emacs} or @file{init.el} init file, or in @file{site-start.el} +so that all the users at your site get the benefit of it. @findex remove-untranslated-filesystem To countermand the effect of @code{add-untranslated-filesystem}, use @@ -215,8 +235,8 @@ previously with @code{add-untranslated-filesystem}. Designating a file system as untranslated does not affect character set conversion, only end-of-line conversion. Essentially, it directs -Emacs to create new files with the Unix-style convention of using -newline at the end of a line. @xref{Coding Systems}. +Emacs to default to creating new files with the Unix-style convention +of using newline at the end of a line. @xref{Coding Systems}. @node Windows Files @section File Names on MS-Windows @@ -229,7 +249,9 @@ backslash, and also knows about drive letters in file names. @cindex file-name completion, on MS-Windows On MS-DOS/MS-Windows, file names are case-insensitive, so Emacs by -default ignores letter-case in file names during completion. +default ignores letter-case in file names during completion. To this +end, the default value of @code{read-file-name-completion-ignore-case} +is non-@code{nil} on MS-DOS/MS-Windows. @xref{Completion Options}. @vindex w32-get-true-file-attributes The variable @code{w32-get-true-file-attributes} controls whether @@ -311,9 +333,9 @@ it doesn't support all of them. Here's the list of the switches it does support: @option{-A}, @option{-a}, @option{-B}, @option{-C}, @option{-c}, @option{-G}, @option{-g}, @option{-h}, @option{-i}, @option{-n}, @option{-R}, @option{-r}, @option{-S}, @option{-s}, @option{-t}, @option{-U}, -@option{-u}, and @option{-X}. The @option{-F} switch is partially -supported (it appends the character that classifies the file, but does -not prevent symlink following). +@option{-u}, @option{v}, and @option{-X}. The @option{-F} switch is +partially supported (it appends the character that classifies the +file, but does not prevent symlink following). @vindex ls-lisp-use-insert-directory-program On MS-Windows and MS-DOS, @file{ls-lisp.el} is preloaded when Emacs @@ -323,6 +345,26 @@ platforms. If you have a ported @code{ls}, setting will revert to using an external program named by the variable @code{insert-directory-program}. +@cindex Dired sorting order, on MS-Windows/MS-DOS + The order in which @file{ls-lisp.el} sorts files depends on several +customizable options described below. + +@vindex ls-lisp-use-string-collate + The default sorting order follows locale-specific rules derived from +your system locale. You can make the order locale-independent by +customizing @code{ls-lisp-use-string-collate} to a @code{nil} value. + +@cindex Unicode Collation Algorithm (UCA), and @file{ls-lisp.el} +@vindex ls-lisp-UCA-like-collation + On GNU and Unix systems, when the locale's encoding is UTF-8, the +collation order follows the Unicode Collation Algorithm +(@acronym{UCA}). To have a similar effect on MS-Windows, the variable +@code{ls-lisp-UCA-like-collation} should have a non-@code{nil} value +(this is the default). The resulting sorting order ignores +punctuation, symbol characters, and whitespace characters, so +@file{.foobar}, @file{foobar} and @w{@file{foo bar}} will appear +together rather than far apart. + @vindex ls-lisp-ignore-case By default, @file{ls-lisp.el} uses a case-sensitive sort order for the directory listing it produces; this is so the listing looks the @@ -371,10 +413,10 @@ Emulate macOS@. Sets @code{ls-lisp-ignore-case} to @code{t}, and @item MS-Windows Emulate MS-Windows. Sets @code{ls-lisp-ignore-case} and @code{ls-lisp-dirs-first} to @code{t}, and @code{ls-lisp-verbosity} to -@code{(links)} on Windows NT/2K/XP/2K3 and to @code{nil} on Windows 9X@. -Note that the default emulation is @emph{not} @code{MS-Windows}, even -on Windows, since many users of Emacs on those platforms prefer the -@sc{gnu} defaults. +@code{nil} on Windows 9X and to @code{t} on modern versions of +Windows. Note that the default emulation is @emph{not} +@code{MS-Windows}, even on Windows, since many users of Emacs on those +platforms prefer the @sc{gnu} defaults. @end table @noindent @@ -421,6 +463,8 @@ formats file time stamps according to what @code{ls-lisp-format-time-list} specifies. The @samp{%}-sequences in @code{ls-lisp-format-time-list} produce locale-dependent month and day names, which might cause misalignment of columns in Dired display. +The default value of @code{ls-lisp-use-localized-time-format} is +@code{nil}. @end ifnottex @node Windows HOME @@ -453,7 +497,8 @@ default @code{HOME} location, and will not look in the application data directory, even if it exists. Note that only @file{.emacs} is looked for in @file{C:\}; the older name @file{_emacs} (see below) is not. This use of @file{C:\.emacs} to define @code{HOME} is -deprecated. +deprecated; Emacs will display a warning about its use during +startup. Whatever the final place is, Emacs sets the internal value of the @env{HOME} environment variable to point to it, and it will use that @@ -467,15 +512,15 @@ first line. Likewise, to visit your init file, type @kbd{C-x C-f ~/.emacs @key{RET}} (assuming the file's name is @file{.emacs}). @cindex init file @file{.emacs} on MS-Windows - The home directory is where your init file is stored. It can have -any name mentioned in @ref{Init File}. + Your init file can have any name mentioned in @ref{Init File}. @cindex @file{_emacs} init file, MS-Windows Because MS-DOS does not allow file names with leading dots, and older Windows systems made it hard to create files with such names, the Windows port of Emacs supports an init file name @file{_emacs}, if such a file exists in the home directory and @file{.emacs} does not. -This name is considered obsolete. +This name is considered obsolete, so Emacs will display a warning if +it is used. @node Windows Keyboard @section Keyboard Usage on MS-Windows @@ -491,7 +536,9 @@ Emacs key bindings. (These Emacs key bindings were established years before Microsoft was founded.) Examples of conflicts include @kbd{C-c}, @kbd{C-x}, @kbd{C-z}, @kbd{C-a}, and @kbd{W-@key{SPC}}. You can redefine some of them with meanings more like the MS-Windows -meanings by enabling CUA Mode (@pxref{CUA Bindings}). +meanings by enabling CUA Mode (@pxref{CUA Bindings}). Another +optional feature which will make Emacs behave like other Windows +applications is Delete Selection mode (@pxref{Using Region}). @iftex @inforef{Windows Keyboard, , emacs}, for information about additional @@ -690,16 +737,14 @@ is non-@code{nil}, the roles of these two buttons are reversed. @cindex subprocesses on MS-Windows @cindex DOS applications, running from Emacs - Emacs compiled as a native Windows application (as opposed to the DOS -version) includes full support for asynchronous subprocesses. -In the Windows version, synchronous and asynchronous subprocesses work -fine on both -Windows 9X/ME and Windows NT/2K/XP/Vista/7/8/10 as long as you run -only 32-bit or 64-bit Windows -applications. However, when you run a DOS application in a subprocess, -you may encounter problems or be unable to run the application at all; -and if you run two DOS applications at the same time in two -subprocesses, you may have to reboot your system. + Emacs compiled as a native Windows application (as opposed to the +DOS version) includes full support for asynchronous subprocesses. In +the Windows version, synchronous and asynchronous subprocesses work +fine on all versions of MS-Windows, as long as you run only 32-bit or +64-bit Windows applications. However, when you run a DOS application +in a subprocess, you may encounter problems or be unable to run the +application at all; and if you run two DOS applications at the same +time in two subprocesses, you may have to reboot your system. Since the standard command interpreter (and most command line utilities) on Windows 9X are DOS applications, these problems are significant when @@ -724,13 +769,13 @@ first one finishes, even if either or both of them are asynchronous. @cindex kill DOS application If you can go to the first subprocess, and tell it to exit, the second -subprocess should continue normally. However, if the second subprocess -is synchronous, Emacs itself will be hung until the first subprocess -finishes. If it will not finish without user input, then you have no -choice but to reboot if you are running on Windows 9X@. If you are -running on Windows NT/2K/XP, you can use a process viewer application to kill -the appropriate instance of NTVDM instead (this will terminate both DOS -subprocesses). +subprocess should continue normally. However, if the second +subprocess is synchronous, Emacs itself will be hung until the first +subprocess finishes. If it will not finish without user input, then +you have no choice but to reboot if you are running on Windows 9X@. +If you are running on Windows NT and later, you can use a process +viewer application to kill the appropriate instance of NTVDM instead +(this will terminate both DOS subprocesses). If you have to reboot Windows 9X in this situation, do not use the @code{Shutdown} command on the @code{Start} menu; that usually hangs the commit 6ddb4bd39ac0629e4e06221a41120aee7c18f548 Author: Eli Zaretskii Date: Fri Feb 16 11:30:29 2018 +0200 Fix 'vc-git--program-version' * lisp/vc/vc-git.el (vc-git--program-version): Fix the function to work with Git for Windows. diff --git a/lisp/vc/vc-git.el b/lisp/vc/vc-git.el index 40aa0b2601..7ebb72f270 100644 --- a/lisp/vc/vc-git.el +++ b/lisp/vc/vc-git.el @@ -239,8 +239,11 @@ Should be consistent with the Git config value i18n.logOutputEncoding." (vc-git--run-command-string nil "version"))) (setq vc-git--program-version (if (and version-string - (string-match "git version \\([0-9.]+\\)$" - version-string)) + ;; Git for Windows appends ".windows.N" to the + ;; numerical version reported by Git. + (string-match + "git version \\([0-9.]+\\)\\(\.windows.[0-9]+\\)$" + version-string)) (match-string 1 version-string) "0"))))) commit 63c93f7ecd469cd8267f2c7c87530341a157b144 Author: Eli Zaretskii Date: Fri Feb 16 11:12:50 2018 +0200 Fix typos and wording in the Emacs manual * doc/emacs/dired.texi (Marks vs Flags, Hiding Subdirectories): * doc/emacs/maintaining.texi (Tag Syntax): * doc/emacs/building.texi (Commands of GUD, Threads Buffer) (Lisp Libraries): * doc/emacs/windows.texi (Temporary Displays): Fix typos. * doc/emacs/files.texi (Backup Copying): Fix wording. Reported by Stefan Kamphausen in emacs-manual-bugs@gnu.org. diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi index 878d2f53d5..b6b664ddb3 100644 --- a/doc/emacs/building.texi +++ b/doc/emacs/building.texi @@ -649,7 +649,7 @@ Set a breakpoint on the source line that point is on. buffer, sets a debugger breakpoint on the current source line. This command is available only after starting GUD@. If you call it in a buffer that is not associated with any debugger subprocess, it signals -a error. +an error. @kindex C-x C-a @r{(GUD)} The following commands are available both in the GUD interaction @@ -1096,9 +1096,9 @@ display the corresponding buffer in a new frame. When you create a buffer showing information about some specific thread, it becomes bound to that thread and keeps showing actual information while you debug your program. The mode indicator for each -GDB buffer shows the number of thread it is showing information about. -The thread number is also included in the buffer name of bound -buffers. +GDB buffer shows the number of the thread whose information that +buffer displays. The thread number is also included in the name of +each bound buffer. Further commands are available in the GDB Threads buffer which depend on the mode of GDB that is used for controlling execution of @@ -1449,7 +1449,7 @@ buffer). To disable this feature, change the variable @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 versions of Emacs---they can cause +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. diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi index 6b6ab3a039..94a10feab4 100644 --- a/doc/emacs/dired.texi +++ b/doc/emacs/dired.texi @@ -579,9 +579,10 @@ might be inconsistent with the file on disk if its contents have changed since it was last visited. If you don't want this, you may wish to revert the files you have visited in your buffers, or to turn on the @code{auto-revert} mode in those buffers, before invoking this -command. @xref{Reverting}. If you prefer that this command always revisit -the file, without having to revert the file or enable @code{auto-revert} -mode, you might want to set @code{dired-always-read-filesystem} to non-@code{nil}. +command. @xref{Reverting}. If you prefer that this command always +revisits the file, without having to revert the file or enable +@code{auto-revert} mode, you might want to set +@code{dired-always-read-filesystem} to non-@code{nil}. @item C-/ @itemx C-x u @@ -1173,7 +1174,7 @@ without having to remove the Dired marks on files in those subdirectories. @xref{Subdirectories in Dired}, for how to insert a subdirectory -listing, and @pxref{Dired Updating} for how delete it. +listing, and see @ref{Dired Updating}, for how to delete it. @node Dired Updating @section Updating the Dired Buffer diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index 45db6d88b4..42cc4e767d 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -694,11 +694,12 @@ Otherwise, renaming is the default choice. When a file is managed with a version control system (@pxref{Version Control}), Emacs does not normally make backups in the usual way for -that file. But check-in and check-out are similar in some ways to -making backups. One unfortunate similarity is that these operations -typically break hard links, disconnecting the file name you visited from -any alternate names for the same file. This has nothing to do with -Emacs---the version control system does it. +that file. But @dfn{committing} (a.k.a.@: @dfn{checking in}, +@pxref{VCS Concepts}) new versions of files is similar in some ways +to making backups. One unfortunate similarity is that these +operations typically break hard links, disconnecting the file name you +visited from any alternate names for the same file. This has nothing +to do with Emacs---the version control system does it. @node Customize Save @subsection Customizing Saving of Files diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index 127c27c037..1234db84b2 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -2203,7 +2203,7 @@ In Ada, the same name can be used for different kinds of entity (e.g., for a procedure and for a function). Also, for things like packages, procedures and functions, there is the spec (i.e., the interface) and the body (i.e., the implementation). To make it -easier to pick the definition you want, Ada tag name have suffixes +easier to pick the definition you want, Ada tag names have suffixes indicating the type of entity: @table @samp diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi index 945b7cb941..9f3b1b6a07 100644 --- a/doc/emacs/windows.texi +++ b/doc/emacs/windows.texi @@ -465,7 +465,7 @@ bottom of the selected frame, regardless of the number of windows already shown on that frame. If you prefer Emacs to display a temporary buffer in a different -fashion, we recommend to customize the variable +fashion, we recommend customizing the variable @code{display-buffer-alist} (@pxref{Choosing Window,,Choosing a Window for Display, elisp, The Emacs Lisp Reference Manual}). For example, to display @file{*Completions*} by splitting a window as described in commit 42f15b05ba4e8d5707a16d80db5e57d152d18f5b Author: Michael Albinus Date: Fri Feb 16 09:53:30 2018 +0100 * doc/emacs/programs.texi (Semantic): Order programming languages. diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi index 2bd6101782..4d515f29b6 100644 --- a/doc/emacs/programs.texi +++ b/doc/emacs/programs.texi @@ -1463,7 +1463,7 @@ the menu item named @samp{Source Code Parsers (Semantic)} in the When Semantic mode is enabled, Emacs automatically attempts to parse each file you visit. Currently, Semantic understands C, C++, -Javascript, Java, HTML, Make, Python, Scheme, SRecode, and Texinfo. +HTML, Java, Javascript, Make, Python, Scheme, SRecode, and Texinfo. Within each parsed buffer, the following commands are available: @table @kbd commit b46be29424cc84982cf8b0cad8f3fdbc98e1c8e0 Author: Eli Zaretskii Date: Thu Feb 15 20:38:13 2018 +0200 More improvements for the Emacs manual * doc/emacs/programs.texi (Basic Indent, Comment Commands): Fix typos. * doc/emacs/text.texi (TeX Print, HTML Mode, Enriched Faces): Fix typos. * doc/emacs/help.texi (Help Files): Improve @uref usage. Reported by Stefan Kamphausen in emacs-manual-bugs@gnu.org. * doc/emacs/fortran-xtra.texi (ForIndent Commands): Fix a typo. (ForIndent Commands, Fortran Columns): Add empty lines between @items in a @table. (ForIndent Cont, ForIndent Num, Fortran Columns): Mention 'column-number-indicator-zero-based'. (ForIndent Vars): Fix a typo. (Fortran Comments): Fix punctuation. (ForIndent Cont, Fortran Autofill): Fix markup of keyboard input. * doc/emacs/programs.texi (Comments): Fix a typo. (Comment Commands): More accurate description of the commands. (Options for Comments): Don't mention "hook". (Man Page): Prefer "M-x man" if available. (Hideshow): Fix the command key sequence. (Semantic): Update supported languages. (Semantic, Hungry Delete, Other C Commands): Fix markup of commands. (Misc for Programs): Fix a typo. (Electric C, Hungry Delete): More accurate description of mode-line lighters of CC submodes. (Asm Mode): Add empty lines between @items in a @table. * doc/emacs/programs.texi (Program Modes): Add a few more modes. Reported by Michael Albinus in emacs-manual-bugs@gnu.org. * doc/emacs/msdos.texi (Windows Misc): A minor rewording. Suggested by Isaac Carter in emacs-manual-bugs@gnu.org. diff --git a/doc/emacs/fortran-xtra.texi b/doc/emacs/fortran-xtra.texi index 98ff8258db..859c613243 100644 --- a/doc/emacs/fortran-xtra.texi +++ b/doc/emacs/fortran-xtra.texi @@ -158,11 +158,14 @@ the required columns. @item C-M-j Break the current line at point and set up a continuation line (@code{fortran-split-line}). + @item M-^ Join this line to the previous line (@code{fortran-join-line}). + @item C-M-q Indent all the lines of the subprogram that point is in (@code{fortran-indent-subprogram}). + @item M-q Fill a comment block or statement (using @code{fortran-fill-paragraph} or @code{fortran-fill-statement}). @@ -185,7 +188,7 @@ lines. @kindex M-^ @r{(Fortran mode)} @kindex C-c C-d @r{(Fortran mode)} @findex fortran-join-line - @kbd{M-^} or @kbd{C-c C-d} runs the command @code{fortran-join-line}, + @kbd{M-^} or @kbd{C-c C-d} run the command @code{fortran-join-line}, which joins a continuation line back to the previous line, roughly as the inverse of @code{fortran-split-line}. The point must be on a continuation line when this command is invoked. @@ -203,7 +206,9 @@ point is in. This removes any excess statement continuations. If the first non-space character on a line is in column 5, then that line is a continuation of the previous line. We call this @dfn{fixed form}. (In GNU Emacs we always count columns from 0; but note that -the Fortran standard counts from 1.) The variable +the Fortran standard counts from 1. You can customize the variable +@code{column-number-indicator-zero-based} to make the column display +Fortran-like; @pxref{Optional Mode Line}.) The variable @code{fortran-continuation-string} specifies what character to put in column 5. A line that starts with a tab character followed by any digit except @samp{0} is also a continuation line. We call this style of @@ -229,10 +234,10 @@ accordingly. If the text on a line starts with the Fortran continuation marker @samp{$}, or if it begins with any non-whitespace character in column 5, Fortran mode treats it as a continuation line. When you indent a -continuation line with @key{TAB}, it converts the line to the current -continuation style. When you split a Fortran statement with -@kbd{C-M-j}, the continuation marker on the newline is created according -to the continuation style. +continuation line with @kbd{@key{TAB}}, it converts the line to the +current continuation style. When you split a Fortran statement with +@kbd{C-M-j}, the continuation marker on the newline is created +according to the continuation style. The setting of continuation style affects several other aspects of editing in Fortran mode. In fixed form mode, the minimum column @@ -247,7 +252,9 @@ column 8 must consist of one tab character. If a number is the first non-whitespace in the line, Fortran indentation assumes it is a line number and moves it to columns 0 -through 4. (Columns always count from 0 in Emacs.) +through 4. (Columns always count from 0 in Emacs, but setting +@code{column-number-indicator-zero-based} to @code{nil} can change +that, @pxref{Optional Mode Line}.) @vindex fortran-line-number-indent Line numbers of four digits or less are normally indented one space. @@ -320,7 +327,7 @@ Extra indentation within each level of @samp{structure}, @samp{union}, Extra indentation for bodies of continuation lines (default 5). @item fortran-check-all-num-for-matching-do -In Fortran 77, a numbered @samp{do} statement is ended by any statement +In Fortran 77, a numbered @samp{do} statement is terminated by any statement with a matching line number. It is common (but not compulsory) to use a @samp{continue} statement for this purpose. If this variable has a non-@code{nil} value, indenting any numbered statement must check for a @@ -330,7 +337,7 @@ then you can speed up indentation by setting this variable to @code{nil} (the default). @item fortran-blink-matching-if -If this is @code{t}, indenting an @samp{endif} (or @samp{enddo} +If this is @code{t}, indenting an @samp{endif} (or @samp{enddo}) statement moves the cursor momentarily to the matching @samp{if} (or @samp{do}) statement to show where it is. The default is @code{nil}. @@ -386,7 +393,7 @@ Fortran mode as in other modes. When a new comment must be inserted, if the current line is blank, a full-line comment is inserted. On a non-blank line, a nonstandard @samp{!} -comment is inserted if you have said you want to use them. Otherwise a +comment is inserted if you have said you want to use them. Otherwise, a full-line comment is inserted on a new line before the current line. Nonstandard @samp{!} comments are aligned like comments in other @@ -434,7 +441,7 @@ distinctive font-locking. The normal Emacs comment command @kbd{C-x ;} (@code{comment-set-column}) has not been redefined. If you use @samp{!} comments, this command -can be used with them. Otherwise it is useless in Fortran mode. +can be used with them. Otherwise, it is useless in Fortran mode. @kindex C-c ; @r{(Fortran mode)} @findex fortran-comment-region @@ -457,9 +464,9 @@ minor mode that automatically splits statements as you insert them when they become too wide. Splitting a statement involves making continuation lines using @code{fortran-continuation-string} (@pxref{ForIndent Cont}). This splitting happens when you type -@key{SPC}, @key{RET}, or @key{TAB}, and also in the Fortran -indentation commands. You activate Auto Fill in Fortran mode in the -normal way. +@kbd{@key{SPC}}, @kbd{@key{RET}}, or @kbd{@key{TAB}}, and also in the +Fortran indentation commands. You activate Auto Fill in Fortran mode +in the normal way. @iftex @xref{Auto Fill,,, emacs, the Emacs Manual}. @end iftex @@ -501,15 +508,18 @@ will confuse font-lock.) @item C-c C-r Display a column ruler momentarily above the current line (@code{fortran-column-ruler}). + @item C-c C-w Split the current window horizontally temporarily so that it is @code{fortran-line-length} columns wide (@code{fortran-window-create-momentarily}). This may help you avoid making lines longer than the limit imposed by your Fortran compiler. + @item C-u C-c C-w Split the current window horizontally so that it is @code{fortran-line-length} columns wide (@code{fortran-window-create}). You can then continue editing. + @item M-x fortran-strip-sequence-nos Delete all text in column @code{fortran-line-length} and beyond. @end table @@ -523,7 +533,9 @@ Fortran programs. Square brackets show the limits of the columns for line numbers, and curly brackets show the limits of the columns for the statement body. Column numbers appear above them. - Note that the column numbers count from zero, as always in GNU Emacs. + Note that the column numbers count from zero, as always in GNU Emacs +(but customizing @code{column-number-indicator-zero-based} can change +column display to match that of Fortran; @pxref{Optional Mode Line}). As a result, the numbers may be one less than those you are familiar with; but the positions they indicate in the line are standard for Fortran. diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi index 2ed264258e..6c093f13d0 100644 --- a/doc/emacs/help.texi +++ b/doc/emacs/help.texi @@ -642,7 +642,7 @@ Display information about where to get external packages @item C-h C-f Display the Emacs frequently-answered-questions list (@code{view-emacs-FAQ}). @item C-h g -Visit a @uref{https://www.gnu.org} page with information about the GNU +Visit the @uref{https://www.gnu.org, page} with information about the GNU Project (@code{describe-gnu-project}). @item C-h C-m Display information about ordering printed copies of Emacs manuals diff --git a/doc/emacs/msdos.texi b/doc/emacs/msdos.texi index dd368adb54..27f9667e38 100644 --- a/doc/emacs/msdos.texi +++ b/doc/emacs/msdos.texi @@ -1033,7 +1033,8 @@ the system default antialiasing. @node Windows Misc @section Miscellaneous Windows-specific features - This section describes miscellaneous Windows-specific features. + This section describes Windows-specific features that don't fit +anywhere else. @vindex w32-use-visible-system-caret @cindex screen reader software, MS-Windows diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi index 3944ce4607..2bd6101782 100644 --- a/doc/emacs/programs.texi +++ b/doc/emacs/programs.texi @@ -86,14 +86,14 @@ mode for the C programming language is @code{c-mode}. @cindex Awk mode Emacs has programming language modes for Lisp, Scheme, the Scheme-based DSSSL expression language, Ada, ASM, AWK, C, C++, -Fortran, Icon, IDL (CORBA), IDLWAVE, Java, Javascript, Metafont -(@TeX{}'s companion for font creation), Modula2, Object Pascal, -Objective-C, Octave, Pascal, Perl, Pike, PostScript, Prolog, Python, -Ruby, Simula, SQL, Tcl, Verilog, and VHDL@. An alternative mode for -Perl is called CPerl mode. Modes are also available for the scripting -languages of the common GNU and Unix shells, and MS-DOS/MS-Windows -@samp{BAT} files, and for makefiles, DNS master files, and various -sorts of configuration files. +Fortran, Icon, IDL (CORBA), IDLWAVE, Java, Javascript, M4, Makefiles, +Metafont (@TeX{}'s companion for font creation), Modula2, Object +Pascal, Objective-C, Octave, Pascal, Perl, Pike, PostScript, Prolog, +Python, Ruby, Simula, SQL, Tcl, Verilog, and VHDL@. An alternative +mode for Perl is called CPerl mode. Modes are also available for the +scripting languages of the common GNU and Unix shells, and +MS-DOS/MS-Windows @samp{BAT} files, and for makefiles, DNS master +files, and various sorts of configuration files. Ideally, Emacs should have a major mode for each programming language that you might want to edit. If it doesn't have a mode for @@ -403,7 +403,7 @@ manually give one of these lines a nonstandard indentation (e.g., for aesthetic purposes), the lines below will follow it. The indentation commands for most programming language modes assume -that a open-parenthesis, open-brace or other opening delimiter at the +that an open-parenthesis, open-brace or other opening delimiter at the left margin is the start of a function. If the code you are editing violates this assumption---even if the delimiters occur in strings or comments---you must set @code{open-paren-in-column-0-is-defun-start} @@ -927,7 +927,7 @@ also do spell checking on comments with Flyspell Prog mode comments. For example, in Lisp code, comments starting with two semicolons are indented as if they were lines of code, while those starting with three semicolons are supposed to be aligned to the left -margin and are often used for sectioning purposes. Emacs understand +margin and are often used for sectioning purposes. Emacs understands these conventions; for instance, typing @kbd{@key{TAB}} on a comment line will indent the comment to the appropriate position. @@ -958,7 +958,9 @@ line will indent the comment to the appropriate position. Insert or realign comment on current line; if the region is active, comment or uncomment the region instead (@code{comment-dwim}). @item @kbd{C-x C-;} -Comment or uncomment the current line (@code{comment-line}). +Comment or uncomment the current line (@code{comment-line}). If the +region is active, comment or uncomment the lines in the region +instead. @item @kbd{C-u M-;} Kill comment on current line (@code{comment-kill}). @item @kbd{C-x ;} @@ -1045,8 +1047,7 @@ region, even if the mark is inactive. In C mode and related modes, this command is bound to @kbd{C-c C-c}. The command @kbd{M-x uncomment-region} uncomments each line in the region; a numeric prefix argument specifies the number of comment delimiters to remove -(negative arguments specify the number of comment to delimiters to -add). +(negative arguments specify the number of comment delimiters to add). For C-like modes, you can configure the exact effect of @kbd{M-;} by setting the variables @code{c-indent-comment-alist} and @@ -1151,8 +1152,8 @@ comment or for aligning an existing comment. It is set differently by various major modes. The function is called with no arguments, but with point at the beginning of the comment, or at the end of a line if a new comment is to be inserted. It should return the column in which the -comment ought to start. For example, the default hook function bases -its decision on how many comment characters begin an existing comment. +comment ought to start. For example, the default function bases its +decision on how many comment characters begin an existing comment. Emacs also tries to align comments on adjacent lines. To override this, the function may return a cons of two (possibly equal) integers @@ -1183,10 +1184,10 @@ buffer at point. For example, in C mode this looks for the symbol in the C Library Manual. The command only works if the appropriate manual's Info files are installed. - The major mode determines where to look for documentation for the -symbol---which Info files to look in, and which indices to search. -You can also use @kbd{M-x info-lookup-file} to look for documentation -for a file name. + Emacs determines where to look for documentation for the +symbol---which Info files to look in, and which indices to +search---based on the major mode. You can also use @kbd{M-x +info-lookup-file} to look for documentation for a file name. If you use @kbd{C-h S} in a major mode that does not support it, it asks you to specify the symbol help mode. You should enter @@ -1256,6 +1257,10 @@ several manual pages by the same name exist in different sections, it pops up a window with possible candidates asking you to choose one of them. + Note that @kbd{M-x woman} doesn't yet support the latest features of +modern man pages, so we recommend using @kbd{M-x man} if that is +available on your system. + For more information about setting up and using @kbd{M-x woman}, see @ifinfo @ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The @@ -1336,7 +1341,7 @@ Hide all top-level blocks (@code{hs-hide-all}). @item C-c @@ C-M-s @itemx C-c @@ C-a Show all blocks in the buffer (@code{hs-show-all}). -@item C-c @@ C-l +@item C-u @var{n} C-c @@ C-l Hide all blocks @var{n} levels below this block (@code{hs-hide-level}). @end table @@ -1458,8 +1463,8 @@ the menu item named @samp{Source Code Parsers (Semantic)} in the When Semantic mode is enabled, Emacs automatically attempts to parse each file you visit. Currently, Semantic understands C, C++, -Scheme, Javascript, Java, HTML, and Make. Within each parsed buffer, -the following commands are available: +Javascript, Java, HTML, Make, Python, Scheme, SRecode, and Texinfo. +Within each parsed buffer, the following commands are available: @table @kbd @item C-c , j @@ -1476,10 +1481,10 @@ parsed, and move point there (@code{semantic-complete-jump}). @kindex C-c , SPC Display a list of possible completions for the symbol at point (@code{semantic-complete-analyze-inline}). This also activates a set -of special key bindings for choosing a completion: @key{RET} accepts -the current completion, @kbd{M-n} and @kbd{M-p} cycle through possible -completions, @key{TAB} completes as far as possible and then cycles, -and @kbd{C-g} or any other key aborts completion. +of special key bindings for choosing a completion: @kbd{@key{RET}} +accepts the current completion, @kbd{M-n} and @kbd{M-p} cycle through +possible completions, @kbd{@key{TAB}} completes as far as possible and +then cycles, and @kbd{C-g} or any other key aborts completion. @item C-c , l @kindex C-c , l @@ -1503,7 +1508,7 @@ is idle. programs are useful for that nonetheless. The Emacs commands that operate on words, sentences and paragraphs -are useful for editing code. Most symbols names contain words +are useful for editing code. Most symbol names contain words (@pxref{Words}), while sentences can be found in strings and comments (@pxref{Sentences}). As for paragraphs, they are defined in most programming language modes to begin and end at blank lines @@ -1678,8 +1683,9 @@ electric characters are @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#}, You might find electric indentation inconvenient if you are editing chaotically indented code. If you are new to CC Mode, you might find it disconcerting. You can toggle electric action with the command -@kbd{C-c C-l}; when it is enabled, @samp{/l} appears in the mode line -after the mode name: +@kbd{C-c C-l}; when it is enabled, @samp{/@var{c}l} appears in the +mode line after the mode name (where @var{c}, if present, is @samp{*} +or @samp{/}): @table @kbd @item C-c C-l @@ -1692,8 +1698,8 @@ negative one it disables it. Electric characters insert newlines only when, in addition to the electric state, the @dfn{auto-newline} feature is enabled (indicated -by @samp{/la} in the mode line after the mode name). You can turn -this feature on or off with the command @kbd{C-c C-a}: +by @samp{/@var{c}la} in the mode line after the mode name). You can +turn this feature on or off with the command @kbd{C-c C-a}: @table @kbd @item C-c C-a @@ -1737,10 +1743,11 @@ Delete the entire block of whitespace after point (@code{c-hungry-delete-forward @end table As an alternative to the above commands, you can enable @dfn{hungry -delete mode}. When this feature is enabled (indicated by @samp{/h} in -the mode line after the mode name), a single @key{DEL} deletes all -preceding whitespace, not just one space, and a single @kbd{C-d} -(but @emph{not} plain @key{Delete}) deletes all following whitespace. +delete mode}. When this feature is enabled (indicated by @samp{h} +after a @samp{/} in the mode line after the mode name), a single +@kbd{@key{DEL}} deletes all preceding whitespace, not just one space, +and a single @kbd{C-d} (but @emph{not} plain @kbd{@key{Delete}}) +deletes all following whitespace. @table @kbd @item M-x c-toggle-hungry-state @@ -1763,14 +1770,14 @@ hungry-delete feature is enabled. @findex c-context-line-break This command inserts a line break and indents the new line in a manner appropriate to the context. In normal code, it does the work of -@key{RET} (@code{newline}), in a C preprocessor line it additionally +@kbd{@key{RET}} (@code{newline}), in a C preprocessor line it additionally inserts a @samp{\} at the line break, and within comments it's like @kbd{M-j} (@code{c-indent-new-comment-line}). @code{c-context-line-break} isn't bound to a key by default, but it needs a binding to be useful. The following code will bind it to -@key{RET}. We use @code{c-initialization-hook} here to make sure -the keymap is loaded before we try to change it. +@kbd{@key{RET}}. We use @code{c-initialization-hook} here to make +sure the keymap is loaded before we try to change it. @example (defun my-bind-clb () @@ -1895,11 +1902,14 @@ defines these commands: @item @key{TAB} @code{tab-to-tab-stop}. @c FIXME: Maybe this should be consistent with other programming modes. + @item C-j Insert a newline and then indent using @code{tab-to-tab-stop}. + @item : Insert a colon and then remove the indentation from before the label preceding colon. Then do @code{tab-to-tab-stop}. + @item ; Insert or align a comment. @end table diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi index 45407b2109..e753ab5519 100644 --- a/doc/emacs/text.texi +++ b/doc/emacs/text.texi @@ -1684,7 +1684,7 @@ when you type the corresponding one. @node TeX Print @subsection @TeX{} Printing Commands - You can invoke @TeX{} as an subprocess of Emacs, supplying either + You can invoke @TeX{} as a subprocess of Emacs, supplying either the entire contents of the buffer or just part of it (e.g., one chapter of a larger document). @@ -1736,7 +1736,7 @@ C-p} (@code{tex-print}) to print a hardcopy of the output file. output of @TeX{} also goes in this directory. To run @TeX{} in a different directory, change the variable @code{tex-directory} to the desired directory. If your environment variable @env{TEXINPUTS} -contains relative names, or if your files contains +contains relative names, or if your files contain @samp{\input} commands with relative file names, then @code{tex-directory} @emph{must} be @code{"."} or you will get the wrong results. Otherwise, it is safe to specify some other directory, @@ -2007,7 +2007,7 @@ used as a cheap preview (@code{sgml-tags-invisible}). @findex nxml-mode @cindex XML schema The major mode for editing XML documents is called nXML mode. This -is a powerful major mode that can recognize many existing XML schema +is a powerful major mode that can recognize many existing XML schemas and use them to provide completion of XML elements via @kbd{M-@key{TAB}}, as well as on-the-fly XML validation with error highlighting. To enable nXML mode in an @@ -2280,7 +2280,7 @@ Prompt for a color, and apply it as a background color. @end table @noindent -These command are also available via the Text Properties menu. +These commands are also available via the Text Properties menu. A self-inserting character normally inherits the face properties (and most other text properties) from the preceding character in the commit 874c0edf30308392bdba870e92247d7e4b0e66f4 Author: Eli Zaretskii Date: Wed Feb 14 21:12:49 2018 +0200 Minor wording change in Emacs manual * doc/emacs/killing.texi (Accumulating Text): Fix spelling. Reported by lyr3 in emacs-manual-bugs@gnu.org. diff --git a/doc/emacs/killing.texi b/doc/emacs/killing.texi index 3416db53f4..19aa9077d7 100644 --- a/doc/emacs/killing.texi +++ b/doc/emacs/killing.texi @@ -675,7 +675,7 @@ use to alter a buffer, then point is always at the end. @kbd{M-x prepend-to-buffer} is just like @code{append-to-buffer} except that point in the other buffer is left before the copied text, so -successive prependings add text in reverse order. @kbd{M-x +successive uses of this command add text in reverse order. @kbd{M-x copy-to-buffer} is similar, except that any existing text in the other buffer is deleted, so the buffer is left containing just the text newly copied into it. commit 53511f91473be97c327b484b950cc469564895d2 Author: Eli Zaretskii Date: Wed Feb 14 21:00:59 2018 +0200 Another set of changes for the manual * doc/emacs/programs.texi (Program Indent): Add a cross-reference to elisp's description of 'pp'. (Program Modes): Add a few more programming modes. Add index entries. (Basic Indent, Multi-line Indent, C Indent, Comment Commands) (Manipulating Comments): Fix markup of keyboard commands. * doc/emacs/search.texi (Regexps): Add an example with non-ASCII characters. Suggested by Michael Albinus in emacs-manual-bugs@gnu.org. * doc/lispref/display.texi (Display Tables): Fix the description of the 5th extra slot of the display table. (Bug#13473) * doc/emacs/regs.texi (Registers): Simplify wording. * doc/emacs/custom.texi (Init Non-ASCII): Remove outdated text about perils of encoded keyboard input. diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index e27760b379..2726690f09 100644 --- a/doc/emacs/custom.texi +++ b/doc/emacs/custom.texi @@ -2567,11 +2567,3 @@ instance: @noindent Type @kbd{C-q}, followed by the key you want to bind, to insert @var{char}. - - @strong{Warning:} if you change the keyboard encoding, or change -between multibyte and unibyte mode, or anything that would alter which -code @kbd{C-q} would insert for that character, this key binding may -stop working. It is therefore advisable to use one and only one -coding system, for your init file as well as the files you edit. For -example, don't mix the @samp{latin-1} and @samp{latin-9} coding -systems. diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi index 4289124545..3944ce4607 100644 --- a/doc/emacs/programs.texi +++ b/doc/emacs/programs.texi @@ -73,23 +73,27 @@ mode for the C programming language is @code{c-mode}. @cindex Python mode @cindex Ruby mode @cindex Simula mode +@cindex Verilog mode @cindex VHDL mode @cindex M4 mode @cindex Shell-script mode +@cindex Scheme mode @cindex OPascal mode @cindex PostScript mode @cindex Conf mode @cindex DNS mode @cindex Javascript mode +@cindex Awk mode Emacs has programming language modes for Lisp, Scheme, the Scheme-based DSSSL expression language, Ada, ASM, AWK, C, C++, Fortran, Icon, IDL (CORBA), IDLWAVE, Java, Javascript, Metafont -(@TeX{}'s companion for font creation), Modula2, Object Pascal, Objective-C, -Octave, Pascal, Perl, Pike, PostScript, Prolog, Python, Ruby, Simula, Tcl, -and VHDL@. An alternative mode for Perl is called CPerl mode. Modes are -also available for the scripting languages of the common GNU and Unix -shells, and MS-DOS/MS-Windows @samp{BAT} files, and for makefiles, -DNS master files, and various sorts of configuration files. +(@TeX{}'s companion for font creation), Modula2, Object Pascal, +Objective-C, Octave, Pascal, Perl, Pike, PostScript, Prolog, Python, +Ruby, Simula, SQL, Tcl, Verilog, and VHDL@. An alternative mode for +Perl is called CPerl mode. Modes are also available for the scripting +languages of the common GNU and Unix shells, and MS-DOS/MS-Windows +@samp{BAT} files, and for makefiles, DNS master files, and various +sorts of configuration files. Ideally, Emacs should have a major mode for each programming language that you might want to edit. If it doesn't have a mode for @@ -100,12 +104,13 @@ distributed with Emacs (@pxref{Packages}); or you can contribute one. @findex backward-delete-char-untabify In most programming languages, indentation should vary from line to line to illustrate the structure of the program. Therefore, in most -programming language modes, typing @key{TAB} updates the indentation -of the current line (@pxref{Program Indent}). Furthermore, @key{DEL} -is usually bound to @code{backward-delete-char-untabify}, which -deletes backward treating each tab as if it were the equivalent number -of spaces, so that you can delete one column of indentation without -worrying whether the whitespace consists of spaces or tabs. +programming language modes, typing @kbd{@key{TAB}} updates the +indentation of the current line (@pxref{Program Indent}). +Furthermore, @kbd{@key{DEL}} is usually bound to +@code{backward-delete-char-untabify}, which deletes backward treating +each tab as if it were the equivalent number of spaces, so that you +can delete one column of indentation without worrying whether the +whitespace consists of spaces or tabs. @cindex mode hook, and major modes @vindex c-mode-hook @@ -122,13 +127,14 @@ For instance, entering C mode runs the hooks @code{prog-mode-hook} and @ifnottex Separate manuals are available for the modes for Ada (@pxref{Top,, Ada Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba -IDL/Pike/AWK (@pxref{Top, , CC Mode, ccmode, CC Mode}), and IDLWAVE -(@pxref{Top,, IDLWAVE, idlwave, IDLWAVE User Manual}). +IDL/Pike/AWK (@pxref{Top, , CC Mode, ccmode, CC Mode}), Octave, VHDL, +and IDLWAVE (@pxref{Top,, IDLWAVE, idlwave, IDLWAVE User Manual}). @end ifnottex @iftex The Emacs distribution contains Info manuals for the major modes for -Ada, C/C++/Objective C/Java/Corba IDL/Pike/AWK, and IDLWAVE@. For -Fortran mode, @pxref{Fortran,,, emacs-xtra, Specialized Emacs Features}. +Ada, C/C++/Objective C/Java/Corba IDL/Pike/AWK, Octave, VHDL, and +IDLWAVE@. For Fortran mode, @pxref{Fortran,,, emacs-xtra, Specialized +Emacs Features}. @end iftex @node Defuns @@ -362,6 +368,7 @@ language modes. @cindex pretty-printer Emacs also provides a Lisp pretty-printer in the @code{pp} package, which reformats Lisp objects with nice-looking indentation. +@xref{Output Functions, pp,, elisp, The Emacs Lisp Reference Manual}. @node Basic Indent @subsection Basic Program Indentation Commands @@ -376,16 +383,18 @@ Insert a newline, then adjust indentation of following line @kindex TAB @r{(programming modes)} @findex indent-line-function - The basic indentation command is @key{TAB} + The basic indentation command is @kbd{@key{TAB}} (@code{indent-for-tab-command}), which was documented in -@ref{Indentation}. In programming language modes, @key{TAB} indents -the current line, based on the indentation and syntactic content of -the preceding lines; if the region is active, @key{TAB} indents each -line within the region, not just the current line. +@ref{Indentation}. In programming language modes, @kbd{@key{TAB}} +indents the current line, based on the indentation and syntactic +content of the preceding lines; if the region is active, +@kbd{@key{TAB}} indents each line within the region, not just the +current line. - The command @key{RET} (@code{newline}), which was documented in -@ref{Inserting Text}, does the same as @kbd{C-j} followed by -@key{TAB}: it inserts a new line, then adjusts the line's indentation. + The command @kbd{@key{RET}} (@code{newline}), which was documented +in @ref{Inserting Text}, does the same as @kbd{C-j} followed by +@kbd{@key{TAB}}: it inserts a new line, then adjusts the line's +indentation. When indenting a line that starts within a parenthetical grouping, Emacs usually places the start of the line under the preceding line @@ -406,7 +415,7 @@ Paren}. Sometimes, you may want to reindent several lines of code at a time. One way to do this is to use the mark; when the mark is active and the -region is non-empty, @key{TAB} indents every line in the region. +region is non-empty, @kbd{@key{TAB}} indents every line in the region. Alternatively, the command @kbd{C-M-\} (@code{indent-region}) indents every line in the region, whether or not the mark is active (@pxref{Indentation Commands}). @@ -434,19 +443,19 @@ grouping, without affecting its overall indentation (i.e., the indentation of the line where the grouping starts). The function that @kbd{C-M-q} runs depends on the major mode; it is @code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode, -etc. To correct the overall indentation as well, type @key{TAB} +etc. To correct the overall indentation as well, type @kbd{@key{TAB}} first. @kindex C-u TAB If you like the relative indentation within a grouping but not the indentation of its first line, move point to that first line and type @kbd{C-u @key{TAB}}. In Lisp, C, and some other major modes, -@key{TAB} with a numeric argument reindents the current line as usual, -then reindents by the same amount all the lines in the parenthetical -grouping starting on the current line. It is clever, though, and does -not alter lines that start inside strings. Neither does it alter C -preprocessor lines when in C mode, but it does reindent any -continuation lines that may be attached to them. +@kbd{@key{TAB}} with a numeric argument reindents the current line as +usual, then reindents by the same amount all the lines in the +parenthetical grouping starting on the current line. It is clever, +though, and does not alter lines that start inside strings. Neither +does it alter C preprocessor lines when in C mode, but it does +reindent any continuation lines that may be attached to them. @findex indent-code-rigidly The command @kbd{M-x indent-code-rigidly} rigidly shifts all the @@ -488,7 +497,7 @@ expression. You can override the standard pattern in various ways for individual functions, according to the @code{lisp-indent-function} property of the function name. This is normally done for macro definitions, using -the @code{declare} construct. @xref{Defining Macros,,, elisp, the +the @code{declare} construct. @xref{Defining Macros,,, elisp, The Emacs Lisp Reference Manual}. @node C Indent @@ -496,7 +505,7 @@ Emacs Lisp Reference Manual}. Here are special features for indentation in C mode and related modes: -@table @code +@table @kbd @item C-c C-q @kindex C-c C-q @r{(C mode)} @findex c-indent-defun @@ -919,8 +928,8 @@ comments. For example, in Lisp code, comments starting with two semicolons are indented as if they were lines of code, while those starting with three semicolons are supposed to be aligned to the left margin and are often used for sectioning purposes. Emacs understand -these conventions; for instance, typing @key{TAB} on a comment line -will indent the comment to the appropriate position. +these conventions; for instance, typing @kbd{@key{TAB}} on a comment +line will indent the comment to the appropriate position. @example ;; This function is just an example. @@ -956,7 +965,7 @@ Kill comment on current line (@code{comment-kill}). Set comment column (@code{comment-set-column}). @item @kbd{C-M-j} @itemx @kbd{M-j} -Like @key{RET} followed by inserting and aligning a comment +Like @kbd{@key{RET}} followed by inserting and aligning a comment (@code{comment-indent-new-line}). @xref{Multi-Line Comments}. @item @kbd{M-x comment-region} @itemx @kbd{C-c C-c} (in C-like modes) @@ -986,8 +995,8 @@ negative argument @var{-n} removes @var{n} delimiters. current line, @kbd{M-;} adds a new comment to the current line. If the line is blank (i.e., empty or containing only whitespace characters), the comment is indented to the same position where -@key{TAB} would indent to (@pxref{Basic Indent}). If the line is -non-blank, the comment is placed after the last non-whitespace +@kbd{@key{TAB}} would indent to (@pxref{Basic Indent}). If the line +is non-blank, the comment is placed after the last non-whitespace character on the line; normally, Emacs tries putting it at the column specified by the variable @code{comment-column} (@pxref{Options for Comments}), but if the line already extends past that column, it puts diff --git a/doc/emacs/regs.texi b/doc/emacs/regs.texi index dd9e4d7cc7..8ff36ca554 100644 --- a/doc/emacs/regs.texi +++ b/doc/emacs/regs.texi @@ -18,7 +18,7 @@ or a number (such as @samp{1}); case matters, so register @samp{a} is not the same as register @samp{A}. You can also set a register in non-alphanumeric characters, for instance @samp{*} or @samp{C-d}. Note, it's not possible to set a register in @samp{C-g} or @samp{ESC}, -because these keys are reserved to terminate interactive commands. +because these keys are reserved for quitting (@pxref{Quitting}). @findex view-register A register can store a position, a piece of text, a rectangle, a diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi index 51a0685197..319f64fbae 100644 --- a/doc/emacs/search.texi +++ b/doc/emacs/search.texi @@ -1,3 +1,4 @@ +@c -*- coding: utf-8 -*- @c This is part of the Emacs manual. @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 Free Software @c Foundation, Inc. @@ -902,7 +903,8 @@ starting and ending characters with a @samp{-} between them. Thus, @samp{[a-z]} matches any lower-case @acronym{ASCII} letter. Ranges may be intermixed freely with individual characters, as in @samp{[a-z$%.]}, which matches any lower-case @acronym{ASCII} letter or @samp{$}, @samp{%} or -period. +period. As another example, @samp{[α-ωί]} matches all lower-case +Greek letters. You can also include certain special @dfn{character classes} in a character set. A @samp{[:} and balancing @samp{:]} enclose a diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 7bf03b8558..64b8c0a22f 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -6966,14 +6966,16 @@ means to use the default for that slot, as stated below. @table @asis @item 0 The glyph for the end of a truncated screen line (the default for this -is @samp{$}). @xref{Glyphs}. On graphical terminals, Emacs uses -arrows in the fringes to indicate truncation, so the display table has -no effect. +is @samp{$}). @xref{Glyphs}. On graphical terminals, Emacs by +default uses arrows in the fringes to indicate truncation, so the +display table has no effect, unless you disable the fringes +(@pxref{Fringes,, Window Fringes, emacs, the Gnu Emacs Manual}). @item 1 The glyph for the end of a continued line (the default is @samp{\}). -On graphical terminals, Emacs uses curved arrows in the fringes to -indicate continuation, so the display table has no effect. +On graphical terminals, Emacs by default uses curved arrows in the +fringes to indicate continuation, so the display table has no effect, +unless you disable the fringes. @item 2 The glyph for indicating a character displayed as an octal character @@ -6988,9 +6990,12 @@ default is @samp{...}). @xref{Selective Display}. @item 5 The glyph used to draw the border between side-by-side windows (the -default is @samp{|}). @xref{Splitting Windows}. This takes effect only -when there are no scroll bars; if scroll bars are supported and in use, -a scroll bar separates the two windows. +default is @samp{|}). @xref{Splitting Windows}. This currently has +effect only on text terminals; on graphical terminals, if vertical +scroll bars are supported and in use, a scroll bar separates the two +windows, and if there are no vertical scroll bars and no dividers +(@pxref{Window Dividers}), Emacs uses a thin line to indicate the +border. @end table For example, here is how to construct a display table that mimics commit 78426b84e8b0e5de87a2203e0c8dd738cd237270 Author: Michael Albinus Date: Wed Feb 14 09:28:33 2018 +0100 Improvements on tramp.texi * doc/misc/tramp.texi: Use Tramp version in title. Further improvements on user option indexing. Finish command examples with @key{RET} where appropriate. (Remote processes): Use 'M-&' for invocation of async shell. (Frequently Asked Questions): Add example with simplified syntax. diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index 61fd0d33a7..e264298efc 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -1,18 +1,16 @@ \input texinfo @c -*- mode: texinfo; coding: utf-8 -*- @setfilename ../../info/tramp.info @c %**start of header -@settitle TRAMP User Manual @include docstyle.texi -@c %**end of header - -@c This is *so* much nicer :) -@footnotestyle end - @c In the Tramp repository, the version number is auto-frobbed from @c configure.ac, so you should edit that file and run @c "autoconf && ./configure" to change the version number. - @include trampver.texi +@settitle @value{tramp} @value{trampver} User Manual +@c %**end of header + +@c This is *so* much nicer :) +@footnotestyle end @c Macro for formatting a file name according to the respective @c syntax. Macro arguments should not have any leading or trailing @@ -48,7 +46,7 @@ copy and modify this GNU manual.'' @end direntry @titlepage -@title @value{tramp} version @value{trampver} User Manual +@title @value{tramp} @value{trampver} User Manual @author by Daniel Pittman @author based on documentation by Kai Großjohann @end titlepage @@ -57,9 +55,9 @@ copy and modify this GNU manual.'' @node Top, Overview, (dir), (dir) -@top @value{tramp} version @value{trampver} User Manual +@top @value{tramp} @value{trampver} User Manual -This file documents @value{tramp} version @value{trampver}, a remote file +This file documents @value{tramp} @value{trampver}, a remote file editing package for Emacs. @value{tramp} stands for ``Transparent Remote (file) Access, Multiple @@ -319,7 +317,7 @@ behind the scenes when you open a file with @value{tramp}. @chapter Obtaining @value{tramp} @cindex obtaining @value{tramp} -@value{tramp} is included as part of Emacs (since Emacs version 22.1). +@value{tramp} is included as part of Emacs (since Emacs 22.1). @value{tramp} is also freely packaged for download on the Internet at @uref{https://ftp.gnu.org/gnu/tramp/}. @@ -1444,8 +1442,8 @@ server. Both ssh and PuTTY support such proxy settings, using an HTTP tunnel via the @command{CONNECT} command (conforming to RFC 2616, 2817 -specifications). Proxy servers using HTTP version 1.1 or later -protocol support this command. +specifications). Proxy servers using HTTP 1.1 or later protocol +support this command. @subsection Tunneling with ssh @@ -1483,6 +1481,7 @@ proxy server @samp{proxy.your.domain} on port 3128. @cindex using non-standard methods @cindex create your own methods +@vindex tramp-methods The @code{tramp-methods} variable currently has an exhaustive list of predefined methods. Any part of this list can be modified with more suitable settings. Refer to the Lisp documentation of that variable, @@ -1493,8 +1492,8 @@ accessible with @kbd{C-h v tramp-methods @key{RET}}. @section Selecting config files for user/host name completion @cindex customizing completion @cindex selecting config files -@vindex tramp-completion-function-alist +@vindex tramp-completion-function-alist @code{tramp-completion-function-alist} uses predefined files for user and host name completion (@pxref{File name completion}). For each method, it keeps a set of configuration files and a function that can @@ -1632,8 +1631,8 @@ the need. @anchor{Using an authentication file} @subsection Using an authentication file -@vindex auth-sources +@vindex auth-sources The package @file{auth-source.el}, originally developed for No Gnus, reads passwords from different sources, @xref{Help for users, , auth-source, auth}. The default authentication file is @@ -1679,7 +1678,6 @@ Set @code{password-cache} to @code{nil} to disable password caching. @node Connection caching @section Reusing connection related information @cindex caching -@vindex tramp-persistency-file-name @vindex tramp-persistency-file-name For faster initial connection times, @value{tramp} stores previous @@ -1703,11 +1701,11 @@ connection related information for that host and creates a new entry. @node Predefined connection information @section Setting own connection related information -@vindex tramp-connection-properties For more precise customization, parameters specified by @code{tramp-methods} can be overwritten manually. +@vindex tramp-connection-properties Set @option{tramp-connection-properties} to manually override @code{tramp-methods}. Properties in this list are in the form @code{(@var{regexp} @var{property} @var{value})}. @var{regexp} @@ -1882,7 +1880,6 @@ prompts, for which @value{tramp} uses @option{tramp-wrong-passwd-regexp}. @item @command{tset} and other questions @cindex unix command tset @cindex tset unix command -@vindex tramp-terminal-type @vindex tramp-terminal-type To suppress inappropriate prompts for terminal type, @value{tramp} @@ -1963,9 +1960,9 @@ shell-specific config files. For example, bash can use @value{tramp} redefines the remote shell prompt internally for robust parsing. This redefinition affects the looks of a prompt in an -interactive remote shell through commands, such as @kbd{M-x -shell}. Such prompts, however, can be reset to something more readable -and recognizable using these @value{tramp} variables. +interactive remote shell through commands, such as @kbd{M-x shell +@key{RET}}. Such prompts, however, can be reset to something more +readable and recognizable using these @value{tramp} variables. @value{tramp} sets the @env{INSIDE_EMACS} variable in the startup script file @file{~/.emacs_SHELLNAME}. @@ -2078,8 +2075,8 @@ directory for temporary files: @item Open a remote connection with the command @kbd{C-x C-f -@trampfn{ssh,192.168.0.26#2222,}}, where @command{sshd} is listening -on port @samp{2222}. +@trampfn{ssh,192.168.0.26#2222,} @key{RET}}, where @command{sshd} is +listening on port @samp{2222}. To add a corresponding entry to the @file{~/.ssh/config} file (recommended), use this: @@ -2106,7 +2103,7 @@ the previous example, fix the connection properties as follows: @noindent Open a remote connection with a more concise command @kbd{C-x C-f -@trampfn{ssh,android,}}. +@trampfn{ssh,android,} @key{RET}}. @end itemize @@ -2114,8 +2111,8 @@ Open a remote connection with a more concise command @kbd{C-x C-f @section Auto-save and Backup configuration @cindex auto-save @cindex backup -@vindex backup-directory-alist +@vindex backup-directory-alist To avoid @value{tramp} from saving backup files owned by @samp{root} to locations accessible to others, default backup settings in @option{backup-directory-alist} have to be altered. @@ -2158,7 +2155,6 @@ Disabling backups can be targeted to just the @option{su} and @end group @end lisp -@vindex backup-directory-alist @vindex tramp-backup-directory-alist Another option is to create better backup file naming with user and host names prefixed to the file name. For example, transforming @@ -2219,8 +2215,9 @@ This section is incomplete. Please share your solutions. @cindex sshx method with cygwin Cygwin's @command{ssh} works only with a Cygwin version of Emacs. To -check for compatibility: type @kbd{M-x eshell}, and start @kbd{ssh -test.host}. Incompatibilities trigger this message: +check for compatibility: type @kbd{M-x eshell @key{RET}}, and start +@kbd{ssh test.host @key{RET}}. Incompatibilities trigger this +message: @example Pseudo-terminal will not be allocated because stdin is not a terminal. @@ -2536,8 +2533,8 @@ remote host name and file name. For example, hopping over a single proxy @samp{bird@@bastion} to a remote file on @samp{you@@remotehost}: @example -@c @kbd{C-x C-f @trampfn{ssh@value{postfixhop}bird@@bastion|ssh,you,remotehost,/path}} -@kbd{C-x C-f @value{prefix}ssh@value{postfixhop}bird@@bastion|ssh@value{postfixhop}you@@remotehost@value{postfix}/path} +@c @kbd{C-x C-f @trampfn{ssh@value{postfixhop}bird@@bastion|ssh,you,remotehost,/path} @key{RET}} +@kbd{C-x C-f @value{prefix}ssh@value{postfixhop}bird@@bastion|ssh@value{postfixhop}you@@remotehost@value{postfix}/path @key{RET}} @end example Proxies can take patterns @code{%h} or @code{%u}. @@ -2759,14 +2756,15 @@ host. Example: @example @group @kbd{C-x C-f @trampfn{sudo,,} @key{RET}} -@kbd{M-! tail -f /var/log/syslog.log & @key{RET}} +@kbd{M-& tail -f /var/log/syslog.log @key{RET}} @end group @end example @command{tail} command outputs continuously to the local buffer, @file{*Async Shell Command*} -@kbd{M-x auto-revert-tail-mode} runs similarly showing continuous output. +@kbd{M-x auto-revert-tail-mode @key{RET}} runs similarly showing +continuous output. @subsection Running @code{eshell} on a remote host @@ -2775,8 +2773,8 @@ host. Example: @value{tramp} is integrated into @file{eshell.el}, which enables interactive eshell sessions on remote hosts at the command prompt. You must add the module @code{em-tramp} to @code{eshell-modules-list}. -Here's a sample interaction after opening @kbd{M-x eshell} on a remote -host: +Here's a sample interaction after opening @kbd{M-x eshell @key{RET}} +on a remote host: @example @group @@ -2857,7 +2855,7 @@ calls include: @end group @end example -Just the local part of a remote file name, such as @kbd{perl -d +Just the local part of a remote file name, such as @command{perl -d /home/user/myprog.pl}, is not possible. Arguments of the program to be debugged must be literal, can take @@ -2877,8 +2875,8 @@ command. Powershell V2.0 on the remote host is required to run processes triggered from @value{tramp}. @option{explicit-shell-file-name} and @option{explicit-*-args} have to -be set properly so @kbd{M-x shell} can open a proper remote shell on a -MS Windows host. To open @command{cmd}, set it as follows: +be set properly so @kbd{M-x shell @key{RET}} can open a proper remote +shell on a MS Windows host. To open @command{cmd}, set it as follows: @lisp @group @@ -2962,9 +2960,9 @@ Before sending a bug report, run the test suite first @ref{Testing}. Check if the bug or problem is already addressed in @xref{Frequently Asked Questions}. -Run @kbd{M-x tramp-bug} to generate a buffer with details of the -system along with the details of the @value{tramp} -installation. Please include these details with the bug report. +Run @kbd{M-x tramp-bug @key{RET}} to generate a buffer with details of +the system along with the details of the @value{tramp} installation. +Please include these details with the bug report. The bug report must describe in as excruciating detail as possible the steps required to reproduce the problem. These details must include @@ -3089,7 +3087,7 @@ put the cursor at the top of the buffer, and then apply the following expression: @example -@kbd{M-: (re-search-forward (concat tramp-shell-prompt-pattern "$"))} +@kbd{M-: (re-search-forward (concat tramp-shell-prompt-pattern "$")) @key{RET}} @end example If the cursor has not moved to the prompt at the bottom of the buffer, @@ -3293,9 +3291,10 @@ the following code in @file{~/.emacs} file. How to get a Visual Warning when working with @samp{root} privileges? 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. -Enable it via @kbd{M-x load-theme @key{RET} tramp}. Further +Enable it via @kbd{M-x load-theme @key{RET} tramp @key{RET}}. Further customization is explained in user option @option{tramp-theme-face-remapping-alist}. @@ -3369,6 +3368,24 @@ is @file{@trampfn{ssh,news@@news.my.domain,/opt/news/etc}}, then: @enumerate +@item +Use simplified syntax: + +If you always apply the default method (@pxref{Default Method}), you +could use the simplified @value{tramp} syntax (@pxref{Change file name +syntax}): + +@lisp +@group +(customize-set-variable 'tramp-default-method "ssh") +(tramp-change-syntax 'simplified) +@end group +@end lisp + +The reduced typing: @kbd{C-x C-f +@code{@value{prefix}news@@news.my.domain@value{postfix}/opt/news/etc} +@key{RET}}. + @item Use default values for method name and user name: @@ -3383,11 +3400,12 @@ You can define default methods and user names for hosts, @end group @end lisp -The reduced typing: @kbd{C-x C-f @trampfn{-,news.my.domain,/opt/news/etc}}. +The reduced typing: @kbd{C-x C-f +@trampfn{-,news.my.domain,/opt/news/etc} @key{RET}}. @strong{Note} that there are some useful shortcuts already. Accessing your local host as @samp{root} user, is possible just by @kbd{C-x C-f -@trampfn{su,,}}. +@trampfn{su,,} @key{RET}}. @item Use configuration options of the access method: @@ -3404,7 +3422,7 @@ Host xy @end group @end example -The reduced typing: @kbd{C-x C-f @trampfn{ssh,xy,/opt/news/etc}}. +The reduced typing: @kbd{C-x C-f @trampfn{ssh,xy,/opt/news/etc} @key{RET}}. Depending on the number of files in the directories, host names completion can further reduce key strokes: @kbd{C-x C-f @@ -3572,8 +3590,8 @@ Load @file{bbdb} in Emacs: @end group @end lisp -Create a BBDB entry with @kbd{M-x bbdb-create-ftp-site}. Then specify -a method and user name where needed. Examples: +Create a BBDB entry with @kbd{M-x bbdb-create-ftp-site @key{RET}}. +Then specify a method and user name where needed. Examples: @example @group @@ -3709,8 +3727,8 @@ To disable both @value{tramp} (and Ange FTP), set @code{tramp-mode} to @end lisp @item -To unload @value{tramp}, type @kbd{M-x tramp-unload-tramp}. Unloading -@value{tramp} resets Ange FTP plugins also. +To unload @value{tramp}, type @kbd{M-x tramp-unload-tramp @key{RET}}. +Unloading @value{tramp} resets Ange FTP plugins also. @end itemize @end itemize commit 0dca618075f4a02d90432d09ecd31be76b4ceca0 Author: Paul Eggert Date: Tue Feb 13 14:52:20 2018 -0800 Tramp minor doc fixes * doc/misc/tramp.texi (Remote processes): Spelling fix and minor wording improvement. diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index 161f48ca3c..61fd0d33a7 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -2652,9 +2652,9 @@ this. You could overwrite this behavior by evaluating @end lisp In addition to @option{tramp-remote-process-environment}, you can set -environment variables for invidivual remote process calls by -let-binding @code{process-environment}. @value{tramp} will apply any -entries which are not present in the global default value of +environment variables for individual remote process calls by +let-binding @code{process-environment}. @value{tramp} applies any +entries not present in the global default value of @code{process-environment} (overriding @option{tramp-remote-process-environment} settings, if they conflict). For example: