CODEWITHSUNDEEP
emacsorg-mode
James
James

Reputation: 1678

Customizing Org Mode variables--where is the documentation?

I've been using Org-mode a few months, and as I customize Emacs, I'm having a lot of difficulty finding documentation on how to specifically customize various variables.

Example: I've successfully set up archiving, but want to customize the org-archive-save-context-info variable to reduce the info that's archived along with the task. I do not want to do this per-file, but in my config file. Despite my best efforts, I don't see documentation on syntax and parameters for customizing this.

I do see some documentation when I customize the variable in the Emacs UI--but I'm looking for documentation so I can see syntax and parameters for customizing this myself via a config file. I can learn it backwards this way (via 'easy customization'): customize a variable, see what Emacs wrote to the config, try tweaking that, etc.

[EDIT] I'm talking about info below the task that appears after archiving, like this:

  :PROPERTIES:
  :ARCHIVE_TIME: 2018-09-10 Mon 11:24
  :ARCHIVE_FILE: ~/Dropbox/logs/capture.org
  :ARCHIVE_OLPATH: Tasks
  :ARCHIVE_CATEGORY: capture
  :ARCHIVE_TODO: DONE
  :END:

Is this intentional? Do I just need to 'know ELisp' first? Is the intention that you use the Emacs point-and-click UI to customize things like this? Happy to RTFM if I could find the FM.

Upvotes: 1

Views: 794

Answers (1)

phils
phils

Reputation: 73274

Is the intention that you use the Emacs point-and-click UI to customize things like this?

It's certainly intended that you would use the customize interface if you don't know elisp (and you might well choose to use it even if you do).

Do I just need to 'know ELisp' first?

Yes, you'll need at least some familiarity with elisp in order to understand the documentation and be able to write your own config changes. This is because elisp is the configuration language for Emacs, and so the documentation is written in that context. (It wouldn't make sense for basic lisp concepts to be explained and repeated in every piece of documentation which used them.)

That said, many people get by just copying and pasting from config examples -- and you're likely to pick up the basics this way, even if you don't fully understand them. If you're serious about Emacs, though, spending some time to learn about elisp will be hugely beneficial to you in future.

I can learn it backwards this way (via 'easy customization'): customize a variable, see what Emacs wrote to the config, try tweaking that, etc.

That's an entirely reasonable thing to do.

FWIW C-hv org-archive-save-context-info is actually very clear if you have the background understanding.

This variable can be a list of any of the following symbols:

time       The time of archiving.
file       The file where the entry originates.
ltags      The local tags, in the headline of the subtree.
itags      The tags the subtree inherits from further up the hierarchy.
todo       The pre-archive TODO state.
category   The category, taken from file name or #+CATEGORY lines.
olpath     The outline path to the item.  These are all headlines above
           the current item, separated by /, like a file path.

That tells you that you might use the following in your config file:

(setq org-archive-save-context-info '(time file todo))

Happy to RTFM if I could find the FM.

You can start learning about elisp in the "Emacs Lisp Intro" manual, which you should find near the top of the Info directory, or jump to directly with C-hig (eintr) RET. Type h from there if you need to learn how to use the Info reader.

Upvotes: 2

Related Questions