note/0x49/contents/usage

                        <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!