\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: next: 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, ) started, documented, and currently maintain notes-mode. I take ultimate responsibility for the code, especially for the ugly parts that I won't let others change. Ashvin Goel has been a very enthusiastic notes-mode user and contributor. He is responsible for at least the ideas behind @code{notes-summarize-subject} and the ideas and initial implementations of some of the original generalization and modularity improvements, @code{notes-follow-next-link} and @code{notes-follow-prev-link}, @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 has been another enthusiastic notes-mode user and victim. He is responsible for finding several bugs, motivation for mouse-less operation, comments about the documentation, the day-of-week convention, and an initial implementation and the idea of multiple entries with the same subjects in a single notes-file. Ramesh Govindan did the xemacs port. Since it's release on Usenet in April 1996 several other folks have contributed. Thanks to David Weisman , Martin L. Smith , Jason Bastek , Ulrich Herbst . See the next section (@xref{Changes}.) for details of their exploits. Thanks to Larry Ayers for popularizing notes-mode with reviews in the Linux Gazette (at and ). @node Changes, Suggested features, Credits, History @comment node-name, next, previous, up @section Changes For the bored: First semi-public release. 12-Jul-95: version 0.1 Shared a version with Ashvin and Geoff. Changed 6-Dec-95: version 0.3 Ashvin's changes for note traversal added (C-c C-p and C-c C-n now move to the prev/next note in note-mode). URL parsing changed so that "localhost" is optional. Changed 19-Dec-95: version 0.4 More robust prev/next code added, both to handle going back and forward in the middle of chains through the index file, and to handle back/forward in a single file. URL parsing changed so that notes-goto-index-entry correctly handles lookups on notes names such as "252A". Changed 20-Dec-95: version 0.5. Fixed a missing variable in notes-url.el. Added a work-around to a bug in emacs-19.30's define-derived-mode. Changed 24-Dec-95: version 0.6. Prev/next code re-re-written to be more robust. Changed 26-Dec-96: version 0.7. Bug fix release. Changed 23-Jan-96: version 0.8. Initialization code added to set up a new note. New variable: notes-bin-dir. I'm skipping version 0.9 because I erroneously release version 0.1 as version 0.9 (only on the web, not on Usenet). I'm bumping from version "0" to version "1" since the code is has been in production use for more than a year by several people. Minor numbers are the same. Changed 26-Mar-96: version 1.10. Setup code completely re-written. Several incompatible changes have been made: - the lisp and Perl code must be installed via make install, not by copying. - some data is specified in a .notesrc file; copy and modify sample.notesrc. - several internal elisp changes. - catsubject added (bound to C-cC-s): collect all notes about the current subject. - new notes-files are initialized with fields based on the prior day's notes; see mknew for details. - daily_work is gone; mkall is rewritten to use .notesrc. Changed 29-Apr-96: version 1.11. Real documentation. Mknew caching added. Changed 9-Aug-96: version 1.12. Added notesinit to do all setup for new users. Changed 24-Aug-96: version 1.13. Minor documentation fixes. Changed 20-Dec-97: version 1.14. Autoconf support. Fontification of the index buffer is now pre-computed in perl other than done when the file is needed (in elisp with slow regular expressions). 2000-line index files are now 1-2 seconds rather than 15-30 on a 100MHz Pentium. If necessary (the pre-computed version isn't up-to-date) we fall back on the slower code. Related work improved (suggestion by David Weisman ). Documentation improvement (problem found by Martin L. Smith ). Installation improved (code by Jason Bastek ). Bug in notes-index mode with subjects containing colons fixed (johnh). Encryption now supports mailcrypt.el. Support for emacs 20 (a small font-lock change). Changed 5-Jan-98: version 1.15. Bug in decryption for non-PAM users fixed (suggestion by Kevin Davidson ). Y2K statement added (suggestion by Kevin Davidson ). Pointer to mailcrypt added (as a supported encryption package). Problem pointed out by K. Ueda . Changed 4-Nov-98: version 1.16. Bug in kill-ring handling of notes-old-underline-line fixed by Tim Potter . Bug in whitespace handling after PGP encryption fixed by Tim Potter. Bugs in handling of entries with hash signs in their name fixed (found by Tim Potter). Fontification of index buffer further improved (mapcar is your friend). Xemacs support added based on code contributed by Ramesh Govindan. Changed 28-Feb-99: version 1.17: Improvement: notes-electric-return now fixes up the prev/next links of new entries (only). Code contributed by Takashi Nishimoto. Bug fix: reversed options -batch and -q in 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