4499ce7b0a
No font supports all of Unicode or anywhere near it. It’s not even really possible with current font formats. Therefore, rename `doom-unicode-font` to `doom-symbol-font`. Only set it as a fallback for characters in the `symbol` and `mathematical` scripts.
260 lines
8.8 KiB
Org Mode
260 lines
8.8 KiB
Org Mode
#+title: :ui ligatures
|
||
#+subtitle: Distract folks from your code
|
||
#+created: June 16, 2018
|
||
#+since: 21.12.0
|
||
|
||
* Description :unfold:
|
||
* Table of Contents :TOC_3:noexport:
|
||
- [[#description][Description]]
|
||
- [[#maintainers][Maintainers]]
|
||
- [[#module-flags][Module flags]]
|
||
- [[#packages][Packages]]
|
||
- [[#hacks][Hacks]]
|
||
- [[#changelog][Changelog]]
|
||
- [[#installation][Installation]]
|
||
- [[#usage][Usage]]
|
||
- [[#mathematical-symbols-replacement][Mathematical symbols replacement]]
|
||
- [[#coding-ligatures][Coding ligatures]]
|
||
- [[#details][Details]]
|
||
- [[#configuration][Configuration]]
|
||
- [[#symbol-replacements-λ-for-lambda][Symbol replacements (λ for "lambda"...)]]
|
||
- [[#font-ligatures-turning--into-an-arrow][Font ligatures (turning "=>" into an arrow...)]]
|
||
- [[#setting-ligatures-for-specific-font-or-major-mode][Setting ligatures for specific font or major mode]]
|
||
- [[#overwriting-all-default-ligatures][Overwriting all default ligatures]]
|
||
- [[#troubleshooting][Troubleshooting]]
|
||
- [[#some-symbols-are-not-rendering-correctly][Some symbols are not rendering correctly]]
|
||
- [[#frequently-asked-questions][Frequently asked questions]]
|
||
- [[#appendix][Appendix]]
|
||
|
||
** Maintainers
|
||
- [[doom-user:][@gagbo]]
|
||
|
||
[[doom-contrib-maintainer:][Become a maintainer?]]
|
||
|
||
** Module flags
|
||
- +extra ::
|
||
Enables extra symbol substitutions in certain modes, for example ~lambda~ in
|
||
lisps are replaced with ~λ~.
|
||
|
||
** Packages
|
||
- [[https://github.com/mickeynp/ligature.el][ligature.el]] (on Emacs 28+ with Harfbuzz)
|
||
|
||
** Hacks
|
||
/No hacks documented for this module./
|
||
|
||
** TODO Changelog
|
||
# This section will be machine generated. Don't edit it by hand.
|
||
/This module does not have a changelog yet./
|
||
|
||
* Installation
|
||
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
|
||
|
||
This module requires one of three setups for ligatures to work:
|
||
|
||
- A recent enough version of Emacs which will compose ligatures automatically
|
||
(Emacs 28 with Harfbuzz support), or
|
||
- Mitsuharu's =emacs-mac= build on macOS (available on Homebrew), or
|
||
- A patched font for Doom's fallback ligature support.
|
||
|
||
/This module does not have specific installation instructions/
|
||
|
||
~doom doctor~ will tell you if the module is incompatible with your current
|
||
Emacs version, and what you can do to remediate.
|
||
|
||
* Usage
|
||
#+begin_quote
|
||
/This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
||
#+end_quote
|
||
|
||
** Mathematical symbols replacement
|
||
If you want to set symbol replacements for modules that don't have them by
|
||
default you can use the ~set-ligatures!~ function in your config.el file
|
||
#+BEGIN_SRC emacs-lisp
|
||
(after! PACKAGE
|
||
(set-ligatures! 'MAJOR-MODE
|
||
:symbol "keyword"))
|
||
#+end_src
|
||
|
||
E.g.
|
||
#+begin_src emacs-lisp
|
||
(after! go-mode ; in this case the major mode and package named the same thing
|
||
(set-ligatures! 'go-mode
|
||
:def "func" ; function keyword
|
||
:true "true" :false "false"
|
||
; this will replace not only definitions
|
||
; but coresponding functions aswell
|
||
:int "int" :str "string"
|
||
:float "float" :bool "bool"
|
||
:for "for"
|
||
:return "return" :yield "yield"))
|
||
#+end_src
|
||
|
||
You can set these symbols out of the box:
|
||
#+begin_src emacs-lisp
|
||
(set-ligatures! 'MAJOR-MODE
|
||
;; Functional
|
||
:lambda "lambda keyword"
|
||
:def "function keyword"
|
||
:composition "composition"
|
||
:map "map/dictionary keyword"
|
||
;; Types
|
||
:null "null type"
|
||
:true "true keyword"
|
||
:false "false keyword"
|
||
:int "int keyword"
|
||
:float "float keyword"
|
||
:str "string keyword"
|
||
:bool "boolean keyword"
|
||
:list "list keyword"
|
||
;; Flow
|
||
:not "not operator"
|
||
:in "in operator"
|
||
:not-in "not in operator"
|
||
:and "and keyword"
|
||
:or "or keyword"
|
||
:for "for keyword"
|
||
:some "some keyword"
|
||
:return "return"
|
||
:yield "yeild"
|
||
;; Other
|
||
:union "Union keyword"
|
||
:intersect "Intersect keyword"
|
||
:diff "diff keyword"
|
||
:tuple "Tuple Keyword "
|
||
:pipe "Pipe Keyword"
|
||
:dot "Dot operator")
|
||
#+end_src
|
||
|
||
If you have multiple versions of the same keyword you can set the symbol twice:
|
||
#+begin_src emacs-lisp
|
||
(set-ligatures! scala-mode
|
||
:null "none"
|
||
:null "None")
|
||
#+end_src
|
||
|
||
|
||
** Coding ligatures
|
||
This module includes configuration to compose combinations like =->= or =::=
|
||
into prettier glyphs (called a ligature), specific for your font, or specific
|
||
for the major modes that you want to use.
|
||
|
||
As these ligatures come from the font itself instead of elisp symbols, we use
|
||
=set-font-ligatures!=
|
||
|
||
#+begin_src elisp
|
||
(set-font-ligatures! '(haskell-mode clojure-mode) ">>=" ">>-")
|
||
#+end_src
|
||
|
||
*** Details
|
||
Ligatures are implemented using a **composition-function-table** method: regexps are
|
||
used to match all the usual sequences which are composed into ligatures. These
|
||
regexps are passed to emacs directly, which asks Harfbuzz to shape it. Ligatures
|
||
are obtained automatically depending on the capabilities of the font, and no
|
||
font-specific configuration is necessary.
|
||
|
||
Emacs-mac port implements the same method natively in [[https://bitbucket.org/mituharu/emacs-mac/src/26c8fd9920db9d34ae8f78bceaec714230824dac/lisp/term/mac-win.el?at=master#lines-345:805][its code]], nothing is
|
||
necessary on Doom side; otherwise, Doom uses the [[https://github.com/mickeynp/ligature.el][ligature.el]] package that
|
||
implements this method for Emacs 28+ built with Harfbuzz support. Therefore, the
|
||
module will not work with Emacs 27 or previous.
|
||
|
||
Even though harfbuzz has been included in emacs 27, there is currently a
|
||
[[https://lists.gnu.org/archive/html/bug-gnu-emacs/2020-04/msg01121.html][bug
|
||
(#40864)]] which prevents a safe usage of the /composition-function-table/ method in
|
||
Emacs 27.
|
||
|
||
* Configuration
|
||
** Symbol replacements (λ for "lambda"...)
|
||
if you don't like the symbols chosen you can change them by using:
|
||
#+begin_src emacs-lisp
|
||
;; you don't need to include all of them you can pick and mix
|
||
(plist-put! +ligatures-extra-symbols
|
||
;; org
|
||
:name "»"
|
||
:src_block "»"
|
||
:src_block_end "«"
|
||
:quote "“"
|
||
:quote_end "”"
|
||
;; Functional
|
||
:lambda "λ"
|
||
:def "ƒ"
|
||
:composition "∘"
|
||
:map "↦"
|
||
;; Types
|
||
:null "∅"
|
||
:true "𝕋"
|
||
:false "𝔽"
|
||
:int "ℤ"
|
||
:float "ℝ"
|
||
:str "𝕊"
|
||
:bool "𝔹"
|
||
:list "𝕃"
|
||
;; Flow
|
||
:not "￢"
|
||
:in "∈"
|
||
:not-in "∉"
|
||
:and "∧"
|
||
:or "∨"
|
||
:for "∀"
|
||
:some "∃"
|
||
:return "⟼"
|
||
:yield "⟻"
|
||
;; Other
|
||
:union "⋃"
|
||
:intersect "∩"
|
||
:diff "∖"
|
||
:tuple "⨂"
|
||
:pipe ""
|
||
:dot "•") ;; you could also add your own if you want
|
||
#+end_src
|
||
|
||
** Font ligatures (turning "=>" into an arrow...)
|
||
*** Setting ligatures for specific font or major mode
|
||
As the [[https://github.com/mickeynp/ligature.el][README]] for ligature.el states, you can manipulate the ligatures that you
|
||
want to enable, specific for your font, or specific for the major modes that you
|
||
want to use. =set-font-ligatures!= is a thin wrapper around =ligature.el= to control these.
|
||
|
||
#+begin_src elisp
|
||
(set-font-ligatures! '(haskell-mode clojure-mode) ">>=" ">>-")
|
||
#+end_src
|
||
|
||
This call will:
|
||
- overwrite all preceding calls to =set-font-ligatures!=
|
||
for =haskell-mode= and =clojure-mode= specifically, but
|
||
- keep the inheritance to ligatures set for all modes, or parent modes like =prog-mode=
|
||
|
||
*** Overwriting all default ligatures
|
||
If you want to "start from scratch" and get control over all ligatures that
|
||
happen in all modes, you can use
|
||
|
||
#+begin_src elisp
|
||
;; Set all your custom ligatures for all prog-modes here
|
||
;; This section is *out of* the after! block
|
||
;; Example: only get ligatures for "==" and "===" in programming modes
|
||
;; by default, and get only "www" in all buffers by default.
|
||
(setq +ligatures-prog-mode-list '("==" "===")
|
||
+ligatures-all-modes-list '("www"))
|
||
;; Set any of those variables to nil to wipe all defaults.
|
||
|
||
;; Set all your additional custom ligatures for other major modes here.
|
||
;; Example: enable traditional ligature support in eww-mode, if the
|
||
;; `variable-pitch' face supports it
|
||
(set-font-ligatures! 'eww-mode "ff" "fi" "ffi")
|
||
#+end_src
|
||
|
||
* Troubleshooting
|
||
[[doom-report:][Report an issue?]]
|
||
|
||
** Some symbols are not rendering correctly
|
||
This can usually be fixed by doing one of the following:
|
||
|
||
- Set [[var:doom-symbol-font]].
|
||
- Disable the [[doom-module::ui unicode]] module. It overrides [[var:doom-symbol-font]]
|
||
and should only be used as a last resort.
|
||
|
||
* Frequently asked questions
|
||
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
|
||
|
||
* TODO Appendix
|
||
#+begin_quote
|
||
This module has no appendix yet. [[doom-contrib-module:][Write one?]]
|
||
#+end_quote
|