learning_todos.org

Todo Basics

This is a simple study in managing your daily ins and outs using OrgExtended. Org is a swiss army knife. It is, what you make of it.

While this tutorial IS looking at some of the organization tooling in org mode AND many people have used org mode to implement a full GTD or other organization system. This quick introduction is not going to go anywhere near that deep. Instead we will try to introduce you to some of the basics of orgmode and encourage you to dig into some of the references on the primary page for more ways to use orgmode to help organize your life.

As a side note, it is because orgmode has been used to implement systems like GTD that has been part of the popularity of using in emacs email clients like mu4e for email, google calendar and jira sync systems etc. Many of these types of tools can help to create the kind of complete, fully integrated and very powerful systems for organizing your life.

That said, org mode is much more than just a means or organizing your life in plain text. It has its roots in reproducible research, has been used as the basis for authoring presentations, wikis, websites. It is a spreadsheet, a means of creating living documents, a writers tool and much much more.

Okay, lets get started.

First, create a new file with a .org extension, such as todo.org

Keybindings for these operations can be found in the keybindings file. You can find the keymap in the package settings menus.

• For regular users most of the org bindings are under Alt+o
• For NeoVintageous users most of the bindings are behind <space> in normal mode with the same followers as the Alt+o equivalents
• If the key binding does not immediately work, make sure your current file ends in “.org” (or any valid extension from validOrgExtensions in your OrgExtended user config).

Our study begins with taking structured notes. We are at a meeting, during that meeting we flow in and out of topics. As I take notes it helps to be able to put each topic under it’s own sub heading.

As we do this, I am using insert heading and insert child.

Alt+o i h and Alt+o i c

Another way to do this is to use Ctrl+Enter This runs the Do What I Mean (DWIM) Insert mechanism. These DWIM commands are context aware operations. Org has several primary DWIM commands:

• Execute
• Toggle
• Insert
• Fold

Using the insert DWIM operation, what happens depends on where I am in my document.

• If you are on a checklist it will insert a new checklist item.
• If you are on a numbered list it will insert the next entry.
• If you are on a heading it will insert a new heading.

Basic note taking is pretty straight forward. Org uses stars much like markdown uses the number sign to denote heading levels.

** My Meeting
   We are taking some notes for this meeting
*** Sub Topic 1
    These notes belong to sub topic 1
**** Sub Sub Topic 1
     A sub topic of the sub topic.
*** Sub Topic 2
    More notes

As I am taking notes I realize I have some things I need to do. We might call these action items. Org expects that todos come up anywhere in your work. You need to mark this thing as a todo. Org expects that action items flow through a stateflow. They start in a new state and progress through a flow of your designing. Sadly, I have not found a way to easily allow you to extend OrgExtendeds syntax highlighting! That said, OrgExtended still accepts custom todo state flows.

The default state flow is defined globally in your config file. if you would like to tweak this you can edit the list in your config file:

"todoStates": ["TODO","NEXT", "BLOCKED","WAITING","|", "CANCELLED", "DONE","MEETING","PHONE","NOTE"],

The vertical bar defines the states that are considered “open” and the states that are considered closed by org. You can also create a custom flow in an org file by defining a todo comment in your org file:

#+TODO: REPORT BUG KNOWNCAUSE | FIXED

A todo is simply a heading with a TODO keyword as the first item on the line.

* TODO This is a todo

This is now recognized by org as a TODO that needs doing. So as you author your meeting notes, you realize that your todos are right in the middle of your meeting notes. You are going to need to take those out of your meetings notes and add them to your own todo lists right?

• Actually you don’t need to.

Org expects that as things come up, you jot them down in context relevant locations. One of the many things that org mode tries to do for you is provide the concept of the agenda and filtered todo lists to make managing your todos less labor intense. When OrgExtended starts up, it parses all valid files in your orgDir to build your agenda and any todo views you have defined. These views are customizable in their own right, but we will gloss over that for the moment.

OrgExtended will parse these files in the background as it starts up. The more files you have in your active list, the longer this background initialization will take. That said, OrgExtended tends to make fast work of quite a few files.

// Where are your org files?
"orgDirs": [
    "c:\\Users\\ian\\notes"
],

// Specific files to add vs whole directories
    "orgFiles": [
],

// Directories to exclude from parsing org files
"orgExcludeDirs": [],

// Files to be excluded from org parsing
"orgExcludeFiles": [],

So now what? Org knows about the todos. How does that help me? We will talk about tagging later, but for the moment a little demonstration can be beneficial.

I am going to add a random todo to a file, I then I will call up a generic todo view and it has my todo in it. I can then jump to the todo quite easily.

Okay, so that’s already pretty useful. I can add action items anywhere and find them and jump around after the fact. Org Mode goes further. It helps to add meta data to your work to give context:

• When are you planning to start it?
• When does it need to be done?
• Is this an appointment verses a project?
• Are there subtasks? If so, what is the next thing you need to work on?
• Do you have a time estimate associated with this thing?
• Is it associated with an external bug tracking system, if so what is the ID?

Etc Etc Etc.

Lets continue with the examples. Here we are going to work with the Do What I Mean insert and toggling functions. The toggling function will not only change the todo state of a heading it will change the state of a checkbox etc.

<space> t
Alt+o t

I am going to insert some headings, set them to todos and add a scheduled entry.

* TODO Project A
  SCHEDULED: <2021-02-15 Mon 10:41>
** TODO Task 1
*** This is a sub task

Org Everywhere

Before we continue and discuss the next logical step, the agenda, we should make time for a little aside.

While this is useful, todos are more useful if you can access them from everywhere. Org becomes more useful if you can access your org files from your mobile device. I find it handy to store my todo lists in dropbox while my notes are often stored in a git repository. There are several mobile orgmode viewers. I personally use Orgzly.

Orgzly can sync with dropbox automatically for you and show you your todos on your mobile device. It can also read your schedule information and notify you about up and comming events.

In the past I have synced some of my todos with google calendar or jira. I have yet to write a plugin to do so with my org files on sublime, although this is entirely possible.

Agenda

At this point you have a simple todo list, it is in the middle of my notes! We have added a SCHEDULED tag, but our todo list doesn’t really convey that information!

This is where the agenda comes in. There are a number of agenda views and I hope to help you build your own in the future. You will need to read the more in depth sections of the docs on how to customize your agenda views. For now we will stick with the default view.

Based on how you have your agenda configured your agenda can find your todos in your files. It is really just a set of fancy todo views that let you visualize your todo content in more schedule oriented ways.

The todo list and the agenda both support enter to open a file in the primary sheet while space will open it in another tab.

I modified the time in the scheduled note by pulling in the time a little. This is because I have my agenda restricted to only show working hours and it wouldn’t make much of a demonstration if it did not appear on the agenda.

To bring up the agenda I use the “org agenda” binding. This brings up the Default agenda view from my config file. By default it is a composite view that I find useful.

Alt+o o a

of for vim users

<space> o a - in normal mode

As I mentioned before, there are agenda specific keybindings. If you press enter on an item you will jump to it. If you press space it will open up in a different layout window. You can clock and change status from within the agenda as well.

In the example I use the SCHEDULED marker. These are a powerful yet complicated part of org mode.

We don’t currently support the full gamut of org functionality, we support a lot, but not quite all.

In particular some of the recurrence options with timestamps is still poorly supported, but will hopefully improve in the future. Dates and Times

SCHEDULED

This marks where you want to START working on something it will appear in the agenda until you close the task. So generally this is used on tasks that may take some time.

DEADLINE

Like scheduled this marks where you want to be DONE working on something. You can specify a warning marker in the time. By default you will get a warning 1 day before your deadline. If the task is still open after the deadline it will be marked as overdue.

< Active Timestamp >

without a deadline or scheduled prefix this event will happen once at the selected time.

CLOSED

There is one other timestamp that can be handy. If you enable logdone, when you flip a TODO to it’s done state you will get a CLOSED marker indicating when you closed the task. You have to enable this with the STARTUP comment set to logdone.

Contents

At this point it is tempting to dive into a deep dive all the ways org can help you author content for your notes. There really is a lot that org can help you out with. Things like:

• Priorities
• Unordered, Numbered and Checkbox Lists
• Diagrams
• Tables

And much more

That said, those are out of scope for this tutorial. We need to be focused on todos and todo tracking.

Links

So, at this point you have been authoring your notes and todos, you can find your active todos within your notes. Sometimes however, you want to leave a trail of breadcrumbs for yourself. Or perhaps you want to store an external link and easily jump to it later.

Org links are fairly powerful. You can link within a document by creating dynamic targets:

<<Anchor>>

That said, any heading is itself a dynamic target:

[[file:myfile.org::*MyHeading]]

External links work as well, org will try to collapse the url portion of the link to hide those unsightly urls.

[[http://myurl.com][Some Text]]

Of course org tries to help you here to. You can create a link to a file using a command or use a snippet to insert a new link:

<l

These links are all active. Pressing enter on a link will follow the link. This makes your org directories a bit of a personal wiki. This is yet another way to manage your todos.

Tagging

Links are great, but, as you get more todos things can get confusing. Org offers tags and properties as a means of adding meta data to your items and going beyond simple todo lists and links.

You can tag any heading with a tag (or multiple tags). A tag looks like this:

:TAG:

Multiple tags look as follows:

:TAG1:TAG2:

Tags go at the end of a heading:

* My heading              :TAG:

Once you have tagged it you can start to filter based on that tag. Here I am going to use a generic filtered todo view to only view todo items tagged with TA.

* A heading
** TODO Task 1                                                            :TA:
** TODO Task 2
** TODO Task 3                                                            :TA:
** TODO Task 4

It’s pretty easy to create a custom todo view with a tag filter.

Tags are recursive. They apply to the entire subtree. Every org file is a rooted tree of nodes. You can apply tags to all headings in a file using the filetags comment. I find it useful to add a REFILE tag to all the items in my refile file.

#+FILETAGS: TAG

Tags are not the only way to curate your data. Property drawers and properties are another way that org allows you to add meta data to your notes. Property drawers are a common means of tracking notes that live elsewhere, such as google calendar, or in jira. Or tag an item with metadata such as estimates of how long a task will take. In fact column mode in emacs (which we don’t yet support) is all about tabular editing of properties associated with a document.

* Heading
  :PROPERTIES:
    :KEY: Value
  :END:

Org Extended will try to fold property drawers automatically to avoid clutter. Property drawers are the most common example of one of org modes generic meta data features. Drawers can be named anything are look a little like tags after a heading. OrgExtended will try to fold these up to hide the clutter, since these are often meta data that we don’t want to examing that often.

Capturing

So at this point you have a pretty decent introductory view of some of the pieces in managing your todos with org mode. There is a lot that we have not covered. That said, any coverage on note taking and todos would be incomplete without talking about:

• Capturing - A quick means of grabbing information and forgetting about it.
• Refiling - A means of moving your data around after after you have written it.
• Archiving - Hiding the work after you are done with it.

Indexing and Goto Anything

Before we get to the OrgExtended features, I think it helps to mention that OrgExtended has some support for sublime indexing. Headings use standard tags that allow sublime to index your files. If your notes are an official sublime project goto symbol should work out of the box:

Archiving

Lets start with the end. Archiving is a means of taking a project, todo, or general heading and storing it in an archive file after you are done with it.

Org will place the heading in an archive file that you have specified. This is controlled globally with the archive entry.

"archive": "%s_archive::* Archive",

Here we archived an entry in learning_todos.org and it was archived to a file called learning_todos.org_archive under a heading called Archive.

This can also be controlled locally with the archive comment:

#+ARCHIVE: %s_archive::* Archive

Refiling

In my mind refiling is all about Getting Stuff Done. In some of the popular literature some authors talk about the concept of having an inbox or quick capture box. This inbox helps you clear your mind. The value of the inbox is later realized as you regularly triage it to put all your data, tasks and information where it needs to go.

This is simulated with the help of the refile command in Org Extended. I have a refile.org file and I regularly triage it using the refile command.

ASIDE: We are working our way BACK to capturing. Talking about refiling first will help motivate why capturing is a nifty feature. Refling is NOT perfect, but it is getting better as I use it and improve it.

Here I am refiling a heading in one of my org files to a specific heading in a different org file: test1.org The quick search box has headings across all your known org files and fuzzy search helps you find what you are looking for. Selecting the heading will have it vanish from this file and appear in the remote file. This is really just a more generalized version of archiving.

Capturing

When I am working on something and have an idea. I want to capture it quicky and move on. Org capture lets me do just that. From my capture definition I can choose how I want the quick capture behaviour to work. I can choose to pop into my refile file directly or open up a panel. The template is a snippet that you specify in your settings file.

NOTE: The panel can be tricky to navigate for neovintageous users, make sure you are in insert mode.

Capturing lets you quickly open a panel, shove the results somewhere useful and move on.

Done

Now you know the basics! I hope you found this useful.