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