1abcf913aa
emacs-straight/org-mode@e22b4eb7aa introduced a breaking change that made it impossible to rely on .dir-locals.el to change org-mode buffers in $EMACSDIR to doom-docs-org-mode (without infinite recursion), so we used file-local variables in7e400ab. emacs-straight/org-mode@215de6176b reverted that change, so we can use .dir-locals.el again, and this is my preference, since it requires less boilerplate across our hundreds of org files. Ref: emacs-straight/org-mode@215de6176b Ref: emacs-straight/org-mode@e22b4eb7aa Revert:7e400abdc0
238 lines
8.2 KiB
Org Mode
238 lines
8.2 KiB
Org Mode
#+title: :ui ligatures
|
||
#+subtitle: Distract folks from your code
|
||
#+created: June 16, 2018
|
||
#+since: 21.12.0
|
||
|
||
* Description :unfold:
|
||
This module enables ligatures and arbitrary symbol substitutions with
|
||
~mac-auto-operator-composition-mode~ (on supported macOS systems) or composition
|
||
tables (harfbuzz on Emacs 28), falling back on ~prettify-symbols-mode~
|
||
otherwise.
|
||
|
||
** Maintainers
|
||
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
|
||
|
||
** Module flags
|
||
- +extra ::
|
||
Enables extra symbol substitutions in certain modes, for example ~lambda~ in
|
||
lisps are replaced with ~λ~.
|
||
- +fira ::
|
||
Enable =Fira Code= ligatures. This requires Fira Code Symbol and [[id:a7e7402b-e202-4860-878b-d1933cff1d16][a patched
|
||
version of Fira Code]].
|
||
- +hasklig ::
|
||
Enable =Hasklig= ligatures. This requires [[id:a7e7402b-e202-4860-878b-d1933cff1d16][a patched version of the HaskLig
|
||
font]].
|
||
- +iosevka ::
|
||
Enable =Iosevka= ligatures. This requires [[id:a7e7402b-e202-4860-878b-d1933cff1d16][a patched version of the Iosevka
|
||
font]].
|
||
- +pragmata-pro ::
|
||
Enable =Pragmata Pro= ligatures. This requires the [[https://www.fsd.it/shop/fonts/pragmatapro/][Pragmata Pro font]].
|
||
|
||
#+begin_quote
|
||
🚧 Font flags are ignored _if_ you're sporting either a) Emacs 28+ with
|
||
Harfbuzz support (which can compose ligatures natively), or b) Mitsuharu's
|
||
=emacs-mac= build on macOS (which uses
|
||
~mac-auto-operator-composition-mode~).
|
||
#+end_quote
|
||
|
||
** Packages
|
||
/This module doesn't install any packages./
|
||
|
||
** 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.
|
||
|
||
** Mutsuharu's emacs-mac port or Emacs 28+ with Harfbuzz support
|
||
Ligatures should be handled without any additional configuration.
|
||
|
||
** Not Emacs-mac and Emacs <= 27
|
||
:PROPERTIES:
|
||
:ID: a7e7402b-e202-4860-878b-d1933cff1d16
|
||
:END:
|
||
1. Enable one of the four ligature font flags: =+fira=, =+hasklig=, =+iosevka=
|
||
or =+pragmata-pro=.
|
||
2. Install the patched version of the associated font with ~M-x
|
||
+ligatures/install-patched-font~. Note: Pragmata Pro cannot be installed this
|
||
way because it is a non-free font and must be purchased and installed
|
||
manually.
|
||
|
||
* TODO Usage
|
||
#+begin_quote
|
||
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
||
#+end_quote
|
||
|
||
** TODO Mathematical symbols replacement
|
||
|
||
** Coding ligatures
|
||
This module includes configuration to compose combinations like =->= or =::=
|
||
into prettier glyphs (called a ligature). Depending on the current version of
|
||
emacs, this is implemented in two different ways :
|
||
|
||
- prettify-symbols-mode method :: this is the "legacy" method. It uses a font
|
||
which haves the ligatures as separate unicode symbols, and using
|
||
prettify-symbols-mode, =->=-like combinations are manually listed and replaced
|
||
with the correct symbol. The mapping between =->=-like sequences and unicode
|
||
values in the font are font-specific ; therefore [[doom-module:][+fira]], [[doom-module:][+iosevka]]... files and
|
||
specific fonts are necessary for it to work.
|
||
- 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 /composition-function-table/ method 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 implements the
|
||
/composition-function-table/ for emacs 28+ built with Harfbuzz support, and the
|
||
/prettify-symbols-mode/ method otherwise.
|
||
|
||
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 /composition-function-table/ method in
|
||
emacs 27.
|
||
|
||
* TODO Configuration
|
||
#+begin_quote
|
||
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
|
||
#+end_quote
|
||
|
||
** Setting ligatures
|
||
If you want to set ligatures for modules that don't have them by default you can
|
||
use the ~set-ligatures!~ macro:
|
||
#+begin_src emacs-lisp
|
||
;; in $DOOMDIR/config.el
|
||
(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" :yeild "yeild"))
|
||
#+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 keywork"
|
||
: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" ;; FIXME: find a non-private char
|
||
: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
|
||
|
||
** Changing ligatures
|
||
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 "" ;; FIXME: find a non-private char
|
||
:dot "•") ;; you could also add your own if you want
|
||
#+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:
|
||
|
||
- Make sure Symbola (the font) is installed on your system.
|
||
- Otherwise, change [[var:][doom-unicode-font]] (set to Symbola by default).
|
||
- Disable the [[doom-module:][:ui unicode]] module. It not only overrides [[var:][doom-unicode-font]], but
|
||
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
|