108 lines
4.7 KiB
Org Mode
108 lines
4.7 KiB
Org Mode
#+TITLE: ui/ligatures
|
|
#+DATE: June 16, 2018
|
|
#+SINCE: v2.0.9
|
|
#+STARTUP: inlineimages nofold
|
|
|
|
* Table of Contents :TOC_3:noexport:
|
|
- [[#description][Description]]
|
|
- [[#maintainers][Maintainers]]
|
|
- [[#module-flags][Module Flags]]
|
|
- [[#font-ligatures-module-flags][Font ligatures module flags]]
|
|
- [[#plugins][Plugins]]
|
|
- [[#prerequisites][Prerequisites]]
|
|
- [[#mutsuharus-emacs-mac-port-or-emacs-28-with-harfbuzz-support][Mutsuharu's emacs-mac port or Emacs 28+ with Harfbuzz support]]
|
|
- [[#not-emacs-mac-and-emacs--27][Not Emacs-mac and Emacs <= 27]]
|
|
- [[#features][Features]]
|
|
- [[#mathematical-symbols-replacement][Mathematical symbols replacement]]
|
|
- [[#coding-ligatures][Coding ligatures]]
|
|
- [[#configuration][Configuration]]
|
|
- [[#set-ligatures][~set-ligatures!~]]
|
|
- [[#troubleshooting][Troubleshooting]]
|
|
|
|
* Description
|
|
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.
|
|
|
|
** Module Flags
|
|
+ =+extra= Enables extra symbol substitutions in certain modes, for example
|
|
~lambda~ in lisps are replaced with ~λ~.
|
|
|
|
*** Font ligatures module flags
|
|
This module provides four flags for enabling fall-back ligature support for a
|
|
particular font. They are:
|
|
|
|
+ =+fira= Enables =Fira Code= ligatures. This requires Fira Code Symbol and a
|
|
patched version of Fira Code (see below).
|
|
+ =+hasklig= Enable =Hasklig= ligatures. This requires a patched version of the
|
|
HaskLig font (see below).
|
|
+ =+iosevka= Enable =Iosevka= ligatures. This requires a patched version of the
|
|
Iosevka font (see below).
|
|
+ =+pragmata-pro= Enable =Pragmata Pro= ligatures. This requires the [[https://www.fsd.it/shop/fonts/pragmatapro/][Pragmata
|
|
Pro font]].
|
|
|
|
#+begin_quote
|
|
All these 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
|
|
|
|
** Plugins
|
|
This module installs no packages.
|
|
|
|
* Prerequisites
|
|
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
|
|
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 Features
|
|
** 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 =+fira=, =+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
|
|
** TODO ~set-ligatures!~
|
|
|
|
* TODO Troubleshooting
|
|
# Common issues and their solution, or places to look for help.
|