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