branch: externals/company
commit b58bc1a7f00e343124fcf75a24758d2253284893
Author: Dmitry Gutov <[email protected]>
Commit: Dmitry Gutov <[email protected]>
Update docs with latest changes
Touches on #1497, #1499, #1525, #1535, #1537, #1542
---
NEWS.md | 18 +++----
company-tng.el | 2 +-
doc/company.texi | 140 +++++++++++++++++++++++++++++++++++--------------------
3 files changed, 99 insertions(+), 61 deletions(-)
diff --git a/NEWS.md b/NEWS.md
index 284b346db30..233d7d06fc0 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -7,7 +7,7 @@
* `company-tooltip-width-grow-only` learned how to grow only up to particular
size (implemented in `company--create-lines`). The default value is 50.
* `company-childframe` gets enabled by default on NS/Mac/W32/PGTK systems, and
- on all others (notably X11 builds) when Emacs is at least 31
+ on all others (notably X11 builds) when Emacs is at least 31.1.
([#1542](https://github.com/company-mode/company-mode/pull/1542)).
* Default key bindings have been changed, moving `company-show-doc-buffer` and
`company-show-location` to `M-h` and `M-g` (from `C-h`/`<f1>` and `C-w`)
@@ -44,15 +44,15 @@
* The minimum required version of Emacs is now 26.1.
* `TAB` binding changed to `company-complete-common-or-cycle`, and `backtab`
binding to `company-cycle-backward`
- (#[1499](https://github.com/company-mode/company-mode/pull/1499)).
+ ([#1499](https://github.com/company-mode/company-mode/pull/1499)).
* Completion is restarted if it enters a new "field" at the end, as indicated
by
the `adjust-boundaries` backend action
- (#[1497](https://github.com/company-mode/company-mode/pull/1497)). This
+ ([#1497](https://github.com/company-mode/company-mode/pull/1497)). This
benefits file name (and directory) completion. The user option
`company-files-chop-trailing-slash` has been removed, and the
`post-completion` handler in `company-files` has been removed as well.
* Handle the case when the current c-a-p-f function changes mid-session
- (#[1494](https://github.com/company-mode/company-mode/pull/1494)).
+ ([#1494](https://github.com/company-mode/company-mode/pull/1494)).
# 2024-09-23 (1.0.2)
@@ -70,9 +70,9 @@
it queries `completion-try-completion`. `company-dabbrev-code` and
`company-etags` also do that when `completion-styles` support is enabled.
* `company-dabbrev-other-buffers` and `company-dabbrev-code-other-buffers` can
- now take a function as its value
(#[1485](https://github.com/company-mode/company-mode/issues/1485))
+ now take a function as its value
([#1485](https://github.com/company-mode/company-mode/issues/1485))
* Completion works in the middle of a symbol
- (#[1474](https://github.com/company-mode/company-mode/pull/1474)).
+ ([#1474](https://github.com/company-mode/company-mode/pull/1474)).
* New user option `company-inhibit-inside-symbols`. Set it to `t` to switch
closer to the previous behavior.
* Improved behavior when user types new character while completion is being
@@ -87,11 +87,11 @@
* `company-files` shows shorter completions. Previously, the popup spanned
the whole absolute file name being completed, and now it starts after the
nearest directory separator
- (#[1040](https://github.com/company-mode/company-mode/issues/1040)).
+ ([#1040](https://github.com/company-mode/company-mode/issues/1040)).
* New user option `company-capf-disabled-functions`
- (#[1437](https://github.com/company-mode/company-mode/issues/1437)).
+ ([#1437](https://github.com/company-mode/company-mode/issues/1437)).
* Better support for `yas-key-syntaxes`
- (#[1268](https://github.com/company-mode/company-mode/issues/1268)).
+ ([#1268](https://github.com/company-mode/company-mode/issues/1268)).
* New user option `company-tooltip-scrollbar-width` with default 0.4.
* The tooltip uses a more complex rendering approach, supporting double
width/CJK characters, as well as buffer text of different sizes
diff --git a/company-tng.el b/company-tng.el
index 6c279d5412c..1de8513b413 100644
--- a/company-tng.el
+++ b/company-tng.el
@@ -60,7 +60,7 @@
;; you can use the arrow keys or M-n/M-p to select and insert
;; candidates. You also need to decide which keys to unbind, depending
;; on whether you want them to do the Company action or the default
-;; Emacs action (for example C-s or C-w).
+;; Emacs action (for example C-s or M-g).
;;
;; We recommend to disable `company-require-match' to allow free typing at any
;; point.
diff --git a/doc/company.texi b/doc/company.texi
index 43df5399594..d709f340ec4 100644
--- a/doc/company.texi
+++ b/doc/company.texi
@@ -2,8 +2,8 @@
@c %**start of header
@setfilename company.info
@settitle Company User Manual
-@set VERSION 1.0.3-snapshot
-@set UPDATED 7 December 2024
+@set VERSION 1.1.0
+@set UPDATED 3 July 2026
@documentencoding UTF-8
@documentlanguage en
@paragraphindent asis
@@ -13,7 +13,7 @@
This user manual is for Company version @value{VERSION}
@w{(@value{UPDATED})}.
-Copyright @copyright{} 2021-2024 Free Software Foundation, Inc.
+Copyright @copyright{} 2021-2026 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@@ -246,6 +246,13 @@ To have Company always enabled for the following sessions,
add the
line @w{@code{(global-company-mode)}} to the Emacs configuration file
(@pxref{Init File,,,emacs}).
+@vindex company-global-minibuffer
+When @code{company-global-minibuffer} is non-nil (the default),
+Company can be used in the minibuffer as well. The necessary
+conditions are that a supported popup frontend is configured (any of
+@code{company-childframe-*-frontend}), and the minibuffer has a local
+value of @code{completion-at-point-functions}.
+
@node Usage Basics
@section Usage Basics
@@ -344,7 +351,22 @@ Insert the @emph{common part} of all completion candidates
or --- if
no @emph{common part} is present --- select the next candidate
(@code{company-complete-common-or-cycle}). In the latter case,
wraparound is implicitly enabled
-(@pxref{company-selection-wrap-around}).
+(@pxref{company-selection-wrap-around}). The @emph{common part}
+behavior can add characters before and after point, as decided by the
+backend's implementation.
+
+@item S-TAB
+@itemx <backtab>
+@kindex S-TAB
+@cindex cycle backwards
+@findex company-cycle-backward
+Select the previous candidate, with wraparound implicitly enabled.
+
+@item C-M-i
+@kindex C-M-i
+@cindex common part
+@findex company-complete-common
+Insert the @emph{common part} of all completion candidates.
@item C-g
@itemx <ESC ESC ESC>
@@ -357,19 +379,18 @@ wraparound is implicitly enabled
@findex company-abort
Cancel @emph{company-mode} activity (@code{company-abort}).
-@item C-h
-@itemx <F1>
-@kindex C-h
+@item M-h
+@kindex M-h
@cindex doc
@findex company-show-doc-buffer
Display a buffer with the documentation for the selected candidate
(@w{@code{company-show-doc-buffer}}). With a prefix argument
-(@kbd{C-u C-h}, @kbd{C-u @key{F1}}), this command toggles between
-temporary showing the documentation and keeping the documentation
-buffer up-to-date whenever the selection changes.
+(@kbd{C-u M-h}), this command toggles between temporary showing the
+documentation and keeping the documentation buffer up-to-date whenever
+the selection changes.
-@item C-w
-@kindex C-w
+@item M-g
+@kindex M-g
@cindex definition
@cindex location
@findex company-show-location
@@ -384,7 +405,6 @@ a more user-friendly output of the pre-defined key
bindings, utilize
@w{@kbd{M-x describe-keymap @key{RET} company-active-map}} or @w{@kbd{C-h
f @key{RET} company-mode}}.}.
-@findex company-complete-common
@findex company-indent-or-complete-common
@findex company-complete
Moreover, Company is bundled with a number of convenience commands
@@ -601,20 +621,26 @@ quick-accessed.
@cindex tooltip
@cindex pop-up
-This group of frontends displays completion candidates in an overlayed
-tooltip (aka @w{pop-up}). Company provides three @emph{tooltip
-frontends}, listed below.
+This group of frontends displays completion candidates in a
+rectangular tooltip (aka @w{pop-up}). Company provides multiple
+@emph{tooltip frontends}, listed below.
+
+The ``pseudo-tooltip'' family of frontends uses ``overlays'' (a
+display engine feature) to render the popup inside the buffer. It
+has a very stable and fast implementation, with known limitations:
+buffers with mixed fonts, complex formatting, some complex glyphs, and
+being limited to the bounds of the buffer's window.
@defun company-pseudo-tooltip-unless-just-one-frontend
-This is one of the default frontends. It starts displaying a tooltip
-only if more than one completion candidate is available, which nicely
-combines --- and it is done so by default --- with
+This has been the most frequently used frontend. It starts displaying
+a tooltip only if more than one completion candidate is available,
+which nicely combines --- and it is done so by default --- with
@code{company-preview-if-just-one-frontend}, @ref{Preview Frontends}.
@end defun
@defun company-pseudo-tooltip-frontend
This frontend outputs a tooltip for any number of completion
-candidates.
+candidates. It's the basic version that related frontends build on.
@end defun
@defun company-pseudo-tooltip-unless-just-one-frontend-with-delay
@@ -646,6 +672,27 @@ following example:
@end lisp
@end defun
+The ``childframe'' family of frontends uses graphical elements to show
+the popup above the buffer. It can cross window boundaries and be
+used in the minibuffer. On some ports it's implemented using X11
+child windows, and uses native widgets on others. It has been slowert
+han the overlay-based ones historically, but the gap has narrowed
+lately.
+
+@defun company-childframe-unless-just-one-frontend
+This is one of the default frontends (except with X11 and Emacs<31.1).
+It starts displaying its graphical tooltip only if more than one
+completion candidate is available, which nicely combines --- and it is
+done so by default --- with
+@code{company-preview-if-just-one-frontend}, @ref{Preview Frontends}.
+@end defun
+
+@defun company-childframe-frontend
+This frontend displays its graphical tooltip for any number of
+completion candidates. It's the basic version that related frontends
+build on.
+@end defun
+
@subheading User Options
@macro img{name}
@@ -756,27 +803,26 @@ top-to-bottom.)
@defopt company-tooltip-minimum-width
Sets the minimum width of a tooltip, excluding the margins and the
scroll bar. Changing this value especially makes sense if the user
-navigates between tooltip pages. Keeping this value at the default
-@code{0} allows Company to always adapt the width of the tooltip to
-the longest shown candidate. Enlarging
-@code{company-tooltip-minimum-width} prevents possible significant
-shifts in the width of the tooltip when navigating to the
-next/previous tooltip page. (For an alternate solution, see
-@code{company-tooltip-width-grow-only}.)
+navigates between tooltip pages. The default value of @code{15} helps
+reduce how often the tooltip's size changes when you are typing or
+paging. Set it to a higher value to limit the resizes further. Or
+vice versa to @code{0} to always adapt to the longest shown candidate.
+And see the related option @code{company-tooltip-width-grow-only}.
@end defopt
@defopt company-tooltip-width-grow-only
-This is another way to restrict auto-adaptation of the tooltip width
-(another is by adjusting @code{company-tooltip-minimum-width} value)
-when navigating between the tooltip pages.
+This is another way to reduce how often the tooltip resizes (in
+addition to @code{company-tooltip-minimum-width}), prohibiting
+reducing the width within one completion session when this option is
+non-nil. And when the value is a number, this is the maximum width up
+to which the non-shrink behavior has effect. The default value is
+@code{50}.
@end defopt
@defopt company-tooltip-maximum-width
This user option controls the maximum width of the tooltip inner area.
-By default, its value is pseudo-limitless, potentially permitting the
-output of extremely long candidates. But if long lines become an
-issue, set this option to a smaller number, such as @code{60} or
-@code{70}.
+By default, its value is @code{100}. Change it to allow different
+limits.
@end defopt
@defopt company-tooltip-margin
@@ -912,7 +958,7 @@ customization:
((t (:background "ivory" :foreground "MistyRose3"))))
'(company-tooltip-selection
((t (:background "LemonChiffon1" :foreground "MistyRose4"))))
- '(company-tooltip-common ((t (:weight bold :foreground "pink1"))))
+ '(company-toolti p-common ((t (:weight bold :foreground "pink1"))))
'(company-scrollbar-fg ((t (:background "ivory3"))))
'(company-scrollbar-bg ((t (:background "ivory2"))))
'(company-tooltip-annotation ((t (:foreground "MistyRose2")))))
@@ -1039,8 +1085,9 @@ To quit the search mode, hit @kbd{C-g}.
@defopt company-search-regexp-function
The value of this user option must be a function that interprets the
search input. By default it is set to the function
-@code{regexp-quote}, with looks for an exact match. Company defines
-several more functions suitable for this option. They are listed below.
+@code{company-search-words-in-any-order-regexp}, which looks for
+matching words in any order. Company defines several more functions
+suitable for this option. They are listed below.
@end defopt
@defun company-search-words-regexp
@@ -1055,6 +1102,11 @@ Searches for words separated with spaces in any order.
Searches for characters in the given order, with anything in between.
@end defun
+@defun company-search-flex-words-in-any-order-regexp
+Searches for words separated with spaces in any order, with anything
+in between the characters of each word.
+@end defun
+
@cindex custom
@cindex configure
@cindex interface
@@ -1555,20 +1607,6 @@ look this way:
@end lisp
@end defopt
-@defopt company-files-chop-trailing-slash
-This setting is enabled by default, which results in stripping off a
-trailing slash from an inserted directory name. On typing a trailing
-slash, the process of completion gets started again, from inside the
-just inserted directory.
-
-Setting @w{@code{company-files-chop-trailing-slash}} to @code{nil}
-makes directory names to be inserted as is, with a trailing slash. In
-this case, the completion process can be continued, for example,
-either by explicitly calling @emph{company-files} backend
-(@pxref{Backends Usage Basics}) or by starting typing a name of a
-file/directory known to be located under the inserted directory.
-@end defopt
-
@end defun
@node Template Expansion
