[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/modus-operandi-theme decf274 046/153: Add manual entry
From: |
Stefan Monnier |
Subject: |
[elpa] externals/modus-operandi-theme decf274 046/153: Add manual entry on Org user faces (DIY) |
Date: |
Thu, 18 Mar 2021 13:47:36 -0400 (EDT) |
branch: externals/modus-operandi-theme
commit decf274f42604e4c72a1355e7613b0bb2d52a550
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>
Add manual entry on Org user faces (DIY)
---
doc/modus-themes.org | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 72 insertions(+)
diff --git a/doc/modus-themes.org b/doc/modus-themes.org
index 4c4d5d5..241d283 100644
--- a/doc/modus-themes.org
+++ b/doc/modus-themes.org
@@ -977,6 +977,78 @@ faces like this:
(set-face-attribute face nil :font "DejaVu Sans Mono-11"))
#+end_src
+** Org user faces (DIY)
+:PROPERTIES:
+:DESCRIPTION: Extend styles for org-mode keywords and priorities
+:CUSTOM_ID: h:89f0678d-c5c3-4a57-a526-668b2bb2d7ad
+:END:
+
+Users of =org-mode= have the option to configure various keywords and
+priority cookies to better match their workflow. User options are
+=org-todo-keyword-faces= and =org-priority-faces=.
+
+As those are meant to be custom faces, it would be futile to have the
+themes try to guess what each user would want to use, which keywords to
+target, and so on. Instead, we can provide guidelines on how to
+customise things to one's liking with the intent to retain the overall
+aesthetics of the theme.
+
+Please bear in mind that the end result of those is not controlled by
+the active theme but by how Org maps faces to its constructs. Editing
+those while =org-mode= is active requires =M-x org-mode-restart= for changes
+to take effect.
+
+Let us assume you wish to visually differentiate your keywords. You
+have something like this:
+
+#+begin_src emacs-lisp
+(setq org-todo-keywords
+ '((sequence "TODO(t)" "|" "DONE(D)" "CANCEL(C)")
+ (sequence "MEET(m)" "|" "MET(M)")
+ (sequence "STUDY(s)" "|" "STUDIED(S)")
+ (sequence "WRITE(w)" "|" "WROTE(W)")))
+#+end_src
+
+You could then use a variant of the following to inherit from a face
+that uses the styles you want and also to preserve the properties
+applied by the =org-todo= face:
+
+#+begin_src emacs-lisp
+(setq org-todo-keyword-faces
+ '(("MEET" . '(font-lock-preprocessor-face org-todo))
+ ("STUDY" . '(font-lock-variable-name-face org-todo))
+ ("WRITE" . '(font-lock-type-face org-todo))))
+#+end_src
+
+This will refashion the keywords you specify, while letting the others
+use their original styles (which are defined in the =org-todo= face).
+
+When you inherit from multiple faces, you need to quote the list as
+shown above. The order is important: the last item is applied over the
+previous ones.
+
+If you do not want to blend multiple faces, you do not need a quoted
+list. A pattern of =keyword . face= would suffice.
+
+Consider both approaches in the configuration of the priority cookies:
+
+#+begin_src emacs-lisp
+(setq org-priority-faces
+ '((?A . '(org-scheduled-today org-priority))
+ (?B . org-priority)
+ (?C . '(shadow org-priority))))
+#+end_src
+
+To find all the faces that are loaded in your current Emacs session, use
+=M-x list-faces-display=. Also try =M-x describe-variable= and then specify
+the name of each of those Org variables demonstrated above. Their
+documentation strings will offer you further guidance.
+
+Also consider reading the "Notes for aspiring Emacs theme developers",
+published on 2020-08-28 by Protesilaos Stavrou:
+https://protesilaos.com/codelog/2020-08-28-notes-emacs-theme-devs/.
+
+
* Face coverage
:PROPERTIES:
:CUSTOM_ID: h:a9c8f29d-7f72-4b54-b74b-ddefe15d6a19
- [elpa] externals/modus-operandi-theme 00f8a28 044/153: Update README to note that the manual is available, (continued)
- [elpa] externals/modus-operandi-theme 00f8a28 044/153: Update README to note that the manual is available, Stefan Monnier, 2021/03/18
- [elpa] externals/modus-operandi-theme 72c0714 038/153: Add support for eshell-syntax-highlighting, Stefan Monnier, 2021/03/18
- [elpa] externals/modus-operandi-theme 0633c2a 047/153: Recompile manual (cover 619e48bbc and decf274f4), Stefan Monnier, 2021/03/18
- [elpa] externals/modus-operandi-theme d09be79 030/153: Expand docstring of new headings' alist option, Stefan Monnier, 2021/03/18
- [elpa] externals/modus-operandi-theme d5b6321 028/153: Initial implementation of reviewed headings option, Stefan Monnier, 2021/03/18
- [elpa] externals/modus-operandi-theme 7789ae9 004/153: Clarify the version numbers that ship with Emacs, Stefan Monnier, 2021/03/18
- [elpa] externals/modus-operandi-theme 95ac8b4 020/153: Re-organise new doc files, Stefan Monnier, 2021/03/18
- [elpa] externals/modus-operandi-theme 49872b0 031/153: Expand manual with new heading styles alist option, Stefan Monnier, 2021/03/18
- [elpa] externals/modus-operandi-theme 3d00716 049/153: Use distinct colour for info-menu-star, Stefan Monnier, 2021/03/18
- [elpa] externals/modus-operandi-theme a745281 053/153: Minor tweaks to custom modeline 'moody' option, Stefan Monnier, 2021/03/18
- [elpa] externals/modus-operandi-theme decf274 046/153: Add manual entry on Org user faces (DIY),
Stefan Monnier <=
- [elpa] externals/modus-operandi-theme 0e45c0a 056/153: Reword manual's entry on Org user faces, Stefan Monnier, 2021/03/18
- [elpa] externals/modus-operandi-theme ab61e17 029/153: Several refinements to new headings custom alist, Stefan Monnier, 2021/03/18
- [elpa] externals/modus-operandi-theme 6fee2d0 055/153: Make the README a bit more informative, Stefan Monnier, 2021/03/18
- [elpa] externals/modus-operandi-theme 306a64a 034/153: Let the README only provide useful links, Stefan Monnier, 2021/03/18
- [elpa] externals/modus-operandi-theme 4d594f0 050/153: Important update in manual entry about font config, Stefan Monnier, 2021/03/18
- [elpa] externals/modus-operandi-theme 3f9da5d 058/153: Add support for racket-mode, Stefan Monnier, 2021/03/18
- [elpa] externals/modus-operandi-theme 82ed3ba 039/153: Reword GuixSD to "Guix System", Stefan Monnier, 2021/03/18
- [elpa] externals/modus-operandi-theme 53f877a 060/153: Expand manual's entry on modeline 'moody' option, Stefan Monnier, 2021/03/18
- [elpa] externals/modus-operandi-theme e523018 071/153: changed cperl-mode colours, Stefan Monnier, 2021/03/18
- [elpa] externals/modus-operandi-theme 28c12e4 063/153: Let quoted Info manual text always be fixed-pitch, Stefan Monnier, 2021/03/18