home — howm tutorial — contact <<< HowmTutorial

Introduction

Overview of howm: "write fragmentarily, read collectively"

"Howm" is a powerful note-taking and hypertext organization tool written in Emacs Lisp, with integrated browser, todo-list, and schedule management.

The slogan "write fragmentarily, read collectively" refers to the spontaneous, stream-of-consciousness note-taking style encouraged by howm. Notes can be created any any time while in Emacs, so a thought may be captured whenever it strikes you.

You can combine plain text, links to relevant files and emails, random thoughts, ASCII art, drafts of essays, webpage links, snippets of code or mathematical equations (via Unicode), output from other programs, todo-list items, schedule entries, and reminders in your notes. You can also categorize notes using Keywords (see below.)

You can then search by keyword (to find notes on a certain topic), search for arbitrary text (for example, you could find web links by searching for "http:"), produce a sorted todo-list report, a schedule of upcoming appointments and deadlines, and more.

About this document

This document is presently very incomplete and under construction.

When I found howm, it was obviously the Right Thing, but there was virtually no English-language help available. Furthermore, although the howm distribution includes an English README file, it doesn’t give much overall strategy or usage advice.

I wrote this document to explain to an English-speaking audience why howm works, and how to combine its features effectively with one another and with other tools.

Obtaining and installing howm

Howm can be downloaded from the official website at:

http://howm.sourceforge.jp

The shell commands below will download, unpack, and build howm 1.3.1, which is the version I used in writing the tutorial. A very useful howm accessory called "snap.el" will also be downloaded.

cd $YOUR_ELISP_FOLDER wget http://howm.sourceforge.jp/a/howm-1.3.1.tar.gz wget http://howm.sourceforge.jp/a/snap.el tar xvzf howm-1.3.1.tar.gz cd howm-1.3.1 ./configure make

These next commands will create your personal howm folder, and copy the distribution’s very informative default menu file:

mkdir ~/howm cp howm-1.3.1/en/0000-00-00-000000.howm ~/howm/menu.howm

Then add the following to your emacs initialization file:

;; load howm (add-to-list ’load-path "$YOUR_ELISP_FOLDER/howm-1.3.1") (require ’howm) (load "snap.el")

;; basic options (setq howm-menu-file "menu.howm") (setq howm-view-use-grep t)

Before you continue

Before reading further, you should become familiar with the basics of howm operation by running through the simple exercises in the official howm README:

http://howm.sourceforge.jp/README.html

It’s a terse but effective document. Don’t worry about memorizing all the commands or exploring every feature. Just play around with howm, write a few notes, and try to get a feel for the different activities. Then you’ll be ready to tackle the strategy advice given in the following sections.

Using howm effectively

Creating notes

Note-taking is the fundamental activity of howm. All your data— whether plain text, todo list, or schedule—are contained within notes. Press

C-c , c

to run (howm-create). A new note is created, stamped with the current time and date:

= [2005-09-20 10:10]

The line beginning with "=" is the title, which should be a one-liner description of the note’s content. Good titles are important when searching hundreds or thousands of notes.

After typing your title, move down to the end of the buffer and type in your thoughts.

Your notes are stored in a special directory specified by the variable howm-directory. It’s useful to keep all your notes together in a "notebook" folder, for easy searching (with grep) and archiving (with tar).

Here’s an example of a completed note:

= Hermann Helmholtz, "On The Sensations Of Tone" [2005-08-25 16:56] >>> ReadingBooks <<< SensationsOfTone

Quote:

"...in music, the sensations of tone are the material of the art." – SensationsOfTone, Introduction

This is a great book. It explains—in plain language and with clear illustrations—how the ear and the mind perceive tones, and then proceeds to develop a more or less complete theory of music.

Keywords

Keywords can be used to categorize notes. A note may be marked with many keywords and thus related to many topics. For example, you might take notes on emacs configuration, and mark such notes with

<<< DotEmacs

The special marker "<<<" is used to create keywords; everything to the right of the marker is taken as the text of the keyword.

You can edit the list of keywords by visiting the file "~/.howm-keys". I tidy up my .howm-keys file from time to time in order to get an alphabetized list of topics in my brain.

Keyword search

After you create a keyword and save the resulting *.howm file, you may notice that other occurrences of the keyword are now highlighted (even in other files where howm-mode is turned on.) If you move the cursor to one of the occurrences, and hit RETURN, a keyword search is performed.

In keyword search results, closely-related notes (i.e. those that have keyword markers) are first on the list; then come those notes that simply refer to the keyword.

So by creating a keyword, you also create links wherever the keyword occurs.

You can also type the command

C-c , s

to initiate a keyword search at any time.

References

References are like keyword search links, but more general-purpose. References can link to keywords, files, and URL’s. As with keyword search links, move the cursor to the text of the reference and hit RETURN to jump to the target of the reference.

Examples:

>>> WeeklyPlan >>> ~/e/scratch.el >>> /etc/services >>> http://www.google.com

. : Regular expression search

Browsing notes

C-c , l howm-list-recent C-c , . howm-find-today C-c , : howm-find-yesterday

Making reminders

Howm’s "reminder" feature is a bit misleadingly named. It allows you to add all of the following data types to your notes:

simple reminder todo-list task appointment/schedule deadline deferred task completed task

Howm departs from the traditional linear notion of "priority" used in most todo-list managers. Instead a more complex system called "magic sorting" is employed. Each item has a date, reminder type, and "laziness" associated with it. Using this information, howm compiles all your reminders, scattered through many files, into a coherent prioritized display. Multiple views and filters of this data are possible.

To understand magic sorting, think for a moment about how the importance of an reminder influences when and where you would like to be reminded. For example, you’d want to be reminded of deadlines well ahead of time, and when there are multiple deadlines you’d certainly want to see them in date order. The same goes for appointments.

You might want a simple reminder to stay near the top of your to-do list but slowly sink as it gets older—this is sort of like sticking a post-it note on the board, watching it get slowly covered up by other notes.

An ordinary todo-list item should rise in the list as the correct date approaches, and then stay at the top.

A deferred task should neither disappear completely nor bother you all the time. One solution is for deferred tasks to periodically rise and fall in the list.

Completed tasks should sink to the bottom of the list permanently, but retain their ordering so that you can review past progress.

Reminder syntax

reminder: [YYYY-MM-DD]- Pick up new shoes todo: [YYYY-MM-DD]+ Return library books todo: [YYYY-MM-DD]+ Buy shampoo deadline: [YYYY-MM-DD]! Credit card payment: $65.00 defer: [YYYY-MM-DD]~ Learn advanced howm-mode features schedule: [YYYY-MM-DD HH:MM]@ Dentist appointment

(1) rise until date, sink after date at speed Z "I COULD do X within Z days" Try Z values of -999 on a reminder for one that sinks REALLY slowly...

todo (+)

(7) rise until date at speed Z, stay (z=rise speed)

"I SHOULD do X within Z days..."

deadline (!)

(7) rise quickly starting Z days before date "I MUST do X by DATE"

defer (~)

(30) hide until date; rise and fall every Z days afterward "I am procrastinating and don’t want to see it"

done (.)

( ) sink forever "I DID X on DATE"

schedule (@)

. : Recurring tasks

.. Browsing reminders

todo

schedule

.. Howm-menu

Action-lock

History

Advanced configuration & usage

Howm faces

"Wiki wind" links

[[Snorb]]

.. Keyword aliases

Using snap.el to bookmark application state

Using howm with the Emacs calendar

Searching your Mail, News, and other data

Hierarchical howm documents with allout-mode

Fontifying headers

DocumentMode wiki pages for writing and planning

Using howm with eev-mode

Embedding e-scripts in your notes

Organize your e-scripts with keywords

Embedding howm in other formats

Publishing your files to the web

Tying it all together: your eefolder

Keymap ideas

• question + answer format for some sections, to show activities of howm user. showing how these questions can map onto howm searches.

• What did I accomplish last week? Last month? - When is my appointment with Dr. Smith? - What was I writing about yesterday? - What URL’s have I put into my notes this week?