Cjots 0.85 Documentation
June 2006, Jesse Read
About
Cjots is a simple notetaker program. When you need to jot/paste something down
for future reference, or find something useful you wrote down a while ago
without messing around in load/save file dialogs or typing out long file paths
on the command line.
It works great for..
-Filing bits and peices for quick reference later, interesting shell commands, phone numbers, etc
-Temporary storage - for typing something out before pasting it somewhere else
-Copying and pasting text - when you need somewhere to put it and organize it
-A Diary - easy to insert the date and time in the name of a page or in the text itself
-A TODO list - easy to add and delete pages and move them around
-Drafting out a document - this document was made in a Cjots file and exported as HTML!
All of these things - one book for each!
Why?
I loved Kjots but use a very minimalistic Desktop, usually IceWM or Ratpoison,
and usually always find myself working out of a screen session. So I don't like
having a whole bunch of KDE stuff on my harddrive just to be able to use Kjots.
This is where the idea for Cjots comes in which has simmilar functionality,
compatible with my old Kjots notes, and can be started instantly for taking
notes, and auto-saves when you exit.
Contact
I would really like some feedback, even if its negative so I can continue
developing this program and adding new features. jesse read AT gmail.com
See the web page http://cjots.sourceforge.net/ for more information
The only requirements for Cjots are Perl 5 and Perl's Curses library.
Perl 5 can be found almost anywhere.
The Curses library can be downloaded from cpan.org
Debian users can probably apt-get install libcurses-ui-perl and I suspect there will be rpms out there for rpm systems.
1. Give cjots.pl permission to execute
chmod +x cjots.pl
2. Configure Cjots
If you are running Cjots for the first time, it should step you through the process of creating a .cjotsrc config file
However, if you have tried a previous version prior to 0.80, you will need to do one of the following:
delete the ~/.cjotsrc file and let Cjots write you a new one when you run it
OR
edit ~/.cjotsrc and add more lines, here is a sample configuration with ALL the necessary lines:
#The directory where the notebook files are kept, for eg $HOME/.notes or $HOME/.kde/share/apps/kjots
notesdir=/home/user/.notes
#Preferred date format, see 'date --help' on the linux command line for format specification
dateformat=%F
#Preferred time format, see 'date --help' on the linux command line for format specification
timeformat=%r
#Width of the table of contents pane (in characters)
toc=25
#Maximum height of the book list pane (in number of books shown without scrolling)
max_bookshelf_height=200;
#Where the plugin list file is located
plugin_file=/home/user/.cjots_plugins
3. Configure Plugins
Note that the 'plugin file=' variable in the .cjotsrc configuration file refers to the location of
the plugins file. The 'cjots_plugins_sample' file is an example file that comes with Cjots which you can use.
I suggest:
cp cjots_plugins_sample ~/.cjots_plugins
Then specify that location from the config file:
plugin_file=/home/username/.cjots_plugins
where username is .. well it should be obvious.
Look inside the plugins file or the Plugins section of this manufal for information about making your own plugins
4. Run
./cjots.pl
or put it in your $PATH so you just need to type:
cjots.pl
Cjots is very simple to use, it works like this:
Cjots is broken up into 3 panes. The Book List pane, the Pages pane, and the Text pane.
(These are covered in the sections 'Books', 'Pages' and 'Text' respectively).
Your folder ('notesdir' set in the .cjotsrc config) contains books (which are files). These books appear in the Books List.
Each book contains pages, the pages are shown when you open a book.
Each page contains text, this text is editable when you select a page.
There are a number of things you can do with books, pages and the text in them, read on for details.
You can press F1 at any point in Cjots to get help.
Working with Books concerns the Book List / Bookshelf / Book pane in the TOP LEFT.
This list contains all books, or actually any files found within the directory specified by 'notesdir' variable in your configuration file .cjots. Usually ".notes" in your home directory but if you are using existing KJots books, you'll specify the directory where they are kept.
From this pane you can:
UP/DOWN...Select a book
F6........Create a new book
F2........Rename the selected book
ENTER.....Open the selected book
Note: To delete a book, you have to remove all the pages first (to stop accidental deletions).
Working with Pages concerns the Page List / Table of Contents pane in the BOTTOM LEFT.
This lists all the pages belonging to the selected book that you have opened.
From this pane you can:
General Operations:
UP/DOWN..Select a page, the text of that page will display to the right in the Text Editor
F6.......Insert a new Page after the currently selected Page
F2.......Rename the currently selected Page
F3.......Save the current book, note that the book is saved under most circumstances automatically, when you change page, quit, etc.
F4.......Focus the book list, the current book is auto-saved and closed
F7.......Run a plugin / External command, see the 'Plugins' Section for more information
F8.......Delete the selected Page
F9.......Export the current book, note that this is different from export PAGE which is done if you press F9 from the PAGE list. You get a choice of HTML or Plain Text.
ENTER....Edit page
Note: All books must have at least 1 page
Cut, Copy & Paste Pages:
x...Cut a page, it is deleted from the list, but stored in memory
y...Yank a page, it is NOT deleted, but stored in memory
p...Paste a page stored in memory (after cutting or yanking it). It is pasted below the currently selected page, thus 'x' and 'y' can be used to move a page in the list.
Note: Cut/Copy/Paste operations can be done between books.
Merging and Splitting Warning: see the 'Bugs' section.
m....Merge a page with another page, be careful entering the number it asks for!
If something goes wrong, your text can be recovered by pressing F12 from within the text editor.
To split a page:
This sounds strange, but just type \NewEntry title where you want to split the page, where title is the name you want to the new page. Put new lines above and below then just press F4 to focus the Book List, and then open the book again - your new page(s) should be listed.
Working with Text concerns the Text Editor pane to the RIGHT.
General Operations
Esc...Focus the Page List
F3....Save (but note that the book is autosaved during most operations like changing page, changing book, quitting, etc)
F4....Focus the book list, your current page and book is autosaved and closed
F7....Run a plugin / External command, see the 'Plugins' Section for more information
F9....Export Page, note that this is different from Export BOOK, which is done if you press F9 from the BOOK LIST
Copy & Paste Text
F11....Copy the contents of the current page to a buffer
F12....Paste the contents of the buffer to the current page
Note: This is a separate buffer to that used to copy entire pages, see the 'Pages' section.
Other operations
See the 'Appendix' of this Document for more key commands which can be used from the editor
Cjots plugins are basically just shell commands that can be run to interact with a Cjots Book
These commands are writtin in the 'plugins file' which is any file specified by the plugin_file variable in the configuration file.
Plugins are listed in that file, one per line, in the format of a command and a description separated by one or more tabs.
You can use the following variables:
$file which will be replaced by the filename of the current open book
$page which will be replaced by the text of the currently selected page
$arg which will be replaced by an argument at the time of execution (the user will be prompted)
Lets look at some examples, note that some example need external programs like lynx and aspell to work:
#COMMAND DESCRIPTION
date +"%F" Insert the current date
date +"%r" Insert the current time
date +"[%r] >" Insert the current time as an IRC style time stamp
wc "$file" Char/Word/Paragraph Count of the Book
echo "$page" | wc Char/Word/Paragraph Count of the Page
echo "$page" Print Page to Screen (Better for copy & pasting with mouse)
echo "$page" | aspell -a Spell Check Page
lynx -dump "$arg" Dump a webpage, $arg will be the URL of the webpage to dump
KN0WN bugs in Cjots 0.82 at the time of writing:
* The Help (F1) page doesn't fit on everyone's screen
* There is no way to put a literal '$date' or '$time' string in a page/book name, or a literal $file, $page or $arg string in a command / plugin.
* There is no way to have a literal tab within a shell command listed in the plugins file
* Books starting with a stop '.' in the filename will be invisible and not show up in the list.
* If by complete chance you write the string \NewEntry starting on a new line, it will cause the book to be parsed differently next time it is loaded and it will split the page around either side of that line. This can actually be used as a method to split a page. No data will be lost.
* The merging function needs extra work to contol the input. Care should be taken to enter the number correctly when prompted. Any lost text can be recovered by pressing F12 from within the Text Editor. Do NOT press F11 first.
* The selected book and page dont always show as Selected when your in the Editor pane
Notify the author of any further bugs you find:
jesse read AT gmail.com
Some things which will be appearing in future versions.
* Auto save with every character or line typed
* Search function
* Scrollbars
* A way to skip through pages without going back to the Page List
* 'Exporting' could be better done as a plugin
Anything else you want? Email the author jesse read AT gmail.com to request a feature for the next version.
Q: I'm getting a 'Your screen is too small..' message when I start Cjots
A: In your .cjotsrc file, set 'toc' and 'max_bookshelf_height' to smaller values.
Q: The Escape Key does't work for returning to the Page list
A: Sometimes in the terminal you have to hit it twice, and there is a delay. Use F5 Instead, or the HOME key.
Other problems? Questions that need Answering? Email the Author: jesse read AT gmail.com
See Editor Commands