• Document Structure, in particular Headlines, Structure editing, Plain lists and Motion.
• Markup for Rich Contents, in particular Paragraphs and Emphasis and Monospace.

Separating tasks from projects is inspired by the Getting Things Done (GTD) methodology, introduced by David Allen. A task can be expressed as a single action like send latest draft to John. In this case, the path to completion is clear: opening my email client, attaching the latest draft and hitting send. A project is something larger, that must be decomposed into a series of subsequent or parallel tasks, like Update paper following Jane's feedback. In this case, the path to completion isn't that clear, and writing something like * TODO Update paper following Jane's feedback isn't going to lead to anything except procrastination. Instead, it is good practice to identify the next tangible action that would move the project forward, something like Summarise Jane's feedback on first draft.

In Org terms, I define a task as any headline with an active todo state, whereas any top level headline without a todo state must be a project, containing tasks as second-level entries with a todo state. Top level headlines with an active todo state are standalone tasks.

* A project
** TODO The next action that would move the project forward

* TODO A standalone task

Let's consider the content of an example Org file named todo.org:

* TODO Update conda package for scikit-fem                     :conda:github:
* Implement parallel parameter sweeping          :python:dev:multiprocessing:
  :PROPERTIES:
  :CATEGORY: pybamm
  :END:
** DONE Get familiar with the ~multiprocessing~ module
** DONE Draft PR on enabling pickling of ~EvaluatorPython~ objects :issue_1283_pickle_python_format:
   - State "DONE"       from "TODO"              [2021-01-05 Tue 10:39] \\
     https://github.com/pybamm-team/PyBaMM/pull/1298
** TODO Understand why call to ~__setstate_~ isn't covered by tests :issue_1283_pickle_python_format:
* STARTED Draft outline of presentation for FOSDEM2021
* Prepare short presentation on Org-mode for MxResearch  :MxResearch:orgmode:
  DEADLINE: <2021-01-14 Thu 14:30>
* CAL Presentation on org-mode for productivity  :present:orgmode:MxResearch:
  <2021-01-07 Thu 15:00>
* CAL Meeting with Jane Doe
  <2021-01-15 Fri 09:00>
* CAL OxfordRSE coffee catchup
  <2021-01-05 Tue 11:00 +1w>
* CAL PyBaMM dev meeting
  <2021-01-04 Mon 13:30-14:30>
* TODO Describe packaging of ~idaklu~ C extension in issue #1296     :github:
  :PROPERTIES:
  :CATEGORY: pybamm
  :END:

Our starting point for building lists of tasks is the agenda dispatcher, which we invoke with M-x org-agenda. For convenience, this is usually bound to C-c a, but it's not by default:

(global-set-key "\C-ca" 'org-agenda)

Commands available from the agenda dispatcher, known as agenda commands, do not operate on the buffer visited at the time the dispatcher was called. Instead, they operate on a list of Org files defined by the variable org-agenda-files. Let's set it to contain our file todo.org.

(setq org-agenda-files '("~/org/todo.org"))

With this set, pressing C-c a t will display all headlines in todo.org which TODO state is TODO, in a separate buffer. This new buffer is in Org-Agenda mode, a major mode that is specific to these lists, also known as agenda views. In Org-Agenda mode, each headline is displayed in a table, the first column being the category, the second column the TODO state, and the third column the title with tags. It is possible to act on a headline just as in the original Org buffer: change TODO state, set tags and properties… With point on a headline, hitting RET will switch to the corresponding org buffer (at the location of the headline) in the current window. Similar behaviour is available by hitting TAB, but this time the Org buffer is opened in another window.

With C-c a t, you instantly get a bird's eye view of all the TODO tasks, that is much easy on the brain than painfully looking through all the entries in your Org files. The agenda dispatcher offers several other agenda commands. With C-c a T, it is possible to compile a list of headlines with a specific TODO state. For instance, hitting C-c a T CAL RET would display an Org-Agenda buffer with a list of all upcoming events.

There's a reason we described our tasks with tags and properties: Org makes it straightforward to build agenda views based on a specific combination of TODO state, tags and properties (and more!).

Let's pretend it's 13:00, my post-lunch coffee is just brewed and I've got an afternoon free of meetings ahead of me. Now would be a good time to start or continue a substantial programming task. At the time of writing, my main project is PyBaMM, a Python package to simulate and study mathematical models of batteries.

Let's build a list of candidate tasks. Let's invoke the agenda dispatcher once again with C-c a (org-agenda). Pressing m, we can compile a list of tasks that match a given set combination of TODO state, tags and property. In this case, we want to match tasks which CATEGORY value is pybamm and TODO state TODO or STARTED. Programming tasks are attached the dev tag. The string for such a match is therefore:

dev+CATEGORY="pybamm"/TODO|STARTED

Where / separates the tag/property query from the TODO state query. NEXT|STARTED matches either states TODO or STARTED.

Because our example Org file is relatively small, there's only one task that matches:

Headlines with TAGS match: dev+CATEGORY="pybamm"/STARTED|TODO
Press ‘C-u r’ to search again
pybamm:     TODO Understand why call to ~__setstate_~ isn't covered by tests :issue_1283_pickle_python_format:dev:

The syntax for matching headlines isn't very complicated. Oftentimes however, there may be several ways of writing complex queries, similarly to writing regular expressions. Speaking of which, you can also use when matching headlines. I won't go into more details about the match syntax here, because it is well described in the Org Reference Manual, see Matching tags and properties.

The ability to narrow down the content of your Org files to a list of tasks matching well defined criteria is of incredible value when it comes to keeping on top of your workload. However, some situations occur more than others, for instance starting or continuing development work on a specific project, and we don't want to continuously (re)write the same – potentially complex – agenda queries.

To avoid this, Org makes it possible to define custom agenda commands, which will be available from the agenda dispatcher, next to "list all TODO entries" and others. With this command defined once and for all, we'll then be one keystroke away from running the corresponding agenda query, just like we would do with C-c a t (org-todo-list).

To define new agenda commands, we customise the variable org-agenda-custom-commands. There's a lot of freedom in defining custom agenda commands, but sadly with great flexibility often comes complexity. So let's illustrate the concept with a couple of simple examples from my own configuration.

Org comes with a very complete support for defining and manipulating times and dates, through timestamps. To insert a timestamp at point in the current Org buffer, hit C-c . (org-time-stamp). This will open the built-in Emacs calendar in which you can navigate (using shift and the arrow keys) to select the date you want the timestamp to describe. In addition to the date, you can also write a time directly in the mini-buffer. Org accepts a lot of formats for specifying both date and time, and I encourage you to have a look at the docs for a description of each of them, see 8.2.1 The date/time prompt.

Once you inserted a timestamp, like this <2021-01-06 Wed>, you might want to modify it. Since Org is nothing but plain text, you can always rewrite its content directly. But if you change the day (for instance going from Wed to Tue), you'd have to remember to change the date as well (from 2021-06-01 to 2021-05-01). Instead, you can just put point on the day (Wed) and hit S-DOWN to go back one day. Note how the date is changed automatically. Same goes for each part of the day: to go one month forward in time, just put point on either digits of the month number (01) and hit S-UP. Note how the day is changed accordingly. You can verify for yourself, 2021-02-06 is a Saturday.

In the example Org file above, a few tasks have timestamps. Most of them are calendar events, with the TODO state CAL, for instance:

* CAL Weekly coffee catchup
     <2021-01-05 Tue 11:00-12:00 +1w>

This task has a duration of one hour, indicated by 11:00-12:00. More importantly, this task is repeated every week, hence the +1w. On next Tuesday around noon, when this tasks' state will be switched to DONE, this change will logged below the headline with the right timestamp, but the headline will go back to CAL instantly, the associated date being pushed by a week. Neat!

All sorts of repeating tasks can be defined following the same syntax, e.g +2d for every other day, or +6m for twice a year. You can learn more about repeating tasks in section 8.3.2 of the Org Reference Manual: 8.3.2 Repeated tasks.

In section 4.1, the Org agenda dispatcher (M-x org-agenda) was introduced. This dispatcher offers several agenda commands that read agenda files (defined in the org-agenda-files variable) and display some of their content in a clear manner inside a separate buffer, in Org-Agenda mode. Examples are org-todo-list (C-c a t) to list all headlines which TODO state is TODO and org-tags-view (C-c a m) to list all headlines matching a tags/properties/todo query.

Another fundamental agenda command in Org is org-agenda-list, bound to the key a from the agenda dispatcher. This displays a buffer in Org-Agenda mode representing a specific time period, by default the current week. This is effectively an agenda, hence the name Org-Agenda for the corresponding major mode.

As you would expect, any task with an associated timestamp appears in the Org agenda, at the right time and date. Upcoming deadlines are announced according to the value of org-deadlines-warning-days, clearly marked in the day's agenda whenever the corresponding task is due. Scheduled tasks on the day are also clearly signalled, and reminded of every day until they are completed.

The display of the Org agenda is customisable, by hitting v in the Org-Agenda buffer. Particularly, it is possible to go from the default weekly view to a monthly or yearly view. or day view. Going forward in time is done hitting f, backward with b. See 11.5 Commands in the Agenda Buffer.

So far, we've learned how the Org agenda can be used to either display lists of tasks matching a specific tags/todo/properties query, or an agenda displaying timestamped tasks on a timeline. However, customising org-agenda-custom-commands, introduced above in section 4.3, it is possible to define new agenda views that mix both list(s) of tasks and agenda(s).

Let's pretend its Wednesday morning, and you are sitting at your desk. In this context, a simple, yet useful, composite (or "block") agenda command is a combination of the day's agenda and the list of urgent tasks:

(setq org-agenda-custom-commands
      ("v" "Custom day agenda"
           ((agenda "" ((org-agenda-span 1)))
            (tags-todo "+PRIORITY=\"A\""
                       ((org-agenda-overriding-header "Urgent"))))))

Defining composite agenda views is similar to defining custom single agenda views (see 4.3 for a reminder), except that the third element of the list is itself a list of single agenda views, that makes the composite agenda. In the above example, the agenda view is made of both the day's agenda (agenda "") and a list of tasks matching headlines with the highest priority (tags-todo "+PRIORITY=\"A\""). Both single agenda views are are further customised by properties org-agenda-span and org-agenda-overriding-header, respectively. The first one makes sure only one day is displayed in the agenda. The second defines a clear header for the list of urgent tasks.

Custom agenda views, whether they define single or composite views, offer a broad range of opportunities for quickly displaying information based on your agenda files, in a way useful to a particular area or context. I encourage you to have a look at the the documentation for org-agenda-custom-commands, to grasp the extent of possibilities. If you are looking for inspiration, there is no shortage of example configurations available on the web, and a little searching should give give lots of ideas.

New tasks come in the form of blurry ideas, often a couple of trigger words, without any tags, TODO state or properties. Adding it to your Org file(s) straight away is therefore risky, as it is likely that you will end up forgetting about its existence, the corresponding headline being progressively buried in the depth of your todo list. Particularly as it will not appear in your agenda buffer with any tags, TODO state or properties.

By adding a tag, say UNPROCESSED, to a new headline, we can make sure that at anytime we can list all tasks that are yet not fully part of the system, and that require processing. However, I still wouldn't consider a satisfactory solution. First of all, it is very easy to forget to add the UNPROCESSED tag. If you do so, you will likely forget about the task and not noticing it until too late… hello stress! Second, when editing an Org file, there is always the risk of messing with its content, potentially altering the description of other tasks. You wouldn't want to inadvertently push the deadline for that grant proposal by a week, would you?

Both pitfalls can be avoided by using org-capture. This function lets you add a new headline to an Org file, from any other buffer, in a well-defined manner. No risks of altering anything.

For this to be true, let's bind org-capture to C-c c in the global keymap:

(global-set-key "\C-cc" 'org-capture)

Now, whatever you're doing in Emacs, for instance reading your emails or writing code, you can always use org-capture to add a new headline in a relevant location – which remains to be defined.

Calling org-capture displays a splash buffer, from which a specific capture template can be selected. A capture template defines the target file as well as under which headline in this file the captured item should be placed, with what tags, TODO state, and potentially more. By default, Org offers only one capture template, named "Tasks". Selecting this template displays a new buffer with a an empty first level headline, ready to be defined with a title, tags, properties and whatever you want to attach to it . Hitting C-c C-c will write this headline as a second level headline under the "* Tasks" entry in a file .notes in your home directory. The capture buffer is closed and you can resume your task at hand.

The behaviour of org-capture is highly customisable, through writing custom capture template as shown in the next section. However, the default behaviour already exposes the tow main benefits of using org-capture: disruption is kept at a minimum, and there is no risk of altering the existing content of the target file.

Capturing must a fast, minimally disruptive action. The main purpose of capturing is to get embryonic tasks or projects off your head as soon and quickly as possible, but with confidence that it will be processed soon, rather than lost the minute your attention shifts back to the task at hand.

Most captured items aren't exploitable yet, because they're not descriptive enough to make it to the main Org file(s). Consequently, most of my captures target a specific file inbox.org, that acts as a repository for ideas, thoughts, assignments or links to emails awaiting reply or containing important information. More generally, it's anything that pops up during the day that is not requesting my attention right away.

Periodically – in average once a day – this list is reviewed, and each headline is processed. This is when the hard thinking is done. Each headline must be clarified, its TODO state and set of tags defined, and its CATEGORY property set. This is done answering several questions such as:

• Is this a task? If yes, what's a good description for it?
• Is this a project instead? If yes, what's a good description for it? What's the goal? Does it need planning? What's the next action?
• Is this something that I want to do? Does this fit my current priorities?
• Is this something that could or should be done by someone else?
• Do I have to care about this now?
• What's the category for this task/project? (i.e. set CATEGORY property).
• What's the context for this task/project? (i.e. set collection of tags).

Once a headline in inbox.org has been processed, it is ready to enter the collection of main Org files that forms the tasks and project database. Again, in my personal case, this is a single file todo.org. Instead of cutting (killing) the headline and potential sub-trees and pasting (yanking) it at the right location in the destination Org file, Org provides the function org-refile, that helps with moving headlines around, whether it is between headlines in a single file, or across files.