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