d41cff489f
* module: add :input bidi Co-authored-by: Yoav Marco <yoavm448@gmail.com> * docs(bidi): flesh out README.org Co-authored-by: Itai Y. Efrat <itai3397@gmail.com> * feat(bidi): add +bidi-global-mode * docs(bidi): improve font setting instructions * feat(bidi): add +bidi-(hebrew|arabic)-font Since the Hebrew and Arabic unicode blocks cover the vast majority of RTL languages used today, we provide these fonts so end users don't have to bother with setting up the hooks themselves. * feat(bidi): add smart fontify Adds support for using the bidi fonts on surrounding whitespace and punctuation through. On by default, customizable through +bidi-want-smart-fontify and +bidi-smart-fontify-keywords. Also adds face versions of the bidi fonts. * docs(bidi): recommend known good nastaliq fonts * fix(bidi): re-set bidi faces after changing fonts * feat(bidi): add +bidi-paragraph-direction This allows users to choose what bidi-paragraph-direction is set to when +bidi-mode is on, so they can choose if they want per paragraph alignment (the default) or to force everything to be aligned RTL * docs(bidi): conform to verbatim/code conventions * docs(bidi): add font overview to Features * docs(bidi): warn on rtl forced alignment footgun +bidi-paragraph-direction is a nice variable to have if you primarily use +bidi-mode for rtl text buffers, but it shouldn't be used in conjunction with +bidi-global-mode since it messes up English buffers. Co-authored-by: Yoav Marco <yoavm448@gmail.com> |
||
|---|---|---|
| .. | ||
| config.el | ||
| README.org | ||
input/bidi
Description
This module improves support for bidi (bidirectional text). It should be enabled if you regularly write in languages that write right-to-left. It also provides some added configuration instructions in the README, since a lot of it is user specific.
Module Flags
This module provides no flags.
Plugins
This module provides no plugins.
Prerequisites
This module has no prerequisites.
Features
This module provides +bidi-mode, a minor mode that improves the display of RTL
text by right-aligning lines that start with an RTL language, on a per-line
basis. Since exact use cases vary, turning on this mode is left to the user.
It also provides easy font configuration for Hebrew and Arabic-derived scripts
(Arabic, Persian, Urdu, etc.) in +bidi-hebrew-font and +bidi-arabic-font.
See /emenel/doomemacs/src/commit/d41cff489f6d8ad326abcb2ccb53d716690b2c16/modules/input/bidi/Fonts for more information. If you use an RTL language that isn't covered by
these characters, open an issue requesting support for it.
Configuration
Using +bidi-mode
+bidi-mode is a local minor mode, meaning it has to be turned on a per-buffer
basis.
If you want to have it on for all buffers, use +bidi-global-mode:
;; ~/.doom.d/config.el
(+bidi-global-mode 1)If you only need it for specific purposes, e.g. editing LaTeX documents, you probably want to enable it through a hook:
(add-hook 'TeX-mode-hook #'+bidi-mode)
This is also useful for adding specific functionality for when +bidi-mode is on.
Force RTL text alignment
By default, +bidi-mode will align paragraphs by the first character with
strong directionality. If you want to force all paragraphs to be aligned
right-to-left when +bidi-mode is on, add the following to your config:
(setq +bidi-paragraph-direction 'right-to-left)
Warning: do not do this if you are using +bidi-global-mode, it will mess up
all of the buffers in Emacs that use English, including things like the M-x buffer.
Input Methods
If you need bidi support, it's likely that you want to easily switch between English and your favorite RTL language. In order to be able to do this without losing access to all of the keybindings require English letters, you should use input methods to switch languages instead of changing the system keyboard language. If you use a non-qwerty layout, you will need extra configuration to keep the input method consistent, see here for an example for dvorak.
Toggling the input method bound to C-\. It prompts you to choose an input
method the first time you do this in a session, but you bypass this by setting
the default input method:
(setq default-input-method "hebrew")Fonts
Many good English fonts do not have great coverage for RTL languages, especially
for Hebrew and monospace fonts. To this end, we provide +bidi-hebrew-font and
+bidi-arabic-font as an easy way to override the default fonts but only for
Hebrew and Arabic characters. They are set by default to DejaVu Sans, since
it has pretty decent looking Hebrew and Arabic characters.
Note, that if you are writing in an Arabic-derived script, such as Persian,
Urdu, or Pashto, you may want to change +bidi-arabic-font to one specific to
your language, especially if you want your script to be written in the Nastaliq
style.
If you use an RTL language the script of which isn't covered by the hebrew or
arabic unicode blocks, you can set a font override manually. For example:
(add-hook 'after-setting-font-hook
(lambda () (set-fontset-font t 'syriac (font-spec :family "DejaVu Sans"))))
Make sure to use the correct unicode block name, see the documentation of
set-fontset-font for more details.
Smart Fontify
Since good bidi fonts are often not monospace (as is the default DejaVu Sans),
It usually looks better to have the surrounding spaces and punctuation in the
use the bidi font as well. This is the default behaviour, but you can turn this
off by setting:
(setq +bidi-want-smart-fontify nil)Change Dictionary Language On Bidi Buffers
If you are only using +bidi-mode in specific buffers, you might want to
automatically change the dictionary language there. For example:
(add-hook! '+bidi-mode-hook
(if +bidi-mode
(ispell-change-dictionary "hebrew")
(ispell-change-dictionary "default")))