0

I want to customize org-agenda-prefix-format but am unable to find something in the reference explaining the syntax and the format strings I can use.

The manual simply states:

You can also customize the prefix using the option org-agenda-prefix-format. This prefix is followed by a cleaned-up version of the outline headline associated with the item.

However, it doesn't explain the exact syntax one needs to use. I also didn't find any references to the syntax when I searched for the issue online.

Can someone point me to a resource that explains the syntax and the format strings one needs to use?

3
  • I don't have an answer for you; hopefully someone else will. But it sounds like you should maybe use M-x report-emacs-bug (which is also for enhancement requests, not just bugs), and suggest that the manual or some doc strings be beefed up a bit to include the info you think is missing. Even just the information that you couldn't find what you were looking for can sometimes help them improve the doc.
    – Drew
    Feb 4, 2019 at 22:02
  • 1
    I cannot point you to formal references in a manual, but I can tell you that I have written up one or more answers here and/or on stackoverflow with examples. In addition, type M-x describe-variable aka C-h v to see what is already in the doc-string. Then, Google org-agenda-prefix-format and you should get quite a few hits with examples. In one of the Google searches, I see that one answer quoted part of the doc-string for the variable that describes several options and what each stands for ....
    – lawlist
    Feb 5, 2019 at 5:47
  • @lawlist, thanks! C-h v never occurred to me. The variable description page does indeed give some information I can start with.
    – Abhik Pal
    Feb 5, 2019 at 7:33

1 Answer 1

1

To make it a formal answer: Use describe-variable org-agenda-prefix-format or C-h v and the help buffer will give you that:

org-agenda-prefix-format is a variable defined in ‘org-agenda.el’.

Its value is shown below.

Format specifications for the prefix of items in the agenda views.

An alist with one entry per agenda type.  The keys of the
sublists are ‘agenda’, ‘todo’, ‘search’ and ‘tags’.  The values
are format strings.

This format works similar to a printf format, with the following meaning:

  %c   the category of the item, "Diary" for entries from the diary,
       or as given by the CATEGORY keyword or derived from the file name
  %e   the effort required by the item
  %l   the level of the item (insert X space(s) if item is of level X)
  %i   the icon category of the item, see ‘org-agenda-category-icon-alist’
  %T   the last tag of the item (ignore inherited tags, which come first)
  %t   the HH:MM time-of-day specification if one applies to the entry
  %s   Scheduling/Deadline information, a short string
  %b   show breadcrumbs, i.e., the names of the higher levels
  %(expression) Eval EXPRESSION and replace the control string
                by the result

All specifiers work basically like the standard ‘%s’ of printf, but may
contain two additional characters: a question mark just after the ‘%’
and a whitespace/punctuation character just before the final letter.

If the first character after ‘%’ is a question mark, the entire field
will only be included if the corresponding value applies to the current
entry.  This is useful for fields which should have fixed width when
present, but zero width when absent.  For example, "%?-12t" will
result in a 12 character time field if a time of the day is specified,
but will completely disappear in entries which do not contain a time.

If there is punctuation or whitespace character just before the
final format letter, this character will be appended to the field
value if the value is not empty.  For example, the format
"%-12:c" leads to "Diary: " if the category is "Diary".  If
the category is empty, no additional colon is inserted.

The default value for the agenda sublist is "  %-12:c%?-12t% s",
which means:

- Indent the line with two space characters
- Give the category a 12 chars wide field, padded with whitespace on
  the right (because of ‘-’).  Append a colon if there is a category
  (because of ‘:’).
- If there is a time-of-day, put it into a 12 chars wide field.  If no
  time, don’t put in an empty field, just skip it (because of ’?’).
- Finally, put the scheduling information.

See also the variables ‘org-agenda-remove-times-when-in-prefix’ and
‘org-agenda-remove-tags’.

Custom commands can set this variable in the options section.

  This variable was introduced, or its default value was changed, in
  version 26.1 of Emacs.
  You can customize this variable.

Value:
((agenda . " %i %-12:c%?-12t% s")
 (todo . " %i %-12:c")
 (tags . " %i %-12:c")
 (search . " %i %-12:c"))

from org 9.6.1

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.