Features and Org mode Basics

EasyOrg is based upon Org mode which is a structured way of writing text files. There is nothing special to an Org mode text file other than that some special keywords and formatting are used and this formatting can be interpreted by EasyOrg and other tools supporting Org mode such as Emacs.

Org mode Basics

Below is a basic overview of the Org mode syntax as well as how this integrates with the features provided by EasyOrg. You can find a more complete documentation of Org mode on the official Org mode site.

Headlines and Text

Headlines in a document start with one or more stars '*'. The number of stars denotes the Headline level.

* Headline level 1
Body text below the headline

** Headline level 2
More body text.

*** Headline level 3

Todo items

A TODO is simply a headline with the keyword 'TODO' after the star(s). You can use more than one star to denote its level within the document.

* TODO This is a todo.
This is body text belonging to the todo. Here you can
write text and note covering multiple lines.
- List item 1
- List item 2
You can also include list items in the TODOs body text.

A TODO can have several states. By default there is TODO and DONE. You can define and add custom states as you like. For example WAIT, CANCELED, PENDING etc.

Nested Todo items

One or more TODOs below a parent TODO will belong to the parent. In the Agenda, when using the 'By Header' view, you will see the sub-todos listede below its corresponding parent todo.

** TODO I'm a parent todo

*** TODO I belong to my parent todo which is on level 2 (**)
I'm on level 3 (***)

*** TODO I'm a child AND parent todo
I'm on level 3 too.

**** TODO Level 4

Tags

A TODO can have one or more tags which is a way to label or categorize the TODO.

* TODO This is a todo with tags.              :work:expenses:

Priority

A TODO can have a priority level attached to it. A priority is added between the TODO keyword and the Headline text. By default it's a character 'A', 'B' or 'C' written between square brackets preceded by a hash '#'. 'A' is the highest priority and 'C' the lowest. If no priority is explicitly assign to a TODO then it is considered having priority 'B', i.e. it is in the middle.

* TODO [#A] This todo has the highest priority.

It's possible to assign more levels and also define the default priority level.

Lists

You can create unordered and ordered lists. Just write each list item on its own line with a dash '-' or '+' in front.

- Item 1
- Item 2
- Item 3

For ordered lists start the line with a numeric value followed by a dot '.' or right parenthesis ')'.

1. Item one
2. Item two
3. Item three

Checkboxes

Inside a TODO you can add a list of items with checkboxes. They are useful in cases where a TODO consists of several small steps that you want to keep track of and check off one by one. You create an empty checkbox using brackets with a whitespace in between [ ] and a checked checkbox with an 'X' instead of whitespace: [X]. The list of checkboxes should be in the body of the TODO.

A TODO with checkboxes could look like the following:

* TODO An example with checkboxes in the body text.
In the body we can add a list of small tasks with checkboxes.
- [ ] I need to do this.
- [X] I have done this.
- [ ] And I also need to do this.

Scheduling

A TODO can have a deadline date and time and/or a scheduled date and time. Deadline means it should be done by this date and scheduled means the TODO is meant to be worked on at this date and time.

A deadline or schedule is added just below the headline of a TODO as shown in the examples below.

* TODO A todo with a deadline.
DEADLINE: <2020-02-18>
* TODO A todo with a scheduled date.
SCHEDULED: <2020-02-18>

A TODO which has a deadline or is scheduled will show up in the Agenda views based on these dates.

If you have a regular meeting at a certain date and time you should use an Active timestamp as explained in the section below and not a SCHEDULED or DEADLINE keyword.

Active and passive timestamps

Related to DEADLINE and SCHEDULE are the active and passive timestamps. An active timestamp will cause an entry to be visible in the Agenda and sorted according to its date. Typically active timestamps can be used to define a meeting date. An active timestamp is a timestamp written within angle brackets. Example:

* Meeting about EasyOrg
<2020-02-18 Tue 13:00>

A passive timestamp is a timestamp written within square brackets. They do not make the note/TODO to show up in the agenda. They are used more as a reference and form of documentation. Example:

* Paid back 100 USD to Steve.
[2020-02-18]

Active and passive timestamps can be attached to regular headlines and texts and don't have to be used exclusively with TODOs.Please not that in EasyOrg currently only TODOs are shown in the Agenda view. A coming upgrade to EasyOrg will include a an Agenda view that shows all notes and text in the agenda.

Effort

When you write down TODOs you plan to make it can often be useful to add the amount of effort you expect it to take. This information can be used in the Agenda to for example easily find TODOs that can quickly be made in case you have some spare time at hand. They can also be used by EasyOrg to estimate the time it will take to complete a set of TODOs within a project or sub-project.

* TODO Fix typos in document on page 5.
:PROPERTIES:
:EFFORT: 0:15
:END:

EasyOrg provides an easy way to add Efforts to your document.

Drawers and Properties Drawers

Drawers is a special construct where you can store data or metadata related to a note or TODO. You can easily hide and show the drawer data in the editor. You already saw an example of a properties drawer in the Effort section above. The PROPERTIES drawer is a special drawer used for storing properties. You are free to give your properties any name you want.

:MYDRAWER:
Here is some text which I might want to hide and only refer to sometimes.
:END:

Links

Internal Links

Internal links are written like:

[[this-is-an-internal-link][Link name]]
[[internal-link-without-explicit-name]]

To link to another Todo within the same document one can create a link target on this other Todo. By adding the same text within angle brackets '<<>>' as in the link we can link them together, eg. <> would be a link target for the above link. The link target should be unique within the document.

External Links

External links to websites are written like:

[[https://www.example.com/a-page][External Link Name]]

External links to files are written like:

[[/home/john/documents/example.org][My Friendly Name]]

EasyOrg Features

The EasyOrg features mirror to a large extent the above mentioned Org mode syntax. Several of the EasyOrg features are explained in the Editor and Agenda sections of this documentation. Below we explain some of the EasyOrg features specifically related to Org mode.

Add/Edit Todos

You can add a Todo by using the 'Add Todo' button in the upper right corner. A Pop-up window will show a form where you can write down a header text (mandatory), a body text (optional) as well as, if you like, select a priority level, assign one or many tags and select the Todo state (eg. TODO or WAIT). You can also chose which heading in the text document the Todo should be placed under. When you press 'Save' the todo will be placed in the text file and you will also see it in the Agenda.

It might be that you have to scroll to see the newly added Todo in case it is not directly visible due to it's sorting, timestamps and priority.

It's also possible to edit a Todo by using the GUI. Simply click the options menu shown as '...' in the lower right of the Todo and select 'Edit'. The Edit pop-up window will show a form with the current data of the Todo. You can edit as you like and then press the 'Update' button. You can also press the 'Cancel' button and any edits you made in this window will be discarded.

Note that you can move around the pop-up window in case it is covering text you want to refer to in the Agenda. You can also scroll the agenda as necessary while the Add/Edit window is open.

Delete Todos

You can delete a Todo by using the options menu shown as '...' in the lower right of the Todo. Click 'Delete' and a confirmation pop-up will show to confirm you want to delete.

Change State

You can change the state of a Todo by right-clicking on the Todo's header and from the context menu that appear select 'Change State' and then the state you want to change it to.

Screenshot of context menu

You can of course also use the Editor window to change the state if you like.

Priority

You can insert the TODOs priority from the Agenda panel by using the right mouse-click context menu and selecting a priority level.

Efforts

From the Agenda panel, using the right mouse-click context menu on a TODO you can insert the estimated effort required to complete the task. If the task already has an effort, then it gets updated to the new value.

You can also insert the effort template from the editor menu if you prefer. Place the cursor on the TODO you want to add the effort to. Once inserted you have to add the value yourself in hours, for example 0:30 for 30 minutes, 1:00 for 1 hour.

In the editor you can hide and show the Effort drawer in case it makes the document too busy. You do that using Ctrl+right-arrow to hide and then show it again with Ctrl+left-arrow.

In the agenda the effort it shown in the TODO header within square brackets just next to the priority in case it's defined for the TODO (eg. [0:30]).

Tags

When creating or updating a Todo via the GUI you can select existing tags to add to your Todo or create new ones by typing them out. Tags which have already been used in the current file will show up in the Tags selector. This makes it easy to pick existing ones instead of accidentally creating duplicates with slightly different wording.

Timestamps and Scheduling

Timestamps can be added to an existing Todo via the actions button in the lower right of the Todo. Select 'Deadline' or 'Schedule' and a Datepicker will show up where you can select the date and time.

You can delete a scheduling timestamp using the same actions button and selecting 'Deadline' or 'Schedule'. If there is already a scheduling timestamp these menu options are in red and with a crossed-over symbol.

Promote To Today/Tomorrow

The 'Do Today' and 'Do Tomorrow' functions in the Agenda panels context menu gives you the possibility to set the SCHEDULED timestamp to today or tomorrows date respectively. This feature is useful for example at the start of your day you can go through your list and mark the TODOs you want to do today. Similarly, in the evening, you can go through your list and mark the TODOs you want to do tomorrow.

Reveal TODO from Agenda <-> Editor

In the Agenda panel, if you left-click with the mouse on any TODO header, the same TODO will be scrolled into view in the editor.

If you right-click with the mouse and select 'Reveal Parent' in the context menu, the TODOs parent heading will scroll into view. This could be useful if you want to see which heading it belongs to of if you manually want to add another TODO just below the heading.

Similarly, if you right-click with the mouse on the TODO header in the editor, and select 'Reveal in Agenda' from the context menu, the TODO will scroll into view in the Agenda panel.

These features are convenient to find the TODO in each respective panel.

Closing Notes

When marking a TODO as DONE, whether from the editor or from the Agenda, a 'Closing Note:' row is added as the last line of the body including a timestamp when the TODO was marked as done. Here you can add any text you want related to the TODO such as how you solved any issues, reasons why you did it a certain way or any other short or long details for future reference.

Links

You can add links to your Todos and you can follow the links by clicking on them in the Agenda. Internal links link within the same document and external links link to web pages or to files on your computer. Clickable links are underlined to easily identify them.

See the Org Mode Basics section for syntax and more details about links.

Internal Links

Internal links link to link targets within the document. Link targets are unique names within double angle brackets, eg. '<>'. The link target should be unique within the document as it will jump to the first found link target with that name.

You can follow a link by clicking on it.

Once you have jumped to the link target and you want to go back to the Todo where the link was, you can click the back button in the menu on top. This arrow button is only visible in case you have already followed a link. You can jump several steps back in case you followed several links in succession.

External Links

External links link to websites or files on your computer. Following a website link opens the web page in your web browser. Following a file link opens the default application for that file type.

Advanced

There are several more advanced features within Org mode. Many of them are related to configuration.

STARTUP blocks

Below is an example of a STARTUP block. You would use a STARTUP block to configure on a per file level how you would Org/EasyOrg to work. This is great if you want to use a few different Org settings in a specific file, but for most file just use the settings you have defined via the settings window.

Any settings you do on a file level would override the global settings made via the settings GUI or default Org behavior.

#+TODO: TODO WAIT | DONE CANCELED
#+PROPERTY: Effort_ALL 0 0:10 0:30 1:00 2:00 3:00 4:00 5:00 6:00 7:00
#+STARTUP: lognotedone
#+PRIORITIES: A D C

Let's break down what each line above does.

This line sets the TODO and DONE states you would like to use in a particular file. #+TODO: TODO WAIT | DONE CANCELED

This line defines the property Effort_ALL which is used to define the effort levels used in your file. In this case 10 minutes, 30 minutes, 1 hour, 2 hours, 3 hours etc. #+PROPERTY: Effort_ALL 0 0:10 0:30 1:00 2:00 3:00 4:00 5:00 6:00 7:00

The following line defines how you want to handle logging when changing the state to DONE. In this case we say that we want to log with a Closing Note and timestamp. #+STARTUP: lognotedone

Setting the above to logdone would mean only mark it with a closing timestamp. Setting it to nologdone would tell EasyOrg to not log anything when marking the Todo as DONE.

The last block lets us define the priorities used in this file using the letters from A to Z with A as highest priority. The first character position defines the highest priority (A in this case), the middle defines the lowest (D) and the last character defines the default priority (C). The highest priority character has to come before the lowest priority character in the alphabet. #+PRIORITIES: A D C