vapniks/org-dotemacs

Store your emacs config as an org file, and load code snippets based on tag matches.

Library Information

org-dotemacs.el — Store your emacs config as an org file, and choose which bits to load.

Filename

org-dotemacs.el

Description

Store your emacs config as an org file, and load code snippets based on tag matches.

Author

Joe Bloggs <[email protected]>

Maintainer

Joe Bloggs <[email protected]>

• Copyleft (Ↄ) 2013, Joe Bloggs, all rites reversed.

Created

2013-04-27 20:19:18

Version

0.1

Last-Updated

2013-04-27 20:19:18

By

Joe Bloggs

URL

https://github.com/vapniks/org-dotemacs

Keywords

local

Compatibility

GNU Emacs 24.3.1

Package-Requires

((org “7.9.3”) (cl-lib “1.0”))

Features that might be required by this library

org cl

This file is NOT part of GNU Emacs

Licensed under the [GPL version 3](http://www.gnu.org/licenses/) or later.

Bitcoin donations gratefully accepted: 1Ph9srQBspJCDS9CnGUyWJPTrU4ydX9Aa3

Commentary

Keeping your emacs config in an org file makes it easier for you to keep your .emacs under control, and avoid DotEmacsBankruptcy. With your config code stored in an org file you can easily edit the structure and keep notes.

This library allows you to load elisp code from an org file on emacs startup. You can also limit the code that is loaded to certain tagged headers using an org tag match, and specify dependencies between code blocks. Using tag matches you can also reuse the same org file for different emacs setups by specifying different tag matches for each setup, or load parts of the file on demand.

Commands/Usage

The main command is `org-dotemacs-load-default’ which loads your default org-dotemacs file (~/.dotemacs.org), and prompts for a tag match to specify which code blocks to load. In this way you can load bits of config code when you need them.

You can also put this command in your InitFile (see Installation below) to load the code on startup. To change the default org file use the `org-dotemacs-default-file’ option. If you want to load a different org file from your default one, use `org-dotemacs-load-file’.

For faster loading you may prefer to keep your config code in a separate elisp file, and just update this file now and again by exporting the code from the org file. Use the `org-dotemacs-load-file’ command for this and specify a target file when prompted. Note however that you may get errors when loading the elisp file that you didnt get with the org file. This is because in order to process the org-file some other libraries are loaded which are not loaded when the elisp file loads. You will have to experiment for yourself.

After loading you can inspect the Messages buffer to see which blocks were successfully loaded and which had errors. If you call the `org-dotemacs-jump-to-block’ command on one of the org-dotemacs lines in this buffer it will take you to the block mentioned on that line, or you can prompt for one by using a prefix with this command.

Structure of the org file

The elisp code should be contained in emacs-lisp code blocks, e.g:

#+BEGIN_SRC emacs-lisp

(setq line-number-mode t)
(setq column-number-mode t)
(setq frame-title-format "%b")
(set-background-color "Black")
(set-foreground-color "White")
(set-cursor-color "White")

#+END_SRC

Ideally you should have each code block under a separate org subtree, then you can use properties to name the blocks and define dependencies, and tags and todo states to specify which blocks should be loaded (see below).

I prefer to keep all my code block subtrees under a single header, and use other headers for keeping notes, defining buffer-wide properties, etc. This way I can get a nice column view of the code blocks (see the columns view section below).

Block dependencies

You can enforce dependencies between code blocks by defining NAME & DEPENDS properties for the subtrees containing the blocks (preferred). The NAME property should contain the name of the block, and the DEPENDS property should contain a space separated list of block names that this block depends on. If a block doesn’t have it’s own NAME property it will be given a default name of “@N” where N is the buffer position of the start of the block. If `org-dotemacs-dependency-inheritance’ is non-nil then block dependencies will be inherited from parent headers.

A block will not be loaded until all of its dependencies have been loaded.

Tags and TODO states

You can tag your subtrees and use tag matches to specify which blocks to evaluate in calls to `org-dotemacs-load-file’ and `org-dotemacs-load-default’. See ”Matching tags and properties” in the org manual for more information on tag matches.

Also, by default any blocks in a subtree marked with a todo state of BROKEN will not be evaluated. You can specify which TODO states to include/exclude for evaluation by customizing the `org-dotemacs-include-todo’ and `org-dotemacs-exclude-todo’ options.

To add the BROKEN state to the list of todo states for the file you need to add buffer-wide todo states by adding a line like this somewhere in your org file (see ”Per file keywords” in the org manual).

#+TODO: BROKEN CHECK TODO

Columns View

If you use properties for defining names and dependencies then you can get a nice column view of your code subtrees with the following columns view specification:

#+COLUMNS: %35ITEM %15NAME %35DEPENDS %15TAGS %TODO

This can be placed anywhere in your dotemacs org file. Then if you press C-c C-x C-c on the toplevel header for your code blocks you’ll get a column view that allows you to easily change the names, dependencies, tags and todo states.

Error handling

Error handling can be controlled by customizing `org-dotemacs-error-handling’ or by setting the error-handling command line option when starting emacs. By default code blocks with unmet dependencies or errors are skipped over as soon as an error is encountered, but you can also specify that org-dotemacs should halt or try to reload the blocks. In the latter case after attempting to evaluate all blocks, any blocks with errors will be tried again. This process is repeated until there are no changes in the blocks that succeed, or no bad blocks left.

Command line options

org-dotemacs.el will look for two command line options when loaded: error-handling (for setting the value of `org-dotemacs-error-handling’) and tag-match (for specifying which headers to load). For example if you enter the following at the command line:

emacs –error-handling retry –tag-match “settings-mouse”

Then only code blocks tagged “settings” but not “mouse” will be loaded, and org-dotemacs will try to reload any blocks that have errors.

Customizable options

• `org-dotemacs-default-file’ : The default org file containing the code blocks to load when `org-dotemacs-load-file’ is called.
• `org-dotemacs-error-handling’ : Indicates how errors should be handled by `org-dotemacs-load-blocks’.
• `org-dotemacs-include-todo’ : A regular expression matching TODO states to be included.
• `org-dotemacs-exclude-todo’ : A regular expression matching TODO states to be excluded.
• `org-dotemacs-conditional-tags’ : A list of tags/regexps and corresponding conditions for loading blocks.
• `org-dotemacs-dependency-inheritance’ : Whether dependency properties (:DEPENDS:) can be inherited or not.
• `org-dotemacs-noselect-on-jump’ : Whether to display or select org-dotemacs file when `org-dotemacs-jump-to-block’ is called.

Installation

To use without using a package manager:

• Put the library in a directory in the emacs load path, like ~/.emacs.d
• Add (require 'org-dotemacs) in your ~/.emacs file
• If you have marmalade-repo.org, this org-dotemacs is part of the emacs packges you can install. Just type M-x package-install org-dotemacs marmalade

After installing org-dotemacs make sure you have an ~/.dotemacs.org file and add the following lines to the end of your .emacs file:

(load-file "~/.emacs.d/org-dotemacs.el")
(org-dotemacs-load-default)

or if you want to just load code blocks matching a tag match:

(load-file "~/.emacs.d/org-dotemacs.el")
(org-dotemacs-load-default "<TAG-MATCH>")

See the org manual ”Matching tags and properties” section for more details on tag matches.

To load a different org file either customize `org-dotemacs-default-file’ or use the `org-dotemacs-load-file’ function, e.g:

(load-file "~/.emacs.d/org-dotemacs.el")
(org-dotemacs-load-file "~/.emacs.d/my_emacs_config.org" "<TAG-MATCH>")

org-dotemacs's Issues

org-dotemacs-load-file doesn't write target file

I recently upgraded from org-dotemacs-20141223.1539 to org-dotemacs-20151119.1022

Unfortunately I can't seem to have org-dotemacs-load-file write target files anymore.

Am I supposed to do things differently or set up new variables?

--- Want to back this issue? **[Post a bounty on it!](https://www.bountysource.com/issues/29275984-org-dotemacs-load-file-doesn-t-write-target-file?utm_campaign=plugin&utm_content=tracker%2F1664175&utm_medium=issues&utm_source=github)** We accept bounties via [Bountysource](https://www.bountysource.com/?utm_campaign=plugin&utm_content=tracker%2F1664175&utm_medium=issues&utm_source=github).

Add a small example to the readme?

It'd be nice to see one way the pieces can be put together :)

Is this compatible with use-package? If so, how?

Tried doing it on my own and it didn't work.

wrong type of quote in readme file

This is nitpicky for sure, but if you format the eslisp in "Add (require ‘org-dotemacs) in your ~/.emacs file" you'll get the correct type of single quote and others won't get an error when they copy this into their init file.

I'll just test to see if it makes a difference here

(require 'org-dotemacs)

(require 'org-dotemacs)

---

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

Latest org-dotemacs-load-file skips trees that lack a NAME property

I just upgraded org-dotemacs and noticed it's not loading any of the source blocks in my org file. Instead, it proudly announces "all 0 blocks evaluated successfully."

I'm rummaging through the code, but it seems that the new evaluation code uses the NAME property of the containing subtree as the key in a hash table of source code blocks.

This is a pretty large API change. The previous evaluation code didn't require NAME properties under the Org headings. Now that property is required for any code to be evaluated. Furthermore, it must be a unique name for each heading.

The current documentation still makes it seem like the NAME property is optional, just in case the user wants to implement dependencies. However, now the NAME property is not optional, it's required. And org-dotemacs doesn't provide a convenient way to add names to unnamed headings.

I can think of a bunch of ways to resolve this, but I don't know which one you'd prefer. As is, though, this completely broke my init when I upgraded via melpa.

distinguishing blocks of the same name with IDs

My org configuration has many headings and some inevitably have the same name. However, each heading has its own unique ID property.

My concern is that your package will not be able to distinguish with blocks of the same name. I would like to explore the possibility of using an ID property instead of the name. That way there we would avoid duplicate information--namely repeating the name of a heading in a property called NAME--and we could safely name our blocks whatever we want knowing each has a unique ID.

Command-line tag-match option produces error, does nothing

I gave some of the headings in my org-dotemacs file the tag “minimal”, and then specified it on the command line like this:

/usr/bin/emacs --tag-match minimal

…but, besides producing the message “org-dotemacs: tag-match = minimal,” it doesn’t seem to have changed org-dotemacs-load-default’s behavior at all. Every code block in my org-dotemacs-default-file still loads (except for the ones with a TODO state excluded by org-dotemacs-exclude-todo, as always).

But, it does produce an error, after successfully evaluating all the code blocks (the error seems to prevent post-startup hooks from running):

Unknown option ‘--tag-match’

In the *Messages* buffer, this shows up as:

file-remote-p: Unknown option ‘--tag-match’

…I have no idea why.

Looking in org-dotemacs.el, it looks like the code successfully sets org-dotemacs-tag-match but never uses it (in contrast to org-dotemacs-error-handling, which does seem to be used by the code). I’m not sure if this is related to #6, but I am using the most recent version on MELPA (20181122.445).

rewrite `org-dotemacs-load-blocks' to use `org-babel-map-src' [$100]

Use org-babel-map-src and topological-sort in org-dotemacs-load-blocks and remove org-dotemacs-extract-subtrees. I have written comments with more details in the code file (above org-dotemacs-load-blocks).

--- Did you help close this issue? Go claim the **[$100 bounty](https://www.bountysource.com/issues/7578095-rewrite-org-dotemacs-load-blocks-to-use-org-babel-map-src?utm_campaign=plugin&utm_content=tracker%2F1664175&utm_medium=issues&utm_source=github)** on [Bountysource](https://www.bountysource.com/?utm_campaign=plugin&utm_content=tracker%2F1664175&utm_medium=issues&utm_source=github).

Exclusion tag match doesn't work with 2nd level headings?

Hello,

I want to exclude certain code when launching emacs in terminal.

If I launch emacs like:

emacs --tag-match "-gui" -mm

Then this section still get's loaded although I did not want :gui: tagged heads to be loaded:

* Config 
** Menu Bar                      :gui:
 #+begin_src
 ..... menu items code
#+end_src

But if it's on the first level, then it doesn't get loaded.

* Menu Bar   :gui:

It took a while to figure out. It would be nice for this to either be fixed or documented.

Otherwise great mode. Thank you so much for your hard work.

--- Want to back this issue? **[Post a bounty on it!](https://www.bountysource.com/issues/9776824-exclusion-tag-match-doesn-t-work-with-2nd-level-headings?utm_campaign=plugin&utm_content=tracker%2F1664175&utm_medium=issues&utm_source=github)** We accept bounties via [Bountysource](https://www.bountysource.com/?utm_campaign=plugin&utm_content=tracker%2F1664175&utm_medium=issues&utm_source=github).

Split file support

I came along this interesting looking project while learning how to use Orgmode efficiently and wonder whether it is possible to split up your .emacs file with something like an #INCLUDE option or a toggleable block.

org-dotemacs-load-file doesn't behave as expected

After the most recent update from Melpa the functionality seems to be broken as the following piece of code doesn't produce an output file:
(org-dotemacs-load-file "enabled" "~/org/config/dotemacs.org" "~/org/config/dotfiles/home/.emacs.d/elisp/dotemacs.el").
Although an output can be produced by org-dotemacs-load-blocks, this functions doesn't match tags despite what is declared in specs and ommiting of unwanted code blocks must be achieved with :tangle no option.

The version from 24.12.2014 works as expected.

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

Debugger entered--Lisp error: (void-function position-if)

Org-Version 8.0.7, org-dotemacs from git (melpa).

Debugger entered--Lisp error: (void-function position-if)
  position-if(#[(x) "�\301\232\207" [x "-error-handling"] 2] ("/usr/bin/emacs"))
  byte-code("... [command-line-args errpos errval tagpos tagval org-dotemacs-error-handling position-if #[(x) "�\301\232\207" [x "-error-handling"] 2] #[(x) "�\301\232\207" [x "--error-handling"] 2] #[(x) "�\301\232\207" [x "-tag-match"] 2] #[(x) "�\301\232\207" [x "--tag-match"] 2] intern message "org-dotemacs: error-handling = %s" "'" symbol-name "org-dotemacs: tag-match = %s" provide org-dotemacs org-dotemacs-tag-match] 6)
  (org-dotemacs-load-file "~/.emacs.d/init/init.org" "{.}")
  eval((org-dotemacs-load-file "~/.emacs.d/init/init.org" "{.}") nil)
  eval-last-sexp-1(nil)
  eval-last-sexp(nil)
  call-interactively(eval-last-sexp nil nil)

org-dotemacs on windows (..I know) fails on the site-start<2> filename

Hi,

I have org-dotemacs working on linux, but my windows machine fails when the script temporarily writes out the buffer to site-start<2>, the buffer with this name is created but windows' filesystem canot handle the brackets.

windows 7, emacs 24.3.1, latest package via package manager version 2013.09.09.156

cheers,
Sander

--- Want to back this issue? **[Post a bounty on it!](https://www.bountysource.com/issues/3362452-org-dotemacs-on-windows-i-know-fails-on-the-site-start-2-filename?utm_campaign=plugin&utm_content=tracker%2F1664175&utm_medium=issues&utm_source=github)** We accept bounties via [Bountysource](https://www.bountysource.com/?utm_campaign=plugin&utm_content=tracker%2F1664175&utm_medium=issues&utm_source=github).