html-doc/manual.html

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head><title>Xournal User's manual</title></head>
   5 <style>
   6  .subtitle {
   7   font-family: Helvetica, Arial, sans-serif;
   8   font-weight: bold;
   9   font-size: 1.3em;
  10   color: rgb(0,150,0);
  11  }
  12  .subsub {
  13   font-family: Helvetica, Arial, sans-serif;
  14   font-weight: bold;
  15   font-size: 1em;
  16   color: rgb(0,150,0);
  17  }
  18  a { color: rgb(0,0,255); text-decoration: none; }
  19  a:hover { text-decoration: underline; }
  20 </style>
  21 <body bgcolor="#ffffff" style="background: rgb(255,255,255)">
  22
  23 <h2 class="subtitle" style="text-align: center; color: rgb(0,0,200)">
  24   Xournal User's Manual
  25 </h2>
  26 <p style="font-size: 0.95em; text-align: center; color: rgb(0,0,0)">
  27  Version 0.4.1
  28 </p>
  29 <hr />
  30 <p>
  31  Xournal is an application for notetaking, sketching, keeping
  32  a journal using a stylus. It is free software (GNU GPL) and runs
  33  on Linux (recent distributions) and other GTK+/Gnome platforms.
  34  It is similar to Microsoft Windows Journal or
  35  to other alternatives such as
  36  <a href="http://www.dklevine.com/general/software/tc1000/jarnal.htm">Jarnal</a>
  37  and <a href="http://www.adebenham.com/gournal/">Gournal</a>.
  38 </p>
  39 <p>
  40 Xournal can be downloaded at
  41 <a href="http://xournal.sourceforge.net/">http://xournal.sourceforge.net/</a> or
  42 <a href="http://math.mit.edu/~auroux/software/xournal/">http://math.mit.edu/~auroux/software/xournal/</a>
  43 </p>
  44 <p>
  45  Xournal aims to provide superior graphical quality (subpixel resolution) and overall
  46  functionality; however it lacks the collaborative features of Jarnal.
  47  Since Xournal is still in its early development stages, it may not
  48  be fully stable, and some features have not been implemented yet.
  49 </p>
  50 <h2 class="subtitle">Table of contents</h2>
  51 <p>
  52  <ul>
  53   <li> <a href="manual.html#getting-started">Getting started</a> </li>
  54   <li> <a href="manual.html#tools">The drawing and selection tools</a> </li>
  55   <li> <a href="manual.html#pages-layers">Pages, layers, and backgrounds</a> </li>
  56   <li> <a href="manual.html#printing">Printing</a> </li>
  57   <li> <a href="manual.html#configuration">Configuration</a> </li>
  58   <li> <a href="manual.html#author">Author information, license, bug-reports</a> </li>
  59   <li> <a href="manual.html#changelog">Version history</a> </li>
  60   <li> <a href="manual.html#file-format">The file format</a> </li>
  61   <li> <a href="manual.html#installation">Installation issues</a> and
  62        <a href="manual.html#calibration">tablet calibration issues</a> </li>
  63  </ul>
  64 </p>
  65 <hr />
  66 <a name="getting-started"></a>
  67 <h2 class="subtitle">Getting started</h2>
  68 <p>
  69  Xournal's user interface is (hopefully) intuitive, and if you don't run
  70  into <a href="manual.html#installation">installation</a> or
  71  <a href="manual.html#calibration">tablet calibration</a> issues, you'll
  72  probably be able to start taking notes without referring to this manual.
  73  <br />
  74  Here is a screenshot of the user interface (click to enlarge):
  75 </p>
  76 <p style="text-align: center">
  77  <a href="screenshot.png">
  78    <img src="screenshot.png" style="width: 321px; height: 176px" />
  79  </a>
  80 </p>
  81 <p>
  82 Refer the next few sections of this manual for more information about
  83 the various functionalities.
  84 </p>
  85 <hr />
  86 <a name="tools"></a>
  87 <h2 class="subtitle">The drawing and selection tools</h2>
  88 <h3 class="subsub"><img src="pixmaps/pencil.png"> The pen</h3>
  89 <p>
  90 The pen is the default drawing tool in Xournal. It comes in a variety
  91 of colors (see the color toolbar buttons and the Color submenu of the
  92 Tools menu) and thicknesses (see the
  93 <a href="manual.html#thicknesses">thickness</a> toolbar buttons and
  94 the Pen Options submenu of the Tools menu).
  95 </p>
  96 <h3 class="subsub"><img src="pixmaps/eraser.png"> The eraser</h3>
  97 <p>
  98 The eraser lets you erase what you have drawn.
  99 By default, stylus buttons 2 and 3 (mouse middle or right buttons) are
 100 mapped to the eraser tool.
 101 <br />
 102 The eraser comes in three different thicknesses (selected using the
 103 <a href="manual.html#thicknesses">thickness</a> toolbar buttons),
 104 and can operate in three different modes (Eraser Options submenu of
 105 the Tools menu):
 106 <ul>
 107  <li>
 108    Standard mode (default): the eraser deletes portions
 109    of strokes previously drawn using the pen or the highlighter.
 110    In this mode, if you erase in the middle of a stroke, the remaining
 111    portions of the stroke are automatically split into shorter strokes.
 112    The background of the page (and the lower layers) are not erased.
 113  </li>
 114  <li>
 115    Whiteout: the eraser is actually a thick white pen, and simply covers
 116    whatever lies underneath, including the background of the page.
 117  </li>
 118  <li>
 119    Delete strokes: whenever the eraser comes in contact with a previously
 120    drawn stroke, the entire stroke is deleted.
 121   </li>
 122 </ul>
 123 </p>
 124 <h3 class="subsub"><img src="pixmaps/highlighter.png"> The highlighter</h3>
 125 <p>
 126   Like the pen, the highlighter comes in a variety of colors (the default
 127   is yellow) and thicknesses. Use the color and thickness toolbar buttons
 128   to change these settings.
 129 </p>
 130 <h3 class="subsub"><img src="pixmaps/text-tool.png"> The text tool</h3>
 131 <p>
 132   To insert a new text item, click at the location where the text is to be
 133   inserted on the page, then type it in or paste it using the contextual
 134   menu (note: no wrapping is performed). To modify a text item, click inside
 135   it. The font and point size can be modified using the "Text Font" command
 136   in the Tools menu (or the toolbar button). The color is the same as that
 137   currently selected for the pen (and can be modified using the toolbar
 138   buttons).
 139 </p>
 140 <p>
 141   Text items can contain arbitrary Unicode characters, provided that a
 142   suitable font is installed on your system. However, languages written
 143   in a direction other than left-to-right might not be handled properly.
 144   If a journal contains some items in a font that is unavailable on your
 145   system, another one will be substituted. (Also, text items will be
 146   lost if the document is opened in a version of Xournal prior to 0.4).
 147   Finally, note that the printing and PDF export features only accept
 148   TrueType and Type 1 scalable fonts (do not use any bitmap fonts), and
 149   that the typesetting of the text may be slightly different in the
 150   printout.
 151 </p>
 152 <h3 class="subsub"><img src="pixmaps/ruler.png"> The ruler</h3>
 153 <p>
 154   The ruler is not a tool by itself, but rather a special operating mode
 155   of the pen and highlighter tools. When it is enabled, these tools paint
 156   line segments instead of curvy strokes. For simplicity, selecting the
 157   ruler when not in pen or highlighter mode automatically selects the pen.
 158 </p>
 159 <h3 class="subsub"><img src="pixmaps/recycled.png"> Default tools</h3>
 160 <p>
 161   Each tool (pen, eraser, highlighter, text) has a default setting
 162   (color, thickness, ... for the drawing tools, font and size for the
 163   text tool) associated to it.
 164   The "Default Pen", "Default Eraser", "Default Highlighter", and
 165   "Default Text" entries of
 166   the Tools menu select the appropriate tool and reset its settings to
 167   the defaults. The toolbar also includes a "Default" button which
 168   resets the currently selected tool to its default settings,
 169   and a "Default Pen" button. <br />
 170   The "Set As Default" entry of the Tools menu takes the current settings
 171   of the currently selected tool and makes them the new default.
 172 </p>
 173 <a name="thicknesses"></a>
 174 <h3 class="subsub"><img src="pixmaps/thin.png"> <img src="pixmaps/medium.png">
 175   <img src="pixmaps/thick.png"> Thickness buttons</h3>
 176 <p>
 177   These three buttons control the thickness of the current drawing tool
 178   (pen, eraser, or highlighter). The thickness can also be adjusted using
 179   the appropriate sub-menu of the Tools menu.
 180 </p>
 181 <h3 class="subsub"><img src="pixmaps/rect-select.png"> Rectangle selection</h3>
 182 <p>
 183   This tool lets you select a rectangular region of the current layer.
 184   All the strokes which are entirely contained within the rectangular region
 185   are selected.
 186   The selection can be moved within its page by clicking inside the
 187   selection rectangle and dragging the cursor. If the cursor is dragged
 188   to a different page, the selection will be moved to the topmost layer of
 189   that page.
 190 </p>
 191 <p>
 192   The selection can be cut, duplicated, etc. (including to a different page
 193   or to a different journal) using the copy-paste toolbar buttons or the
 194   corresponding entries of the Edit menu.
 195 </p>
 196 <h3 class="subsub"><img src="pixmaps/stretch.png"> Vertical space</h3>
 197 <p>
 198   This tool lets you insert or remove vertical space within the page:
 199   all the items of the current layer which lie entirely between the cursor
 200   position and the end of the page are moved up or down.
 201 </p>
 202 <p>
 203   Note that the background, and items on other layers, are not affected.
 204   Also, if you insert too much vertical space, some items may fall below
 205   the bottom of the page and become invisible. These items are not lost:
 206   to retrieve them, either use
 207   the vertical space tool again to remove the excess vertical
 208   space, or change the page height to an appropriate value (using the
 209   "Paper Size" entry in the Journal menu).
 210 </p>
 211 <p>
 212   If you drag the cursor below the bottom of the page (so that the
 213   entire block being moved has become invisible), the items will be moved
 214   to the next page (topmost layer); however, any items that were already
 215   present on the next page are left unchanged. Similarly, dragging the
 216   cursor above the top of the page so that the entire block being moved
 217   becomes invisible results in the items being moved to the previous page.
 218 </p>
 219 <h3 class="subsub"><img src="pixmaps/hand.png"> Hand tool</h3>
 220 <p>
 221   This tool lets you browse the journal; dragging the cursor scrolls the
 222   view.
 223 </p>
 224 <h3 class="subsub">Undo and redo</h3>
 225 <p>
 226   All operations performed on the currently open journal (drawing, erasing,
 227   cut-and-paste; adding, deleting, and reformatting pages; etc.) can be
 228   undone and redone at will using the Undo and Redo toolbar buttons or
 229   the corresponding entries in the Edit menu.<br />
 230   There is no limit to the depth of the undo/redo stack. It is cleared only
 231   when you quit the application or open a new journal.
 232 </p>
 233 <a name="mappings"></a>
 234 <h3 class="subsub">Button mappings</h3>
 235 <p>
 236   Stylus buttons 2 and 3 (mouse middle and right buttons) can be mapped
 237   to different tools using the appropriate submenus in the Options menu
 238   (whereas the Tools menu and the toolbar buttons affect the primary tool
 239   assigned to button 1). The default mapping is the eraser.
 240 </p>
 241 <p><b>Advanced configuration:</b>
 242   if a secondary button is mapped to a drawing tool (pen, eraser, or
 243   highlighter), the default is to "dynamically link" its settings to those
 244   of the primary tool, which means that each drawing tool has common
 245   settings (color, thickness, etc.) for all buttons.
 246   Dynamic linking of brush settings
 247   can be disabled by selecting the "Copy of current brush" option in the
 248   "Button mapping" submenu. The settings of the tool for button 2 or 3 are
 249   copied from the button 1 settings at the time when you select the option,
 250   and afterwards they are no longer updated when the button 1 settings are
 251   modified, thus making it possible to assign pens of different colors or
 252   thicknesses to different buttons.
 253 </p>
 254 <p>
 255   Another option that affects button mappings is the "Eraser tip" option.
 256   If this option is turned on and the XInput extensions are enabled, then
 257   the eraser tip of your tablet's stylus will automatically be remapped to
 258   the eraser tool. This behavior, which overrides all other button mappings,
 259   is most useful if your X server is configured to map the eraser tip of
 260   your tablet's stylus to button 1.
 261 </p>
 262 <hr />
 263 <a name="pages-layers"></a>
 264 <h2 class="subtitle">Pages, layers, and backgrounds</h2>
 265 <p>
 266 A journal is composed of one or more pages, whose characteristics can be
 267 modified independently of each other. Each page consists of a background
 268 and one or more layers stacked on top of the background. All drawing
 269 operations take place within a single layer, and do not affect the background
 270 or the other layers. You can think of the layers as transparent overlays:
 271 drawing and erasing always takes place on the topmost visible overlay.
 272 <br />
 273 Layers are a convenient mechanism to add temporary annotations on top of a
 274 journal page: because of the logical separation between layers, erasing
 275 in the top layer will not affect the contents of the other layers, and
 276 the top layer can be easily discarded.
 277 </p>
 278 <h3 class="subsub">Navigating the journal</h3>
 279 <p>
 280 The user interface either displays all pages in the journal below each other
 281 ("continuous mode") or a single page ("one-page mode"). You can switch
 282 between the two modes by using the "Continuous" and "One page" entries in
 283 the View menu. The default is the
 284 continuous mode, best adapted to note-taking on multiple pages. The one-page
 285 mode is more appropriate if your journal is a scrapbook in which the pages
 286 have different characteristics (in particular, if you are annotating a
 287 series of pictures of different sizes).
 288 </p>
 289 <p>
 290 You can navigate the journal pages in several different ways:
 291 <ul>
 292  <li> using the navigation toolbar buttons (or the corresponding entries
 293   in the View menu) to go back or forward one page, or to jump to the first
 294   or last page of the journal;
 295  </li>
 296  <li> in continuous mode, scrolling down to the desired page;
 297  </li>
 298  <li> entering a value or using the +/- buttons in the page selection box
 299   at the lower-left corner of the Xournal window.
 300  </li>
 301 </ul>
 302 As a convenient shortcut, going forward one page (or pressing the + button
 303 in the selection box) when already at the end of the journal creates a new
 304 page at the end of the journal.
 305 </p>
 306 <p>
 307 Note: jumping to a page automatically selects the top-most layer in
 308 that page.
 309 </p>
 310 <p>
 311 To navigate the layers of a page, either use the layer selection box at
 312 the bottom of the Xournal window, or use the "Show Layer" and "Hide Layer"
 313 entries in the View menu. The basic rule to remember is that the display
 314 shows all the layers underneath the currently select one, and while those
 315 above it are hidden.
 316 </p>
 317 <p>
 318 Note: the background layer cannot be drawn on; any attempt to draw on the
 319 background will generate an error message and switch back to the first
 320 layer.
 321 </p>
 322 <h3 class="subsub">Managing pages and layers</h3>
 323 <p>
 324 Pages can be added to the journal by using the "New Page ..." entries in
 325 the Journal menu. The newly created page has the same format and background as the
 326 current page (for the "New Page Before" and "New Page After" commands), or
 327 as the last page of the journal (for "New Page At End"). Additionally,
 328 jumping to the next page when already on the last page creates a new page
 329 at the end of the journal.
 330 </p>
 331 <p>
 332 The "Delete Page" entry in the Journal menu removes the current page from
 333 the journal. (Remember that you can always undo this operation if you
 334 deleted a page by accident).
 335 </p>
 336 <p>
 337 The "New Layer" entry in the Journal menu creates a new layer immediately
 338 above the current one, while "Delete Layer" removes the current layer and
 339 its contents (if you attempt to delete the only layer of a page, a new
 340 empty layer will be automatically created).
 341 </p>
 342 <h3 class="subsub">Paper formats and backgrounds</h3>
 343 <p>
 344 The size of the current page can be modified using the "Paper Size" entry
 345 in the Journal menu. Standard and custom sizes are available.
 346 </p>
 347 <p>
 348 The background is either one of several kinds of standard paper types, or a
 349 bitmap image, or a page of a PDF file.
 350 </p>
 351 <p>
 352 To select a <b>standard paper type</b> as background for the current page, use
 353 the "Paper Style" submenu of the Journal menu. The paper color can also
 354 be changed using the "Paper Color" submenu of the Journal menu.
 355 </p>
 356 <p>
 357 To use a <b>PDF file</b> as the background for a journal, see the paragraph
 358 on <a href="manual.html#pdfannotate">PDF annotation</a> below.
 359 </p>
 360 <p>
 361 To load a <b>bitmap image file</b> for use as background for the current page, use
 362 the "Load Background" entry of the Journal menu. This automatically
 363 resizes the current page according to the size of the bitmap image, and
 364 resets the zoom level to 100%. If <i>ghostscript</i> is installed on your
 365 system, you can also use this method to import a fixed-resolution bitmap
 366 version of a Postscript or PDF file; in that case, all pages will be
 367 imported sequentially as backgrounds into consecutive pages (this is not the
 368 recommended method; PDF annotation is better in many respects).
 369 </p>
 370 <p>
 371 To capture a <b>screenshot</b> of a window or the entire screen and make it
 372 the background of the current page, use the "Background Screenshot" entry of
 373 the Journal menu. This will iconify the Xournal window; click in any window
 374 (after ensuring it is fully visible) to capture its contents, or click on
 375 the desktop (or screen background) to capture the entire screen.
 376 </p>
 377 <p><b>Important note:</b> by default, bitmap images loaded using the "Load
 378 Background" command will not be saved with the journal; instead, the journal
 379 file will contain a reference to the absolute location of the image file.
 380 This means that the background will become unavailable if the image file
 381 is moved or deleted. To avoid this, check the option "Attach file to the
 382 journal" at the bottom of the file selection dialog box.<br />
 383 This option only applies to bitmap image files loaded from disk;
 384 screenshot backgrounds (and bitmaps converted from PS/PDF files using
 385 ghostscript) are automatically "attached" to the journal file: when the
 386 journal is saved, they will be saved (in PNG format) along with it
 387 (using file names of the form *.xoj.bg_*.png).
 388 </p>
 389 <p>
 390 <b>Rescaling and anti-aliasing:</b> by default,
 391 bitmap backgrounds are rescaled and anti-aliased as needed when the zoom
 392 level is changed, to ensure their appearance always remains acceptable.
 393 Because this consumes a lot of memory and CPU resources, by default this
 394 rescaling is performed on-demand as each page becomes visible. This means
 395 that you will occasionally notice bitmap backgrounds being smoothed while
 396 you are scrolling inside the document (at large zoom levels, this can slow
 397 down the screen refresh rate noticeably). If you'd prefer all backgrounds to
 398 be rescaled immediately upon changing the zoom level (slower but maybe more
 399 intuitive), disable the "Progressive Backgrounds" option in the Options
 400 menu.<br />
 401 If you are handling large bitmaps, you can save memory and CPU resources (at the
 402 expense of quality) by disabling the "Antialiased Bitmaps" option in the Options menu.
 403 </p>
 404
 405 <a name="pdfannotate"></a>
 406 <h3 class="subsub">PDF annotation</h3>
 407 <p>
 408 Xournal can be used to annotate PDF files, by loading the pages of a PDF
 409 file as backgrounds for a journal. This feature requires the
 410 <i>pdftoppm</i> converter to be installed (this is part of the <i>xpdf</i>
 411 &nbsp;PDF file viewer).
 412 </p>
 413 <p>
 414 The "Annotate PDF" command in the File menu can be used to load a PDF file
 415 into a new (empty) journal. The page backgrounds and page sizes correspond
 416 to the contents of the PDF file. (Most unencrypted PDF files should be
 417 supported).
 418 </p>
 419 <p>
 420 By default, the PDF file used to generate the backgrounds
 421 will not be saved with the journal; instead, the journal
 422 file will contain a reference to the absolute location of this file.
 423 This means that all backgrounds will become unavailable if the PDF file
 424 is moved or deleted (although Xournal will let you specify
 425 the updated location of the PDF file when opening the journal
 426 file). To avoid this, check the option "Attach file to the journal"
 427 at the bottom of the dialog box when opening the PDF file. The PDF file will
 428 then be saved along with the journal (using a file name of the form
 429 *.xoj.bg.pdf).
 430 <p>
 431 Upon zooming, the page backgrounds are asynchronously updated
 432 to fit the current display resolution. Since this process is quite slow and
 433 memory-intensive, the pages are normally updated only as needed, when they
 434 become visible on the screen (unless you disable the "Progressive
 435 Backgrounds" option in the Options menu). This means that you will
 436 occasionally notice the page backgrounds being updated while you are
 437 scrolling inside the document (at large zoom levels, it can take a while
 438 for the updated background to appear). However, since the backgrounds are
 439 generated asynchronously by a separate Unix process, you can keep drawing in the journal
 440 while the update process is still in progress.
 441 </p>
 442 <p>
 443 It is strongly recommended that you do not resize PDF pages (using the
 444 "Paper Size" command). This will result in extremely ugly rendering, as
 445 the PDF converter is unable to render bitmaps with
 446 non-standard aspect ratios.
 447 </p>
 448 <p>
 449 While you can perform all sorts of page operations on a journal file
 450 that was created from a PDF file (such as duplicating or deleting pages,
 451 inserting pages with blank or bitmapped backgrounds, ...), it is not
 452 possible to include pages from more than one PDF file into a single journal
 453 document. If you need to annotate two or more PDF files inside a same
 454 journal document, please consider using an external utility for merging
 455 PDF files (for example <i>pdfmerge</i>).
 456 <hr />
 457 <a name="printing"></a>
 458 <h2 class="subtitle">Printing</h2>
 459 <p>
 460 Xournal uses the gnome-print architecture for printing. While it is very
 461 powerful, some aspects of the API leave to be desired. As of version 0.3,
 462 Xournal also includes a native PDF printing feature.
 463 </p>
 464 <h3 class="subsub">Printing via gnome-print</h3>
 465 <p>
 466 The "Printer" tab of the print dialog box lets you select a printer
 467 (either one of the printers installed on your system, or the generic
 468 Postscript printer, or the PDF virtual printer). The "Job" tab lets you
 469 select a range of pages to print (the default is to print the entire
 470 journal). The "Paper" tab lets you select the paper size. Each page
 471 of the journal is automatically rescaled so as to fit the paper size.
 472 (minus a 5% margin all around).
 473 </p>
 474 <p>
 475 The settings are currently not saved properly from one print job to
 476 the next, so make sure to select the appropriate printer and verify
 477 the paper size. When printing to a file (Postscript or PDF), Xournal
 478 attempts to pre-fill the output file name (for the Postscript driver
 479 this often fails due to gnome-print API issues).
 480 </p>
 481 <p>
 482 Note that the PDF virtual printer produces files that are very large
 483 and far from optimal, so its use is not recommended.
 484 The gnome-print architecture also forces page backgrounds (bitmaps
 485 and PDF) to be generated as uncompressed bitmaps, which leads to gigantic
 486 print job files. A better alternative is to export a PDF file, and
 487 print the PDF file.
 488 </p>
 489 <h3 class="subsub">Exporting to PDF</h3>
 490 <p>
 491 Starting with version 0.3, Xournal provides its own PDF rendering
 492 engine. The "Export to PDF" command (in the File menu) produces a
 493 PDF-1.4 file from the currently loaded document. The resulting PDF
 494 file is much more compact than those produced via gnome-print, and
 495 its pages have the same size as in Xournal. Highlighter strokes
 496 are rendered in a partially transparent manner (note however that
 497 applications such as xpdf and ghostview do not always handle
 498 PDF transparency properly). Text items are rendered by embedding
 499 TrueType subsets or Type 1 fonts into the PDF document as appropriate.
 500 </p>
 501 <p>
 502 Xournal also includes a PDF file parser compatible with PDF format
 503 version 1.4; the compression features of PDF 1.5 (Acrobat 6) are
 504 not supported. When exporting a document that uses PDF
 505 backgrounds, Xournal attempts to preserve most of the structure of
 506 the original PDF file (however, auxiliary data such as thumbnails, hyperlinks,
 507 and annotations are lost). If Xournal is unable to parse the PDF
 508 file, the backgrounds are converted to (compressed) bitmaps and a new
 509 PDF file is generated from scratch.
 510 </p>
 511 <hr />
 512 <a name="configuration"></a>
 513 <h2 class="subtitle">Configuration</h2>
 514 <p>
 515 Starting with version 0.3.2, Xournal's configuration settings can be
 516 saved to a file (<tt>~user/.xournal/config</tt>) by using the "Save
 517 Preferences" command in the Options menu. The settings saved in the
 518 configuration file include in particular:
 519 <ul>
 520 <li>general display preferences: zoom level, window size, ...</li>
 521 <li>default paper settings (as set by the "Set As Default" command in
 522 the Journal menu)</li>
 523 <li>default settings for the pen, eraser, highlighter, and text tools
 524 (as set by the "Set As Default" command in the Tools menu)</li>
 525 <li>mappings for buttons 2 and 3</li>
 526 <li>the various preferences set in the Options menu</li>
 527 </ul>
 528 The configuration file also gives access to additional customization
 529 options which cannot be set from the user interface, such as: the
 530 display resolution in pixels per inch, the step increment in zoom factors,
 531 the tool selected at startup, the thickness of the various drawing tools,
 532 the default directory for opening and saving files, the visibility and
 533 position of the menu and toolbars, ...
 534 </p>
 535 <hr />
 536 <a name="author"></a>
 537 <h2 class="subtitle">Author information, license, bug-reports</h2>
 538 <p>
 539 Xournal is written by Denis Auroux
 540 (aur<!--despam-->oux<span>&#x40;</span><span>math</span>&#x2e;<span>mit&#x2e;edu).
 541 <br />It is distributed under the GNU General Public License.
 542 </p>
 543 <p>Feel free to contact me with bug reports and suggestions; I apologize
 544 in advance if I am unable to respond properly to some requests.
 545 </p><p>
 546 If you find a sequence of operations which crashes Xournal in a reproducible
 547 manner, please send detailed instructions on how to reproduce the crash.
 548 A core file may also be helpful.
 549 </p>
 550 <p>
 551 Bug reports and suggestions can also be submitted on Xournal's
 552 <a href="http://www.sourceforge.net/projects/xournal/">SourceForge page.</a>
 553 </p>
 554 <hr />
 555 <a name="changelog"></a>
 556 <h2 class="subtitle">Version history</h2>
 557 <p>
 558 Version 0.4.1 (Sep 15, 2007):
 559 <ul>
 560  <li> bugfix: compatibility with new versions of pdftoppm (thanks to
 561       Vincenzo Ciancia)</li>
 562  <li>GTK+ 2.11 event processing bugfix</li>
 563  <li>minor bugfixes: hand tool, handling of filenames containing '&amp;'</li>
 564  <li>desktop and MIME files (thanks to Mathieu Bouchard) + updated installer</li>
 565  <li>config options: left-handed scrollbar (contributed by Uwe Winter),
 566      hide some menu items (customizable in config file), auto-save
 567      preferences</li>
 568 </ul>
 569 </p>
 570 <p>
 571 Version 0.4.0.1 (September 3, 2007):
 572 <ul>
 573  <li>bugfixes for GTK+ 2.11 behavior (thanks to everyone who reported bugs)</li>
 574 </ul>
 575 </p>
 576 <p>
 577 Version 0.4 (August 15, 2007):
 578 <ul>
 579  <li>text tool (handles most TrueType and Type1 fonts)</li>
 580  <li>font selection dialog and button</li>
 581  <li>keyboard mappings (arrow keys)</li>
 582  <li>menu mnemonics and shortcuts (suggestions by Jean-Baptiste Rouquier)</li>
 583  <li>more responsive hand tool</li>
 584  <li>bugfix for GTK+ 2.11 XInput behavior (thanks to Robert Gerlach)</li>
 585  <li>various minor bugfixes and enhancements</li>
 586 </ul>
 587 </p>
 588 <p>
 589 Version 0.3.3 (January 31, 2007):
 590 <ul>
 591  <li>bugfix: upon loading a new file, zoom is set to default startup zoom</li>
 592  <li>config option to allow input from a mouse or other core pointer device</li>
 593  <li>config file entry to specify a default location for open/save
 594      (patch contributed by Andy Neitzke)</li>
 595  <li>config file entries to customize visibility and position of toolbars</li>
 596  <li>icon (thanks to Michele Codutti)</li>
 597 </ul>
 598 </p>
 599 <p>
 600 Version 0.3.2 (November 25, 2006):
 601 <ul>
 602  <li>preferences file and Save Preferences command</li>
 603  <li>extra customization (via preferences file)</li>
 604  <li>minor UI changes (patch contributed by Eduardo de Barros Lima)</li>
 605  <li>hand tool (partially contributed by Vincenzo Ciancia)</li>
 606  <li>a few bugfixes in rendering of bitmap backgrounds</li>
 607 </ul>
 608 <p>
 609 Version 0.3.1 (August 3, 2006):
 610 <ul>
 611  <li>fixed a file format bug on systems with non-standard numeric locale
 612      (bug reported by Gert Renckens)</li>
 613 </ul>
 614 </p>
 615 <p>
 616 Version 0.3 (July 23, 2006):
 617 <ul>
 618  <li>new PDF rendering engine: export to PDF generates optimized files
 619    (smaller and more accurate)</li>
 620  <li>export to PDF handles PDF backgrounds (up to PDF-1.4) natively
 621     (without conversion to bitmap)</li>
 622  <li>default thickness of erasers and highlighters slightly increased</li>
 623  <li>zoom dialog box with input box and "fit to page height" option</li>
 624  <li>file format documentation added to the user's manual</li>
 625 </ul>
 626 </p>
 627 <p>
 628 Version 0.2.2 (June 5, 2006):
 629 <ul>
 630  <li>mapping of tools to stylus buttons (the options menu has new entries
 631     to allow the mapping of buttons 2 and 3 to arbitrary tools; the tools
 632     menu and toolbar affect the settings for button 1)
 633     (see <a href="manual.html#mappings">here</a>)</li>
 634  <li>moving selection by drag-and-drop works across page boundaries</li>
 635  <li>vertical space tool can move items to next page (only when the entire
 636     block being moved has crossed the page boundary; items on the new page
 637     are not moved)</li>
 638  <li>"apply to all pages" is now a toggle button affecting the behavior of
 639     paper size, color, and style commands</li>
 640  <li>change in the behavior of the selection upon switching between tools</li>
 641 </ul>
 642 </p>
 643 <p>
 644 Version 0.2.1 (June 3, 2006):
 645 <ul>
 646  <li>recently used files listed in file menu</li>
 647  <li>can change color or thickness of pen strokes in selection</li>
 648  <li>function to apply paper style to all pages</li>
 649  <li>can specify on command line a PDF file to annotate</li>
 650  <li>suggest a derived file name for PDF annotation</li>
 651  <li>speed up switching between pages</li>
 652  <li>fixed a bug in XInput initialization (thanks to Luca de Cicco)</li>
 653  <li>fixed a bug in print ranges (thanks to Mathieu Bouchard)</li>
 654  <li>fixed a refresh bug in rescaling bitmap backgrounds</li>
 655 </ul>
 656 </p>
 657 <p>
 658 Version 0.2 (January 29, 2006):
 659 <ul>
 660  <li>PDF file annotation using xpdf's pdftoppm
 661       (PDF backgrounds updated asynchronously at all resolutions)</li>
 662  <li>PS/PDF backgrounds (as bitmaps at fixed resolution) using ghostscript</li>
 663  <li>option to antialias and filter bitmap backgrounds when zooming</li>
 664  <li>option to emulate eraser tip with right mouse button</li>
 665  <li>binary installer allows non-root installation without compiling</li>
 666  <li>full-screen mode (patch contributed by Luca De Cicco)</li>
 667 </ul>
 668 </p>
 669 <p>
 670 Version 0.1.1 (January 5, 2006):
 671 <ul>
 672  <li> two bugfixes </li>
 673  <li> backward compatibility with GTK+ 2.4 </li>
 674 </ul>
 675 </p>
 676 <p>
 677 Version 0.1 (January 2, 2006): initial release.
 678 </p>
 679 <hr />
 680 <a name="file-format"></a>
 681 <h2 class="subtitle">The file format</h2>
 682 <h3 class="subsub">Overall structure</h3>
 683 <p>
 684 Xournal stores its data in gzipped XML-like files. The gzipped data consists
 685 of a succession of XML tags describing the document. By convention, the
 686 file header and trailer look like this:
 687 <pre>
 688 &lt;?xml version="1.0" standalone="no"?&gt;
 689 &lt;xournal version="..."&gt;
 690 &lt;title&gt;Xournal document - see http://math.mit.edu/~auroux/software/xournal/&lt;/title&gt;
 691 ... sequence of pages ...
 692 &lt;/xournal&gt;
 693 </pre>
 694 The &lt;title&gt; and &lt;xournal&gt; tags may only appear within the file
 695 header (not within the pages of the document). The <i>version</i> attribute of
 696 the &lt;xournal&gt; tag indicates which version of Xournal was used to
 697 create the document; it is currently ignored, but may be used in a later
 698 release if the file format changes in an incompatible manner.
 699 (Following a suggestion of Matteo Abrate, starting with version 0.4 the
 700 &lt;xournal&gt; tag is the document's root tag, and encloses all other tags).
 701 </p>
 702 <p>
 703 The rest of the file is a sequence of pages, specified by a
 704 &lt;page&gt; tag, whose attributes <i>width</i> and <i>height</i> specify the
 705 physical size of the page in points (1/72 in). The width and height
 706 parameters are floating point values. The format of a page is therefore:
 707 <pre>
 708 &lt;page width="..." height="..."&gt;
 709 ... page contents ...
 710 &lt;/page&gt;
 711 </pre>
 712 </p>
 713 <h3 class="subsub">Page background</h3>
 714 <p>
 715 The first entry within a page describes the page background.
 716 It consists of a &lt;background&gt; tag followed by several mandatory
 717 XML attributes. The first attribute is always <i>type</i>, which
 718 can take three possible values: "solid" for a solid background, "pixmap"
 719 for a bitmap background, and "pdf" if the background is a page of a PDF
 720 document. The rest of the attributes depends on the type of background.
 721 <ul>
 722 <li><p> Solid background: <tt>&lt;background type="solid" color="..."
 723 style="..." /&gt;</tt> <br />The <i>color</i> attribute takes one of
 724 the standard values "white", "yellow", "pink", "orange", "blue", "green",
 725 or can specify a hexadecimal RGBA value in the format "#rrggbbaa". The
 726 <i>style</i> attribute takes one of the standard values "plain", "lined",
 727 "ruled", or "graph".</p>
 728 </li>
 729 <li><p> Bitmap background: <tt>&lt;background type="pixmap" domain="..."
 730 filename="..." /&gt;</tt> <br />
 731 The <i>domain</i> attribute takes one of the standard values "absolute",
 732 "attach", or "clone". A value of "absolute" indicates that the bitmap is
 733 found in the file specified by <i>filename</i>. The bitmap can be in any
 734 format recognized by the gdk-pixbuf library; this includes most of the
 735 common bitmap formats (JPEG, PNG, BMP, GIF, PCX, PNM, TIFF, ...).
 736 <br />A value
 737 of "attach" indicates that the bitmap is an attachment to the Xournal file.
 738 The bitmap is in PNG format, and resides in a file whose name is derived
 739 from that of the main Xournal file by appending to it a dot and the contents
 740 of the <i>filename</i> attribute. For example, if the Xournal file is in
 741 <tt>file.xoj</tt> and the <i>filename</i> attribute is <tt>"bg_1.png"</tt>
 742 then the bitmap file is <tt>file.xoj.bg_1.png</tt> (Xournal saves attached
 743 bitmaps sequentially in files ...bg_1.png, ...bg_2.png, etc.)
 744 <br />A value of "clone" indicates that the bitmap is identical to the
 745 background of a previous page of the journal; the <i>filename</i> attribute
 746 then specifies the page number, starting with 0 for the first page. For
 747 example, if a <i>filename</i> value of <tt>"1"</tt> indicates that the
 748 background bitmap is identical to that of the second page.
 749 </p>
 750 </li>
 751 <li><p> PDF background: <tt>&lt;background type="pdf" domain="..."
 752 filename="..." pageno="..." /&gt;</tt> or
 753 <tt>&lt;background type="pdf" pageno="..." /&gt;</tt>
 754 <br />The <i>domain</i> and <i>filename</i> attributes must be specified
 755 for the first page of the journal that uses a PDF background, and must
 756 be omitted subsequently for every other page that uses a PDF background.
 757 The <i>domain</i> attribute takes one of the standard values
 758 "absolute" and "attach"; the PDF document is to be found in the file
 759 specified by <i>filename</i> (if <i>domain</i> is "absolute"), or in the
 760 file whose name is obtained by appending a dot and the contents of the
 761 <i>filename</i> attribute to the name of the main Xournal file (if
 762 <i>domain</i> is "attach"). The <i>pageno</i> attribute specifies which
 763 page of the PDF file is used as background, starting with 1 for the first
 764 page of the PDF file.
 765 </p>
 766 </li>
 767 </ul>
 768 </p>
 769 <h3 class="subsub">Layers and strokes</h3>
 770 <p>
 771 After the line specifying the background, the remainder of a &lt;page&gt;
 772 section is occupied by one or more layer sections
 773 <pre>&lt;layer&gt; ... &lt;/layer&gt;</pre>
 774 describing the various items within a layer. Every page must
 775 contain at least one layer; a layer may be empty. The successive layers
 776 are listed in their stacking order, from bottom to top.
 777 </p>
 778 <p>
 779 A layer consists of a collection of items, listed in the order in which
 780 they should be drawn
 781 (from bottom-most to top-most).
 782 Up to version 0.3.3, the only legal contents within a layer are
 783 strokes. The format of a stroke is:
 784 <pre>&lt;stroke tool="..." color="..." width="..."&gt;
 785 ... list of coordinates ...
 786 &lt;/stroke&gt;
 787 </pre>
 788 The <i>tool</i> attribute can take the values "pen", "highlighter", or
 789 "eraser" depending on the tool used to create the stroke (pen, highlighter,
 790 or whiteout eraser); a value of "highlighter" indicates that the stroke
 791 should be painted in a partially transparent manner (Xournal uses an alpha
 792 coefficient of 0.5).
 793 The <i>color</i> attribute can take one of the standard values "black",
 794 "blue", "red", "green", "gray", "lightblue", "lightgreen", "magenta",
 795 "orange", "yellow", "white", or can specify a hexadecimal RGBA value in
 796 the format "#rrggbbaa". The <i>width</i> attribute is a floating-point
 797 number and specifies the width of the stroke in points (1/72 in).
 798 </p>
 799 <p>
 800 The list of coordinates is simply a succession of floating-point values,
 801 separated by whitespace.
 802 The number of given values must be even; consecutive pairs of values give
 803 the <i>x</i> and <i>y</i> coordinates of each point along the stroke.
 804 These values are expressed in points (1/72 in). The coordinates (0,0)
 805 represent the top-left corner of the page: hence x is measured from the left
 806 of the page, and y is measured from the top of the page.
 807 </p>
 808 <p>
 809 Every stroke must contain at least two points (four floating point values).
 810 Moreover, two consecutive points on the stroke should be spaced no more
 811 than 5 units apart or so; longer line segments should be subdivided as
 812 appropriate (otherwise the eraser tool will not interact properly with the
 813 stroke). The default precision used by Xournal for the x,y coordinates is
 814 0.01 unit (1/7200 in).
 815 </p>
 816 <p>Starting with version 0.4, layers also contain text items.
 817 The format of a text item is:
 818 <pre>&lt;text font="..." size="..." x="..." y="..." color="..."&gt;... text ...&lt;/text&gt;
 819 </pre>
 820 The <i>font</i> attribute contains the font name, for example "Serif Bold
 821 Italic"; if the font is not available, another font will be substituted.
 822 The <i>size</i> attribute specifies the font size in points. The <i>x</i>
 823 and <i>y</i> attributes specify the coordinates of the top-left corner
 824 of the text box in page coordinates (measured in points from the top-left
 825 corner of the page). Finally, the <i>color</i> attribute contains either
 826 the name of a standard color or a hexadecimal RGBA value (see above).
 827 </p>
 828 <p>
 829 The contents of the text are encoded in UTF-8, with the characters
 830 <tt>'&amp;', '&lt;', '&gt;'</tt> replaced by <tt>&amp;amp;, &amp;lt;,
 831 &amp;gt;</tt>. Whitespace and linefeeds are preserved (in particular,
 832 no extraneous whitespace should be inserted between the enclosing tags
 833 and the text itself).
 834 </p>
 835 <hr />
 836 <a name="installation"></a>
 837 <h2 class="subtitle">Installation issues</h2>
 838 <h3 class="subsub">Dependencies</h3>
 839 <p>
 840 The following libraries are required to run Xournal (they are standard on
 841 modern Linux distributions such as Fedora Core 3 or later, or RHEL 4 or
 842 later):
 843 <ul>
 844  <li> the <b>gtk+</b> libraries, version <b>2.4</b> or later
 845        (2.6 recommended) &nbsp; (package gtk2 and dependencies)</li>
 846  <li> <b>libgnomecanvas</b> version <b>2.4</b> or later &nbsp;
 847        (package libgnomecanvas and dependencies)</li>
 848  <li> <b>libgnomeprint</b> and <b>libgnomeprintui</b> version <b>2.2</b> or later &nbsp;
 849        (packages libgnomeprint22, libgnomeprintui22, and dependencies) </li>
 850 </ul>
 851 </p>
 852 <p>
 853  Additionally:
 854 <ul>
 855  <li> <b>xpdf</b> (more precisely, <b>pdftoppm</b>) is required for PDF file
 856 annotation</li>
 857  <li> <b>ghostscript</b> (optional: used to import PS/PDF files as bitmap
 858  backgrounds)</li>
 859 </ul>
 860 <p>
 861 To compile Xournal, you also need the <b>development packages</b> for the above
 862 libraries (packages gtk2-devel, libgnomecanvas-devel, libgnomeprint22-devel,
 863 libgnomeprintui22-devel, and dependencies), as well as <b>autoconf</b> and
 864 <b>automake</b>.
 865 </p>
 866 <h3 class="subsub">Compilation and installation procedure</h3>
 867 <p>
 868 Download the Xournal distribution tar.gz file, and any needed dependencies.
 869 </p>
 870 <p>
 871 <b>Binary installation in /usr/local:</b><br />
 872 Run (as root) the installer script
 873 <pre>./install-binary</pre> (and upgrade GTK+ and the other libraries if needed).
 874 </p>
 875 <p>
 876 <b>Binary installation in home directory:</b><br />
 877 Run (as any user) the installer script
 878 <pre>./install-binary</pre> (and hope that the required libraries are
 879 installed on your system).
 880 </p>
 881 <p>
 882 <b>Compilation and installation in /usr/local:</b>
 883 <pre>
 884 ./autogen.sh
 885 make
 886 (as root) make install
 887 (as root) make desktop-install
 888 </pre>
 889 </p>
 890 <p>
 891 <b>Compilation and installation in $HOME:</b>
 892 <pre>
 893 ./autogen.sh
 894 ./configure --prefix=$HOME
 895 make
 896 make install
 897 make home-desktop-install
 898 </pre>
 899 </p>
 900 <p><b>Configure error message:</b> <br />
 901 If autogen.sh generates the error message
 902 &nbsp; &nbsp; <tt><i>
 903 configure: error: Library requirements (gtk+-2.0 >= 2.4.0 libgnomecanvas-2.0 >= 2.4.0 libgnomeprintui-2.2 >= 2.0.0) not met
 904 </i></tt> &nbsp; &nbsp;
 905 even though you have sufficiently recent versions of these libraries on your
 906 system, then you need to install some missing development packages.
 907 </p>
 908 <hr />
 909 <a name="calibration"></a>
 910 <h2 class="subtitle">Tablet calibration issues</h2>
 911 <p>
 912 Configuring the tablet devices properly is unfortunately not as simple as it
 913 ought to be. This is a subject worthy of a detailed how-to document;
 914 meanwhile, here are some hints about how to configure your tablet.
 915 </p>
 916 <h3 class="subsub">Basics</h3>
 917 <p>
 918 Xournal uses the XInput extension to obtain high-resolution coordinates for
 919 strokes drawn using the stylus. If you decide that getting just the right
 920 XInput configuration isn't worth the effort, you can disable XInput features
 921 by unsetting the "Use XInput" option in the Options menu. The price to pay
 922 is a lower graphics quality, as the resolution of all strokes then drops to
 923 1 pixel (instead of the native resolution of the tablet device, which can
 924 be higher by several orders of magnitude).
 925 </p>
 926 <p>
 927 The configuration of tablet devices is controlled in the X server's
 928 configuration file (usually <b>XF86Config</b> or <b>xorg.conf</b> depending on your
 929 distribution). The ServerLayout section should contain lines like:
 930 <pre>
 931 Section "ServerLayout"
 932         ...
 933         InputDevice    "cursor" "SendCoreEvents"
 934         InputDevice    "stylus" "SendCoreEvents"
 935         InputDevice    "eraser" "SendCoreEvents"
 936 EndSection
 937 </pre>
 938 (the last one only if your stylus has an eraser tip), and your configuration
 939 file should include sections such as
 940 <pre>
 941 Section "InputDevice"
 942         Identifier "cursor"
 943         Driver "wacom"
 944         Option "Device" "/dev/ttyS0"
 945         Option "Type" "cursor"
 946         Option "ForceDevice" "ISDV4"
 947         Option "BottomX" "28800"
 948         Option "BottomY" "21760"
 949         Option "Mode" "absolute"
 950 EndSection
 951
 952 Section "InputDevice"
 953         Identifier "stylus"
 954         Driver "wacom"
 955         Option "Device" "/dev/ttyS0"
 956         Option "Type" "stylus"
 957         Option "ForceDevice" "ISDV4"
 958         Option "BottomX" "28800"
 959         Option "BottomY" "21760"
 960         Option "Mode" "absolute"
 961 EndSection
 962
 963 Section "InputDevice"
 964         Identifier "eraser"
 965         Driver "wacom"
 966         Option "Device" "/dev/ttyS0"
 967         Option "Type" "eraser"
 968         Option "ForceDevice" "ISDV4"
 969         Option "BottomX" "28800"
 970         Option "BottomY" "21760"
 971         Option "Mode" "absolute"
 972 EndSection
 973 </pre>
 974 The actual settings will depend on your hardware; look on the web for Linux
 975 installation instructions specific to your model: for example, the
 976 "Device" settings above correspond to a serial port protocol, many tablets
 977 use USB instead; the BottomX and BottomY values correspond to the physical
 978 resolution of the tablet and will vary from one model to another.
 979 </p>
 980 <p>
 981 For historical reasons, most X servers do not allow the input device
 982 designated as the "core pointer" in the X server's configuration file
 983 to be used as an XInput extension device. Thus, your tablet input devices
 984 should <b>not</b> be designated as the core pointer device. Instead, they
 985 should be configured with the "SendCoreEvents" option, which enables them
 986 to simultaneously generate XInput extension events and move the cursor on
 987 the screen. Since high-resolution coordinates cannot be obtained for the
 988 core pointer device, it is disabled in Xournal by default.
 989 Starting with version 0.3.3,
 990 it is possible to have core events processed alongside with extension
 991 events (uncheck "Discard Core Events" in the Options menu); however, in
 992 some rare cases this may lead to a loss of resolution on all devices.
 993 </p>
 994 <h3 class="subsub">The cursor doesn't appear in the right place...</h3>
 995 <p>
 996 If the mouse pointer does not follow accurately the position of the stylus,
 997 this is an indication that your tablet is not properly calibrated. If you
 998 have the linuxwacom package, you can try modifying the tablet calibration
 999 using <b>xsetwacom</b>. The relevant parameters are named TopX, BottomX,
1000 TopY, BottomY, and need to be set separately for the stylus and for the
1001 eraser. For example:
1002 <pre>
1003     xsetwacom set stylus TopX 270
1004     xsetwacom set stylus BottomX 28510
1005     ...
1006 </pre>
1007 (the TopX and TopY parameters default to 0 if you haven't set them in your
1008 X server's configuration file). Experiment with these parameters until you
1009 find the right calibration settings for your tablet (i.e., the mouse pointer
1010 appears right under the tip of the stylus).
1011 </p>
1012 <p>
1013 Once you have found the perfect settings for your tablet, update your X
1014 server's configuration file (due to issues with some versions of the
1015 linuxwacom driver, the tablet calibration information is often not updated
1016 properly when using xsetwacom).
1017 </p>
1018 <p>
1019 <b>Important:</b> due to issues with the linuxwacom driver, it is important
1020 to either upgrade your driver to a <a href="manual.html#wacompatch">patched
1021 version</a>, or restrict your choice of settings as follows:
1022 <ul>
1023 <li> your calibration settings should not be changed at runtime (i.e.,
1024 insert your settings directly into your X server configuration file.
1025 Do not add a list of xsetwacom commands to your startup files).
1026 </li>
1027 <li> TopX and TopY values should always be 0.
1028 </li>
1029 </ul>
1030 </p>
1031 <h3 class="subsub">Strokes aren't drawn under the cursor...</h3>
1032 <p>
1033 This is due to misfeatures in the linuxwacom driver in versions prior
1034 to 0.7.6. Typically, this will happen in all of the following cases:
1035 <ul>
1036 <li> the calibration settings have been changed after the X server was
1037 started (using xsetwacom) </li>
1038 <li> the calibration TopX or TopY values are not 0 </li>
1039 <li> the display has been rotated </li>
1040 </ul>
1041 Most of these issues should have been fixed in version 0.7.6 of the
1042 wacom driver. Otherwise, you can
1043 either disable XInput support in Xournal (in the Options menu), at a
1044 price of a severe loss of resolution (and the eraser tip won't be detected
1045 anymore), or apply this <a href="manual.html#wacompatch">patch</a>
1046 to version 0.7.0 of the wacom driver.
1047 </p>
1048 <p>
1049 I have also had a report that one of the workarounds used by Xournal to
1050 bypass a calibration bug in GTK+ can actually entirely prevent strokes
1051 from being drawn. If you are being unsuccessful at drawing in Xournal
1052 with XInput enabled, try recompiling after changing the first line of
1053 <tt>src/main.c</tt> to
1054 <pre>#define ENABLE_XINPUT_BUGFIX 0</pre>
1055 If this modification does improve things for you, and if you have a bit
1056 of spare time to help investigate the causes of this problem, please
1057 contact me.
1058 </p>
1059 <h3 class="subsub">On-the-fly display rotation</h3>
1060 <p>
1061 You need an X server that supports the RANDR extension, and a
1062 recent (0.7.6 or later) or <a href="manual.html#wacompatch">patched</a>
1063 version of the linuxwacom driver to support on-the-fly rotation.
1064 </p>
1065 <p>
1066 To set the tablet in portrait mode:
1067 <pre>
1068   xrandr -o 3
1069   xsetwacom set stylus Rotate cw
1070 </pre>
1071 To return to landscape mode:
1072 <pre>
1073   xrandr -o 0
1074   xsetwacom set stylus Rotate none
1075 </pre>
1076 <b>Note:</b> you should not rotate the display while Xournal is running,
1077 otherwise the tablet calibration in Xournal may (and most likely will)
1078 become incorrect.
1079 Exit Xournal and restart it after the display has been rotated.
1080 </p>
1081 <a name="wacompatch"></a>
1082 <h3 class="subsub">Linuxwacom patch for calibration and rotation</h3>
1083 <p>
1084 This patch fixes rotation and calibration issues with the linuxwacom driver
1085 version 0.7.0.
1086 <ul>
1087 <li>The <a href="http://xournal.sourceforge.net/linuxwacom-0.7.0-rotate-patch">patch
1088 file</a> for the linuxwacom source code (also included with the Xournal
1089 distribution).</li>
1090 <li>The <a href="http://xournal.sourceforge.net/linuxwacom-rotate-patch.tar.gz">patched
1091 binaries</a> for the X.org X server.</li>
1092 </ul>
1093 This patch has been included in version 0.7.6 of the linuxwacom driver,
1094 and should now be obsolete.
1095 </p>
1096 </body>
1097 </html>