Org collection readme

Introduction

Goals

The goal is to wrap org-mode customizations into collections, or project if you will, to encourage a more modularized way of thinking. See more about motivation here:

• motivation.org

This package makes it possible (though maybe still not easy) to configure org mode for multiple collections. Maybe one folder for your personal notes, and another for work? With org-collection it is easy to switch between them.

Changes

See changes.org for changes to this package that was worth pointing out.

Installation

The package currently only exist on Github and not in (M)ELPA. With (for example) use-package and straight it’s possible to load the package anyhow:

(use-package org-collection
  :straight (org-collection :type git
                            :host github
                            :branch "master"
                            :repo "Whil-/org-collection")
  :after org
  :init (org-collection-mode +1))

Global minor mode

The package provides a global minor mode (“OC” in mode-line). It does nothing on it’s own except providing a couple of functions which can be used to load, unload and switch between collections.

Notably the following:

• C-c z c (org-collection-create)
• C-c z r (org-collection-register)
• C-c z R (org-collection-unregister) (uppercase = “Reverse” lowercase key)
• C-c z l (org-collection-load)
• C-c z L (org-collection-unload) (uppercase = “Reverse” lowercase key)
• C-c z h (org-collection-visit-home)
• C-c z f (org-collection-visit-file)
• C-c z s (org-collection-visit-settings)

Org collection definition and declaration

An org collection is defined as a folder in which a collection-declaration-file named .org-collection is found.

That file is assumed to contain a lisp datastructure on the following form:

(org-collection-definition
 :name "ShortName"
 :home "home.org"
 :require (package1 package2 ...)
 :customization ((org-defcustom1 value)
                 (org-defcustom2 value)
                 (... ...)))

I.e. a list with first element org-collection-definition and the rest being a set of key-value properties where currently three keys are used:

:name

Value is a short name for the collection. Used in mode line when global minor mode is active.

:home

Value is a string containing the filename for the home file within the collection. Use it for convenience together with command org-collection-visit-home (C-c z h).

:require

Value is a list of packages that the collection depend on, will be loaded when collection is activated, unless package already is loaded.

:customization

Value is an association list of org customizations and their values. The associated value of each element in the list is stored in the CAR of the CDR of the element. Only defcustoms starting with org-, ol- and ox- are allowed. Note that quoting isn’t supported, as this list is seen as data not to be evaluated. No evaluation means no need for quoting. [fn:1]

More properties can be added but won’t be used in any way (right now anyhow).

At the time of writing this there are no validators available. There is a helper-function for creating such a file though:

• C-c z c (org-collection-create)

[fn:1] This actually means quoting won’t even work. This is unconvenient, since copy-paste of existing configurations now requires “unquoting”. But there is no workaround in place for this at the moment.

Org collection pre-processing

Before the collection definition is read there is a pre-processing step. In this pre-processing the content of the definition is parsed and some strings are replaced.

Default replacements are listed here:

:path:

Replaced with the full path to the current org collection folder.

The replacements can be reconfigured with the variable org-collection-variables.

Customizations

Org-collection-files-extension

Use this to declare what file type extension the Convenience functions working with files in the collection should use when looking for available … files! :D

Org-collection-scan-directories-recusively

Use this to declare if an org-collection applies to subfolders in the filesystem tree. As a consequence, the convenience functions that work on files in the collection will also be affected by this.

Org customizations changed by Org collection

It makes sense for some parameters to have defaults other than the “global” defaults that can be configured in the emacs initiailization.

These parameters all have customizations within Org collection with prefixes org-collection-default. Setting any of these parameters shall deactivate the org collection default which means that the parameters will fall back on either any global user customization or the Org mode default.

Parameters relying on a filesystem path should by default be set to be relative to the active org collection path:

• org-directory (set to default-directory)
• org-id-locations-file (set to default name inside path for the collection)

Some other parameters that makes sense to switch from the otherwise default Org mode default when in Org collection mode:

• org-id-track-globally (enforce it, maybe with an override option)
• org-id-locations-file-relative (enable relative paths. If not relative the collection will not (by default) be portable between filesystem-locations.)

Convenience functions

A function, org-collection-goto is provided for visiting a collection (using find-file to the path of the collection).

A function, org-collection-visit-file is provided for quickly visiting a file inside the currently active collection.

A function, org-collection-update-id-locations is provided to update the ID locations for all org files within the collection.

Selecting a collection

No collection is turned on by default. Functions for doing that, and undoing that, are:

• org-collection-load
• org-collection-unload

If no collection exist since before they can be enabled by providing a path using:

• org-collection-register

That will also load the collection.

When a collection is loaded the mode-line for org-collection-mode will show OC:collection name to signal which collection is in use.

List of stored collections

The package will keep track of previously visited collections using a file called org-collections that by default is stored inside your emacs customization folder.

Major mode…

… does not yet exist. Would be cool though! In some form or another.

What should it do? Who knows! I can imagine it giving a convenient overview of the files within the collection and a way of customizing it without having to manually changing .org-collection.

But with the global minor mode allowing for augmenting the Org mode customization for that folder, I’m starting to think that a major modes working with collections should be built outside of this package. Because all other already existing modes that work on sets of org mode files could be seen as “org collection major modes”. Those modes just needs to be configured for the collection at hand.

Misc

Read about some thoughts while building this here:

• motivation.org
• ramblings.org

Potential future ideas

Custom file link

Would be cool to be able to create links between collections based on collection name and note ID’s.