Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Cannot retrieve contributors at this time

1586 lines (1250 sloc) 47.936 kb
\input texinfo @c -*-texinfo-*-
@c %**start of header
@settitle Notes-mode: Organizing on-line note-taking.
@c For double-sided printing, uncomment:
@c @setchapternewpage odd
@c %**end of header
@c FIXME: Figure out a way to keep these things up-to-date w/o RCS/CVS!
@set EDITION $Revision: 1.40 $
@c XXX: the next line should track the release file.
@set VERSION 1.16
@set UPDATED $Date: 2010/06/20 18:30:34 $
@end iftex
@dircategory Emacs
* Notes-mode: (notes-mode). Organizing on-line note-taking.
@end direntry
@c FIXME: The leading spaces lead to double spaces inside the
@c generated .info file!
Notes-mode: Organizing on-line note-taking.
This file documents notes-mode, a package
for organizing on-line note-taking.
@end ifinfo
Copyright (C) 1994-1996,2012 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
and with the Back-Cover Texts as in (a) below. A copy of the license
is included in the section entitled ``GNU Free Documentation License''.
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
modify this GNU manual. Buying copies from the FSF supports it in
developing GNU and promoting software freedom.''
@end quotation
@end copying
@title Notes-mode
@subtitle Organizing on-line note-taking
@subtitle Edition @value{EDITION}, for notes-mode version @value{VERSION}
@subtitle @value{UPDATED}
@author by John Heidemann
@end titlepage
@node Top, Introduction, (dir), (dir)
@comment node-name, next, previous, up
This file documents notes-mode, a package
for organizing on-line note-taking.
This is edition @value{EDITION}, for notes-mode version @value{VERSION},
last updated @value{UPDATED}.
@end ifinfo
@c Outline as of 16-Apr-96:
@c introduction
@c - what is notes mode
@c - why keep notes on-line
@c - easier to type than write
@c - information already on-line (program errors, measurement data, etc.)
@c - easy to search (grep, glimpse)
@c - easy to index (notes-mode)
@c - why use notes-mode
@c - automates indexing
@c - supports links
@c - emacs helpers (subject completion, elisp customization)
@c - alternatives:
@c HTML (+formatting, +links, -tags are intrusive, -errors are bad, -index by hand)
@c word processor (+formatting, -links, -indexing)
@c - related work
@c - notes-mode is not related to Lotus Notes
@c basics
@c - notes-file
@c (text mode)
@c - front-matter
@c - entries
@c - subject
@c - links
@c like urls, but not quite
@c mouse-2 follows a link (and also pastes)
@c - text
@c can contain other, embedded links
@c - notes-index
@c - subjects
@c mouse-2 follows links
@c - re-indexing
@c - file layout
@c - root ~/NOTES, changing
@c - intermediate directories @cY@cm
@c - notes-files @cy@cm@cd
@c intermediate features
@c - notes-files
@c - conventions
@c today
@c Monday
@c date in front-matter
@c hierarchical subjects
@c - C-c C-s subject summary
@c - C-c C-k current-url-as-kill
@c - getting around
@c - C-c C-i notes-goto-index-entry
@c - C-c C-n notes-follow-next-link, C-c C-p notes-follow-prev-link
@c - C-c C-f notes-w3-follow-link
@c - M-C-a notes-beginning-of-defun, M-C-e notes-end-of-defun
@c - C-c C-e, C-c C-s encryption
@c - notes-index
@c - RET notes-index-follow-link
@c - o notes-index-link
@c - C-c C-s summarize subject
@c advanced features:
@c - .notesrc
@c history
@c - genesis: minimal functionality: subject collection
@c - Leviticus: indexing, urls
@c - exodus: share with others
@c - Deuteronomy: features are added
@c The master menu, created with texinfo-master-menu, goes here.
* Introduction::
* Basics::
* Advanced Features::
* History::
* Installation::
* Keystroke index::
* Concept index::
--- The Detailed Node Listing ---
* What is it?::
* Why keep notes at all?::
* Why keep notes on-line?::
* Why use notes-mode?::
* Y2K Statement::
* Related work::
* Staying on top::
* Getting started::
* A notes file::
* The notes index::
* The notes directories::
Advanced Features
* Notes files::
* Notes indices::
* Notes-mode configuration::
Notes files
* Getting around::
* Subject summary::
* Encryption::
* Useful conventions::
* Notes-mode history::
* Credits::
* Changes::
@end detailmenu
@end menu
@c ----------------------------------------------------------------------
@node Introduction, Basics, Top, Top
@chapter Introduction
What is notes-mode and why should you (perhaps) use it?
* What is it?::
* Why keep notes at all?::
* Why keep notes on-line?::
* Why use notes-mode?::
* Y2K Statement::
* Related work::
* Staying on top::
@end menu
@node What is it?, Why keep notes at all?, Introduction, Introduction
@comment node-name, next, previous, up
@section What is it?
Notes-mode is an indexing system for on-line note-taking.
Notes-mode is composed of two parts, the visible part,
a major-mode for emacs to aid note-taking;
and the invisible part,
scripts which periodically index your notes for you.
Note that notes-mode provides tools to @dfn{index} your notes,
not to @dfn{search} them.
(Other existing tools such as @file{grep}, @file{agrep}, and @file{glimpse}
already allow file search.)
A digression about indexing vs. searching:
Indexing in this sense means
organize them according to categories you give,
while searching looks through all text for arbitrary strings.
Drawing on the World Wide Web for examples,
Yahoo (@file{}) is an index,
while Alta Vista (@file{})
is a search-engine.
In (potentially) more familiar terms,
the yellow pages
@footnote{Trademarked, in Great Britain, Sunone tells me.}
are an index,
while directory information (411 in the USA)
is sort of a search-engine.
@node Why keep notes at all?, Why keep notes on-line?, What is it?, Introduction
@comment node-name, next, previous, up
@section Why keep notes at all?
So why should you use notes-mode?
Well, first, consider why you should (perhaps)
keep your notes on line.
I assume that you take notes as part of your work or school.
If you don't,
you can stop reading now and go back to watching TV.
If you keep notes, ask yourself why you keep them.
Reasons vary for different people, but some include:
@itemize @bullet
To remember what is said or done.
To focus on what is important about what is said.
To provide proof of having done something
at a particular time or date.
I know there were other reasons here,
but they slipped my mind.
@end itemize
@node Why keep notes on-line?, Why use notes-mode?, Why keep notes at all?, Introduction
@comment node-name, next, previous, up
@section Why keep notes on-line?
OK, I've talked you into keeping notes.
Why do it on-line?
Again, there are different reasons for different people.
If you don't want to consider keeping your notes on-line,
you're welcome to go back to your (clay tablets)
paper notes.
However, if you do much of your work on-line,
or if you have portable computer,
then you might want to consider keeping your notes on-line.
@itemize @bullet
It's faster to type than write,
and possibly more legible at high speed.
Often information is already on-line.
For example, in software development, bug reports,
measurement results, and everything else that's useful
is on-line.
You can take down more detail than you otherwise would
(especially if the data is already on-line).
Taking more copious notes can be helpful when you go back
to figure out why that strange thing was happening.
On-line notes are easy to search.
Full-text search with
grep, agrep, and glimpse are all much faster
and are often more accurate than paging through paper notes
looking for a particular keyword.
On-line notes are easy to index.
(At least with notes-mode!)
In addition to full-text search,
it's helpful to organize notes by category.
If you keep a table-of-contents of your paper notes,
you are either extremely fastidious
or a librarian (Nadia?).
You can keep all of your notes with you at all times
(if you have a portable computer).
Even at a page a day,
paper notes quickly become bulky and awkward to carry around.
On-line notes fit on your computer's hard disk,
an extraordinarily compact medium
by comparison.
Your notes can be automatically backed up.
Paper notes can become damaged with time,
and as a graduate student
one of my fears was fire in Boelter Hall
consuming all my research experiments
and and therefore hopes of a degree.
Electronic notes are extremely easy to duplicate
and can be automatically backed up with the rest of your computer.
(You @emph{do} back up your computer, don't you?)
@end itemize
While these advantages are undoubtedly clear to any
right-thinking computer user,
it should be said that there are a few disadvantages
for on-line note-taking.
@itemize @bullet
If you don't have a computer with you most of the time,
it's difficult take notes on-line (because you're off-line, of course).
@footnote{I consider myself pretty anal about this subject,
often typing notes in from paper after-the-fact,
and @emph{I} certainly don't manage to back-enter
my notes all time time.}
Computers require power.
If your portable computer runs out of juice,
you're on your own.
Corollary: watch your power, or bring paper.
Better corollary: watch your power, @emph{and} bring paper.
Social limitations.
It's not always socially acceptable to take notes-on-line.
For example,
at a party,
few people would use a computer
to take down the phone number of a person
to whom they're attracted
(at least, if they wanted the attraction to be mutual).
On the other hand, some folks at MIT are working
on this problem from both the hardware and the social side of
things (@file{})
(Perhaps they have wild parties with computers, too.)
Sometimes other people find the sound of typing distracting.
Health issues.
Repetitive stress injuries do occur
writing (slower) by hand is at least
an alternate motion than typing.
Legal limitations.
If you want to use your electronic notes
to justify a patent or invention,
you may be breaking legal ground.
Being on the legal cutting-edge is rarely an easy thing
for the person involved.@footnote{My hat is off to Rosa Parks
and the many other normal people who triggered landmark cases.}
@end itemize
@node Why use notes-mode?, Y2K Statement, Why keep notes on-line?, Introduction
@comment node-name, next, previous, up
@section Why use notes-mode?
OK, I've sold you on note-taking and even on on-line note-taking.
What about notes-mode?
it slices, dices, and makes julienne fries.
But wait, there's more:
@itemize @bullet
It automates indexing your notes,
linking notes with the same subject together.
It supports embedded links,
allowing you to manually link together different topics
and external files.
It includes a number of convenience-features in emacs.
Subjects can be completed based on existing subjects.
The usual emacs customization mechanisms are available.
Notes containing sensitive information can be encrypted.
Notes-mode seems better than the other, currently available alternatives.
@end itemize
What are the alternatives? I'm glad you asked.
@footnote{If you think I'm missing an alternative, please let me know.}
@itemize @bullet
HTML has better formatting capabilities than notes-mode,
and it has excellent linking capabilities.
HTML's tags are fairly intrusive
(each is at least four characters long and most come with a pair),
tags can get confused with normal text,
errors in HTML can be bad (obscuring data),
and there's no automatic indexing feature
(at least with plain HTML).
all data should be kept as close to the ASCII from whence it came,
as God Intended (hi, Steve).
@strong{Word Processors}.
Word processors are strong in the formatting department,
but most don't really have linking capabilities,
and have poor or restricted indexing.
@end itemize
@node Y2K Statement, Related work, Why use notes-mode?, Introduction
@comment node-name, next, previous, up
@section Y2K Statement
Notes mode uses dates extensively,
both two-digit years and seconds-since-1970.
However, notes-mode has been coded to function correctly through
the year 2038.
To avoid problems with the year 2000, notes-mode assumes
that any two-digit years before ``70'' are 20xx, not 19xx.
Notes-mode should therefore work correctly in both the year 1999 and 2000.
(Notes-mode 1.17 released February 1999 fixes a lingering Y2K problem.)
Because notes-mode uses seconds-since-1970 for some date calculations
it will fail beyond the year 2038 on computers with 32-bit integers.
If I'm still using notes-mode then on a 32-bit machine I'll see what I can do.
@node Related work, Staying on top, Y2K Statement, Introduction
@comment node-name, next, previous, up
@section Related work
What would a document be without related work?
Notes-mode is not related in any way to Lotus Notes.
I am told (by David Weisman)
that it's something like the now defunct Lotus Agenda.
Ashvin Goel, one of the contributors to notes-mode,
has gone off and done a from-scratch reimplementation
called records-mode.
It's very similar to notes mode,
and emphasizes on-the-fly updates to entry links
but lacks a manual.
You may want to check it out at
Hyperbole (by Bob Weiner) offers better linking facilities
than notes-mode, but it has a bunch of stuff notes-mode doesn't need
and it's missing notes-specific indexing provided by notes-mode.
For people already using Hyperbole
it would be interesting to replace notes-mode's linking
with Hyperbole's.
Contributions in this area are welcome, provided they make Hyperbole
@node Staying on top, , Related work, Introduction
@comment node-name, next, previous, up
@section Staying on top
The most recent distribution of notes-mode
is always available via
After you've installed notes mode you're encouraged to subscribe
to the mailing lists.
To subscribe, go to the web page
Send the message "subscribe" to
@file{} or
The announce list will contain only release announcements
and so is guaranteed to be very low bandwidth.
@c ----------------------------------------------------------------------
@node Basics, Advanced Features, Introduction, Top
@comment node-name, next, previous, up
@chapter Basics
All you need to use notes-mode
in a chapter.
(Except for installation, @xref{Installation}.)
* Getting started::
* A notes file::
* The notes index::
* The notes directories::
@end menu
@node Getting started, A notes file, Basics, Basics
@comment node-name, next, previous, up
@section Getting started
@cindex notesinit
@cindex setup
To get started with notes-mode,
read the introduction this chapter,
then either:
@itemize @bullet
Start emacs, do
@kbd{M-x} @code{load-library} @kbd{RET} @code{notes-mode} @kbd{RET}
This approach will set up notes-mode with the default parameters.
OR, from the shell,
run the program @file{notesinit}.
This approach will ask you some questions about how you want to configure
notes mode.
@end itemize
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
@kbd{M-x} @code{notes-index-todays-link}
to jump directly to today's note.
You may even wish to bind this to something,
perhaps with
@code{(define-key global-map "\C-cn" 'notes-index-todays-link)}
in your @file{.emacs}.
If you want to browse your existing notes,
you might instead want to edit the
(What is a notes file and the index? Hurry up and finish
reading this chapter.)
@node A notes file, The notes index, Getting started, Basics
@comment node-name, next, previous, up
@section A notes file
@c - notes-file
@c (text mode)
@c - front-matter
@c - entries
@c - subject
@c - links
@c like urls, but not quite
@c mouse-2 follows a link (and also pastes)
@c - text
@c can contain other, embedded links
@cindex Notes files
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 @dfn{entries}.
Here's an example:
@cindex Notes entries
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.
@end example
Each entry has a subject-block, (maybe) some links, and then (maybe) some text.
The subject-block must begin with an asterisk-space (@kbd{* })
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 @kbd{@key{RTN}} (@code{notes-electric-return}),
and @kbd{@key{TAB}} on a partially completed subject will
invoke completion based on indexed subjects (@code{notes-complete-subject}).
@cindex Notes subjects
@kindex RTN
@kindex TAB
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.
@cindex Notes links
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 @kbd{S-mouse-2} on the pseudo-URL
@cindex Pseudo-URLs
@cindex URLs
@kindex S-mouse-2
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
@dfn{front matter}.
They're not usually used for much,
but they can be a good place to label the file.
@cindex Notes files, font matter
@cindex Font matter
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 @pxref{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.
@xref{Outline Mode, Outline Mode, , emacs, The Emacs Editor}, for details.
@node The notes index, The notes directories, A notes file, Basics
@comment node-name, next, previous, up
@section The notes index
@c - notes-index
@c - subjects
@c mouse-2 follows links
@c - re-indexing
@cindex 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 @emph{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
@end example
Clicking on any of the dates with @kbd{mouse-2}
will take you to that note
(You can also move the point over the date and hit @kbd{@key{RTN}}
if you're musaphobic [@code{notes-index-follow-link}].)
@kindex mouse-2
@kindex RTN
The notes index is automatically updated by the program @file{mkall}.
Typically @file{mkall} is run nightly by @file{cron}.
On most modern versions of Unix, you can add this command to cron by
running @file{crontab -e} and adding the line:
0 4 * * * /usr/local/lib/notes-mode/mkall
@end example
@cindex Crontab
@cindex mkall
@cindex re-indexing
(Assuming that your notes programs are installed
in /usr/local/lib/notes-mode, the default location.)
@node The notes directories, , The notes index, Basics
@comment node-name, next, previous, up
@section The notes directories
@cindex Notes directories
@cindex Directory hierarchy
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-mode keeps its files in a two-level hierarchy:
@end example
The top level, @file{~/NOTES}, is the notes directory.
It keeps all notes in one place.
(The name of this directory is configurable, @xref{Notes-mode configuration}.)
Inside the notes directory are two files and a number of directories.
The files are @file{index},
the index of all entries (@pxref{The notes index}),
and @file{rawindex},
used internally.
@cindex Root directory
The notes directory also contains a number of subdirectories,
sometimes called @dfn{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, @xref{Notes-mode configuration}.)
@cindex Intermediate directories
in each intermediate directory are the notes files themselves,
named according to the two-digit year, month, and day-of-month.
@cindex Notes files
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 ensure
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.)
@cindex Notes file permissions
@c ----------------------------------------------------------------------
@node Advanced Features, History, Basics, Top
@comment node-name, next, previous, up
@chapter Advanced Features
Notes-mode, the minutiae, and some other good stuff.
* Notes files::
* Notes indices::
* Notes-mode configuration::
@end menu
@node Notes files, Notes indices, Advanced Features, Advanced Features
@comment node-name, next, previous, up
@section Notes files
* Getting around::
* Subject summary::
* Encryption::
* Useful conventions::
@end menu
@node Getting around, Subject summary, Notes files, Notes files
@comment node-name, next, previous, up
@subsection Getting around
Moving between notes entries and around the hierarchy is fairly common,
so there are some accelerators.
@table @kbd
@item C-c C-i
Jump to the index entry for the current entry's subject
@kindex C-c C-i
@item C-c C-n
@item C-c C-p
Move to the next or prior note with the same subject
(@code{notes-follow-next-link} and @code{notes-follow-prev-link}).
These functions follow the links in the note,
if they're defined.
If not,
they look through the index file.
This approach usually works,
but will fail if there are multiple new entries created
with the given subject
between when the index is recomputed.
@kindex C-c C-n
@kindex C-c C-p
@item C-c@key{RTN}
Follow the link under the point
a keyboard equivalent of @key{S-mouse-2}.
@kindex C-c@key{RTN}
@item M-C-a
@item M-C-e
Jump to the beginning or end of the current note entry
(@code{notes-beginning-of-defun} and @code{notes-end-of-defun}).
@kindex M-C-a
@kindex M-C-e
@item C-c C-k
Copies the pseudo-URL for the current note into the kill-ring
To link two entries, go to the target,
grab its URL with @kbd{C-c C-k},
go to where you want to make the link,
and yank the URL with @kbd{C-y}.
@kindex C-c C-k
@end table
Notes mode supports imenu,
if you have it bound to something
(I use @code{(global-set-key [down-mouse-3] 'imenu)}).
@cindex imenu
@node Subject summary, Encryption, Getting around, Notes files
@comment node-name, next, previous, up
@subsection Subject summary
It's often helpful to look at all
entries for a given subject
@kbd{C-c C-s}
collects all entries with the subject of the current
entry in a new buffer
@kindex C-c C-s
@cindex Subject summary
@node Encryption, Useful conventions, Subject summary, Notes files
@comment node-name, next, previous, up
@subsection Encryption
@cindex Encryption
@cindex Decryption
@c - C-c C-e, C-c C-d encryption
Notes occasionally contain private material.
While Unix has strong services for file protection
(compared to other, say, more wide-selling operating systems),
in many systems root passwords are shared,
while other systems are vulnerable to physical compromise.
In such systems,
properly used encryption is the best approach to security.
Notes-mode encryption is based
Phill Zimmerman's PGP (Pretty Good Privacy)
(see @file{})
and either
with Rick Campbell's
emacs interface, PAM (PGP Augmented Messaging)
(from @file{})
(note that as of January 1997, PAM is no longer at this ftp site
and appears to not be publicly available),
or LoPresti and Choi's mailcrypt
(from @file{}).
@cindex PGP
@cindex Pretty good privacy
@cindex PAM
@cindex PGP Augmented Messaging
@cindex mailcrypt
@table @kbd
@item C-c C-e
Encrypt the current note
By default this function encrypts the whole entry.
With a prefix argument,
only the part from the point to the end of the entry is encrypted.
@kindex C-c C-e
@item C-c C-d
Decrypt the current note
@end table
@kindex C-c C-d
By default notes-mode determines your public key by looking
up your @code{user-full-name} in your PGP keyring.
You can override this default by setting
to the desired key-id.
@cindex key-id
@node Useful conventions, , Encryption, Notes files
@comment node-name, next, previous, up
@subsection Useful conventions
@c - conventions
@c date, 12-Jan-96 Friday
@c Today
@c Monday
@c hierarchical subjects
@cindex conventions
@cindex mknew
There are a number of conventions which can make notes-mode
easier to use.
These conventions are a matter of personal taste,
of course.
Do what works for you.
I find it helpful to keep the date of each notes-file at the top
of the file.
This makes the file self-identifying
if the filename is lost.
I find it useful to have the first entry of each file
have the same subject (perhaps ``Today'').
This entry then links all notes together,
making it easy to go to yesterday and tomorrow.
I keep a to-do list on this entry,
bringing the list forward each day.
@cindex Today
A third useful convention is to keep an
entry with the name based on the day of the week
in each file.
Analogous to ``Today'', this entry links together
Notes-mode supports these conventions.
When you make a new notes-file in emacs,
notes-mode searches for the preceding file.
If it follows any of these conventions,
the new file is initialized appropriately.
the approach to do this process
(in the program @file{mknew})
is fairly sensitive,
so it may not work in all cases.
In particular,
the date convention works only on
for English-language dates.
(If you use notes-mode with a non-English language,
let me know and I'll work with you to fix this limitation.)
If you find other helpful conventions,
please let me know.
Modifications to @file{mknew} to implement
new conventions are also invited.
If you don't want to use these conventions,
or if you want to use different ones,
set the emacs variable notes-mode-initialization-program
to nil or the name of your initialization program.
@cindex notes-mode-initialization-program
@node Notes indices, Notes-mode configuration, Notes files, Advanced Features
@comment node-name, next, previous, up
@section Notes indices
@c - notes-index
@c - RET notes-index-follow-link
@c - o notes-index-link
@c - C-c C-s summarize subject
Only two features of notes index mode haven't yet been described.
you can open any notes-file based on date
with @code{notes-index-link},
normally bound to @key{o}.
@kindex o
you can get a subject-summary
with @key{C-c C-s}
(@pxref{Subject summary}).
The subject defaults to that of the current index line.
@kindex C-c C-s
@node Notes-mode configuration, , Notes indices, Advanced Features
@comment node-name, next, previous, up
@section Notes-mode configuration
@cindex configuration
@cindex .notesrc
Several aspects of notes mode are particularly visible
to the user.
Because I'm not a fascist,
a user can change most of these.
Preferences are specified in @file{~/.notesrc}.
This file lists things to change:
# lines beginning with a hash are comments
dir: ~/NOTES
int_form: %Y%m
@end example
Currently, two things can be changed:
@table @code
@item dir
Specifies the root of the notes directory hierarchy
(@pxref{The notes directories}).
@item int_form
Specifies the form of the intermediate directory.
A limited subset of @code{strftime(3)}
formatting is allowed.
@end table
The subset of @code{strftime(3)} supported in @code{int_form} is:
@table @code
@item %Y
The four-digit year.
@item %y
The two-digit year.
@item %m
A two-digit numeric month.
@item %d
A two-digit day.
@end table
In addition to @file{.notesrc},
there are a number of emacs-specific variables.
These variables are documented in the file
@c ----------------------------------------------------------------------
@node History, Installation, Advanced Features, Top
@comment node-name, next, previous, up
@chapter History
More about notes-mode than you wanted to know,
and some thanks.
* Notes-mode history::
* Credits::
* Changes::
* Suggested features::
@end menu
@c history
@c - genesis: minimal functionality: subject collection
@c - Leviticus: indexing, urls
@c - exodus: share with others
@c - Deuteronomy: features are added
@node Notes-mode history, Credits, History, History
@comment node-name, next, previous, up
@section Notes-mode history
I started keeping notes on-line shortly after I got a portable computer
in January, 1994.
After a month-and-a-half of notes, I realized that
one does not live by grep alone,
so I started adding indexing facilities.
In June of 1995
some other Ficus-project members started
keeping and indexing on-line notes
using other home-grown systems.
After some discussion,
we generalized my notes-mode work and
they started using it.
Over the next 18 months notes-mode grew.
Finally, in April, 1996 I wrote documentation,
guaranteeing that innovation on notes-mode will now cease
or the documentation will become out of date.
@node Credits, Changes, Notes-mode history, History
@comment node-name, next, previous, up
@section Credits
I (John Heidemann, <>)
started, documented, and currently maintain notes-mode.
I take ultimate responsibility for the code,
especially for the ugly parts that I won't let others change.
Ashvin Goel
has been a very enthusiastic notes-mode user and contributor.
He is responsible for at least
the ideas behind @code{notes-summarize-subject}
and the ideas and initial implementations of
some of the original generalization and modularity improvements,
@code{notes-follow-next-link} and @code{notes-follow-prev-link},
programmed subject completion,
context-sensitive mouse-2 handling.
In addition,
he is an invaluable second opinion about
what and how things should be done
(even if I don't always agree with him).
Geoff Kuenning
has been another enthusiastic notes-mode user and victim.
He is responsible for
finding several bugs,
motivation for mouse-less operation,
comments about the documentation,
the day-of-week convention,
and an initial implementation and the idea of
multiple entries with the same subjects in a single notes-file.
Ramesh Govindan <> did the xemacs port.
Since it's release on Usenet in April 1996 several
other folks have contributed.
Thanks to
David Weisman <>,
Martin L. Smith <>,
Jason Bastek <>,
Ulrich Herbst <>.
See the next section (@xref{Changes}.) for details of their exploits.
Thanks to Larry Ayers <>
for popularizing notes-mode with reviews in
the Linux Gazette
(at <> and
@node Changes, Suggested features, Credits, History
@comment node-name, next, previous, up
@section Changes
For the bored:
First semi-public release. 12-Jul-95: version 0.1
Shared a version with Ashvin and Geoff.
Changed 6-Dec-95: version 0.3
Ashvin's changes for note traversal added (C-c C-p and C-c C-n now
move to the prev/next note in note-mode).
URL parsing changed so that "localhost" is optional.
Changed 19-Dec-95: version 0.4
More robust prev/next code added, both to handle going back and
forward in the middle of chains through the index file, and to handle
back/forward in a single file.
URL parsing changed so that notes-goto-index-entry correctly handles
lookups on notes names such as "252A".
Changed 20-Dec-95: version 0.5.
Fixed a missing variable in notes-url.el.
Added a work-around to a bug in emacs-19.30's define-derived-mode.
Changed 24-Dec-95: version 0.6.
Prev/next code re-re-written to be more robust.
Changed 26-Dec-96: version 0.7.
Bug fix release.
Changed 23-Jan-96: version 0.8.
Initialization code added to set up a new note.
New variable: notes-bin-dir.
I'm skipping version 0.9 because I erroneously release version 0.1
as version 0.9 (only on the web, not on Usenet).
I'm bumping from version "0" to version "1" since the code is has been
in production use for more than a year by several people. Minor
numbers are the same.
Changed 26-Mar-96: version 1.10.
Setup code completely re-written.
Several incompatible changes have been made:
- the lisp and Perl code must be installed via make install,
not by copying.
- some data is specified in a .notesrc file; copy and modify sample.notesrc.
- several internal elisp changes.
- catsubject added (bound to C-cC-s): collect all notes about the
current subject.
- new notes-files are initialized with fields based on the prior
day's notes; see mknew for details.
- daily_work is gone; mkall is rewritten to use .notesrc.
Changed 29-Apr-96: version 1.11.
Real documentation.
Mknew caching added.
Changed 9-Aug-96: version 1.12.
Added notesinit to do all setup for new users.
Changed 24-Aug-96: version 1.13.
Minor documentation fixes.
Changed 20-Dec-97: version 1.14.
Autoconf support.
Fontification of the index buffer is now pre-computed in perl
other than done when the file is needed (in elisp with slow regular
expressions). 2000-line index files are now 1-2 seconds rather than
15-30 on a 100MHz Pentium. If necessary (the
pre-computed version isn't up-to-date) we fall back on the slower
Related work improved (suggestion by David Weisman <>).
Documentation improvement (problem found by Martin L. Smith
Installation improved (code by Jason Bastek <>).
Bug in notes-index mode with subjects containing colons fixed (johnh).
Encryption now supports mailcrypt.el.
Support for emacs 20 (a small font-lock change).
Changed 5-Jan-98: version 1.15.
Bug in decryption for non-PAM users fixed
(suggestion by Kevin Davidson <>).
Y2K statement added
(suggestion by Kevin Davidson <>).
Pointer to mailcrypt added (as a supported encryption package).
Problem pointed out by K. Ueda <>.
Changed 4-Nov-98: version 1.16.
Bug in kill-ring handling of notes-old-underline-line
fixed by Tim Potter <>.
Bug in whitespace handling after PGP encryption fixed by Tim Potter.
Bugs in handling of entries with hash signs in their name fixed
(found by Tim Potter).
Fontification of index buffer further improved
(mapcar is your friend).
Xemacs support added based on code contributed by Ramesh Govindan.
Changed 28-Feb-99: version 1.17:
Improvement: notes-electric-return now fixes up the prev/next links
of new entries (only). Code contributed by
Takashi Nishimoto.
Bug fix: reversed options -batch and -q in to placate
XEmacs 20.0; changed notesinit to not downcase the pathname
(bugs found by Thierry Bezecourt).
Clarification: Autofilling of new notes more clear in the manual (hopefully,
suggested by Solofo Ramangalahy).
Bug fix: a y2k bug in was found and fixed in mkindex. Sigh.
New: Two mailing lists for notes-mode have been created:
@file{} and
Send the line ``subscribe notes-mode-announce''
(or ``subscribe notes-mode-talk'')
to @file{}
to join them.
[@emph{These instructions are now superceeded; to subscribe, go to
Changed 6-Oct-99: version 1.18:
Bug fix: handling of electric-prevnext is better when there are
existing prev/next links.
Clarification: I added some pointers in the code to the installation
instructions. (Apparently people can't RTF README.)
Extension: mailcrypt-3.5.x suported including pgp, pgp5 and gpg.
Changed (date 23-Dec-00): version 1.19:
Bug fix (cosmetic): suppress comments in encrypted nodes.
Install fixes from Kannan Varadhan: elisp directories changed on install.
Added C-j as a synonym for RET in notes-mode to parallel C++ or perl mode.
(Suggested by Fred Jaggi @file{}.)
Outline-minor-mode support added and documented.
(Suggested by Tim Carroll @file{}.)
Bug/typo fixes in gpg support
(Contributed by William A. Perkins @file{},
with separate patches from Knut Anders Hatlen @file{}.)
Installation improvements suggested by Christophe Troestler
use install-info to update the info dir,
warn users of --prefix that lisp files go elsewhere.
Changed (date 1-Feb-01): version 1.20:
Bug fix: missing file notes-first.el added to the distribution.
(Bug found by Michael Totschnig @file{}.)
Changed ( 5-Dec-01): version 1.21:
(backed-out---didn't work with spaced URLs)
URL lookup now uses thing-at-point.
Fix to make notes-mode work with emacs-21.1
(Fix from Klaus Zeitler @file{}.)
Changed ( 3-Jan-02): version 1.22:
Several bugs in @file{notesinit} for stricter Perl implementations
(bug found by Paul Craven" @file{},
and Kasper van Wijk @file{})
and to make it run cleanly more often.
Notes-first now autoinitializes notes mode from emacs.
(As instisted by rms, unfortunately about two years later than requested.)
Changed (20-Feb-05): version 1.23:
Outline mode is now forcebly turned on to avoid interactions
with user's text-mode hooks
(bug and fix from Nils Ackermann @file{}).
Install bug involving ordering of scripts and byte-compilation
fixed (bug and fix from Mark Allman @file{}).
Fix obscure bug in configure, reported by Klaus Zeitler @file{}.
Fix for notes-summarize-subject when no subject is specified (bug and fix
from Geoff Kuenning).
Changed (14-Jan-06): version 1.24:
install-info bug documented with the Debian install-info
(bug reported by Aaron Falk @file{}).
Automatic date completion in new days is now done in the current
locale, so it should now work for non-English languages. Bug reported
by Torsten Bronger @file{}.
Fixed a bug in mkindexcache, triggered by subjects with percent signs
in them. Bug reported by Philip Austin @file{}.
We're a bit more robust about subjects, I hope. Warnings should
appear about embedded number signs, and leading spaces should be
filtered. Bug reported by Philip Austin @file{}.
Notes-mode now dervies from indented-text-mode rather than
paragraph-indent-text mode. Unfortunatley this is not customizable
because of limitations of define-derived-mode. Change suggested by
Aaron Falk @file{}.
Provide better hints about how to get started after installation or
running notes-mode in emacs for the first time.
In notes init, the default path for dir was the full path, not the tilde
version of the path. Now it defaults to using tidle for home
directory. Bug reported by Mark Allman @file{}.
Changed (26-May-06): version 1.25:
fixed a bug in the release tar.gz file that had a additional copies
copy nested.
Changed (30-Jun-08): version 1.26:
Force unicode I/O in @file{mkindexcache} to fix highlighting mis-alignment
when using emacs-21 with unicode subject lines.
Changed mkprevnext and mkrawindex to optionally take the list of notes files
to index from stdin rather than from the command line. Yes, I finally
have 4093 notes files, overflowing the Unix command line buffer.
Changes notes-mode.el to put path in quotes, allowing spaces to appear in home directory names (bug fix from Ulrich Herbst).
Added a suggested features section.
Changed ( 8-Aug-08): version 1.27:
Change I/O in @file{mkindexcache} to use locale (the sadly correct thing)
rather than forcing utf-8 (the Righteous Path).
Bug report from Geoff Kuenning, a man with an older Unix environment than I.
Changed (20-Jun-10): version 1.28:
Changed a regular expression in @file{notes-index-mode.el} that was
causing emacs-v23 (a pre-release version)
to regular expression infinite recursion.
Changed (2012-04-04): version 1.29
(2011-08-23) Changed @code{run-hooks} to @code{run-mode-hooks}.
Bug report from Geoff Kuenning.
Changed some handling of PGP encryption to account for
some apparent API changes.
(2012-04-04) Fixed encyrption to handle encrypting empty notes at the end
of buffers without going into an infinite loop.
Clearly wrong code, but you have to ask this guy for why he tried:
Bug report from Geoff Kuenning.
@c ----------------------------------------------------------------------
@node Suggested features, , Changes, History
@comment node-name, next, previous, up
@section Suggested features
Features suggested by users but not yet implemented:
21-Feb-08: (from Xavier Maillard): should support ``disconnected'' notes that
are indexed but not date-based.
21-Feb-08: (from John Heidemann): should switch all notes files to have an extension (maybe @file{.notes}).
@c ----------------------------------------------------------------------
@node Installation, Keystroke index, History, Top
@comment node-name, next, previous, up
@chapter Installation
@c FIXME: Out-of-date now that we install via package.el.
To install notes-mode,
Unpack and extract the distribution
(gunzip notes-mode-xxx.tar.gz; tar xvf notes-mode-xxx.tar; cd notes-mode-xxx).
Run configure (./configure).
Type ``make install''.
@end enumerate
(To control what's installed where, use --prefix=/where, or
--with-lisp-dir=/where, --datadir=/where (for scripts),
and --infodir=/where.)
For each user:
Run notesinit
@end enumerate
If you have problems with paths being incorrect, please be aware that
you @emph{cannot} run notes directly out of where you untar it. The
installation process customizes the programs for where things are on
your system.
Make sure you move out of the directory where you untarred it
before running it.
The most recent distribution of notes-mode
is always available via
@c ----------------------------------------------------------------------
@node Keystroke index, Concept index, Installation, Top
@comment node-name, next, previous, up
@unnumbered Keystroke index
This index lists notes-mode keystrokes.
@printindex ky
@node Concept index, , Keystroke index, Top
@comment node-name, next, previous, up
@unnumbered Concept index
This index lists notes-mode concepts.
@printindex cp
@c Geoff, make ispell support texinfo mode!
@c LocalWords: texinfo setfilename settitle iftex finalout ifinfo DIR vskip
@c LocalWords: titlepage pt filll dir urls prev defun dfn Yahoo yahoo com Jun
@c LocalWords: alta Trademarked Sunone Grep agrep Nadia emph HTML's notesrc
@c LocalWords: altavista julienne kbd RTN pxref musaphobic mkall cron crontab
@c LocalWords: usr lib rawindex xref cC url imenu Phill PGP Campbell's ftp gp
@c LocalWords: cmu rfb pam keyring mknew Apr int strftime cindex kindex grep
@c LocalWords: isi ashvin geoff printindex ky cp wearables mit mantis co uk
@c LocalWords: pgp html setchapternewpage XXX elisp cY cy cd RET Weisman cn
@c LocalWords: reimplementation mode's Hyperbole's notesinit weisman app osf
@c LocalWords: org ner Bastek jason aai Jul Ashvin's localhost catsubject Aug
@c LocalWords: Autoconf Fontification perl mailcrypt LoPresti Choi's cag lcs
@c LocalWords: Ramesh govindan xemacs tkld quadstone Ueda kueda jupiter qse
@c LocalWords: tohoku ac jp Nov timp jna au mapcar gunzip xxx gz xvf xxx xxx
@c LocalWords: datadir infodir untar
Jump to Line
Something went wrong with that request. Please try again.