Brendan Kidwell
4 Dec 2013
Copyright © 2013 Brendan Kidwell.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License”.
I am a free and open source developer living in New York City, but I’m originally from Boston. I have a day job working remotely for the IT department Abt Associates Inc., which is a global policy research consulting form working in health, social and economic policy, and international development.
Except for my day job, I use various server and desktop versions of Linux on all my computers. My main desktop at the moment runs Linux Mint 16 with MATE desktop environment. Some major apps I use all the time include:
We all need to take notes on our computers, and with all the work that we naturally do “online”, it’s tempting to use a cloud service or a cloud application to store all of our private informal notes. Services like Microsoft OneNote and EverNote provide online storage of your notebooks with excellent front-ends that make writing, reading, and searching your notes simple.
But what kind of control do you have over all that private data stored online? Usually very little. You have token access controls that prevent the general public from reading your notes, but you have no guarantee that these controls will never fail — you have no way to inspect the server environment to validate its security. Additionally, your vendor, their advertizing partners, and the government are all likely to look at that data and do things with it that are not in your interest. Richard Stallman from the Free Software Foundation has written about these issues. See this Guardian article, for example: Cloud computing is a trap, warns GNU founder Richard Stallman.
My default security posture in all my computing work is to share as little as possible with remote systems over which I have no control. So that leads to private note-taking applications like Zim on my desktop and privately-controlled file sharing schemes such as those I will demonstrate in this guide.
Zim tries to be a platform-agnostic application, compatible with any modern desktop operating system, but when you do complicated things with Zim, sometimes you are using it in concert with other applications and systems. For the sake of simplicity, I will mostly assume you are using an Ubuntu-based operating system such as Ubuntu, Kubuntu, or Linux Mint. Where I can comment on differences with other OSes, I will.
If you are using Windows, you may end up installing some external tools to support functions of some Zim plugins. For example, you might want to use LaTeX via Zim’s Insert Equation plugin.
Even after you’ve installed the external tool, Zim might still say that the commands provided by the tool aren’t found. That might be because Zim didn’t find the commands in folders listed in your system’s PATH environment variable. To resolve that:
C:\Program Files or C:\Program Files (x86) . Copy the path of the folder to the clipboard.;).Install the package called zim using your desktop’s package manager. Then you should see a new entry “Zim Desktop Wiki” in your desktop’s application menu under “Accessories” or “Utilities” or some other name, depending on your desktop. You can also launch Zim from your desktop’s Run command by executing the command
zimIf your operating system doesn’t have a built-in package for Zim, you can get the source code as a tarball from the Download page on Zim’s web site.
Zim is under active development and your operating system’s default repositories may include an older version of Zim. If you are using an Ubuntu-derived operating system, you can run the following commands in a Terminal to install the latest package directly from the Zim project:
sudo add-apt-repository ppa:jaap.karssenberg/zim
sudo apt-get update
sudo apt-get install zimIf you do not have access to the latest version of Zim within your operating system, you can install it from the source code tarball.
See also the official installation instructions.
Make sure you have these packages installed in your system:
You can try out Zim without installing it globally by extracting the source tarball to a folder in your profile such as ~/Apps, and then executing zim.py in that folder.
To install globally, open a command prompt, navigate to the folder were you extracted the tarball, and run
sudo setup.py installThen you should see “Zim Desktop Wiki” in your application menu or you can run the command
zimwith your desktop’s Run command.
Zim is available as a standard installer package and as a portable application (zero global configuration, run from its own folder) from the Zim Desktop Wiki for Windows page on my web site.
The official installation instructions offer some tips on installing Zim in OS X. I have not had a chance to try this.
Notebooks in Zim are just folders that contain Zim pages, attachments, and folders with more Zim pages.
You can create a Notebook using the “Add” command inside the “Open [Another] Notebook” dialog box by pointing to a new folder you just created or opening an existing folder. Any “.txt” files in that folder will be treated as Pages in the Notebook; everything else will be attachments.
By default, Zim shows an Index of all the pages in your notebook in a sidebar on the left side of the window.
To create a new page, you can right-click anywhere in the Index and select “New Page” (for a new top level page) or “New Sub Page” (to create a new child of the selected node). You can also access these commands from the File menu (→ New Page, New Sub Page) or their keyboard shortcuts CTRL+N and CTRL+SHIFT+N.
In the files that make up the Notebook, whenever you create a Sub Page for a page that doesn’t have one, a new folder is created with the same name as the parent Page. If you delete or move all the Sub Pages of a parent Page (and that Page also has no attachments) then the folder to contain Sub Pages is also deleted, automatically.
Another way to navigate pages is the Pathbar — the list of Page names above the Page content pane in Zim.
By default the Pathbar lists the pages you most recently visited, with the current page on the right. Click on one of the entries to navigate to that Page. This is the list you traverse when you use the Go Back (ALT+Left) and Go Forward (ALT+Right) commands.
Alternatively, you can choose History in the Pathbar submenu of the View menu. This is like Recent mode, except every visited node is listed strictly in cronological order from left to right, with repeats when you’ve visited a Page more than once. Think of it as a log file.
You can also choose Namespace mode to show the path of the current Page within the Notebook’s structure.
If you don’t find any of these lists useful, set the Pathbar mode to None.
One of the best features of Zim which is missing in most other wikis is actually a lack of a feature: There are no separate modes for reading and writing pages. There is only the one mode which works equally well for reading and writing.
In the page content frame of the Zim interface, you can use the usual editing conventions to move around in the text, edit the text, and follow hyperlinks.
Zim supports supports some basic text formatting:
Bulleted and numbered lists can have sub-lists inside them. Just use Tab and SHIFT+Tab to indent and unindent list items.
One of the most important features of wikis is the ability to easily insert Links to other topics directly in the context they are needed, instead of relying only on a topic index. Zim allows you to make any selected text in a Page a Link to another Page in the Notebook or to any URL or file outside of the Notebook.
The Insert Link (CTRL+L) command in the Insert menu allows you to insert any kind of link (internal or external). You can type a Page name in the current Notebook in the Link To field and it will help you by autocompleting it.
The “Browse” button in the “Insert Link” dialog box allows you to browse the filesystem interactively to make a link to a local or remote Windows/Samba-shared file.
Zim has a number of differnet formats for Links listed in the Zim Manual for various kinds of relative and absolute links within the current Notebook, and for other resources that are external to the Notebook, but it’s not necessary to memorize these rules up front when you’re learning Zim. Use drag-and-drop for most hyperlinks until you find yourself making a lot of the same kind of Link; then if you want to learn to type the links quicker, right-click on an existing Link and Edit Properties to see what it looks like. Here are the simplest ways for making most kinds of Links:
wp?query → http://en.wikipedia.org/wiki/query .
Whereas Links only make a reference to another Page in the Notebook or some other resource, the Attach File command in the Tools menu make a fresh physical copy of the file you choose as a new file within the Notebook.
As with Sub Pages, Attachments are stored in a folder in the Notebook with the same name as the parent Page of the Attachment.
By default, when you attach and image file, it is displayed inline instead of as a simple Link as other kinds of attachments are rendered. When you right-click on an inline image and click Edit Properties, you are given the opportunity to resize the image. (Changing the size here just changes the display size; it doesn’t change the image file.)
Like any other good text editor, Zim has a command to Find (CTRL+F) or Replace (CTRL+H) text within the current Page. On a long page, the Find command is easiest way to quickly find a section you want to read or edit.
Whereas the Find command looks for keywords on the current Page, the Search command (CTRL+SHIFT+F) will find instances of your keywords on any Page in the current Notebook. Use it to find all the Pages that mention a topic.
Zim is a powerful tool for organizing your thoughts, plans, work notes … pretty much anything that you would want to write down quickly without spending a lot of time formatting or polishing.
In this section I will describe how I use Zim in my daily work. Everything here is only a suggestion to get you started. Zim tries to provide tools and without dictating how you structure your data.
Here is an approximation of what my own personal “Main” Zim Notebook looks like, simplified to show the overall structure:
Most of my notes go under the “Projects” page. Each project gets a Sub Page under “Projects”, and if there are a lot of notes for a project, I’ll make further Sub Pages under the project.
I use “Archive” as a graveyard for old projects that aren’t needed active anymore. This keeps the list of Sub Pages under “Projects” reasonbly short, while I can still look at inactive projects elsewhere if I need to.
“Configuration” is where I put notes about how I’ve set things up
“Tasks” are short-lived pages for things that are smaller than projects and won’t be saved very long after they’ve been completed. For example, the “After Move-In” Page under “Tasks” might contain a LibreOffice spreadsheet (attachment) with a list of things I need buy and do to complete moving into my new apartment.
“Journal” is a catch-all for new bits of information. I have the Journal plugin enabled, which allows you to create a new page called “Journal:yyyy:mm:dd” with the keyboard shortcut ALT+D (“Go to Today”). Some example notes that might get recorded this way would include:
Eventually, you may trim down the Journal notes for some days — deleting bits of data that are no longer needed or moving them to Projects or Tasks.
When you write “[]”, Zim translates that to a checkbox widget. The checkbox has three states: Open, Finished, and Dropped.
Checkboxes can be indented so you can present one checkbox as being a part of a larger Task.
An example of using checkboxes would be for tracking pieces of a project, for example:
Foo Project
[] Define scope
[] Determine requirements
[] User interface mockups
[] User stories
[] Tests
[] Prototype
[] DeliverThe Task List plugin takes the checkbox concept further. It maintains an index of every checkbox in the whole Notebook. Then you can use the View → Task List command to list all the Tasks that aren’t marked Finished with a check mark or Dropped with an X mark.
You can apply due dates to checkbox Tasks by including the date in year-month-day format somewhere in the Task name, preceded by “d:” and enclosed in square brackets. If you had library books due on 13 December 2013 you would write:
[] Return library books [d:2013-12-13]Now with those two above examples written in the Notebook, the Task List dialog box would look like this:
Now if you have a lot of project details in checkboxes as well as major “todo” items outside the scope of projects, you might want to configure Task List as I have, with the switch “Consider all checkboxes as tasks” turned off. You will find that in Edit → Preferences → Plugins → Task List → Configure.
Now you have to put “TODO” in each checkbox line that you want on the Task List, or on a line by itself before each list of Tasks. So, we would rewrite the “library books” Task like this:
TODO:
[] Return library books [d:2013-12-13]
So far, we’ve covered finding information by brute force searching and simply finding it by its hierarchical Page name in the Index, and by viewing open Tasks in the Task List. Zim supports Tags as an alternative way to find and link data. You can use Tags to identify the context or grouping of Tasks.
After you enable the Tags plugin, you can put a tag anywhere in any page by typing “@” followed by letters, digits, and underscores.
Let’s edit the “library books” Tasks on the Tasks page and add a few more to demonstrate:
TODO:
[] Return library books [d:2013-12-13] @errands
[] Buy sandwich bread @errands
[] Mail //JavaScript: The Good Parts// to Steve @errandsAnd we’ll add another Task that’s really a note to followup. Suppose today we lent Python in a Nutshell to Steve and we expect to get it back by next month. We could Go to Today (ALT+D) and write:
TODO:
[] //Python in a Nutshell// (to Steve) [d:2014-01-01] @lent_itemsRemember, your Journal pages can be a catch-all for little notes like this that don’t necessarily belong on other pages.
Now those four tasks look like this in the Task List:
You’ll notice that the Tags pane in the left side of the Task List dialog box lets you filter the list to show only certain Tags.
For better clarity, you can also put tags at the top of a list in the introductory “TODO” line and they will apply to all Tasks in that particular list. You could rewrite the “errands” list like this:
TODO: @errands
[] Return library books [d:2013-12-13]
[] Buy sandwich bread
[] Mail //JavaScript: The Good Parts// to SteveYou can use Tags for other things than Tasks. For example, you could use a Tag to declare that a Page is a set of “meeting notes”:
@meeting_notes
* Alice, Bob, and Carol attended.
* Lorem ipsum dolor sit amet, consectetur adipiscing elit.After you’ve got a lot of Pages tagged like that, you can go to the Tags tab in the Index pane to see a list of all the tags anywhere in the Notebook. If click on a Tag in the list at the top, a list of Pages that include that Tag is shown.
There are more advanced options for the Tasks, Journal, and Tags plugin that aren’t covered in this guide. Look at these plugins Preferences, and read the Zim manual to get more organization ideas.
If you follow David Allen’s famous Getting Things Done time management methodology, you will find a scheme for implementing GTD in Zim, in the Zim manual.
If you’re like me, you probably will want to work with your Zim notebooks across more than one computer. Since Zim stores all its primary data in plain text files and folders (with attachments stored in their native format), any file sharing strategy you would use for individual documents should work fine for a Zim notebook.
There are a few general approaches to file syncing:
The first step in setting up real syncing is enable “Shared” mode. Go to File → Properties and turn on the checkbox called “Shared Notebook”.
This will move the index file and UI state file from ./.zim under the Notebook folder to ~/.cache/zim/$NOTEBOOK-ID (under your desktop profile folder). If you skip this step, your file sync process will unneccesarily copy extra data in those file which is constantly changing and is derived from your primary files anyway.
If you have your own personal server at home or at a hosting provider, ownCloud is one of the best ways to automatically sync files across more than one device. ownCloud is a free and open source web application that provides a space to store your files, and the project includes a desktop file sync tool that works just like proprietary tools like Dropbox and Google Drive.
Setting up an instance of ownCloud is beyond the scope of this guide, so I will assume you’ve already done that. See the ownCloud manual for instructions.
Once you’ve got an ownCloud folder installed on your desktop (on each computer that will use it) all you have to do is move Zim Notebooks into that folder or create new Notebooks there.
The Open Another Notebook dialog box in Zim shows you the path to each notebook in the list. You can use your desktop’s file manager to navigate to that path and move it to the ownCloud folder. Then back in the Open Notebook dialog box, you can remove the defunct path and Add the path to which you moved the Notebook.
ownCloud’s desktop client automatically pushes new changes from your local machine to the central server immediately as you make the changes. It polls the central server for upstream changes from elsewhere in your sharing network once every 30 seconds.
One great side effect of storing your Notebooks in ownCloud is that now you can make small edits to edits to your Notebooks from any web browser! Zim stores Pages in plain text files, and if you navigate to one of those files in the ownCloud web interface, you get a text editor.
There are also non-FOSS IOS and Android clients (priced at $1) that let you edit files on your phone or tablet.
Using a version control tool like Git is a good alternative to automatic file sharing if you don’t want to setup a complicated file sharing application and you also don’t want to use a proprietary service. In fact, you might have a larger project under version control and you want to keep notes in a Zim Notebook in a subfolder of that project.
This section will show you how to setup a Git repository for a Zim Notebook on its own. I assume you have the git packages installed on your desktop and access to a Unix shell account somewhere where you can store your files.
In Zim, use the Open Another Notebook to create and add a folder as a new Notebook. Turn on “Shared” mode and add some Pages.
In a Terminal, navigate to where you want to create your Notebook and create a repository.
$ cd ~/Notebooks/zim-git
$ rm -rf .zim # Make sure the cache files are gone
$ git init
Initialized empty Git repository in /home/brendan/Notebooks/zim-git/.git/
$ git add .
$ git commit -m "First commit"
[master (root-commit) 6268e32] First commit
3 files changed, 28 insertions(+)
create mode 100644 Home.txt
create mode 100644 Page_2.txt
create mode 100644 notebook.zimNow push your new repository to the remote server.
$ ssh brendan@fileserver
$ mkdir -p ~/repos/zim-git.git
$ cd ~/repos/zim-git.git/
$ git init --bare
Initialized empty Git repository in /home/brendan/repos/zim-git.git/
$ exit
$ cd ~/Notebooks/zim-git
$ git push --set-upstream brendan@fileserver:repos/zim-git.git master
Counting objects: 5, done.
Delta compression using up to 3 threads.
Compressing objects: 100% (5/5), done.
Writing objects: 100% (5/5), 578 bytes, done.
Total 5 (delta 1), reused 0 (delta 0)
To brendan@fileserver:repos/zim-git.git
* [new branch] master -> master
Branch master set up to track remote branch master from brendan@fileserver:repos/zim-git.git.Use your normal Git workflows to make commits and push and pull changes between your work computers and the central repository.
Depending on what you store in your Notebooks, it’s a good idea to do regular backups of your data as well. As you can see from the syncing instructions above, backing up notebooks is simple: Just archive or copy the top-level folder of the Notebook (the one with the notebook.zim file in it).
To test your backup, restore it onto another computer or in another folder and open it in Zim or in a file manager and make sure all your data is there.
Take extra care if you habitually make Links from Zim pages to data somewhere else on your computer that you didn’t copy into the Notebook. You will have to back up that data separately!
Zim has a built-in web server that you can use to provide a read-only view of your Notebook for a device you’re not syncing with. To run it, open a Terminal and run Zim with the --server option and the path to your Notebook:
$ zim --server ~/Cloud/fileserver/zim-demoThen open a browser and navigate to http://localhost:8080 .
If you want to, you can even create a start/stop script for it and then add the start script to your crontab file.
You could run this script on a headless server to which you’re already syncing your Notebooks.
Put this in ~/bin/zim-server.sh. (Modify it to have the correct path to your Notebook.)
#!/bin/bash
NAME=Zim
CMD="zim --server ~/Cloud/fileserver/zim-demo/"
PID=""
function get_pid {
PID=`ps -ef|grep "zim --server"|grep -v grep|awk '{ print $2}'`
}
function stop {
get_pid
if [ -z $PID ]; then
echo "$NAME is not running."
exit 1
else
kill $PID
sleep 1
echo "$NAME stopped."
fi
}
function start {
get_pid
if [ -z $PID ]; then
nohup $CMD >/dev/null 2>&1 &
echo "$NAME started."
else
echo "$NAME is already running."
fi
}
function restart {
get_pid
if [ -z $PID ]; then
start
else
stop
start
fi
}
function status {
get_pid
if [ -z $PID ]; then
echo "$NAME is not running."
exit 1
else
echo "$NAME is running."
fi
}
case "$1" in
start)
start
;;
stop)
stop
;;
restart)
restart
;;
status)
status
;;
*)
echo "Usage: $0 {start|stop|restart|status}"
esacThen make it executable.
$ chmod +x ~/bin/zim-server.shNow you can run those scripts to start and stop Zim from the Terminal using zim-server.sh start and zim-server.sh stop, but you don’t have to keep the Terminal open.
If you want the Zim web server to start automatically when you reboot, run
$ crontab -eand add this to the end of the file and save it. (Be sure to put your username in after /home/.)
@reboot /home/brendan/bin/zim-server.sh startZim offers some functions for exporting single Pages or entire Notebooks to HTML, LaTeX, MarkDown, and ReStructuredText. See the Exporting in the manual for general instructions.
" . If I want to export one long Page to start working on it another document format, I usually export to Markdown format and then use Pandoc to make a first pass at converting it to my target format.
Not all Links to web sites from Zim Pages need to be given as a complete URL. Zim keeps a list of shortcuts in a file called urls.list. You can look at the file online in the Zim source code. For example, if you make a Link to wp?Zim (software) then Zim will translate that to http://en.wikipedia.org/wiki/Zim+(software) when you click on it.
I use this feature to link to pages and tickets in my company’s internal instance of FogBugz. To create your own URL shortcut, create a file ~/.local/share/zim/urls.list in your desktop profile:
# Brendan's FogBugz
fb http://fogbugz/default.asp?
# TV Tropes
tvtropes http://tvtropes.org/pmwiki/search_result.php?q=Besides having the ability to attach arbitrary images Zim includes several plugins for creating graphics from source code. They all require you to have their respective applications installed on your system to create new graphics; you can view the rendered graphics on other Zim instances on computers where you don’t have all the external tools installed.
To use any of these plugins, make sure you have the required software installed, and then go to Edit → Preferences → Plugins, and enable the ones you want.
One of the most requested features of Zim is the ability to create inline tables. Unfortunately, the way Zim is built doesn’t allow for easily editing tables within the rich text widget, and allowing for tables would require extensive modifications to Zim.
Two easy workarounds are available. The first workaround is to simply create the table in a spreadsheet such as LibreOffice Calc, and attach it to a Page as you would attach any file.
A more useful workaround is to use the Insert Equation plugin. This allows you to show the table (read-only) inline as an image. You can edit the table like you would any Equation by right-clicking on the image and selecting Edit Equation.
Here is a template for a LaTeX table you can write using the Insert Equation command:
\begin{tabular}{ l l l }
1 & 2 & 3 \\
4 & 5 & 6 \\
7 & 8 & 9 \\
\end{tabular}The first line specifies that the table has three columns, aligned “l”eft, “l”eft, and “l”eft. Then the rest of the lines until \end list three table cells separated by &, and with rows separated by \\.
For more information on LaTeX’s table syntax, see the Tables chapter in the LaTeX WikiBook.
The Quick Note plugin is a convenient command line interface to add pages to a certain area where you want to capture notes from other places. Usage information can be found in the manual.
As a simple example, create a shortcut in your application menu or on your taskbar that runs this command:
zim --plugin quicknote notebook=~/Cloud/fileserver/zim-demo namespace=Inbox input=clipboardWhen you run it, Zim will open a Quick Note dialog box with
~/Cloud/fileserver/zim-demo selected.Click OK to finish creating the Quick Note.
If you enable the Tray Icon plugin, Zim will always display an icon in your desktop’s System Tray that opens a menu of all registered Notebooks, and the Quick Note command (if the Quick Note plugin is enabled).
To always start the Tray Icon when you login, without opening a Notebook right away, create a launcher in your desktop’s automatic-start collection that runs this command:
zim --plugin trayiconThe Line Sorter plugin is easy to overlook, but it comes in handy for me quite often. It add an Edit → Sort Lines command sorts the selected lines of text.
| Key | Action |
|---|---|
| CTRL+Up, CTRL+Down | Previous, next paragraph |
| CTRL+Left, CTRL+Right | Previous, next word |
| Home, End | Start, end of line |
| CTRL+Home, CTRL+End | Start, end of page |
| Enter | Follow a hyperlink |
| ALT+Left, ALT+Right | Previous, next page in navigation history |
| ALT+PageUp, ALT+PageDown | Previous, next page in page index |
| CTRL+J | Jump to Page by name |
| Key | Action |
|---|---|
| SHIFT+[cursor movement] | Select text |
| CTRL+C, CTRL+X, CTRL+V | Copy, cut, paste selected text |
| Enter | Insert a newline (twice for a paragraph) if cursor is not inside a hyperlink |
| SHIFT+Enter | Always insert a newline (twice for a paragraph) |
| Key | Action |
|---|---|
| CTRL+I | Italic |
| CTRL+B | bold |
| CTRL+U | highlight |
| CTRL+K | |
| CTRL+L | Insert hyperlink |
Zim’s manual is well written and has a lot of useful advice in it. Pay particular attention to the Usage and Plugins sections. If you’re inclined to write scripts that create Zim notebooks or pages, be sure to check out the Wiki Syntax section.
Zim also has a publicly shared wiki with Zim tips and tricks hosted on GitHub. If you have anything to contribute, don’t hesitate to registar a GitHub account and edit this wiki.
You can get help with Zim by signing up for the Zim mailing list hosted at Launchpad and also in the chat room #zim-wiki on Freenode IRC network. I’m the host in that chat room and if I’m at my desk I will respond. (Be prepared to wait a while for a response.)
If you find a bug and you’re sure it’s a bug, please report it in the bug tracker on Launchpad. If you’re not sure it’s a bug, post on the mailing list asking for help first.