[elpa] externals/modus-operandi-theme 5b0cb43 118/153: Add note in manual about company-mode popup

[Stefan Monnier]

branch: externals/modus-operandi-theme
commit 5b0cb43861f4324a0e03675ca0a92b34374534ec
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Add note in manual about company-mode popup
    
    * doc/modus-themes.org (Note on company-mode overlay pop-up): Document
    the potential problem with using overlays to draw the pop-up with the
    completion candidates.   The solution is to use company-posframe.
    
    * doc/modus-themes.org (Acknowledgements): Add Iris Garcia to the list
    of contributors.  Helped confirm that the bug was in company-mode (per
    issue 96: https://gitlab.com/protesilaos/modus-themes/-/issues/96).
    
    * doc/modus-themes.info: Recompile manual.
---
 doc/modus-themes.info | 166 +++++++++++++++++++++++++++++---------------------
 doc/modus-themes.org  |  29 +++++++--
 2 files changed, 119 insertions(+), 76 deletions(-)

diff --git a/doc/modus-themes.info b/doc/modus-themes.info
index 14266da..5433edf 100644
--- a/doc/modus-themes.info
+++ b/doc/modus-themes.info
@@ -104,6 +104,7 @@ Face coverage
 
 Notes for individual packages
 
+* Note on company-mode overlay pop-up::
 * Note for ERC escaped colour sequences::
 * Note for powerline or spaceline::
 * Note on shr colours::
@@ -1648,6 +1649,7 @@ individual packages.
 
 * Menu:
 
+* Note on company-mode overlay pop-up::
 * Note for ERC escaped colour sequences::
 * Note for powerline or spaceline::
 * Note on shr colours::
@@ -1655,9 +1657,30 @@ individual packages.
 * Note on vc-annotate-background-mode::
 
 
-File: modus-themes.info,  Node: Note for ERC escaped colour sequences,  Next: 
Note for powerline or spaceline,  Up: Notes for individual packages
+File: modus-themes.info,  Node: Note on company-mode overlay pop-up,  Next: 
Note for ERC escaped colour sequences,  Up: Notes for individual packages
 
-7.1 Note for ERC escaped colour sequences
+7.1 Note on company-mode overlay pop-up
+=======================================
+
+By default, the ‘company-mode’ pop-up that lists completion candidates
+is drawn using an overlay.  This creates alignment issues every time it
+is placed above a piece of text that has a different height than the
+default.
+
+   The solution recommended by the project’s maintainer is to use an
+alternative front-end for drawing the pop-up which uses child frames
+instead of overlays.(1)(2)
+
+   ---------- Footnotes ----------
+
+   (1) <https://github.com/company-mode/company-mode/issues/1010>
+
+   (2) <https://github.com/tumashu/company-posframe/>
+
+
+File: modus-themes.info,  Node: Note for ERC escaped colour sequences,  Next: 
Note for powerline or spaceline,  Prev: Note on company-mode overlay pop-up,  
Up: Notes for individual packages
+
+7.2 Note for ERC escaped colour sequences
 =========================================
 
 The built-in IRC client ‘erc’ has the ability to colourise any text
@@ -1695,7 +1718,7 @@ Emacs: <https://www.mirc.com/colors.html>
 
 File: modus-themes.info,  Node: Note for powerline or spaceline,  Next: Note 
on shr colours,  Prev: Note for ERC escaped colour sequences,  Up: Notes for 
individual packages
 
-7.2 Note for powerline or spaceline
+7.3 Note for powerline or spaceline
 ===================================
 
 Both Powerline and Spaceline package users will likely need to use the
@@ -1705,7 +1728,7 @@ and/or modeline setup.
 
 File: modus-themes.info,  Node: Note on shr colours,  Next: Note for Helm 
grep,  Prev: Note for powerline or spaceline,  Up: Notes for individual packages
 
-7.3 Note on shr colours
+7.4 Note on shr colours
 =======================
 
 Emacs’ HTML rendering mechanism (‘shr’) may need explicit configuration
@@ -1715,7 +1738,7 @@ webpage provides.  Consult ‘C-h v shr-use-colors’.
 
 File: modus-themes.info,  Node: Note for Helm grep,  Next: Note on 
vc-annotate-background-mode,  Prev: Note on shr colours,  Up: Notes for 
individual packages
 
-7.4 Note for Helm grep
+7.5 Note for Helm grep
 ======================
 
 There is one face from the Helm package that is meant to highlight the
@@ -1745,7 +1768,7 @@ ANSI colour number 1 (red) from the already-supported 
array of
 
 File: modus-themes.info,  Node: Note on vc-annotate-background-mode,  Prev: 
Note for Helm grep,  Up: Notes for individual packages
 
-7.5 Note on vc-annotate-background-mode
+7.6 Note on vc-annotate-background-mode
 =======================================
 
 Due to the unique way ‘vc-annotate’ (‘C-x v g’) applies colours, support
@@ -1866,12 +1889,12 @@ Ideas and user feedback
      Shmalko, Anders Johansson, André Alexandre Gomes, Arif Rezai, Basil
      L.  Contovounisios, Damien Cassou, Dario Gjorgjevski, David
      Edmondson, Davor Rotim, Divan Santana, Gerry Agbobada, Gianluca
-     Recchia, Len Trigg, Manuel Uberti, Mark Burton, Markus Beppler,
-     Michael Goldenberg, Murilo Pereira, Nicolas De Jaeghere, Pierre
-     Téchoueyres, Ryan Phillips, Shreyas Ragavan, Tassilo Horn, Thibaut
-     Verron, Trey Merkley, Uri Sharf, Utkarsh Singh, Vincent Foley.  As
-     well as users: Ben, Fourchaux, Fredrik, Moesasji, Nick, TheBlob42,
-     dinko, doolio, jixiuf, okamsn, tycho garen.
+     Recchia, Iris Garcia, Len Trigg, Manuel Uberti, Mark Burton, Markus
+     Beppler, Michael Goldenberg, Murilo Pereira, Nicolas De Jaeghere,
+     Pierre Téchoueyres, Ryan Phillips, Shreyas Ragavan, Tassilo Horn,
+     Thibaut Verron, Trey Merkley, Uri Sharf, Utkarsh Singh, Vincent
+     Foley.  As well as users: Ben, Fourchaux, Fredrik, Moesasji, Nick,
+     TheBlob42, dinko, doolio, jixiuf, okamsn, tycho garen.
 
 Packaging
      Dhavan Vaidya (Debian), Stefan Kangas (core Emacs), Stefan Monnier
@@ -2390,64 +2413,67 @@ Appendix A GNU Free Documentation License
 
 Tag Table:
 Node: Top218
-Node: Overview3938
-Node: How do the themes look like5623
-Node: Installation6106
-Node: Install from the archives6756
-Node: Install on GNU/Linux7443
-Node: Debian 11 Bullseye7888
-Node: GNU Guix8297
-Node: Enable and load8648
-Node: Load automatically9225
-Node: Load at a given time or at sunset/sunrise10038
-Ref: Load at a given time or at sunset/sunrise-Footnote-112076
-Ref: Load at a given time or at sunset/sunrise-Footnote-212204
-Node: Toggle between the themes on demand12287
-Node: Configure options prior to loading13034
-Ref: Configure options prior to loading-Footnote-115630
-Node: Customisation Options15805
-Node: Bold constructs17549
-Node: Slanted constructs18548
-Node: Syntax highlighting19139
-Node: No mixed fonts19867
-Node: Link underline20915
-Node: Command prompts21397
-Node: Mode line22195
-Node: Completion UIs24632
-Node: Fringes26544
-Node: Line highlighting27308
-Node: Matching parentheses27976
-Node: Diffs28620
-Node: Org mode blocks30413
-Node: Heading styles31916
-Node: Scaled headings35305
-Node: Scaled heading sizes35922
-Node: Headings' font37881
-Node: Advanced customisation (do-it-yourself)38505
-Node: Tweak colours (DIY)39509
-Node: Font configs (DIY)43143
-Ref: Font configs (DIY)-Footnote-145723
-Ref: Font configs (DIY)-Footnote-245910
-Node: Org user faces (DIY)46132
-Node: Face coverage49353
-Node: Supported packages49855
-Node: Covered indirectly55864
-Node: Will NOT be supported56249
-Node: Notes for individual packages56967
-Node: Note for ERC escaped colour sequences57415
-Ref: Note for ERC escaped colour sequences-Footnote-158798
-Node: Note for powerline or spaceline58908
-Node: Note on shr colours59326
-Node: Note for Helm grep59739
-Node: Note on vc-annotate-background-mode61186
-Node: Contributing62040
-Node: Sources of the themes62459
-Node: Issues you can help with63221
-Node: Merge requests64408
-Node: Acknowledgements65490
-Node: Meta66760
-Node: External projects (ports)67952
-Node: GNU Free Documentation License68775
+Node: Overview3978
+Node: How do the themes look like5663
+Node: Installation6146
+Node: Install from the archives6796
+Node: Install on GNU/Linux7483
+Node: Debian 11 Bullseye7928
+Node: GNU Guix8337
+Node: Enable and load8688
+Node: Load automatically9265
+Node: Load at a given time or at sunset/sunrise10078
+Ref: Load at a given time or at sunset/sunrise-Footnote-112116
+Ref: Load at a given time or at sunset/sunrise-Footnote-212244
+Node: Toggle between the themes on demand12327
+Node: Configure options prior to loading13074
+Ref: Configure options prior to loading-Footnote-115670
+Node: Customisation Options15845
+Node: Bold constructs17589
+Node: Slanted constructs18588
+Node: Syntax highlighting19179
+Node: No mixed fonts19907
+Node: Link underline20955
+Node: Command prompts21437
+Node: Mode line22235
+Node: Completion UIs24672
+Node: Fringes26584
+Node: Line highlighting27348
+Node: Matching parentheses28016
+Node: Diffs28660
+Node: Org mode blocks30453
+Node: Heading styles31956
+Node: Scaled headings35345
+Node: Scaled heading sizes35962
+Node: Headings' font37921
+Node: Advanced customisation (do-it-yourself)38545
+Node: Tweak colours (DIY)39549
+Node: Font configs (DIY)43183
+Ref: Font configs (DIY)-Footnote-145763
+Ref: Font configs (DIY)-Footnote-245950
+Node: Org user faces (DIY)46172
+Node: Face coverage49393
+Node: Supported packages49895
+Node: Covered indirectly55904
+Node: Will NOT be supported56289
+Node: Notes for individual packages57007
+Node: Note on company-mode overlay pop-up57495
+Ref: Note on company-mode overlay pop-up-Footnote-158159
+Ref: Note on company-mode overlay pop-up-Footnote-258226
+Node: Note for ERC escaped colour sequences58281
+Ref: Note for ERC escaped colour sequences-Footnote-159708
+Node: Note for powerline or spaceline59818
+Node: Note on shr colours60236
+Node: Note for Helm grep60649
+Node: Note on vc-annotate-background-mode62096
+Node: Contributing62950
+Node: Sources of the themes63369
+Node: Issues you can help with64131
+Node: Merge requests65318
+Node: Acknowledgements66400
+Node: Meta67683
+Node: External projects (ports)68875
+Node: GNU Free Documentation License69698
 
 End Tag Table
 
diff --git a/doc/modus-themes.org b/doc/modus-themes.org
index 3b33ed5..55a42b2 100644
--- a/doc/modus-themes.org
+++ b/doc/modus-themes.org
@@ -1517,6 +1517,22 @@ and the intended styles for the content you are actually 
working on.
 This section covers information that may be of interest to users of
 individual packages.
 
+** Note on company-mode overlay pop-up
+:PROPERTIES:
+:CUSTOM_ID: h:20cef8c4-d11f-4053-8b2c-2872925780b1
+:END:
+
+By default, the =company-mode= pop-up that lists completion candidates is
+drawn using an overlay.  This creates alignment issues every time it is
+placed above a piece of text that has a different height than the
+default.
+
+The solution recommended by the project's maintainer is to use an
+alternative front-end for drawing the pop-up which uses child frames
+instead of overlays.[fn::
+https://github.com/company-mode/company-mode/issues/1010][fn::
+https://github.com/tumashu/company-posframe/]
+
 ** Note for ERC escaped colour sequences
 :PROPERTIES:
 :CUSTOM_ID: h:98bdf319-1e32-4469-8a01-771200fba65c
@@ -1704,12 +1720,13 @@ The Modus themes are a collective effort.  Every 
contribution counts.
   Alex Peitsinis, Alexey Shmalko, Anders Johansson, André Alexandre
   Gomes, Arif Rezai, Basil L. Contovounisios, Damien Cassou, Dario
   Gjorgjevski, David Edmondson, Davor Rotim, Divan Santana, Gerry
-  Agbobada, Gianluca Recchia, Len Trigg, Manuel Uberti, Mark Burton,
-  Markus Beppler, Michael Goldenberg, Murilo Pereira, Nicolas De
-  Jaeghere, Pierre Téchoueyres, Ryan Phillips, Shreyas Ragavan, Tassilo
-  Horn, Thibaut Verron, Trey Merkley, Uri Sharf, Utkarsh Singh, Vincent
-  Foley.  As well as users: Ben, Fourchaux, Fredrik, Moesasji, Nick,
-  TheBlob42, dinko, doolio, jixiuf, okamsn, tycho garen.
+  Agbobada, Gianluca Recchia, Iris Garcia, Len Trigg, Manuel Uberti,
+  Mark Burton, Markus Beppler, Michael Goldenberg, Murilo Pereira,
+  Nicolas De Jaeghere, Pierre Téchoueyres, Ryan Phillips, Shreyas
+  Ragavan, Tassilo Horn, Thibaut Verron, Trey Merkley, Uri Sharf,
+  Utkarsh Singh, Vincent Foley.  As well as users: Ben, Fourchaux,
+  Fredrik, Moesasji, Nick, TheBlob42, dinko, doolio, jixiuf, okamsn,
+  tycho garen.
 
 + Packaging :: Dhavan Vaidya (Debian), Stefan Kangas (core Emacs),
   Stefan Monnier (GNU Elpa).