emenel/doomemacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Update & reformat ui/pretty-code readme ToC

Browse source
This commit is contained in:
Henrik Lissner 2020-05-02 22:49:07 -04:00
parent bef3457232
commit 0edbf9cb04
No known key found for this signature in database
GPG key ID: 5F6C0EA160557395
1 changed files with 40 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

48
modules/ui/pretty-code/README.org
View file

@ -7,9 +7,15 @@
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#font-ligatures-module-flags][Font ligatures module flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#ligatures][Ligatures]]
- [[#emacs-mac-port-or-emacs-28][Emacs-mac port or Emacs 28+]]
- [[#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-pretty-symbols][~set-pretty-symbols!~]]
- [[#troubleshooting][Troubleshooting]]
@ -23,7 +29,10 @@ This module has no dedicated maintainers.
** Module Flags
*** Font ligatures module flags
Those flags are ignored on emacs-mac and on other platforms if running emacs 28+ with harfbuzz feature. In those cases, ligatures are handled without needing the extra configuration provided by those flags.
Those flags are ignored on emacs-mac and on other platforms if running emacs 28+
with harfbuzz feature. In those cases, ligatures are handled without needing the
extra configuration provided by those flags.
+ =+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
@ -38,10 +47,16 @@ This module installs no packages.
* Prerequisites
** Ligatures
For ligatures to work, you must either have a recent enough version of emacs which will compose ligatures automatically, or use the font specific configurations.
For ligatures to work, you must either:
- Have a recent enough version of Emacs which will compose ligatures
automatically, or
- Use one of our font-specific configurations.
*** Emacs-mac port or Emacs 28+
Ligatures are handled without needing additional configuration. If this doesn't work, report a bug with your current version of emacs and the ligatures which aren't working.
Ligatures are handled without needing additional configuration. If this doesn't
work, report a bug with your current version of emacs and the ligatures which
aren't working.
*** Not Emacs-mac and Emacs <= 27
1. Enable one of the four ligature font flags: =+fira=, =+hasklig=, =+iosevka=
@ -55,13 +70,30 @@ Ligatures are handled without needing additional configuration. If this doesn't
# An in-depth list of features, how to use them, and their dependencies.
** 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 :: regexes are used to match all the usual sequences which are composed into ligatures. These regexes 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.
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 :
Emacs-mac port implements the /composition-function-table/ method in 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.
- 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 :: regexes are used to match all the usual
sequences which are composed into ligatures. These regexes 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.
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.
Emacs-mac port implements the /composition-function-table/ method in 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
# How to configure this module, including common problems and how to address them.