Arabic Roots: The Power of Patterns
Image credit: “Holy Karbala street signage” by أخٌ‌في‌الله, Unsplash License.
Ξ
I want to quickly introduce the Arabic language, through its “root system” —i.e., most words have 3-letters at their core— and how these roots can be placed in “patterns” to obtain new words.
I'd like to take a glance at Arabic's Verb Forms: These give you 10 words for each root!
Some interesting concepts will also be mentioned, for those curious, but should be ignored on a first reading. These will be hidden away in clickable/foldable regions.
These are notes of things that I'm learning; there's likely errors.
1. The Arabic Root System
Most Arabic words are derived from a three-letter root
The Arabic language is based on “roots” that link words of related meanings.
An Arabic “root” is the sequence of (usually 3) Arabic letters that carry the underlying meaning of a word, for example
ش−ر−ب “to drink” and ح−م−ل “to carry”.
Vowels and consonants are added around the roots to create related words.
Roots are the building blocks of the Arabic language and are helpful for guessing the meaning of vocabulary.
Generally foreign loan words, such as internet انترنت, fall outside the root system.
For more, see www.alhassy.com/arabic-roots
For example, the sequence of letters س−ف−ر (read right-to-left as s-f-r) carries the meaning of “travel”. Any word containing these letters, in this order, likely has something to do with travel. For example:
| English | Arabic | Transliteration |
|---|---|---|
| journey | سفر | safar |
| he travels | يسافر | yusafir |
| amabassdor | سفير | safeer |
| traveller | مسافر | musafir |
| embassy | سفارة | sifara |
All of these words are derived from the root س−ف−ر, s-f-r, in this order.
Much of Arabic grammar is concerned with how the root is manipulated to create different related meanings:
Additional letters, or vowels, modify the meaning according to different general patterns.
Likewise, ك−ت−ب is a root regarding “writing”, from which we can obtain numerous words:
Can't we simply just stick the roots together?
No.
For example the letters ح−م−ل have the meaning of “to carry” but naively connecting the letters gives us حمل, which, without any context, could be read as
- حَمَلَ “he carried”, or
- حُمِلْ “he was carried”!
- (Vowel signs ـْ ـَ ـِ ـُ
Arabs infer vowels from context, otherwise words alone such as حمل are ambigious: It could mean حَمَلَ “he carried” or حُمِلْ “he was carried”.
As an example sentence with vowels written, Prophet Muhammad is known to have said:
أنَا مَدِينَةُ الْعِلْمِ وَعَلَيٌ بَابُهَا I am the city of knowledge and Ali is its gate Incidentally, Ali was the one who commissioned the system of vowels. https://blogs.transparent.com/arabic/the-beginning-of-dotting-and-diacritics-in-arabic/
Arabic has only three short vowels, or حركات (literally: “movements”), which are written as small symbols above/below letters.
Vowel name Vowel sound Arabic English example Fatha; فتحة a ـَ mat Dhamma; ظمّة u ـُ sugar Kasra; كسرة i ـِ bit The “no vowel” marker is suukun/سكون: While هههه has its vowels guessed to be هَهَهَهَ “hahahah”, we obtain “hhhh” by using sukkun, هْهْهْهْ. It is important for consonant-vowel-consonant syllables, such as بَابْ “bab” which means door.
Incidentally, when a sound needs to be repeated twice, it is usually written once with a Shadda ـّـ to indicate the doubling. For example, فَهِمَ fahima “he understood” but فَهَّمَ fahhama “he explained”. Shadda is used with الـ + ‘sun letters’. Unlike the other short vowels, the Shadda is usually written even in informal Arabic, to avoid ambiguity.
Arabic has 3 long vowels, which are formed using specific letters after the short vowels:
Long vowel sound Arabic English example aa ـَا far ii ـِي meet uu ـُو boot Since short vowels are normally not written, letters ا ي و play two roles: They behave as long vowels aa,ii,uu (when preceded by short vowels) and also behave as consonant sounds a,y,w.
- For example, as a consonant, ي makes an English “y” sound; but as a long vowel it makes an “ii” sound.
- Occasionally, aa is written using ی (which is like ي but without the dots), or یٰ, rather than an alif. This always happens at the end of a word and is called alif maqsuura “broken alif”; for example علی “on” and موسیٰ “Musa”.
The following video reads all Arabic letters, where each letter is vowelised by one of the 3 short vowels. It's a really nice video: https://www.youtube.com/embed/U1Cl6W8EEBQ?start=6.
are discussed below.)
- (Vowel signs ـْ ـَ ـِ ـُ
Both of these words are specific to
- a male person,
- in the past, and
- it's not clear whether the person is doing the carrying or the one being carried.
Thus حمل is far more specific than the general meaning of ح−م−ل “to carry” —which is not itself a word, but an abstract sequence of letters.
Irregular Roots
Irregular roots do not consist of 3 different consonants; instead, they fall into three categories:
- Doubled roots
where the second and third root letters are the same.
− If a doubled verb is put into a form involving a sukkun ـْـ on the 3rd root, then the 2nd and 3rd letters are written separately; otherwise, the 2nd and 3rd letters are written together with a shadda ـّـ.
− For example, ر−د−د “to reply” becomes رَدَّ “he replied” when placed in the masculine-second-person-past-tense form فَعَلَ, but becomes رَدَدْتُ “I replied” when placed in the first-person-past-tense form فَعَلْتُ. More on forms below!
- In doubt: Doubled roots are usually written together.
- Weak roots
where one of the three root letters is و or ي; for example ق−و−ل “to speak”.
- These letters are “so weak” that they change from the constant sounds و/w and ي/y to vowel sounds or disappear entirely, depending on the pattern the root is placed in.
− If و/ي is the first root, then it almost always drops out in the present tense. For example, و−ص−ل “to arrive” becomes أَصِلُ “I arrive” in the first-person-present-tense أَفْعُلُ form. Contrast this with the regular root ك−ت−ب “to write” becoming أَكْتُبُ “I write”.
- Hamzated roots
- where one of the root letters is hamza ء; for example ق−ر−ء “to read”.
1.1. Meanings of roots Interactive
Enter 3 letters to get a link to Arabic words that are derived from that root:
See: https://alhassy.github.io/AngularJSCheatSheet/
Alternatively, this link provides more information, but has less roots.
2. Arabic has 112 symbols and 112 sounds
What are the vowels that can be added to roots to make new words?
Arabic has 28 letters, and like cursive English, it is written with letters connected.
Each letter has 4 forms: The isolated form, the form where the letter starts a word, the form where the letter is in the middle of a word, and the form where a letter is at the end of a word. So, Arabic has 28 * 4 = 112 distinct shapes for its alphabet. (Since some letters do not connect forwards, the isolated form actually does appear in written text. For example, او means “or” and it consists of two isolated letters.) For example, the letter ha has the following forms:
| isolated | initial | medial | final |
|---|---|---|---|
| ه | هـ | ـهـ | ـه |
If a friend texts you something funny, you reply with ههههه −−− “hahaha”.
But, where are the short vowels “a”? Arabic short vowels are generally not written!
There are only three short vowels in Arabic: a, i and u. They are denoted by small symbols above/below letters, for example:
| Vowel | Example | English reading |
|---|---|---|
| ـَـ | هَهَهَهَ | hahahaha |
| ـُـ | هُهُهُهُ | huhuhuhu |
| ـِـ | هِهِهِهِ | hihihihi |
Incidentally, the sound “h” is obtained by using the “no vowel” marker: هْـ. So with the 3 short vowels and the fourth symbol to indicate the absence of a vowel, there are a total of 4 * 28 = 112 sounds in Arabic.
Tell me more about Arabic Vowels!
Arabs infer vowels from context, otherwise words alone such as حمل are ambigious: It could mean حَمَلَ “he carried” or حُمِلْ “he was carried”.
An example sentence with vowels written:
Arabic has only three short vowels, or حركات (literally: “movements”), which are written as small symbols above/below letters.
| Vowel name | Vowel sound | Arabic | English example |
|---|---|---|---|
| Fatha / فتحة | a | ـَ | mat |
| Dhamma / ظمّة | u | ـُ | sugar |
| Kasra / كسرة | i | ـِ | bit |
The “no vowel” marker is suukun/سكون: While هههه has its vowels guessed to be هَهَهَهَ “hahahah”, we obtain “hhhh” by using sukkun, هْهْهْهْ.
Arabic has 3 long vowels, which are formed using specific letters after the short vowels:
| Long vowel sound | Arabic | English example |
|---|---|---|
| aa | ـَا | far |
| ii | ـِي | meet |
| uu | ـُو | boot |
Since short vowels are normally not written, letters ا ي و play two roles: They behave as long vowels aa,ii,uu (when preceded by short vowels) and also behave as consonant sounds a,y,w.
- For example, as a consonant, ي makes an English “y” sound; but as a long vowel it makes an “ii” sound.
- Occasionally, aa is written using ی (which is like ي but without the dots), or یٰ, rather than an alif. This always happens at the end of a word and is called alif maqsuura “broken alif”; for example علی “on” and موسیٰ “Musa”.
The following video reads all Arabic letters, where each letter is vowelised by one of the 3 short vowels. It's a really nice video: https://www.youtube.com/embed/U1Cl6W8EEBQ?start=6.
Of-course, there is more to the story! There is the “glottal stop”, Hamza ـٔ , and other special characters and symbols
above/below letters. So the counts of 112 are not exact. For example, some letters, like alif ا, have the same shape
for different forms, but sometimes it can be written as ی (such as علی “on”) یٰ (such as موسیٰ “Musa”).
The Arabic Hamza ـٔ is like the English Apostrophe ـ'
- In both cases there is uncertaininty as to when and how to use it, even among native speakers.
- Whereas in English we ask ourselves: Should the apostrophe come before the “s” or after the “s”?, in Arabic the question becomes: Which letter should carry the hamza?.
- The hamza itself is considered a consonant, not a vowel, pronounced as a short pause.
- Like the apostrophe, the rules for hamza are more concerned with where to place it than how to pronounce it.
- General rules:
- At the start of a word, hamza is written on an alif: أ
- This might result in two alifs side-by-side, if so then merge them into alif madda آ, which is read as a long aa sound.
- Otherwise, the letter carrying the hamza tends to relate to the vowel before the hamza:
If we have ـُـ ، ـِـ ، ـَـ before the hamza, then the hamza is written ؤ ، یٔ/ـٔـ ، أ respectively.
- If we have ـْـ before the hamza, we write ؤ ، یٔ/ـٔـ ، أ depending on the vowel the hamza root should be taking. For example, س−ء−ل “to ask” becomes يسْأَل “he asks” in the masculine-second-person-present-tense (يَفْعَلُ form, for this particular root).
The following video reads all Arabic letters, where each letter is vowelised by one of the 3 short vowels. It's a really nice video.
3. ف−ع−ل : The template for any 3 core root letters
As a symbol to represent the three root letters of any word, Arabic grammar uses the roots of the prototypical verb فعل “to do”, read fa'al.
For example, the root ك−ت−ب is associated with “writing”. The word for “office” مَكْتَب is the مَفْعَل-pattern: The root letters have مَـ before them, a sukkun ـْـ over the first root letter, and a fatha ـَـ over the second root letter. In the same way, “books” كُتُب is the فُعُل-pattern.
Below are some example patterns. If you are faced with an Arabic word that you have never heard before, you can guess
the meaning by its root and pattern.
3.1. The فَعَّال-pattern: “the person whose job is X”
This pattern gives the profession associated with a core root. Here's some examples:
| Profession | Core meaning |
|---|---|
| كَتَّاب | ك−ت−ب |
| Scribe | to write |
| فَنَّان | ف−ن−ن |
| Artist | to be artistic |
| خَبَّاز | خ−ب−ز |
| Baker | to bake |
| عَطَّار | ع−ط−ر |
| Perfume vendor | to perfume |
| رَكَّاض | ر−ك−ظ |
| Runner | to run |
| جَرَّاح | ج−ر−ح |
| Surgeon | to cut |
3.2. The مَفعَل-pattern: “the place where X is done”
This pattern gives the place associated with a core root. Here's some examples:
| Place | Core meaning |
|---|---|
| مَسكَن | س−ك−ن |
| home | to live |
| مَكتَب | ك−ت−ب |
| office | to write |
| مَدخَل | د−خ−ل |
| entrance | to enter |
| مَخبَز | خ−ب−ز |
| bakery | to bake |
| مَعبَر | ع−ب−ر |
| crossing point | to cross |
| مَسبَح | س−ب−ح |
| swimming pool | to swim |
4. Verb Forms: The True Power of Arabic's Form System
The richness of Arabic is based on its system of word roots, and nowhere is this more evident than in the verb system. 
In English we can add extra letters to form different but connected meanings —for example: value, revalue, validate. Arabic takes this principle much farther with many different patterns that add meaning to the origninal root form. These derived forms are the major way in which Arabic achieves its richness of vocabulary. For example, from ق−ت−ل “to kill”, we can obtain
| he killed | قتل | qatala |
| he massacred (“killed intensely”) | قتّل | qattala |
| he battled (“tried to kill”) | قاتل | qaatala |
| they fought each other | تقاتلوا | taqaataluu |
Here are the significant verb forms. For simplicitly, I'm presenting them in the past tense using the root ف−ع−ل “to do”.
| Form | Common Meanings | Example |
|---|---|---|
| 1. فَعَلَ | “doing an action X”; (this is the most basic form) | كَتَبَ “he wrote” from ك−ت−ب “to write” |
| 2. فَعَّلَ | “doing X to another”; “making another do X” | خَرّجَ “he made someone go-out/graduate” from خ−ر−ج “to go out” |
| “doing X intensely/repeatedly” | كَسَّرَ “he smashed” from ك−س−ر “to break” | |
| 3. فَاعَلَ | “doing X with someone else” | جَالَسَ “he sat with (someone)” from ج−ل−س “to sit” |
| “trying to do X” | سَابَقَ “he raced” from س−ب−ق “to come before” | |
| 4. أَفْعَلَ | Transitive A “transitive” verb is a verb that requires an object to express a complete thought, otherwise it is “intransitive”. Some verbs are both transitive and intransitive. A “transitive” verb needs to transfer its action to something or someone —the object. In essence, transitive means “to affect something else.” For example, “Please bring coffee.” would not be a complete thought without the object “coffee”. That is, “Please bring.” is an incomplete thought: What or whom should we bring? As such, “bring” is a transitive verb. In contrast, “Please sing.” is a complete thought, and so “sing” is an intransitive verb —actually, it's also transitive. In Arabic, the Form-4 أفْعَلَ pattern turns intransitive verbs into transitive ones; and turns transitive verbs into doubly-transitive verbs —which means it takes two objects: E.g., “I gave the boy the ball”, here “gave” is doubly-transitive. E.g., in Form-4, ر−س−ل “to send” gives the transitive verb أرْسَلَ which means it can be followed by two objects: أرْسَلَ الولد لكتاب “The boy sent the book”. meaning: “doing X to another”; like Form-2 |
أَسْخَنَ “he heated (something)” from س−خ−ن “to be hot” |
| 5. تَفَعَّلَ | “doing X to yourself”; this is Form-2 + تَـ | تَذَكَّرَ “he remembered” from ذ−ك−ر “to remind” |
| 6. تَفَاعَلَ | “doing X together (as a group)”; this is Form-3 + تَـ | تَعَاوَنَ “he cooperated” from ع−و−ن “to help” |
| 7. اِنْفَعَلَ | Passive A “passive” verb is one where the subject undergoes the action of the verb rather than carries out the action, for example حُملت “she was carried” and يُستخدم “it is used”. meaning: “to be X-ed”. This is Form-1 + اِنْـ |
اِنْحَمَلَ “he was carried” from ح−م−ل “to carry” |
| 8. اِفْتَعَلَ | No consistent meaning; “to make yourself do X” | اِفْتَعَلَ “he incited” from ف−ع−ل “to do” |
| 9. اِفْعَلَّ | used for changing colours: “to turn colour X” | اِحْمَرَّ “he blushed / turned-red” from أحمر “red” |
| 10. اِسْتَفْعَلَ | “asking for X”; this is nearly Form-1 + اِسْتَـ | اِسْتَعْلَمَ “he inquired” from ع−ل−م “to know” |
| “to consider or find something to have quality X” | اِسْتَحْسَنَ “he admired” from ح−س−ن “to be beautiful” |
- Exercise! Place the roots ع−م−ل into all of these patterns, except form-9; then guess their meanings! ( Solution )
- AlManny.com is an excellent online dictionary to finding out the meanings of words when placing them in these forms.
All the derived forms do not exist for all roots, but most roots have at least one or two forms in general circulation.
- You'll need to look in a dictionary, or the above root-meaning tool, to know exactly which forms exist.
- There are an additional 5 forms, but they are super rare in usage.
- In addition, Arabic speakers will sometimes make up new verbs from existing roots, either as a joke or in an effort to be creative or ✨poetic💐.
5. Closing & Useful Resources
I've often seen introductions to Arabic mention the power of roots & patterns, but one usually has to work through a host of fundamental topics before actually seeing some of these patterns.
I've written this brief introduction so that one can actually see some of these patterns in action.
It's been a lot of fun —I had to learn a lot more than I thought I knew to make this happen. It seems writing about things forces you to understand them better!
Anyhow, I'm going to keep writing about Arabic since it seems fun and I'd like to have a way to quickly review my notes on what I'm learning.
5.1. Resources
Mastering Arabic Grammar by Jane Wightwick & Mahmoud Gaafar
Perhaps the most accessible book I've seen on Arabic grammar.
It's a small book, whose chapters are also small/focused and digestible.
It assumes you're familiar with the Arabic alphabet and takes you to forming full sentences, and reading short stories.
-
Almost every word in every sentence and phrase on this website is clickable, and takes you to a page with generous information about the word, along with audio clips. It's a free, beautiful, interactive website.
All The Arabic You Never Learned The First Time Around (PDF)
This seems like a very good book.
-
OERabic is an ambitious initiative that aims to enhance the mastering of Arabic by creating bespoke creative learning (and teaching) resources.
6. Appendix: Arabic Input Setup
How was this article written? Emacs!
On the left below is what I type, and on the right is what you see in this article (which include hover/tooltips for the cards).
How was this article written? Emacs!
With Emacs, I type phonetically (based on sounds) to get Arabic; e.g.,
typing musy$ alHsaIY gives me موسیٰ الحسائي, my name Musa Al-hassy.
Moreover, this is how Arabic looks like within Emacs:
Figure 1: This is how Arabic looks like within Emacs. (Old Arabic did not have any of the coloured symbols; not even the dots!)
The rest of this section details my Emacs setup.
6.1. The look within Emacs
;; Makes all dots, hamza, diadiract marks coloured!
(set-fontset-font "fontset-default" '(#x600 . #x6ff) "Amiri Quran Colored")
How did I find this font?
- Look for a font I like on https://fonts.google.com/?subset=arabic
brew search amiri- Look to see if there is a font associated with it
brew install font-amiri- Install the likely candidate
(set-fontset-font "fontset-default" '(#x600 . #x6ff) "Amiri Quran Colored")- Get the full name by: Emacs -> Options -> Set Default Font
Why even bother with this line?
I found that I personally need the above set-fontset-font/bin/bash: line 1: wn: command not found
line, since
I was typing the phrase
| اهلاً وسهلاً |
| “Hello, and welcome” |
| Literally: /Be with family, and at ease/ |
Yet I could not see the Fatha Tanween, ـًـ, on the Lam-Alif لا. This issue was only within Emacs: When I exported to HTML via C-c C-e h o then لاً would render with the tanween.
Anyhow, here are some other fun fonts to try out.
"Times New Roman" ;; Default?
"Libian SC" ;; Default?
"Noto Sans Arabic" ;; Also good! -- brew install font-noto-sans-arabic --cask
"Sana" ;; is super fun!
"Al Bayan"
"Baghdad"
"Damascus" ;; Thin
"Beirut" ;; Super thick!
"KufiStandardGK" ;; Reasonable bold
"Diwan Kufi" ;; fancy, almost calligraphic
"DecoType Naskh" ;; Tight; looks like handwritten; does not support `___` elongations.
"Farah" ;; sloppy handwritten
"Waseem" ;; handwritten
"Farisi" ;; Persian-style: Super thin and on an angle
"Noto Nastaliq Urdu" ;; Like Farisi, but a bit larger & thicker
"Noto Kufi Arabic UI"
"Geeza Pro" ;; nice and thick
"DecoType Naskh"
6.2. Actually typing Arabic
The "arabic" input method (via C-\, which is toggle-input-methodEnable or disable multilingual text input method for the current buffer.
Only one input method can be enabled at any time in a given buffer.
The normal action is to enable an input method if none was enabled,
and disable the current one otherwise. Which input method to enable
can be determined in various ways--either the one most recently used,
or the one specified by ‘default-input-method’, or as a last resort
by reading the name of an input method in the minibuffer.
With a prefix argument ARG, read an input method name with the minibuffer
and enable that one. The default is the most recent input method specified
(not including the currently active input method, if any).
When called interactively, the optional argument INTERACTIVE is non-nil,
which marks the variable ‘default-input-method’ as set for Custom buffers.
(fn &optional ARG INTERACTIVE)
) just changes my English QWERTY keyboard into an
Arabic keyboard —useful if one has already mastered touch typing in Arabic!
In contrast, the Perso-Arabic input method (known as farsi-transliterate-banan) uses a system of transliteration: ASCII
keys are phonetically mapped to Arabic letters.
C-\ farsi-transliterate-banan RET M-x describe-input-methodto enter this method and to learn more about it.- For example,
wrb≈ عرب andalwrbYTh≈ العربية
- For example,
- When you're done writing in Arabic, just press
C-\to toggle back to English.
M-x describe-input-method
Input method: farsi-transliterate-banan (mode line indicator:ب)
Intuitive transliteration keyboard layout for persian/farsi.
See http://www.persoarabic.org/PLPC/120036 for additional documentation.
KEYBOARD LAYOUT
---------------
This input method works by translating individual input characters.
Assuming that your actual keyboard has the ‘standard’ layout,
translation results in the following "virtual" keyboard layout
(the labels on the keys indicate what character will be produced
by each key, with and without holding Shift):
+----------------------------------------------------------+
| ۱ ! | ۲ ْ | ۳ ً | ۴ ٰ | ۵ ٪ | ۶ َ | ۷ & | ۸ * | ۹ ( | ۰ ) | − ـ | = + | ٔ ّ |
+----------------------------------------------------------+
| غ ق | ع ء | ِ ٍ | ر R | ت ط | ی ي | و ٓ | ی ئ | ُ ٌ | پ P | [ { | ] } |
+---------------------------------------------------------+
| ا آ | س ص| د ٱ | ف إ | گ غ | ه ح | ج | ک ك | ل L | ؛ : | ' " | \ | |
+--------------------------------------------------------+
| ز ذ | ض ظ | ث ٕ | و ؤ | ب B | ن « | م » | ، < | . > | ؟ |
+-----------------------------------------------+
+-----------------------------+
| space bar |
+-----------------------------+
KEY SEQUENCE
------------
You can also input more characters by the following key sequences:
Th ة kh خ sh ش ch چ
Also watch Perso-Arabic Input Methods And BIDI Aware Apps (also on youtube).
Vowel me to the moon!
| fatha | fathaTan | kasrah | kasrahTan | dhama | dhamTan | sukun | hamza | alif | madda | shadda |
| بَ | بً | بِ | بٍ | بُ | بٌ | بْ | بٔ | بٰ | بٓ | بّ |
| ^ | # | e | E | o | O | @ | ` | $ | U | ~ |
Arabic Tatweel: Stretching out the handwritten text for beauty!
We can obtain elongation by pressing underscore: j_______w________f_______r gives us جـــــــعـــــــفــــــــر
- جعفر is read Jaafar; it is a popular name that also means small stream.
6.3. Typing outside of Emacs
TypingClub ~ Arabic is a fun & free website to learn how to type Arabic on a standard keyboard. I highly recommend it.
Being able to type Arabic while thinking in Arabic, instead of thinking of sounds using the English alphabet to approximate Arabic sounds, may be helpful in actually learning Arabic.
6.4. Using Images as Emojis
I found some images online, from OERabic, that I thought could be used to enhance my prose.
- I want to treat them like emojis, as such they're intentionally small, so that they can more-or-less be used inline within sentences.
- When you click on them, they take you to the actual image source.
- This is better than me downloading the images then having to host them somewhere then linking back to the source to credit the people who made the images.
- When you hover over them, you see the translation.
The docstring of org-deflinkMake a new Org-link NAME that exports using form BODY.
ARGLIST names the link’s label, description, and export backend ---in that
order--- for use in BODY and DISPLAY:
(org-deflink shout (label &optional description)
"Shout the description, else the label."
:face =’(:weight bold)
:export (upcase (or description label)))
An argument written (NAME DEFAULT) falls back to DEFAULT when absent; e.g.,
(label &optional (description "…")). A link that needs none of them
has the ARGLIST ().
Since Org links are essentially string-valued functions,
a function ‘org-link/NAME’ is created.
DOCSTRING is optional; it is visible with
(documentation ’org-link/NAME)
BODY is a string-valued expression, that may make use of ARGLIST’s names.
The backend is, e.g., =’html or =’latex; the label and description are
obtained from uses:
[[name:label][description]]
In particular, the use case “name:label” means that the description is nil.
---------------------------------------------------------------------------
Example use:
;; In a Lisp buffer, press “C-x C-e” to load this definition
(org-deflink shout (label &optional description) (upcase (or description label)))
;; In an Org-buffer, press “C-c C-e h o” to see how this exports
<shout: hello world!>
;; Or using the bracket format
[[shout:][hello world!]]
[[shout: hello world!]]
;; or using the plain format
shout:hello_world
Here is a more complex, involved, example that makes use of
‘:let’ for local declarations. For instance, “define:hello”
renders as the word “hello” with a tooltip defining the word; the
definition is obtained from the command line tool ‘wn’.
(org-deflink define (word)
"Define the given word using WordNet, along with synonyms and coordinate terms."
:let (definition (shell-command-to-string (format "wn %s -over -synsn -coorn" word)))
:help-echo definition
:export (org--html-tooltip definition word :plain))
See ‘org--html-tooltip’ for HTML tooltips: their text is Org, or, as here, plain.
More generally, org-special-block-extra’s “doc” link type
supports, in order of precedence: User definitions, Emacs Lisp
documentation of functions & variables, and definitions of
English words. For example, “doc:existential_angst” for an entry
‘existential_angst’ whose associated documentation-glossary is
user-defined in a ‘#+documentation’ Org-block, or
“doc:thread-first” for the Emacs Lisp documentation of the
function ‘thread-first’, or “doc:user-mail-address” for the Emacs
Lisp documentation of the variable ‘user-mail-address’, or
“doc:hello” for the definition of the English word ‘hello’.
Besides :export, the following keys affect how the link is displayed in Emacs
Org buffers. They are given alongside :export, as above; in the deprecated
style, they form a vector DISPLAY between the docstring and BODY, such as
[:help-echo (format "%s" label)].
+ :help-echo is a string-valued expression of the tooltip that should accompany
the new link in Org buffers. It has access to o-format being one of ‘plain’,
‘angle’, ‘bracket’ which indicates the format of the link, as shown above.
It also has access to ARGLIST’s label and description.
By default, the tooltip is the link name followed by the documentation
of the link, and, finally, the HTML export of the link.
That way, upon hover, users can visually see the link contents,
know what/how the link exports, and actually see the HTML export.
That is to say, for the ‘shout’ example above, the default display is essentially:
:help-echo (org-link/shout o-label o-description ’html)
You may want to add the following to your Emacs init file:
;; Nearly instantaneous display of tooltips.
(setq tooltip-delay 0)
;; Give user 30 seconds before tooltip automatically disappears.
(setq tooltip-hide-delay 300)
+ :face specifies how should these links be displayed within Emacs.
It is a list-valued expression.
As usual, it may make use of ARGLIST’s label (but the description is nil).
Example:
:face ’(:underline "green")
See https://www.gnu.org/software/emacs/manual/html_node/elisp/Face-Attributes.html
+ :display ’full if you do not want bracket links to be
folded away in Org buffers; i.e., “[[X][Y]]” does not render as just “Y”.
+ :follow is a form that is executed when you click on such links; e.g., to open
another buffer, browser, or other action. It makes use of ARGLIST’s label.
Be aware that the label is a string that may contain spaces; e.g., when the action is to open
a URL in a browser.
If you are in need of providing similar, related, actions on a single link
then your :follow can condition on the current prefix argument via ‘o-prefix’
(which is essentially ‘current-prefix-arg’).
For instance, a user presses “C-u RET” on your link to do one thing
but “C-u 72 RET” to do another action.
+ :keymap is an alternating list of keys and actions to be
performed when those keys are pressed while point is on the link.
For example:
:keymap (C-h (message-box "hola"))
By default, C-n and C-p are for moving to next and previous occruances of the same link type.
+ :hover and :manual are as for ‘org-defblock’: prose eldoc shows beneath the docstring’s first line, and the URL,
or #ANCHOR of ‘org-special-block-extras-manual’, of where the link is documented.
+ :let is a list of alternating variable symbol name and value, which are then used to form
a concrete ‘let*’ clause. This is useful for introducing local variables for use in the DISPLAY
as well as in the CONTENTS. Such local declarations may make use of ARGLIST’s names, as usual.
The preferred syntax supplies all keys — including :export for the export body — as a
flat top-level plist with no enclosing vector:
(org-deflink shout (label)
"Shout the label."
:face '(:weight bold)
:export (upcase label))
(fn NAME ARGLIST &optional DOCSTRING DISPLAY &rest BODY) has nice examples, so we quickly adapt the very first example for our needs: We look at
the label given to the link, then depending on that, we show an clickable image along with a tooltip.
It lives in AlBasmala, so every Arabic article can use it —§shared link types:
(org-deflink arabic (label)
"Show one of 6 hardcoded phrases as a small inline image."
(-let [url
(pcase label
("Let's take a break" "https://alhassy.com/resources/iraqi-sign-take-a-break.png")
("Yes" "https://alhassy.com/resources/iraqi-sign-yes.png")
("No" "https://alhassy.com/resources/iraqi-sign-no.png")
("Agree" "https://alhassy.com/resources/iraqi-sign-agree.png")
("Disagree" "https://alhassy.com/resources/iraqi-sign-disagree.png")
("I have a question" "https://alhassy.com/resources/iraqi-sign-question.png")
(_ (error "arabic:%s is not one of: Let's take a break, Yes, No, Agree, Disagree, I have a question" label)))]
(format "<a href=\"%s\" class=\"tooltip\" title=\"%s\"><img src=\"%s\" height=50></a>" url label url)))
Below is how I would go about actually using this new link type. The left shows what I would write within Emacs, and the right is the resulting HTML (which I also see within Emacs, and the Chrome Browser.)
Life & Computing Science by Musa Al-hassy is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License