Merge commit '0cda39255827f283e7578cd469ae42daad9556a2' from js2-mode

[gnu-emacs-elpa] / packages / notes-mode / notes-mode.texi

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename notes-mode.info
@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 $

@iftex
@finalout
@end iftex

@dircategory Emacs
@direntry
* 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!

@ifinfo
Notes-mode:  Organizing on-line note-taking.

This file documents notes-mode, a package
for organizing on-line note-taking.
@end ifinfo

@copying
Copyright (C) 1994-1996,2012  Free Software Foundation, Inc.

@quotation
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

@titlepage
@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

@ifinfo
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
@c Outline as of 16-Apr-96:
@c
@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



@c The master menu, created with texinfo-master-menu, goes here.

@menu
* Introduction::                
* Basics::                      
* Advanced Features::           
* History::                     
* Installation::                
* Keystroke index::             
* Concept index::               

@detailmenu
 --- The Detailed Node Listing ---

Introduction

* What is it?::                 
* Why keep notes at all?::      
* Why keep notes on-line?::     
* Why use notes-mode?::         
* Y2K Statement::               
* Related work::                
* Staying on top::              

Basics

* 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::          

History

* 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?

@menu
* 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{http://www.yahoo.com/}) is an index,
while Alta Vista (@file{http://www.altavista.digital.com/})
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.
First,
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

@item
To remember what is said or done.

@item
To focus on what is important about what is said.

@item
To provide proof of having done something
at a particular time or date.

@item
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

@item
It's faster to type than write,
and possibly more legible at high speed.

@item
Often information is already on-line.
For example, in software development, bug reports,
measurement results, and everything else that's useful
is on-line.

@item
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.

@item
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.

@item
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?).

@item
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.

@item
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

@item
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.}

@item
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.

@item
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).
@footnote{
On the other hand, some folks at MIT are working
on this problem from both the hardware and the social side of
things (@file{http://wearables.www.media.mit.edu/projects/wearables/})
(Perhaps they have wild parties with computers, too.)
}
Sometimes other people find the sound of typing distracting.

@item
Health issues.
Repetitive stress injuries do occur
writing (slower) by hand is at least 
an alternate motion than typing.

@item
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?
Naturally,
it slices, dices, and makes julienne fries.
But wait, there's more:

@itemize @bullet

@item
It automates indexing your notes,
linking notes with the same subject together.

@item
It supports embedded links,
allowing you to manually link together different topics 
and external files.

@item
It includes a number of convenience-features in emacs.
Subjects can be completed based on existing subjects.
The usual emacs customization mechanisms are available.

@item
Notes containing sensitive information can be encrypted.

@item
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

@item
@strong{HTML}.
HTML has better formatting capabilities than notes-mode,
and it has excellent linking capabilities.
Unfortunately,
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).
Besides,
 all data should be kept as close to the ASCII from whence it came,
 as God Intended (hi, Steve).

@item
@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
 @file{http://www.cse.ogi.edu/~ashvin/software.html}.

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
 optional.

@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
 @file{http://www.isi.edu/~johnh/SOFTWARE/NOTES_MODE/}.

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{http://www.heidemann.la.ca.us/mailman/listinfo/notes-mode-announce} or
@file{http://www.heidemann.la.ca.us/mailman/listinfo/notes-mode-talk}.

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}.)

@menu
* 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

@item
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.

@item
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
 @file{~/NOTES/index}.
(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

@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.
...
@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
 (@code{notes-w3-follow-link-mouse}).
@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:

@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
 (@code{notes-index-mouse-follow-link}).
(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:

@example
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:

@example
~/NOTES
~/NOTES/index
~/NOTES/rawindex
~/NOTES/199603
~/NOTES/199603/960329
~/NOTES/199603/960330
~/NOTES/199604
~/NOTES/199604/960401
@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

Finally,
 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.

@menu
* 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

@menu
* 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
(@code{notes-goto-index-entry}).
@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
(@code{notes-w3-follow-link}),
 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
(@code{current-url-as-kill}).
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
 (@code{notes-summarize-subject}).
@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{http://www.mantis.co.uk/pgp/pgp.html})
 and either
 with Rick Campbell's
 emacs interface, PAM (PGP Augmented Messaging)
(from @file{ftp://h.gp.cs.cmu.edu/usr/rfb/pam/})
 (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{http://cag-www.lcs.mit.edu/mailcrypt/}).
@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
(@code{notes-encrypt-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
(@code{notes-decrypt-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
 @code{notes-encryption-key-id}
 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.

First,
 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.

Second,
 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
 weeks.

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.
Currently
 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.
First,
 you can open any notes-file based on date
 with @code{notes-index-link},
 normally bound to @key{o}.
@kindex o

Second,
 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:

@example
# 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
 @file{notes-variables.el}.



@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.

@menu
* 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

Briefly,
 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, <johnh@@isi.edu>)
 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
 <ashvin@@ficus.cs.ucla.edu>
 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},
 @code{notes-goto-index-entry},
 programmed subject completion,
 and
 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
 <geoff@@ficus.cs.ucla.edu>
 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 <govindan@@isi.edu> did the xemacs port.

Since it's release on Usenet in April 1996 several
 other folks have contributed.
Thanks to
 David Weisman <weisman@@app1.osf.org>,
 Martin L. Smith <martin@@ner.com>,
 Jason Bastek <jason@@aai.com>,
 Ulrich Herbst <Ulrich.Herbst@@t-systems.com>.
See the next section (@xref{Changes}.) for details of their exploits.

Thanks to Larry Ayers <layers@@marktwain.net>
 for popularizing notes-mode with reviews in
 the Linux Gazette
 (at <http://www.linuxgazette.com/issue22/notes-mode.html> and
 <http://www.linuxgazette.com/issue35/ayers.html>).

@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
code.

Related work improved (suggestion by David Weisman <weisman@@app1.osf.org>).

Documentation improvement (problem found by Martin L. Smith
<martin@@ner.com>).

Installation improved (code by Jason Bastek <jason@@aai.com>).

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 <tkld@@quadstone.com>).

Y2K statement added
 (suggestion by Kevin Davidson <tkld@@quadstone.com>).

Pointer to mailcrypt added (as a supported encryption package).
Problem pointed out by K. Ueda <kueda@@jupiter.qse.tohoku.ac.jp>.

Changed  4-Nov-98: version 1.16.
Bug in kill-ring handling of notes-old-underline-line
 fixed by Tim Potter <timp@@jna.com.au>.
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 configure.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{notes-mode-announce@@heidemann.la.ca.us} and 
@file{notes-mode-talk@@heidemann.la.ca.us}.
Send the line ``subscribe notes-mode-announce''
(or ``subscribe notes-mode-talk'')
to @file{majordomo@@heidemann.la.ca.us}
to join them.
[@emph{These instructions are now superceeded; to subscribe, go to
@file{http://www.heidemann.la.ca.us/mailman/listinfo/notes-mode-talk}
and
@file{http://www.heidemann.la.ca.us/mailman/listinfo/notes-mode-announce}.}]

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{jaggi@@rsn.hp.com}.)

Outline-minor-mode support added and documented.
(Suggested by Tim Carroll @file{tim@@boomboom.com}.)

Bug/typo fixes in gpg support
(Contributed by William A. Perkins @file{wa_perkins@@pnl.gov},
with separate patches from Knut Anders Hatlen @file{kahatlen@@online.no}.)

Installation improvements suggested by Christophe Troestler
@file{Ch.Troestler@@linkline.be}:
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{michaelt@@supernet.ca}.)

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{kzeitler@@lucent.com}.)

Changed ( 3-Jan-02): version 1.22:
Several bugs in @file{notesinit} for stricter Perl implementations
(bug found by Paul Craven" @file{pcraven@@yorku.ca},
and Kasper van Wijk @file{kasper@@acoustics.mines.edu})
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{nils@@nieback.de}).

Install bug involving ordering of scripts and byte-compilation
fixed (bug and fix from Mark Allman @file{mallman@@grc.nasa.gov}).

Fix obscure bug in configure, reported by Klaus Zeitler @file{kzeitler@@lucent.com}.

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{falk@@isi.edu}).

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{bronger@@physik.rwth-aachen.de}.

Fixed a bug in mkindexcache, triggered by subjects with percent signs
in them.  Bug reported by Philip Austin @file{paustin@@eos.ubc.ca}.

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{paustin@@eos.ubc.ca}.

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{falk@@isi.edu}.

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{allman@@icir.org}.

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,

@enumerate
@item
Unpack and extract the distribution
(gunzip notes-mode-xxx.tar.gz; tar xvf notes-mode-xxx.tar; cd notes-mode-xxx).

@item
Run configure (./configure).

@item
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:
@enumerate
@item
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
 @file{http://www.isi.edu/~johnh/SOFTWARE/NOTES_MODE/}.


@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




@contents
@bye

@c Geoff, make ispell support texinfo mode!
@c
@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