1 Introduction

beorg is an iOS app to help you manage your agenda, tasks and notes. It uses a simple plaintext file format compatible with a powerful system called Org mode. Edit the files on your computer in any editor - or use Org-mode in Emacs for maximum power. Org mode extensions are also available for Atom, VScode, ViM and other editors.

This manual was last updated for beorg 2.0.

2 Getting started

You can install beorg from the App Store onto your iPhone and/or iPad. When you run beorg for the first time you will need to setup syncing your org files. Either Dropbox or WebDAV can be used.

If you don't have any org files just create an empty folder in Dropbox or on your WebDAV share and you can create files from within beorg.

3 The Agenda

The agenda is the default screen shown when beorg is started. It shows the tasks for each day in the current week. A task in the agenda is a heading in one of your org files which has a scheduled date, deadline or active date.

agenda.png

Figure 1: The agenda tab

You can perform the following actions on a task:

  • Tap, to be taken to that task in its org file.
  • Swipe from left to right, edit the main details of the task.
  • Swipe from right to left, quickly set the TODO state of the task.

edit_item_from_agenda.png

Figure 2: Editing an item from the agenda

state_from_agenda.png

Figure 3: Changing the state of a task from the agenda

At the bottom right is a button to show the Quick Capture dialog.

Also at the bottom are buttons to allow you to change the week shown.

4 TODO

The TODO tab lists each org file and the tasks, including ones without dates. A summary is shown of the number of tasks and how many are overdue.

todo.png

Figure 4: The TODO tab

The same actions that are available on the Agenda tab are available on the TODO tab.

5 Files

Files is split into two sections. At the top are your favorite files. Next are all the files in beorg.

files.png

Figure 5: The Files tab

To add to favorites swipe on a file from left to right then tap Add. To remove do the same from the favorites section.

adding_favourite_file.png

Figure 6: Adding a file to favorites

To delete a file swipe from right to left and tap delete. You will be asked to confirm the deletion.

You can add a new file by tapping the add button on the navigation bar at the top of the screen.

new_file.png

Figure 7: Creating a new file

6 Settings

The Settings tab allows you to setup beorg.

settings.png

Figure 8: The settings tab

The most important section allows you to configure syncing your org files. You can sync files using either Dropbox or WebDAV.

Tasks in beorg can notify you to remind you to get them completed. Tasks with a date but no time will generate a notification at the same time everyday. Change "All day tasks start at" to the time you would like these notifications. Tasks with a time will generate there notification a certain number of minutes before the time set. Set "Timed task reminders" to how many minutes before the set time you would like these to fire.

beorg can show events from your calendars alongside your Org mode tasks. In Settings you can choose which calendars are included in beorg. This is useful if you have duplicates, such as multiple holiday calendars.

By default there are two states for tasks - TODO and DONE. It can be helpful to have more states. For example a task which isn't yet completed could be:

  • Not yet started (TODO)
  • In progress (INPROGRESS)
  • Waiting on something (WAITING)

Similarly completed tasks may need different completion statuses. For example:

  • The tasks was fully completed (DONE)
  • The tasks was cancelled and doesn't need to be done (CANCELED)

7 Sync

beorg can sync files with either Dropbox or WebDAV (this includes services such as NextCloud). Once sync is setup then beorg will sync your files when:

  • The app starts
  • If you try editing an item from the agenda or TODO tab
  • When a file is edited, created or deleted
  • In the background based on when iOS thinks it would be useful for beorg to sync

As beorg works with files it is possible that a file edited in beorg is not the latest version. If you are using Dropbox then beorg should detect this and a conflict version of the file will be created. You will then need to resolve the conflict outside of beorg. Where possible make sure that you don't have unsaved files on your computer that you are going to edit in beorg.

8 Viewing and editing files

You can view and edit files in beorg. To show a file either tap an agenda or todo item, or select the file itself from the files tab.

A file is shown as an outline. An outline is an organised hierarchy of text. You may sometimes see items in an outline referred to as nodes. An item can contain other items, known as it's children. A headline can also contain text. Here is an example of what beorg writes when you save a file you've been working on:

* Headline 1
** Headline 1.1
Some text belonging to headline 1.1
** Headline 1.2
* Headline 2

beorg allows you to fold (that is show/hide it's children) an item in the outline. To show/hide the children of an item tap on the left hand side of the screen on the headline. You can see if an item has it's children hidden because it will contain a triangle pointing right. If it's children are shown then the triangle will point down. An item with no children will show as an empty circle.

As well as viewing files you can also edit files as well. To edit an existing item tap on the right side of the screen on the headline. So you can see which item is being edited a blue line will appear on it's left.

outlining_outline.png

Figure 9: Editing an item in an outline

You can add a new item to the bottom of the document by tapping the Add Item button.

outlining_add_item.png

Figure 10: Adding a new item

The top set of icons in the edit area are as follows:

  1. Hide the editor
  2. Promote an item (that is make it a higher level heading)
  3. Demote an item (that is make an item a child of the item above)
  4. Move an item up
  5. Move an item down
  6. Add an item below the current selection
  7. Add an item above the current selection
  8. Delete the item

You should experiment with these tools before using on an important file.

Below these tools is a switch between editing the item's headline and editing the text underneath the headline (sometimes referred to as notes).

When editing an item's headline there are some additional buttons and information which appears:

  1. The state of the item. An item can be marked as TODO, DONE or a custom state you've configured in settings. If an item is in a done state then the box shown will contain a tick.
  2. Priority. An items priority is a letter between A and G. An item with a priority of A will appear higher up the list of items in the agenda than one with a priority of D. An item with no priority will appear below those items with a priority.
  3. Scheduled date/time.
  4. Deadline.
  5. Show on (or when this item should appear in the agenda but won't then be shown as overdue if that date passes).
  6. Show all item details full screen.

notes.png

Figure 11: Editing an items notes

You can view a file as formatted text by tapping the button at the top right of the screen. If you want to view just part of an outline as text long press the item and choose Export from the popup menu. The formatted view of the document or subtree can be exported as a PDF for printing or sharing via an app.

export.png

Figure 12: Viewing rendered outline

The long press menu for an item can also be used to copy the item as Org mode text to the clipboard.

item_menu.png

Figure 13: Item menu

9 Editing an individual item

Whilst you can edit an item from the file its in, often it is more convenient to edit the item itself directly from the agenda.

The edit screen contains the details about the item and its text (or notes).

edit_item.png

Figure 14: Editing an item's details

10 Dates

An item can be assigned zero or more dates. A date can be:

  • A show on date - that is the item will show in the agenda on that date, but won't be shown as overdue if that date passes and it is still marked as TODO.
  • A scheduled date - the item will be shown on that date in the agenda, and then shown as overdue on subsequent days if not complete.
  • A deadline date - similar to scheduled but indicates a hard deadline for completion.

It is often useful to set both a scheduled and deadline date for an item which is a multi-day project.

In addition to an item being assigned a specific day it can also be given a time.

The date/time editor allows you to quickly set a date to today or tomorrow, and to move forward/backwards in increments of 1 or 7 days at a time. At the top of the date dialog you can see how many days in the past/future the date is and which day (e.g. Monday) it is.

date.png

Figure 15: Setting a date

To add or remove a time to a date tap the clock icon at the top of the dialog. To remove a date (e.g. you've decided not to have a scheduled date now, just a deadline) tap the trash can icon.

date_with_time.png

Figure 16: Date with a time

The current version of beorg supports date ranges and repeating dates for the agenda and notifications, however these cannot yet be added or edited in beorg itself.

11 Quick capture

You can quickly add items to your quick capture file in one of two ways:

  • Tapping the + icon at the bottom of the agenda and TODO tab
  • Via the beorg share extension allowing you to add to beorg from other apps.

quick_capture.png

Figure 17: The quick capture dialog

12 URL Scheme

If you use apps such as Workflow or Drafts then you may find the beorg URL scheme useful. The URL scheme allows you to launch the beorg app and do one of the following:

  • Add a new item to a file
  • View the agenda
  • View a specific file

To add a new item you need to use the URL beorg://x-callback-url/capture. Without any arguments the quick capture dialog will be shown. You can also supply the following arguments:

  • title (the item headline)
  • notes
  • scheduled (a date in the format yyyy-MM-dd)
  • deadline (a date)
  • file (the name of the file, without an extension, to add to. If this is not supplied then your detail quick capture file is used)

For example beorg://x-callback-url/capture?title=New%20task&notes=Buy%20eggs&scheduled=2017-10-03&file=shopping

To view the agenda use the URL beorg://x-callback-url/agenda.

To view a file use the URL beorg://x-callback-url/file with the argument file - e.g. beorg://x-callback-url/file?file=shopping

beorg supports x-success and x-cancel arguments, however they are not mandatory.

13 Editing files on your computer

beorg writes files using the Org mode syntax. Whilst you can edit these files using any text editor a text editor which understands Org mode will work best. Org mode was written for the Emacs editor - and if you want to use all of the (many) features supported by Org mode then you will want to use Emacs. However there are plugins for other editors including Atom, Visual Studio Code, ViM, Sublime Text and others. These will only support a small fraction of what Org mode is capable of - however beorg only supports a small fraction of the power of the Emacs Org mode anyway!

14 Limitations

Org mode is a very rich, capable system. beorg only supports a fraction of what you can do using Org mode in Emacs. beorg is focused on giving you access to your agenda and basic editing of org files whilst using your iOS device. There are many things not supported by beorg. The following are currently not supported but will be in a future version:

  • Editing and viewing repeated dates (although repeated dates are used when constructing the agenda).
  • Editing date ranges (e.g. [2018-05-09]--[2018-05-12])

15 Useful resources

To find out more about Org mode - https://orgmode.org/

Download now for iPhone and iPad