note/README

note 0.8 by Thomas Linden, 19/03/2000


Introduction
============

	This is a small console program written in
	perl, which allows you to manage notes similar
	to programs like "knotes" from commandline.

	This version is completely rewritten and it is
	able to display colored output.

	You can add, edit, list and delete as many notes
	as you want. You can run note from the commandline
	or interactive from within your console. You can
	sort your notes in different topics, which is usefull
	if you have a lot of them.

	There are currently two different database backends,
	which you can use with note:
		o NOTEDB::binary - this is the default backend
		  and uses a binary file to store your notes.
		o NOTEDB::mysql  - this backend uses a mysql
		  database to store your notes. You can switch
		  easily to another DBMS since this module uses
		  the Perl standard module "DBI" for database-
		  access. See below for more info on this topic!


Requirements
============

	You need the following things:
		o perl installed (5.004x)
		o The module IO::Seekable and Fcntl, which should be 
		  already installed with your perl distributuion.
		o DBI module and DBI::mysql if you want to use the 
		  mysql version.



Installation
============

	There is a script provided called "install.sh", which will
	ask you a few questions about file destinations and database
	backends. Simply answer this questions and it does the rest.

	For installation instructions for the mysql database installation
	see mysql/README.



Configuration
=============

	This version of note doesn't neccessarily need
	a configuration file. But you can have one and change
	some default values. Take a look to the file config/noterc
	provided with this tarball. There are detailed instructions
	about every available parameter.
	Simply copy this file into your home-directory and name it
	.noterc
	If you decide not to use the default database backend (a binary
	file), you will *need* a configuration!



Usage
=====

	If you don't know, how to run note, try "note -h" first. 
	It will tell you all available commandline options.

	To create a new note, simply run "note". You can enter
	the note (the length is by default limited to 4096 bytes,
	which you can change from your config file).
	End by typing a . on a line itself. note will tell you the 
	number of the note.

	If you want to view the note, type "note 1", if the notenumber
	was 1. 

	If you want to get an overview of all notes, type "note -l".
	You will get a list of all notes, containing the number,
	the first line and the creation date. If topic-support is
	turned on (which is by default), then all subtopics under the 
	current topic will be displayed first.
	If you want to get a listing of all
	If you want to see the timestamps, use "-L" instead of "-l". 
	Read more about topics below in the section "Topics".

	To edit a certain note, type "note -e 1". It will invoke your
	editor (vi or pico). You can edit it, after saving, note
	will store the changed note to the database.

	Of course you can drop a certain note: "note -d 1" deletes
	note number 1. If a note in the middle or the beginning of
	the database will be deleted, note will recount the other
	existent notes. For example there are 3 notes, number 1, 2
	and 3. If you delete number 2, then number 3 will become
	number 2.
	You can also make use of the extended delete-syntax:
	To delete note 1 and 2, use "-d 1,2"
	To delete note 1,2 and 3, use "-d 1-3".

	If you cannot remember, which note you are looking for, you
	can use the search capability of note: "note -s <searchstring>".
	note will search the whole note database case insensitive for
	an occurence of this string and tell you the number and first-
	line it have.

	Instead of using note from the commandline you can use the
	interactive mode. Run note with "note -i". If you need assistance
	type "?" or "h" at the ">" prompt. The interactive mode
	provides you the most functions of note.

	You can also dump the contents of your note-database into a 
	ASCII-textfile(-D). You can use this file later to import it into
	your note-database(-I). This is usefull, if you want quickly trans-
	fer your notes from one host to another (i.e. you could mail
	your note-dump form your office to home and import it there
	for further use).
	The dumps from the two versions of note are in the same format.



Topics
======

	If topic-support is turned on (which is by default), the various 
	notes are sorted under various topics. There is no special database
	field for the topic. Instead the topic will be stored right in the
	note.
	If the first line of your note contains some text bordered by slashes
	(or whatever you prefer, set $TopicSep in your config! default is slash), 
	then note will consider it as the topic of this certain note. For examle:
	/TodoList/
	If you are using topics, no data after the topic is allowed, if there	
	is any text, note will consider it as a subtopic! Therefore, don't for-
	get to put a newline after the topic-line.
	
	If you are in interactive mode, you can "cd" to a different note simply
	by typing it's name at the command-prompt, or you can use the well-known
	syntax "cd topic". 
	The list-command will only show you notes under this topic. If you create
	a new note, it will automagically inserted under the current topic (note
	will prepend  the string "/topicname/" to the text of your note).
	
	You can create at any time from any point a new topic. Just create a new
	note and type the name of the new topic bordered by slashes (or $TopicSep)
	at the first line of this note. After saving, there will be available a
	new topic with one note in it.

	You can create as many subtopics as you like, the format is similar to a 
	filesystem-path. An example, say, you want to create such a structure:
	
	(root - top level)
	|
	|----test
	|      |----subtopic
	|      |       |--note 1
	|      |       |--note 2
	|      |
	|      |--note 4  
	|
	|--note 3
	
	Then you may create those 4 new notes:
	--- snip ---
	/test/subtopic/
	note 1
	--- snip ---
	/test/subtopic/
	note 2
	--- snip ---
	note 3
	--- snip ---
	/test/
	note 4
	--- snip ---		 
	
	I hope, you got the point ;-)
	   
	
	
	If a note does not contain the "magic" /topic/ construction on the first
	line, it will be listed under the "root" of note, that is the point you are 
	at the startup of note.

	You can subsequently move a note without a topic to a certain topic. Simply
	edit it and insert at the first line the above mentioned construction.

	Note: 	Please don't forget the prepending and appending a slash of a topic. 
		You will get strange results without it!



Format of the notedb (binary backend)
=====================================

	The database where the notes are stored is a binary file of
	the following format:
	It consists of three fixed length fields per entry. The fields
	have the following types:
		o Number: Integer (1 byte)
		o Note:   String (default 1024 bytes)
		o Time:   String (default 64 bytes)
	You can change the sizes of the fields "Note" and "Time" in
	the configfile "~/.noterc". If it does not exist, the above
	defaults will be used.
	If the data to be stored is smaller then the size of the field,
	it will be filled with ZERO's ("\0"). The Note and the Time
	fields will be uuencoded before storage. Of course, this is
	no security, never mind...



The note-database (mysql backend)
=================================
	
	The sql-database for the mysql version has the following design:
	+--------+---------+------+-----+---------+----------------+
	| Field  | Type    | Null | Key | Default | Extra          |
	+--------+---------+------+-----+---------+----------------+
	| number | int(10) |      | PRI | 0       | auto_increment |
	| note   | text    | YES  |     | NULL    |                |
	| date   | text    | YES  |     | NULL    |                |
	+--------+---------+------+-----+---------+----------------+



Format of the ASCII-dump file (note -D)
=======================================

	The dump of a note-database (if you use note -D) has the following
	format:
	
	--- snip ---
	Number: 1
	Timestamp: 14.01.2000 00:25:01
	This is a sample text
	in a sample note.

	Number: 2
	Timestamp: 14.01.2000 02:37:40
	And this is another sample
	of a note.
	--- snip ---
	
	You can reimport a dump into your note-database with "note -I <file>"
	Existing notes will not overwritten, note will append the imported
	data to your note-database.




Security
========

	You can't use the following hints with the mysql version!
	Refer to the mysql manual for more informations about
	security of mysql databases:
	http://www.mysql.org/Manual_chapter/manual_Privilege_system.html
	
	If you want to protect the notedb against unauthorized persons
	(even root), you might want to use pgp. I use gpg (GNU privacy
	guard), which is compatible to pgp, usage should be similar.
	You could add a function to your .profile or .bashrc or whatever:
	--- snip ---
		function note
		{
			gpg -o ~/.notedb -d ~/.notedb.gpg
			note $1 $2 $3
			gpg -e ~/.notedb --yes -r username
			rm -rf ~/.notedb
		}
	--- snip ---
	You should replace <username> with your real username. After applying
	this function to your .profile, issue the following command:
		"source .profile"
	You shell will reread the file, so you can try it out without the need
	of new login.
	This function assumes, there exists a file called "~/.notedb.gpg",
	therefore you need to encrypt your notedb once before you can use this
	funcion:
		"gpg -e ~/.notedb --yes -r username"

	Here is, how to do it with pgp, create a shell script with the following
	content:
	--- snip ---
		#!/bin/sh
		/bin/echo -n "passphrase:"
		pgp -o ~/.notedb -d ~/.notedb.pgp > /dev/null 2>&1
		rm -f ~/.notedb.pgp > /dev/null 2>&1
		note.pl $1 $2 $3
		pgp -e ~/.notedb tlinden > /dev/null 2>&1
		rm -f ~/.notedb > /dev/null 2>&1
	--- snip ---
	Do "chmod 700 whatevername". That's it.	

	If you don't make use of encryption, I suggest you to chmod it:
		"chmod 600 .notedb"
	So, only you can read the file (and root or any intruder who became root).	



Comments
========

	You can send any comments to Thomas Linden <tom@daemon.de>.
	If you find a bug or if you have a suggestion for improvement of the script
	feel free to send me a patch ;-)



License
=======

	This script comes with absolutely NO WARRANTY. It is distributed under the
	terms of the GNU General Public License. Use it at your own risk :-)
	You can read the complete GPL at: http://www.gnu.org/copyleft/gpl.html



Author and Copyright
====================

	The author is Thomas Linden.
	note is Copyright of Thomas Linden.




Last changed
============

	19/03/2000