* lisp/help-fns.el (describe-symbol-backends): New var.
(help-xref-stack-item): Declare.
(describe-symbol): Rename from describe-function-or-variable.
Rewrite using describe-symbol-backends instead of help-xref-interned.
* lisp/help.el (help-map): Use it.
* lisp/help-mode.el (help-symbol, help-follow-symbol): Use it.
(help-xref-interned): Make it into an obsolete alias.
Fix several problems with the recently-added custom variable
help-quote-translation where the code would quote inconsistently
in help buffers. Add support for quoting 'like this', which
is common in other GNU programs in ASCII environments. Change
help-quote-translation to use more mnemonic values: values are now the
initial quoting char, e.g., (setq help-quote-translation ?`) gets the
traditional Emacs help-buffer quoting style `like this'. Change the
default behavior of substitute-command-keys to match what's done in
set-locale-environment, i.e., quote ‘like this’ if displayable,
'like this' otherwise.
* doc/lispref/help.texi (Keys in Documentation): Document
new behavior of substitute-command-keys, and document
help-quote-translation.
* doc/lispref/tips.texi (Documentation Tips):
Mention the effect of help-quote-translation.
* etc/NEWS: Mention new behavior of substitute-command-keys,
and merge help-quote-translation news into it.
When talking about doc strings, mention new ways to type quotes.
* lisp/cedet/mode-local.el (overload-docstring-extension):
Revert my recent change to this function, which shouldn't be
needed as the result is a doc string.
* lisp/cedet/mode-local.el (mode-local-print-binding)
(mode-local-describe-bindings-2):
* lisp/cedet/srecode/srt-mode.el (srecode-macro-help):
* lisp/cus-theme.el (describe-theme-1):
* lisp/descr-text.el (describe-text-properties-1, describe-char):
* lisp/emacs-lisp/cl-generic.el (cl--generic-describe):
* lisp/emacs-lisp/eieio-opt.el (eieio-help-class)
(eieio-help-constructor):
* lisp/emacs-lisp/package.el (describe-package-1):
* lisp/faces.el (describe-face):
* lisp/help-fns.el (help-fns--key-bindings)
(help-fns--compiler-macro, help-fns--parent-mode)
(help-fns--obsolete, help-fns--interactive-only)
(describe-function-1, describe-variable):
* lisp/help.el (describe-mode):
Use substitute-command-keys to ensure a more-consistent quoting
style in help buffers.
* lisp/cus-start.el (standard):
Document new help-quote-translation behavior.
* lisp/emacs-lisp/lisp-mode.el (lisp-fdefs):
* lisp/help-mode.el (help-xref-symbol-regexp, help-xref-info-regexp)
(help-xref-url-regexp):
* lisp/international/mule-cmds.el (help-xref-mule-regexp-template):
* lisp/wid-edit.el (widget-documentation-link-regexp):
Also match 'foo', in case we're in a help buffer generated when
help-quote-translation is ?'.
* src/doc.c: Include disptab.h, for DISP_CHAR_VECTOR.
(LEFT_SINGLE_QUOTATION_MARK, uLSQM0, uLSQM1, uLSQM2, uRSQM0)
(uRSQM1, uRSQM2, LSQM, RSQM): New constants.
(Fsubstitute_command_keys): Document and implement new behavior.
(Vhelp_quote_translation): Document new behavior.
Fix suggested by Stefan Monnier.
* lisp/help-fns.el (help-fns--signature):
Insert "`X", not "(\` X)", when documenting `X (Bug#20759).
* lisp/help.el (help-split-fundoc, help--make-usage-docstring):
Don't treat `X specially, as help-fns--signature now handles this.
While investigating Bug#20759, I discovered other quoting problems:
C-h f mishandled characters like backslash and quote in function names.
This fix changes the behavior so that 'C-h f pcase RET' now
generates "... (\` QPAT) ..." instead of "... (` QPAT) ...",
because '(format "%S" '(` FOO))' returns "(\\` FOO)". A comment
in src/lread.c's read1 function says that the backslash will be
needed starting in Emacs 25, which implies that 'format' is
correct and the old pcase documention was wrong to omit the backslash.
* lisp/emacs-lisp/nadvice.el (advice--make-docstring):
* lisp/help-fns.el (help-fns--signature):
* lisp/help.el (help-add-fundoc-usage):
* lisp/progmodes/elisp-mode.el (elisp-function-argstring):
Use help--make-usage-docstring rather than formatting
help-make-usage.
* lisp/emacs-lisp/pcase.el (pcase--make-docstring):
Return raw docstring.
* lisp/help-fns.el (help-fns--signature): New arg RAW, to return
raw docstring. Take more care to distinguish raw from cooked dstrings.
(describe-function-1): Let help-fns--signature substitute
command keys.
* lisp/help.el (help--docstring-quote): New function.
(help-split-fundoc): Use it, to quote funny characters more
systematically.
(help--make-usage): Rename from help-make-usage, since this
should be private. Leave an obsolete alias for the old name.
(help--make-usage-docstring): New function.
* test/automated/help-fns.el (help-fns-test-funny-names): New test.
Fixes: debbugs:19645
* lisp/help.el (help-make-usage): Don't turn a "_" arg into an empty-string.
* lisp/emacs-lisp/cl-generic.el (cl--generic-lambda): Don't confuse a string
body with a docstring.
* help.el (help-window-old-frame): New variable.
(help-window-select): Default to nil (Bug#11039). Rewrite
doc-string.
(help-window-setup): When the help window appears on another
frame and `help-window-select' is non-nil, give that frame input
focus too (Bug#19012).
(with-help-window): Store selected frame in
help-window-old-frame.
* lisp/help.el (help--key-binding-keymap): New function.
(help--binding-locus): New function.
(describe-key): Mention the keymap in which the binding was
found.
Fixes: debbugs:13948
These are old copies of online information that is not Emacs-specific.
* etc/CENSORSHIP, etc/GNU, etc/LINUX-GNU, etc/THE-GNU-PROJECT, etc/WHY-FREE:
Replace contents with pointers to www.gnu.org or emacs.info, mark obsolete.
* src/callproc.c (init_callproc): In etc, look for NEWS rather than GNU.
* lisp/startup.el (fancy-startup-text):
* lisp/help.el (describe-gnu-project): Visit online info about GNU project.
* doc/emacs/help.texi (Help Files): Update C-h g description.
* doc/misc/efaq.texi (Informational files for Emacs): Do not mention etc/GNU.
* admin/notes/copyright: Remove references to these files.
* etc/MACHINES, etc/NEWS.19: Replace references to these files.
* window.el (with-temp-buffer-window): Don't make BUFFER-OR-NAME
current (Bug#16816, Bug#17007).
(with-current-buffer-window): New macro doing the same as
`with-temp-buffer-window' but with BUFFER-OR-NAME current.
* help.el (help-print-return-message): Warn in doc-string to not
use this in `with-help-window'.
(describe-bindings-internal): Call `describe-buffer-bindings'
from within help buffer. See Juanma's scenario in (Bug#16816).
(with-help-window): Update doc-string.
* dired.el (dired-mark-pop-up):
* files.el (save-buffers-kill-emacs):
* register.el (register-preview): Use `with-current-buffer-window'
instead of `with-temp-buffer-window'.
* display.texi (Temporary Displays): Rewrite descriptions of
`with-output-to-temp-buffer' and `with-temp-buffer-window'.
* help.texi (Help Functions): Rewrite description of
`with-help-window'.
They are now needed by eg the function `documentation' in some circumstances.
* lisp/help-fns.el (help-split-fundoc, help-add-fundoc-usage)
(help-function-arglist, help-make-usage): Move from here...
* lisp/help.el (help-split-fundoc, help-add-fundoc-usage)
(help-function-arglist, help-make-usage): ... to here.
* lisp/emacs-lisp/bytecomp.el (byte-compile-lambda): Do not load help-fns.
Fixes: debbugs:17001
* window.el (with-temp-buffer-window): Revert change from
2014-02-21. Suggested by Thierry Volpiatto
<thierry.volpiatto@gmail.com>. Fix doc-string based on a
suggestion by Nicolas Richard <theonewiththeevillook@yahoo.fr>.
* help.el (with-help-window): Fix doc-string.
* etc/FTP: Mark as obsolete.
* etc/ORDERS: Replace contents with pointer to emacs.info, mark obsolete.
* doc/emacs/emacs.texi (Distrib): Add donate URL. Add anchor.
* lisp/help.el (view-order-manuals): Open emacs.info rather than ORDERS.
Ref: http://lists.gnu.org/archive/html/emacs-devel/2010-02/msg00135.html
* lisp/simple.el (messages-buffer-mode): New major mode.
(messages-buffer): New function.
* lisp/startup.el (normal-top-level): Switch mode of *Messages* buffer.
* src/xdisp.c (message_dolog): If we create *Messages*,
switch it to messages-buffer-mode.
* lisp/emacs-lisp/ert.el (ert--force-message-log-buffer-truncation)
(ert-run-test): Use `message-buffer' function.
(ert--force-message-log-buffer-truncation): Ignore read-only.
* lisp/help.el (view-echo-area-messages): Use `message-buffer' function.
* lisp/mail/emacsbug.el (report-emacs-bug): Use `message-buffer' function.
* lisp/gnus/gnus-util.el (gnus-message-with-timestamp-1):
Use `message-buffer' function if available. Ignore read-only.
* etc/NEWS: Mention this.
In buffer display functions handle window-height/window-width
alist entries. Suggested by Juri Linkov as fix for Bug#1806.
* window.el (window--display-buffer): New argument ALIST. Obey
window-height and window-width alist entries.
(window--try-to-split-window): New argument ALIST. Bind
window-combination-limit to t when the window's size shall be
changed and window-combination-limit equals `window-size'.
(display-buffer-in-atom-window)
(display-buffer-in-major-side-window)
(display-buffer-in-side-window, display-buffer-same-window)
(display-buffer-reuse-window, display-buffer-pop-up-frame)
(display-buffer-pop-up-window, display-buffer-below-selected)
(display-buffer-at-bottom, display-buffer-in-previous-window)
(display-buffer-use-some-window): Adjust all callers of
window--display-buffer and window--try-to-split-window.
(fit-frame-to-buffer): New option.
(fit-window-to-buffer): Can resize frames if fit-frame-to-buffer
is non-nil.
(display-buffer-in-major-side-window): Evaluate window-height /
window-width alist entries.
* help.el (temp-buffer-resize-frames)
(temp-buffer-resize-regexps): Remove options.
(temp-buffer-resize-mode): Adjust doc-string.
(resize-temp-buffer-window): Don't consult
temp-buffer-resize-regexps. Use fit-frame-to-buffer instead of
temp-buffer-resize-frames.
* dired.el (dired-mark-pop-up): Call
display-buffer-below-selected with a fit-window-to-buffer alist
entry.
* window.c (Vwindow_combination_limit): New default value.
(Qwindow_size): New symbol replacing Qtemp_buffer_resize.
* window.c (Fsplit_window_internal): Handle only Qt value of
Vwindow_combination_limit separately.
(Qtemp_buffer_resize): New symbol.
(Vwindow_combination_limit): New default value. Rewrite
doc-string.
* cus-start.el (window-combination-limit): Add new optional
values.
* window.el (temp-buffer-window-show)
(window--try-to-split-window): Obey new values of
window-combination-limit.
(split-window): Test window-combination-limit for t instead of
non-nil.
(display-buffer-at-bottom): New buffer display action function.
* help.el (temp-buffer-resize-regexps): New option.
(temp-buffer-resize-mode): Rewrite doc-string.
(resize-temp-buffer-window): Obey temp-buffer-resize-regexps.
Don't resize reused window. Suggested by Glen Morris.
* lisp/help-fns.el (help-fns--autoloaded-p): New function.
(describe-function-1): Refer to a function as "autoloaded" if it
was autoloaded at any time in the past. Perform autoloading if
help-enable-auto-load is non-nil.
* lisp/help.el (help-enable-auto-load): New variable.
* src/doc.c (Fsubstitute_command_keys): Fix punctuation.
* window.el (set-window-buffer-start-and-point): Call
set-window-start with NOFORCE argument t. Suggested by Thierry
Volpiatto <thierry.volpiatto@gmail.com>.
(quit-window): Reword doc-string. Handle new format of
quit-restore parameter. Don't delete window if it has a
previous buffer we can show instead of the present one.
(display-buffer-record-window): Rewrite using a new format for
the quit-restore window parameter
(special-display-popup-frame, display-buffer-same-window)
(display-buffer-reuse-window, display-buffer-pop-up-frame)
(display-buffer-pop-up-window, display-buffer-use-some-window):
Adapt symbol passed to display-buffer-record-window.
* help.el (help-window-setup): Handle new format of quit-restore
parameter.
* window.el (display-buffer-window): Remove.
(display-buffer-record-window): Use help-setup window parameter
instead of variable display-buffer-window.
(display-buffer-function, special-display-buffer-names)
(special-display-function): Mention help-setup parameter instead
of display-buffer-window in doc-string.
* help.el (help-window-setup): New argument help-window. Use
help-window-setup parameter instead of display-buffer-window.
Reword some messages.
(with-help-window): Pass window used for displaying the buffer
to help-window-setup. Don't set display-buffer-window.
* help.el (help-window): Remove variable.
(help-window-point-marker, temp-buffer-max-height)
(temp-buffer-resize-mode, help-window-select): Rewrite doc-strings.
(help-print-return-message): Don't set help-window.
(resize-temp-buffer-window): Rewrite cod eand doc-string.
(help-window-setup-finish): Remove.
(help-window-display-message, help-window-setup)
(with-help-window): Major rewrite based on new
display-buffer-window variable.
* help-mode.el (help-mode-finish): Remove help-window related
code.
* view.el (view-exits-all-viewing-windows): Remove reference to
view-return-to-alist in doc-string.
(view-return-to-alist): Make obsolete.
(view-buffer): Call pop-to-buffer-same-window and remove
undo-window code.
(view-buffer-other-window): Call pop-to-buffer-other-window and
simplify code. Ignore second argument.
(view-buffer-other-frame): Call pop-to-buffer-other-frame and
simplify code. Ignore second argument.
(view-return-to-alist-update): Make obsolete.
(view-mode-enter): Rename second argument to QUIT-RESTORE.
Rewrite using quit-restore window parameters.
(view-mode-exit): Rename second argument to EXIT-ONLY. Rewrite
using quit-restore-window.
(View-exit, View-exit-and-edit, View-leave, View-quit)
(View-quit-all, View-kill-and-leave): Call view-mode-exit with
appropriate arguments.
(view-end-message): Use quit-restore window parameter.
* lisp/help.el (help-form-show): New function, to be called from C.
Put help-form output in a buffer named differently than *Help*.
* src/keyboard.c (read_char): Call Lisp function help-form-show,
instead of using internal_with_output_to_temp_buffer.
(Qhelp_form_show): New var.
* src/lisp.h (internal_with_output_to_temp_buffer): Remove prototype.
* src/print.c (internal_with_output_to_temp_buffer): Function deleted.
* isearch.el (isearch-help-for-help-internal): Purecopy the second arg.
* help-macro.el (make-help-screen): Avoid using an ambiguous function
definition where the docstring could be taken for the return value.
