Version 0.2
Xournal is an application for notetaking, sketching, keeping a journal using a stylus. It is free software (GNU GPL) and runs on Linux (recent distributions) and other GTK+/Gnome platforms. It is similar to Microsoft Windows Journal or to other alternatives such as Jarnal and Gournal.
Xournal can be downloaded at http://math.mit.edu/~auroux/software/xournal/
Xournal aims to provide superior graphical quality (subpixel resolution) and overall functionality; however it lacks the collaborative features of Jarnal. Since Xournal is still in its early development stages, it may not be fully stable, and some features have not been implemented yet.
Xournal's user interface is (hopefully) intuitive, and if you don't run
into installation or
tablet calibration issues, you'll
probably be able to start taking notes without referring to this manual.
Here is a screenshot of the user interface (click to enlarge):
Refer the next few sections of this manual for more information about the various functionalities.
The penThe pen is the default drawing tool in Xournal. It comes in a variety of colors (see the color toolbar buttons and the Color submenu of the Tools menu) and thicknesses (see the thickness toolbar buttons and the Pen Options submenu of the Tools menu).
The eraser
The eraser lets you erase what you have drawn. If your tablet's stylus
has an eraser tip, and if the XInput extensions are enabled, the eraser
will be automatically selected when drawing with the eraser tip.
Another possibility is to enable the "Emulate Eraser" option in the Options
menu, which lets you use button 2 or 3 on the stylus (mouse middle or right button)
as an eraser.
The eraser comes in three different thicknesses (selected using the
thickness toolbar buttons),
and can operate in three different modes (Eraser Options submenu of
the Tools menu):
The highlighterLike the pen, the highlighter comes in a variety of colors (the default is yellow) and thicknesses. Use the color and thickness toolbar buttons to change these settings.
The rulerThe ruler is not a tool by itself, but rather a special operating mode of the pen and highlighter tools. When it is enabled, these tools paint line segments instead of curvy strokes. For simplicity, selecting the ruler when not in pen or highlighter mode automatically selects the pen.
Default tools
Each drawing tool (pen, eraser, highlighter) has a default setting
(color, thickness, ...) associated to it.
The "Default Pen", "Default Eraser", and "Default Highlighter" entries of
the Tools menu select the appropriate tool and reset its settings to
the defaults. The toolbar also includes a "Default" button which
resets the currently selected drawing tool to its default settings,
and a "Default Pen" button.
The "Set As Default" entry of the Tools menu takes the current settings
of the currently selected drawing tool and makes them the new default.
Thickness buttonsThese three buttons control the thickness of the current drawing tool (pen, eraser, or highlighter). The thickness can also be adjusted using the appropriate sub-menu of the Tools menu.
Rectangle selectionThis tool lets you select a rectangular region of the current layer. All the strokes which are entirely contained within the rectangular region are selected. The selection can be moved within its page by clicking inside the selection rectangle and dragging the cursor.
The selection can be cut, duplicated, etc. (including to a different page or to a different journal) using the copy-paste toolbar buttons or the corresponding entries of the Edit menu.
Vertical spaceThis tool lets you insert or remove vertical space within the page: all the items of the current layer which lie entirely between the cursor position and the end of the page are moved up or down.
Note that the background, and items on other layers, are not affected. Also, if you insert too much vertical space, some items may fall below the bottom of the page and become invisible. These items are not lost: to retrieve them, either use the vertical space tool again to remove the excess vertical space, or change the page height to an appropriate value (using the "Paper Size" entry in the Journal menu).
All operations performed on the currently open journal (drawing, erasing,
cut-and-paste; adding, deleting, and reformatting pages; etc.) can be
undone and redone at will using the Undo and Redo toolbar buttons or
the corresponding entries in the Edit menu.
There is no limit to the depth of the undo/redo stack. It is cleared only
when you quit the application or open a new journal.
A journal is composed of one or more pages, whose characteristics can be
modified independently of each other. Each page consists of a background
and one or more layers stacked on top of the background. All drawing
operations take place within a single layer, and do not affect the background
or the other layers. You can think of the layers as transparent overlays:
drawing and erasing always takes place on the topmost visible overlay.
Layers are a convenient mechanism to add temporary annotations on top of a
journal page: because of the logical separation between layers, erasing
in the top layer will not affect the contents of the other layers, and
the top layer can be easily discarded.
The user interface either displays all pages in the journal below each other ("continuous mode") or a single page ("one-page mode"). You can switch between the two modes by using the "Continuous" and "One page" entries in the View menu. The default is the continuous mode, best adapted to note-taking on multiple pages. The one-page mode is more appropriate if your journal is a scrapbook in which the pages have different characteristics (in particular, if you are annotating a series of pictures of different sizes).
You can navigate the journal pages in several different ways:
Note: jumping to a page automatically selects the top-most layer in that page.
To navigate the layers of a page, either use the layer selection box at the bottom of the Xournal window, or use the "Show Layer" and "Hide Layer" entries in the View menu. The basic rule to remember is that the display shows all the layers underneath the currently select one, and while those above it are hidden.
Note: the background layer cannot be drawn on; any attempt to draw on the background will generate an error message and switch back to the first layer.
Pages can be added to the journal by using the "New Page ..." entries in the Journal menu. The newly created page has the same format and background as the current page (for the "New Page Before" and "New Page After" commands), or as the last page of the journal (for "New Page At End"). Additionally, jumping to the next page when already on the last page creates a new page at the end of the journal.
The "Delete Page" entry in the Journal menu removes the current page from the journal. (Remember that you can always undo this operation if you deleted a page by accident).
The "New Layer" entry in the Journal menu creates a new layer immediately above the current one, while "Delete Layer" removes the current layer and its contents (if you attempt to delete the only layer of a page, a new empty layer will be automatically created).
The size of the current page can be modified using the "Paper Size" entry in the Journal menu. Standard and custom sizes are available.
The background is either one of several kinds of standard paper types, or a bitmap image, or a page of a PDF file.
To select a standard paper type as background for the current page, use the "Paper Style" submenu of the Journal menu. The paper color can also be changed using the "Paper Color" submenu of the Journal menu.
To use a PDF file as the background for a journal, see the paragraph on PDF annotation below.
To load a bitmap image file for use as background for the current page, use the "Load Background" entry of the Journal menu. This automatically resizes the current page according to the size of the bitmap image, and resets the zoom level to 100%. If ghostscript is installed on your system, you can also use this method to import a fixed-resolution bitmap version of a Postscript or PDF file; in that case, all pages will be imported sequentially as backgrounds into consecutive pages (this is not the recommended method; PDF annotation is better in many respects).
To capture a screenshot of a window or the entire screen and make it the background of the current page, use the "Background Screenshot" entry of the Journal menu. This will iconify the Xournal window; click in any window (after ensuring it is fully visible) to capture its contents, or click on the desktop (or screen background) to capture the entire screen.
Important note: by default, bitmap images loaded using the "Load
Background" command will not be saved with the journal; instead, the journal
file will contain a reference to the absolute location of the image file.
This means that the background will become unavailable if the image file
is moved or deleted. To avoid this, check the option "Attach file to the
journal" at the bottom of the file selection dialog box.
This option only applies to bitmap image files loaded from disk;
screenshot backgrounds (and bitmaps converted from PS/PDF files using
ghostscript) are automatically "attached" to the journal file: when the
journal is saved, they will be saved (in PNG format) along with it
(using file names of the form *.xoj.bg_*.png).
Rescaling and anti-aliasing: by default,
bitmap backgrounds are rescaled and anti-aliased as needed when the zoom
level is changed, to ensure their appearance always remains acceptable.
Because this consumes a lot of memory and CPU resources, by default this
rescaling is performed on-demand as each page becomes visible. This means
that you will occasionally notice bitmap backgrounds being smoothed while
you are scrolling inside the document (at large zoom levels, this can slow
down the screen refresh rate noticeably). If you'd prefer all backgrounds to
be rescaled immediately upon changing the zoom level (slower but maybe more
intuitive), disable the "Progressive Backgrounds" option in the Options
menu.
If you are handling large bitmaps, you can save memory and CPU resources (at the
expense of quality) by disabling the "Antialiased Bitmaps" option in the Options menu.
Xournal can be used to annotate PDF files, by loading the pages of a PDF file as backgrounds for a journal. This feature requires the pdftoppm converter to be installed (this is part of the xpdf PDF file viewer).
The "Annotate PDF" command in the File menu can be used to load a PDF file into a new (empty) journal. The page backgrounds and page sizes correspond to the contents of the PDF file. (Most unencrypted PDF files should be supported).
By default, the PDF file used to generate the backgrounds will not be saved with the journal; instead, the journal file will contain a reference to the absolute location of this file. This means that all backgrounds will become unavailable if the PDF file is moved or deleted (although Xournal will let you specify the updated location of the PDF file when opening the journal file). To avoid this, check the option "Attach file to the journal" at the bottom of the dialog box when opening the PDF file. The PDF file will then be saved along with the journal (using a file name of the form *.xoj.bg.pdf).
Upon zooming, the page backgrounds are asynchronously updated to fit the current display resolution. Since this process is quite slow and memory-intensive, the pages are normally updated only as needed, when they become visible on the screen (unless you disable the "Progressive Backgrounds" option in the Options menu). This means that you will occasionally notice the page backgrounds being updated while you are scrolling inside the document (at large zoom levels, it can take a while for the updated background to appear). However, since the backgrounds are generated asynchronously by a separate Unix process, you can keep drawing in the journal while the update process is still in progress.
It is strongly recommended that you do not resize PDF pages (using the "Paper Size" command). This will result in extremely ugly rendering, as the PDF converter is unable to render bitmaps with non-standard aspect ratios.
While you can perform all sorts of page operations on a journal file that was created from a PDF file (such as duplicating or deleting pages, inserting pages with blank or bitmapped backgrounds, ...), it is not possible to include pages from more than one PDF file into a single journal document. If you need to annotate two or more PDF files inside a same journal document, please consider using an external utility for merging PDF files (for example pdfmerge).
Xournal uses the gnome-print architecture for printing. While it is very powerful, some aspects of the API leave to be desired, and future versions of Xournal will probably also include a native Postscript/PDF printing feature.
The "Printer" tab of the print dialog box lets you select a printer (either one of the printers installed on your system, or the generic Postscript printer, or the PDF virtual printer). The "Job" tab lets you select a range of pages to print (the default is to print the entire journal). The "Paper" tab lets you select the paper size. Each page of the journal is automatically rescaled so as to fit the paper size. (minus a 5% margin all around).
The settings are currently not saved properly from one print job to the next, so make sure to select the appropriate printer and verify the paper size. When printing to a file (Postscript or PDF), Xournal attempts to pre-fill the output file name (for the Postscript driver this often fails due to gnome-print API issues).
The "Print to PDF" entry of the File menu directly generates a PDF file using the PDF virtual printer, without bringing up the dialog box (the page size is the default one for that printer, usually A4). Note that the PDF virtual printer produces files that are very large and far from optimal, so in the current state of things it is better to generate a Postscript file and use a converter such as ps2pdf.
The gnome-print architecture also forces page backgrounds (bitmaps and PDF) to be generated as uncompressed bitmaps, which leads to gigantic print job files. An alternative to gnome-print will be implemented in a future release of Xournal.
Xournal is written by Denis Auroux
(auroux@math.mit.edu).
It is distributed under the GNU General Public License.
Feel free to contact me with bug reports and suggestions; I apologize in advance if I am unable to respond properly to some requests. List of known bugs/misfeatures (no need to report them again):
Version 0.2 (January 29, 2006):
Version 0.1.1 (January 5, 2006):
Version 0.1 (January 2, 2006): initial release.
Features yet to be implemented:
XOJ files are gzipped XML-like files. A more precise documentation of the file format will be added at a later date. Meanwhile, most of the format should be easy to figure out by trial-and-error or by looking at the source; if some details are unclear, feel free to ask.
The following libraries are required to run Xournal (they are standard on modern Linux distributions such as Fedora Core 3 or later, or RHEL 4 or later):
Additionally:
To compile Xournal, you also need the development packages for the above libraries (packages gtk2-devel, libgnomecanvas-devel, libgnomeprint22-devel, libgnomeprintui22-devel, and dependencies), as well as autoconf and automake.
Download the Xournal distribution tar.gz file, and any needed dependencies.
Binary installation in /usr/local:
Run (as root) the installer script
./install-binary(and upgrade GTK+ and the other libraries if needed).
Binary installation in home directory:
Run (as any user) the installer script
./install-binary(and hope that the required libraries are installed on your system).
Compilation and installation in /usr/local:
./autogen.sh make (as root) make install
Compilation and installation in $HOME:
./autogen.sh ./configure --prefix=$HOME make make install
Configure error message:
If autogen.sh generates the error message
configure: error: Library requirements (gtk+-2.0 >= 2.4.0 libgnomecanvas-2.0 >= 2.4.0 libgnomeprintui-2.2 >= 2.0.0) not met
even though you have sufficiently recent versions of these libraries on your
system, then you need to install some missing development packages.
Configuring the tablet devices properly is unfortunately not as simple as it ought to be. This is a subject worthy of a detailed how-to document; meanwhile, here are some hints about how to configure your tablet.
Xournal uses the XInput extension to obtain high-resolution coordinates for strokes drawn using the stylus. If you decide that getting just the right XInput configuration isn't worth the effort, you can disable XInput features by unsetting the "Use XInput" option in the Options menu. The price to pay is a lower graphics quality, as the resolution of all strokes then drops to 1 pixel (instead of the native resolution of the tablet device, which can be higher by several orders of magnitude).
The configuration of tablet devices is controlled in the X server's configuration file (usually XF86Config or xorg.conf depending on your distribution). The ServerLayout section should contain lines like:
Section "ServerLayout"
...
InputDevice "cursor" "SendCoreEvents"
InputDevice "stylus" "SendCoreEvents"
InputDevice "eraser" "SendCoreEvents"
EndSection
(the last one only if your stylus has an eraser tip), and your configuration
file should include sections such as
Section "InputDevice"
Identifier "cursor"
Driver "wacom"
Option "Device" "/dev/ttyS0"
Option "Type" "cursor"
Option "ForceDevice" "ISDV4"
Option "BottomX" "28800"
Option "BottomY" "21760"
Option "Mode" "absolute"
EndSection
Section "InputDevice"
Identifier "stylus"
Driver "wacom"
Option "Device" "/dev/ttyS0"
Option "Type" "stylus"
Option "ForceDevice" "ISDV4"
Option "BottomX" "28800"
Option "BottomY" "21760"
Option "Mode" "absolute"
EndSection
Section "InputDevice"
Identifier "eraser"
Driver "wacom"
Option "Device" "/dev/ttyS0"
Option "Type" "eraser"
Option "ForceDevice" "ISDV4"
Option "BottomX" "28800"
Option "BottomY" "21760"
Option "Mode" "absolute"
EndSection
The actual settings will depend on your hardware; look on the web for Linux
installation instructions specific to your model: for example, the
"Device" settings above correspond to a serial port protocol, many tablets
use USB instead; the BottomX and BottomY values correspond to the physical
resolution of the tablet and will vary from one model to another.
If the mouse pointer does not follow accurately the position of the stylus, this is an indication that your tablet is not properly calibrated. If you have the linuxwacom package, you can try modifying the tablet calibration using xsetwacom. The relevant parameters are named TopX, BottomX, TopY, BottomY, and need to be set separately for the stylus and for the eraser. For example:
xsetwacom set stylus TopX 270
xsetwacom set stylus BottomX 28510
...
(the TopX and TopY parameters default to 0 if you haven't set them in your
X server's configuration file). Experiment with these parameters until you
find the right calibration settings for your tablet (i.e., the mouse pointer
appears right under the tip of the stylus).
Once you have found the perfect settings for your tablet, update your X server's configuration file (due to issues with some versions of the linuxwacom driver, the tablet calibration information is often not updated properly when using xsetwacom).
Important: due to issues with the linuxwacom driver, it is important to either upgrade your driver to a patched version, or restrict your choice of settings as follows:
This is due to misfeatures in the linuxwacom driver. Typically, this will happen in all of the following cases:
I have also had a report that one of the workarounds used by Xournal to bypass a calibration bug in GTK+ can actually entirely prevent strokes from being drawn. If you are being unsuccessful at drawing in Xournal with XInput enabled, try recompiling after changing the first line of src/main.c to
#define ENABLE_XINPUT_BUGFIX 0If this modification does improve things for you, and if you have a bit of spare time to help investigate the causes of this problem, please contact me.
You need an X server that supports the RANDR extension, and a patched version of the linuxwacom driver to support on-the-fly rotation.
To set the tablet in portrait mode:
xrandr -o 3 xsetwacom set stylus Rotate cwTo return to landscape mode:
xrandr -o 0 xsetwacom set stylus Rotate noneNote: you should not rotate the display while Xournal is running, otherwise the tablet calibration in Xournal may (and most likely will) become incorrect. Exit Xournal and restart it after the display has been rotated.
This patch fixes rotation and calibration issues with the linuxwacom driver version 0.7.0.