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