--- /dev/null
+<?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.2
+</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://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
+ (in particular, freeform selection and PDF backgrounds are missing).
+</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#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. 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.<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/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>
+<h3 class="subsub"><img src="pixmaps/recycled.png"> Default tools</h3>
+<p>
+ 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. <br />
+ 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.
+</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.
+</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>
+<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.
+<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,
+and future versions of Xournal will probably also include a native
+Postscript/PDF printing feature.
+</p>
+<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>
+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.
+</p>
+<p>
+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.
+<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.
+List of known bugs/misfeatures (no need to report them again):
+<ul>
+ <li> highlighter strokes become opaque on printouts (apparently a bug in
+ libgnomeprint).</li>
+ <li> print settings are not saved from one print command to the next.</li>
+ <li> printing to PDF and/or printing page backgrounds generates large files.</li>
+ <li> preferences are not saved on disk.</li>
+ <li> selection cannot be dragged across page boundaries.</li>
+</ul>
+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>
+<hr />
+<a name="changelog"></a>
+<h2 class="subtitle">Version history</h2>
+<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</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>
+<p>
+Features yet to be implemented:
+<ul>
+ <li>freeform selection tool</li>
+ <li>preferences file; persistent printer settings; recent files list</li>
+ <li>native PDF print feature</li>
+ <li>various functionalities (flatten layers, drag-and-drop across pages, ...)</li>
+</ul>
+</p>
+<hr />
+<a name="file-format"></a>
+<h2 class="subtitle">The file format</h2>
+<p>
+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.
+</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
+ (2.6 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
+</pre>
+</p>
+<p>
+<b>Compilation and installation in $HOME:</b>
+<pre>
+./autogen.sh
+./configure --prefix=$HOME
+make
+make 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>
+<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 the linuxwacom driver, it is important
+to either upgrade your driver to a <a href="manual.html#wacompatch">patched
+version</a>, 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 due to misfeatures in the linuxwacom driver. Typically, this
+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>
+Future versions of the driver may fix these issues. Meanwhile, 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 apply this <a href="manual.html#wacompatch">patch</a>
+to the wacom driver.
+</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 changing the first line of
+<tt>src/main.c</tt> to
+<pre>#define ENABLE_XINPUT_BUGFIX 0</pre>
+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
+<a href="manual.html#wacompatch">patched</a> 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>
+<a name="wacompatch"></a>
+<h3 class="subsub">Linuxwacom patch for calibration and rotation</h3>
+<p>
+This patch fixes rotation and calibration issues with the linuxwacom driver
+version 0.7.0.
+<ul>
+<li>The <a href="http://math.mit.edu/~auroux/software/xournal/linuxwacom-0.7.0-rotate-patch">patch
+file</a> for the linuxwacom source code (also included with the Xournal
+distribution).</li>
+<li>The <a href="http://math.mit.edu/~auroux/software/xournal/linuxwacom-rotate-patch.tar.gz">patched
+binaries</a> for the X.org X server.</li>
+</ul>
+</p>
+</body>
+</html>
projects / xournal.git / commitdiff