Notes-mode: 2 Basics

All you need to use notes-mode in a chapter. (Except for installation, See section Installation.)

2.1 Getting started

To get started with notes-mode, read the introduction this chapter, then either:

Either way these should set up everything notes-mode needs. This program will modify your environment (as described in this section), or it will give you the exact commands you should run yourself.

After you’ve done one of these, start up emacs and note-away. I usually begin a day of note-taking by running the command M-x notes-index-todays-link to jump directly to today’s note. You may even wish to bind this to something, perhaps with (define-key global-map "\C-cn" 'notes-index-todays-link) in your ‘.emacs’.

If you want to browse your existing notes, you might instead want to edit the ‘~/NOTES/index’. (What is a notes file and the index? Hurry up and finish reading this chapter.)

2.2 A notes file

The notes file is the focus of most of the activity in notes-mode, it’s where you take your notes. Notes files are mostly free-form text broken up into entries. Here’s an example:

8-Jun-95 Thursday
-----------------

* Today
-------
prev: <none>
next: <file:///~/NOTES/199506/950609#* Today>

next week - release notes-mode


* Environment/notes
-------------------

I explained notes mode to Ashvin and Geoff.
...

The subject-block must begin with an asterisk-space (* ) at the beginning of a line, followed by the subject itself. Subjects must be underlined with a row of dashes (if they’re not exact, that’s OK; notes-mode will fix them periodically). For convenience, notes-mode will automatically add the underlines when you hit <RTN> (notes-electric-return), and <TAB> on a partially completed subject will invoke completion based on indexed subjects (notes-complete-subject).

Following the subject may be links. (In the example, the “Today” entry has links, the “Environment/notes” entry doesn’t.) These links will be automatically updated by notes-mode when your notes are re-indexed; just leave a blank line when writing the note.

Links are made with pseudo-URLs, sort of like those in the World Wide Web. Any of these URLs can be followed in notes-mode files by clicking S-mouse-2 on the pseudo-URL (notes-w3-follow-link-mouse).

Finally comes the text. Go wild, but just don’t include text that looks like a subject. You can embed pseudo-URLs to link notes together manually.

The more anal of you may have noticed that the lines before the first subject are not part of any entry. These lines are front matter. They’re not usually used for much, but they can be a good place to label the file.

There are a number of useful conventions that can be adopted to organize your notes. The most common is the “Today” entry. If you keep an entry with the same subject at the beginning of each file, you link all of your notes together. Notes-mode will help you out with some of these convetions by automatically creating or copying some fields for you; see see section Useful conventions for details.

Finally, notes-mode can also work with outline-minor-mode (thanks to Tim Carroll for pointing this out). Outline-mode supports hiding and revealing text and other helpful features beyond the scope of this document. See Outline Mode in The Emacs Editor, for details.

2.3 The notes index

The notes index lists all subjects you’ve kept notes about, and each date of each note. Impress your friends, show your advisor why you’re worth the big peanuts, you’ll soon have the biggest index of all.

The index has one line per subject, listing the subject and each day a note was made about that subject. For example:

Bicycle: 950314, 950316
Bicycle/maintenance/books: 951028
Bridge/hands: 951113, 951114, 951116, 951117
Bridge/UCLA: 960222, 960409

Clicking on any of the dates with mouse-2 will take you to that note (notes-index-mouse-follow-link). (You can also move the point over the date and hit <RTN> if you’re musaphobic [notes-index-follow-link].)

The notes index is automatically updated by the program ‘mkall’. Typically ‘mkall’ is run nightly by ‘cron’. On most modern versions of Unix, you can add this command to cron by running ‘crontab -e’ and adding the line:

0 4 * * * /usr/local/lib/notes-mode/mkall

(Assuming that your notes programs are installed in /usr/local/lib/notes-mode, the default location.)

2.4 The notes directories

The final thing needed to tie basic notes-mode together his how the pieces fit together. Since my graduate work is in file systems, you can bet that directories are involved.

~/NOTES
~/NOTES/index
~/NOTES/rawindex
~/NOTES/199603
~/NOTES/199603/960329
~/NOTES/199603/960330
~/NOTES/199604
~/NOTES/199604/960401

The top level, ‘~/NOTES’, is the notes directory. It keeps all notes in one place. (The name of this directory is configurable, See section Notes-mode configuration.)

Inside the notes directory are two files and a number of directories. The files are ‘index’, the index of all entries (see section The notes index), and ‘rawindex’, used internally.

The notes directory also contains a number of subdirectories, sometimes called intermediate directories. These directories group the actual notes files into manageable chunks, keeping any directory from getting too large. Intermediate directories are named by the four-digit year and the two-digit month of the entries they contain. (The format of intermediate directories is configurable, See section Notes-mode configuration.)

Finally, each intermediate directory are the notes files themselves, named according to the two-digit year, month, and day-of-month.

For the most part, notes-mode will automatically maintain this organization of files, once you create the top-level directory. Notes-mode will also automatically insure that all files in the notes directory are unreadable by anyone other than their owner. Notes are personal things. (This behavior is not currently configurable, but it probably should be.)