1 \input texinfo @c -*-texinfo-*-
3 @setfilename notes-mode.info
5 @c For double-sided printing, uncomment:
6 @c @setchapternewpage odd
9 @set EDITION $Revision: 1.40 $
10 @c XXX: the next line should track the release file.
12 @set UPDATED $Date: 2010/06/20 18:30:34 $
21 * Notes-mode: (notes-mode). Organizing on-line note-taking.
25 Notes-mode: Organizing on-line note-taking.
27 This file documents notes-mode, a package
28 for organizing on-line note-taking.
30 Copyright (C) 1994-1996 by John Heidemann
32 Permission is granted to make and distribute verbatim copies of
33 this manual provided the copyright notice and this permission notice
34 are preserved on all copies.
37 Permission is granted to process this file through TeX and print the
38 results, provided the printed document carries copying permission
39 notice identical to this one except for the removal of this paragraph
40 (this paragraph not being relevant to the printed manual).
43 Permission is granted to copy and distribute modified versions of this
44 manual under the conditions for verbatim copying, provided that the entire
45 resulting derived work is distributed under the terms of a permission
46 notice identical to this one.
48 Permission is granted to copy and distribute translations of this manual
49 into another language, under the above conditions for modified versions,
50 except that this permission notice may be stated in a translation approved
56 @subtitle Organizing on-line note-taking
57 @subtitle Edition @value{EDITION}, for notes-mode version @value{VERSION}
58 @subtitle @value{UPDATED}
59 @author by John Heidemann
62 @vskip 0pt plus 1filll
63 Copyright @copyright{} 1994-1996 by John Heidemann
65 Permission is granted to make and distribute verbatim copies of
66 this manual provided the copyright notice and this permission notice
67 are preserved on all copies.
69 Permission is granted to copy and distribute modified versions of this
70 manual under the conditions for verbatim copying, provided that the entire
71 resulting derived work is distributed under the terms of a permission
72 notice identical to this one.
74 Permission is granted to copy and distribute translations of this manual
75 into another language, under the above conditions for modified versions,
76 except that this permission notice may be stated in a translation approved
80 @node Top, Introduction, (dir), (dir)
81 @comment node-name, next, previous, up
84 This file documents notes-mode, a package
85 for organizing on-line note-taking.
86 This is edition @value{EDITION}, for notes-mode version @value{VERSION},
87 last updated @value{UPDATED}.
92 @c Outline as of 16-Apr-96:
95 @c - what is notes mode
96 @c - why keep notes on-line
97 @c - easier to type than write
98 @c - information already on-line (program errors, measurement data, etc.)
99 @c - easy to search (grep, glimpse)
100 @c - easy to index (notes-mode)
101 @c - why use notes-mode
102 @c - automates indexing
104 @c - emacs helpers (subject completion, elisp customization)
106 @c HTML (+formatting, +links, -tags are intrusive, -errors are bad, -index by hand)
107 @c word processor (+formatting, -links, -indexing)
109 @c - notes-mode is not related to Lotus Notes
117 @c like urls, but not quite
118 @c mouse-2 follows a link (and also pastes)
120 @c can contain other, embedded links
123 @c mouse-2 follows links
126 @c - root ~/NOTES, changing
127 @c - intermediate directories @cY@cm
128 @c - notes-files @cy@cm@cd
129 @c intermediate features
134 @c date in front-matter
135 @c hierarchical subjects
136 @c - C-c C-s subject summary
137 @c - C-c C-k current-url-as-kill
139 @c - C-c C-i notes-goto-index-entry
140 @c - C-c C-n notes-follow-next-link, C-c C-p notes-follow-prev-link
141 @c - C-c C-f notes-w3-follow-link
142 @c - M-C-a notes-beginning-of-defun, M-C-e notes-end-of-defun
143 @c - C-c C-e, C-c C-s encryption
145 @c - RET notes-index-follow-link
146 @c - o notes-index-link
147 @c - C-c C-s summarize subject
148 @c advanced features:
151 @c - genesis: minimal functionality: subject collection
152 @c - Leviticus: indexing, urls
153 @c - exodus: share with others
154 @c - Deuteronomy: features are added
159 @c The master menu, created with texinfo-master-menu, goes here.
164 * Advanced Features::
171 --- The Detailed Node Listing ---
176 * Why keep notes at all?::
177 * Why keep notes on-line?::
178 * Why use notes-mode?::
188 * The notes directories::
194 * Notes-mode configuration::
201 * Useful conventions::
205 * Notes-mode history::
212 @c ----------------------------------------------------------------------
214 @node Introduction, Basics, Top, Top
215 @chapter Introduction
217 What is notes-mode and why should you (perhaps) use it?
221 * Why keep notes at all?::
222 * Why keep notes on-line?::
223 * Why use notes-mode?::
229 @node What is it?, Why keep notes at all?, Introduction, Introduction
230 @comment node-name, next, previous, up
233 Notes-mode is an indexing system for on-line note-taking.
234 Notes-mode is composed of two parts, the visible part,
235 a major-mode for emacs to aid note-taking;
236 and the invisible part,
237 scripts which periodically index your notes for you.
239 Note that notes-mode provides tools to @dfn{index} your notes,
240 not to @dfn{search} them.
241 (Other existing tools such as @file{grep}, @file{agrep}, and @file{glimpse}
242 already allow file search.)
244 A digression about indexing vs. searching:
245 Indexing in this sense means
246 organize them according to categories you give,
247 while searching looks through all text for arbitrary strings.
248 Drawing on the World Wide Web for examples,
249 Yahoo (@file{http://www.yahoo.com/}) is an index,
250 while Alta Vista (@file{http://www.altavista.digital.com/})
252 In (potentially) more familiar terms,
254 @footnote{Trademarked, in Great Britain, Sunone tells me.}
256 while directory information (411 in the USA)
257 is sort of a search-engine.
260 @node Why keep notes at all?, Why keep notes on-line?, What is it?, Introduction
261 @comment node-name, next, previous, up
262 @section Why keep notes at all?
264 So why should you use notes-mode?
265 Well, first, consider why you should (perhaps)
266 keep your notes on line.
268 I assume that you take notes as part of your work or school.
270 you can stop reading now and go back to watching TV.
272 If you keep notes, ask yourself why you keep them.
273 Reasons vary for different people, but some include:
278 To remember what is said or done.
281 To focus on what is important about what is said.
284 To provide proof of having done something
285 at a particular time or date.
288 I know there were other reasons here,
289 but they slipped my mind.
293 @node Why keep notes on-line?, Why use notes-mode?, Why keep notes at all?, Introduction
294 @comment node-name, next, previous, up
295 @section Why keep notes on-line?
297 OK, I've talked you into keeping notes.
299 Again, there are different reasons for different people.
300 If you don't want to consider keeping your notes on-line,
301 you're welcome to go back to your (clay tablets)
304 However, if you do much of your work on-line,
305 or if you have portable computer,
306 then you might want to consider keeping your notes on-line.
311 It's faster to type than write,
312 and possibly more legible at high speed.
315 Often information is already on-line.
316 For example, in software development, bug reports,
317 measurement results, and everything else that's useful
321 You can take down more detail than you otherwise would
322 (especially if the data is already on-line).
323 Taking more copious notes can be helpful when you go back
324 to figure out why that strange thing was happening.
327 On-line notes are easy to search.
328 Full-text search with
329 grep, agrep, and glimpse are all much faster
330 and are often more accurate than paging through paper notes
331 looking for a particular keyword.
334 On-line notes are easy to index.
335 (At least with notes-mode!)
336 In addition to full-text search,
337 it's helpful to organize notes by category.
338 If you keep a table-of-contents of your paper notes,
339 you are either extremely fastidious
340 or a librarian (Nadia?).
343 You can keep all of your notes with you at all times
344 (if you have a portable computer).
345 Even at a page a day,
346 paper notes quickly become bulky and awkward to carry around.
347 On-line notes fit on your computer's hard disk,
348 an extraordinarily compact medium
352 Your notes can be automatically backed up.
353 Paper notes can become damaged with time,
354 and as a graduate student
355 one of my fears was fire in Boelter Hall
356 consuming all my research experiments
357 and and therefore hopes of a degree.
358 Electronic notes are extremely easy to duplicate
359 and can be automatically backed up with the rest of your computer.
360 (You @emph{do} back up your computer, don't you?)
364 While these advantages are undoubtedly clear to any
365 right-thinking computer user,
366 it should be said that there are a few disadvantages
367 for on-line note-taking.
372 If you don't have a computer with you most of the time,
373 it's difficult take notes on-line (because you're off-line, of course).
374 @footnote{I consider myself pretty anal about this subject,
375 often typing notes in from paper after-the-fact,
376 and @emph{I} certainly don't manage to back-enter
377 my notes all time time.}
380 Computers require power.
381 If your portable computer runs out of juice,
383 Corollary: watch your power, or bring paper.
384 Better corollary: watch your power, @emph{and} bring paper.
388 It's not always socially acceptable to take notes-on-line.
391 few people would use a computer
392 to take down the phone number of a person
393 to whom they're attracted
394 (at least, if they wanted the attraction to be mutual).
396 On the other hand, some folks at MIT are working
397 on this problem from both the hardware and the social side of
398 things (@file{http://wearables.www.media.mit.edu/projects/wearables/})
399 (Perhaps they have wild parties with computers, too.)
401 Sometimes other people find the sound of typing distracting.
405 Repetitive stress injuries do occur
406 writing (slower) by hand is at least
407 an alternate motion than typing.
411 If you want to use your electronic notes
412 to justify a patent or invention,
413 you may be breaking legal ground.
414 Being on the legal cutting-edge is rarely an easy thing
415 for the person involved.@footnote{My hat is off to Rosa Parks
416 and the many other normal people who triggered landmark cases.}
421 @node Why use notes-mode?, Y2K Statement, Why keep notes on-line?, Introduction
422 @comment node-name, next, previous, up
423 @section Why use notes-mode?
425 OK, I've sold you on note-taking and even on on-line note-taking.
426 What about notes-mode?
428 it slices, dices, and makes julienne fries.
429 But wait, there's more:
434 It automates indexing your notes,
435 linking notes with the same subject together.
438 It supports embedded links,
439 allowing you to manually link together different topics
443 It includes a number of convenience-features in emacs.
444 Subjects can be completed based on existing subjects.
445 The usual emacs customization mechanisms are available.
448 Notes containing sensitive information can be encrypted.
451 Notes-mode seems better than the other, currently available alternatives.
454 What are the alternatives? I'm glad you asked.
455 @footnote{If you think I'm missing an alternative, please let me know.}
461 HTML has better formatting capabilities than notes-mode,
462 and it has excellent linking capabilities.
464 HTML's tags are fairly intrusive
465 (each is at least four characters long and most come with a pair),
466 tags can get confused with normal text,
467 errors in HTML can be bad (obscuring data),
468 and there's no automatic indexing feature
469 (at least with plain HTML).
471 all data should be kept as close to the ASCII from whence it came,
472 as God Intended (hi, Steve).
475 @strong{Word Processors}.
476 Word processors are strong in the formatting department,
477 but most don't really have linking capabilities,
478 and have poor or restricted indexing.
482 @node Y2K Statement, Related work, Why use notes-mode?, Introduction
483 @comment node-name, next, previous, up
484 @section Y2K Statement
486 Notes mode uses dates extensively,
487 both two-digit years and seconds-since-1970.
488 However, notes-mode has been coded to function correctly through
491 To avoid problems with the year 2000, notes-mode assumes
492 that any two-digit years before ``70'' are 20xx, not 19xx.
493 Notes-mode should therefore work correctly in both the year 1999 and 2000.
495 (Notes-mode 1.17 released February 1999 fixes a lingering Y2K problem.)
497 Because notes-mode uses seconds-since-1970 for some date calculations
498 it will fail beyond the year 2038 on computers with 32-bit integers.
500 If I'm still using notes-mode then on a 32-bit machine I'll see what I can do.
503 @node Related work, Staying on top, Y2K Statement, Introduction
504 @comment node-name, next, previous, up
505 @section Related work
507 What would a document be without related work?
509 Notes-mode is not related in any way to Lotus Notes.
511 I am told (by David Weisman)
512 that it's something like the now defunct Lotus Agenda.
514 Ashvin Goel, one of the contributors to notes-mode,
515 has gone off and done a from-scratch reimplementation
517 It's very similar to notes mode,
518 and emphasizes on-the-fly updates to entry links
520 You may want to check it out at
521 @file{http://www.cse.ogi.edu/~ashvin/software.html}.
523 Hyperbole (by Bob Weiner) offers better linking facilities
524 than notes-mode, but it has a bunch of stuff notes-mode doesn't need
525 and it's missing notes-specific indexing provided by notes-mode.
526 For people already using Hyperbole
527 it would be interesting to replace notes-mode's linking
529 Contributions in this area are welcome, provided they make Hyperbole
532 @node Staying on top, , Related work, Introduction
533 @comment node-name, next, previous, up
534 @section Staying on top
536 The most recent distribution of notes-mode
537 is always available via
538 @file{http://www.isi.edu/~johnh/SOFTWARE/NOTES_MODE/}.
540 After you've installed notes mode you're encouraged to subscribe
541 to the mailing lists.
542 To subscribe, go to the web page
543 Send the message "subscribe" to
544 @file{http://www.heidemann.la.ca.us/mailman/listinfo/notes-mode-announce} or
545 @file{http://www.heidemann.la.ca.us/mailman/listinfo/notes-mode-talk}.
547 The announce list will contain only release announcements
548 and so is guaranteed to be very low bandwidth.
551 @c ----------------------------------------------------------------------
553 @node Basics, Advanced Features, Introduction, Top
554 @comment node-name, next, previous, up
557 All you need to use notes-mode
559 (Except for installation, @xref{Installation}.)
565 * The notes directories::
568 @node Getting started, A notes file, Basics, Basics
569 @comment node-name, next, previous, up
570 @section Getting started
574 To get started with notes-mode,
575 read the introduction this chapter,
582 @kbd{M-x} @code{load-library} @kbd{RET} @code{notes-mode} @kbd{RET}
583 This approach will set up notes-mode with the default parameters.
587 run the program @file{notesinit}.
588 This approach will ask you some questions about how you want to configure
593 Either way these should set up everything notes-mode needs.
594 This program will modify your environment (as described in this section),
595 or it will give you the exact commands you should run yourself.
597 After you've done one of these,
598 start up emacs and note-away.
600 day of note-taking by running the command
601 @kbd{M-x} @code{notes-index-todays-link}
602 to jump directly to today's note.
603 You may even wish to bind this to something,
605 @code{(define-key global-map "\C-cn" 'notes-index-todays-link)}
606 in your @file{.emacs}.
608 If you want to browse your existing notes,
609 you might instead want to edit the
610 @file{~/NOTES/index}.
611 (What is a notes file and the index? Hurry up and finish
612 reading this chapter.)
615 @node A notes file, The notes index, Getting started, Basics
616 @comment node-name, next, previous, up
617 @section A notes file
624 @c like urls, but not quite
625 @c mouse-2 follows a link (and also pastes)
627 @c can contain other, embedded links
631 The notes file is the focus of most of the activity in notes-mode,
632 it's where you take your notes.
633 Notes files are mostly free-form text
634 broken up into @dfn{entries}.
637 @cindex Notes entries
646 next: <file:///~/NOTES/199506/950609#* Today>
648 next week - release notes-mode
654 I explained notes mode to Ashvin and Geoff.
658 Each entry has a subject-block, (maybe) some links, and then (maybe) some text.
660 The subject-block must begin with an asterisk-space (@kbd{* })
661 at the beginning of a line, followed by the subject itself.
662 Subjects must be underlined with a row of dashes
663 (if they're not exact, that's OK;
664 notes-mode will fix them periodically).
666 notes-mode will automatically add the underlines when you
667 hit @kbd{@key{RTN}} (@code{notes-electric-return}),
668 and @kbd{@key{TAB}} on a partially completed subject will
669 invoke completion based on indexed subjects (@code{notes-complete-subject}).
670 @cindex Notes subjects
674 Following the subject may be links.
675 (In the example, the ``Today'' entry has links,
676 the ``Environment/notes'' entry doesn't.)
677 These links will be automatically updated by notes-mode
678 when your notes are re-indexed;
679 just leave a blank line when writing the note.
682 Links are made with pseudo-URLs,
683 sort of like those in the World Wide Web.
684 Any of these URLs can be followed in notes-mode files
685 by clicking @kbd{S-mouse-2} on the pseudo-URL
686 (@code{notes-w3-follow-link-mouse}).
691 Finally comes the text.
692 Go wild, but just don't include text that looks like a subject.
693 You can embed pseudo-URLs to link notes together manually.
695 The more anal of you may have noticed
696 that the lines before the first subject
697 are not part of any entry.
700 They're not usually used for much,
701 but they can be a good place to label the file.
702 @cindex Notes files, font matter
705 There are a number of useful conventions
706 that can be adopted to organize your notes.
707 The most common is the ``Today'' entry.
708 If you keep an entry with the same subject
709 at the beginning of each file,
710 you link all of your notes together.
711 Notes-mode will help you out with some of these convetions
712 by automatically creating or copying some fields for you;
713 see @pxref{Useful conventions} for details.
715 Finally, notes-mode can also work with outline-minor-mode
716 (thanks to Tim Carroll for pointing this out).
717 Outline-mode supports hiding and revealing text and other helpful
718 features beyond the scope of this document.
719 @xref{Outline Mode, Outline Mode, , emacs, The Emacs Editor}, for details.
721 @node The notes index, The notes directories, A notes file, Basics
722 @comment node-name, next, previous, up
723 @section The notes index
726 @c mouse-2 follows links
731 The notes index lists all subjects you've kept notes about,
732 and each date of each note.
733 Impress your friends,
734 show your advisor why you're worth the @emph{big} peanuts,
735 you'll soon have the biggest index of all.
737 The index has one line per subject, listing the subject
738 and each day a note was made about that subject.
742 Bicycle: 950314, 950316
743 Bicycle/maintenance/books: 951028
744 Bridge/hands: 951113, 951114, 951116, 951117
745 Bridge/UCLA: 960222, 960409
748 Clicking on any of the dates with @kbd{mouse-2}
749 will take you to that note
750 (@code{notes-index-mouse-follow-link}).
751 (You can also move the point over the date and hit @kbd{@key{RTN}}
752 if you're musaphobic [@code{notes-index-follow-link}].)
756 The notes index is automatically updated by the program @file{mkall}.
757 Typically @file{mkall} is run nightly by @file{cron}.
758 On most modern versions of Unix, you can add this command to cron by
759 running @file{crontab -e} and adding the line:
762 0 4 * * * /usr/local/lib/notes-mode/mkall
768 (Assuming that your notes programs are installed
769 in /usr/local/lib/notes-mode, the default location.)
772 @node The notes directories, , The notes index, Basics
773 @comment node-name, next, previous, up
774 @section The notes directories
776 @cindex Notes directories
777 @cindex Directory hierarchy
779 The final thing needed to tie basic notes-mode together his how
780 the pieces fit together.
781 Since my graduate work is in file systems,
782 you can bet that directories are involved.
784 Notes-mode keeps its files in a two-level hierarchy:
791 ~/NOTES/199603/960329
792 ~/NOTES/199603/960330
794 ~/NOTES/199604/960401
797 The top level, @file{~/NOTES}, is the notes directory.
798 It keeps all notes in one place.
799 (The name of this directory is configurable, @xref{Notes-mode configuration}.)
801 Inside the notes directory are two files and a number of directories.
802 The files are @file{index},
803 the index of all entries (@pxref{The notes index}),
806 @cindex Root directory
808 The notes directory also contains a number of subdirectories,
809 sometimes called @dfn{intermediate directories}.
810 These directories group the actual notes files into manageable chunks,
811 keeping any directory from getting too large.
812 Intermediate directories are named
813 by the four-digit year and the two-digit month
814 of the entries they contain.
815 (The format of intermediate directories
816 is configurable, @xref{Notes-mode configuration}.)
817 @cindex Intermediate directories
820 each intermediate directory are the notes files themselves,
821 named according to the two-digit year, month, and day-of-month.
825 notes-mode will automatically maintain this organization of files,
826 once you create the top-level directory.
827 Notes-mode will also automatically insure
828 that all files in the notes directory are unreadable by
829 anyone other than their owner.
830 Notes are personal things.
831 (This behavior is not currently configurable,
832 but it probably should be.)
833 @cindex Notes file permissions
836 @c ----------------------------------------------------------------------
838 @node Advanced Features, History, Basics, Top
839 @comment node-name, next, previous, up
840 @chapter Advanced Features
842 Notes-mode, the minutiae, and some other good stuff.
847 * Notes-mode configuration::
850 @node Notes files, Notes indices, Advanced Features, Advanced Features
851 @comment node-name, next, previous, up
858 * Useful conventions::
861 @node Getting around, Subject summary, Notes files, Notes files
862 @comment node-name, next, previous, up
863 @subsection Getting around
865 Moving between notes entries and around the hierarchy is fairly common,
866 so there are some accelerators.
870 Jump to the index entry for the current entry's subject
871 (@code{notes-goto-index-entry}).
876 Move to the next or prior note with the same subject
877 (@code{notes-follow-next-link} and @code{notes-follow-prev-link}).
878 These functions follow the links in the note,
881 they look through the index file.
882 This approach usually works,
883 but will fail if there are multiple new entries created
884 with the given subject
885 between when the index is recomputed.
890 Follow the link under the point
891 (@code{notes-w3-follow-link}),
892 a keyboard equivalent of @key{S-mouse-2}.
897 Jump to the beginning or end of the current note entry
898 (@code{notes-beginning-of-defun} and @code{notes-end-of-defun}).
903 Copies the pseudo-URL for the current note into the kill-ring
904 (@code{current-url-as-kill}).
905 To link two entries, go to the target,
906 grab its URL with @kbd{C-c C-k},
907 go to where you want to make the link,
908 and yank the URL with @kbd{C-y}.
913 Notes mode supports imenu,
914 if you have it bound to something
915 (I use @code{(global-set-key [down-mouse-3] 'imenu)}).
919 @node Subject summary, Encryption, Getting around, Notes files
920 @comment node-name, next, previous, up
921 @subsection Subject summary
923 It's often helpful to look at all
924 entries for a given subject
926 collects all entries with the subject of the current
927 entry in a new buffer
928 (@code{notes-summarize-subject}).
930 @cindex Subject summary
933 @node Encryption, Useful conventions, Subject summary, Notes files
934 @comment node-name, next, previous, up
935 @subsection Encryption
940 @c - C-c C-e, C-c C-d encryption
941 Notes occasionally contain private material.
942 While Unix has strong services for file protection
943 (compared to other, say, more wide-selling operating systems),
944 in many systems root passwords are shared,
945 while other systems are vulnerable to physical compromise.
947 properly used encryption is the best approach to security.
949 Notes-mode encryption is based
950 Phill Zimmerman's PGP (Pretty Good Privacy)
951 (see @file{http://www.mantis.co.uk/pgp/pgp.html})
954 emacs interface, PAM (PGP Augmented Messaging)
955 (from @file{ftp://h.gp.cs.cmu.edu/usr/rfb/pam/})
956 (note that as of January 1997, PAM is no longer at this ftp site
957 and appears to not be publicly available),
958 or LoPresti and Choi's mailcrypt
959 (from @file{http://cag-www.lcs.mit.edu/mailcrypt/}).
961 @cindex Pretty good privacy
963 @cindex PGP Augmented Messaging
968 Encrypt the current note
969 (@code{notes-encrypt-note}).
970 By default this function encrypts the whole entry.
971 With a prefix argument,
972 only the part from the point to the end of the entry is encrypted.
976 Decrypt the current note
977 (@code{notes-decrypt-note}).
981 By default notes-mode determines your public key by looking
982 up your @code{user-full-name} in your PGP keyring.
983 You can override this default by setting
984 @code{notes-encryption-key-id}
985 to the desired key-id.
989 @node Useful conventions, , Encryption, Notes files
990 @comment node-name, next, previous, up
991 @subsection Useful conventions
994 @c date, 12-Jan-96 Friday
997 @c hierarchical subjects
1002 There are a number of conventions which can make notes-mode
1004 These conventions are a matter of personal taste,
1006 Do what works for you.
1009 I find it helpful to keep the date of each notes-file at the top
1011 This makes the file self-identifying
1012 if the filename is lost.
1015 I find it useful to have the first entry of each file
1016 have the same subject (perhaps ``Today'').
1017 This entry then links all notes together,
1018 making it easy to go to yesterday and tomorrow.
1019 I keep a to-do list on this entry,
1020 bringing the list forward each day.
1023 A third useful convention is to keep an
1024 entry with the name based on the day of the week
1026 Analogous to ``Today'', this entry links together
1029 Notes-mode supports these conventions.
1030 When you make a new notes-file in emacs,
1031 notes-mode searches for the preceding file.
1032 If it follows any of these conventions,
1033 the new file is initialized appropriately.
1035 the approach to do this process
1036 (in the program @file{mknew})
1037 is fairly sensitive,
1038 so it may not work in all cases.
1040 the date convention works only on
1041 for English-language dates.
1042 (If you use notes-mode with a non-English language,
1043 let me know and I'll work with you to fix this limitation.)
1045 If you find other helpful conventions,
1047 Modifications to @file{mknew} to implement
1048 new conventions are also invited.
1050 If you don't want to use these conventions,
1051 or if you want to use different ones,
1052 set the emacs variable notes-mode-initialization-program
1053 to nil or the name of your initialization program.
1054 @cindex notes-mode-initialization-program
1057 @node Notes indices, Notes-mode configuration, Notes files, Advanced Features
1058 @comment node-name, next, previous, up
1059 @section Notes indices
1062 @c - RET notes-index-follow-link
1063 @c - o notes-index-link
1064 @c - C-c C-s summarize subject
1066 Only two features of notes index mode haven't yet been described.
1068 you can open any notes-file based on date
1069 with @code{notes-index-link},
1070 normally bound to @key{o}.
1074 you can get a subject-summary
1076 (@pxref{Subject summary}).
1077 The subject defaults to that of the current index line.
1081 @node Notes-mode configuration, , Notes indices, Advanced Features
1082 @comment node-name, next, previous, up
1083 @section Notes-mode configuration
1085 @cindex configuration
1088 Several aspects of notes mode are particularly visible
1090 Because I'm not a fascist,
1091 a user can change most of these.
1093 Preferences are specified in @file{~/.notesrc}.
1094 This file lists things to change:
1097 # lines beginning with a hash are comments
1102 Currently, two things can be changed:
1106 Specifies the root of the notes directory hierarchy
1107 (@pxref{The notes directories}).
1110 Specifies the form of the intermediate directory.
1111 A limited subset of @code{strftime(3)}
1112 formatting is allowed.
1115 The subset of @code{strftime(3)} supported in @code{int_form} is:
1118 The four-digit year.
1124 A two-digit numeric month.
1130 In addition to @file{.notesrc},
1131 there are a number of emacs-specific variables.
1132 These variables are documented in the file
1133 @file{notes-variables.el}.
1137 @c ----------------------------------------------------------------------
1139 @node History, Installation, Advanced Features, Top
1140 @comment node-name, next, previous, up
1143 More about notes-mode than you wanted to know,
1147 * Notes-mode history::
1150 * Suggested features::
1154 @c - genesis: minimal functionality: subject collection
1155 @c - Leviticus: indexing, urls
1156 @c - exodus: share with others
1157 @c - Deuteronomy: features are added
1160 @node Notes-mode history, Credits, History, History
1161 @comment node-name, next, previous, up
1162 @section Notes-mode history
1165 I started keeping notes on-line shortly after I got a portable computer
1167 After a month-and-a-half of notes, I realized that
1168 one does not live by grep alone,
1169 so I started adding indexing facilities.
1172 some other Ficus-project members started
1173 keeping and indexing on-line notes
1174 using other home-grown systems.
1175 After some discussion,
1176 we generalized my notes-mode work and
1177 they started using it.
1179 Over the next 18 months notes-mode grew.
1180 Finally, in April, 1996 I wrote documentation,
1181 guaranteeing that innovation on notes-mode will now cease
1182 or the documentation will become out of date.
1185 @node Credits, Changes, Notes-mode history, History
1186 @comment node-name, next, previous, up
1189 I (John Heidemann, <johnh@@isi.edu>)
1190 started, documented, and currently maintain notes-mode.
1191 I take ultimate responsibility for the code,
1192 especially for the ugly parts that I won't let others change.
1195 <ashvin@@ficus.cs.ucla.edu>
1196 has been a very enthusiastic notes-mode user and contributor.
1197 He is responsible for at least
1198 the ideas behind @code{notes-summarize-subject}
1199 and the ideas and initial implementations of
1200 some of the original generalization and modularity improvements,
1201 @code{notes-follow-next-link} and @code{notes-follow-prev-link},
1202 @code{notes-goto-index-entry},
1203 programmed subject completion,
1205 context-sensitive mouse-2 handling.
1207 he is an invaluable second opinion about
1208 what and how things should be done
1209 (even if I don't always agree with him).
1212 <geoff@@ficus.cs.ucla.edu>
1213 has been another enthusiastic notes-mode user and victim.
1214 He is responsible for
1215 finding several bugs,
1216 motivation for mouse-less operation,
1217 comments about the documentation,
1218 the day-of-week convention,
1219 and an initial implementation and the idea of
1220 multiple entries with the same subjects in a single notes-file.
1222 Ramesh Govindan <govindan@@isi.edu> did the xemacs port.
1224 Since it's release on Usenet in April 1996 several
1225 other folks have contributed.
1227 David Weisman <weisman@@app1.osf.org>,
1228 Martin L. Smith <martin@@ner.com>,
1229 Jason Bastek <jason@@aai.com>,
1230 Ulrich Herbst <Ulrich.Herbst@@t-systems.com>.
1231 See the next section (@xref{Changes}.) for details of their exploits.
1233 Thanks to Larry Ayers <layers@@marktwain.net>
1234 for popularizing notes-mode with reviews in
1236 (at <http://www.linuxgazette.com/issue22/notes-mode.html> and
1237 <http://www.linuxgazette.com/issue35/ayers.html>).
1239 @node Changes, Suggested features, Credits, History
1240 @comment node-name, next, previous, up
1245 First semi-public release. 12-Jul-95: version 0.1
1246 Shared a version with Ashvin and Geoff.
1248 Changed 6-Dec-95: version 0.3
1249 Ashvin's changes for note traversal added (C-c C-p and C-c C-n now
1250 move to the prev/next note in note-mode).
1251 URL parsing changed so that "localhost" is optional.
1253 Changed 19-Dec-95: version 0.4
1254 More robust prev/next code added, both to handle going back and
1255 forward in the middle of chains through the index file, and to handle
1256 back/forward in a single file.
1257 URL parsing changed so that notes-goto-index-entry correctly handles
1258 lookups on notes names such as "252A".
1260 Changed 20-Dec-95: version 0.5.
1261 Fixed a missing variable in notes-url.el.
1262 Added a work-around to a bug in emacs-19.30's define-derived-mode.
1264 Changed 24-Dec-95: version 0.6.
1265 Prev/next code re-re-written to be more robust.
1267 Changed 26-Dec-96: version 0.7.
1270 Changed 23-Jan-96: version 0.8.
1271 Initialization code added to set up a new note.
1272 New variable: notes-bin-dir.
1274 I'm skipping version 0.9 because I erroneously release version 0.1
1275 as version 0.9 (only on the web, not on Usenet).
1277 I'm bumping from version "0" to version "1" since the code is has been
1278 in production use for more than a year by several people. Minor
1279 numbers are the same.
1281 Changed 26-Mar-96: version 1.10.
1282 Setup code completely re-written.
1283 Several incompatible changes have been made:
1284 - the lisp and Perl code must be installed via make install,
1286 - some data is specified in a .notesrc file; copy and modify sample.notesrc.
1287 - several internal elisp changes.
1288 - catsubject added (bound to C-cC-s): collect all notes about the
1290 - new notes-files are initialized with fields based on the prior
1291 day's notes; see mknew for details.
1292 - daily_work is gone; mkall is rewritten to use .notesrc.
1294 Changed 29-Apr-96: version 1.11.
1296 Mknew caching added.
1298 Changed 9-Aug-96: version 1.12.
1299 Added notesinit to do all setup for new users.
1301 Changed 24-Aug-96: version 1.13.
1302 Minor documentation fixes.
1304 Changed 20-Dec-97: version 1.14.
1307 Fontification of the index buffer is now pre-computed in perl
1308 other than done when the file is needed (in elisp with slow regular
1309 expressions). 2000-line index files are now 1-2 seconds rather than
1310 15-30 on a 100MHz Pentium. If necessary (the
1311 pre-computed version isn't up-to-date) we fall back on the slower
1314 Related work improved (suggestion by David Weisman <weisman@@app1.osf.org>).
1316 Documentation improvement (problem found by Martin L. Smith
1319 Installation improved (code by Jason Bastek <jason@@aai.com>).
1321 Bug in notes-index mode with subjects containing colons fixed (johnh).
1323 Encryption now supports mailcrypt.el.
1325 Support for emacs 20 (a small font-lock change).
1327 Changed 5-Jan-98: version 1.15.
1328 Bug in decryption for non-PAM users fixed
1329 (suggestion by Kevin Davidson <tkld@@quadstone.com>).
1332 (suggestion by Kevin Davidson <tkld@@quadstone.com>).
1334 Pointer to mailcrypt added (as a supported encryption package).
1335 Problem pointed out by K. Ueda <kueda@@jupiter.qse.tohoku.ac.jp>.
1337 Changed 4-Nov-98: version 1.16.
1338 Bug in kill-ring handling of notes-old-underline-line
1339 fixed by Tim Potter <timp@@jna.com.au>.
1340 Bug in whitespace handling after PGP encryption fixed by Tim Potter.
1341 Bugs in handling of entries with hash signs in their name fixed
1342 (found by Tim Potter).
1343 Fontification of index buffer further improved
1344 (mapcar is your friend).
1345 Xemacs support added based on code contributed by Ramesh Govindan.
1347 Changed 28-Feb-99: version 1.17:
1348 Improvement: notes-electric-return now fixes up the prev/next links
1349 of new entries (only). Code contributed by
1352 Bug fix: reversed options -batch and -q in configure.in to placate
1353 XEmacs 20.0; changed notesinit to not downcase the pathname
1354 (bugs found by Thierry Bezecourt).
1356 Clarification: Autofilling of new notes more clear in the manual (hopefully,
1357 suggested by Solofo Ramangalahy).
1359 Bug fix: a y2k bug in was found and fixed in mkindex. Sigh.
1361 New: Two mailing lists for notes-mode have been created:
1362 @file{notes-mode-announce@@heidemann.la.ca.us} and
1363 @file{notes-mode-talk@@heidemann.la.ca.us}.
1364 Send the line ``subscribe notes-mode-announce''
1365 (or ``subscribe notes-mode-talk'')
1366 to @file{majordomo@@heidemann.la.ca.us}
1368 [@emph{These instructions are now superceeded; to subscribe, go to
1369 @file{http://www.heidemann.la.ca.us/mailman/listinfo/notes-mode-talk}
1371 @file{http://www.heidemann.la.ca.us/mailman/listinfo/notes-mode-announce}.}]
1373 Changed 6-Oct-99: version 1.18:
1374 Bug fix: handling of electric-prevnext is better when there are
1375 existing prev/next links.
1377 Clarification: I added some pointers in the code to the installation
1378 instructions. (Apparently people can't RTF README.)
1380 Extension: mailcrypt-3.5.x suported including pgp, pgp5 and gpg.
1382 Changed (date 23-Dec-00): version 1.19:
1383 Bug fix (cosmetic): suppress comments in encrypted nodes.
1385 Install fixes from Kannan Varadhan: elisp directories changed on install.
1387 Added C-j as a synonym for RET in notes-mode to parallel C++ or perl mode.
1388 (Suggested by Fred Jaggi @file{jaggi@@rsn.hp.com}.)
1390 Outline-minor-mode support added and documented.
1391 (Suggested by Tim Carroll @file{tim@@boomboom.com}.)
1393 Bug/typo fixes in gpg support
1394 (Contributed by William A. Perkins @file{wa_perkins@@pnl.gov},
1395 with separate patches from Knut Anders Hatlen @file{kahatlen@@online.no}.)
1397 Installation improvements suggested by Christophe Troestler
1398 @file{Ch.Troestler@@linkline.be}:
1399 use install-info to update the info dir,
1400 warn users of --prefix that lisp files go elsewhere.
1402 Changed (date 1-Feb-01): version 1.20:
1403 Bug fix: missing file notes-first.el added to the distribution.
1404 (Bug found by Michael Totschnig @file{michaelt@@supernet.ca}.)
1406 Changed ( 5-Dec-01): version 1.21:
1407 (backed-out---didn't work with spaced URLs)
1408 URL lookup now uses thing-at-point.
1410 Fix to make notes-mode work with emacs-21.1
1411 (Fix from Klaus Zeitler @file{kzeitler@@lucent.com}.)
1413 Changed ( 3-Jan-02): version 1.22:
1414 Several bugs in @file{notesinit} for stricter Perl implementations
1415 (bug found by Paul Craven" @file{pcraven@@yorku.ca},
1416 and Kasper van Wijk @file{kasper@@acoustics.mines.edu})
1417 and to make it run cleanly more often.
1419 Notes-first now autoinitializes notes mode from emacs.
1420 (As instisted by rms, unfortunately about two years later than requested.)
1423 Changed (20-Feb-05): version 1.23:
1424 Outline mode is now forcebly turned on to avoid interactions
1425 with user's text-mode hooks
1426 (bug and fix from Nils Ackermann @file{nils@@nieback.de}).
1428 Install bug involving ordering of scripts and byte-compilation
1429 fixed (bug and fix from Mark Allman @file{mallman@@grc.nasa.gov}).
1431 Fix obscure bug in configure, reported by Klaus Zeitler @file{kzeitler@@lucent.com}.
1433 Fix for notes-summarize-subject when no subject is specified (bug and fix
1434 from Geoff Kuenning).
1436 Changed (14-Jan-06): version 1.24:
1438 install-info bug documented with the Debian install-info
1439 (bug reported by Aaron Falk @file{falk@@isi.edu}).
1441 Automatic date completion in new days is now done in the current
1442 locale, so it should now work for non-English languages. Bug reported
1443 by Torsten Bronger @file{bronger@@physik.rwth-aachen.de}.
1445 Fixed a bug in mkindexcache, triggered by subjects with percent signs
1446 in them. Bug reported by Philip Austin @file{paustin@@eos.ubc.ca}.
1448 We're a bit more robust about subjects, I hope. Warnings should
1449 appear about embedded number signs, and leading spaces should be
1450 filtered. Bug reported by Philip Austin @file{paustin@@eos.ubc.ca}.
1452 Notes-mode now dervies from indented-text-mode rather than
1453 paragraph-indent-text mode. Unfortunatley this is not customizable
1454 because of limitations of define-derived-mode. Change suggested by
1455 Aaron Falk @file{falk@@isi.edu}.
1457 Provide better hints about how to get started after installation or
1458 running notes-mode in emacs for the first time.
1460 In notes init, the default path for dir was the full path, not the tilde
1461 version of the path. Now it defaults to using tidle for home
1462 directory. Bug reported by Mark Allman @file{allman@@icir.org}.
1464 Changed (26-May-06): version 1.25:
1466 fixed a bug in the release tar.gz file that had a additional copies
1469 Changed (30-Jun-08): version 1.26:
1471 Force unicode I/O in @file{mkindexcache} to fix highlighting mis-alignment
1472 when using emacs-21 with unicode subject lines.
1474 Changed mkprevnext and mkrawindex to optionally take the list of notes files
1475 to index from stdin rather than from the command line. Yes, I finally
1476 have 4093 notes files, overflowing the Unix command line buffer.
1478 Changes notes-mode.el to put path in quotes, allowing spaces to appear in home directory names (bug fix from Ulrich Herbst).
1480 Added a suggested features section.
1482 Changed ( 8-Aug-08): version 1.27:
1484 Change I/O in @file{mkindexcache} to use locale (the sadly correct thing)
1485 rather than forcing utf-8 (the Righteous Path).
1486 Bug report from Geoff Kuenning, a man with an older Unix environment than I.
1488 Changed (20-Jun-10): version 1.28:
1490 Changed a regular expression in @file{notes-index-mode.el} that was
1491 causing emacs-v23 (a pre-release version)
1492 to regular expression infinite recursion.
1494 Changed (2012-04-04): version 1.29
1496 (2011-08-23) Changed @code{run-hooks} to @code{run-mode-hooks}.
1497 Bug report from Geoff Kuenning.
1499 Changed some handling of PGP encryption to account for
1500 some apparent API changes.
1502 (2012-04-04) Fixed encyrption to handle encrypting empty notes at the end
1503 of buffers without going into an infinite loop.
1504 Clearly wrong code, but you have to ask this guy for why he tried:
1505 Bug report from Geoff Kuenning.
1508 @c ----------------------------------------------------------------------
1510 @node Suggested features, , Changes, History
1511 @comment node-name, next, previous, up
1512 @section Suggested features
1514 Features suggested by users but not yet implemented:
1516 21-Feb-08: (from Xavier Maillard): should support ``disconnected'' notes that
1517 are indexed but not date-based.
1519 21-Feb-08: (from John Heidemann): should switch all notes files to have an extension (maybe @file{.notes}).
1520 @c ----------------------------------------------------------------------
1522 @node Installation, Keystroke index, History, Top
1523 @comment node-name, next, previous, up
1524 @chapter Installation
1526 To install notes-mode,
1530 Unpack and extract the distribution
1531 (gunzip notes-mode-xxx.tar.gz; tar xvf notes-mode-xxx.tar; cd notes-mode-xxx).
1534 Run configure (./configure).
1537 Type ``make install''.
1540 (To control what's installed where, use --prefix=/where, or
1541 --with-lisp-dir=/where, --datadir=/where (for scripts),
1542 and --infodir=/where.)
1550 If you have problems with paths being incorrect, please be aware that
1551 you @emph{cannot} run notes directly out of where you untar it. The
1552 installation process customizes the programs for where things are on
1554 Make sure you move out of the directory where you untarred it
1558 The most recent distribution of notes-mode
1559 is always available via
1560 @file{http://www.isi.edu/~johnh/SOFTWARE/NOTES_MODE/}.
1563 @c ----------------------------------------------------------------------
1565 @node Keystroke index, Concept index, Installation, Top
1566 @comment node-name, next, previous, up
1567 @unnumbered Keystroke index
1569 This index lists notes-mode keystrokes.
1574 @node Concept index, , Keystroke index, Top
1575 @comment node-name, next, previous, up
1576 @unnumbered Concept index
1578 This index lists notes-mode concepts.
1588 @c Geoff, make ispell support texinfo mode!
1590 @c LocalWords: texinfo setfilename settitle iftex finalout ifinfo DIR vskip
1591 @c LocalWords: titlepage pt filll dir urls prev defun dfn Yahoo yahoo com Jun
1592 @c LocalWords: alta Trademarked Sunone Grep agrep Nadia emph HTML's notesrc
1593 @c LocalWords: altavista julienne kbd RTN pxref musaphobic mkall cron crontab
1594 @c LocalWords: usr lib rawindex xref cC url imenu Phill PGP Campbell's ftp gp
1595 @c LocalWords: cmu rfb pam keyring mknew Apr int strftime cindex kindex grep
1596 @c LocalWords: isi ashvin geoff printindex ky cp wearables mit mantis co uk
1597 @c LocalWords: pgp html setchapternewpage XXX elisp cY cy cd RET Weisman cn
1598 @c LocalWords: reimplementation mode's Hyperbole's notesinit weisman app osf
1599 @c LocalWords: org ner Bastek jason aai Jul Ashvin's localhost catsubject Aug
1600 @c LocalWords: Autoconf Fontification perl mailcrypt LoPresti Choi's cag lcs
1601 @c LocalWords: Ramesh govindan xemacs tkld quadstone Ueda kueda jupiter qse
1602 @c LocalWords: tohoku ac jp Nov timp jna au mapcar gunzip xxx gz xvf xxx xxx
1603 @c LocalWords: datadir infodir untar