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.2
  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://math.mit.edu/~auroux/software/xournal/">http://math.mit.edu/~auroux/software/xournal/</a>
  42 </p>
  43 <p>
  44  Xournal aims to provide superior graphical quality (subpixel resolution) and overall
  45  functionality; however it lacks the collaborative features of Jarnal.
  46  Since Xournal is still in its early development stages, it may not
  47  be fully stable, and some features have not been implemented yet
  48  (in particular, freeform selection and PDF backgrounds are missing).
  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#author">Author information, license, bug-reports</a> </li>
  58   <li> <a href="manual.html#changelog">Version history</a> </li>
  59   <li> <a href="manual.html#file-format">The file format</a> </li>
  60   <li> <a href="manual.html#installation">Installation issues</a> and
  61        <a href="manual.html#calibration">tablet calibration issues</a> </li>
  62  </ul>
  63 </p>
  64 <hr />
  65 <a name="getting-started"></a>
  66 <h2 class="subtitle">Getting started</h2>
  67 <p>
  68  Xournal's user interface is (hopefully) intuitive, and if you don't run
  69  into <a href="manual.html#installation">installation</a> or
  70  <a href="manual.html#calibration">tablet calibration</a> issues, you'll
  71  probably be able to start taking notes without referring to this manual.
  72  <br />
  73  Here is a screenshot of the user interface (click to enlarge):
  74 </p>
  75 <p style="text-align: center">
  76  <a href="screenshot.png">
  77    <img src="screenshot.png" style="width: 321px; height: 176px" />
  78  </a>
  79 </p>
  80 <p>
  81 Refer the next few sections of this manual for more information about
  82 the various functionalities.
  83 </p>
  84 <hr />
  85 <a name="tools"></a>
  86 <h2 class="subtitle">The drawing and selection tools</h2>
  87 <h3 class="subsub"><img src="pixmaps/pencil.png"> The pen</h3>
  88 <p>
  89 The pen is the default drawing tool in Xournal. It comes in a variety
  90 of colors (see the color toolbar buttons and the Color submenu of the
  91 Tools menu) and thicknesses (see the
  92 <a href="manual.html#thicknesses">thickness</a> toolbar buttons and
  93 the Pen Options submenu of the Tools menu).
  94 </p>
  95 <h3 class="subsub"><img src="pixmaps/eraser.png"> The eraser</h3>
  96 <p>
  97 The eraser lets you erase what you have drawn. If your tablet's stylus
  98 has an eraser tip, and if the XInput extensions are enabled, the eraser
  99 will be automatically selected when drawing with the eraser tip.
 100 Another possibility is to enable the "Emulate Eraser" option in the Options
 101 menu, which lets you use button 2 or 3 on the stylus (mouse middle or right button)
 102 as an eraser.<br />
 103 The eraser comes in three different thicknesses (selected using the
 104 <a href="manual.html#thicknesses">thickness</a> toolbar buttons),
 105 and can operate in three different modes (Eraser Options submenu of
 106 the Tools menu):
 107 <ul>
 108  <li>
 109    Standard mode (default): the eraser deletes portions
 110    of strokes previously drawn using the pen or the highlighter.
 111    In this mode, if you erase in the middle of a stroke, the remaining
 112    portions of the stroke are automatically split into shorter strokes.
 113    The background of the page (and the lower layers) are not erased.
 114  </li>
 115  <li>
 116    Whiteout: the eraser is actually a thick white pen, and simply covers
 117    whatever lies underneath, including the background of the page.
 118  </li>
 119  <li>
 120    Delete strokes: whenever the eraser comes in contact with a previously
 121    drawn stroke, the entire stroke is deleted.
 122   </li>
 123 </ul>
 124 </p>
 125 <h3 class="subsub"><img src="pixmaps/highlighter.png"> The highlighter</h3>
 126 <p>
 127   Like the pen, the highlighter comes in a variety of colors (the default
 128   is yellow) and thicknesses. Use the color and thickness toolbar buttons
 129   to change these settings.
 130 </p>
 131 <h3 class="subsub"><img src="pixmaps/ruler.png"> The ruler</h3>
 132 <p>
 133   The ruler is not a tool by itself, but rather a special operating mode
 134   of the pen and highlighter tools. When it is enabled, these tools paint
 135   line segments instead of curvy strokes. For simplicity, selecting the
 136   ruler when not in pen or highlighter mode automatically selects the pen.
 137 </p>
 138 <h3 class="subsub"><img src="pixmaps/recycled.png"> Default tools</h3>
 139 <p>
 140   Each drawing tool (pen, eraser, highlighter) has a default setting
 141   (color, thickness, ...) associated to it.
 142   The "Default Pen", "Default Eraser", and "Default Highlighter" entries of
 143   the Tools menu select the appropriate tool and reset its settings to
 144   the defaults. The toolbar also includes a "Default" button which
 145   resets the currently selected drawing tool to its default settings,
 146   and a "Default Pen" button. <br />
 147   The "Set As Default" entry of the Tools menu takes the current settings
 148   of the currently selected drawing tool and makes them the new default.
 149 </p>
 150 <a name="thicknesses"></a>
 151 <h3 class="subsub"><img src="pixmaps/thin.png"> <img src="pixmaps/medium.png">
 152   <img src="pixmaps/thick.png"> Thickness buttons</h3>
 153 <p>
 154   These three buttons control the thickness of the current drawing tool
 155   (pen, eraser, or highlighter). The thickness can also be adjusted using
 156   the appropriate sub-menu of the Tools menu.
 157 </p>
 158 <h3 class="subsub"><img src="pixmaps/rect-select.png"> Rectangle selection</h3>
 159 <p>
 160   This tool lets you select a rectangular region of the current layer.
 161   All the strokes which are entirely contained within the rectangular region
 162   are selected.
 163   The selection can be moved within its page by clicking inside the
 164   selection rectangle and dragging the cursor.
 165 </p>
 166 <p>
 167   The selection can be cut, duplicated, etc. (including to a different page
 168   or to a different journal) using the copy-paste toolbar buttons or the
 169   corresponding entries of the Edit menu.
 170 </p>
 171 <h3 class="subsub"><img src="pixmaps/stretch.png"> Vertical space</h3>
 172 <p>
 173   This tool lets you insert or remove vertical space within the page:
 174   all the items of the current layer which lie entirely between the cursor
 175   position and the end of the page are moved up or down.
 176 </p>
 177 <p>
 178   Note that the background, and items on other layers, are not affected.
 179   Also, if you insert too much vertical space, some items may fall below
 180   the bottom of the page and become invisible. These items are not lost:
 181   to retrieve them, either use
 182   the vertical space tool again to remove the excess vertical
 183   space, or change the page height to an appropriate value (using the
 184   "Paper Size" entry in the Journal menu).
 185 </p>
 186 <h3 class="subsub">Undo and redo</h3>
 187 <p>
 188   All operations performed on the currently open journal (drawing, erasing,
 189   cut-and-paste; adding, deleting, and reformatting pages; etc.) can be
 190   undone and redone at will using the Undo and Redo toolbar buttons or
 191   the corresponding entries in the Edit menu.<br />
 192   There is no limit to the depth of the undo/redo stack. It is cleared only
 193   when you quit the application or open a new journal.
 194 <hr />
 195 <a name="pages-layers"></a>
 196 <h2 class="subtitle">Pages, layers, and backgrounds</h2>
 197 <p>
 198 A journal is composed of one or more pages, whose characteristics can be
 199 modified independently of each other. Each page consists of a background
 200 and one or more layers stacked on top of the background. All drawing
 201 operations take place within a single layer, and do not affect the background
 202 or the other layers. You can think of the layers as transparent overlays:
 203 drawing and erasing always takes place on the topmost visible overlay.
 204 <br />
 205 Layers are a convenient mechanism to add temporary annotations on top of a
 206 journal page: because of the logical separation between layers, erasing
 207 in the top layer will not affect the contents of the other layers, and
 208 the top layer can be easily discarded.
 209 </p>
 210 <h3 class="subsub">Navigating the journal</h3>
 211 <p>
 212 The user interface either displays all pages in the journal below each other
 213 ("continuous mode") or a single page ("one-page mode"). You can switch
 214 between the two modes by using the "Continuous" and "One page" entries in
 215 the View menu. The default is the
 216 continuous mode, best adapted to note-taking on multiple pages. The one-page
 217 mode is more appropriate if your journal is a scrapbook in which the pages
 218 have different characteristics (in particular, if you are annotating a
 219 series of pictures of different sizes).
 220 </p>
 221 <p>
 222 You can navigate the journal pages in several different ways:
 223 <ul>
 224  <li> using the navigation toolbar buttons (or the corresponding entries
 225   in the View menu) to go back or forward one page, or to jump to the first
 226   or last page of the journal;
 227  </li>
 228  <li> in continuous mode, scrolling down to the desired page;
 229  </li>
 230  <li> entering a value or using the +/- buttons in the page selection box
 231   at the lower-left corner of the Xournal window.
 232  </li>
 233 </ul>
 234 As a convenient shortcut, going forward one page (or pressing the + button
 235 in the selection box) when already at the end of the journal creates a new
 236 page at the end of the journal.
 237 </p>
 238 <p>
 239 Note: jumping to a page automatically selects the top-most layer in
 240 that page.
 241 </p>
 242 <p>
 243 To navigate the layers of a page, either use the layer selection box at
 244 the bottom of the Xournal window, or use the "Show Layer" and "Hide Layer"
 245 entries in the View menu. The basic rule to remember is that the display
 246 shows all the layers underneath the currently select one, and while those
 247 above it are hidden.
 248 </p>
 249 <p>
 250 Note: the background layer cannot be drawn on; any attempt to draw on the
 251 background will generate an error message and switch back to the first
 252 layer.
 253 </p>
 254 <h3 class="subsub">Managing pages and layers</h3>
 255 <p>
 256 Pages can be added to the journal by using the "New Page ..." entries in
 257 the Journal menu. The newly created page has the same format and background as the
 258 current page (for the "New Page Before" and "New Page After" commands), or
 259 as the last page of the journal (for "New Page At End"). Additionally,
 260 jumping to the next page when already on the last page creates a new page
 261 at the end of the journal.
 262 </p>
 263 <p>
 264 The "Delete Page" entry in the Journal menu removes the current page from
 265 the journal. (Remember that you can always undo this operation if you
 266 deleted a page by accident).
 267 </p>
 268 <p>
 269 The "New Layer" entry in the Journal menu creates a new layer immediately
 270 above the current one, while "Delete Layer" removes the current layer and
 271 its contents (if you attempt to delete the only layer of a page, a new
 272 empty layer will be automatically created).
 273 </p>
 274 <h3 class="subsub">Paper formats and backgrounds</h3>
 275 <p>
 276 The size of the current page can be modified using the "Paper Size" entry
 277 in the Journal menu. Standard and custom sizes are available.
 278 </p>
 279 <p>
 280 The background is either one of several kinds of standard paper types, or a
 281 bitmap image, or a page of a PDF file.
 282 </p>
 283 <p>
 284 To select a <b>standard paper type</b> as background for the current page, use
 285 the "Paper Style" submenu of the Journal menu. The paper color can also
 286 be changed using the "Paper Color" submenu of the Journal menu.
 287 </p>
 288 <p>
 289 To use a <b>PDF file</b> as the background for a journal, see the paragraph
 290 on <a href="manual.html#pdfannotate">PDF annotation</a> below.
 291 </p>
 292 <p>
 293 To load a <b>bitmap image file</b> for use as background for the current page, use
 294 the "Load Background" entry of the Journal menu. This automatically
 295 resizes the current page according to the size of the bitmap image, and
 296 resets the zoom level to 100%. If <i>ghostscript</i> is installed on your
 297 system, you can also use this method to import a fixed-resolution bitmap
 298 version of a Postscript or PDF file; in that case, all pages will be
 299 imported sequentially as backgrounds into consecutive pages (this is not the
 300 recommended method; PDF annotation is better in many respects).
 301 </p>
 302 <p>
 303 To capture a <b>screenshot</b> of a window or the entire screen and make it
 304 the background of the current page, use the "Background Screenshot" entry of
 305 the Journal menu. This will iconify the Xournal window; click in any window
 306 (after ensuring it is fully visible) to capture its contents, or click on
 307 the desktop (or screen background) to capture the entire screen.
 308 </p>
 309 <p><b>Important note:</b> by default, bitmap images loaded using the "Load
 310 Background" command will not be saved with the journal; instead, the journal
 311 file will contain a reference to the absolute location of the image file.
 312 This means that the background will become unavailable if the image file
 313 is moved or deleted. To avoid this, check the option "Attach file to the
 314 journal" at the bottom of the file selection dialog box.<br />
 315 This option only applies to bitmap image files loaded from disk;
 316 screenshot backgrounds (and bitmaps converted from PS/PDF files using
 317 ghostscript) are automatically "attached" to the journal file: when the
 318 journal is saved, they will be saved (in PNG format) along with it
 319 (using file names of the form *.xoj.bg_*.png).
 320 </p>
 321 <p>
 322 <b>Rescaling and anti-aliasing:</b> by default,
 323 bitmap backgrounds are rescaled and anti-aliased as needed when the zoom
 324 level is changed, to ensure their appearance always remains acceptable.
 325 Because this consumes a lot of memory and CPU resources, by default this
 326 rescaling is performed on-demand as each page becomes visible. This means
 327 that you will occasionally notice bitmap backgrounds being smoothed while
 328 you are scrolling inside the document (at large zoom levels, this can slow
 329 down the screen refresh rate noticeably). If you'd prefer all backgrounds to
 330 be rescaled immediately upon changing the zoom level (slower but maybe more
 331 intuitive), disable the "Progressive Backgrounds" option in the Options
 332 menu.<br />
 333 If you are handling large bitmaps, you can save memory and CPU resources (at the
 334 expense of quality) by disabling the "Antialiased Bitmaps" option in the Options menu.
 335 </p>
 336
 337 <a name="pdfannotate"></a>
 338 <h3 class="subsub">PDF annotation</h3>
 339 <p>
 340 Xournal can be used to annotate PDF files, by loading the pages of a PDF
 341 file as backgrounds for a journal. This feature requires the
 342 <i>pdftoppm</i> converter to be installed (this is part of the <i>xpdf</i>
 343 &nbsp;PDF file viewer).
 344 </p>
 345 <p>
 346 The "Annotate PDF" command in the File menu can be used to load a PDF file
 347 into a new (empty) journal. The page backgrounds and page sizes correspond
 348 to the contents of the PDF file. (Most unencrypted PDF files should be
 349 supported).
 350 </p>
 351 <p>
 352 By default, the PDF file used to generate the backgrounds
 353 will not be saved with the journal; instead, the journal
 354 file will contain a reference to the absolute location of this file.
 355 This means that all backgrounds will become unavailable if the PDF file
 356 is moved or deleted (although Xournal will let you specify
 357 the updated location of the PDF file when opening the journal
 358 file). To avoid this, check the option "Attach file to the journal"
 359 at the bottom of the dialog box when opening the PDF file. The PDF file will
 360 then be saved along with the journal (using a file name of the form
 361 *.xoj.bg.pdf).
 362 <p>
 363 Upon zooming, the page backgrounds are asynchronously updated
 364 to fit the current display resolution. Since this process is quite slow and
 365 memory-intensive, the pages are normally updated only as needed, when they
 366 become visible on the screen (unless you disable the "Progressive
 367 Backgrounds" option in the Options menu). This means that you will
 368 occasionally notice the page backgrounds being updated while you are
 369 scrolling inside the document (at large zoom levels, it can take a while
 370 for the updated background to appear). However, since the backgrounds are
 371 generated asynchronously by a separate Unix process, you can keep drawing in the journal
 372 while the update process is still in progress.
 373 </p>
 374 <p>
 375 It is strongly recommended that you do not resize PDF pages (using the
 376 "Paper Size" command). This will result in extremely ugly rendering, as
 377 the PDF converter is unable to render bitmaps with
 378 non-standard aspect ratios.
 379 </p>
 380 <p>
 381 While you can perform all sorts of page operations on a journal file
 382 that was created from a PDF file (such as duplicating or deleting pages,
 383 inserting pages with blank or bitmapped backgrounds, ...), it is not
 384 possible to include pages from more than one PDF file into a single journal
 385 document. If you need to annotate two or more PDF files inside a same
 386 journal document, please consider using an external utility for merging
 387 PDF files (for example <i>pdfmerge</i>).
 388 <hr />
 389 <a name="printing"></a>
 390 <h2 class="subtitle">Printing</h2>
 391 <p>
 392 Xournal uses the gnome-print architecture for printing. While it is very
 393 powerful, some aspects of the API leave to be desired,
 394 and future versions of Xournal will probably also include a native
 395 Postscript/PDF printing feature.
 396 </p>
 397 <p>
 398 The "Printer" tab of the print dialog box lets you select a printer
 399 (either one of the printers installed on your system, or the generic
 400 Postscript printer, or the PDF virtual printer). The "Job" tab lets you
 401 select a range of pages to print (the default is to print the entire
 402 journal). The "Paper" tab lets you select the paper size. Each page
 403 of the journal is automatically rescaled so as to fit the paper size.
 404 (minus a 5% margin all around).
 405 </p>
 406 <p>
 407 The settings are currently not saved properly from one print job to
 408 the next, so make sure to select the appropriate printer and verify
 409 the paper size. When printing to a file (Postscript or PDF), Xournal
 410 attempts to pre-fill the output file name (for the Postscript driver
 411 this often fails due to gnome-print API issues).
 412 </p>
 413 <p>
 414 The "Print to PDF" entry of the File menu directly generates a PDF file
 415 using the PDF virtual printer, without bringing up the dialog box
 416 (the page size is the default one for that printer, usually A4).
 417 Note that the PDF virtual printer produces files that are very large
 418 and far from optimal, so in the current state of things it is better
 419 to generate a Postscript file and use a converter such as ps2pdf.
 420 </p>
 421 <p>
 422 The gnome-print architecture also forces page backgrounds (bitmaps
 423 and PDF) to be generated as uncompressed bitmaps, which leads to gigantic
 424 print job files. An alternative to gnome-print will be
 425 implemented in a future release of Xournal.
 426 <hr />
 427 <a name="author"></a>
 428 <h2 class="subtitle">Author information, license, bug-reports</h2>
 429 <p>
 430 Xournal is written by Denis Auroux
 431 (aur<!--despam-->oux<span>&#x40;</span><span>math</span>&#x2e;<span>mit&#x2e;edu).
 432 <br />It is distributed under the GNU General Public License.
 433 </p>
 434 <p>Feel free to contact me with bug reports and suggestions; I apologize
 435 in advance if I am unable to respond properly to some requests.
 436 List of known bugs/misfeatures (no need to report them again):
 437 <ul>
 438  <li> highlighter strokes become opaque on printouts (apparently a bug in
 439       libgnomeprint).</li>
 440  <li> print settings are not saved from one print command to the next.</li>
 441  <li> printing to PDF and/or printing page backgrounds generates large files.</li>
 442  <li> preferences are not saved on disk.</li>
 443  <li> selection cannot be dragged across page boundaries.</li>
 444 </ul>
 445 If you find a sequence of operations which crashes Xournal in a reproducible
 446 manner, please send detailed instructions on how to reproduce the crash.
 447 A core file may also be helpful.
 448 </p>
 449 <hr />
 450 <a name="changelog"></a>
 451 <h2 class="subtitle">Version history</h2>
 452 <p>
 453 Version 0.2 (January 29, 2006):
 454 <ul>
 455  <li>PDF file annotation using xpdf's pdftoppm
 456       (PDF backgrounds updated asynchronously at all resolutions)</li>
 457  <li>PS/PDF backgrounds (as bitmaps at fixed resolution) using ghostscript</li>
 458  <li>option to antialias and filter bitmap backgrounds when zooming</li>
 459  <li>option to emulate eraser tip with right mouse button</li>
 460  <li>binary installer allows non-root installation without compiling</li>
 461  <li>full-screen mode</li>
 462 </ul>
 463 </p>
 464 <p>
 465 Version 0.1.1 (January 5, 2006):
 466 <ul>
 467  <li> two bugfixes </li>
 468  <li> backward compatibility with GTK+ 2.4 </li>
 469 </ul>
 470 </p>
 471 <p>
 472 Version 0.1 (January 2, 2006): initial release.
 473 </p>
 474 <p>
 475 Features yet to be implemented:
 476 <ul>
 477  <li>freeform selection tool</li>
 478  <li>preferences file; persistent printer settings; recent files list</li>
 479  <li>native PDF print feature</li>
 480  <li>various functionalities (flatten layers, drag-and-drop across pages, ...)</li>
 481 </ul>
 482 </p>
 483 <hr />
 484 <a name="file-format"></a>
 485 <h2 class="subtitle">The file format</h2>
 486 <p>
 487 XOJ files are gzipped XML-like files. A more precise documentation of
 488 the file format will be added at a later date. Meanwhile, most of the
 489 format should be easy to figure out by trial-and-error or by looking
 490 at the source; if some details are unclear, feel free to ask.
 491 </p>
 492 <hr />
 493 <a name="installation"></a>
 494 <h2 class="subtitle">Installation issues</h2>
 495 <h3 class="subsub">Dependencies</h3>
 496 <p>
 497 The following libraries are required to run Xournal (they are standard on
 498 modern Linux distributions such as Fedora Core 3 or later, or RHEL 4 or
 499 later):
 500 <ul>
 501  <li> the <b>gtk+</b> libraries, version <b>2.4</b> or later
 502        (2.6 recommended) &nbsp; (package gtk2 and dependencies)</li>
 503  <li> <b>libgnomecanvas</b> version <b>2.4</b> or later &nbsp;
 504        (package libgnomecanvas and dependencies)</li>
 505  <li> <b>libgnomeprint</b> and <b>libgnomeprintui</b> version <b>2.2</b> or later &nbsp;
 506        (packages libgnomeprint22, libgnomeprintui22, and dependencies) </li>
 507 </ul>
 508 </p>
 509 <p>
 510  Additionally:
 511 <ul>
 512  <li> <b>xpdf</b> (more precisely, <b>pdftoppm</b>) is required for PDF file
 513 annotation</li>
 514  <li> <b>ghostscript</b> (optional: used to import PS/PDF files as bitmap
 515  backgrounds)</li>
 516 </ul>
 517 <p>
 518 To compile Xournal, you also need the <b>development packages</b> for the above
 519 libraries (packages gtk2-devel, libgnomecanvas-devel, libgnomeprint22-devel,
 520 libgnomeprintui22-devel, and dependencies), as well as <b>autoconf</b> and
 521 <b>automake</b>.
 522 </p>
 523 <h3 class="subsub">Compilation and installation procedure</h3>
 524 <p>
 525 Download the Xournal distribution tar.gz file, and any needed dependencies.
 526 </p>
 527 <p>
 528 <b>Binary installation in /usr/local:</b><br />
 529 Run (as root) the installer script
 530 <pre>./install-binary</pre> (and upgrade GTK+ and the other libraries if needed).
 531 </p>
 532 <p>
 533 <b>Binary installation in home directory:</b><br />
 534 Run (as any user) the installer script
 535 <pre>./install-binary</pre> (and hope that the required libraries are
 536 installed on your system).
 537 </p>
 538 <p>
 539 <b>Compilation and installation in /usr/local:</b>
 540 <pre>
 541 ./autogen.sh
 542 make
 543 (as root) make install
 544 </pre>
 545 </p>
 546 <p>
 547 <b>Compilation and installation in $HOME:</b>
 548 <pre>
 549 ./autogen.sh
 550 ./configure --prefix=$HOME
 551 make
 552 make install
 553 </pre>
 554 </p>
 555 <p><b>Configure error message:</b> <br />
 556 If autogen.sh generates the error message
 557 &nbsp; &nbsp; <tt><i>
 558 configure: error: Library requirements (gtk+-2.0 >= 2.4.0 libgnomecanvas-2.0 >= 2.4.0 libgnomeprintui-2.2 >= 2.0.0) not met
 559 </i></tt> &nbsp; &nbsp;
 560 even though you have sufficiently recent versions of these libraries on your
 561 system, then you need to install some missing development packages.
 562 </p>
 563 <hr />
 564 <a name="calibration"></a>
 565 <h2 class="subtitle">Tablet calibration issues</h2>
 566 <p>
 567 Configuring the tablet devices properly is unfortunately not as simple as it
 568 ought to be. This is a subject worthy of a detailed how-to document;
 569 meanwhile, here are some hints about how to configure your tablet.
 570 </p>
 571 <h3 class="subsub">Basics</h3>
 572 <p>
 573 Xournal uses the XInput extension to obtain high-resolution coordinates for
 574 strokes drawn using the stylus. If you decide that getting just the right
 575 XInput configuration isn't worth the effort, you can disable XInput features
 576 by unsetting the "Use XInput" option in the Options menu. The price to pay
 577 is a lower graphics quality, as the resolution of all strokes then drops to
 578 1 pixel (instead of the native resolution of the tablet device, which can
 579 be higher by several orders of magnitude).
 580 </p>
 581 <p>
 582 The configuration of tablet devices is controlled in the X server's
 583 configuration file (usually <b>XF86Config</b> or <b>xorg.conf</b> depending on your
 584 distribution). The ServerLayout section should contain lines like:
 585 <pre>
 586 Section "ServerLayout"
 587         ...
 588         InputDevice    "cursor" "SendCoreEvents"
 589         InputDevice    "stylus" "SendCoreEvents"
 590         InputDevice    "eraser" "SendCoreEvents"
 591 EndSection
 592 </pre>
 593 (the last one only if your stylus has an eraser tip), and your configuration
 594 file should include sections such as
 595 <pre>
 596 Section "InputDevice"
 597         Identifier "cursor"
 598         Driver "wacom"
 599         Option "Device" "/dev/ttyS0"
 600         Option "Type" "cursor"
 601         Option "ForceDevice" "ISDV4"
 602         Option "BottomX" "28800"
 603         Option "BottomY" "21760"
 604         Option "Mode" "absolute"
 605 EndSection
 606
 607 Section "InputDevice"
 608         Identifier "stylus"
 609         Driver "wacom"
 610         Option "Device" "/dev/ttyS0"
 611         Option "Type" "stylus"
 612         Option "ForceDevice" "ISDV4"
 613         Option "BottomX" "28800"
 614         Option "BottomY" "21760"
 615         Option "Mode" "absolute"
 616 EndSection
 617
 618 Section "InputDevice"
 619         Identifier "eraser"
 620         Driver "wacom"
 621         Option "Device" "/dev/ttyS0"
 622         Option "Type" "eraser"
 623         Option "ForceDevice" "ISDV4"
 624         Option "BottomX" "28800"
 625         Option "BottomY" "21760"
 626         Option "Mode" "absolute"
 627 EndSection
 628 </pre>
 629 The actual settings will depend on your hardware; look on the web for Linux
 630 installation instructions specific to your model: for example, the
 631 "Device" settings above correspond to a serial port protocol, many tablets
 632 use USB instead; the BottomX and BottomY values correspond to the physical
 633 resolution of the tablet and will vary from one model to another.
 634 </p>
 635 <h3 class="subsub">The cursor doesn't appear in the right place...</h3>
 636 <p>
 637 If the mouse pointer does not follow accurately the position of the stylus,
 638 this is an indication that your tablet is not properly calibrated. If you
 639 have the linuxwacom package, you can try modifying the tablet calibration
 640 using <b>xsetwacom</b>. The relevant parameters are named TopX, BottomX,
 641 TopY, BottomY, and need to be set separately for the stylus and for the
 642 eraser. For example:
 643 <pre>
 644     xsetwacom set stylus TopX 270
 645     xsetwacom set stylus BottomX 28510
 646     ...
 647 </pre>
 648 (the TopX and TopY parameters default to 0 if you haven't set them in your
 649 X server's configuration file). Experiment with these parameters until you
 650 find the right calibration settings for your tablet (i.e., the mouse pointer
 651 appears right under the tip of the stylus).
 652 </p>
 653 <p>
 654 Once you have found the perfect settings for your tablet, update your X
 655 server's configuration file (due to issues with some versions of the
 656 linuxwacom driver, the tablet calibration information is often not updated
 657 properly when using xsetwacom).
 658 </p>
 659 <p>
 660 <b>Important:</b> due to issues with the linuxwacom driver, it is important
 661 to either upgrade your driver to a <a href="manual.html#wacompatch">patched
 662 version</a>, or restrict your choice of settings as follows:
 663 <ul>
 664 <li> your calibration settings should not be changed at runtime (i.e.,
 665 insert your settings directly into your X server configuration file.
 666 Do not add a list of xsetwacom commands to your startup files).
 667 </li>
 668 <li> TopX and TopY values should always be 0.
 669 </li>
 670 </ul>
 671 </p>
 672 <h3 class="subsub">Strokes aren't drawn under the cursor...</h3>
 673 <p>
 674 This is due to misfeatures in the linuxwacom driver. Typically, this
 675 will happen in all of the following cases:
 676 <ul>
 677 <li> the calibration settings have been changed after the X server was
 678 started (using xsetwacom) </li>
 679 <li> the calibration TopX or TopY values are not 0 </li>
 680 <li> the display has been rotated </li>
 681 </ul>
 682 Future versions of the driver may fix these issues. Meanwhile, you can
 683 either disable XInput support in Xournal (in the Options menu), at a
 684 price of a severe loss of resolution (and the eraser tip won't be detected
 685 anymore), or apply this <a href="manual.html#wacompatch">patch</a>
 686 to the wacom driver.
 687 </p>
 688 <p>
 689 I have also had a report that one of the workarounds used by Xournal to
 690 bypass a calibration bug in GTK+ can actually entirely prevent strokes
 691 from being drawn. If you are being unsuccessful at drawing in Xournal
 692 with XInput enabled, try recompiling after changing the first line of
 693 <tt>src/main.c</tt> to
 694 <pre>#define ENABLE_XINPUT_BUGFIX 0</pre>
 695 If this modification does improve things for you, and if you have a bit
 696 of spare time to help investigate the causes of this problem, please
 697 contact me.
 698 </p>
 699 <h3 class="subsub">On-the-fly display rotation</h3>
 700 <p>
 701 You need an X server that supports the RANDR extension, and a
 702 <a href="manual.html#wacompatch">patched</a> version of the linuxwacom
 703 driver to support on-the-fly rotation.
 704 </p>
 705 <p>
 706 To set the tablet in portrait mode:
 707 <pre>
 708   xrandr -o 3
 709   xsetwacom set stylus Rotate cw
 710 </pre>
 711 To return to landscape mode:
 712 <pre>
 713   xrandr -o 0
 714   xsetwacom set stylus Rotate none
 715 </pre>
 716 <b>Note:</b> you should not rotate the display while Xournal is running,
 717 otherwise the tablet calibration in Xournal may (and most likely will)
 718 become incorrect.
 719 Exit Xournal and restart it after the display has been rotated.
 720 </p>
 721 <a name="wacompatch"></a>
 722 <h3 class="subsub">Linuxwacom patch for calibration and rotation</h3>
 723 <p>
 724 This patch fixes rotation and calibration issues with the linuxwacom driver
 725 version 0.7.0.
 726 <ul>
 727 <li>The <a href="http://math.mit.edu/~auroux/software/xournal/linuxwacom-0.7.0-rotate-patch">patch
 728 file</a> for the linuxwacom source code (also included with the Xournal
 729 distribution).</li>
 730 <li>The <a href="http://math.mit.edu/~auroux/software/xournal/linuxwacom-rotate-patch.tar.gz">patched
 731 binaries</a> for the X.org X server.</li>
 732 </ul>
 733 </p>
 734 </body>
 735 </html>