alphapapa / alphapapa/org-super-agenda
org-super-agenda-groups needs a custom-type definition
- Dominant language
- Emacs Lisp
- Stars
- 1.5k
- Forks
- 107
- PR merge metrics
- No merged PRs in 30d
Description
Right now, `org-super-agenda-groups` is defined like this:
```
(defcustom org-super-agenda-groups nil
"List of groups to apply to agenda views when `org-super-agenda-mode' is on.
See readme for information."
:type 'list)
```
When you edit the option in `customize`, it looks like this:
```
org-super-agenda-groups: nil
State : STANDARD. (mismatch)
```
…and you can’t define the list using any customization widgets, you have to write bare Lisp syntax. I’m sure this is okay for you Emacs Lisp wizards, but to a n00b like me, it’s intimidating!
Since `org-super-agenda-groups` is a complicated (and powerful) option with its own syntax, a proper `:type` definition would be a godsend! Here’s a good example of a thorough definition for a complex option with specialized syntax, from `org-capture.el`:
```
(defcustom org-capture-templates nil
;; very very long docstring snipped here —Tina
:group 'org-capture
:version "24.1"
:set (lambda (s v) (set s (org-capture-upgrade-templates v)))
:type
(let ((file-variants '(choice :tag "Filename "
(file :tag "Literal")
(function :tag "Function")
(variable :tag "Variable")
(sexp :tag "Form"))))
`(repeat
(choice :value ("" "" entry (file "~/org/notes.org") "")
(list :tag "Multikey description"
(string :tag "Keys ")
(string :tag "Description"))
(list :tag "Template entry"
(string :tag "Keys ")
(string :tag "Description ")
(choice :tag "Capture Type " :value entry
(const :tag "Org entry" entry)
(const :tag "Plain list item" item)
(const :tag "Checkbox item" checkitem)
(const :tag "Plain text" plain)
(const :tag "Table line" table-line))
(choice :tag "Target location"
(list :tag "File"
(const :format "" file)
,file-variants)
(list :tag "ID"
(const :format "" id)
(string :tag " ID"))
(list :tag "File & Headline"
(const :format "" file+headline)
,file-variants
(string :tag " Headline"))
(list :tag "File & Outline path"
(const :format "" file+olp)
,file-variants
(repeat :tag "Outline path" :inline t
(string :tag "Headline")))
(list :tag "File & Regexp"
(const :format "" file+regexp)
,file-variants
(regexp :tag " Regexp"))
(list :tag "File [ & Outline path ] & Date tree"
(const :format "" file+olp+datetree)
,file-variants
(option (repeat :tag "Outline path" :inline t
(string :tag "Headline"))))
(list :tag "File & function"
(const :format "" file+function)
,file-variants
(sexp :tag " Function"))
(list :tag "Current clocking task"
(const :format "" clock))
(list :tag "Function"
(const :format "" function)
(sexp :tag " Function")))
(choice :tag "Template "
(string)
(list :tag "File"
(const :format "" file)
(file :tag "Template file"))
(list :tag "Function"
(const :format "" function)
(function :tag "Template function")))
(plist :inline t
;; Give the most common options as checkboxes
:options (((const :format "%v " :prepend) (const t))
((const :format "%v " :immediate-finish) (const t))
((const :format "%v " :jump-to-captured) (const t))
((const :format "%v " :empty-lines) (const 1))
((const :format "%v " :empty-lines-before) (const 1))
((const :format "%v " :empty-lines-after) (const 1))
((const :format "%v " :clock-in) (const t))
((const :format "%v " :clock-keep) (const t))
((const :format "%v " :clock-resume) (const t))
((const :format "%v " :time-prompt) (const t))
((const :format "%v " :tree-type) (const week))
((const :format "%v " :unnarrowed) (const t))
((const :format "%v " :table-line-pos) (string))
((const :format "%v " :kill-buffer) (const t)))))))))
```
As the `org-super-agenda` documentation says, “At first you might feel bewildered by all the options.” The advantage of having a thorough `:type` definition for `customize` is that users can tackle one decision at a time, with the different choices clearly displayed at each juncture, without having to go back and forth between code and documentation or keep parentheses balanced or whatever, and without having to have the entire idea fully formed in one’s head from the beginning.
The documentation for `:type` is here: [elisp: Customization Types](https://www.gnu.org/software/emacs/manual/html_node/elisp/Customization-Types.html) Thanks for all your hard work! :smile:
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.