<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><title>Xournal User's manual</title></head>
<style>
.subtitle {
font-family: Helvetica, Arial, sans-serif;
font-weight: bold;
font-size: 1.3em;
color: rgb(0,150,0);
}
.subsub {
font-family: Helvetica, Arial, sans-serif;
font-weight: bold;
font-size: 1em;
color: rgb(0,150,0);
}
a { color: rgb(0,0,255); text-decoration: none; }
a:hover { text-decoration: underline; }
</style>
<body bgcolor="#ffffff" style="background: rgb(255,255,255)">
<h2 class="subtitle" style="text-align: center; color: rgb(0,0,200)">
Xournal User's Manual
</h2>
<p style="font-size: 0.95em; text-align: center; color: rgb(0,0,0)">
Version 0.4.2.1
</p>
<hr />
<p>
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
<a href="http://www.dklevine.com/general/software/tc1000/jarnal.htm">Jarnal</a>
and <a href="http://www.adebenham.com/gournal/">Gournal</a>.
</p>
<p>
Xournal can be downloaded at
<a href="http://xournal.sourceforge.net/">http://xournal.sourceforge.net/</a> or
<a href="http://math.mit.edu/~auroux/software/xournal/">http://math.mit.edu/~auroux/software/xournal/</a>
</p>
<p>
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.
</p>
<h2 class="subtitle">Table of contents</h2>
<p>
<ul>
<li> <a href="manual.html#getting-started">Getting started</a> </li>
<li> <a href="manual.html#tools">The drawing and selection tools</a> </li>
<li> <a href="manual.html#pages-layers">Pages, layers, and backgrounds</a> </li>
<li> <a href="manual.html#printing">Printing</a> </li>
<li> <a href="manual.html#configuration">Configuration</a> </li>
<li> <a href="manual.html#author">Author information, license, bug-reports</a> </li>
<li> <a href="manual.html#changelog">Version history</a> </li>
<li> <a href="manual.html#file-format">The file format</a> </li>
<li> <a href="manual.html#installation">Installation issues</a> and
<a href="manual.html#calibration">tablet calibration issues</a> </li>
</ul>
</p>
<hr />
<a name="getting-started"></a>
<h2 class="subtitle">Getting started</h2>
<p>
Xournal's user interface is (hopefully) intuitive, and if you don't run
into <a href="manual.html#installation">installation</a> or
<a href="manual.html#calibration">tablet calibration</a> issues, you'll
probably be able to start taking notes without referring to this manual.
<br />
Here is a screenshot of the user interface (click to enlarge):
</p>
<p style="text-align: center">
<a href="screenshot.png">
<img src="screenshot.png" style="width: 321px; height: 176px" />
</a>
</p>
<p>
Refer the next few sections of this manual for more information about
the various functionalities.
</p>
<hr />
<a name="tools"></a>
<h2 class="subtitle">The drawing and selection tools</h2>
<h3 class="subsub"><img src="pixmaps/pencil.png"> The pen</h3>
<p>
The 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
<a href="manual.html#thicknesses">thickness</a> toolbar buttons and
the Pen Options submenu of the Tools menu).
</p>
<h3 class="subsub"><img src="pixmaps/eraser.png"> The eraser</h3>
<p>
The eraser lets you erase what you have drawn.
By default, stylus buttons 2 and 3 (mouse middle or right buttons) are
mapped to the eraser tool.
<br />
The eraser comes in three different thicknesses (selected using the
<a href="manual.html#thicknesses">thickness</a> toolbar buttons),
and can operate in three different modes (Eraser Options submenu of
the Tools menu):
<ul>
<li>
Standard mode (default): the eraser deletes portions
of strokes previously drawn using the pen or the highlighter.
In this mode, if you erase in the middle of a stroke, the remaining
portions of the stroke are automatically split into shorter strokes.
The background of the page (and the lower layers) are not erased.
</li>
<li>
Whiteout: the eraser is actually a thick white pen, and simply covers
whatever lies underneath, including the background of the page.
</li>
<li>
Delete strokes: whenever the eraser comes in contact with a previously
drawn stroke, the entire stroke is deleted.
</li>
</ul>
</p>
<h3 class="subsub"><img src="pixmaps/highlighter.png"> The highlighter</h3>
<p>
Like 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.
</p>
<h3 class="subsub"><img src="pixmaps/text-tool.png"> The text tool</h3>
<p>
To insert a new text item, click at the location where the text is to be
inserted on the page, then type it in or paste it using the contextual
menu (note: no wrapping is performed). To modify a text item, click inside
it. The font and point size can be modified using the "Text Font" command
in the Tools menu (or the toolbar button). The color is the same as that
currently selected for the pen (and can be modified using the toolbar
buttons).
</p>
<p>
Text items can contain arbitrary Unicode characters, provided that a
suitable font is installed on your system. However, languages written
in a direction other than left-to-right might not be handled properly.
If a journal contains some items in a font that is unavailable on your
system, another one will be substituted. (Also, text items will be
lost if the document is opened in a version of Xournal prior to 0.4).
Finally, note that the printing and PDF export features only accept
TrueType and Type 1 scalable fonts (do not use any bitmap fonts), and
that the typesetting of the text may be slightly different in the
printout.
</p>
<h3 class="subsub"><img src="pixmaps/ruler.png"> The ruler</h3>
<p>
The 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.
</p>
<a name="recognizer"></a>
<h3 class="subsub"><img src="pixmaps/shapes.png"> The shape recognizer</h3>
<p>
The shape recognizer is also a special
operating mode of the pen and highlighter tools. When it is enabled,
Xournal attempts to recognize geometric shapes as they are drawn, and
if successful will replace the drawn strokes accordingly. The shapes
that can be recognized are: line segments, circles, rectangles, arrows,
triangles and quadrilaterals. Polygonal shapes can be drawn in a single
stroke or in a sequence of consecutive strokes.
</p>
<p>
The recognizer is set to be as unobtrusive as possible, and should not
interfere too much with handwriting. (It differs in this and other ways
from another shape recognizer written for Xournal by Lukasz Kaiser).
As a result, it may only recognize shapes if you draw them carefully and
deliberately. Specific tips for better recognition: (1) for circles,
a closed curve that isn't quite round works better
than a rounder curve that doesn't close; (2) for arrows, it is better
to lift the pen before drawing the tip of the arrow, and make sure
the tip consists of two straight line segments;
(3) for very elongated rectangles,
recognition tends to be better if you lift the pen between consecutive
sides.
</p>
<h3 class="subsub"><img src="pixmaps/recycled.png"> Default tools</h3>
<p>
Each tool (pen, eraser, highlighter, text) has a default setting
(color, thickness, ... for the drawing tools, font and size for the
text tool) associated to it.
The "Default Pen", "Default Eraser", "Default Highlighter", and
"Default Text" 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 tool to its default settings,
and a "Default Pen" button. <br />
The "Set As Default" entry of the Tools menu takes the current settings
of the currently selected tool and makes them the new default.
</p>
<a name="thicknesses"></a>
<h3 class="subsub"><img src="pixmaps/thin.png"> <img src="pixmaps/medium.png">
<img src="pixmaps/thick.png"> Thickness buttons</h3>
<p>
These 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.
</p>
<h3 class="subsub"><img src="pixmaps/rect-select.png"> Rectangle selection</h3>
<p>
This 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. If the cursor is dragged
to a different page, the selection will be moved to the topmost layer of
that page.
</p>
<p>
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.
</p>
<h3 class="subsub"><img src="pixmaps/stretch.png"> Vertical space</h3>
<p>
This 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.
</p>
<p>
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).
</p>
<p>
If you drag the cursor below the bottom of the page (so that the
entire block being moved has become invisible), the items will be moved
to the next page (topmost layer); however, any items that were already
present on the next page are left unchanged. Similarly, dragging the
cursor above the top of the page so that the entire block being moved
becomes invisible results in the items being moved to the previous page.
</p>
<h3 class="subsub"><img src="pixmaps/hand.png"> Hand tool</h3>
<p>
This tool lets you browse the journal; dragging the cursor scrolls the
view.
</p>
<h3 class="subsub">Undo and redo</h3>
<p>
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.<br />
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.
</p>
<a name="mappings"></a>
<h3 class="subsub">Button mappings</h3>
<p>
Stylus buttons 2 and 3 (mouse middle and right buttons) can be mapped
to different tools using the appropriate submenus in the Options menu
(whereas the Tools menu and the toolbar buttons affect the primary tool
assigned to button 1). The default mapping is the eraser.
</p>
<p><b>Advanced configuration:</b>
if a secondary button is mapped to a drawing tool (pen, eraser, or
highlighter), the default is to "dynamically link" its settings to those
of the primary tool, which means that each drawing tool has common
settings (color, thickness, etc.) for all buttons.
Dynamic linking of brush settings
can be disabled by selecting the "Copy of current brush" option in the
"Button mapping" submenu. The settings of the tool for button 2 or 3 are
copied from the button 1 settings at the time when you select the option,
and afterwards they are no longer updated when the button 1 settings are
modified, thus making it possible to assign pens of different colors or
thicknesses to different buttons.
</p>
<p>
Another option that affects button mappings is the "Eraser tip" option.
If this option is turned on and the XInput extensions are enabled, then
the eraser tip of your tablet's stylus will automatically be remapped to
the eraser tool. This behavior, which overrides all other button mappings,
is most useful if your X server is configured to map the eraser tip of
your tablet's stylus to button 1.
</p>
<hr />
<a name="pages-layers"></a>
<h2 class="subtitle">Pages, layers, and backgrounds</h2>
<p>
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.
<br />
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.
</p>
<h3 class="subsub">Navigating the journal</h3>
<p>
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).
</p>
<p>
You can navigate the journal pages in several different ways:
<ul>
<li> using the navigation toolbar buttons (or the corresponding entries
in the View menu) to go back or forward one page, or to jump to the first
or last page of the journal;
</li>
<li> in continuous mode, scrolling down to the desired page;
</li>
<li> entering a value or using the +/- buttons in the page selection box
at the lower-left corner of the Xournal window.
</li>
</ul>
As a convenient shortcut, going forward one page (or pressing the + button
in the selection box) when already at the end of the journal creates a new
page at the end of the journal.
</p>
<p>
Note: jumping to a page automatically selects the top-most layer in
that page.
</p>
<p>
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.
</p>
<p>
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.
</p>
<h3 class="subsub">Managing pages and layers</h3>
<p>
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.
</p>
<p>
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).
</p>
<p>
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).
</p>
<h3 class="subsub">Paper formats and backgrounds</h3>
<p>
The size of the current page can be modified using the "Paper Size" entry
in the Journal menu. Standard and custom sizes are available.
</p>
<p>
The background is either one of several kinds of standard paper types, or a
bitmap image, or a page of a PDF file.
</p>
<p>
To select a <b>standard paper type</b> 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.
</p>
<p>
To use a <b>PDF file</b> as the background for a journal, see the paragraph
on <a href="manual.html#pdfannotate">PDF annotation</a> below.
</p>
<p>
To load a <b>bitmap image file</b> 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 <i>ghostscript</i> 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).
</p>
<p>
To capture a <b>screenshot</b> 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.
</p>
<p><b>Important note:</b> 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.<br />
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).
</p>
<p>
<b>Rescaling and anti-aliasing:</b> 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.<br />
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.
</p>
<a name="pdfannotate"></a>
<h3 class="subsub">PDF annotation</h3>
<p>
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
<i>pdftoppm</i> converter to be installed (this is part of the <i>xpdf</i>
PDF file viewer).
</p>
<p>
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).
</p>
<p>
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).
<p>
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.
</p>
<p>
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.
</p>
<p>
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 <i>pdfmerge</i>).
<hr />
<a name="printing"></a>
<h2 class="subtitle">Printing</h2>
<p>
Xournal uses the gnome-print architecture for printing. While it is very
powerful, some aspects of the API leave to be desired. As of version 0.3,
Xournal also includes a native PDF printing feature.
</p>
<h3 class="subsub">Printing via gnome-print</h3>
<p>
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).
</p>
<p>
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).
</p>
<p>
Note that the PDF virtual printer produces files that are very large
and far from optimal, so its use is not recommended.
The gnome-print architecture also forces page backgrounds (bitmaps
and PDF) to be generated as uncompressed bitmaps, which leads to gigantic
print job files. A better alternative is to export a PDF file, and
print the PDF file.
</p>
<h3 class="subsub">Exporting to PDF</h3>
<p>
Starting with version 0.3, Xournal provides its own PDF rendering
engine. The "Export to PDF" command (in the File menu) produces a
PDF-1.4 file from the currently loaded document. The resulting PDF
file is much more compact than those produced via gnome-print, and
its pages have the same size as in Xournal. Highlighter strokes
are rendered in a partially transparent manner (note however that
applications such as xpdf and ghostview do not always handle
PDF transparency properly). Text items are rendered by embedding
TrueType subsets or Type 1 fonts into the PDF document as appropriate.
</p>
<p>
Xournal also includes a PDF file parser compatible with PDF format
version 1.4; the compression features of PDF 1.5 (Acrobat 6) are
not supported. When exporting a document that uses PDF
backgrounds, Xournal attempts to preserve most of the structure of
the original PDF file (however, auxiliary data such as thumbnails, hyperlinks,
and annotations are lost). If Xournal is unable to parse the PDF
file, the backgrounds are converted to (compressed) bitmaps and a new
PDF file is generated from scratch.
</p>
<hr />
<a name="configuration"></a>
<h2 class="subtitle">Configuration</h2>
<p>
Starting with version 0.3.2, Xournal's configuration settings can be
saved to a file (<tt>~user/.xournal/config</tt>) by using the "Save
Preferences" command in the Options menu. The settings saved in the
configuration file include in particular:
<ul>
<li>general display preferences: zoom level, window size, ...</li>
<li>default paper settings (as set by the "Set As Default" command in
the Journal menu)</li>
<li>default settings for the pen, eraser, highlighter, and text tools
(as set by the "Set As Default" command in the Tools menu)</li>
<li>mappings for buttons 2 and 3</li>
<li>the various preferences set in the Options menu</li>
</ul>
The configuration file also gives access to additional customization
options which cannot be set from the user interface, such as: the
display resolution in pixels per inch, the step increment in zoom factors,
the tool selected at startup, the thickness of the various drawing tools,
the default directory for opening and saving files, the visibility and
position of the menu and toolbars, ...
</p>
<hr />
<a name="author"></a>
<h2 class="subtitle">Author information, license, bug-reports</h2>
<p>
Xournal is written by Denis Auroux
(aur<!--despam-->oux<span>@</span><span>math</span>.<span>mit.edu).
<br />It is distributed under the GNU General Public License.
</p>
<p>Feel free to contact me with bug reports and suggestions; I apologize
in advance if I am unable to respond properly to some requests.
</p><p>
If you find a sequence of operations which crashes Xournal in a reproducible
manner, please send detailed instructions on how to reproduce the crash.
A core file may also be helpful.
</p>
<p>
Bug reports and suggestions can also be submitted on Xournal's
<a href="http://www.sourceforge.net/projects/xournal/">SourceForge page.</a>
</p>
<hr />
<a name="changelog"></a>
<h2 class="subtitle">Version history</h2>
<p>
Version 0.4.2.1 (Mar 27, 2008):
<ul>
<li>bugfix for #1926757 (crash upon pasting variable-width stroke)</li>
<li>bugfix: set ruler/recognizer setting to default upon switching tools</li>
</ul>
</p>
<p>
Version 0.4.2 (Mar 25, 2008):
<ul>
<li>bugfixes for X.org 7.3; allow XInput and core events in reverse order</li>
<li>resize selection (patch contributed by Andy Neitzke)</li>
<li>pressure sensitive pen (variable stroke width) (patch by Andy Neitzke)</li>
<li>geometric shape recognizer (after an idea by Lukasz Kaiser)
(see <a href="manual.html#recognizer">here</a>)</li>
<li>clean up compiler warnings (patch contributed by Danny Kukawka)</li>
</ul>
</p>
<p>
Version 0.4.1 (Sep 15, 2007):
<ul>
<li> bugfix: compatibility with new versions of pdftoppm (thanks to
Vincenzo Ciancia)</li>
<li>GTK+ 2.11 event processing bugfix</li>
<li>minor bugfixes: hand tool, handling of filenames containing '&'</li>
<li>desktop and MIME files (thanks to Mathieu Bouchard) + updated installer</li>
<li>config options: left-handed scrollbar (contributed by Uwe Winter),
hide some menu items (customizable in config file), auto-save
preferences</li>
</ul>
</p>
<p>
Version 0.4.0.1 (September 3, 2007):
<ul>
<li>bugfixes for GTK+ 2.11 behavior (thanks to everyone who reported bugs)</li>
</ul>
</p>
<p>
Version 0.4 (August 15, 2007):
<ul>
<li>text tool (handles most TrueType and Type1 fonts)</li>
<li>font selection dialog and button</li>
<li>keyboard mappings (arrow keys)</li>
<li>menu mnemonics and shortcuts (suggestions by Jean-Baptiste Rouquier)</li>
<li>more responsive hand tool</li>
<li>bugfix for GTK+ 2.11 XInput behavior (thanks to Robert Gerlach)</li>
<li>various minor bugfixes and enhancements</li>
</ul>
</p>
<p>
Version 0.3.3 (January 31, 2007):
<ul>
<li>bugfix: upon loading a new file, zoom is set to default startup zoom</li>
<li>config option to allow input from a mouse or other core pointer device</li>
<li>config file entry to specify a default location for open/save
(patch contributed by Andy Neitzke)</li>
<li>config file entries to customize visibility and position of toolbars</li>
<li>icon (thanks to Michele Codutti)</li>
</ul>
</p>
<p>
Version 0.3.2 (November 25, 2006):
<ul>
<li>preferences file and Save Preferences command</li>
<li>extra customization (via preferences file)</li>
<li>minor UI changes (patch contributed by Eduardo de Barros Lima)</li>
<li>hand tool (partially contributed by Vincenzo Ciancia)</li>
<li>a few bugfixes in rendering of bitmap backgrounds</li>
</ul>
<p>
Version 0.3.1 (August 3, 2006):
<ul>
<li>fixed a file format bug on systems with non-standard numeric locale
(bug reported by Gert Renckens)</li>
</ul>
</p>
<p>
Version 0.3 (July 23, 2006):
<ul>
<li>new PDF rendering engine: export to PDF generates optimized files
(smaller and more accurate)</li>
<li>export to PDF handles PDF backgrounds (up to PDF-1.4) natively
(without conversion to bitmap)</li>
<li>default thickness of erasers and highlighters slightly increased</li>
<li>zoom dialog box with input box and "fit to page height" option</li>
<li>file format documentation added to the user's manual</li>
</ul>
</p>
<p>
Version 0.2.2 (June 5, 2006):
<ul>
<li>mapping of tools to stylus buttons (the options menu has new entries
to allow the mapping of buttons 2 and 3 to arbitrary tools; the tools
menu and toolbar affect the settings for button 1)
(see <a href="manual.html#mappings">here</a>)</li>
<li>moving selection by drag-and-drop works across page boundaries</li>
<li>vertical space tool can move items to next page (only when the entire
block being moved has crossed the page boundary; items on the new page
are not moved)</li>
<li>"apply to all pages" is now a toggle button affecting the behavior of
paper size, color, and style commands</li>
<li>change in the behavior of the selection upon switching between tools</li>
</ul>
</p>
<p>
Version 0.2.1 (June 3, 2006):
<ul>
<li>recently used files listed in file menu</li>
<li>can change color or thickness of pen strokes in selection</li>
<li>function to apply paper style to all pages</li>
<li>can specify on command line a PDF file to annotate</li>
<li>suggest a derived file name for PDF annotation</li>
<li>speed up switching between pages</li>
<li>fixed a bug in XInput initialization (thanks to Luca de Cicco)</li>
<li>fixed a bug in print ranges (thanks to Mathieu Bouchard)</li>
<li>fixed a refresh bug in rescaling bitmap backgrounds</li>
</ul>
</p>
<p>
Version 0.2 (January 29, 2006):
<ul>
<li>PDF file annotation using xpdf's pdftoppm
(PDF backgrounds updated asynchronously at all resolutions)</li>
<li>PS/PDF backgrounds (as bitmaps at fixed resolution) using ghostscript</li>
<li>option to antialias and filter bitmap backgrounds when zooming</li>
<li>option to emulate eraser tip with right mouse button</li>
<li>binary installer allows non-root installation without compiling</li>
<li>full-screen mode (patch contributed by Luca De Cicco)</li>
</ul>
</p>
<p>
Version 0.1.1 (January 5, 2006):
<ul>
<li> two bugfixes </li>
<li> backward compatibility with GTK+ 2.4 </li>
</ul>
</p>
<p>
Version 0.1 (January 2, 2006): initial release.
</p>
<hr />
<a name="file-format"></a>
<h2 class="subtitle">The file format</h2>
<h3 class="subsub">Overall structure</h3>
<p>
Xournal stores its data in gzipped XML-like files. The gzipped data consists
of a succession of XML tags describing the document. By convention, the
file header and trailer look like this:
<pre>
<?xml version="1.0" standalone="no"?>
<xournal version="...">
<title>Xournal document - see http://math.mit.edu/~auroux/software/xournal/</title>
... sequence of pages ...
</xournal>
</pre>
The <title> and <xournal> tags may only appear within the file
header (not within the pages of the document). The <i>version</i> attribute of
the <xournal> tag indicates which version of Xournal was used to
create the document; it is currently ignored, but may be used in a later
release if the file format changes in an incompatible manner.
(Following a suggestion of Matteo Abrate, starting with version 0.4 the
<xournal> tag is the document's root tag, and encloses all other tags).
</p>
<p>
The rest of the file is a sequence of pages, specified by a
<page> tag, whose attributes <i>width</i> and <i>height</i> specify the
physical size of the page in points (1/72 in). The width and height
parameters are floating point values. The format of a page is therefore:
<pre>
<page width="..." height="...">
... page contents ...
</page>
</pre>
</p>
<h3 class="subsub">Page background</h3>
<p>
The first entry within a page describes the page background.
It consists of a <background> tag followed by several mandatory
XML attributes. The first attribute is always <i>type</i>, which
can take three possible values: "solid" for a solid background, "pixmap"
for a bitmap background, and "pdf" if the background is a page of a PDF
document. The rest of the attributes depends on the type of background.
<ul>
<li><p> Solid background: <tt><background type="solid" color="..."
style="..." /></tt> <br />The <i>color</i> attribute takes one of
the standard values "white", "yellow", "pink", "orange", "blue", "green",
or can specify a hexadecimal RGBA value in the format "#rrggbbaa". The
<i>style</i> attribute takes one of the standard values "plain", "lined",
"ruled", or "graph".</p>
</li>
<li><p> Bitmap background: <tt><background type="pixmap" domain="..."
filename="..." /></tt> <br />
The <i>domain</i> attribute takes one of the standard values "absolute",
"attach", or "clone". A value of "absolute" indicates that the bitmap is
found in the file specified by <i>filename</i>. The bitmap can be in any
format recognized by the gdk-pixbuf library; this includes most of the
common bitmap formats (JPEG, PNG, BMP, GIF, PCX, PNM, TIFF, ...).
<br />A value
of "attach" indicates that the bitmap is an attachment to the Xournal file.
The bitmap is in PNG format, and resides in a file whose name is derived
from that of the main Xournal file by appending to it a dot and the contents
of the <i>filename</i> attribute. For example, if the Xournal file is in
<tt>file.xoj</tt> and the <i>filename</i> attribute is <tt>"bg_1.png"</tt>
then the bitmap file is <tt>file.xoj.bg_1.png</tt> (Xournal saves attached
bitmaps sequentially in files ...bg_1.png, ...bg_2.png, etc.)
<br />A value of "clone" indicates that the bitmap is identical to the
background of a previous page of the journal; the <i>filename</i> attribute
then specifies the page number, starting with 0 for the first page. For
example, if a <i>filename</i> value of <tt>"1"</tt> indicates that the
background bitmap is identical to that of the second page.
</p>
</li>
<li><p> PDF background: <tt><background type="pdf" domain="..."
filename="..." pageno="..." /></tt> or
<tt><background type="pdf" pageno="..." /></tt>
<br />The <i>domain</i> and <i>filename</i> attributes must be specified
for the first page of the journal that uses a PDF background, and must
be omitted subsequently for every other page that uses a PDF background.
The <i>domain</i> attribute takes one of the standard values
"absolute" and "attach"; the PDF document is to be found in the file
specified by <i>filename</i> (if <i>domain</i> is "absolute"), or in the
file whose name is obtained by appending a dot and the contents of the
<i>filename</i> attribute to the name of the main Xournal file (if
<i>domain</i> is "attach"). The <i>pageno</i> attribute specifies which
page of the PDF file is used as background, starting with 1 for the first
page of the PDF file.
</p>
</li>
</ul>
</p>
<h3 class="subsub">Layers and strokes</h3>
<p>
After the line specifying the background, the remainder of a <page>
section is occupied by one or more layer sections
<pre><layer> ... </layer></pre>
describing the various items within a layer. Every page must
contain at least one layer; a layer may be empty. The successive layers
are listed in their stacking order, from bottom to top.
</p>
<p>
A layer consists of a collection of items, listed in the order in which
they should be drawn
(from bottom-most to top-most).
Up to version 0.3.3, the only legal contents within a layer are
strokes. The format of a stroke is:
<pre><stroke tool="..." color="..." width="...">
... list of coordinates ...
</stroke>
</pre>
The <i>tool</i> attribute can take the values "pen", "highlighter", or
"eraser" depending on the tool used to create the stroke (pen, highlighter,
or whiteout eraser); a value of "highlighter" indicates that the stroke
should be painted in a partially transparent manner (Xournal uses an alpha
coefficient of 0.5).
</p>
<p>
The <i>color</i> attribute can take one of the standard values "black",
"blue", "red", "green", "gray", "lightblue", "lightgreen", "magenta",
"orange", "yellow", "white", or can specify a hexadecimal RGBA value in
the format "#rrggbbaa".
</p>
<p>
The <i>width</i> attribute is a floating-point
number (or a sequence of floating-point numbers starting with version 0.4.2),
and specifies the width of the stroke in points (1/72 in). (For a
variable-width stroke, the <i>width</i> attribute contains a
whitespace-separated succession of floating-point values: first the
nominal brush width, and then the width of each successive segment forming
the stroke.)
</p>
<p>
The list of coordinates is simply a succession of floating-point values,
separated by whitespace.
The number of given values must be even; consecutive pairs of values give
the <i>x</i> and <i>y</i> coordinates of each point along the stroke.
These values are expressed in points (1/72 in). The coordinates (0,0)
represent the top-left corner of the page: hence x is measured from the left
of the page, and y is measured from the top of the page.
</p>
<p>
Every stroke must contain at least two points (four floating point values).
Moreover, two consecutive points on the stroke should be spaced no more
than 5 units apart or so; longer line segments should be subdivided as
appropriate (otherwise the eraser tool will not interact properly with the
stroke). The default precision used by Xournal for the x,y coordinates is
0.01 unit (1/7200 in).
</p>
<p>Starting with version 0.4, layers also contain text items.
The format of a text item is:
<pre><text font="..." size="..." x="..." y="..." color="...">... text ...</text>
</pre>
The <i>font</i> attribute contains the font name, for example "Serif Bold
Italic"; if the font is not available, another font will be substituted.
The <i>size</i> attribute specifies the font size in points. The <i>x</i>
and <i>y</i> attributes specify the coordinates of the top-left corner
of the text box in page coordinates (measured in points from the top-left
corner of the page). Finally, the <i>color</i> attribute contains either
the name of a standard color or a hexadecimal RGBA value (see above).
</p>
<p>
The contents of the text are encoded in UTF-8, with the characters
<tt>'&', '<', '>'</tt> replaced by <tt>&amp;, &lt;,
&gt;</tt>. Whitespace and linefeeds are preserved (in particular,
no extraneous whitespace should be inserted between the enclosing tags
and the text itself).
</p>
<hr />
<a name="installation"></a>
<h2 class="subtitle">Installation issues</h2>
<h3 class="subsub">Dependencies</h3>
<p>
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):
<ul>
<li> the <b>gtk+</b> libraries, version <b>2.4</b> or later
(<b>2.6</b> strongly recommended) (package gtk2 and dependencies)</li>
<li> <b>libgnomecanvas</b> version <b>2.4</b> or later
(package libgnomecanvas and dependencies)</li>
<li> <b>libgnomeprint</b> and <b>libgnomeprintui</b> version <b>2.2</b> or later
(packages libgnomeprint22, libgnomeprintui22, and dependencies) </li>
</ul>
</p>
<p>
Additionally:
<ul>
<li> <b>xpdf</b> (more precisely, <b>pdftoppm</b>) is required for PDF file
annotation</li>
<li> <b>ghostscript</b> (optional: used to import PS/PDF files as bitmap
backgrounds)</li>
</ul>
<p>
To compile Xournal, you also need the <b>development packages</b> for the above
libraries (packages gtk2-devel, libgnomecanvas-devel, libgnomeprint22-devel,
libgnomeprintui22-devel, and dependencies), as well as <b>autoconf</b> and
<b>automake</b>.
</p>
<h3 class="subsub">Compilation and installation procedure</h3>
<p>
Download the Xournal distribution tar.gz file, and any needed dependencies.
</p>
<p>
<b>Binary installation in /usr/local:</b><br />
Run (as root) the installer script
<pre>./install-binary</pre> (and upgrade GTK+ and the other libraries if needed).
</p>
<p>
<b>Binary installation in home directory:</b><br />
Run (as any user) the installer script
<pre>./install-binary</pre> (and hope that the required libraries are
installed on your system).
</p>
<p>
<b>Compilation and installation in /usr/local:</b>
<pre>
./autogen.sh
make
(as root) make install
(as root) make desktop-install
</pre>
</p>
<p>
<b>Compilation and installation in $HOME:</b>
<pre>
./autogen.sh
./configure --prefix=$HOME
make
make install
make home-desktop-install
</pre>
</p>
<p><b>Configure error message:</b> <br />
If autogen.sh generates the error message
<tt><i>
configure: error: Library requirements (gtk+-2.0 >= 2.4.0 libgnomecanvas-2.0 >= 2.4.0 libgnomeprintui-2.2 >= 2.0.0) not met
</i></tt>
even though you have sufficiently recent versions of these libraries on your
system, then you need to install some missing development packages.
</p>
<hr />
<a name="calibration"></a>
<h2 class="subtitle">Tablet calibration issues</h2>
<p>
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.
</p>
<h3 class="subsub">Basics</h3>
<p>
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).
</p>
<p>
The configuration of tablet devices is controlled in the X server's
configuration file (usually <b>XF86Config</b> or <b>xorg.conf</b> depending on your
distribution). The ServerLayout section should contain lines like:
<pre>
Section "ServerLayout"
...
InputDevice "cursor" "SendCoreEvents"
InputDevice "stylus" "SendCoreEvents"
InputDevice "eraser" "SendCoreEvents"
EndSection
</pre>
(the last one only if your stylus has an eraser tip), and your configuration
file should include sections such as
<pre>
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
</pre>
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.
</p>
<p>
For historical reasons, most X servers do not allow the input device
designated as the "core pointer" in the X server's configuration file
to be used as an XInput extension device. Thus, your tablet input devices
should <b>not</b> be designated as the core pointer device. Instead, they
should be configured with the "SendCoreEvents" option, which enables them
to simultaneously generate XInput extension events and move the cursor on
the screen. Since high-resolution coordinates cannot be obtained for the
core pointer device, it is disabled in Xournal by default.
Starting with version 0.3.3,
it is possible to have core events processed alongside with extension
events (uncheck "Discard Core Events" in the Options menu); however, in
some rare cases this may lead to a loss of resolution on all devices.
</p>
<h3 class="subsub">The cursor doesn't appear in the right place...</h3>
<p>
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 <b>xsetwacom</b>. The relevant parameters are named TopX, BottomX,
TopY, BottomY, and need to be set separately for the stylus and for the
eraser. For example:
<pre>
xsetwacom set stylus TopX 270
xsetwacom set stylus BottomX 28510
...
</pre>
(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).
</p>
<p>
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).
</p>
<p>
<b>Important:</b> due to issues with old versions of the linuxwacom
driver (< 0.7.6), it is important to upgrade your driver,
or restrict your choice of settings as follows:
<ul>
<li> your calibration settings should not be changed at runtime (i.e.,
insert your settings directly into your X server configuration file.
Do not add a list of xsetwacom commands to your startup files).
</li>
<li> TopX and TopY values should always be 0.
</li>
</ul>
</p>
<h3 class="subsub">Strokes aren't drawn under the cursor...</h3>
<p>
This is typically due to misfeatures in the linuxwacom driver in versions
prior to 0.7.6, and will happen in all of the following cases:
<ul>
<li> the calibration settings have been changed after the X server was
started (using xsetwacom) </li>
<li> the calibration TopX or TopY values are not 0 </li>
<li> the display has been rotated </li>
</ul>
Most of these issues should have been fixed in version 0.7.6 of the
wacom driver. Otherwise, you can
either disable XInput support in Xournal (in the Options menu), at a
price of a severe loss of resolution (and the eraser tip won't be detected
anymore), or inspect carefully your X server configuration and make
sure the tablet devices are calibrated and configured properly.
</p>
<p>
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 commenting out the line
<pre>#define ENABLE_XINPUT_BUGFIX</pre>
near the beginning of <tt>src/xournal.h</tt>.
If 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.
</p>
<h3 class="subsub">On-the-fly display rotation</h3>
<p>
You need an X server that supports the RANDR extension, and a sufficiently
recent (0.7.6 or later)
version of the linuxwacom driver to support on-the-fly rotation.
</p>
<p>
To set the tablet in portrait mode:
<pre>
xrandr -o 3
xsetwacom set stylus Rotate cw
</pre>
To return to landscape mode:
<pre>
xrandr -o 0
xsetwacom set stylus Rotate none
</pre>
<b>Note:</b> 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.
</p>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
fddf6460be4c0a7fe67c7f485d582f2e
>
files
>
8
