mirror of
https://codeberg.org/scip/note.git
synced 2025-12-17 12:41:10 +01:00
9cf564ffe4
file, use perls open() instead.
CHANGED: excluded some of the help texts from the usage message and the
interactive help command to a manpage.
ADDED: new commandline flag "--encrypt" which one can use to encrypt
the mysql database password. This will be decrypted before
connecting to the db. There is also a new config file option
"encrypt_passwd" which indicates an encrypted db-password.
ADDED: another new config option "ShortCd", which can be set to "yes"
or 1 and if set, then a command like "cd 13" would jump
directly to the topic of the note with the number 13.
ADDED: now you can at any time cd back to the "root" of the
topic-structure using the command "cd /".
CHANGED: mysql.pm does now only do a table-lock on single write
accesses, no more on the whole session. This allows one to
access the same db twice or more.
FIXED: Changed README and Changelog for readability on 80 by 25
displays. And changed indentation of the note script itself.
ADDED: NOTEDB.pm - a generic module, which holds some methods, which
are used by binary.pm, mysql.pm and dbm.pm.
ADDED: NOTEDB.pm generate_search(), which allows one to
use AND, OR and various combinations of them using ( and ).
ADDED: a search does now return the 2nd line of a note if a matching
note's first line is a topic.
CHANGED: use "unshift" instead of push to add $libpath to @INC.
ADDED: a new feature, Caching of notes. supported by binary.pm and
mysql.pm. To turn it on, one need to set "Cache" in the config
to a true value.
351 lines
15 KiB
Plaintext
351 lines
15 KiB
Plaintext
<h2>usage of note</h2>
|
|
<p>
|
|
<a href="#desc">1. Description</a><p>
|
|
<a href="#topics">2. Topics</a><p>
|
|
<a href="#format">3. Formatting of note-text</a><p>
|
|
<a href="#script">4. Scripting</a><p>
|
|
<a href="#dbformat">5. Binary DB</a><p>
|
|
<a href="#sqlformat">6. Mysql DB</a><p>
|
|
<a href="#dumpformat">7. Dump Format</a><p>
|
|
<a href="#security">8. Security</a><p>
|
|
<hr>
|
|
<p>
|
|
<a name="#desc">
|
|
<h4>Decription</h4>
|
|
|
|
If you don't know, how to run note, try "note -h" first.
|
|
It will tell you all available commandline options.
|
|
<p>
|
|
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, therwise there is no limitation).
|
|
End by typing a . on a line itself. note will tell you the
|
|
number of the note.
|
|
<p>
|
|
If you want to view the note, type "note 1", if the notenumber
|
|
was 1.
|
|
<p>
|
|
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.
|
|
<br> 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".
|
|
You can also specify the topic which notes you want to see:
|
|
"-l mytopic" does the trick.
|
|
<br> Additional, you might want to get an overview of your topic-
|
|
strcture. You can use the command "-t" in this case, which
|
|
will display a tree-view of your tpic-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.
|
|
<p>
|
|
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.
|
|
<p>
|
|
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.
|
|
<br> 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".
|
|
<p>
|
|
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.
|
|
<p>
|
|
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.
|
|
<p>
|
|
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).
|
|
<br> 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 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:
|
|
<br> $ note -D - | note -o -I -
|
|
<br> What the hell, does it?! Step by step:
|
|
<ul>
|
|
<li> "note -D -" creates a note-database dump and prints it out
|
|
to stantdard output.
|
|
<li> "|" 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.
|
|
<li> "note -o -I -" imports a note-database dump from standard input
|
|
and overwrites an existing database.
|
|
</ul>
|
|
Before you use the "-o" switch, I consider yuo to make a backup!
|
|
|
|
<p>
|
|
|
|
<a href="#top">top</a><p><p><a name="topics">
|
|
<h4>Topics</h4>
|
|
|
|
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.
|
|
<br> 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:
|
|
<br> /TodoList/
|
|
<br> 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.
|
|
<p>
|
|
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".
|
|
<br> 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).
|
|
<p>
|
|
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.
|
|
<p>
|
|
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:
|
|
<p>
|
|
<pre>
|
|
(root - top level)
|
|
|
|
|
|----test
|
|
| |----subtopic
|
|
| | |--note 1
|
|
| | |--note 2
|
|
| |
|
|
| |--note 4
|
|
|
|
|
|--note 3
|
|
</pre>
|
|
<p>
|
|
Then you may create those 4 new notes:
|
|
<br>
|
|
<pre>
|
|
--- snip ---
|
|
/test/subtopic/
|
|
note 1
|
|
--- snip ---
|
|
/test/subtopic/
|
|
note 2
|
|
--- snip ---
|
|
note 3
|
|
--- snip ---
|
|
/test/
|
|
note 4
|
|
--- snip ---
|
|
</pre><br>
|
|
I hope, you got the point ;-)
|
|
<p>
|
|
|
|
|
|
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.
|
|
<p>
|
|
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.
|
|
<p>
|
|
Note: Please don't forget the prepending and appending a slash of a topic.
|
|
You will get strange results without it!
|
|
|
|
|
|
<p>
|
|
|
|
<a href="#top">top</a><p><p><a name="format">
|
|
<h4>Formatting of notes</h4>
|
|
|
|
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 color-
|
|
izing. Those strings looks much like HTML:
|
|
i<br> "<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 ens with an end tag </colorname>.
|
|
<p>
|
|
The following colors are available:
|
|
black, red, green, yellow, blue, magenta, cyan and white.
|
|
<p>
|
|
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.
|
|
<br> 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:
|
|
<pre>
|
|
bold: **word**
|
|
underlined: __word__
|
|
inverse: {{word}}
|
|
</pre>
|
|
The text will be formatted using the actually note-color.
|
|
<p>
|
|
|
|
|
|
<a href="#top">top</a><p><p><a name="script">
|
|
<h4>Scripting</h4>
|
|
|
|
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.
|
|
<p>
|
|
Here are the possibilies you have:
|
|
<p>
|
|
You can add a new note through a pipe, another commands output becomes
|
|
note's input:
|
|
<br> $ cat /var/spool/news/daily | note -
|
|
<br> 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.
|
|
<p>
|
|
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:
|
|
<br> $ export NOTE_PASSWD=secret
|
|
<br> If the variable is present, note will not ask you for a passphrase!
|
|
<p>
|
|
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.
|
|
<p>
|
|
|
|
|
|
|
|
<a href="#top">top</a><p><p><a name="dbformat">
|
|
<h4>Format of the notedb (binary backend)</h4>
|
|
|
|
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:
|
|
<ul>
|
|
<li> Number: Integer (1 byte)
|
|
<li> Note: String (default 1024 bytes)
|
|
<li> Time: String (default 64 bytes)
|
|
</ul>
|
|
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.
|
|
<br> 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...
|
|
|
|
<p>
|
|
|
|
<a href="#top">top</a><p><p><a name="sqlformat">
|
|
<h4>The note-database (mysql backend)</h4>
|
|
|
|
The sql-database for the mysql version has the following design:
|
|
<pre>
|
|
+--------+---------+------+-----+---------+----------------+
|
|
| Field | Type | Null | Key | Default | Extra |
|
|
+--------+---------+------+-----+---------+----------------+
|
|
| number | int(10) | | PRI | 0 | auto_increment |
|
|
| note | text | YES | | NULL | |
|
|
| date | text | YES | | NULL | |
|
|
+--------+---------+------+-----+---------+----------------+
|
|
</pre>
|
|
|
|
<p>
|
|
|
|
<a href="#top">top</a><p><p><a name="dumpformat">
|
|
<h4>Format of the ASCII-dump file (note -D)</h4>
|
|
|
|
The dump of a note-database (if you use note -D) has the following
|
|
format:
|
|
<pre>
|
|
--- 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 ---
|
|
</pre>
|
|
<p> 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.
|
|
<p>
|
|
|
|
|
|
<a href="#top">top</a><p><p><a name="security">
|
|
<h4>Security</h4>
|
|
|
|
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
|
|
<p>
|
|
If you are using notes proprietary binary driver, then
|
|
the permission 0600 of the file "~/.notedb" is strongly required!
|
|
<p>
|
|
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!
|
|
<p>
|
|
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:
|
|
<ul>
|
|
<li> MD5
|
|
<li> Crypt::IDEA
|
|
<li> Crypt::DES
|
|
<li> Crypt::CBC
|
|
</ul>
|
|
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!
|
|
<p>
|
|
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!
|
|
<br> 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).
|
|
<p>
|
|
Note: To make sure, the encrypted data can be stored properly,
|
|
it will be uuencoded after encryption.
|
|
<p>
|
|
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!
|
|
<p>
|
|
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!
|