#+title:    :ui unicode
#+subtitle: Extended unicode support for various languages
#+created:  June 08, 2020
#+since:    2.0.0

* Description :unfold:
This module extends Doom's ability to display non-English unicode. It is
primarily useful for non-English Emacs users, for whom Doom's built-in unicode
support in insufficient.

This module relies on the [[https://github.com/rolandwalker/unicode-fonts][unicode-fonts]] package. It tries to setup the default
emacs fontset to cover as many unicode glyphs as possible by scanning all
available glyphs from all available fonts.

When this module is enabled:
- Emacs will prefer to use the ~doom-symbol-font~ font to display non-latin
  glyphs if it provides coverage for them.
- The first time you run Emacs a unicode cache will be generated -- this will
  take a while!
- The cache will be regenerated every time Emacs is made aware of new fonts or
  you change the font configuration e.g. by modifying ~doom-symbol-font~.
- The cache will be stored and should not be regenerated unless font-related
  configuration or the versions of relevant packages changes.

** Maintainers
*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]]

** Module flags
/This module has no flags./

** Packages
- [[doom-package:unicode-fonts]]

** 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 has no external requirements./

* TODO Usage
#+begin_quote
 󱌣 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote

* TODO Configuration
#+begin_quote
 󱌣 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

The first font that will be analyzed to see if it contains the glyphs of
non-latin characters will be ~doom-symbol-font~:
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(setq doom-symbol-font (font-spec :family "JuliaMono"))
#+end_src

If your ~doom-font~ provides good unicode coverage use:
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(setq doom-symbol-font doom-font)
#+end_src

If your font does not provide some glyphs, this package will try its best to
find another font that does.

** Getting fonts with good coverage
A list of fonts with good unicode coverage can be found on the page of the
[[https://github.com/rolandwalker/unicode-fonts#minimum-useful-fonts][unicode-fonts]] package.

** Advanced configuration
Consult the [[https://github.com/rolandwalker/unicode-fonts][unicode-fonts]] package documentation for a description of more
advanced configuration. The configuration should be placed, as usual, in
=$DOOMDIR/config.el= wrapped in an ~(after! unicode-fonts)~ block. The variable
~unicode-fonts-blocks~ contains a list of all unicode block names and their
character ranges. The default fonts to search for glyphs are in the variable
~unicode-fonts-block-font-mapping~.

If you want to use the font =Symbola= for =Miscellaneous Symbols= by default
use:
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(after! unicode-fonts
  (push "Symbola" (cadr (assoc "Miscellaneous Symbols" unicode-fonts-block-font-mapping))))
#+end_src

If you want to redefine several blocks an efficient way would be:
#+begin_src emacs-lisp
(after! unicode-fonts
  (dolist (unicode-block '("Mathematical Alphanumeric Symbols"
                           "Mathematical Operators"
                           "Miscellaneous Mathematical Symbols-A"
                           "Miscellaneous Mathematical Symbols-B"
                           "Miscellaneous Symbols"
                           "Miscellaneous Symbols and Arrows"
                           "Miscellaneous Symbols and Pictographs"))
      (push "DejaVu Math TeX Gyre" (cadr (assoc unicode-block unicode-fonts-block-font-mapping)))))
#+end_src

You can find a list of fonts available to emacs using ~M-x counsel-fonts~.

* Troubleshooting
[[doom-report:][Report an issue?]]

** TODO Emacs daemon mode ([[doom-ref:][#3328]])
This module may fail to setup fonts when emacs is run in a daemon session.

** Common error: ~void-variable \.\.\.~ ([[doom-ref:][#7164]])
Users for this module may see the error similar to:

#+begin_src
Debugger entered--Lisp error: (void-variable \.\.\.)
  (progn (set-fontset-font "fontset-default" '(64256 . 64335) (font-spec :name "Arial Unicode MS:" :registry "iso10646-1")) (set-fontset-font "fontset-default" '(65856 . 65935) (font-spec :name "Apple Symbols:" :registry "iso10646-1")) (set-fontset-font "fontset-default" '(1536 . 1791) (font-spec :name "Courier New:" :registry "iso10646-1")) (set-fontset-font "fontset-default" '(1536 . 1791) (font-spec :name "Geeza Pro:" :registry "iso10646-1") nil 'append) (set-fontset-font "fontset-default" '(1536 . 1791) (font-spec :name "Baghdad:" :registry "iso10646-1") nil 'append) (set-fontset-font "fontset-default" '(1536 . 1791) (font-spec :name "Damascus:" :registry "iso10646-1") nil 'append) (set-fontset-font "fontset-default" '(1536 . 1791) (font-spec :name "Al Bayan:" :registry "iso10646-1") nil 'append) (set-fontset-font "fontset-default" '(1536 . 1791) (font-spec :name "Arial Unicode MS:" :registry "iso10646-1") nil 'append) (set-fontset-font "fontset-default" '(1536 . 1791) (font-spec :name "Nadeem:" :registry "iso10646-1") nil 'append) \.\.\.)
  eval((progn (set-fontset-font "fontset-default" '(64256 . 64335) (font-spec :name "Arial Unicode MS:" :registry "iso10646-1")) (set-fontset-font "fontset-default" '(65856 . 65935) (font-spec :name "Apple Symbols:" :registry "iso10646-1")) (set-fontset-font "fontset-default" '(1536 . 1791) (font-spec :name "Courier New:" :registry "iso10646-1")) (set-fontset-font "fontset-default" '(1536 . 1791) (font-spec :name "Geeza Pro:" :registry "iso10646-1") nil 'append) (set-fontset-font "fontset-default" '(1536 . 1791) (font-spec :name "Baghdad:" :registry "iso10646-1") nil 'append) (set-fontset-font "fontset-default" '(1536 . 1791) (font-spec :name "Damascus:" :registry "iso10646-1") nil 'append) (set-fontset-font "fontset-default" '(1536 . 1791) (font-spec :name "Al Bayan:" :registry "iso10646-1") nil 'append) (set-fontset-font "fontset-default" '(1536 . 1791) (font-spec :name "Arial Unicode MS:" :registry "iso10646-1") nil 'append) (set-fontset-font "fontset-default" '(1536 . 1791) (font-spec :name "Nadeem:" :registry "iso10646-1") nil 'append) \.\.\.))
  unicode-fonts--setup-1("fontset-default" nil)
  unicode-fonts-setup()
#+end_src

This is a known issue with an unidentified cause. See
[[doom-ref:][rolandwalker/unicode-fonts#36]]. A workaround is to delete your
unicode-fonts cache and restart Emacs:
#+begin_src bash
# $EMACSDIR == where you cloned Doom Emacs
rm -f $EMACSDIR/.local/cache/pcache/unicode-fonts
#+end_src

* 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