Overview
Yawn is a command-line based to-do list manager for Linux. It uses human-readable and human-editable TODO files in a straightforward plaintext format, and comes with an integrated filtering language which lets you perform both simple and complex queries on your TODO files.
Snore is Yawn's simple filtering language, which is concise yet expressive, and is based on a recursive tree-walk of the hierarchical TODO file. It is designed to be as concise as possible; so it has the readability of a complex Perl regular expression. That is to say, those who have learned it will swear by it, and those who are learning it will swear at it.
Feature Summary
Yes, I know. There are at least a dozen other todo list manager programs out there. And I recognize that Yawn is not for everybody. It only fits a certain mindset. So, I will list Yawn's distinguishing features up front to help you decide if this is for you, or if you want to look elsewhere.
Command-line based. No need to install X if you don't want to.
Non-interactive. Can be used easily in a pipeline. Great for shell scriptists.
Todo files editable with your favorite text editor.
File format in plaintext, human-readable and human-writable.
Arbitrary nesting of entries.
Many entry types to indicate the status/type of the entry: done, undone, postponed, cancelled, merged, carried, annotation.
Entry body auto-formatted, but allows unformatted literal blocks for code snippets, etc.. Wrap width fully configurable.
Snore: simple yet expressive filtering language. Filter based on type, nesting level, substring match, regex match, what has been selected before, etc., plus arbitrary boolean combinations of these.
Default entries to be displayed fully specifiable in Snore.
Support for directory-based TODO file hierarchy: searches parent directories for TODO files if can't find one in the current directory, specify "root" TODO file with single option. In future releases, will support TODO file importing, so that a master TODO file can pull in files from subdirectories.
My TODO list for Yawn is managed by Yawn.
Licensed under GPL.
News & Announcements
Yawn version 1.0 has been released! Get it now before you fall asleep. And please, no snoring in public. Not everyone can filter out the noise.
Why such wacky names as Yawn and Snore?
The reason for these whimsical names is an unfortunate historical accident.
The original name of this program was 2do (pronounced “to-do”, obviously), and its filtering language was named SFL (Simple Filtering Language). Unfortunately, during the lapse of time between my stumbling across this nice name and when the program is actually ready to be published to the world, somebody else happened to pick the same name, 2do, for another, web-based, todo list manager.
Obviously, one of us has to go, since both programs are too close in functionality and so exist in the same practical namespace. I didn't want to pick a fight with Bart, since he clearly picked the same name only by chance (nobody else in the world knew of my 2do yet). I also didn't want to be associated with PHP for entirely irrational reasons (although, ironically enough, this page is actually being served by PHP right now). Therefore, in response, I decided to change the name of my 2do to Yawn: i. e., when I am bored, it reminds me of what else I haven't done yet.
This Great Renaming took place on the 29th of July, 2004, five years after the initial concept of the program was laid down. And while I was at it, I decided that the name SFL was not unique enough (the same cause that cost me the neat name 2do); so I decided to also change it to Snore, in correspondence with Yawn's new name. This Lesser Renaming took place on the same day as the Great Renaming.
System Requirements
Yawn is a standalone program that runs on any Linux system. It can probably be compiled for any other Unix system if you care to. It doesn't require anything else except the standard system libraries (libc6, etc.), unless you want to compile the source yourself.
The requirements for compiling Yawn are:
CONS - the most reliable, cleanest build system on Earth besides SCONS (which is based on CONS). If you haven't experienced the joy of having reliable, reproducible builds and correct dependency checking, if you're suffering under that long-outdated nightmare called Make, then you might want to use CONS for your own projects too.
Perl 5.x - required by CONS.
The prog/lib libraries. This is a set of simple commonly-used C routines and C++ classes that I use for most of my projects. Granted, much of it was written during my NIH days, but it's too much effort to port my programs to standard libraries right now, so prog/lib will have to haunt me for another while yet. Fortunately, it is not meant to be built as a shared library, so its evil will remain confined within my own programs only.
Download
Latest stable release of Yawn: yawn-1.0.tar.gz
Current version of the prog/lib libraries: proglib-0.2.tar.gz
Build instructions
Assuming you unpacked the prog/lib tarball and the Yawn tarball in the same directory, there should be a directory called proglib and another directory called yawn. Then all you need to do is:
cd proglib
cons .
cd ../yawn
cons . PROGLIB=../proglib
See the INSTALL file for more details.
Installation instructions
Copy the executable yawn to any directory in your PATH, and make sure it has the right executable permissions.
Copy yawn.cfg to /etc
Users may create .yawnrc in their home directory and put any overriding settings there, such as specifying the default place to look for a TODO file. (Or, if your computer is essentially a single-user system, you can just copy yawn.cfg to ~/.yawnrc without installing it in /etc, if that suits you better.)
Copy the manpages doc/yawn.1 and doc/snore.7 to your preferred manpage directories, usually /usr/share/man/man1 and /usr/share/man/man7 respectively.
Documentation
Yawn usage summary
Here are some common ways to invoke Yawn.
yawn -h to get usage summary.
yawn to see what else you haven't done. By default, this displays the first 5 of all undone entries together with any annotations attached to them. If you have specified another default filter in your configuration file, Yawn will use that instead.
yawn /usr/src/myproject show what still needs to be done in MyProject. (Reads /usr/src/myproject/TODO.)
yawn -r use root TODO file.
yawn -e edit TODO file.
yawn -n10 display the first 10 entries selected by default filter.
yawn -d display done entries.
yawn -a override default filter.
yawn -au show all undone entries.
yawn -f'...' append Snore filter snippet to default filter. (It's a good idea to protect the Snore snippet with quotes to prevent the shell from mangling or misinterpreting it.)
yawn -af'...' override default filter with Snore snippet.
Exhaustive Yawn documentation
Exhaustive Yawn documentation is available in Yawn's manual page, which comes with the Yawn tarball. The manual page can be found in the doc subdirectory. A web-browsable version will be available soon.
Snore documentation
The Snore documentation is also available in the Yawn tarball in the doc subdirectory. A web-browsable version will be available soon.
