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