Skip to content

Guide

Jump to bottom
Gregory Dushkin edited this page Sep 17, 2020 · 9 revisions

NOAFtodo guide

NOAFtodo guide is under developement. Some parts of it are finsihed, some yet to be written. Anyway, I hope you find it useful

Lets agree on following:

$ this # is a shell command

and

:this # is an internal NOAFtodo command

On a single line we will use shell_command and :internal_command. OK? Let's begin then!

Building/installing

AUR

If you are an Arch/Arch derivative user, you're lucky. NOAFtodo is available in AUR as noaftodo-git (yay -S noaftodo-git is your friend. Or any AUR helper of your choice). Cool!

Building

If not/you just want to build it yourself/maybe, even contribute, build NOAFtodo using cmake to produce build files and then GNU make to build the program:

$ cd path/to/noaftodo/repo
$ mkdir build && cd build # you can use any directory for building, but build/* is already configured to be ignored via .gitignore
$ cmake .. && make  # replace "make" with "gmake" on Solaris 11 and maybe some other systems

sudo make install also should put noaftodo binary to /usr/bin.

Dependencies

  • ncurses (on an Arch-based system: sudo pacman -S ncurses, on a Debian-based system: sudo apt install libncurses5-dev)
  • (optional) libnotify (libnotify and libnotify-bin on Arch and Debian based distributions respectively) and a notification daemon of your choice: provides notification support notify-send command used in default config

Build flags

Specify build flags as FLAG_NAME=1 or FLAG_NAME=VALUE before running cmake.

Flag name Flag description
NO_MQUEUE Compile with a primitive replacement to message queues from mqueue.h, in case you don't have one on your system, or don't want to use it (on by default on Haiku)
NO_ROOT_CHECK Disable checking EUID for root privileges. Can be achieved by setting allow_root to true in config, but on some platforms (like Haiku) better remove this feature at all (on by default on Haiku)
DEBUG Just tuns on -g3 flag
PKGROOT PKGROOT value, if set, will be used as a path to package root during make install. Used, for example, while making package in PKGBUILD
PKGNAME PKGNAME value, if set, will specify the name of the directory under $PKGROOT/usr/share/licenses/ and $PKGROOT/etc/ where other program files are installed (again, see PKGBUILD)

First launch, basics

Hey, you've got this far! Time to launch NOAFtodo for the first time.

Upon first launch, if not told otherwise, NOAFtodo creates two files:

  • default list .noaftodo-list in $HOME
  • default config (see noaftodo.conf.template) noaftodo.conf in $XDG_CONFIG_HOME or, if it's not specified, $HOME

If $HOME and $XDG_CONFIG_HOME are not specified too, both files are going to be created in current directory.

You are greeted with an almost empty terminal window: only title and status bars. Status bar displays something like

Welcome to NOAFtodo! | NORMAL | All lists | UVCFN_

First one is just a welcome message. Some commands can put their output there too.

The second field displays current mode. There are 5 modes:

Mode Default shortcut Description
NORMAL None Default mode - view list and navigate through it
LISTVIEW L NOAFtodo supports assigning tasks to multiple lists (called "tags" internally). In this mode you can view and switch between them as in a regular list
DETAILS ENTER Displays selected entry information in a box. It looks pretty. Scroll text with left and right arrow keys (yeah, very intuitive, I know)
COMMAND : Command mode, where magic happens. Basically the same thing as in most terminal applications when you press :
HELP ? Remember DETAILS box? I copy-pasted it and made it show the list of commands and their descriptions. Scrolling with left/right arrow keys, as in DETAILS

Then goes the list (see LISTVIEW descriptsion) number and name. By default, program shows entries from all lists, that's why it says what it says.

Finally, the filters. Besides tags, entries can displayed/hidden based on 5 attributes:

Visibility flag (Default) switch with Description
U Yes, you've guessed it, U Entries that don't fall into any of the following categories
V V Completed entries
C C Upcoming entries (the ones that have 24 hours or less left until their due)
F F Failed entries (due now or in the past)
N N "nodue" entries. Don't have a due, therefore, can't be upcoming or failed

The last attribute (0, default switch key - ( = Shift+0) shows/hides from LISTVIEW lists that don't have visible entries.

The attributes that are filtered-out are shown with _ (as you can see, by default all entries are shown, but empty lists or list that don't have visible entries are filtered out).

You can also filter tasks (and lists in LISTVIEW) by their names/descriptions using regular expressions. Default key for this is /. If regex filter is not empty, it will be displayed in filter section. For example,

NORMAL | All lists | UVCFN_ [e abc] [l def]

means that you are seeing entries that match abc pattern and lists that match def pattern.

On a non-empty list, status will also by default show the selected entry ID, last entry ID, and percentage of entries that are cpmpleted:

NORMAL | All lists | UVCFN_ | 0/10 | 10%

By default, NOAFtodo should also start a background daemon (and kill it upon exit). If you have notify-send (see Building) on your machine, you should see a notification that will confirm that the daemon is launched. You will also be notified about task status updates, deletion, completion.

Exiting noaftodo is easier then ever with quit command (:q) bound to q and ESC keys by default.

Basic commands and default binds

Adding your first task

It's time to add your first entry. Press A. You will be moved to command mode: status bar will disappear, replaced by a command prompt:

:a

:a is a command for adding entries. Its syntax:

:a <due> <title> <description>[ <id>]

<id> is optional, it is used to replace existing entries instead of adding new ones. <title> and <description> are self-explanatory. If fields contain spaces or semicolons, you should put them in quotes or put a ** before every space or semicolon. <due> is where it gets interesting. Date/time is specified as:

  • [number]y - year
  • [number]m - month
  • [number]d - day
  • [number]h - hour (24-hour format is used)
  • just a [number] with nothing after - minute

A few examples:

  • 2020y06m07d12h15 - the 7th of June 2020, 12:15
  • 14h30 - 14:30

<due> value could be interpreted in two modes: absolute (default) and relative:

  • absulute: values specified in <due> override current date/time
  • relative: values specified in <due> are added to current date/time

Modes are switched with a. Assume now is the 7th of June 2020, 12:15. Some due strings and what they mean in that case:

  • 45 - take everything as it is now, override minutes to be 45 = the 7th of June 2020, 12:45
  • 30d - take everything as it is now, override day to be 30 = the 30th of June 2020, 12:15
  • 70d - ...., day is 70 = 70th of June = the 10th of July 2020, 12:15
  • a45 - take everything as it is, switch to relative mode, add 45 minutes = the 7th of June 2020, 13:00
  • 17h00a1d - take everything as it is now, set hour to be 17, minute to 00, switch to relative mode, add 1d = the 8th of June 2020, 17:00
  • 2021y14h00a1m1d - take everything as it is now, set year to 2021, hour to 14, minute to 00, switch to relative mode, add 1 month, add 1 day = the 8th of July 2021, 14:00

That should be enough for everyone to understand NOAFtodo due format.

Add your first task, for example:

:a a1d "My first task" "This is my first task"

For the command above, it should appear in the table and get C flag assigned as its due is in less than 24 hours.

Tasks by default are assinged to the list you are currently viewing. If you view all lists, it's assigned to list 0.

Marking task "completed" and deleting a task

Press space. Task should be marked "completed": it will turn green and get V flag assigned. To delete the task, press d. Notice, that it doesn't execute corresponding command (:d) immediately, but instead puts you in COMMAND mode with it pre-typed. Confirm deletion by pressing ENTER. Your list is empty again.

Editing a task, task meta properties

You can edit a task by executing:

:a <new-due> <new-title> <new-description> <task-id>

(bound to e and by default autocompleted all fields with their current values). :a command means that, in fact, a new task is created the old one is getting replaced with it.

You can also directly edit task properties with:

:set title <new-title>
:set desc <new-description>
:set due <new-due>

One more thing to know about tasks is task meta properties. Task meta string is set with

:setmeta <prop_1> <val_1> <prop_2> <val_2> ...	# replaces old meta
						# or
:setmeta %meta% <prop_n+1> <val_n+1> ...	# appends meta values without ressetting meta

Supported meta properties:

Property name Property Description
nodue true or false (= anything that is not true) - disables task due checks. nodue task can't be failed or upcoming, but you can complete it. Shortcut for creating a nodue task: :a - <title> <description>
warn_time Custom time for the entry to be counted as upcoming. If not set, interpreted as "1d"
on_completed, on_uncompleted, on_failed, on_coming on_edited NOAFtodo internal command to be executed on task completion, when the task is switched form completed to not completed, when task becomes failed or upcoming
ignore_global_on_failed, ignore_global_on_coming, ignore_global_on_removed, ignore_global_on_completed, ignore_global_on_uncompleted, ignore_global_on_edited When set to true, makes the task ignore global events

All on_... events are executed by a daemon and won't work without it running.

Switching between lists

New lists are created automatically when you rename them or add new tasks to them.

From command mode

From NORMAL mode, press : and run

:set tag_filter <list_id> # go to list with any number

From LISTVIEW (go only to existing lists and lists in between them)

Go to LISTVIEW (L). Select wanted list and press ENTER

Renaming a list

When viewing a list:

:set pname <list_name>

Assigning task to a list

:set parent <list_id>

NOAFtodo command interpreter

NOAFtodo command interpreter is not very advanced, but still does a more than a simple program command interpreter should do.

Variables

(aka console variables aka cvars)

Let's start with variables. Variables are set with

:set <var_name> <var_value>

Some of them represent internal program variables (list incoming... soon), others are created by you, for you. If there is no variable named var_name, :set command will create it.

Executing just

:set <var_name>

will reset variable var_name to its default value or, if one does not exist, will just delete it.

There is two ways to access a variable's value:

%var_name%	# is replaced with variable value as-it-is
%%var_name%%	# is replaced with variable value with '\' before all "special" characters
		# by the way, comments start with '#' if you didn't guess yet

In this guide, we will highligh variable names as %varname%.

Let's try it now!

:set a "a bc"	# set variable a to "a bc"
:echo a		# prints "a" in status
:echo %a%	# prints "a bc" in status
:echo %%a%%	# does the same as previous command,

# but let's see the difference between
# % and %%

:set b %a%	# <=> :set b a bc : b is assigned a value of "a", " bc" is ignored
:set c %%a%%	# <=> :set c a\ bc : c is assigned a value of "a bc"
:set d "%a%"	# d = c

:echo %b%	# outputs only "a" to status
:echo %c%	# outputs "a bc"
:echo %d%	# same

Arithmetics

Currently the only way to perfrom arithmetci operations is to execute

:math <operand1> <operator> <operand2> <var_name>

The result is written in %var_name% variables, or, if unspecified, to %ret%. See the :math command description on the (manpage) to see supported operations.

Aliases

Aliases are created with:

:alias <alias_name> <alias_command>

Alias arguments

You can put alias arguments in alias command as %arg1%, %arg2%, etc. Upon execution interpreter will try to find arguments in alias command starting from 1. All arguments for which a place to replace was not found are appended to the command at the end.

Let's look at an example:

:alias g "set id" # from scripts/legacy_aliases.conf

:g 1	# executes ":set id 1"

:alias vtoggle "toggle filter.%arg1%" # from scripts/legacy_aliases.conf

:vtoggle complete	# executes ":toggle filter.complete"

Configuring

Tips and tricks

Clone this wiki locally