note 1.1.1 by Thomas Linden, 20/08/2000
=======================================

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

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

	There are currently three 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!
		o NOTEDB::dbm - this module uses two DBM files
		  for data storage and requires the module DB_FILE,
		  which is part of the perl standard distribution.
		  See below for more details about the DBM module.



Where to get?
=============

	By now at 
		http://www.daemon.de/software.html 
	or
		ftp://www.0c49.org/pub/scip/note/
	
	You may also try your nearest tucows mirror.




Features
========

	o Three different database backends, mysql(DBI), dbm, binary(bin file).
	o Commandline interface using the standard perl module
	  Getopt::Long, which allows you to use short or long
	  command-line options.
	o Interactive interface(pure ascii), the following functions
	  are available in interactive mode: list, display, topic,
	  delete, edit, help.
	o Highly confiurable using a perlish configfile ~/.noterc.
	  although it is configurable it is not required, note can
	  run without a configfile using useful default presets.
	o Colourized output is supported using ASCII Escape-Sequences.
	o The user can customize the color for each item.
	o Data can be stored in various different database backends,
	  since all database access is excluded from the program itself
	  in perl modules.
	o Notes can be deleted, edited and you can search trough your notes.
	o Notes can be categorized. Each category(topic) can contain multiple
	  notes and even more sup-topics. There is no limitation about
	  sub topics.
	o You can view all notes in a list and it is possible only to view
	  notes under a certain topic.
	o There is a tree-view, which allows you to get an overview of your
	  topic-hierarchy.
	o Notes can be encrypted using DES or IDEA algorythms and Crypt::CBC.
	o You can dump the contents of your note database into a plain text
	  file, which can later be imported. Imports can be appended or it can
	  overwrite an existing database (-o).
	o Note has scripting capabilities, you can create a new note by piping
	  another commands output to note, you can also import a notedump from
	  stdin as well es duming to stdout instead a file. Additional, there 
	  is an option --raw available, which prints everything out completely
	  without formatting.
	o for better performance, note can cache the database for listings
	  or searching.
	o It can be installed without root-privileges.
	o Last, a while ago a user stated: "... it simply does, what it
	  says ..."





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 if
		  you want to use the binary database backend.
		o DBI module and DBI::mysql if you want to use the 
		  mysql database backend.
		o The module DB_FILE if you want to use the DBM module.
		o Getopt::Long (part of perl std ditribution)



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

	Unpack the tar-ball and issue the command:
	$ perl Makefile.PL
	It will ask you a few questions about file destinations.
	The script will find itself the proper destinations for
	the files. So, if you agree with it, simply press ENTER.
	However, you may decide to use other destinations. In this
	case, enter it, when asked. This maybe usefull, if you are
	installing it in your ome-directory and if you are not root! 

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

	If want to use another SQL database, i.e. postgresql then set
	the option "DbDriver" to the name of the responding DBI-driver
	and create a symlink of this name like this:
	/usr/lib/perl5/siteperl/NOTEDB $ ln -s mysql.pm oracle.pm
	The functionality is the same, but not the name!

	The default binary file backend does not need any special installation
	procedure, you need only to spceify a filename in your config file.

	The DBM backend(NOTEDB::dbm) requires the existence of a directory,
	which you must specify in your config using the option "DbName".



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 if you are using
	the binary backend, otherwise there is no limitation).
	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 see the timestamps, use "-L" instead of "-l". 
	Read more about topics below in the section "Topics".
	You can also specify the topic which notes you want to see:
	"-l mytopic" does the trick.
	Additional, you might want to get an overview of your topic-
	structure. You can use the command "-t" in this case, which
	will display a tree-view of your topic-structure. You can
	use the command "-T" if you want to see the notes under each
	topic too. "-T" will also show the number of each note.

	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.
	You can extend the searchstring using B<AND>, B<OR> ( and ) and
	shell-like wildcards:

	$ note -s "moses AND lenin"

	or:

	$ note -s "(mike OR ar??ld) AND (jackson OR schwarzen*)"

	If note finds a note, which first line is a topic, then it will
	display it's second line.
	If you want to search for ? or * then you have to surround the
	searchstring with apostrophs ("").
	These rules apply for the interactive search too.

	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.
	Using dumps it is also possible to reinitialize your database. You
	can use the "-o" switch which causes note to overwrite your existing 
	database. This is very handy if you changed heavily your config. And 
	it is required, if you changed: encryption, db-driver, (binary-format)
	and the password. You can use the following command for reinitializing:
		$ note -D - | note -o -I -
	What the hell, does it?! Step by step:
		o "note -D -" creates a note-database dump and prints it out
		  to stantdard output.
		o "|" this is the shell's pipe command. It takes the output
		  of the left program and gives it to the right program as
		  standard input.
		o "note -o -I -" imports a note-database dump from standard
		  input and overwrites an existing database.
	Before you use the "-o" switch, I consider yuo to make a backup!




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 "TopicSeparator" 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 use some enhanced capabilities of the cd command. If you turn on
	the "ShortCd" parameter in your configuration, then you can cd to a
	note number (and thus - to it's topic) i.e. "cd 13" jumps to the topic
	of the note number 13. You can always go one level up using the "cd .."
	command and you can go to the top-level topic using "cd /".
	
	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
	TopicSeparator) 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!




Formatting of notes
===================

	Another very nice feature is the possibility to format the note-text
	(as much as shell allows it). First, you can use the note-internal
	"magic-strings" for colorizing. Those strings looks much like HTML:
		"<green>here is a green line of text</green> no more green."
	As you see, the beginning of another color starts with a tag(kinda) of
	the color <colorname> and ends with an end tag </colorname>.

	The following colors are available:
		black, red, green, yellow, blue, magenta, cyan and white.

	Beside colorizing text, you can also create bold or underlined text! If
	you decide to use this (additional) feature, you need to set the
	Config-Option "FormatNotes" to 1 which turns it on.
	Usage is very straightforward, if a word (a word is defined as some
	text with at least one space surrounded) is between a magic mark-
	character. Here are the available things, you can do:

		bold:	     	**word**
		underlined:	__word__
		inverse:	{{word}}

	The text will be formatted using the actually note-color.




Cache
=====

	If you have many notes stored in your database then you might
	find the cache feature useful. Chaching is currently supported
	by the binary and the mysql backend. Set the configuration
	parameter "Cache" to "1" or "yes" to turn caching on.
	Note will then use an internal copy of your notes-database for
	the list/search/tree commands instead of every time accessing
	the physically database. If something changed (i.e. you edited
	a note or added a new one) then the database will be used and
	the cache will be updated.
	A "%" character at the top left of the screen indicates that
	the cache is in use.
	I consider you not to use the cache feature if you are using
	multiple instances of note using the same database.
	The cache is turned off by default. 






Scripting
=========

	Since version 1.0.3 there are some additions which allows you to use
	note in scripts, without user-interaction. You might run a special
	script as cronjob, which adds a note under a certain topic every week.
	Or the like.

	Here are the possibilies you have:
	
	You can add a new note through a pipe, another commands output becomes
	note's input:
		$ cat /var/spool/news/daily | note -
	This command adds the content of a file "daily" as a new note. Note
	the dash - it stands for "Standard Input". Note will be completely
	silent and it will not ask for something.

	Suppose you are using encryption. You might wonder, how note will get
	your passphrase? The solution: You need to set up an environment
	variable which contains the password:
		$ export NOTE_PASSWD=secret
	If the variable is present, note will not ask you for a passphrase! 
		
	Another thingy you might find useful is the -r (--raw) command-line
	flag. This turns note into raw mode , which means it will only print the
	data without any formatting. Raw mode is available for list and display,
	since it makes no sense, interactive mode doe not support raw mode.


	


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

	The database where the notes are stored is a binary fixed record length
	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
========

	If you are using the MySQL driver, 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 are using notes proprietary binary driver, then
	the permission 0600 of the file "~/.notedb" is strongly required!

	Additional, you can turn on encryption from the config file.
	Simply set UseEncryption to 1. Please note, that you need
	to decide, if you want to use encryption before the first use
	of note! If have already a note database and want to "migrate"	
	to encryption, I suggest you to follow the directions in the 
	file UPGRADE!

	You can choose from different encryption algorythms. The default
	is IDEA, but DES or BLOWFISH is also possible. You need to have
	installed the following additional perl-modules on your system:
		MD5
		Crypt::IDEA
		Crypt::DES
		Crypt::CBC

	After turning on encryption, note will ask you for a passphrase
	everytime it runs! It will *not* store this passphrase!
	So, don't forget it! Be careful!

	If you are using the mysql backend and if your mysql database
	requires a password then you can store an encrypted version of
	your mysql password instead of the cleartext one.
	You need to turn on the config-parameter "encrypt_passwd" (set it
	to 1). Then you need to create an encrypted string from your
	mysql-password using note's commandline option --encrypt <string>.
	Note will ask you for a passphrase which will be used to encrypt
	the mysql-password. This passphrase must be exactly the same as
	you use for mysql itself. That means you need to use encryption.
	The string you get from this command must be saved in your config
	file as attribute to "DbPasswd". Later on note will decrypt that
	string using the supplied note-passphrase (that's why it must be
	the same used for encrypt) and pass the result to the mysql server.
	
	Once note have encrypted some data using this passphrase, you 
	cannot simply switch to another passphrase, because all data
	within the database needs to be encrypted using the same passphrase!
	If you want to change the passphrase for any reason, please read
	the file UPGRADE and follow it's directions!
	Someday I will add a "change passwd" function, which will do all
	these things for you. Someday, I said...
	For now you can use the "re-initialze database" functionality, mentioned
	earlier in the "Usage" section (at the end of the section).
	
	Note: To make sure, the encrypted data can be stored properly,
	      it will be uuencoded after encryption.
	
	Note: *If* you forgot your passphrase and *if* you don't have
	      a backup of your database without encryption, PLEASE
	      don't bother me with "helpme" emails! If you don't know
	      the phrase, then the data can't be decrypted. Even if it
	      is possible - I am not responsible for that!
	
	Note: How does note know, if the passphrase was incorrect? It uses the
	      specified phrase and encodes at least one note (the first one)
	      and checks if the decrypted timestamp field matches the following
	      expression: "^\d+\.\d+". Translated from perl to human:
	      the timestamp must begin with minimum one digit (possibly more),
	      followed by one dot, followed by minimum one digit (possibly
	      more).
	      Chances are bad, that a wrong passphrase will cause a timestamp
	      matching the rule above. If you have other experiences, please
	      drop me a mail!

	For the paranoid: do not use the cache-feature, 'cause note stores a
	copy of your note database in RAM if cache support is turned on.
	This means an attacker could access your (unencrypted!) notes. 


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





Recources
=========

	The command-line options and all commands of the interactive mode are
	described in the supplied note(1) manpage.
	You may also refer to the note website http://www.0x49.org.




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

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




Contributors / Credits
======================

	Shouts to those guys who helped me to enhance note: THANKS A LOT!

	Jens Heunemann <jens.heunemann@consol.de>	- sub tree.
	Peter Palmreuther				- various additions.
	
	And many other people who sent bug reports, feature requests. If you
	feel that I forgot your name in this list, then please send me an email
	and I'll add you.



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

	20/08/2000