1821844357 Add missing K key documentation for Cangjie input methods
be860c1385 Fix manual entry of 'quit-restore-window' (Bug#52328)
35a96139df Clarify a comment in xdisp.c
6ba2f028cf Revert "Grep alias `all' shall not match parent directory"
eb9e33e238 ; * etc/NEWS: Non-nil repeat-keep-prefix is not the defaul...
538fc1d0e0 Fix mode-line display in Calendar mode
# Conflicts:
# etc/NEWS
# lisp/help.el
* lisp/help.el (substitute-command-keys): New optional argument
NO-FACE, to avoid putting the 'help-key-binding' face on the key
bindings.
* lisp/calendar/calendar.el (calendar-mode-line-entry): Call
'substitute-command-keys' with the new optional argument non-nil.
(Bug#52366)
* doc/lispref/help.texi (Keys in Documentation): Document the new
optional argument of 'substitute-command-keys'.
* etc/NEWS: Announce the addition of a new argument to
'substitute-command-keys'.
* lisp/help.el (substitute-command-keys): Add new format "\\`f'" for
literal key sequences. (Bug#50804)
* doc/lispref/help.texi (Keys in Documentation): Document the above
new substitution.
* test/lisp/help-tests.el
(help-tests-substitute-command-keys/literal-key-sequence):
(help-tests-substitute-command-keys/literal-key-sequence-errors): New
tests.
(help-tests-substitute-key-bindings/face-help-key-binding): Extend test.
* lisp/emacs-lisp/shortdoc.el (shortdoc-add-function): Use nconc to
actually append a new section to the list of groups while avoiding a
previous OBOE. Push a new group to the front of shortdoc--groups
without copying it, just like define-short-documentation-group does.
(buffer): Fix copypasta in unlock-buffer example.
* test/lisp/emacs-lisp/shortdoc-tests.el (shortdoc-examples): Also
check that :no-value forms demonstrate the right function.
* doc/lispref/help.texi (Documentation Groups): Clarify that @dots
in the define-short-documentation-group arglist refer to whole
key-value pairs. Fix typo in :eg-result-string description.
* doc/lispref/help.texi (Documentation Groups): Fix typos and add an
example.
* lisp/emacs-lisp/shortdoc.el (define-short-documentation-group): Add
:no-eval* and :result-string keywords to the docstring. (Bug#48730)
Be consistent when pretty-printing keys: put modifiers outside <>,
thus the more logical C-M-<return> instead of <C-M-return>.
* src/keymap.c (Fsingle_key_description):
Skip modifier prefix before adding <>.
* doc/lispref/help.texi (Describing Characters): Update example.
* doc/lispref/debugging.texi (Backtraces):
* doc/lispref/minibuf.texi (Text from Minibuffer):
Use @kbd instead of @key.
* etc/NEWS: Announce the change.
* test/src/keymap-tests.el (keymap--key-description):
* test/lisp/subr-tests.el (subr--kbd): New tests.
* doc/lispref/help.texi (Help Functions): Mention help-form for
read-char-from-minibuffer and y-or-n-p.
* doc/lispref/minibuf.texi (Yes-or-No Queries): Mention help-form
for y-or-n-p.
(Multiple Queries): Mention help-form for read-char-from-minibuffer.
* lisp/files.el (find-file-noselect): Let-bind multi-line help text
to help-form for y-or-n-p.
* lisp/subr.el (read-char-choice): Mention help-form in docstring.
(read-char-from-minibuffer): Mention help-form in docstring.
(y-or-n-p-map): Remove handling of 'help'.
(y-or-n-p): Mention help-form in docstring.
When help-form is non-nil: add help-char to 'prompt', and bind
help-char to help-form-show in composed-keymap.
* doc/lispref/help.texi (Documentation Groups): Document it.
* lisp/help-fns.el (help-fns--mention-shortdoc-groups): Output
references to the shortdocs.
* lisp/emacs-lisp/shortdoc.el: New file.
* doc/lispref/abbrevs.texi (Abbrev Expansion):
* doc/lispref/backups.texi (Reverting):
* doc/lispref/functions.texi (Mapping Functions):
* doc/lispref/help.texi (Accessing Documentation):
* doc/lispref/sequences.texi (Char-Tables):
* doc/lispref/syntax.texi (Categories):
* doc/lispref/text.texi (Sorting):
Remove function quoting from lambda in examples where it still occurs,
since examples should follow our best style and be consistent.
* src/keymap.c (Ftext_char_description):
* doc/lispref/help.texi (Describing Characters): More accurate
description of 'text-char-description'. Remove incorrect
examples from the ELisp manual. (Bug#32743)
* doc/lispref/help.texi (Describing Characters):
* doc/lispref/commands.texi (Keyboard Events)
(Reading One Event, Classifying Events): Make the distinction
between characters and character events more explicit.
* src/keymap.c (Ftext_char_description)
(Fsingle_key_description):
* src/lread.c (Fread_char, Fread_char_exclusive): Doc fixes,
to make a clear distinction between a character input event
and a character code. (Bug#32562)
* doc/lispref/help.texi (Help Functions): Change variable name
to 'buffer-or-name'.
* lisp/help.el (with-help-window): Change variable name to
'buffer-or-name' and rewrite the doc string, adding reference
to 'help-window-setup'. (Bug#30792)
* doc/lispref/control.texi (Signaling Errors):
* doc/lispref/display.texi (Displaying Messages):
* doc/lispref/strings.texi (Formatting Strings):
Edit for brevity, farming out the details to the new
Text Quoting Style node.
* doc/lispref/help.texi (Text Quoting Style): New section.
Move detailed discussion of text-quoting-style here.
Add discussion about how to output grave accent and apostrophe in
documentation and messages. Adjust xrefs to point to this section
when appropriate.
* etc/NEWS: text-quoting-style semantics have not changed.
This is a partial reversion of yesterday's commit by the same author, which
changed the meaning of nil and introduced the new value t.
* src/doc.c (text_quoting_style, text-quoting-style)
(internal--text-quoting-flag): Revert yesterday's changes.
* lisp/cus-start.el: (top level): Amend the entry for text-quoting-style.
* etc/NEWS: Amend the entry for text-quoting-style.
* doc/lispref/control.texi (Signalling Errors)
* doc/lispref/display.texi (Displaying Messages)
* doc/lispref/strings.texi (Formatting Strings): Bind text-quoting-style to
grave rather than nil to inhibit translation of quotes.
* doc/lispref/help.texi (Keys in Documentation): Revert the description of the
proposed new default, t.
A value of nil for text-quoting-style now means "no translation". t means
"Use curved quotes if displayable".
* src/doc.c (text-quoting-style (function)): modify for new semantics.
(text-quoting-style (variable)): Amend the doc string, set the default value
to t.
* lisp/cus-start.el: (top level): Create a customize entry for
text-quoting-style in group display.
* etc/NEWS: Amend the entry for text-quoting-style.
* doc/emacs/display.texi (Text Display): Describe the translation of ASCII
quotes to curved quotes, and how to influence or inhibit it.
* doc/lispref/control.texi (Signalling Errors)
* doc/lispref/display.texi (Displaying Messages)
* doc/lispref/strings.texi (Formatting Strings): Describe binding
text-quoting-style to nil to inhibit unwanted quote translation.
* doc/lispref/help.texi (Keys in Documentation): Change text-quoting-style
from a variable to a user option. Describe its changed set of values. State
that it can be customized freely.
Change 'text-quoting-style' so that it no longer affects
formatting of curved quotes in format arguments to functions like
'message'. In particular, when this variable's value is 'grave',
all quotes in formats are output as-is.
* doc/lispref/help.texi (Keys in Documentation):
* doc/lispref/strings.texi (Formatting Strings):
* doc/lispref/tips.texi (Documentation Tips):
* etc/NEWS:
* src/doc.c (syms_of_doc): Document this.
* lisp/help-fns.el (describe-function-1):
* src/doc.c (text_quoting_style, Fsubstitute_command_keys)
(syms_of_doc):
* src/editfns.c (styled_format): Omit now-unnecessary code.
* src/lisp.h (LEAVE_QUOTING_STYLE): Remove.
* doc/emacs/text.texi, doc/lispintro/emacs-lisp-intro.texi:
* doc/lispref/control.texi, doc/lispref/display.texi:
* doc/lispref/help.texi, doc/lispref/strings.texi, lisp/subr.el:
* src/callint.c, src/doprnt.c, src/editfns.c:
Document quoting a bit more systematically.
Problem reported by Alan Mackenzie (Bug#23425).
The manuals often used quotes ``...'' when it is better to use @dfn or
@code or capitalized words or no quoting at all. For example, there is
no need for the `` and '' in “if a variable has one effect for
@code{nil} values and another effect for ``non-@code{nil}'' values”.
Reword the Emacs, Lisp intro, and Lisp reference manuals to eliminate
unnecessary quoting like this, and to use @dfn etc. instead when called
for (Bug#21472).
This attempts to fix a problem reported by Alan Mackenzie in:
http://lists.gnu.org/archive/html/emacs-devel/2015-09/msg00112.html
* doc/lispref/display.texi (Active Display Table):
Mention how text-quoting-style affects it.
* doc/lispref/help.texi (Keys in Documentation):
Say how to set text-quoting-style in ~/.emacs.
* etc/NEWS: Document the change.
* lisp/startup.el (startup--setup-quote-display):
Follow user preference if text-quoting-style is set.
(command-line): Setup quote display again if user expresses
a preference in .emacs.
This is simpler and easier to explain, and should encourage better
typography. Do this in Electric Quote mode and when translating
quotes in docstrings. Inspired by a suggestion by Dmitry Gutov in:
https://lists.gnu.org/archive/html/emacs-devel/2015-08/msg00806.html
* doc/emacs/text.texi (Quotation Marks):
* doc/lispref/help.texi (Keys in Documentation):
* etc/NEWS:
Document this.
* lisp/electric.el (electric-quote-post-self-insert-function):
* src/doc.c (Fsubstitute_command_keys):
Always treat ' like ’ even when not matched by an open quote.
This is a followup to the recent doc string change, and deals with
diagnostics and the like. This patch is more conservative than
the doc string change, in that the behavior of ‘format’ changes
only if its first arg contains curved quotes and the user prefers
straight or grave quotes. (Come to think of it, perhaps we should
be similarly conservative with doc strings too, but that can wait.)
The upside of this conservatism is that existing usage is almost
surely unaffected. The downside is that we'll eventually have to
change Emacs's format strings to use curved quotes in places where
the user might want curved quotes, but that's a simple and
mechanical translation that I'm willing to do later. (Bug#21222)
* doc/lispref/help.texi (Keys in Documentation):
Move description of text-quoting-style from here ...
* doc/lispref/strings.texi (Formatting Strings):
... to here, and describe new behavior of ‘format’.
* etc/NEWS: Describe new behavior.
* lisp/calc/calc-help.el (calc-describe-thing):
* lisp/emacs-lisp/derived.el (derived-mode-make-docstring):
* lisp/info.el (Info-find-index-name):
Use ‘concat’ rather than ‘format’ to avoid misinterpretation
of recently-added curved quotes.
* src/doc.c (uLSQM0, uLSQM1, uLSQM2, uRSQM0, uRSQM1, uRSQM2):
Move from here ...
* src/lisp.h: ... to here.
* src/doc.c (text_quoting_style): New function.
(Fsubstitute_command_keys): Use it.
* src/editfns.c (Fformat): Implement new behavior.
* src/lisp.h (enum text_quoting_style): New enum.
Rename help-quote-translation to text-quoting-style,
and use symbols rather than characters as values.
This follows suggestions along these lines by Alan Mackenzie in:
http://lists.gnu.org/archive/html/emacs-devel/2015-06/msg00343.html
and by Drew Adams in:
http://lists.gnu.org/archive/html/emacs-devel/2015-08/msg00048.html
* doc/lispref/help.texi (Keys in Documentation)
* etc/NEWS:
* lisp/cus-start.el (standard):
* src/doc.c (Fsubstitute_command_keys, syms_of_doc):
Document and/or implement the new behavior instead of the old.
(syms_of_doc): New symbols 'grave' and 'straight'.
* doc/lispref/help.texi (Keys in Documentation):
* lisp/international/mule-cmds.el (set-locale-environment):
* lisp/term/w32console.el (terminal-init-w32console):
* src/doc.c (Fsubstitute_command_keys, Vhelp_quote_translation):
If ‘ is not displayable, transliterate it to `, not to '. See:
http://lists.gnu.org/archive/html/emacs-devel/2015-06/msg00542.html
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.
So, for example, it turns "`abc'" into "‘abc’" (Bug#20385).
* doc/lispref/help.texi (Keys in Documentation):
* etc/NEWS: Document this.
* src/doc.c (Fsubstitute_command_keys): Implement it.
doc/lispref/windows.texi (Recombining Windows): Index subject of sections.
doc/lispref/variables.texi (Variables with Restricted Values)
(Generalized Variables): Index subject of sections.
doc/lispref/text.texi (Buffer Contents, Examining Properties)
(Changing Properties, Property Search, Substitution): Index
subject of sections.
doc/lispref/syntax.texi (Motion and Syntax, Parsing Expressions)
(Motion via Parsing, Position Parse, Control Parsing): Index
subject of sections.
doc/lispref/strings.texi (Predicates for Strings, Creating Strings)
(Modifying Strings, Text Comparison): Index subject of sections.
doc/lispref/searching.texi (Syntax of Regexps, Regexp Special)
(Regexp Functions, Regexp Functions): Index subject of sections.
doc/lispref/processes.texi (Subprocess Creation, Process Information): Index
subject of sections.
doc/lispref/positions.texi (Screen Lines): Index subject of sections.
doc/lispref/nonascii.texi (Scanning Charsets, Specifying Coding Systems):
Index subject of sections.
doc/lispref/minibuf.texi (Text from Minibuffer, Object from Minibuffer)
(Multiple Queries, Minibuffer Contents): Index subject of
sections.
doc/lispref/markers.texi (Predicates on Markers, Creating Markers)
(Information from Markers, Moving Markers): Index subject of
sections.
doc/lispref/macros.texi (Defining Macros, Problems with Macros): Index
subject of sections.
doc/lispref/loading.texi (Loading Non-ASCII, Where Defined): Index subject
of sections.
doc/lispref/lists.texi (List-related Predicates, List Variables, Setcar)
(Setcdr, Plist Access): Index subject of sections.
doc/lispref/keymaps.texi (Controlling Active Maps, Scanning Keymaps)
(Modifying Menus): Index subject of sections.
doc/lispref/help.texi (Accessing Documentation, Help Functions): Index
subject of sections.
doc/lispref/hash.texi (Hash Access): Index subject of sections.
doc/lispref/functions.texi (Core Advising Primitives)
(Advising Named Functions, Porting old advices): Index subject of
sections.
doc/lispref/frames.texi (Creating Frames, Initial Parameters)
(Position Parameters, Buffer Parameters, Minibuffers and Frames)
(Pop-Up Menus, Drag and Drop): Index subject of sections.
doc/lispref/files.texi (Visiting Functions, Kinds of Files)
(Unique File Names): Index subject of sections.
doc/lispref/display.texi (Refresh Screen, Echo Area Customization)
(Warning Variables, Warning Options, Delayed Warnings)
(Temporary Displays, Managing Overlays, Overlay Properties)
(Finding Overlays, Size of Displayed Text, Defining Faces)
(Attribute Functions, Displaying Faces, Face Remapping)
(Basic Faces, Font Lookup, Fontsets, Replacing Specs)
(Defining Images, Showing Images): Index subject of sections.
doc/lispref/debugging.texi (Debugging, Explicit Debug)
(Invoking the Debugger, Excess Open, Excess Close): Index subject
of sections.
doc/lispref/customize.texi (Defining New Types, Applying Customizations)
(Custom Themes): Index subject of sections.
doc/lispref/control.texi (Sequencing, Combining Conditions)
(Processing of Errors, Cleanups): Index subject of sections.
doc/lispref/compile.texi (Eval During Compile): Index subject of sections.
doc/lispref/commands.texi (Using Interactive, Distinguish Interactive)
(Command Loop Info, Classifying Events, Event Mod)
(Invoking the Input Method): Index subject of sections.
doc/lispref/buffers.texi (Buffer List, Buffer Gap): Index subject of sections.
doc/lispref/backups.texi (Making Backups, Numbered Backups, Backup Names)
(Reverting): Index subject of sections.
doc/lispref/abbrevs.texi (Abbrev Tables, Defining Abbrevs, Abbrev Files)
(Abbrev Expansion, Standard Abbrev Tables, Abbrev Properties)
(Abbrev Table Properties): Index subject of sections.
doc/lispref/os.texi (Time of Day, Time Conversion, Time Parsing)
(Time Calculations, Idle Timers): Index subject of sections.
* 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'.
