[elpa] externals/company 9108c62267 7/7: Merge pull request #1284 from yugaego/doc

[ELPA Syncer]

branch: externals/company
commit 9108c6226764b629e2834455adb466b42b092acf
Merge: 54cf6f8d09 245bc3d9f9
Author: Dmitry Gutov <dgutov@yandex.ru>
Commit: GitHub <noreply@github.com>

    Merge pull request #1284 from yugaego/doc
    
    User manual updates: Extend 'Package Backends' and fix typos
---
 doc/Makefile     |   2 +-
 doc/company.texi | 230 ++++++++++++++++++++++++++++++++++++++++++-------------
 2 files changed, 179 insertions(+), 53 deletions(-)

diff --git a/doc/Makefile b/doc/Makefile
index 7eb6ddad90..d6cb27a89b 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -17,7 +17,7 @@ install-info: company.info
        install-info --info-dir=${INFO_INSTALL_DIR} $^
 
 company.html/: \
-       HTML_CSS_URL ?= http://company-mode.github.io/stylesheets/stylesheet.css
+       HTML_CSS_URL ?= 
https://company-mode.github.io/stylesheets/stylesheet.css
        --css-ref=${HTML_CSS_URL}
 #      HTML_CSS_FILE ?= 
../../company-mode.github.com/stylesheets/stylesheet.css
 #      --css-include=${HTML_CSS_FILE}
diff --git a/doc/company.texi b/doc/company.texi
index 22f2cc8554..f16d2ce5c3 100644
--- a/doc/company.texi
+++ b/doc/company.texi
@@ -2,14 +2,16 @@
 @c %**start of header
 @setfilename company.info
 @settitle Company User Manual
-@set VERSION 0.9.14
+@set VERSION 0.9.14snapshot
+@set UPDATED 28 December 2021
 @documentencoding UTF-8
 @documentlanguage en
 @paragraphindent asis
 @c %**end of header
 
 @copying
-This user manual is for Company version @value{VERSION}.
+This user manual is for Company version @value{VERSION}
+@w{(@value{UPDATED})}.
 
 Copyright @copyright{} 2021 Free Software Foundation, Inc.
 
@@ -28,6 +30,7 @@ any later version published by the Free Software Foundation.
 @titlepage
 @title Company User Manual
 @subtitle for version @value{VERSION}
+@subtitle @value{UPDATED}
 @page
 @vskip 0pt plus 1filll
 @insertcopying
@@ -123,7 +126,7 @@ chosen for successful completion.  And each of the 
candidates contains
 the initially typed characters: either only at the beginning
 (so-called @dfn{prefix matches}), or also inside (@dfn{non-prefix
 matches}) of a candidate @footnote{A good starting point to learn
-about types of matches is to play with Emacs' user option
+about types of matches is to play with the Emacs's user option
 @code{completion-styles}.  For illustrations on how Company visualizes
 the matches, @pxref{Frontends}.}.
 
@@ -524,9 +527,8 @@ description characters (@pxref{Syntax Class 
Table,,,elisp}), or a
 predicate function.  By default, @code{company-auto-commit-chars} is
 set to the list of the syntax characters: @w{@code{(?\ ?\) ?.)}},
 which translates to the whitespaces, close parenthesis, and
-punctuation.  The particular convenience of
-@code{company-auto-commit-chars} is that they do not act as a trigger
-when they are a part of valid completion.
+punctuation.  The particular convenience of this user option values is
+they do not act as triggers when they are part of valid completion.
 @end defopt
 
 @subheading Hooks
@@ -920,13 +922,13 @@ The look of the preview is controlled by the following 
faces:
 @code{company-preview}, @code{company-preview-common}, and
 @code{company-preview-search}.
 
-@itemize @w{}
-@item
 @img{preview-light}
 
-@item
+@ifnothtml
+@sp 1
+@end ifnothtml
+
 @img{preview-dark}
-@end itemize
 
 @node Echo Frontends
 @section Echo Frontends
@@ -934,8 +936,8 @@ The look of the preview is controlled by the following 
faces:
 @cindex echo
 @cindex face
 @cindex company-echo
-The frontends listed in this section display information in the Emacs'
-echo area, @ref{Echo Area,,,emacs}.
+The frontends listed in this section display information in the
+Emacs's echo area, @ref{Echo Area,,,emacs}.
 
 @defun company-echo-metadata-frontend
 This frontend is a part of the predefined frontends set.  Its
@@ -988,7 +990,7 @@ the faces @w{@code{company-echo}} and 
@code{company-echo-common}.
 By default, when @emph{company-mode} is in action, a key binding
 @kbd{C-s} starts looking for matches to additionally typed characters
 among the displayed candidates.  When a search is initiated, an
-indicator @w{@samp{Search: CHARACTERS}} is shown in the Emacs' mode
+indicator @w{@samp{Search: CHARACTERS}} is shown in the Emacs's mode
 line.
 
 @kindex C-g
@@ -1063,16 +1065,19 @@ If @code{company-show-quick-access} is enabled, 
@emph{tooltip-} and
 (setq company-show-quick-access 'left)
 @end lisp
 
-@itemize @w{}
-@item
 @img{tooltip-quick-access}
 
-@item
+@ifnothtml
+@sp 1
+@end ifnothtml
+
 @img{echo-qa}
 
-@item
+@ifnothtml
+@sp 1
+@end ifnothtml
+
 @img{echo-strip-qa}
-@end itemize
 
 @cindex custom
 @cindex configure
@@ -1223,31 +1228,37 @@ The following sections give a short overview of the 
commonly used
 backends bundled with Company.  Each section is devoted to one of the
 roughly outlined groups of the backends.
 
-Some of the backends expose several user options for customization.
-To see the list of the user options, we suggest doing one of the
+Some of the backends expose user options for customization; a few of
+these options are introduced below.  For those who would like to fetch
+the full list of a backend's user options, we suggest doing one of the
 following:
 
 @itemize
 @item
-Execute command @code{M-x customize-group @key{RET} <backend-name>}.
+Execute command @w{@kbd{M-x customize-group @key{RET}
+<backend-name>}}.
 
 @item
-Open the source file of the backend and run @code{M-x occur @key{RET}
-^(defcustom}.
+Open the source file of the backend and run @w{@kbd{M-x occur
+@key{RET} ^(defcustom}}.
+
+@itemize @minus
+@item
+Optionally, search for the matches with @w{@kbd{M-x isearch @key{RET}
+(defcustom}}.
 @end itemize
 
-@node Symbol Names Completion
-@subsection Symbol Names Completion
+@end itemize
 
-A completion for symbol names typically assists programmers working
-with the source code.
+@node Code Completion
+@subsection Code Completion
 
 @defun company-capf
-In Emacs' world, the current tendency is to have the completion logic
-executed by @w{@code{completion-at-point-functions}} (@acronym{CAPF})
-implementations.  [Among the other things, this is what the popular
-packages that support language server protocol (@acronym{LSP}) also
-rely on.]
+In the Emacs's world, the current tendency is to have the completion
+logic provided by @w{@code{completion-at-point-functions}}
+(@acronym{CAPF}) implementations.  [Among the other things, this is
+what the popular packages that support language server protocol
+(@acronym{LSP}) also rely on.]
 
 Since @emph{company-capf} works as a bridge to the standard
 @acronym{CAPF} facility, it is probably the most often used and
@@ -1266,10 +1277,10 @@ For more details on @acronym{CAPF}, @ref{Completion in 
Buffers,,,elisp}.
 @end defun
 
 @defun company-dabbrev-code
-This backend works similarly to the Emacs built-in package
-@emph{dabbrev}, parsing completion candidates from the text in open
-buffer(s).  Internally, its based on the backend
-@emph{company-dabbrev} (@pxref{Natural Language Completion}).
+This backend works similarly to the built-in Emacs package
+@emph{dabbrev}, searching for completion candidates inside the
+contents of the open buffer(s).  Internally, its based on the backend
+@emph{company-dabbrev} (@pxref{Text Completion}).
 @end defun
 
 @defun company-keywords
@@ -1301,30 +1312,144 @@ Emacs' @acronym{CAPF} facility, therefore a user may 
consider
 switching to @emph{company-capf} backend.
 @end defun
 
-@node Natural Language Completion
-@subsection Natural Language Completion
+@node Text Completion
+@subsection Text Completion
 
 @defun company-dabbrev
-This backend works similarly to the Emacs built-in package
-@emph{dabbrev}, parsing completion candidates from the text entered
-into the open buffer(s).
+This backend works similarly to the built-in Emacs package
+@emph{dabbrev}, searching for completion candidates inside the
+contents of the open buffer(s).  It is one of the often used backends,
+and it has several interesting options for configuration.  Let's
+review a few of them.
+
+@defopt company-dabbrev-minimum-length
+This option sets the minimum length of a completion candidate to
+collect from the text.  The default value of @samp{4} is intended to
+prevent potential performance issues.  But in many scenarios, it may
+be acceptable to lower this value.  Note that this option also affects
+the behavior of the @emph{company-dabbrev-code} backend.
+
+@lisp
+(setq company-dabbrev-minimum-length 2)
+@end lisp
+@end defopt
+
+@defopt company-dabbrev-other-buffers
+By default, @emph{company-dabbrev} collects completion candidates from
+all not ignored buffers (see more on that below).  This behavior can
+be changed to collecting candidates from the current buffer only (by
+setting the value to @samp{nil}) or from the buffers with the same
+major mode:
+
+@lisp
+(setq company-dabbrev-other-buffers t)
+@end lisp
+@end defopt
+
+@defopt company-dabbrev-ignore-buffers
+The value of this option should be a regexp or a predicate function
+that can be used to match a buffer name.  The matched buffers are
+omitted from the search for completion candidates.
+@end defopt
+
+The last two options described here relate to handling uppercase and
+lowercase letters in completion candidates.  The illustrative examples
+given below can be reproduced in the @samp{*scratch*} buffer, with the
+word @samp{Enjoy} typed in, and with this initial setup:
+
+@lisp
+(setq-local company-backends '(company-dabbrev)
+            company-dabbrev-other-buffers nil
+            company-dabbrev-ignore-case nil
+            company-dabbrev-downcase nil)
+@end lisp
+
+@defopt company-dabbrev-ignore-case
+This user option controls whether the case is ignored when collecting
+completion candidates.  When the option is set to @code{nil},
+@samp{Enjoy} is suggested as a completion candidate for the typed
+@samp{Enj} letters, but not for @samp{enj}.  When the option is set to
+@code{t}, @samp{Enjoy} is suggested as a candidate for both @samp{Enj}
+and @samp{enj} input; note that @samp{enj} prefix is ``overwritten''
+by completing with the @samp{Enjoy} candidate.  The third, default,
+type of behavior solves this issue, keeping the case of the typed
+prefix (and still collecting candidates case-insensitively):
+
+@lisp
+(setq company-dabbrev-ignore-case 'keep-prefix)
+@end lisp
+
+Now we can type @samp{enj}, complete it with the suggested
+@samp{Enjoy}, and @emph{enjoy} the result.
+@end defopt
+
+@defopt company-dabbrev-downcase
+This user option controls whether completion candidates are down-cased
+before their display.  When the option is set to @code{nil}, no
+transformation is performed; in the environment described above,
+typing @samp{Enj} results in the candidate @samp{Enjoy} being
+suggested.  When the option is set to @code{t}, the down-cased
+candidate @samp{enjoy} is suggested.  By default, this option is set
+to @code{case-replace}, meaning taking a value of the Emacs's variable
+@code{case-replace} (@code{t} is the current default).
+@end defopt
+
 @end defun
 
+@sp 1
 @defun company-ispell
 This backend returns completion candidates collected by @emph{Ispell},
 a built-in Emacs package that performs spell-checking.
-@xref{Spelling,,Checking and Correcting Spelling,emacs}.
+@xref{Spelling,,Checking and Correcting Spelling,emacs}.  Note that
+@emph{Ispell} uses only one dictionary at a time (combining several
+dictionaries into one file is an accepted practice).  By default,
+@emph{company-ispell} suggests candidates from a dictionary specified
+by the Emacs's setting @code{ispell-complete-word-dict}.
+
+@defopt company-ispell-dictionary
+Optionally, set a file path for @emph{company-ispell} to use another
+dictionary.
+@end defopt
+
 @end defun
 
-@node File Paths Completion
-@subsection File Paths Completion
+@node File Name Completion
+@subsection File Name Completion
 
 @defun company-files
-This backend can be used to retrieve file paths completion candidates.
+This backend can be used to retrieve completion candidates for the
+absolute and relative paths in the directory structure of an operating
+system.  The behavior of the @emph{company-files} backend can be
+adjusted with the two user options.
+
+@defopt company-files-exclusions
+It may be desirable to exclude directories or files from the list of
+suggested completion candidates.  For example, someone's setup might
+look this way:
+
+@lisp
+(setq company-files-exclusions '(".git/" ".DS_Store"))
+@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
+@w{(@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 Templates Expansion
-@subsection Templates Expansion
+@node Template Expansion
+@subsection Template Expansion
 
 @cindex template
 @cindex expansion
@@ -1338,13 +1463,14 @@ their expansions.
 
 @defun company-tempo
 A backend for users of
-@uref{https://www.lysator.liu.se/~davidk/elisp/, Tempo}, a built-in
-Emacs package for creating and inserting (expanding) templates.
+@uref{https://www.lysator.liu.se/~davidk/elisp/, Tempo}, one more
+built-in Emacs package for creating and inserting (expanding)
+templates.
 @end defun
 
 @defun company-yasnippet
-Used as a completion backend for a third-party template system
-@uref{https://github.com/joaotavora/yasnippet, YASnippet}.
+Used as a completion backend for the popular third-party template
+system @uref{https://github.com/joaotavora/yasnippet, YASnippet}.
 @end defun
 
 @node Candidates Post-Processing
@@ -1423,7 +1549,7 @@ issue to the corresponding third-party package 
maintainer(s).
 If the used backend is @samp{company-capf}, then take a look at the
 line starting with @samp{Value of c-a-p-f:}.  The issue could have
 been caused by a function listed there.  To identify to which package
-it belongs, type @w{@kbd{M-x find-function @key{RET} FUNCTION-NAME
+it belongs, type @w{@kbd{M-x find-function @key{RET} <function-name>
 @key{RET}}}.
 @end itemize