1# -*-perl-*- 2 3=head1 NAME 4 5note - a perl script for maintaining notes. 6 7 8=head1 SYNPOPSIS 9 10note [options] [ number [,number...]] 11 12 13=head1 DESCRIPTION 14 15B<note> is a small console program written in perl, which allows 16you to manage notes similar to programs like "knotes" but from 17the commandline. Note can use different database-backends for 18notes-storage. It ships with a DBI-based mysql-module(which 19can also be used for other by DBI supported DBMS), another 20module, which uses a binary file for storage and a DBM module. 21There are also two modules available which uses a text file. 22Note supports since version 1.0.0 encryption(IDEA or DES)! 23 24 25=head1 OPTIONS 26 27 28=over 29 30=item I<-c, --config file> 31 32Use another config file than the default ~/.noterc. 33 34 35=item I<-l, --list [topic]> 36 37Lists all existing notes. If no topic were specified, 38it will display a list of all existing topics. 39See the section I<TOPICS> for details about topics. 40 41=item I<-L, --longlist [topic]> 42 43The same as I<-l> but prints also the timestamp of the notes. 44 45 46=item I<-t, --topic> 47 48Prints a list of all topics as a tree. 49 50 51=item I<-T, --longtopic> 52 53Prints the topic-tree with the notes under each topic. 54 55 56=item I<-s, --search string> 57 58Searches for <string> trough the notes database. See the section 59I<SEARCHING> for details about the search engine. 60 61 62=item I<-e, --edit number> 63 64Edit the note with the number <number> using your default editor 65or the one you specified in the config file. 66 67 68=item I<-d, --delete number> 69 70Delete the note with the number <number>. You can delete multiple notes 71with one command. "1-4" deletes the notes 1,2,3,4. And "1,5,7" deletes 72the specified ones. 73 74 75=item I<-D, --Dump [file | -]> 76 77Dumps all notes to the textfile <file>. If <file> is a "-" it will 78be printed out to standard output (STDOUT). 79 80 81=item I<-I, --Import file | -> 82 83Imports a previously dumped textfile into the 84note database. Data will be appended by default. 85You can also specify a dash I<note -I -> instead of a <file>, 86which causes note, silently to read in a dump from STDIN. 87 88 89=item I<-o, --overwrite> 90 91Only suitable for use with --Import. Overwrites an 92existing notedb. Use with care. 93 94 95=item I<-r, --raw> 96 97Raw mode, output will not be formatted. Works not in interactive 98mode, only on cmd-line for list and display. That means, no colors 99will be used and no lines or titles. 100 101 102=item I<-i, --interactive> 103 104Start note in interactive mode. See the section I<INTERACTIVE MODE> 105for details on this mode. 106 107 108=item I<--encrypt cleartext> 109 110Encrypt the given clear text string. You would need that if you want to 111store the mysql password not in cleartext in the config(if you are using 112the mysql backend!). 113 114 115=item I<-h, --help> 116 117Display this help screen. 118 119 120=item I<-v, --version> 121 122Display the version number. 123 124 125=item B<-> 126 127If you run note just with one dash: B<note ->, then it will read in a new 128note from STDIN until EOF. This makes it possible to pipe text into a new note, i.e.: 129 130 cat sometextfile | note - 131 132 133=back 134 135 136 137 138=head1 USAGE 139 140=head2 GENERAL USAGE 141 142If you don't know, how to run note, try "note -h" first. 143It will tell you all available commandline options. 144 145To create a new note, simply run "note". You can enter 146the note (the length is by default limited to 4096 bytes, 147which you can change from your config file if you are using 148the binary backend, otherwise there is no limitation). 149End by typing a . on a line itself. note will tell you the 150number of the note. 151 152If you want to view the note, type "note 1", if the notenumber 153was 1. 154 155If you want to get an overview of all notes, type "note -l". 156You will get a list of all notes, containing the number, 157the first line and the creation date. If topic-support is 158turned on (which is by default), then all subtopics under the 159current topic will be displayed first. 160If you want to see the timestamps, use "-L" instead of "-l". 161Read more about topics below in the section "Topics". 162You can also specify the topic which notes you want to see: 163"-l mytopic" does the trick. 164Additional, you might want to get an overview of your topic- 165structure. You can use the command "-t" in this case, which 166will display a tree-view of your topic-structure. You can 167use the command "-T" if you want to see the notes under each 168topic too. "-T" will also show the number of each note. 169 170To edit a certain note, type "note -e 1". It will invoke your 171editor (vi or pico). You can edit it, after saving, note 172will store the changed note to the database. 173 174Of course you can drop a certain note: "note -d 1" deletes 175note number 1. If a note in the middle or the beginning of 176the database will be deleted, note will recount the other 177existent notes. For example there are 3 notes, number 1, 2 178and 3. If you delete number 2, then number 3 will become 179number 2. 180You can also make use of the extended delete-syntax: 181To delete note 1 and 2, use "-d 1,2" 182To delete note 1,2 and 3, use "-d 1-3". 183 184 185 186=head2 SEARCHING 187 188If you cannot remember, which note you are looking for, you 189can use the search capability of note: "note -s <searchstring>". 190note will search the whole note database case insensitive for 191an occurence of this string and tell you the number and first- 192line it has. 193 194You can extend the searchstring using B<AND>, B<OR> ( and ) and 195shell-like wildcards: 196 197 $ note -s "moses AND lenin" 198 199or: 200 201 $ note -s "(mike OR arnold) AND (jackson OR schwarzenegger)" 202 203If note finds a note, which first line is a topic, then it will 204display it's second line. 205 206These rules apply for the interactive search too. 207 208You need to know, that note searches for the expression in every 209note. In other words, "moses AND lenin" searches for an occurence 210of "moses" and "lenin" in ONE note. Or, if you are looking for 211"mike OR daniel", then it searches for an occurence of "mike" or 212daniel" in ONE note. Thus a note with the text "mike oldfield" will 213match that search. 214 215 216=head2 TOPICS 217 218If topic-support is turned on (which is by default), the various 219notes are sorted under various topics. There is no special database 220field for the topic. Instead the topic will be stored right in the 221note. 222If the first line of your note contains some text bordered by slashes 223(or whatever you prefer, set "TopicSeparator" in your config! default 224is slash), then note will consider it as the topic of this certain 225note. For examle: 226 227 B</TodoList/> 228 229If you are using topics, no data after the topic is allowed, if there 230is any text, note will consider it as a subtopic! Therefore, don't for- 231get to put a newline after the topic-line. 232 233The list-command will only show you notes under this topic. If you 234create a new note, it will automagically inserted under the current 235topic (note will prepend the string "/topicname/" to the text of your 236note). 237 238You can create at any time from any point a new topic. Just create a new 239note and type the name of the new topic bordered by slashes (or 240TopicSeparator) at the first line of this note. After saving, there 241will be available a new topic with one note in it. 242 243You can create as many subtopics as you like, the format is similar to 244a filesystem-path. An example, say, you want to create such a 245structure: 246 247 (root - top level) 248 | 249 |----test 250 | |----subtopic 251 | | |--note 1 252 | | |--note 2 253 | | 254 | |--note 4 255 | 256 |--note 3 257 258Then you may create those 4 new notes: 259 260 --- snip --- 261 /test/subtopic/ 262 note 1 263 --- snip --- 264 /test/subtopic/ 265 note 2 266 --- snip --- 267 note 3 268 --- snip --- 269 /test/ 270 note 4 271 --- snip --- 272 273I hope, you got the point ;-) 274 275If a note does not contain the "magic" /topic/ construction on the first 276line, it will be listed under the "root" of note, that is the point 277you are at the startup of note. 278 279You can subsequently move a note without a topic to a certain topic. 280Simply edit it and insert at the first line the above mentioned 281construction. 282 283Note: Please don't forget the prepending and appending a slash of a 284topic. You will get strange results without it! 285 286 287 288 289=head2 INTERACTIVE MODE 290 291If you start note with the commandline flag B<-i>, then it starts 292with an interactive interface. 293It will start with a listing under the default top-topic ("/"). 294You can enter the name of a topic to change to that topic. This works 295similar to a filesystem structure. The current topic will be 296displayed on the top of the screen. 297 298The following commands are available: 299 300=over 301 302=item B<L [topic]> 303 304This command lists all notes with a timestamp. If you specify a topic, it 305will only list the notes under this topic. If you are under a certain subtopic, 306then it will only display the notes under this topic. 307 308=item B<l [topic]> 309 310This commands behaves similar to B<L> but it does not display the timestamp. 311You can achieve the same result by simply pressing enter at any time. 312 313 314=item B<N> 315 316You can create a new note by simply pressing B<N> or B<n>. You favorite 317editor will be started and you can enter your note text. If you are already 318under a topic then this new note will automatically go to this topic. 319note adds an aditional line to the top of the note with the topic. But 320you can of course specify your own topic. 321 322Note will tell you which number it has assigned to the newly created note. 323 324=item B<E number> 325 326By entering B<E> or B<e> and a note-number you can edit an existing note 327using your favorite editor. This way you can also move an existing note 328from one topic to another one by editing the first line of the note. 329 330 331=item B<D number> 332 333B<E> or B<e> deletes one or more existing note(s). It requires a note number 334or a set of note numbers. 1-5 and 1,7,9 are possible values. 335After one or more notes has been deleted note will recount all remaining notes. 336Say if you delete 1 and 2, then 3 will become 1, 4 will become 5 and so forth. 337 338 339=item B<S [expression]> 340 341You can search for the occurence of a text in your notes-database with the 342command B<S> or B<s>. If you omit an expression note will ask you for one. 343 344If your search criteria matches on exactly one entry, note will display 345that note entry instead of displaying its number. 346 347=item B<T> 348 349This prints a tree-view of your topic-structure. B<T> displays the tree with 350notes, B<t> displays just the topics without notes. 351 352=item B<C> 353 354It is possible to change note's behavior at runtime. Specify the parameter 355you'd like to modify followed by equalsign and the new value. Use with 356care! However, database related parameters cannot be changed at runtime. 357Entering just "c" without parameters displays the customizable variables. 358 359=item B<cd topic> 360 361Change the actual topic under which you are. This works identical like just 362entering the topic but it has some advantages. You can enter B<cd ..> if 363you want to go one level up in the topic-structure. And you can enter B<cd /> 364to go to the top of the structure. You can always leave out the 'cd' keyword too. 365 366Additional it is possible to enter a note-number instead of a topic name. 367For this feature to be active you need to set the config option B<ShortCd> 368to B<1> or B<yes>. If you use a number and the note with this number is 369under a certain topic then you will "cd" to this topic. This allows you 370to do kind of jumps over multiple levels of topics. 371 372If is possible to abbreviate a topic. This works only if the abbreviation 373matches on one single topic. If it matches more than one topic then the 374available ones will be suggested. 375 376 377=item B<? or h> 378 379Display a short help screen. 380 381 382=item B<Q> 383 384Quit note. 385 386=back 387 388 389 390 391 392=head2 BACKUP 393 394You can also dump the contents of your note-database into a 395ASCII-textfile(I<-D>). You can use this file later to import it into 396your note-database(-I). This is usefull, if you want quickly trans- 397fer your notes from one host to another (i.e. you could mail 398your note-dump form your office to home and import it there 399for further use). 400 401The dumps from the two versions of note are in the same format. 402Using dumps it is also possible to reinitialize your database. You 403can use the "-o" switch whcih causes note to overwrite your existing 404database. This is very handy if you changed heavily your config. And 405it is required, if you changed: encryption, db-driver, (binary-format) 406and the password. You can use the following command for reinitializing: 407 408 $ note -D - | note -o -I - 409 410What the hell, does this do?! Step by step: 411 412=over 413 414=item * 415 416B<note -D -> creates a note-database dump and prints it out 417to stantdard output. 418 419=item * 420 421B<|> this is the shell's pipe command. It takes the output 422of the left program and gives it to the right program as 423standard input. 424 425=item * 426 427B<note -o -I -> imports a note-database dump from standard 428input and overwrites an existing database. 429 430=back 431 432Before you use the B<-o> switch, I consider you to make a backup! 433 434=head3 BACKUP FILE FORMAT 435 436B<Caution>: since version 1.3.8 note uses a new file format 437for backups: YAML. The old format is only supported by the 438B<-I> option to import old backups. New backups are always 439created as YAML files. See L<YAML>. 440 441 442 443=head2 FORMATING 444 445Another very nice feature is the possibility to format the note-text 446(as much as shell allows it). First, you can use the note-internal 447"magic-strings" for colorizing. Those strings looks much like HTML: 448"<green>here is a green line of text</green> no more green." 449As you see, the beginning of another color starts with a tag(kinda) of 450the color <colorname> and ends with an end tag </colorname>. 451 452The following colors are available: 453black, red, green, yellow, blue, magenta, cyan and white. 454 455Beside colorizing text, you can also create bold or underlined text! If 456you decide to use this (additional) feature, you need to set the 457Config-Option "FormatText" to 1 which turns it on. 458Usage is very straightforward, if a word (a word is defined as some 459text with at least one space surrounded) is between a magic mark- 460character. Here are the available things, you can do: 461 462 bold: **word** 463 underlined: __word__ 464 inverse: {{word}} 465 hidden: //word// 466 467The text will be formatted using the actually note-color. 468 469The hidden formatting will use blue forground and blue background 470to hide a string from the terminal, which is usefull for passwords. 471 472If you set "FormatText" to I<simple> then the formatting can be 473done this way instead: 474 475 bold: *word* 476 underlined: _word_ 477 inverse: {word} 478 hidden: /word/ 479 480=head1 ENCRYPTION 481 482You can turn on encryption from the config file. 483Simply set UseEncryption to 1. Please note, that you need 484to decide, if you want to use encryption before the first use 485of note! If have already a note database and want to "migrate" 486to encryption, I suggest you to follow the directions in the 487file UPGRADE! 488 489You can choose from different encryption algorythms. The default 490is IDEA, but DES or BLOWFISH are also possible. You need to have 491installed the following additional perl-modules on your system: 492MD5 493Crypt::IDEA 494Crypt::DES 495Crypt::CBC 496 497After turning on encryption, note will ask you for a passphrase 498everytime it runs! It will *not* store this passphrase! 499So, don't forget it! Be careful! 500 501 502 503 504=head1 CONFIGURATION 505 506You can use a configuration file with note but it is not required. 507Note will use default values if there is no config. 508 509The default config file is B<~/.noterc>. You may specify another 510one with the commandline flag I<--config>. 511 512Comments start with #, empty lines will be ignored. 513 514To turn on an option, set it to: B<1>, B<on> or B<yes>. 515 516To turn off an option, set it to: B<0>, B<off> or B<no>. 517 518An option consists of an atribute-value pair separated 519by minimum one space (more spaces and/or tabs are allowed) 520and an optional equal sign in between. 521 522Variable names are case in-sensitive. 523 524For a detailed explanation of each possible parameter take a look 525at the supplied sample configuration file in B<config/noterc>. 526 527 528 529 530 531=head1 AUTHOR 532 533T.v.Dein <tlinden@cpan.org> 534 535=head1 VERSION 536 5371.3.20 538 539=cut 540