NixNote 1.

2
User's Guide & Technical Overview

Revised July 16, 2011

Page 1 of 44

Table of Contents
Differences Between Evernote & NixNote...................................................................................................6
Installation...................................................................................................................................................9
Known problems on 64 bit systems.........................................................................................................9
Interacting with Evernote..........................................................................................................................10
Initial Synchronization...........................................................................................................................10
Selective synchronization......................................................................................................................10
Storing your userid & password.............................................................................................................10
Synchronization intervals.......................................................................................................................11
Emptying the trash................................................................................................................................11
Using multiple Evernote accounts.........................................................................................................12
Security..................................................................................................................................................12
Privilege Hack........................................................................................................................................12
Using NixNote............................................................................................................................................13
Notes.....................................................................................................................................................13
Ink notes............................................................................................................................................13
Merging notes....................................................................................................................................13
Note history.......................................................................................................................................13
Duplicating a note..............................................................................................................................13
Background color...............................................................................................................................13
Title colors.........................................................................................................................................14
Save interval......................................................................................................................................14
Thumbnails........................................................................................................................................14
Viewing note lists...............................................................................................................................14
Emailing notes...................................................................................................................................14
Printing..............................................................................................................................................14
Note HTML Source............................................................................................................................14

Page 2 of 44

Note Links..........................................................................................................................................15
Notebooks.............................................................................................................................................16
Creating, editing, & deleting notebooks............................................................................................16
Stacks.................................................................................................................................................16
Opening & closing notebooks............................................................................................................16
Tags........................................................................................................................................................17
Merging Tags.....................................................................................................................................17
Saved Searches......................................................................................................................................18
Deleting Notes.......................................................................................................................................19
Custom Icons.........................................................................................................................................20
Screen Clipper........................................................................................................................................20
Colored Notes & Note Titles..................................................................................................................20
Keyboard Shortcuts...............................................................................................................................20
Preferences Dialog.....................................................................................................................................21
Indexing.....................................................................................................................................................23
Interval and synchronization.............................................................................................................23
Reindexing specific notes or the entire database..............................................................................23
OCR Data............................................................................................................................................23
Attachments......................................................................................................................................24
Editing Attachments..........................................................................................................................24
Tools..........................................................................................................................................................25
Import folders........................................................................................................................................25
Import/export of data............................................................................................................................25
Spell Checking........................................................................................................................................26
Backup/restore of data..........................................................................................................................26
Security......................................................................................................................................................27
Database encryption..............................................................................................................................27
Linked Notebooks......................................................................................................................................28
LaTeX Formulas..........................................................................................................................................29

Page 3 of 44

Command Line Options.............................................................................................................................30

NN_NAME=<name>...........................................................................................................................30
NN_HOME=<path>............................................................................................................................30
NN_XMS=<memory>.........................................................................................................................30
NN_XMX=<memory>.........................................................................................................................30
NN_NEW_RATIO=<ratio>...................................................................................................................30
NN_GC_OPT=<option>......................................................................................................................30
NN_DEBUG=<option>........................................................................................................................30
Frequently Asked Questions......................................................................................................................31
What Evernote features does NixNote support?...............................................................................31
Why does it require so much memory?.............................................................................................31
Why is it so slow?...............................................................................................................................31
Why is it so ugly?...............................................................................................................................31
Why does it disappear when minimizing?.........................................................................................31
What does it mean when it says A thread has died?......................................................................31
Does NixNote use SSL?.......................................................................................................................32
Can I do a client-to-client synchronization or synchronize without going through Evernote?...........32
NixNote doesn't stop when I exit the program!.................................................................................32
How can I help?.................................................................................................................................32
How about money for NixNote development?..................................................................................32
Is Evernote giving anything?..............................................................................................................32
Why don't you support creating ink notes?.......................................................................................33
Why did you write it in Java?.............................................................................................................33
Why did you choose Qt Jambi as the GUI?........................................................................................33
Can you implement feature ___?......................................................................................................33
Can it run on a thumb drive?.............................................................................................................33

Page 4 of 44

Is there a way to set global hot so I can press Ctrl-F from anywhere & bring up NixNote?...............33
Development.............................................................................................................................................34
Setting up a programming environment................................................................................................35
Programming Language.........................................................................................................................35
Database................................................................................................................................................36
Evernote data .......................................................................................................................................37
Threads..................................................................................................................................................37
SyncRunner thread and synchronization processing.........................................................................38
IndexRunner Thread..........................................................................................................................40
SaveRunner Thread............................................................................................................................40
ThumbnailRunner Thread..................................................................................................................41
Counter Threads................................................................................................................................41
Program Directory Hierarchy.................................................................................................................42
Java Class Hierarchy ..............................................................................................................................43
Third Party Libraries...............................................................................................................................44

Page 5 of 44

Differences Between Evernote & NixNote

I've tired to keep NixNote with the same feature set as Evernote. Despite this, there are some
differences. Some of these I hope to correct as time allows, some I'll never be able to correct due to
limitations, and some I may never correct unless someone asks since I find no use of them.
Features in Evernote that NixNote doesn't have or does differently:

Searching is different. Evernote will search for partial words, so if you search for book it will
find the word bookstore in a note. NixNote matches on whole words by default, so searching
for book will not find bookstore in a note. There are two reasons for this difference. First,
searching is several times faster by only matching the full word. Second, I personally don't like
the way Evernote handles it. I can see where it is useful, but I typically know what I want to
search for and looking through a list of false positives is frustrating for me. If you feel you need
this, you can force it to automatically add wild cards by going into Edit/Preferences/Appearance
and checking Automatically Wildcard All Searches.

The search syntax is slightly different. I think all the same search features work, but NixNote
allows any term to be negated, where Evernote does not. For example, searching for the term
notebook:inbox will find any note in the inbox notebook, but searching -notebook:inbox will
search for any note containing the word inbox and doesn't contain the word notebook.
NixNote interprets this differently. It will searh for any note that is not in the notebook inbox.

Twitter & Facebook sharing. I don't use it so I don't plan on implementing it any time soon. If
this is important then you can let me know and I'll look into it, but it is pretty low on the list of
things to do.

Audio notes are not directly supported. Evernote allows you to directly record a message, but
NixNote does not. The best workaround is to create the audio file in another application and
attach the file to a note.

Evernote has the ability to use webcams to capture pictures. NixNote does not have this ability.
The best workaround is to create the image in another application and attach the image to a
note.

Ink notes are not possible. Evernote doesn't provide an API for ink notes and reverse
engineering the file format is something I can't do. You can view ink notes as an image, but that
is it. Many of Evernotes non-Windows clients have this same restriction.

NixNote doesn't have a screen clipper. A simple workaround is to use a third party clipper and
setup an auto-import directory. For example, I use Shutter and have it configured to

Page 6 of 44

automatically save images to a directory. I then have NixNote automatically import from that
directory.
There are a few small features that NixNote has that Evernote doesn't. None of them are earth
shatteringly cool features, but I like them.

Selective notebook synchronization. You only ever want to do this the first time you install
NixNote, but it will allow you to specify what notebooks you wish to download. The primary
benefit is the ability to keep personal notebooks off a work PC or to allow NixNote to be used on
smaller netbooks.

You can close or open notebooks to make them disappear. This is similar to the selective sync
feature, but it is different. It allows you to do full synchronization of a notebook, but you can
hide notebooks you don't frequently use. I use this feature for some older reference material
that I seldom need, but I don't want to forget. This just hides them in the interface so when I
search I don't need to look through all those old notes. The important thing to remember is that
this does NOT impact any synchronization of a note.

MS-Word, PowerPoint, Excel, Outlook, OpenOffice (or Libre Office) documents & spread sheets,
and RTF documents as well as PDF documents are indexed. The indexing isn't perfect, but it can
find most things that I've tested.

You can have multiple accounts under the same Windows, Linux, or OS-X login ID. These
accounts could be linked to separate Evernote accounts.

Totals for tags & notes are dynamically updated filtering notes. For example, if you select the
notebook inbox the counts beside the tags change to only be the count of notes matching
your selection criteria.

Editing the source of a note is possible, so if you REALLY want to mess with the formatting or
just want to see what it looks like you can do an Edit/View Source. I don't recommend it for
everyone since you can really mess things up, but it can be useful at times.

Notes can be pinned. A pinned note will always appear in the note list regardless of any other
selection criteria. If a notebook is closed, however, a pinned note will not be visible.

Note titles in the note list and individual note backgrounds can be colored. Since this is a nonstandard view, the note may not appear with a colored background on Evernote clients (it
depends upon the client) and editing them on another client can result in a loss of that color.
Note titles can be colored in the note list and will not appear colored in any Evernote client but
they are synchronized across NixNote clients.

NixNote has notebook specific sorting, so when changing notebooks the sort options will
automatically revert to the order you last viewed for that notebook.

Page 7 of 44

You can quick link from a note to another note by highlighting text & selecting Quick Link
from the context menu. It will then search for any notes with titles matching the selected text.

NixNote has the option of including notes with the children of any tags in a selection. This
allows you to select a higher level tag & see any notes which contain children of the selected
tags. Since this is a non-standard option, it is disabled by default. It can be the enabled in
Edit/Preferences dialog.

LaTeX formulas can be inserted as PNG images and edited later when needed. Please note that
Internet connectivity is required as it goes out to another site to produce the images.

Page 8 of 44

Installation
NixNote can be installed in various ways depending upon the operating system you are using.
For Linux based systems there are several options. Debian/Ubuntu can use the deb packages, RedHat
based systems can use RPMs, and any other packages can use the tar file. In addition to these there is
an Arch Linux package but I dont maintain it and the last update on it said the original packager will no
longer maintain it since they dont use the software.
Windows users can download the install file. It contains both the 32 & 64 bit versions and should install
the correct run time libraries based upon your system.
OS-X based systems can use the tar file and extract its contents. I dont have Macintosh system to test
the install or to debug with, but I have heard from others that it works.
After starting NixNote for the first time it will create a database in your home directory. The database
and temporary files needed for the program to run properly are installed in the .nevernote directory off
your home directory.

Known problems on 64 bit systems

If you are running a 32 bit Java JVM on a 64 bit Windows or Linux system you may have problems
starting NixNote.
To correct this problem on Linux, there are two solutions. Either change to a 64 bit Java virtual machine,
or uninstall the package and download the 32 bit NixNote tar.gz file.
For Windows the easiest thing to do is to convert to a 64 bit Java virtual machine.

Page 9 of 44

Interacting with Evernote

Initial Synchronization
NixNote is designed to interact with Evernote and synchronize any data you have. The first time you
synchronize it will download all of your data. The first sync can take a very long time based upon the
size of your database.
If it encounters problems and crashes on the first sync, you should be able to restart the program and
continue the synchronization. It will take up the synchronization where it stopped.

Selective synchronization
If space is a concern, you can choose which notes you wish to synchronize. It is easiest to do this before
the first sync, or youll download everything in your account only to delete it later. If you have already
synchronized and wish to use this feature you can do it at any time.
When you use this feature NixNote will still download all notes just as if you were doing a full
synchronization, but it wont save any notes matching your criteria. It will also allow you to create any
notes with those tags & notebooks and will store them until you synchronize. When you synchronize,
the note will be uploaded & deleted from your local database. They should then be available online.
To setup selective synchronize follow these steps:
1. Under the Online menu, choose the option Connect.
2. Choose the option Selective Synchronize. NixNote will then prompt you for your userid &
password.
3. After connecting it will download a list of your notebooks & tags. Choose the tags you wish
to ignore and click OK.
4. Synchronize your account.
There is a penalty to using this feature. If you use it and later change your mind NixNote wont go back
and download any missing notes until that note has changed. When the note has changed Evernote will
send a fresh copy and it will be available offline.

Storing your userid & password

If you dont want to constantly be prompted for your userid & password, you can tell NixNote to
remember it. Under Edit/Preferences there is an option called Connection. In that dialog enter in
your userid & password and click the checkbox Remember Userid & Password.
Please be aware that your userid & password ARE NOT SECURE. They are saved in an encrypted file to
prevent the casual user, but any determined person can decrypt this file.
Page 10 of 44

Synchronization intervals
NixNote will synchronize every 15 minutes by default. You can customize this under the
Edit/Preferences dialog in the Connection section.
There are a few other options you can customize if you wish.

Automatic Connect This option will automatically log you into Evernote and start a sync
when you start the program. If you dont store your userid & password, this option doesnt
work.

Synchronize On Shutdown By choosing this option NixNote will do a final synchronization

when it shuts down. This option will only work if you are connected at the time you shut
down. If you are not connected it will not synchronize.

Synchronize Deleted Note Content By default, when a note is deleted and you synchronize
the note is only flagged for deletion on Evernotes servers and any changes you may have
made are not synchronized. The advantage of this is that it doesnt use as much of your
upload quota on a note you no longer care about and it reduces the synchronization
interval. The downside is that if you restore it from the trash on another Evernote client,
the contents will not be in sync. By choosing this option you are telling NixNote not to just
mark the note for deletion, but to synchronize any change to the note.

Proxy Settings if you are behind a firewall you can specify the proxy host and (if needed)
the userid & password you need to access the Internet. I have heard from some users that
adding the proxy host does work, but they didnt need to specify a userid & password so I
dont know how well this feature works (or if it works at all) since I dont have access to a
proxy server.

Emptying the trash

When you delete a note it is moved to the trash. The next time you synchronize that note should then
be moved to the trash in your Evernote account. This works the same as any other Evernote client.
There is I difference in behavior between NixNote and the way Evernotes official clients handle the
trash. When you empty the trash on an Evernote client it is permanently removed from your local
database and when you synchronize it is permanently removed from your online account.
NixNote doesnt work this way. In NixNote, when you empty the trash you can no longer restore it and
the note vanishes from your trash, but when you synchronize it will remain in your trash on in your
online account and is not permanently deleted. If you empty the trash on another Evernote client, the
note is then permanently removed from NixNote. If you restore the note from Evernotes trash it will
reappear in NixNote.

Page 11 of 44

This is due to an Evernote security restriction. In the past, they had third party API developers delete
the wrong notes and cause work for their support team to restore the note. To prevent this they dont
allow other clients to permanently delete notes.

Using multiple Evernote accounts

NixNote will allow you to access multiple Evernote accounts at one time, but these accounts are stored
in different databases. To do this, you need to create a separate shortcut or launch command for
NixNote and pass the parameter NN_NAME=my_name where my_name is any name you wish to use. It
does not need to match your Evernote account ID. When you start NixNote with this parameter, it will
create a new database for that instance, but will otherwise work the same way.

Security
NixNote uses HTTPS to communicate with Evernote. All data, your userid, and password is encrypted
when it is transmitted.

Privilege Hack
It is not necessary to have an Evernote account to use NixNote. NixNote wont prompt you for a
userid/password until you try to connect to Evernotes servers. If you never connect it is the same as
having all local-only notebooks.
If you are a premium user of Evernote you have the ability to attach any type of file to a note. If you are
a free user you are only permitted images, PDFs, and a few audio file types. If you dont plan on using
Evernote then you can trick NixNote into thinking you are a premium user and it will allow you attach
any file type the same as if you were a premium member. To do this you need to edit the NixNote
configuration file. In Linux & OS-X youll find the file in ~/.config/fbn.cx/NixNote.conf. Under Windows
you need to use Regedit and search for fbn.cx.
Once you have the configuration file open (or the registry) you need to find the section User. In that
section there may be a value privilege. Change that value to 3 and restart NixNote. NixNote should
then think you are a premium user. If you dont find that value under User, then you will need to
insert it.
If you synchronize with Evernote and wish to do this I think it will still work, but be careful. If you attach
a file type that a free user cant normally use then that note will not synchronize and youll get an error.
If you do this, it is safest to do it in local-only notebooks.

Page 12 of 44

Using NixNote
Notes
Ink notes
NixNote allows you to create a text note and synchronize it with your Evernote account. You cant
create or edit ink notes. Evernote doesnt provide an API or any documentation on the file formats for
ink notes so there is nothing I can do but vewing ink notes is possible. When you synchronize it should
pull an image down and show it to you. The note is read-only and you cant change the contents.
Evernotes non-Windows clients cannot edit ink notes, so Im not expecting Evernote to provide this
ability to other third party clients any time soon.
Merging notes
You can merge the contents of multiple notes together. This is done by selecting multiple notes in the
note list and choosing Merge Notes. The order of the merged notes is the same order in which you
selected them.
Note history
If you are a premium user, you can restore older versions of notes from Evernotes servers. This is under
Online/Note History and you must be connected for this feature to work. If you are a free user, you
can use this to pull a copy of the note as it currently exists on Evernotes servers.
When you restore a note you can either overwrite the existing note or you can restore it as a new note.
If you restore it as a new note then all data is separate from the original note and it is treated the same
as any other new note.
The history feature does a lot of communication with Evernote, so depending upon the contents of your
note and the speed of your connection it could be very slow. Please be patient.
Duplicating a note
NixNote allows you to duplicate an existing note. Any data or file attachments are treated as separate
notes. This can be useful if you wish to use one note as a template for other notes.
Background color
You can change the background of any note by right clicking in the note and choosing the Background
Color option. This is a non-standard feature and it may not work on all Evernote platforms. Ive used it
in Evernote 3.5 with no problem but I dont know about other native clients. Depending upon your web
browser it may appear properly in the web interface, but editing it in the web interface will remove the
color.

Page 13 of 44

Title colors
Another non-standard feature is the ability to set the color of a note in the note list. To change a color,
right click in the note list and choose Title Color. This data is NOT synchronized and if you delete your
local database or if your local database becomes corrupt you will lose this color.
Save interval
Under Edit/Preferences you can customize how often NixNote will save the note you are editing. By
default, it will save every 5 minutes. Increasing this value reduces the overhead slightly, but increases
your risk if the program crashes.
Switching from one note to another note always results in the note being saved and it will automatically
be saved prior to a synchronization starting or when the program is shut down.
Thumbnails
NixNote will try to create a thumbnail of your note. By default, this is enabled but it can cause large
CPU and disk space since it needs to render each note in your database. You can disable this under
Edit/Preferences in the Debugging section. By default it is enabled.
Viewing note lists
You can customize the list of notes and you can customize where it appears. By default it is on the right
hand side of the screen just above the note editor. By selecting View/Narrow List View or View/Wide
List View you can move it from appearing above the note to appearing between the note and the left
hand panels.
If you dont wish to change which columns are visible in the note list, you can customize them by right
clicking the title bar and choosing the columns to view. The wide view and narrow view are
separate so customizing one does not update the other. This is to allow for things like a thumbnail in
the narrow view where you have more vertical space, but hiding it in the wide view where you want to
be able to see a larger number of notes.
Emailing notes
You can email any note from NixNote by clicking the email icon in the toolbar and it will start your
default email client. At this time, it will only email plain text and will not email attachments.
Printing
A note can be printed using the print icon. If you are a Linux user you must have CUPS installed or
printing will not work. Some people have also had problems with network printers or specific models of
printers, but unless I can recreate the problem I cant fix them at this time.
Note HTML Source
You can view the HTML source of a note under the View/Vew Source menu option. Doing this allows
you to change the markup of a note more directly and overcome some of the editor's limitations, but it
also means you can really mess things up. NixNote won't prevent you from producing really badly
formatted HTML but it will still try to clean up anything you create so it can synchronize with Evernote
properly.
Page 14 of 44

Note Links
Note links can be created in NixNote by right clicking on a note in the note list and selecting Copy as
URL. You can then paste the URL into another note. When you click on the link, the note will open in a
new window.
If a note exists in a synchronized notebook, you will be prompted to synchronize with Evernote before
you can create a note link. This is to prevent the link from being lost when a new GUID is assigned to the
note after it is synchronized.
It is also possible to have a broken link by performing the following steps:
1. Create a new note in a local notebook.
2. Create a link to that note in another note.
3. Switch back to the first note and move it to a synchronized notebook.
Doing this will cause a broken link in the second note. This is the same behavior as in Evernote's clients.

Page 15 of 44

Notebooks
Creating, editing, & deleting notebooks
Notebooks can be created or renamed the same as any Evernote client. When you create a notebook
you have the option of creating it as a local or synchronized notebook. Local notebooks are saved only
on your hard drive and never go through Evernotes servers. If you local notebooks I highly recommend
doing frequent backups to preserve any data in the event of a crash.
You can move notes from synchronized notebooks to local notebooks. If you move a note to a
synchronized notebook it will be created on Evernote the next time you synchronize. If you move from
a synchronized notebook to a local notebook that note is moved to the trash on your Evernote account
the next time you synchronize.
Renaming a notebook works the same as any other Evernote client. The next time you synchronize it
will update the name on Evernote. NixNote will not permit two notebooks to have the same name and
it is case insensitive, so you cant have a notebook called My Data and another called my data.
NixNote considers them to be the same. Evernotes clients work this way too.
Deleting a notebook is possible only if all notes in that notebook have been deleted or moved to other
notebooks. It doesnt allow you to delete a notebook and all notes in one operation.
Stacks
NixNote supports stacks the same as other Evernote clients. To set a stack right click on the notebook
and select Set Stack or choose the option File/Notebook/Set Stack. There, you can set a stack name
or choose an existing stack for that notebook. To remove a notebook from a stack simply blank out the
stack name and click OK. It will then be removed from that stack.
Opening & closing notebooks
NixNote has a non-standard feature to permit you to show or hide specific notebooks. This allows you
to, for instance, hide all your personal data on your work PC or hide notebooks you seldom use.
To open or close a notebook, choose the option File/Notebook/Open/Close. A dialog box will appear
where you can choose the notebooks you wish to view.
Please note, this does NOT change any synchronization behavior. Any changed notes are synchronized
regardless if the notebook is opened or closed and all data remains on your hard disk. If you dont wish
to have this feature, then you need to do a selective synchronize.

Page 16 of 44

Tags
Tags in NixNote work in much the same way as other Evernote clients. You cant have duplicate tag
names and selecting a parent tag does not show notes containing the children of those tags. This is to
mimic Evernotes interface.
When you create a tag it is placed in the top level of the tree. If you want it somewhere else you need
to drag it to that tag and it will be moved to be a child of that parent tag.
You can choose how to view tags under Edit/Preferences in the Appearance tag. The options are

Do Nothing This will show you a list of the tags and the total number of notes matching them
regardless of any selection criteria.

Count Tags & Do Not Hide Inactive This will show you all tags available. In addition, the
number of notes assigned to that tag will be shown next to it. This count is updated based upon
the notes visible in the note list, so as you search for notes that count will change.

Count Tags & Hide Inactive This option will hide any tags which are not assigned to any notes
in the note list. As you change your search criteria tags will appear & disappear. If a child tag
should be visible, then the parent for that tag will also be visible.

Color Active Tags This option will show you all tags and will update the counts the same as
Count Tags & Do Not Hide Inactive but it will change the text color of any tags matching the
search criteria.

Merging Tags
You can merge multiple tags into one tag. To do this, select the tags you want merged (including the
one you want them merged with). Right-click in the tag menu and select the Merge menu option.
This will bring up a dialog box of the selected tags. Choose the tag you want them merged into and click
OK. Any notes with any of the selected tags will be changed to the one tag. Please note that the old
tags are not deleted.

Page 17 of 44

Saved Searches
Saved searches work the same as in the Evernote client. I believe the full syntax is supported, but as
Evernote announces new search keywords NixNote may be a little behind implementing them.
The current items supported are:

Any word or phrase. You can use * to indicate a wild card.

Words in the title of a note (intitle:)

Tags (tag:)

Notebook (notebook:)

Author (author:)

Source (source:)

Source Application (sourceapplication:)

Created (created:)

Updated (updated:)

Subject Date (subjectdate:)

Todo (todo:)

Recognition Type (recotype:)

Stack (stack:)

Longitude (longitude:)

Latitude (latitude:)

Altitude (altitude:)

In addition to the search terms, you can prefix with a term with a negative (i.e. -tag:) and it will negate
the statement. Using this, you could search for all notes that don't match the criteria (for example, all
notes not tagged with a value).

Page 18 of 44

Deleting Notes
Deleting a note moves it to the trash. It can be restored at any time until the trash is emptied. When
the trash is emptied, the note is not permanently deleted from NixNote until you empty the trash on an
Evernote client. The section Emptying the trash above has more details.

Page 19 of 44

Custom Icons
If you dont like the notebook, stack, saved search, or tag icons that NixNote uses you can change them.
Choose the tag you wish to update, right click, and choose Set Icon. You can then click on the icon
image and a dialog box will appear. Currently, only PNG images can be used as icons. The icon you
choose is stored within the database, so updating the icon outside of NixNote doesnt cause the icon to
change appearance within NixNote.
This data is not synchronized, so if you delete your database or if it becomes corrupt you will lose your
custom icons.

Screen Clipper
NixNote doesn't come with a screen clipper. If you need one the easiest thing to do is to download the
screen clipper of your choice (I recommend Shutter for Linux and Snagit for Windows). Change the
settings for the clipper to save any images to a folder. When you've done this, add that folder to
NixNote as an auto-importing folder that deletes the file upon importing. This will allow you to create
screen clips without NixNote being active. When NixNote starts it will create a note of the image

Colored Notes & Note Titles

NixNote allows you to change the background color of a note. This isn't officially supported by Evernote,
but it will display properly on some of their clients. You can set the background color by right clicking in
the note and selecting Background Color. Be aware that editing the note on an Evernote client or in
the web version of Evernote may remove this color. It depends upon the client.
You can also change the background color of the title of a note. This will change the background color in
the note list. This is a non-Evernote supported attribute and will not be synchronized with Evernote's
servers.

Keyboard Shortcuts
Most of the menu items in NixNote can be customized. To do this, you must create a shortcut.txt file in
your nevernote home directory (the default for this is ~/.nevernote in Linux). For more information on
customizing shortcuts, look in /usr/share/nevernote/shortcuts_howto.txt in Linux or C:\Program
Files\NixNote\shortcuts_howto.txt on Windows. After making any changes, you must restart NixNote
for the changes to take effect.

Page 20 of 44

Preferences Dialog
Under Edit/Preferences there are various options that can change the appearance of NixNote. The first
tab you will see is the Appearance tag.

The GUI Style and Use standard palette control the style sheet that NixNote uses. By default
there are 6 different styles.

NixNote also has theme support. You can modify these styles by creating a default.qss and
putting it in your ~/.nevernote/qss directory. For details on how to use this file to customize
NixNote, please visit http://thesmithfam.org/blog/2009/09/10/qt-stylesheets-tutorial/ for a
style sheet tutorial.

The time and date dialogs control the date & time format NixNote uses to display date & time
fields.

Mimic Evernote Selection Behavior alters the way NixNote handles notebooks. By default,
you cannot select more than one notebook. If this is not checked, NixNote will remove the All
Notebooks entry and will permit multiple notebook selections. Changing this value requires
you restart NixNote before it takes effect.

Minimize to Tray tells NixNote to put a small icon in the system tray when it is minimized. It
also hides the window from the normal task bar. In older releases, this was the default but in
more recent ones the default is to not minimize the application to the tray.

Minimize on close tells NixNote to ignore the close window action and will minimize it instead.
If you do not have Minimize to tray selected you cannot enable this value.

Show splash screen on startup controls if NixNote will display a splash screen image upon
startup.

Verify Deletes tells NixNote to prompt for verification each time a note is deleted.

Display PDF Documents Inline controls how NixNote displays notes with PDF attachments. If
selected, it will try to create a PNG image of the first page of the PDF. The user can then use the
arrow keys above the image to browse through the PDF without leaving NixNote. If this value is
uchecked, the PDF will be displayed as a small icon which, when clicked, will launch the default
PDF reader.

Create New Notes With Selected Tags alters the way NixNote acts when a note is created. If
selected, any new note will automatically be assigned any tag that is currently selected. This
allows for more quickly creating & tagging new notes when entering lots of notes at once.

Page 21 of 44

Display Notes Matching Any Selected Tags determines how notes are selected based upon the
tags selected. By default a note must match all of the tags selected to be displayed. Any notes
which do not match all of the selected tags does not appear in the note list. If this option is
selected, any note matching any selected tags will be displayed.

Check for updates at startup will tell NixNote to scan for a new release when it starts. If this
value is unselected it will not check for never versions.

There are other options on this page, but they are discussed elsewhere in this document.

In the Fonts tab there is the ability to change fonts. Setting this option will change the way any new
note looks when it is created. This does not change any existing notes.
The Indexing tab is discussed in the Indexing section of this document.
The spell check tab alters the way the spell checker behaves. Here you can specify words to ignore to
make using the spell checker easier.
The Connection tab is discussed in the Interacting with Evernote section of this document.
The Debug setting controls various debugging settings.

The most useful one is the message level selection. Increasing this will cause more information
to be written to the debugging logs. This can be useful in diagnosing bugs but it will can cause
NixNote to run more slowly and writes some confidential information in the log files. Normally,
you run this with the Low setting.

The database cache setting reserves some memory for the database. This can increase
performance but it will also require more memory to run.

The thumbnails checkbox tells NixNote to spend time creating thumbnails of any note. By
default it is enabled, but you can disable this to save CPU resources and disk space. Once a note
thumbnail is generated, disabling this will not remove the thumbnail nor will it update it if the
note is changed. This can be re-enabled at any time and NixNote will resume creating
thumbnails on any image which needs it.

Server Configuration allows you to specify which server to synchronize with. This isn't used but
at one time it permitted using the Evernote sandbox servers instead of the production servers.

Enable Carriage Return Fix alters the way some notes may be displayed. There are differences
between the method that some notes are created on different platforms. This attempts to alter
the carriage returns to remove double space problems with some notes.

Page 22 of 44

Indexing
NixNote will split out a note into separate words and add those to a separate database for searching.
When indexing, it removes any not-alphanumeric characters from the beginning or end of a note. It
splits the contents into words based upon a regular expression. By default this regular expression is [,\s]
+ but it can be changed to any value you wish. If you change this value, you need to re-index your entire
database or it will only use the new value on new or updated notes.
Interval and synchronization
Indexing is done via a background process. This process starts periodically and scans for any notes
which need to be indexed. You can customize this interval via the Edit/Preferences dialog in the
Indexing section. Reducing this value will cause your notes to be indexed more frequently, but can
increase overhead.
If you wish to temporarily disable indexing, you can stop it by selecting the Tools/Disable Note
Indexing option. Selecting this option a second time will re-enable indexing and it will automatically be
re-enabled when the program is restarted
NixNote will index any note that hasnt been changed in the last 5 minutes. This is done to prevent
constantly indexing the same note until you are done with it. It will also not index during a sync to
prevent wasting time indexing a note that may be updated due to a sync. When a sync is complete it
will wait for the next interval and begin indexing again.
Reindexing specific notes or the entire database
Indexing your entire database takes time, but if you want to do it again you can tell NixNote to do this by
choosing the Tools/Reindex Database option. If you want to reindex a specific note you can choose
the menu option File/Note/Reindex Note and only the current note will be reindexed.
When a note (or the database) is reindexed the search words for that note are not immediately deleted,
but are deleted just prior to indexing that note.
OCR Data
When Evernote gets a note, it will OCR any images in a note and (if you are a premium member) it will
OCR any images in PDFs. Evernote stores the OCR text and assigns a value to it. The higher the value
the more certain it is that it found a word. The next time NixNote syncs, Evernote will send that OCR
data and NixNote can then add it to its search database.
You can tell NixNote how certain you wish to be when searching for images under Edit/Preferences in
the Indexing section. By default it is 30 but it can be changed to whatever you wish. When you
change this value you do not need to re-index your database.
Data which has not passed through Evernotes servers (local notebooks and unsynchronized notes) does
not contain any OCR data.

Page 23 of 44

Attachments
NixNote has the ability to index PDF, Microsoft Office (Excel, Outlook messages, Word, & PowerPoint),
Rich Text Format, ODF, and text documents. This isnt perfect but in my limited testing it seems to work
reasonably well. This does, however, increase the database size immensely if you have a lot of
attachments. You can enable or disable this under Edit/Preferences in the Indexing section. If you
enable this option it will NOT reindex any existing attachments, so you may need to reindex your entire
database to get all of your attachments indexed.
This also causes some problems when shutting down NixNote. The main problem is that it can hang the
shutdown process if it is indexing an attachment when you close the program. Ive tried to find ways
around it but so far have not been successful. It does not have this problem if you close after indexing is
complete or if it is not indexing an attachment.
Editing Attachments
By clicking on a file attachment the default program for that file type is launched. If that program allows
editing any changes made will be updated in NixNote. For example, if you open an image in a note using
an external editor, any changes to that image will be reflected in the note. This works the same as
Evernote's clients.

Page 24 of 44

Tools
Import folders
Import folders are used by NixNote to automatically import data when it appears in a directory. There
are two types of import folders.
The first type is Import and keep. This type of directory is monitored while NixNote is running. If a file
is moved into that folder or an existing file is modified it will create a new note in NixNote with the file
name as the title. If NixNote is not running then any new or changed files in this directory will not be
imported.
The second type is Import and delete. This is the same as Import and keep except for two things.
The first difference is that the file is deleted when the note is created. The second difference is that if a
file exists in that directory when NixNote starts it will import that file and create a note, so that even if
NixNote is down a note will be created when it starts.
The contents of any new notes that are automatically imported depends upon the type of file.

Image files are created from image files (PNG & JPG).

Text files are created from plain text files.

Other types of files are are created as an attachment in a new note.

If you are a free user you won't be able to create new notes with attachments with any type
except those permitted by Evernote. File types that are note permitted are ignored.

If NixNote is running, it will notice the new (or changed) file as soon as it is written.

Import/export of data
Under the File menu there is an option to export and import notes. Exporting notes creates a NixNote
export file with the extension of nnex and contains information about any selected notes. This includes
notebooks, tags, & resources.
Restoring a notet from a NixNote export odes not replace any existing notes and it does not create any
notebooks or tags. An imported note is treated as a new note.
Importing & exporting can be useful ways to move data between NixNote systems if you want to create
a duplicate of an existing note.

Page 25 of 44

Spell Checking
NixNote uses Jazzy to provide spell checking. By default, it ships with several English dictionaries. If you
speak another language you can try to find the proper dictionary at
http://sourceforge.net/projects/jazzydicts/. Download the dictionary and put it in the NixNote program
spell directory. In Linux, this is /usr/share/nevernote/spell and C:\Program Files\NixNote\spell on
Windows. I don't include them by default simply because of space concerns. If you do not need English
(or any other language) you can remove these files.
To the best of my knowledge, Jazzy doesn't support non-Latin based languages.

Backup/restore of data
The backup & restore process is similar to the import/export process with a few exceptoins.
The first difference is that everything is backed up (not just the selected notes). This means that it will
take longer to backup a database than to export a few notes.
Restoring from a backup is also different. I only recommend using this when you have an empty
database. Restoring will not create any new notes. Any restored notes should have the same GUID,
tags, & be in the same notebook as it was when it was backed up. It also will restore notebook, tag, &
saved searches.

Page 26 of 44

Security
Database encryption
As mentioned, storing your userid & password in NixNote is not secure. It is encrypted to prevent casual
viewing but a determined person can decrypt it.
If you need additional security, you can encrypt your entire database. Doing this will does not change
the security of your userid & password (although it probably will in the future). You can encrypt your
database under Tools/Encrypt Database. You will be prompted for a password and when you shut
down NixNote will encrypt your database.
Please be aware that if you forget your password I cannot recover it. The only thing that can be done is
to delete your database and start over.
The database can be decrypted using the same method under Tools/Encryption.
If your database is encrypted, you will be prompted for a password every time you start NixNote. This
does not need to be the same password as your Evernote account.
The advantages of encryption are enhanced security, but it does cause slower response. If you are a
Linux user I recommend encrypting your home directory. This wont cause as severe a performance
impact to NixNote and it makes storing your userid & password in NixNote secure since every file in your
home directory is secure.

Page 27 of 44

Linked Notebooks
Linked notebooks are notebooks that another user shares with you. This allows you to view or, if you
have authority, edit notes in that notebook. The way NixNote handles linked reports is different than
the way Evernote handles them.
In Evernote, linked notebooks are separate from your notebooks. You go to a separate panel to view
them. You can only search one at a time and notes cannot be moved between shared & local
notebooks.
NixNote is a little different. Shared notebooks show up in the normal list of notebooks and you can see
them when you select All Notebooks.
When you create a note, as long as it is not synchronized you can move it to any notebook regardless if
it is synchronized, shared, or local. Once a note is synchronized it is tied to the user's account. If you
synchronize it to a shared notebook it can't be moved to another notebook. You can duplicate the note
to create a copy and (since it isn't synchronized).
Tags, similarly, show up the same as any other tags. You cannot assign a tag in another users notebook
to a note it your account and you can't assign one of your tags to a note in a shared notebook. You also
cannot create a tag in another user's account.
Once you have synchronized, you can modify the name of any shared tags or notebooks the same as any
ther tags or notebooks. The name is NOT updated in the owner's account. It is just a way to help
organize the notebooks & tags.
Other than these differences, shared notebooks should behave the same as Evernote's clients.

Page 28 of 44

LaTeX Formulas
NixNote has the ability to add LaTeX formula images. This is done by sending the formula to CodeCogs
(www.codecogs.com) and using their rendering engine to produce a bitmap. The formula is then
downloaded and stored in the note as a normal image. You can add an LaTex formula in one of two
ways. Please note, you need to have Internet access for this to work.
The first way to insert a formula is to type the formula in a note, highlight it, and select Insert LaTeX
Formula via the context menu.
The second way is to select Insert LaTeX Formula via the context menu with no text selected. This will
cause a dialog box to appear and you can enter the formula. By clicking OK the formula is sent to
CodeCogs.
Any image downloaded from CodeCogs is treated by NixNote as a bitmap image. As a result, the image
is sent to Evernote where the normal OCR processing is done. Once this is done, you can search for text
in the image the same as any other Evernote client. Since other Evernote clients also see this image, you
can search on those clients too.
NixNote does allow you to edit a LaTeX formula. It does this by recognizing the source URL as coming
from CodeCogs. By clicking on a LaTeX image it will bring up a dialog box where you can edit the
formula.

Page 29 of 44

Command Line Options

NN_NAME=<name>
This allows you to have multiple instances of NixNote using different databases. Each database can
point to a different Evernote userid if you wish. If you use this, a separate ~/.nevernote-<name>
directory will be created. For example, passing NN_NAME=test will create a ~/.nevernote-test directory
with separate preferences and a separate database. The default is null, so everything by default goes in
~/.nevernote
NN_HOME=<path>
This specifies the home path for the .nevernote directory. By default this is your home directory but by
specifying this you can point to a separate location. For example, saying NN_HOME=/my/data will cause
NixNote to look for your database in the /my/data/.nevernote directory.
NN_XMS=<memory>
This specifies the initial heap size that Java uses. By default it is 256M, but if you are concerned you can
try to lower it. I've used NixNote with this set to 128M with no problems.
NN_XMX=<memory>
This specifies the maximum heap size that Java uses. The default is 1024M. If you are concerned, you
can probably reduce this after the first synchronization and indexing is complete. I've been able to
decrease it to 256M with no noticeable problems.
NN_NEW_RATIO=<ratio>
Specifies the ratio of the heap used for young generation objects. By default this is set to 1, so if the
heap will be used.
NN_GC_OPT=<option>
Specifies the garbage collection algorithm used by NixNote. The default is -Xincgc (incremental garbage
collection). Other possibilities include -XX:+UseParNewGC, -XX:+UseConcMarkSweepGC, and -XX:
+UseParallelGC
NN_DEBUG=<option>
Specifes JVM debugging options. This can vary depending upon the Java Virtual Machine you are using.

Page 30 of 44

Frequently Asked Questions

What Evernote features does NixNote support?
NixNote supports most of the same features that Evernote's Windows & Macintosh clients support. The
exceptions are webcams, only a subset of the search syntax is supported, ink notes are read-only, and it
doesn't have the ability to post to Facebook or Twitter.
Why does it require so much memory?
NixNote requires a lot of memory. I've tried to reduce it when possible but the I've set the amount of
memory it will try to use deliberately high. The initial synchronization with Evernote and the initial index
require a lot of memory. After that is done, you can try to reduce the amount of memory NixNote uses
by passing the NN_XMX startup parameter. You can also reduce memory by lowering the database
cache size in the Preferences dialog in the Debugging section. In my testing, I've set the NN_XMX
parameter to 256M (the default is 1024M) and it hasn't had any problems.
Why is it so slow?
There are a lot of variables that impact NixNote's speed. Things like CPU speed, database cache, heap
size, and the number of notes & attachments all influence speed. I've done some tuning and I've tried to
improve the performance wherever possible in each release, but there is still some room for
improvement.
Why is it so ugly?
I'm sure it thinks you're ugly too! Seriously, NixNote suffers from a few fundamental problems that
make it look less than beautiful. The first (and largest) is the developer. I have no skill in making pretty
pictures. The images it currently uses are primarily the result of scrounging around for free images. The
second limitation is the lack of time I have. When given the choice between working on fixing a bug,
adding a feature, or concentrating on the GUI, the GUI is typically the lowest priority. The primary goal
is to make something usable, not pretty. Ideally both would be great, but right now my time is limited.
If you want to help then please contact me.
Why does it disappear when minimizing?
Prior to 0.98, NixNote would, by default, would minimize to the system tray and disappear from the task
bar. This caused some confusion so, as of 0.98, the default is to minimize to the task bar the same as
any other program. You can customize this under the Edit/Preferences dialog box.
What does it mean when it says A thread has died?
NixNote uses multiple threads to improve performance. Occasionally one of the threads can run into
problems and die. NixNote occasionally checks these threads and, if one has died, it displays a warning
message. The first thing I'd try is to restart NixNote and, hopefully, that is all you need to do. If you
continually get this message then run it from a terminal (/usr/share/nevernote/nevernote.sh in Linux).

Page 31 of 44

After the thread dies, look in the terminal and see if any messages appear. Cut and paste any messages
and open a tracker issue or a topic in the user forum to get help.
Does NixNote use SSL?
Yes. NixNote uses encryption for userid & password authentication and for all data transfers. At one
point Evernote only permitted SSL data transfers if you are a premium member, but this is no longer the
case.
Can I do a client-to-client synchronization or synchronize without going through Evernote?
No. NixNote was designed to be a client to Evernote. It currently doesn't have the ability to synchronize
directly with other clients. You can, however, do a backup of your database and restore it to another
client. It isn't a true synchronization but it can reduce the amount of network activity needed when you
start NixNote on a machine for the first time.
NixNote doesn't stop when I exit the program!
There is a known bug where NixNote might not stop if it is indexing an attachment at the time you stop.
I haven't been able to determine the cause, but it appears that it is hanging in a utility program needed
to parse out the attachment. To get around it you need to manually kill the process. If your database is
indexed this is less likely to happen (because the odds of it indexing an attachment are less likely). The
benefit of indexing attachments is (to me) worth the inconvenience of this bug, but if you don't agree
you can disable attachment indexing in Edit/Preferences to avoid this problem.
How can I help?
You can do a few things to help. If you are a developer then you can contribute by coding. If you are
not a developer you can help by helping find bugs or suggest features. I could also use help with
documentation.
How about money for NixNote development?
If you like NixNote and you want to help with monetary support, I ask that you donate any amount you
feel is appropriate to the charity of your choice. I'm sure there are other people who are in more need
than me. I also don't want to get into the I'm a paying customer and I want feature X arguments. I do
this in my spare time and don't have the ability or desire to give priority to people who pay me. If you
do donate to a charity, please post a note on the message boards so I can say thanks.
If you use the LaTeX function often, then I'd highly recommend donating to CodeCogs (there is a PayPal
link at http://www.codecogs.com/latex/usage.php). They are kind enough to offer this service and have
not asked for anything, but it does cost them money to run their servers and I'm sure any amount would
be appreciated.
Is Evernote giving anything?
Evernote has been extremely supportive in NixNote's development. Any question I've asked has been
answered and they've been very helpful with things like encryption and ink notes.

Page 32 of 44

Why don't you support creating ink notes?

Evernote doesn't provide an API for ink notes. In order to support creating ink notes I'd need to reverse
engineer their existing file format. That simply isn't something I have the time or ability to do at this
point. The only reason read-only ink notes are supported at all is because it pulls the image from the
web site. Even Evernote has limited ink note support. Only their Windows clients support creating ink
notes. Other clients are read-only just like NixNote.
Why did you write it in Java?
Mainly because I never intended it to be a full client nor was it intended for anyone other than myself.
NixNote started out as something completely different. The initial project I started with failed, but I had
enough to create a thin Evernote client. After creating a thin client I decided to make a full client to
allow off line notes. From there it just grew into the behemoth it is now.
Why did you choose Qt Jambi as the GUI?
Qt has a very nice toolkit for development. I initially tried a few others and used SWT for several months
before giving up & restarting with Jambi. I also hoped that by using Jambi I could eventually move to
C/C++ more easily in the future by replacing sections of Java with C++, but I haven't gotten that far.
Can you implement feature ___?
Maybe. There is a section in the user boards and in the SourceForge project to suggest features. I don't
promise anything but many of the current features are the results of people asking. Things like autoimport folders, LaTeX formulas, and viewing ink notes are all things that were added by request.
Can it run on a thumb drive?
Technically there isn't anything preventing it from running on a thumb drive, but I don't recommend on
using NixNote as a mobile application. You'd need to specify the NN_HOME directory to your thumb
drive and you'd still leave config file traces on any computer. In Linux you'd find these tracks in
~/.config/fbn.cx/NixNote.conf or in Windows it would be in the registry. If you need portability I'd
recommend using the web version.
Is there a way to set global hot so I can press Ctrl-F from anywhere & bring up NixNote?
Not at this time. Java doesn't provide the ability to do do this without native program code. There are a
few free libraries that interact with Java on Windows & Linux, but I haven't investigated them yet.

Page 33 of 44

Development
This section is for anyone who wants to know how NixNote works at a programming level. The goal of
this section is not to document every class & method, but to give a general overview of how NixNote
works.

Page 34 of 44

Setting up a programming environment

If you wish to use Eclipse, here are the steps to set it up.
You want to start by making sure you have Eclipse, a version of the jdk 1.5 or later, and qtbambi
(some java middleware for using a windowing toolkit called QT which is written in C++).
Download the NixNote source by following the instructions here:
https://sourceforge.net/projects/nevernote/develop
You will need a version of Qt Jambi that matches your operating system. If you've already installed
NixNote you can find them in the /usr/share/nixnote/lib directory or the lib directory in the Windows
install program.
Open the nevernote project in Eclipse:
* File > New > Java Project
* Select "Create project from existing source"
* Select the directory where you put the nixnote source
* After you do this you should have some build errors
* Right click the project and click "Properties"
* Click the "Java Build Path" property on the left hand side
* Click the "Libraries" tab
* Scroll down to the bottom and remove the QT_JAMBI/* Libraries
* Click "Add External JARs..."
* Select the qtjambi-4.5.2_01.jar file (in your qtjambi directory)
* Then expand the qtjambi jar (click the arrow to its left) and select "Native library location"
* Click Edit... to the right and navigate to your qtjambi directory and the lib/ subdirectory.
* At this point, you should be able to run NixNote from Eclipse.

Programming Language
NixNote is written in Java. For a lot of its GUI and data structures it takes advatage of QT Jambi. Qt
Jambi is the Java bindings for Qt. When I started, Jambi was supported by Nokia but Nokia has since
stopped development on it and it is maintained as a community open source project. If you search on
SourceForge for Jambi, you will find their information.
Jambi provides five different libraries.

Jambi for Linux 32 bit

Jambi for Linux 64 bit

Jambi for Windows 32 bit

Jambi for Windows 64 bit

Jambi for OS-X

Page 35 of 44

While Java is platform independent, the Jambi libraries contain system specific modules. This means
that you must be careful when building NixNote to ensure you have the correct libraries. I do not have
the libraries uploaded to Sourceforge in the NixNote repository. I didn't add them mainly because they
are large and you'll only need one of the five available anyway.
The version of Qt Jambi that is used is 4.5.0. This is the last stable version released by Nokia. I do not
believe earlier versions will work since I rely on using Javascript in the editor to call back to QT methods
and I don't believe this was added until version 4.5. I have used Jambi 4.6 and have not run into any
problems on Linux. I know some other people have used them without running into troubles either. On
Windows they behaved oddly. Since I didn't wanted to keep all of the platforms on the same level I
didn't upgrade to 4.6. When a 4.7 stable version is released I plan on trying it.

Database
NixNote uses H2 as the back end database. There are actually three separate databases to try and keep
NixNote a little more responsive. All databases are found in the ~/.nevernote/db directory.
The first database is the NixNote database itself. This contains all notes, notebooks, saved searches,
tags, and synchronization information. It also contains some tables to help speed up saving notes (this
will be discussed later in the Saving a note section.
The second database is the Resources database. This only has one table. It contains the resources for a
note (images & attachments). This information was separated from the NixNote database to try and
increase speed.
The third database is the Words database. This contains all of the indexed words that NixNote findes in
a document. This can be quite large and have a lot of IO when it is initially created. It was separated out
for a few different reasons.
The first reason is that if it becomes corrupt, you can just delete that database and start NixNote. If it
doesn't exsit NixNote will create it. You can then go into the Tools menu option and reindex the entire
database. Before this, when the database became corrupted you would delete everything and start
over.
The second reason it is in a separate database is because when NixNote is indexing it will write lots of
data into it. This causes additional overhead and can slow down or cause problems with users as they
are creating notes.
When NixNote starts, it accesses the database in embedded mode. This means that it does not use
TCP/IP for communication and there is no server daemon running. According to the documentation this
speeds up processing, but it also means that only one JVM can accesss the database at a time. If
multiple JVMs try to access it you will get an error. Multiple threads within the same JVM can access the
same database with no problems.
Whenever you connect to H2, H2 will start multiple threads to handle database activity. NixNote
doesn't control these threads.
Page 36 of 44

Evernote data
Each note, resource, saved search, notebook and tag have a global unique identifier (GUID) assigned to
them and they have a sequence count. The GUID is unique among all Evernote accounts, so there
should not be any duplicates.
The synchronization number indicates the current version of the note. When a note is updated on
Evernote's servers it gets a higher sequence number. This sequence number is assigned by Evernote
(not NixNote). A sequence number is unique within a users account, so no two GUIDs will have the
same sequence number. A note which has a sequence number of 1, when synchronized, may next have
a sequence number of 243.
This sequence number is used to indicate the position at which you last synchronized. When starting a
sync, you pass the highest number you've ever received and it will give you data starting from that point.

Threads
NixNote has several threads of its own that it uses for processing.
The first thread to start is the main (or NixNote) thread. This is the master thread that controls most
other threads. There is a restriction that no Widgets (pretty much anything GUI) can exist outside the
main thread. This means that any fields that are presented to the user and any updates the user make
must pass through this main thread. Doing something foolish in this thread can really hurt performance.
This main thread spawns several other threads:

SyncRunner thread

IndexRunner thread

SaveRunner thread

ThumbnailRunner thread.

Three CounterRunner threads

Communication to all threads is handled in two ways.

The first method is by passing methods over a blocking linked list queue. The main thread posts actions
into this thread and (when it does) the other client thread will become unblocked and begin doing work.
If there is no work for the thread it tries to read an entry from the queue and becomes blocked until a
request is made.
The second method of communication is via the Signal API in Qt. Qt permits signals to be emitted and a
client in another thread can receive them. This is how the child threads communicate their status back
to the main thread in most instances.

Page 37 of 44

Threads should remain active for the life of the program. A timer will wake up every minute and check
that the threads are alive. If a thread is not alive it will show a warning to the user and recommend that
the program be restarted.
SyncRunner thread and synchronization processing
The SyncRunner thread handles most of the interaction with Evernote. It is the process that deals with
synchronizing any notes and resolving any conflicts. Most of the time this thread is asleep and will wake
up when the synchronization timer has expired, or when the user clicks the synchronization button to do
a manual sync. If the SyncRunner encounteres a problem it will post an error message back to the main
thread and disconnect from Evernote.
When the SyncRunner thread is running, a global flag should be set to indicate a sync is in progress. This
will prevent the ThumbnailRunner and IndexRunner threads from running. The logic is that they
shouldn't waste CPU doing work for a note that may change in a few moments.
The SyncRunner thread goes through some interesting logic to handle everything. This is a rough
overview of the flow.
The first thing it does is it tries to validate your userid & password with Evernote. Assuming that is
successful, it continues. If it isn't successful it is done and the thread waits for the next request.
The next thing it does is to get the User's account information. This is used to determine if a user is a
premium member, their Evernote email address, and their quota usage.
The next information it retrieves is from Evernote is the sync status of your account. This will give you
the highest sequence number on your account that Evernote is aware of. If this count is higher than
yours then you need to get data from Evernote. If this number is the same as yours then you don't need
to download any data.
The sync status also contains a date. This date is a drop dead date. If the last time you synchronized is
before this date, then Evernote no longer has the individual changes you need to synchronize. If you are
in this state, you will need to do a full synchronization.
If you need to get information from Evernote, the first thing you tell it is the highest sequence number
you received in the past. This tells Evernote where to begin sending data. Evernote sends data an
chunks. These chunks can be any size, but I do about 10 records per chunk. There isn't any reason, it
just felt like a good round number.
A chunk of data contains any items (notes, resources, tags, notebooks & saved searches) which have
changed. It contains records indicating deleted records a well as new & changed records. A chunk also
contains the highest sequence number in that chunk. This sequence number is changed so we know
where to begin the the next time we get data.
Notebooks, saved searches, and tags are pretty straight forward. Any change from Evernote will be
added or updated. If there is a conflict, Evernote wins. For example, if you renamed a notebook on the

Page 38 of 44

web interface and you edited it on NixNote, the Evernote name will win and you'll lose the NixNote
change.
Note changes are a bit different, since we need to deal with potential conflicts.
If a note hasn't been changed locally, but it was changed remotely then we just update the note in the
database, flag it to be reindexed, and move to the next note.
If there is a conflict (a note has been changed locally and on Evernote) then we have a conflict. In this
case, the note that was changed in NixNote is given a new GUID by NixNote. It is then moved to a local
notebook called Conflicts. If a Conflicts notebook doesn't exist, it creates one and moves the note
into it. It is then the users responsibility to decide what to do with the conflicts. If the user simply
moves the note from the conflicts notebook back into a synchronized notebook, it is treated as a new
note and will get a new GUID.
The next part of a sync is to look at what has changed locally. When a note, notebook, saved search, or
tag is changed NixNote flags that note as dirty. Dirty items are items that need to be synchronized.
NixNote goes through its database looking for any records which are flagged as dirty. Those records
are then sent to Evernote. When the note is sent, Evernote will send back a new sequence number for
that record. That sequence number is saved back with the note. If it is a new record, the GUID will
change as well, so any references to that GUID need to be updated.
The tricky part about sending changes to Evernote are tags. Before a new child tag can be created, its
parent tag needs to exist at Evernote.
For instance, if I were to create TAG1 & TAG2 and set TAG2 as a child to TAG1, neither tag has a valid
Evernote GUID so, when I synchronize, I need to be sure to synchronize TAG1 first, get the new GUID,
update the parent GUID for TAG2, then finally synchronize TAG2. If there is an error with TAG1 and it
can't be synchronized, then TAG2 will not be synchronized either. Most of this is accomplished with lists
to keep track of what tags are ready to be synchronized.
Finally, the last thing the synchronization process does is to synchronize linked notebooks. This is
essentially the same as synchronizing your own account as described above, except you go against the
notebook owner's shard. The other major difference is that changes to tags & notebooks in linked
notebooks are not synchronized (you can't update another person's notebooks or tags). This is an
Evernote restriction. NixNote will let you change them, but that change is only on that system and it
isn't synchronized. Tags & notebooks are stored a little differently in the database to denote that they
are linked instead of tags you created.
Each linked notebook is a different sync. If you have 10 linked notebooks, the sync process is run against
each notebook individually. The initial sync of a linked notebook seems to be very slow. It looks like it
sends the data in chunks (the same as synchronizing your account the first time), but it will send empty
chunks if you are not authorized for any data in that particular chunk. For example, if I can receive a
chunk that contains nothing.

Page 39 of 44

IndexRunner Thread
NixNote maintains a separate database for searching. Adding words to this database is handled by the
IndexRunner thread.
The first thing the IndexRunner will do is to determine if any notes need to be indexed and it will parse
them and add individual words to the database. Note resources are not done at the same time as the
contents of a note.
Once all notes are done it will index note resources (attachments and OCR data). The OCR data is
received from Evernote and is in XML format. Once the OCR data is added it will then handle indexing
ather attachments.
SaveRunner Thread
Saving a note can be a slow process, so it is handled via another thread. When a note is modified by a
user, the changes are saved when:
1.) The save interval timer expires.
2.) A user switches to another note
3.) The program shuts down
User changes are saved via the SaveRunner thread. Its purpose is to convert the document from HTML
to XML, validate the XML matches Evernote's Markup Language format (ENML) and to save any
attachments or images.
Notes are saved in a three step process.
The first step cleans up the HTML and converts it to XML. This is normally done via JTIDY to do the
converting & cleanup. If JTIDY cannot process the note there is an backup process that will try to
cleanup the note. This backup process is very slow but it is useful if a note is very badly formatted.
The second step is to remove anything that doesn't validate against ENML. This second process uses a
database of invalid XML elements that it has seen in the past. Those invalid XML elements & attributes
are removed prior to going to the third step. The most efficient way to remove an invalid element or
attribute is in this step.
The third step is the actual XML validation of ENML. If everything goes well, this is a very fast step. If it
encounters an invalid XML element or attribute it will remove. This step is less efficient than the other
step and is much slower. To avoid doing this constantly, it saves any newly discovered elements &
attributes to the database so the next time step 2 sees them it can remove them.
Changes to a note are handled by the SaveRunner thread, but the main GUI thread also maintains a
cache of notes which have been viewed or edited since the program has started. This is done to speed
up viewing and to eliminate problems where a note hasn't been saved prior to being viewed (or you
might get an old copy of a note).

Page 40 of 44

ThumbnailRunner Thread
The ThumbnailRunner thread is responsible for generating GUI images of each note that can be viewed
in the note list. This can be disabled in the Edit/Preferences dialog in the Debugging section.
The ThumbnailRunner thread does a lot of the work of generating thumbnails, but due to Qt Jambi
restrictions some of the work is still handled by the main thread. This can cause some overhead slow
response.
This thread is also disabled when synchronizing since a note might be updated and require a new
thumbnail. It is also disabled when indexing to reduce program overhead.
Counter Threads
The notebook, tag, & trash lists in the GUI maintain a count of notes. The actual counting, however, is
done in a separate thread to improve user performance. One thread counts notebooks, one counts
tags, & the other counts notes in the trash. All three of these threads use the same threads and are
pretty similar in their function.
Once a count is complete, the total is passed back to the main thread via signals. If a thread is counting
and another count request comes in, the existing count is canceled and the counting is restarted. For
example, if it is counting and you switch notebooks a new count is ordered and the existing count is
aborted. This is done to prevent meaningless counts and improve user responses.

Page 41 of 44

Program Directory Hierarchy

The NixNote GIT repository contains the following hierarchy:
src All Java source code.
images HTML images used when displaying notes. File attachment icons and other sample icons are
stored here. For file attachments, the PNG name determines what is displayed. For example, files
ending in mov will use mov.png and files ending in mp3 will use mp3.png. If a file doesn't have an icon it
will use default.png.
lib Third party jar files.
package_scripts Scripts used when releasing a new version of NixNote. It basically takes the jar files
and source libraries and creates the rpm, deb, or gzip files. Windows & OS-X packages are created by
Install Builder and are not included.
qss Used for Qt style sheets. These permit the user to customize how NixNote appears.
spell Spell check dictionaries.
translations Used to translate NixNote into different languages.
xml Used to store enml2.dtd. This is used to validate any new note to match Evernote's restrictions.
NixNote keeps a local copy in case a network isn't available when a note is created.

Page 42 of 44

Java Class Hierarchy

NixNote code is stored in the following hierarchy:
cx.fbn.nevernote High level entry point. This directory contains NixNote.java (the main program
entry point and Global.java (used for global variables).
cx.fbn.nevernote.config This level contains utility functions like determining program location
directories and cleaning up temporary files.
cx.fbn.nevernote.dialog This level contains user dialog boxes. Any popup dialog box is defined here.
cx.fbn.nevernote.evernote This level contains some Evernote specific utilities. Things like ENML
conversion and encryption algorithms for notes are handled here.
cx.fbn.nevernote.filters This level contains classes used to filter a list of notes and contains classes
used when counting notes for tags & notebooks.
cx.fbn.nevernote.gui This contains most of the GUI classes used (other than those defined in
NixNote.java). Customized Jambi classes are modified here.
cx.fbn.nevernote.gui.controls This contains classes used to display the user account information when
clicking on the quota bar.
cx.fbn.nevernote.icons This contains images used throughout NixNote. The toolbar, window, &
pushbutton icons are stored here. This does NOT contain every image used. Some images are stored in
the images directory and are used for the images displayed in notes.
cx.fbn.neveronote.signals These classes contain signals used between various threads.
cx.fbn.nevernote.sql These clasess deal with SQL functions relating to H2.
cx.fbn.nevernote.sql.driver A generic SQLQuery function. This is mainly used as an abstraction layer
between H2 and NixNote. Initially NixNote used SQLite but later moved to H2. This class helped keep
an abstraction and removed the need to rewrite the SQL calls.
cx.fbn.nevernote.threads Thread classes used throughout NixNote to offload work to the non-gui
thread.
cx.fbn.nevernote.utillities Various utility functions. Things like list management, file utilities, and
password encryption are store here.
cx.fbn.nevernote.xml XML formatting utilities.

Page 43 of 44

Third Party Libraries

NixNote uses a lot of third party libraries to perform various functions. These libraries are:

Evernote & Thrift libraries Used for communications & data structures with Evernote servers.

H2 Database Engine The primary SQL database.

POI, PDFBox, & Tika libraries These are used to provide parsing of RTF, PDF, MS Office, & ODF
file formats. This is done to allow NixNote to index attachments.

Jazzy Used as the spell check engine.

Apache Commons HTML Libraries Used for various HTML related functions.

Jtidy Used to cleanup HTML code prior to it being converted to XML.

Page 44 of 44