note/note.1

.\" Automatically generated by Pod::Man version 1.02
.\" Sat Aug 19 15:59:14 2000
.\"
.\" Standard preamble:
.\" ======================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R

.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used
.\" to do unbreakable dashes and therefore won't be available.  \*(C` and
.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` `
.    ds C' '
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr
.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
.\" index entries marked with X<> in POD.  Of course, you'll have to process
.\" the output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
.    .
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it
.\" makes way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.bd B 3
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ======================================================================
.\"
.IX Title "NOTE 1"
.TH note 1 "note version 1.1.1" "20/Aug/2000" "Documentation"
.UC
.SH "NAME"
note \- a perl script for maintaining notes.
.SH "SYNPOPSIS"
.IX Header "SYNPOPSIS"
note [options] [ number [,number...]]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBnote\fR is a small console program written in perl, which allows 
you to manage notes similar to programs like \*(L"knotes\*(R" but from 
the commandline. Note can use different database-backends for 
notes-storage. It ships with a DBI-based mysql-module(which 
can also be used for other by \s-1DBI\s0 supported \s-1DBMS\s0), another 
module, which uses a binary file for storage and a \s-1DBM\s0 module.
Note supports since version 1.0.0 encryption(\s-1IDEA\s0 or \s-1DES\s0)!
.SH "OPTIONS"
.IX Header "OPTIONS"
.Ip "\fI\-c, \-\-config file\fR" 4
.IX Item "-c, --config file"
Use another config file than the default ~/.noterc.
.Ip "\fI\-l, \-\-list [topic]\fR" 4
.IX Item "-l, --list [topic]"
Lists all existing notes. If no topic were specified,
it will display a list of all existing topics.
See the section \fI\s-1TOPICS\s0\fR for details about topics.
.Ip "\fI\-L, \-\-longlist [topic]\fR" 4
.IX Item "-L, --longlist [topic]"
The same as \fI\-l\fR but prints also the timestamp of the notes.
.Ip "\fI\-t, \-\-topic\fR" 4
.IX Item "-t, --topic"
Prints a list of all topics as a tree.
.Ip "\fI\-T, \-\-longtopic\fR" 4
.IX Item "-T, --longtopic"
Prints the topic-tree with the notes under each topic.
.Ip "\fI\-s, \-\-search string\fR" 4
.IX Item "-s, --search string"
Searches for <string> trough the notes database. See the section
\&\fI\s-1SEARCHING\s0\fR for details about the search engine.
.Ip "\fI\-e, \-\-edit number\fR" 4
.IX Item "-e, --edit number"
Edit the note with the number <number> using your default editor
or the one you specified in the config file.
.Ip "\fI\-d, \-\-delete number\fR" 4
.IX Item "-d, --delete number"
Delete the note with the number <number>. You can delete multiple notes
with one command. \*(L"1\-4\*(R" deletes the notes 1,2,3,4. And \*(L"1,5,7\*(R" deletes
the specified ones.
.Ip "\fI\-D, \-\-Dump [file | \-]\fR" 4
.IX Item "-D, --Dump [file | -]"
Dumps all notes to the textfile <file>. If <file> is a \*(L"\-\*(R" it will 
be printed out to standard output (\s-1STDOUT\s0).
.Ip "\fI\-I, \-\-Import file | -\fR" 4
.IX Item "-I, --Import file | -"
Imports a previously dumped textfile into the
note database. Data will be appended by default.
You can also specify a dash \fInote \-I -\fR instead of a <file>,
which causes note, silently to read in a dump from \s-1STDIN\s0.
.Ip "\fI\-o, \-\-overwrite\fR" 4
.IX Item "-o, --overwrite"
Only suitable for use with \-\-Import. Overwrites an 
existing notedb. Use with care.
.Ip "\fI\-r, \-\-raw\fR" 4
.IX Item "-r, --raw"
Raw mode, output will not be formatted. Works not in interactive
mode, only on cmd-line for list and display. That means, no colors
will be used and no lines or titles.
.Ip "\fI\-i, \-\-interactive\fR" 4
.IX Item "-i, --interactive"
Start note in interactive mode. See the section \fI\s-1INTERACTIVE\s0 \s-1MODE\s0\fR
for details on this mode.
.Ip "\fI\*(--encrypt cleartext\fR" 4
.IX Item "encrypt cleartext"
Encrypt the given clear text string. You would need that if you want to
store the mysql password not in cleartext in the config(if you are using
the mysql backend!).
.Ip "\fI\-h, \-\-help\fR" 4
.IX Item "-h, --help"
Display this help screen.
.Ip "\fI\-v, \-\-version\fR" 4
.IX Item "-v, --version"
Display the version number.
.Ip "\fB-\fR" 4
.IX Item "-"
If you run note just with one dash: \fBnote -\fR, then it will read in a new
note from \s-1STDIN\s0 until \s-1EOF\s0. This makes it possible to pipe text into a new note, i.e.:
.Sp
.Vb 1
\& cat sometextfile | note -
.Ve
.SH "USAGE"
.IX Header "USAGE"
.Sh "\s-1GENERAL\s0 \s-1USAGE\s0"
.IX Subsection "GENERAL USAGE"
If you don't know, how to run note, try \*(L"note \-h\*(R" first.
It will tell you all available commandline options.
.PP
To create a new note, simply run \*(L"note\*(R". 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.
.PP
If you want to view the note, type \*(L"note 1\*(R", if the notenumber
was 1.
.PP
If you want to get an overview of all notes, type \*(L"note \-l\*(R".
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"\-L\*(R" instead of \*(L"\-l\*(R".
Read more about topics below in the section \*(L"Topics\*(R".
You can also specify the topic which notes you want to see:
\&\*(L"\-l mytopic\*(R" does the trick.
Additional, you might want to get an overview of your topic-
structure. You can use the command \*(L"\-t\*(R" in this case, which
will display a tree-view of your topic-structure. You can
use the command \*(L"\-T\*(R" if you want to see the notes under each
topic too. \*(L"\-T\*(R" will also show the number of each note.
.PP
To edit a certain note, type \*(L"note \-e 1\*(R". It will invoke your
editor (vi or pico). You can edit it, after saving, note
will store the changed note to the database.
.PP
Of course you can drop a certain note: \*(L"note \-d 1\*(R" 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 \*(L"\-d 1,2\*(R"
To delete note 1,2 and 3, use \*(L"\-d 1\-3\*(R".
.Sh "\s-1SEARCHING\s0"
.IX Subsection "SEARCHING"
If you cannot remember, which note you are looking for, you
can use the search capability of note: \*(L"note \-s <searchstring>\*(R".
note will search the whole note database case insensitive for
an occurence of this string and tell you the number and first-
line it has.
.PP
You can extend the searchstring using \fB\s-1AND\s0\fR, \fB\s-1OR\s0\fR ( and ) and
shell-like wildcards:
.PP
.Vb 1
\& $ note -s "moses AND lenin"
.Ve
or:
.PP
.Vb 1
\& $ note -s "(mike OR arnold) AND (jackson OR schwarzenegger)"
.Ve
If note finds a note, which first line is a topic, then it will
display it's second line.
.PP
These rules apply for the interactive search too.
.PP
You need to know, that note searches for the expression in every
note. In other words, \*(L"moses \s-1AND\s0 lenin\*(R" searches for an occurence
of \*(L"moses\*(R" and \*(L"lenin\*(R" in \s-1ONE\s0 note. Or, if you are looking for
\&\*(L"mike \s-1OR\s0 daniel\*(R", then it searches for an occurence of \*(L"mike\*(R" or
daniel\*(L" in \s-1ONE\s0 note. Thus a note with the text \*(R"mike oldfield" will
match that search.
.Sh "\s-1TOPICS\s0"
.IX Subsection "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 \*(L"TopicSeparator\*(R" in your config! default
is slash), then note will consider it as the topic of this certain
note. For examle:
.PP
.Vb 1
\& B</TodoList/>
.Ve
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.
.PP
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 \*(L"/topicname/\*(R" to the text of your
note).
.PP
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.
.PP
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:
.PP
.Vb 10
\& (root - top level)
\& |
\& |----test
\& |      |----subtopic
\& |      |       |--note 1
\& |      |       |--note 2
\& |      |
\& |      |--note 4
\& |
\& |--note 3
.Ve
Then you may create those 4 new notes:
.PP
.Vb 12
\& --- snip ---
\& /test/subtopic/
\& note 1
\& --- snip ---
\& /test/subtopic/
\& note 2
\& --- snip ---
\& note 3
\& --- snip ---
\& /test/
\& note 4
\& --- snip ---
.Ve
I hope, you got the point ;\-)
.PP
If a note does not contain the \*(L"magic\*(R" /topic/ construction on the first
line, it will be listed under the \*(L"root\*(R" of note, that is the point
you are at the startup of note.
.PP
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.
.PP
Note: Please don't forget the prepending and appending a slash of a
topic.  You will get strange results without it!
.Sh "\s-1INTERACTIVE\s0 \s-1MODE\s0"
.IX Subsection "INTERACTIVE MODE"
If you start note with the commandline flag \fB\-i\fR, then it starts
with an interactive interface.
It will start with a listing under the default top-topic (\*(L"/\*(R").
You can enter the name of a topic to change to that topic. This works
similar to a filesystem structure. The current topic will be 
displayed on the top of the screen.
.PP
The following commands are available:
.Ip "\fBL [topic]\fR" 4
.IX Item "L [topic]"
This command lists all notes with a timestamp. If you specify a topic, it
will only list the notes under this topic. If you are under a certain subtopic,
then it will only display the notes under this topic.
.Ip "\fBl [topic]\fR" 4
.IX Item "l [topic]"
This commands behaves similar to \fBL\fR but it does not display the timestamp.
You can achieve the same result by simply pressing enter at any time.
.Ip "\fBN\fR" 4
.IX Item "N"
You can create a new note by simply pressing \fBN\fR or \fBn\fR. You favorite
editor will be started and you can enter your note text. If you are already
under a topic then this new note will automatically go to this topic.
note adds an aditional line to the top of the note with the topic. But
you can of course specify your own topic.
.Sp
Note will tell you which number it has assigned to the newly created note.
.Ip "\fBE number\fR" 4
.IX Item "E number"
By entering \fBE\fR or \fBe\fR and a note-number you can edit an existing note
using your favorite editor. This way you can also move an existing note
from one topic to another one by editing the first line of the note.
.Ip "\fBD number\fR" 4
.IX Item "D number"
\&\fBE\fR or \fBe\fR deletes one or more existing \fInote\fR\|(s). It requires a note number
or a set of note numbers. 1\-5 and 1,7,9 are possible values.
After one or more notes has been deleted note will recount all remaining notes.
Say if you delete 1 and 2, then 3 will become 1, 4 will become 5 and so forth.
.Ip "\fBS [expression]\fR" 4
.IX Item "S [expression]"
You can search for the occurence of a text in your notes-database with the
command \fBS\fR or \fBs\fR. If you omit an expression note will ask you for one.
.Ip "\fBT\fR" 4
.IX Item "T"
This prints a tree-view of your topic-structure. \fBT\fR displays the tree with
notes, \fBt\fR displays just the topics without notes.
.Ip "\fBcd topic\fR" 4
.IX Item "cd topic"
Change the actual topic under which you are. This works identical like just
entering the topic but it has some advantages. You can enter \fBcd ..\fR if
you want to go one level up in the topic-structure. And you can enter \fBcd /\fR
to go to the top of the structure.
Additional it is possible to enter a note-number instead of a topic name.
For this feature to be active you need to set the config option \fBShortCd\fR
to \fB1\fR or \fByes\fR. If you use a number and the note with this number is
under a certain topic then you will \*(L"cd\*(R" to this topic. This allows you
to do kind of jumps over multiple levels of topics.
.Ip "\fB? or h\fR" 4
.IX Item "? or h"
Display a short help screen.
.Ip "\fBQ\fR" 4
.IX Item "Q"
Quit note.
.Sh "\s-1BACKUP\s0"
.IX Subsection "BACKUP"
You can also dump the contents of your note-database into a
ASCII-textfile(\fI\-D\fR). 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).
.PP
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 \*(L"\-o\*(R" switch whcih 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:
.PP
.Vb 1
\& $ note -D - | note -o -I -
.Ve
What the hell, does this do?! Step by step:
.Ip "\(bu" 4
\&\fBnote \-D -\fR creates a note-database dump and prints it out
to stantdard output.
.Ip "\(bu" 4
\&\fB|\fR 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.
.Ip "\(bu" 4
\&\fBnote \-o \-I -\fR imports a note-database dump from standard
input and overwrites an existing database.
.PP
Before you use the \fB\-o\fR switch, I consider you to make a backup!
.Sh "\s-1FORMATING\s0"
.IX Subsection "FORMATING"
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
\&\*(L"magic-strings\*(R" for colorizing. Those strings looks much like \s-1HTML:\s0
\&\*(L"<green>here is a green line of text</green> no more green.\*(R"
As you see, the beginning of another color starts with a tag(kinda) of
the color <colorname> and ends with an end tag </colorname>.
.PP
The following colors are available:
black, red, green, yellow, blue, magenta, cyan and white.
.PP
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 \*(L"FormatNotes\*(R" 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:
.PP
.Vb 3
\& bold:     **word**
\& underlined:__word__
\& inverse:{{word}}
.Ve
The text will be formatted using the actually note-color.
.SH "ENCRYPTION"
.IX Header "ENCRYPTION"
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 \*(L"migrate\*(R"
to encryption, I suggest you to follow the directions in the
file \s-1UPGRADE\s0!
.PP
You can choose from different encryption algorythms. The default
is \s-1IDEA\s0, but \s-1DES\s0 or \s-1BLOWFISH\s0 is also possible. You need to have
installed the following additional perl-modules on your system:
\&\s-1MD5\s0
Crypt::IDEA
Crypt::DES
Crypt::CBC
.PP
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!
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
You can use a configuration file with note but it is not required.
Note will use default values if there is no config.
.PP
The default config file is \fB~/.noterc\fR. You may specify another
one with the commandline flag \fI\*(--config\fR.
.PP
Comments start with #, empty lines will be ignored.
1 turns an option on, 0 turns it off.
An option consists of an atribute-value pair separated
by minimum one space (more spaces and/or tabs are allowed).
.PP
For a detailed explanation of each possible parameter take a look
at the supplied sample configuration file in \fBconfig/noterc\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
See the usage guide in the \s-1README\s0 or visit the note website:
http://www.0x49.org.
.SH "AUTHOR"
.IX Header "AUTHOR"
Thomas Linden <tom@daemon.de>