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.4.5
  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.berkeley.edu/~auroux/software/xournal/">http://math.berkeley.edu/~auroux/software/xournal/</a>
  43 </p>
  44 <p>
  45  Xournal aims to provide superior graphical quality (subpixel resolution) and overall
  46  functionality; however various advanced features have not been implemented
  47  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 file</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 to 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/text-tool.png"> The text tool</h3>
 130 <p>
 131   To insert a new text item, click at the location where the text is to be
 132   inserted on the page, then type it in or paste it using the contextual
 133   menu (note: no wrapping is performed). To modify a text item, click inside
 134   it. The font and point size can be modified using the "Text Font" command
 135   in the Tools menu (or the toolbar button). The color is the same as that
 136   currently selected for the pen (and can be modified using the toolbar
 137   buttons).
 138 </p>
 139 <p>
 140   Text items can contain arbitrary Unicode characters, provided that a
 141   suitable font is installed on your system. However, languages written
 142   in a direction other than left-to-right might not be handled properly.
 143   If a journal contains some items in a font that is unavailable on your
 144   system, another one will be substituted. (Also, text items will be
 145   lost if the document is opened in a version of Xournal prior to 0.4).
 146   Finally, note that the printing and PDF export features only accept
 147   TrueType and Type 1 scalable fonts (do not use any bitmap fonts), and
 148   that the typesetting of the text may be slightly different in the
 149   printout.
 150 </p>
 151 <h3 class="subsub"><img src="pixmaps/ruler.png"> The ruler</h3>
 152 <p>
 153   The ruler is not a tool by itself, but rather a special operating mode
 154   of the pen and highlighter tools. When it is enabled, these tools paint
 155   line segments instead of curvy strokes. For simplicity, selecting the
 156   ruler when not in pen or highlighter mode automatically selects the pen.
 157 </p>
 158 <a name="recognizer"></a>
 159 <h3 class="subsub"><img src="pixmaps/shapes.png"> The shape recognizer</h3>
 160 <p>
 161   The shape recognizer is also a special
 162   operating mode of the pen and highlighter tools. When it is enabled,
 163   Xournal attempts to recognize geometric shapes as they are drawn, and
 164   if successful will replace the drawn strokes accordingly. The shapes
 165   that can be recognized are: line segments, circles, rectangles, arrows,
 166   triangles and quadrilaterals. Polygonal shapes can be drawn in a single
 167   stroke or in a sequence of consecutive strokes.
 168 </p>
 169 <p>
 170   The recognizer is set to be as unobtrusive as possible, and should not
 171   interfere too much with handwriting. (It differs in this and other ways
 172   from another shape recognizer written for Xournal by Lukasz Kaiser).
 173   As a result, it may only recognize shapes if you draw them carefully and
 174   deliberately. Specific tips for better recognition: (1) for circles,
 175   a closed curve that isn't quite round works better
 176   than a rounder curve that doesn't close; (2) for arrows, it is better
 177   to lift the pen before drawing the tip of the arrow, and make sure
 178   the tip consists of two straight line segments;
 179   (3) for very elongated rectangles,
 180   recognition tends to be better if you lift the pen between consecutive
 181   sides.
 182 </p>
 183 <h3 class="subsub"><img src="pixmaps/recycled.png"> Default tools</h3>
 184 <p>
 185   Each tool (pen, eraser, highlighter, text) has a default setting
 186   (color, thickness, ... for the drawing tools, font and size for the
 187   text tool) associated to it.
 188   The "Default Pen", "Default Eraser", "Default Highlighter", and
 189   "Default Text" entries of
 190   the Tools menu select the appropriate tool and reset its settings to
 191   the defaults. The toolbar also includes a "Default" button which
 192   resets the currently selected tool to its default settings,
 193   and a "Default Pen" button. <br />
 194   The "Set As Default" entry of the Tools menu takes the current settings
 195   of the currently selected tool and makes them the new default.
 196 </p>
 197 <a name="thicknesses"></a>
 198 <h3 class="subsub"><img src="pixmaps/thin.png"> <img src="pixmaps/medium.png">
 199   <img src="pixmaps/thick.png"> Thickness buttons</h3>
 200 <p>
 201   These three buttons control the thickness of the current drawing tool
 202   (pen, eraser, or highlighter). The thickness can also be adjusted using
 203   the appropriate sub-menu of the Tools menu.
 204 </p>
 205 <h3 class="subsub"><img src="pixmaps/rect-select.png"> Rectangle selection</h3>
 206 <p>
 207   This tool lets you select a rectangular region of the current layer.
 208   All the strokes which are entirely contained within the rectangular region
 209   are selected.
 210   The selection can be moved within its page by clicking inside the
 211   selection rectangle and dragging the cursor. If the cursor is dragged
 212   to a different page, the selection will be moved to the topmost layer of
 213   that page.
 214 </p>
 215 <p>
 216   The selection can be cut, duplicated, etc. (including to a different page
 217   or to a different journal) using the copy-paste toolbar buttons or the
 218   corresponding entries of the Edit menu.
 219 </p>
 220 <h3 class="subsub"><img src="pixmaps/stretch.png"> Vertical space</h3>
 221 <p>
 222   This tool lets you insert or remove vertical space within the page:
 223   all the items of the current layer which lie entirely between the cursor
 224   position and the end of the page are moved up or down.
 225 </p>
 226 <p>
 227   Note that the background, and items on other layers, are not affected.
 228   Also, if you insert too much vertical space, some items may fall below
 229   the bottom of the page and become invisible. These items are not lost:
 230   to retrieve them, either use
 231   the vertical space tool again to remove the excess vertical
 232   space, or change the page height to an appropriate value (using the
 233   "Paper Size" entry in the Journal menu).
 234 </p>
 235 <p>
 236   If you drag the cursor below the bottom of the page (so that the
 237   entire block being moved has become invisible), the items will be moved
 238   to the next page (topmost layer); however, any items that were already
 239   present on the next page are left unchanged. Similarly, dragging the
 240   cursor above the top of the page so that the entire block being moved
 241   becomes invisible results in the items being moved to the previous page.
 242 </p>
 243 <h3 class="subsub"><img src="pixmaps/hand.png"> Hand tool</h3>
 244 <p>
 245   This tool lets you browse the journal; dragging the cursor scrolls the
 246   view.
 247 </p>
 248 <h3 class="subsub">Undo and redo</h3>
 249 <p>
 250   All operations performed on the currently open journal (drawing, erasing,
 251   cut-and-paste; adding, deleting, and reformatting pages; etc.) can be
 252   undone and redone at will using the Undo and Redo toolbar buttons or
 253   the corresponding entries in the Edit menu.<br />
 254   There is no limit to the depth of the undo/redo stack. It is cleared only
 255   when you quit the application or open a new journal.
 256 </p>
 257 <a name="mappings"></a>
 258 <h3 class="subsub">Button mappings</h3>
 259 <p>
 260   Stylus buttons 2 and 3 (mouse middle and right buttons) can be mapped
 261   to different tools using the appropriate submenus in the Options menu
 262   (whereas the Tools menu and the toolbar buttons affect the primary tool
 263   assigned to button 1). The default mapping is the eraser.
 264 </p>
 265 <p><b>Advanced configuration:</b>
 266   if a secondary button is mapped to a drawing tool (pen, eraser, or
 267   highlighter), the default is to "dynamically link" its settings to those
 268   of the primary tool, which means that each drawing tool has common
 269   settings (color, thickness, etc.) for all buttons.
 270   Dynamic linking of brush settings
 271   can be disabled by selecting the "Copy of current brush" option in the
 272   "Button mapping" submenu. The settings of the tool for button 2 or 3 are
 273   copied from the button 1 settings at the time when you select the option,
 274   and afterwards they are no longer updated when the button 1 settings are
 275   modified, thus making it possible to assign pens of different colors or
 276   thicknesses to different buttons.
 277 </p>
 278 <p>
 279   Another option that affects button mappings is the "Eraser tip" option.
 280   If this option is turned on and the XInput extensions are enabled, then
 281   the eraser tip of your tablet's stylus will automatically be remapped to
 282   the eraser tool. This behavior, which overrides all other button mappings,
 283   is most useful if your X server is configured to map the eraser tip of
 284   your tablet's stylus to button 1.
 285 </p>
 286 <p>
 287   Also note the "Buttons switch mappings" option, which may be useful to
 288   users of external tablets: when this option is turned on, buttons 2 and 3
 289   only switch the tool mapping, and drawing is still done with button 1.
 290 </p>
 291 <hr />
 292 <a name="pages-layers"></a>
 293 <h2 class="subtitle">Pages, layers, and backgrounds</h2>
 294 <p>
 295 A journal is composed of one or more pages, whose characteristics can be
 296 modified independently of each other. Each page consists of a background
 297 and one or more layers stacked on top of the background. All drawing
 298 operations take place within a single layer, and do not affect the background
 299 or the other layers. You can think of the layers as transparent overlays:
 300 drawing and erasing always takes place on the topmost visible overlay.
 301 <br />
 302 Layers are a convenient mechanism to add temporary annotations on top of a
 303 journal page: because of the logical separation between layers, erasing
 304 in the top layer will not affect the contents of the other layers, and
 305 the top layer can be easily discarded.
 306 </p>
 307 <h3 class="subsub">Navigating the journal</h3>
 308 <p>
 309 The user interface either displays all pages in the journal below each other
 310 ("continuous mode") or a single page ("one-page mode"). You can switch
 311 between the two modes by using the "Continuous" and "One page" entries in
 312 the View menu. The default is the
 313 continuous mode, best adapted to note-taking on multiple pages. The one-page
 314 mode is more appropriate if your journal is a scrapbook in which the pages
 315 have different characteristics (in particular, if you are annotating a
 316 series of pictures of different sizes).
 317 </p>
 318 <p>
 319 You can navigate the journal pages in several different ways:
 320 <ul>
 321  <li> using the navigation toolbar buttons (or the corresponding entries
 322   in the View menu) to go back or forward one page, or to jump to the first
 323   or last page of the journal;
 324  </li>
 325  <li> in continuous mode, scrolling down to the desired page;
 326  </li>
 327  <li> entering a value or using the +/- buttons in the page selection box
 328   at the lower-left corner of the Xournal window.
 329  </li>
 330 </ul>
 331 As a convenient shortcut, going forward one page (or pressing the + button
 332 in the selection box) when already at the end of the journal creates a new
 333 page at the end of the journal.
 334 </p>
 335 <p>
 336 Note: jumping to a page automatically selects the top-most layer in
 337 that page.
 338 </p>
 339 <p>
 340 To navigate the layers of a page, either use the layer selection box at
 341 the bottom of the Xournal window, or use the "Show Layer" and "Hide Layer"
 342 entries in the View menu. The basic rule to remember is that the display
 343 shows all the layers underneath the currently select one, and while those
 344 above it are hidden.
 345 </p>
 346 <p>
 347 Note: the background layer cannot be drawn on; any attempt to draw on the
 348 background will generate an error message and switch back to the first
 349 layer.
 350 </p>
 351 <h3 class="subsub">Managing pages and layers</h3>
 352 <p>
 353 Pages can be added to the journal by using the "New Page ..." entries in
 354 the Journal menu. The newly created page has the same format and background as the
 355 current page (for the "New Page Before" and "New Page After" commands), or
 356 as the last page of the journal (for "New Page At End"). Additionally,
 357 jumping to the next page when already on the last page creates a new page
 358 at the end of the journal.
 359 </p>
 360 <p>
 361 The "Delete Page" entry in the Journal menu removes the current page from
 362 the journal. (Remember that you can always undo this operation if you
 363 deleted a page by accident).
 364 </p>
 365 <p>
 366 The "New Layer" entry in the Journal menu creates a new layer immediately
 367 above the current one, while "Delete Layer" removes the current layer and
 368 its contents (if you attempt to delete the only layer of a page, a new
 369 empty layer will be automatically created).
 370 </p>
 371 <h3 class="subsub">Paper formats and backgrounds</h3>
 372 <p>
 373 The size of the current page can be modified using the "Paper Size" entry
 374 in the Journal menu. Standard and custom sizes are available.
 375 </p>
 376 <p>
 377 The background is either one of several kinds of standard paper types, or a
 378 bitmap image, or a page of a PDF file.
 379 </p>
 380 <p>
 381 To select a <b>standard paper type</b> as background for the current page, use
 382 the "Paper Style" submenu of the Journal menu. The paper color can also
 383 be changed using the "Paper Color" submenu of the Journal menu.
 384 </p>
 385 <p>
 386 To use a <b>PDF file</b> as the background for a journal, see the paragraph
 387 on <a href="manual.html#pdfannotate">PDF annotation</a> below.
 388 </p>
 389 <p>
 390 To load a <b>bitmap image file</b> for use as background for the current page, use
 391 the "Load Background" entry of the Journal menu. This automatically
 392 resizes the current page according to the size of the bitmap image, and
 393 resets the zoom level to 100%. If <i>ghostscript</i> is installed on your
 394 system, you can also use this method to import a fixed-resolution bitmap
 395 version of a Postscript or PDF file; in that case, all pages will be
 396 imported sequentially as backgrounds into consecutive pages (this is
 397 <i>not</i> the
 398 recommended method; PDF annotation is better in every respect).
 399 </p>
 400 <p>
 401 To capture a <b>screenshot</b> of a window or the entire screen and make it
 402 the background of the current page, use the "Background Screenshot" entry of
 403 the Journal menu. This will iconify the Xournal window; click in any window
 404 (after ensuring it is fully visible) to capture its contents, or click on
 405 the desktop (or screen background) to capture the entire screen.
 406 </p>
 407 <p><b>Important note:</b> by default, bitmap images loaded using the "Load
 408 Background" command will not be saved with the journal; instead, the journal
 409 file will contain a reference to the absolute location of the image file.
 410 This means that the background will become unavailable if the image file
 411 is moved or deleted. To avoid this, check the option "Attach file to the
 412 journal" at the bottom of the file selection dialog box.<br />
 413 This option only applies to bitmap image files loaded from disk;
 414 screenshot backgrounds (and bitmaps converted from PS/PDF files using
 415 ghostscript) are automatically "attached" to the journal file: when the
 416 journal is saved, they will be saved (in PNG format) along with it
 417 (using file names of the form *.xoj.bg_*.png).
 418 </p>
 419
 420 <a name="pdfannotate"></a>
 421 <h3 class="subsub">PDF annotation</h3>
 422 <p>
 423 Xournal can be used to annotate PDF files, by loading the pages of a PDF
 424 file as backgrounds for a journal. As of version 0.4.5 this is done using
 425 the <i>poppler</i> library (previous versions used the
 426 <i>pdftoppm</i> converter, which is part of the <i>xpdf</i> utilities or
 427 the <i>poppler</i> utilities depending on distributions).
 428 </p>
 429 <p>
 430 The "Annotate PDF" command in the File menu can be used to load a PDF file
 431 into a new (empty) journal. The page backgrounds and page sizes correspond
 432 to the contents of the PDF file. (Most unencrypted PDF files should be
 433 supported).
 434 </p>
 435 <p>
 436 By default, the PDF file used to generate the backgrounds
 437 will not be saved with the journal; instead, the journal
 438 file will contain a reference to the absolute location of this file.
 439 This means that all backgrounds will become unavailable if the PDF file
 440 is moved or deleted (although Xournal will let you specify
 441 the updated location of the PDF file when opening the journal
 442 file). To avoid this, check the option "Attach file to the journal"
 443 at the bottom of the dialog box when opening the PDF file. The PDF file will
 444 then be saved along with the journal (using a file name of the form
 445 *.xoj.bg.pdf).
 446 <p>
 447 Upon zooming, the page backgrounds are asynchronously updated
 448 to fit the current display resolution. Since this process is quite slow and
 449 memory-intensive, the pages are normally updated only as needed, when they
 450 become visible on the screen (unless you disable the "Progressive
 451 Backgrounds" option in the Options menu). This means that you will
 452 occasionally notice the page backgrounds being updated while you are
 453 scrolling inside the document (at large zoom levels, it can take a while
 454 for the updated background to appear).
 455 <!-- However, since the backgrounds are generated asynchronously by a
 456 separate Unix process, you can keep drawing in the journal
 457 while the update process is still in progress. -->
 458 </p>
 459 <p>
 460 It is strongly recommended that you do not resize PDF pages (using the
 461 "Paper Size" command). This will result in extremely ugly rendering, as
 462 the PDF converter is unable to render bitmaps with
 463 non-standard aspect ratios.
 464 </p>
 465 <p>
 466 While you can perform all sorts of page operations on a journal file
 467 that was created from a PDF file (such as duplicating or deleting pages,
 468 inserting pages with blank or bitmapped backgrounds, ...), it is not
 469 possible to include pages from more than one PDF file into a single journal
 470 document. If you need to annotate two or more PDF files inside a same
 471 journal document, please consider using an external utility for merging
 472 PDF files (for example <i>pdfmerge</i>).
 473 </p>
 474 <p>
 475 <b>Note:</b> the PDF backgrounds are
 476 rescaled and/or regenerated as needed when the zoom level is changed.
 477 Because this consumes a lot of memory and CPU resources, by default this
 478 rescaling is performed on-demand as each page becomes visible. This means
 479 that you will occasionally notice backgrounds being generated while
 480 you are scrolling inside the document (at large zoom levels, this can slow
 481 down the screen refresh rate noticeably). If you'd prefer all backgrounds to
 482 be loaded in advance and rescaled immediately upon changing the zoom level,
 483 disable the "Progressive Backgrounds" option in the Options menu. Be aware
 484 that this increases the memory consumption and will cause out-of-memory
 485 crashes when viewing long documents.
 486 </p>
 487
 488 <hr />
 489 <a name="printing"></a>
 490 <h2 class="subtitle">Printing</h2>
 491 <p>
 492 As of version 0.4.5, Xournal uses the gtk-print architecture for printing
 493 (previous versions used gnome-print). Xournal also includes a native PDF
 494 printing feature.
 495 </p>
 496 <h3 class="subsub">Printing via gtk-print</h3>
 497 <p>
 498 The print dialog box lets you select a printer
 499 (either one of the printers installed on your system, or the "Print to File"
 500 virtual printer), and a range of pages to print (the default is to print
 501 the entire journal). Each page
 502 of the journal is automatically rescaled so as to fit the paper size.
 503 </p>
 504 <p>
 505 Unlike the older gnome-print architecture, gtk-print and poppler make it
 506 possible to efficiently print files that annotate PDF backgrounds. (Prior to
 507 version 0.4.5, PDF backgrounds had to be converted to bitmaps upon printing,
 508 resulting in huge print jobs and low printout quality).
 509 </p>
 510 <p>
 511 The settings are currently not saved properly from one print job to
 512 the next, so make sure to verify the settings.
 513 </p>
 514 <h3 class="subsub">Exporting to PDF</h3>
 515 <p>
 516 Xournal also provides its own PDF rendering
 517 engine. The "Export to PDF" command (in the File menu) produces a
 518 PDF-1.4 file from the currently loaded document. The pages of the
 519 resulting PDF file have the same size as in Xournal. Highlighter strokes
 520 are rendered in a partially transparent manner (note however that
 521 applications such as xpdf and ghostview do not always handle
 522 PDF transparency properly). Text items are rendered by embedding
 523 TrueType subsets or Type 1 fonts into the PDF document as appropriate.
 524 </p>
 525 <p>
 526 Xournal includes a PDF file parser compatible with PDF format
 527 version 1.4; the compression features of PDF 1.5 are
 528 not supported. When exporting a document that uses PDF
 529 backgrounds, Xournal attempts to preserve most of the structure of
 530 the original PDF file (however, auxiliary data such as thumbnails, hyperlinks,
 531 and annotations are lost). If Xournal is unable to parse the PDF
 532 file, the backgrounds are converted to (compressed) bitmaps and a new
 533 PDF file is generated from scratch.
 534 </p>
 535 <hr />
 536 <a name="configuration"></a>
 537 <h2 class="subtitle">Configuration file</h2>
 538 <p>
 539 Xournal's configuration settings are saved to the file
 540 <tt>~user/.xournal/config</tt> by using the "Save
 541 Preferences" command in the Options menu. The settings saved in the
 542 configuration file include in particular:
 543 <ul>
 544 <li>general display preferences: zoom level, window size, ...</li>
 545 <li>default paper settings (as set by the "Set As Default" command in
 546 the Journal menu)</li>
 547 <li>default settings for the pen, eraser, highlighter, and text tools
 548 (as set by the "Set As Default" command in the Tools menu)</li>
 549 <li>mappings for buttons 2 and 3</li>
 550 <li>the various preferences set in the Options menu</li>
 551 </ul>
 552 The configuration file also gives access to additional customization
 553 options which cannot be set from the user interface, such as: the
 554 display resolution in pixels per inch, the step increment in zoom factors,
 555 the tool selected at startup, the thickness of the various drawing tools,
 556 the default directory for opening and saving files, the visibility and
 557 position of the menu and toolbars, ...
 558 </p>
 559 <p>Here is a partial list of configuration file settings:
 560 <ul>
 561 <li> <p><b>Display settings</b> (in the <tt><b>[general]</b></tt> section): <ul>
 562 <li><tt><b>display_dpi:</b></tt>
 563 the display resolution in pixels per inch</li>
 564 <li><tt><b>initial_zoom:</b></tt>
 565 the initial zoom level, in percent</li>
 566 <li><tt><b>window_maximize:</b></tt>
 567 whether to start with a maximized window</li>
 568 <li><tt><b>window_fullscreen:</b></tt>
 569 whether to start in fullscreen mode</li>
 570 <li><tt><b>window_width, window_height:</b></tt>
 571 the preferred window size (if not maximized)</li>
 572 <li><tt><b>zoom_step_factor:</b></tt>
 573 the (multiplicative) factor by which the zoom in/zoom out buttons change the zoom
 574 level</li>
 575 <li><tt><b>view_continuous:</b></tt>
 576 whether to start in continuous or single-page view mode (see also View menu)</li>
 577 <li><tt><b>highlighter_opacity:</b></tt>
 578 the opacity level of highlighter strokes (from 0 to 1; 1 is fully opaque).
 579 Note that .xoj files do not store the opacity level of strokes, so if you
 580 change from the default value of 0.5 your files will look different when
 581 opened on another machine.</li>
 582 </ul></p></li>
 583 <li> <p><b>User interface settings</b> (in the <tt><b>[general]</b></tt> section): <ul>
 584 <li><tt><b>autosave_prefs:</b></tt>
 585 whether to automatically save preferences upon exiting Xournal.</li>
 586 <li><tt><b>interface_order:</b></tt>
 587 the position of the various toolbars relative to the drawing area,
 588 from top to bottom. The default order is: <tt>menu main_toolbar pen_toolbar
 589 drawarea statusbar</tt>. Switching elements around rearranges the
 590 interface. Removing elements from the list hides them.</li>
 591 <li><tt><b>interface_fullscreen:</b></tt>
 592 the same thing, but in fullscreen mode. For example, <tt>drawarea main_toolbar
 593 pen_toolbar</tt> would position the toolbars below the drawing area, and hide
 594 the menu and status bar.
 595 interface.</li>
 596 <li><tt><b>shorten_menus:</b></tt>
 597 whether to hide some little-used menu or toolbar items (see also "Shorten
 598 Menus" in Options menu)</li>
 599 <li><tt><b>shorten_menu_items:</b></tt>
 600 the list of interface items to hide when shorten_menus is enabled. Virtually
 601 everything in the interface can be hidden. A complete list of interface item ID names
 602 can be obtained by running the command <tt>grep id= xournal.glade</tt> in
 603 the base directory of the source code distribution.</li>
 604 <li><tt><b>default_path:</b></tt>
 605 the default path for the open/save dialog boxes (leave blank to use the
 606 current directory)</li>
 607 <li><tt><b>autoload_pdf_xoj:</b></tt>
 608 whether to load filename.pdf.xoj (if it exists) when the user opens
 609 filename.pdf (see also "Autoload .pdf.xoj" in Options menu)</li>
 610 </ul></p></li>
 611 <li> <p><b>Input device settings</b> (in the <tt><b>[general]</b></tt> section): <ul>
 612 <li><tt><b>use_xinput:</b></tt>
 613 whether to enable XInput extensions for high-resolution tablet input
 614 (see also "Use XInput" in Options menu)</li>
 615 <li><tt><b>discard_corepointer:</b></tt>
 616 whether to discard Core events when XInput extensions are enabled. Setting
 617 this to "false" should be safe.</li>
 618 <li><tt><b>use_erasertip:</b></tt>
 619 whether to always map the eraser tip of a stylus to the eraser
 620 (see also "Eraser Tip" in Options menu)</li>
 621 <li><tt><b>buttons_switch_mappings:</b></tt>
 622 whether to have buttons 2 and 3 switch the tool mapping instead of actually
 623 drawing (useful with some external tablets; see also "Buttons Switch
 624 Mappings" in Options menu)</li>
 625 <li><tt><b>pressure_sensitivity:</b></tt>
 626 whether to use stylus pressure to control stroke width (see also "Pressure
 627 Sensitivity" in Options menu)</li>
 628 <li><tt><b>width_minimum_multiplier, width_maximum_multiplier:</b></tt>
 629 the minimum and maximum width multipliers for pressure-sensitive strokes</li>
 630 </ul></p></li>
 631 <li> <p><b>Paper settings</b> (in the <tt><b>[paper]</b></tt> section): <ul>
 632 <li><tt><b>width, height:</b></tt>
 633 the default paper size, in points (1 point = 1/72 in = 0.353 mm)</li>
 634 <li><tt><b>color:</b></tt>
 635 the default paper color (named color or #rrggbbaa)</li>
 636 <li><tt><b>style:</b></tt>
 637 the default paper style (plain, lined, ruled, or graph)</li>
 638 <li><tt><b>apply_all:</b></tt>
 639 whether paper style changes get applied to all pages (see also "Apply to all
 640 pages" in Journal menu)</li>
 641 <li><tt><b>print_ruling:</b></tt>
 642 whether to include the paper ruling lines when printing
 643 (see also "Print Paper Ruling" in Options menu)</li>
 644 <li><tt><b>progressive_bg:</b></tt>
 645 whether to generate PDF backgrounds just-in-time as pages become visible
 646 (rather than immediately upon opening the document or changing the zoom
 647 level, which is more memory-intensive); see also "Progressive Backgrounds"
 648 in Options menu</li>
 649 <li><tt><b>gs_bitmap_dpi:</b></tt>
 650 resolution (in dpi) of bitmap backgrounds generated from PS/PDF files
 651 when using "Load Background" in Journal menu; higher values mean higher
 652 quality but larger memory usage</li>
 653 <li><tt><b>pdftoppm_printing_dpi:</b></tt>
 654 resolution (in dpi) of bitmaps generated from PDF backgrounds when exporting
 655 to PDF (only used if the PDF parser is unable to process the background PDF
 656 file); higher values mean higher quality but larger output files</li>
 657 </ul></p></li>
 658 <li> <p><b>Tool settings</b> (in the <tt><b>[tools]</b></tt> section): <ul>
 659 <li><tt><b>startup_tool:</b></tt>
 660 the tool selected at startup (one of: pen, eraser, highlighter, selectrect,
 661 vertspace, hand)</li>
 662 <li><tt><b>pen_color, pen_thickness, pen_ruler, pen_recognizer:</b></tt>
 663 the default pen settings: color (a named color or #rrggbbaa), thickness
 664 (fine = 1, medium = 2, thick = 3), ruler mode, recognizer mode</li>
 665 <li><tt><b>highlighter_color, highlighter_thickness, highlighter_ruler,
 666 highlighter_recognizer:</b></tt>
 667 the default highlighter settings</li>
 668 <li><tt><b>eraser_thickness, eraser_mode:</b></tt>
 669 the default eraser settings: thickness (fine = 1, medium = 2, thick = 3)
 670 and operating mode (standard = 0, whiteout = 1, delete strokes = 2)</li>
 671 <li><tt><b>btn2_tool, btn3_tool:</b></tt>
 672 the tools mapped to buttons 2 and 3 (can be: pen, eraser, highlighter, selectrect,
 673 vertspace, hand)</li>
 674 <li><tt><b>btn2_linked, btn3_linked:</b></tt>
 675 whether the settings of the tools for buttons 2 and 3 are linked to those of
 676 the corresponding primary tools</li>
 677 <li><tt><b>btn2_color, btn2_thickness, btn2_ruler, btn2_recognizer,
 678 btn2_erasermode:</b></tt>
 679 if the settings are not linked to the primary tool (<tt>btn2_linked</tt> is
 680 false), the settings of the tool mapped to button 2. Not all entries are
 681 applicable, depending on the value of <tt>btn2_tool</tt>.</li>
 682 <li><tt><b>btn3_color, btn3_thickness, btn3_ruler, btn3_recognizer,
 683 btn3_erasermode:</b></tt>
 684 similarly for the button 3 tool.</li>
 685 <li><tt><b>pen_thicknesses, eraser_thicknesses, highlighter_thicknesses:</b></tt>
 686 the widths in points (1 pt = 1/72 in = 0.353 mm) of the various pens
 687 (5 values from 'very fine' to 'very thick'), erasers (3 values from 'fine'
 688 to 'thick') and highlighters (3 values from 'fine' to 'thick') </li>
 689 <li><tt><b>default_font, default_font_size:</b></tt>
 690 the name and point size of the default text font.</li>
 691 </ul></p></li>
 692 </ul>
 693 </p>
 694 <hr />
 695 <a name="author"></a>
 696 <h2 class="subtitle">Author information, license, bug-reports</h2>
 697 <p>
 698 Xournal is written by Denis Auroux
 699 (aur<!--despam-->oux<span>&#x40;</span><span>math</span>&#x2e;<span>mit&#x2e;edu,
 700 aur<!--despam-->oux<span>&#x40;</span><span>math</span>&#x2e;<span>berkeley&#x2e;edu).
 701 </p>
 702 <p>
 703 The source code includes contributions by the following people:
 704 Eduardo de Barros Lima, Mathieu Bouchard, Ole J&oslash;rgen Br&oslash;nner,
 705 Vincenzo Ciancia, Luca de Cicco, Michele Codutti,
 706 Robert Gerlach, Lukasz Kaiser, Danny Kukawka, Bob McElrath,
 707 Andy Neitzke, David Planella, Alex Ray, Jean-Baptiste Rouquier,
 708 Mike Ter Louw, Uwe Winter, Lu Zhihe.
 709 </p>
 710 <p style="font-size:0.9em">(Let me know if you are missing from this list or
 711 if your name is mis-spelled)</p>
 712 <p>
 713 Xournal is distributed under the GNU General Public License.
 714 </p>
 715 <p style="font-size: 0.9em; font-style: italic">
 716  <b>Note:</b> most of the code of version 0.4.2.1
 717  (excluding graphics and a few portions of the code) has also been released
 718  under the MIT License. Please contact the main developer if
 719  you need an MIT License version of the 0.4.2.1 code. Later versions are
 720  not available under MIT License.
 721 </p>
 722 <p>Feel free to contact me with bug reports and suggestions; I apologize
 723 in advance if I am unable to respond properly to some requests.
 724 If you find a sequence of operations which crashes Xournal in a reproducible
 725 manner, please send detailed instructions on how to reproduce the crash.
 726 A core file may also be helpful.
 727 </p>
 728 <p>
 729 Bug reports and suggestions can also be submitted on Xournal's
 730 <a href="http://www.sourceforge.net/projects/xournal/">SourceForge page.</a>
 731 </p>
 732 <hr />
 733 <a name="changelog"></a>
 734 <h2 class="subtitle">Version history</h2>
 735 <p>
 736 Version 0.4.5 (Oct 2, 2009):
 737 <ul>
 738      <li>bugfixes for GTK+ 2.16/2.17 issues with xinput events
 739 </li><li>various minor UI bugfixes
 740 </li><li>gettext internationalization (contributed by David Planella)
 741 </li><li>Catalan translation (by David Planella), French translation
 742 </li><li>use poppler instead of pdftoppm to render PDF backgrounds
 743     (after patches by Mike Ter Louw and Bob McElrath)
 744 </li><li>various improvements to UI and to key bindings (including
 745     patches by Bob McElrath and Lu Zhihe)
 746 </li><li>use gtk-print instead of libgnomeprint for printing
 747 </li><li>custom color chooser (patch contributed by Alex Ray)
 748 </li><li>option to have tablet buttons toggle the mapping rather than draw
 749 </li><li>paper color chooser (after a patch by Ole Joergen Broenner)
 750 </li><li>remove binary installer (due to binary incompatibilities)
 751 </li><li>UPDATED DEPENDENCIES: need gtk+ 2.10, poppler-glib 0.5.4
 752 </li>
 753 </ul>
 754 </p>
 755 <p>
 756 Version 0.4.2.1 (Mar 27, 2008):
 757 <ul>
 758  <li>bugfix for #1926757 (crash upon pasting variable-width stroke)</li>
 759  <li>bugfix: set ruler/recognizer setting to default upon switching tools</li>
 760 </ul>
 761 </p>
 762 <p>
 763 Version 0.4.2 (Mar 25, 2008):
 764 <ul>
 765  <li>bugfixes for X.org 7.3; allow XInput and core events in reverse order</li>
 766  <li>resize selection (patch contributed by Andy Neitzke)</li>
 767  <li>pressure sensitive pen (variable stroke width) (patch by Andy Neitzke)</li>
 768  <li>geometric shape recognizer (after an idea by Lukasz Kaiser)
 769      (see <a href="manual.html#recognizer">here</a>)</li>
 770  <li>clean up compiler warnings (patch contributed by Danny Kukawka)</li>
 771 </ul>
 772 </p>
 773 <p>
 774 Version 0.4.1 (Sep 15, 2007):
 775 <ul>
 776  <li> bugfix: compatibility with new versions of pdftoppm (thanks to
 777       Vincenzo Ciancia)</li>
 778  <li>GTK+ 2.11 event processing bugfix</li>
 779  <li>minor bugfixes: hand tool, handling of filenames containing '&amp;'</li>
 780  <li>desktop and MIME files (thanks to Mathieu Bouchard) + updated installer</li>
 781  <li>config options: left-handed scrollbar (contributed by Uwe Winter),
 782      hide some menu items (customizable in config file), auto-save
 783      preferences</li>
 784 </ul>
 785 </p>
 786 <p>
 787 Version 0.4.0.1 (September 3, 2007):
 788 <ul>
 789  <li>bugfixes for GTK+ 2.11 behavior (thanks to everyone who reported bugs)</li>
 790 </ul>
 791 </p>
 792 <p>
 793 Version 0.4 (August 15, 2007):
 794 <ul>
 795  <li>text tool (handles most TrueType and Type1 fonts)</li>
 796  <li>font selection dialog and button</li>
 797  <li>keyboard mappings (arrow keys)</li>
 798  <li>menu mnemonics and shortcuts (suggestions by Jean-Baptiste Rouquier)</li>
 799  <li>more responsive hand tool</li>
 800  <li>bugfix for GTK+ 2.11 XInput behavior (thanks to Robert Gerlach)</li>
 801  <li>various minor bugfixes and enhancements</li>
 802 </ul>
 803 </p>
 804 <p>
 805 Version 0.3.3 (January 31, 2007):
 806 <ul>
 807  <li>bugfix: upon loading a new file, zoom is set to default startup zoom</li>
 808  <li>config option to allow input from a mouse or other core pointer device</li>
 809  <li>config file entry to specify a default location for open/save
 810      (patch contributed by Andy Neitzke)</li>
 811  <li>config file entries to customize visibility and position of toolbars</li>
 812  <li>icon (thanks to Michele Codutti)</li>
 813 </ul>
 814 </p>
 815 <p>
 816 Version 0.3.2 (November 25, 2006):
 817 <ul>
 818  <li>preferences file and Save Preferences command</li>
 819  <li>extra customization (via preferences file)</li>
 820  <li>minor UI changes (patch contributed by Eduardo de Barros Lima)</li>
 821  <li>hand tool (partially contributed by Vincenzo Ciancia)</li>
 822  <li>a few bugfixes in rendering of bitmap backgrounds</li>
 823 </ul>
 824 <p>
 825 Version 0.3.1 (August 3, 2006):
 826 <ul>
 827  <li>fixed a file format bug on systems with non-standard numeric locale
 828      (bug reported by Gert Renckens)</li>
 829 </ul>
 830 </p>
 831 <p>
 832 Version 0.3 (July 23, 2006):
 833 <ul>
 834  <li>new PDF rendering engine: export to PDF generates optimized files
 835    (smaller and more accurate)</li>
 836  <li>export to PDF handles PDF backgrounds (up to PDF-1.4) natively
 837     (without conversion to bitmap)</li>
 838  <li>default thickness of erasers and highlighters slightly increased</li>
 839  <li>zoom dialog box with input box and "fit to page height" option</li>
 840  <li>file format documentation added to the user's manual</li>
 841 </ul>
 842 </p>
 843 <p>
 844 Version 0.2.2 (June 5, 2006):
 845 <ul>
 846  <li>mapping of tools to stylus buttons (the options menu has new entries
 847     to allow the mapping of buttons 2 and 3 to arbitrary tools; the tools
 848     menu and toolbar affect the settings for button 1)
 849     (see <a href="manual.html#mappings">here</a>)</li>
 850  <li>moving selection by drag-and-drop works across page boundaries</li>
 851  <li>vertical space tool can move items to next page (only when the entire
 852     block being moved has crossed the page boundary; items on the new page
 853     are not moved)</li>
 854  <li>"apply to all pages" is now a toggle button affecting the behavior of
 855     paper size, color, and style commands</li>
 856  <li>change in the behavior of the selection upon switching between tools</li>
 857 </ul>
 858 </p>
 859 <p>
 860 Version 0.2.1 (June 3, 2006):
 861 <ul>
 862  <li>recently used files listed in file menu</li>
 863  <li>can change color or thickness of pen strokes in selection</li>
 864  <li>function to apply paper style to all pages</li>
 865  <li>can specify on command line a PDF file to annotate</li>
 866  <li>suggest a derived file name for PDF annotation</li>
 867  <li>speed up switching between pages</li>
 868  <li>fixed a bug in XInput initialization (thanks to Luca de Cicco)</li>
 869  <li>fixed a bug in print ranges (thanks to Mathieu Bouchard)</li>
 870  <li>fixed a refresh bug in rescaling bitmap backgrounds</li>
 871 </ul>
 872 </p>
 873 <p>
 874 Version 0.2 (January 29, 2006):
 875 <ul>
 876  <li>PDF file annotation using xpdf's pdftoppm
 877       (PDF backgrounds updated asynchronously at all resolutions)</li>
 878  <li>PS/PDF backgrounds (as bitmaps at fixed resolution) using ghostscript</li>
 879  <li>option to antialias and filter bitmap backgrounds when zooming</li>
 880  <li>option to emulate eraser tip with right mouse button</li>
 881  <li>binary installer allows non-root installation without compiling</li>
 882  <li>full-screen mode (patch contributed by Luca De Cicco)</li>
 883 </ul>
 884 </p>
 885 <p>
 886 Version 0.1.1 (January 5, 2006):
 887 <ul>
 888  <li> two bugfixes </li>
 889  <li> backward compatibility with GTK+ 2.4 </li>
 890 </ul>
 891 </p>
 892 <p>
 893 Version 0.1 (January 2, 2006): initial release.
 894 </p>
 895 <hr />
 896 <a name="file-format"></a>
 897 <h2 class="subtitle">The file format</h2>
 898 <h3 class="subsub">Overall structure</h3>
 899 <p>
 900 Xournal stores its data in gzipped XML-like files. The gzipped data consists
 901 of a succession of XML tags describing the document. By convention, the
 902 file header and trailer look like this:
 903 <pre>
 904 &lt;?xml version="1.0" standalone="no"?&gt;
 905 &lt;xournal version="..."&gt;
 906 &lt;title&gt;Xournal document - see http://math.mit.edu/~auroux/software/xournal/&lt;/title&gt;
 907 ... sequence of pages ...
 908 &lt;/xournal&gt;
 909 </pre>
 910 The &lt;title&gt; and &lt;xournal&gt; tags may only appear within the file
 911 header (not within the pages of the document). The <i>version</i> attribute of
 912 the &lt;xournal&gt; tag indicates which version of Xournal was used to
 913 create the document; it is currently ignored, but may be used in a later
 914 release if the file format changes in an incompatible manner.
 915 (Following a suggestion of Matteo Abrate, starting with version 0.4 the
 916 &lt;xournal&gt; tag is the document's root tag, and encloses all other tags).
 917 </p>
 918 <p>
 919 The rest of the file is a sequence of pages, specified by a
 920 &lt;page&gt; tag, whose attributes <i>width</i> and <i>height</i> specify the
 921 physical size of the page in points (1/72 in). The width and height
 922 parameters are floating point values. The format of a page is therefore:
 923 <pre>
 924 &lt;page width="..." height="..."&gt;
 925 ... page contents ...
 926 &lt;/page&gt;
 927 </pre>
 928 </p>
 929 <h3 class="subsub">Page background</h3>
 930 <p>
 931 The first entry within a page describes the page background.
 932 It consists of a &lt;background&gt; tag followed by several mandatory
 933 XML attributes. The first attribute is always <i>type</i>, which
 934 can take three possible values: "solid" for a solid background, "pixmap"
 935 for a bitmap background, and "pdf" if the background is a page of a PDF
 936 document. The rest of the attributes depends on the type of background.
 937 <ul>
 938 <li><p> Solid background: <tt>&lt;background type="solid" color="..."
 939 style="..." /&gt;</tt> <br />The <i>color</i> attribute takes one of
 940 the standard values "white", "yellow", "pink", "orange", "blue", "green",
 941 or can specify a hexadecimal RGBA value in the format "#rrggbbaa". The
 942 <i>style</i> attribute takes one of the standard values "plain", "lined",
 943 "ruled", or "graph".</p>
 944 </li>
 945 <li><p> Bitmap background: <tt>&lt;background type="pixmap" domain="..."
 946 filename="..." /&gt;</tt> <br />
 947 The <i>domain</i> attribute takes one of the standard values "absolute",
 948 "attach", or "clone". A value of "absolute" indicates that the bitmap is
 949 found in the file specified by <i>filename</i>. The bitmap can be in any
 950 format recognized by the gdk-pixbuf library; this includes most of the
 951 common bitmap formats (JPEG, PNG, BMP, GIF, PCX, PNM, TIFF, ...).
 952 <br />A value
 953 of "attach" indicates that the bitmap is an attachment to the Xournal file.
 954 The bitmap is in PNG format, and resides in a file whose name is derived
 955 from that of the main Xournal file by appending to it a dot and the contents
 956 of the <i>filename</i> attribute. For example, if the Xournal file is in
 957 <tt>file.xoj</tt> and the <i>filename</i> attribute is <tt>"bg_1.png"</tt>
 958 then the bitmap file is <tt>file.xoj.bg_1.png</tt> (Xournal saves attached
 959 bitmaps sequentially in files ...bg_1.png, ...bg_2.png, etc.)
 960 <br />A value of "clone" indicates that the bitmap is identical to the
 961 background of a previous page of the journal; the <i>filename</i> attribute
 962 then specifies the page number, starting with 0 for the first page. For
 963 example, if a <i>filename</i> value of <tt>"1"</tt> indicates that the
 964 background bitmap is identical to that of the second page.
 965 </p>
 966 </li>
 967 <li><p> PDF background: <tt>&lt;background type="pdf" domain="..."
 968 filename="..." pageno="..." /&gt;</tt> or
 969 <tt>&lt;background type="pdf" pageno="..." /&gt;</tt>
 970 <br />The <i>domain</i> and <i>filename</i> attributes must be specified
 971 for the first page of the journal that uses a PDF background, and must
 972 be omitted subsequently for every other page that uses a PDF background.
 973 The <i>domain</i> attribute takes one of the standard values
 974 "absolute" and "attach"; the PDF document is to be found in the file
 975 specified by <i>filename</i> (if <i>domain</i> is "absolute"), or in the
 976 file whose name is obtained by appending a dot and the contents of the
 977 <i>filename</i> attribute to the name of the main Xournal file (if
 978 <i>domain</i> is "attach"). The <i>pageno</i> attribute specifies which
 979 page of the PDF file is used as background, starting with 1 for the first
 980 page of the PDF file.
 981 </p>
 982 </li>
 983 </ul>
 984 </p>
 985 <h3 class="subsub">Layers and strokes</h3>
 986 <p>
 987 After the line specifying the background, the remainder of a &lt;page&gt;
 988 section is occupied by one or more layer sections
 989 <pre>&lt;layer&gt; ... &lt;/layer&gt;</pre>
 990 describing the various items within a layer. Every page must
 991 contain at least one layer; a layer may be empty. The successive layers
 992 are listed in their stacking order, from bottom to top.
 993 </p>
 994 <p>
 995 A layer consists of a collection of items, listed in the order in which
 996 they should be drawn
 997 (from bottom-most to top-most).
 998 Up to version 0.3.3, the only legal contents within a layer are
 999 strokes. The format of a stroke is:
1000 <pre>&lt;stroke tool="..." color="..." width="..."&gt;
1001 ... list of coordinates ...
1002 &lt;/stroke&gt;
1003 </pre>
1004 The <i>tool</i> attribute can take the values "pen", "highlighter", or
1005 "eraser" depending on the tool used to create the stroke (pen, highlighter,
1006 or whiteout eraser); a value of "highlighter" indicates that the stroke
1007 should be painted in a partially transparent manner (Xournal uses an alpha
1008 coefficient of 0.5).
1009 </p>
1010 <p>
1011 The <i>color</i> attribute can take one of the standard values "black",
1012 "blue", "red", "green", "gray", "lightblue", "lightgreen", "magenta",
1013 "orange", "yellow", "white", or can specify a hexadecimal RGBA value in
1014 the format "#rrggbbaa".
1015 </p>
1016 <p>
1017 The <i>width</i> attribute is a floating-point
1018 number (or a sequence of floating-point numbers starting with version 0.4.2),
1019 and specifies the width of the stroke in points (1/72 in). (For a
1020 variable-width stroke, the <i>width</i> attribute contains a
1021 whitespace-separated succession of floating-point values: first the
1022 nominal brush width, and then the width of each successive segment forming
1023 the stroke.)
1024 </p>
1025 <p>
1026 The list of coordinates is simply a succession of floating-point values,
1027 separated by whitespace.
1028 The number of given values must be even; consecutive pairs of values give
1029 the <i>x</i> and <i>y</i> coordinates of each point along the stroke.
1030 These values are expressed in points (1/72 in). The coordinates (0,0)
1031 represent the top-left corner of the page: hence x is measured from the left
1032 of the page, and y is measured from the top of the page.
1033 </p>
1034 <p>
1035 Every stroke must contain at least two points (four floating point values).
1036 Moreover, two consecutive points on the stroke should be spaced no more
1037 than 5 units apart or so; longer line segments should be subdivided as
1038 appropriate (otherwise the eraser tool will not interact properly with the
1039 stroke). The default precision used by Xournal for the x,y coordinates is
1040 0.01 unit (1/7200 in).
1041 </p>
1042 <p>Starting with version 0.4, layers also contain text items.
1043 The format of a text item is:
1044 <pre>&lt;text font="..." size="..." x="..." y="..." color="..."&gt;... text ...&lt;/text&gt;
1045 </pre>
1046 The <i>font</i> attribute contains the font name, for example "Serif Bold
1047 Italic"; if the font is not available, another font will be substituted.
1048 The <i>size</i> attribute specifies the font size in points. The <i>x</i>
1049 and <i>y</i> attributes specify the coordinates of the top-left corner
1050 of the text box in page coordinates (measured in points from the top-left
1051 corner of the page). Finally, the <i>color</i> attribute contains either
1052 the name of a standard color or a hexadecimal RGBA value (see above).
1053 </p>
1054 <p>
1055 The contents of the text are encoded in UTF-8, with the characters
1056 <tt>'&amp;', '&lt;', '&gt;'</tt> replaced by <tt>&amp;amp;, &amp;lt;,
1057 &amp;gt;</tt>. Whitespace and linefeeds are preserved (in particular,
1058 no extraneous whitespace should be inserted between the enclosing tags
1059 and the text itself).
1060 </p>
1061 <hr />
1062 <a name="installation"></a>
1063 <h2 class="subtitle">Installation issues</h2>
1064 <h3 class="subsub">Dependencies</h3>
1065 <p>
1066 The following libraries are required to run Xournal (they are standard on
1067 modern Linux distributions such as Fedora 6 or later, RHEL 5 or
1068 later, Ubuntu 6.10 or later, etc.):
1069 <ul>
1070  <li> the <b>gtk+</b> libraries, version <b>2.10</b> or later
1071  (package gtk2 and dependencies)</li>
1072  <li> <b>libgnomecanvas</b> version <b>2.4</b> or later &nbsp;
1073  (package libgnomecanvas and dependencies)</li>
1074  <li> <b>poppler-glib</b> version <b>0.5.4</b> or later &nbsp;
1075  (package poppler-glib and dependencies)</li>
1076 </ul>
1077 </p>
1078 <p>
1079  Optional:
1080 <ul>
1081  <li> ghostscript (optional: used to import PS/PDF files as bitmap
1082  backgrounds)</li>
1083 </ul>
1084 <p>
1085 To compile Xournal, you also need the <b>development packages</b> for the above
1086 libraries (packages gtk2-devel, libgnomecanvas-devel, poppler-glib-devel,
1087 and dependencies), as well as <b>autoconf</b> and
1088 <b>automake</b>.
1089 </p>
1090 <h3 class="subsub">Compilation and installation procedure</h3>
1091 <p>
1092 Download the Xournal distribution tar.gz file, and any needed dependencies.
1093 </p>
1094 <p>
1095 <b>Compilation and installation in /usr/local:</b>
1096 <pre>
1097 ./configure
1098 make
1099 (as root) make install
1100 (as root) make desktop-install
1101 </pre>
1102 </p>
1103 <p>
1104 <b>Compilation and installation in $HOME:</b>
1105 <pre>
1106 ./configure --prefix=$HOME
1107 make
1108 make install
1109 make home-desktop-install
1110 </pre>
1111 </p>
1112 <p><b>Configure error message:</b> <br />
1113 If configure generates the error message
1114 &nbsp; &nbsp; <tt><i>
1115 configure: error: Package requirements (gtk+-2.0 >= 2.10.0
1116 libgnomecanvas-2.0 >= 2.4.0 poppler-glib >= 0.5.4)  not met
1117 </i></tt> &nbsp; &nbsp;
1118 even though you have sufficiently recent versions of these libraries on your
1119 system, then you need to install some missing development packages.
1120 </p>
1121 <hr />
1122 <a name="calibration"></a>
1123 <h2 class="subtitle">Tablet calibration issues</h2>
1124 <p>
1125 Configuring the tablet devices properly is unfortunately not as simple as it
1126 ought to be. This is a subject worthy of a detailed how-to document;
1127 meanwhile, here are some hints about how to configure your tablet.
1128 </p>
1129 <h3 class="subsub">Basics</h3>
1130 <p>
1131 Xournal uses the XInput extension to obtain high-resolution coordinates for
1132 strokes drawn using the stylus. If you decide that getting just the right
1133 XInput configuration isn't worth the effort, you can disable XInput features
1134 by unsetting the "Use XInput" option in the Options menu. The price to pay
1135 is a lower graphics quality, as the resolution of all strokes then drops to
1136 1 pixel (instead of the native resolution of the tablet device, which can
1137 be higher by several orders of magnitude).
1138 </p>
1139 <p>
1140 The configuration of tablet devices is controlled in the X server's
1141 configuration file (usually <b>/etc/X11/xorg.conf</b> depending on your
1142 distribution). The latest X servers can detect a tablet automatically and
1143 do not require the presence of xorg.conf to work properly; so recent
1144 distributions typically no longer includde such a file. However, if
1145 auto-configuration fails, you can always create a xorg.conf that explicitly
1146 specifies tablet devices.
1147 </p>
1148 <p>
1149 Assuming you do have a xorg.conf, the ServerLayout section should contain lines like:
1150 <pre>
1151 Section "ServerLayout"
1152         ...
1153         InputDevice    "cursor" "SendCoreEvents"
1154         InputDevice    "stylus" "SendCoreEvents"
1155         InputDevice    "eraser" "SendCoreEvents"
1156 EndSection
1157 </pre>
1158 (the last one only if your stylus has an eraser tip), and your configuration
1159 file should include sections such as
1160 <pre>
1161 Section "InputDevice"
1162         Identifier "cursor"
1163         Driver "wacom"
1164         Option "Device" "/dev/ttyS0"
1165         Option "Type" "cursor"
1166         Option "ForceDevice" "ISDV4"
1167         Option "BottomX" "28800"
1168         Option "BottomY" "21760"
1169         Option "Mode" "absolute"
1170 EndSection
1171
1172 Section "InputDevice"
1173         Identifier "stylus"
1174         Driver "wacom"
1175         Option "Device" "/dev/ttyS0"
1176         Option "Type" "stylus"
1177         Option "ForceDevice" "ISDV4"
1178         Option "BottomX" "28800"
1179         Option "BottomY" "21760"
1180         Option "Mode" "absolute"
1181 EndSection
1182
1183 Section "InputDevice"
1184         Identifier "eraser"
1185         Driver "wacom"
1186         Option "Device" "/dev/ttyS0"
1187         Option "Type" "eraser"
1188         Option "ForceDevice" "ISDV4"
1189         Option "BottomX" "28800"
1190         Option "BottomY" "21760"
1191         Option "Mode" "absolute"
1192 EndSection
1193 </pre>
1194 The actual settings will depend on your hardware; look on the web for Linux
1195 installation instructions specific to your model: for example, the
1196 "Device" settings above correspond to a serial port protocol, many tablets
1197 use USB instead; the BottomX and BottomY values correspond to the physical
1198 resolution of the tablet and will vary from one model to another.
1199 </p>
1200 <p>
1201 For historical reasons, most X servers do not allow the input device
1202 designated as the "core pointer" in the X server's configuration file
1203 to be used as an XInput extension device. Thus, your tablet input devices
1204 should <b>not</b> be designated as the core pointer device. Instead, they
1205 should be configured with the "SendCoreEvents" option, which enables them
1206 to simultaneously generate XInput extension events and move the cursor on
1207 the screen.
1208 </p>
1209 <p>
1210 <b>If you have a newer X server</b> and no xorg.conf file, the input devices can be
1211 configured using the <i>xinput</i> command.
1212 </p>
1213 <p>
1214 <b>Note:</b> with older X servers, only tablet devices are XInput devices, while
1215 a built-in pointing device or an external mouse would only act as the core
1216 pointer. In newer X servers, all devices are handled through XInput (even
1217 though without advanced capabilities), though mice and touchpads typically
1218 send invalid event data. Xournal tries to work around the most common bugs
1219 in input device drivers and GTK+ input event processing.
1220 </p>
1221 <h3 class="subsub">The cursor doesn't appear in the right place...</h3>
1222 <p>
1223 If the mouse pointer does not follow accurately the position of the stylus,
1224 this is an indication that your tablet is not properly calibrated. If you
1225 have the linuxwacom package, you can try modifying the tablet calibration
1226 using <b>xsetwacom</b>. The relevant parameters are named TopX, BottomX,
1227 TopY, BottomY, and need to be set separately for the stylus and for the
1228 eraser. For example:
1229 <pre>
1230     xsetwacom set stylus TopX 270
1231     xsetwacom set stylus BottomX 28510
1232     ...
1233 </pre>
1234 (the TopX and TopY parameters default to 0 if you haven't set them in your
1235 X server's configuration file). Experiment with these parameters until you
1236 find the right calibration settings for your tablet (i.e., the mouse pointer
1237 appears right under the tip of the stylus).
1238 </p>
1239 <p>
1240 Once you have found the perfect settings for your tablet, update your X
1241 server's configuration file or startup scripts.
1242 </p>
1243 <p>
1244 <b>Important:</b> on older systems, the TopX and TopY values should always
1245 be kept at 0 to avoid calibration bugs.
1246 </p>
1247 <h3 class="subsub">The cursor is in the right place, but strokes aren't
1248 drawn under the cursor...</h3>
1249 <p>
1250 If you experience this while trying to draw with a mouse, touchpad, or other
1251 non-tablet device:
1252 <ul>
1253 <li> If you don't have a tablet, simply disable "Use XInput" in the Options
1254 menu, this is the fastest way of fixing the problem.</li>
1255 <li> Upgrade to a recent version of Xournal (0.4.5 or later). Older versions
1256 of Xournal are not compatible with the event handling code of recent X server
1257 and GTK+ library versions.</li>
1258 <li> Check that the "Discard Core Events" option is disabled
1259 (<tt>discard_corepointer</tt> should be set to <tt>false</tt> in
1260 ~/.xournal/config).</li>
1261 </ul>
1262 If you experience this while trying to draw with a tablet pen:
1263 <ul>
1264 <li> If you are using an obsolete version of the linuxwacom driver (before
1265 0.7.6) or of GTK+, please upgrade your system.</li>
1266 <li>If you are using GTK+ 2.17 or newer, please upgrade to Xournal 0.4.5 or
1267 later. The input event processing behavior of GTK+ has changed and is no
1268 longer compatible with older versions of Xournal.</li>
1269 <li> The display geometry might have changed since the beginning of your
1270 session in Xournal
1271 (resolution changed, external monitor connected, display rotated, etc.).
1272 You need to exit Xournal and re-start it each time your display
1273 configuration changes.</li>
1274 <li> Your tablet devices might be incorrectly calibrated or configured.</li>
1275 </ul>
1276 If all else fails, you can disable XInput support in Xournal (in the
1277 Options menu), at a price of a severe loss of resolution (and the eraser tip
1278 won't be detected anymore).
1279 </p>
1280 <p>
1281 I have also had a report that one of the workarounds used by Xournal to
1282 bypass a calibration bug in GTK+ can actually entirely prevent strokes
1283 from being drawn. If you are being unsuccessful at drawing in Xournal
1284 with XInput enabled, try recompiling after commenting out the line
1285 <pre>#define ENABLE_XINPUT_BUGFIX</pre>
1286 near the beginning of <tt>src/xournal.h</tt>.
1287 If this modification does improve things for you, and if you have a bit
1288 of spare time to help investigate the causes of this problem, please
1289 contact me.
1290 </p>
1291 <h3 class="subsub">On-the-fly display rotation</h3>
1292 <p>
1293 You need an X server that supports the RANDR extension, and a sufficiently
1294 recent (0.7.6 or later)
1295 version of the linuxwacom driver to support on-the-fly rotation.
1296 </p>
1297 <p>
1298 To set the tablet in portrait mode:
1299 <pre>
1300   xrandr -o 3
1301   xsetwacom set stylus Rotate cw
1302 </pre>
1303 To return to landscape mode:
1304 <pre>
1305   xrandr -o 0
1306   xsetwacom set stylus Rotate none
1307 </pre>
1308 <b>Note #1:</b> you should not rotate the display while Xournal is running,
1309 otherwise the tablet calibration in Xournal may (and most likely will)
1310 become incorrect.
1311 Exit Xournal and restart it after the display has been rotated.
1312 </p>
1313 <p>
1314 <b>Note #2:</b> the syntax of xrandr commands has changed in newer X servers.
1315 Consult the xrandr manual page for the new syntax.
1316 </body>
1317 </html>