X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=html-doc%2Fmanual.html;fp=html-doc%2Fmanual.html;h=5ed27187ceb82ebbff7bf42213e5d7129147f69e;hb=59df9eb838b273295a6b86ce9f522dc4ad71dc4d;hp=cf97892ec9cf7329260527d4cd0285d1d12b83fa;hpb=ddd27893ae44eb5eb62c80e5751a6943a4782fe2;p=xournal.git diff --git a/html-doc/manual.html b/html-doc/manual.html index cf97892..5ed2718 100644 --- a/html-doc/manual.html +++ b/html-doc/manual.html @@ -24,7 +24,7 @@ Xournal User's Manual
- Version 0.2.2 + Version 0.3
@@ -427,10 +427,10 @@ PDF files (for example pdfmerge).
Xournal uses the gnome-print architecture for printing. While it is very -powerful, some aspects of the API leave to be desired, -and future versions of Xournal will probably also include a native -Postscript/PDF printing feature. +powerful, some aspects of the API leave to be desired. As of version 0.3, +Xournal also includes a native PDF printing feature.
+The "Printer" tab of the print dialog box lets you select a printer (either one of the printers installed on your system, or the generic @@ -448,18 +448,34 @@ attempts to pre-fill the output file name (for the Postscript driver this often fails due to gnome-print API issues).
-The "Print to PDF" entry of the File menu directly generates a PDF file -using the PDF virtual printer, without bringing up the dialog box -(the page size is the default one for that printer, usually A4). Note that the PDF virtual printer produces files that are very large -and far from optimal, so in the current state of things it is better -to generate a Postscript file and use a converter such as ps2pdf. -
-+and far from optimal, so its use is not recommended. The gnome-print architecture also forces page backgrounds (bitmaps and PDF) to be generated as uncompressed bitmaps, which leads to gigantic -print job files. An alternative to gnome-print will be -implemented in a future release of Xournal. +print job files. A better alternative is to export a PDF file, and +print the PDF file. +
++Starting with version 0.3, Xournal provides its own PDF rendering +engine. The "Export to PDF" command (in the File menu) produces a +PDF-1.4 file from the currently loaded document. The resulting PDF +file is much more compact than those produced via gnome-print, and +its pages have the same size as in Xournal. Highlighter strokes +are rendered in a partially transparent manner (note however that +applications such as xpdf and ghostview do not always handle +PDF transparency properly). +
++Xournal also includes a PDF file parser compatible with PDF format +version 1.4; the compression features of PDF 1.5 (Acrobat 6) are +not supported. When exporting a document that uses PDF +backgrounds, Xournal attempts to preserve most of the structure of +the original PDF file (however, auxiliary data such as thumbnails, hyperlinks, +and annotations are lost). If Xournal is unable to parse the PDF +file, the backgrounds are converted to (compressed) bitmaps and a new +PDF file is generated from scratch. +
Feel free to contact me with bug reports and suggestions; I apologize in advance if I am unable to respond properly to some requests. -List of known bugs/misfeatures (no need to report them again): -
If you find a sequence of operations which crashes Xournal in a reproducible manner, please send detailed instructions on how to reproduce the crash. A core file may also be helpful. @@ -490,6 +499,18 @@ Bug reports and suggestions can also be submitted on Xournal's
+Version 0.3 (July 23, 2006): +
Version 0.2.2 (June 5, 2006):
-XOJ files are gzipped XML-like files. A more precise documentation of -the file format will be added at a later date. Meanwhile, most of the -format should be easy to figure out by trial-and-error or by looking -at the source; if some details are unclear, feel free to ask. +Xournal stores its data in gzipped XML-like files. The gzipped data consists +of a succession of XML tags describing the document. By convention, the +first few lines contain a header in the following format: +
+<?xml version="1.0" standalone="no"?> +<title>Xournal document - see http://math.mit.edu/~auroux/software/xournal/</title> +<xournal version="..."/> ++The <title> and <xournal> tags may only appear within the file +header (not within the pages of the document). The version attribute of +the <xournal> tag indicates which version of Xournal was used to +create the document; it is currently ignored, but may be used in a later +release if the file format changes in an incompatible manner. + +
+The rest of the file is a sequence of pages, specified by a +<page> tag, whose attributes width and height specify the +physical size of the page in points (1/72 in). The width and height +parameters are floating point values. The format of a page is therefore: +
+<page width="..." height="..."> +... page contents ... +</page> ++ +
+The first entry within a page describes the page background. +It consists of a <background> tag followed by several mandatory +XML attributes. The first attribute is always type, which +can take three possible values: "solid" for a solid background, "pixmap" +for a bitmap background, and "pdf" if the background is a page of a PDF +document. The rest of the attributes depends on the type of background. +
Solid background: <background type="solid" color="..."
+style="..." />
The color attribute takes one of
+the standard values "white", "yellow", "pink", "orange", "blue", "green",
+or can specify a hexadecimal RGBA value in the format "#rrggbbaa". The
+style attribute takes one of the standard values "plain", "lined",
+"ruled", or "graph".
Bitmap background: <background type="pixmap" domain="..."
+filename="..." />
+The domain attribute takes one of the standard values "absolute",
+"attach", or "clone". A value of "absolute" indicates that the bitmap is
+found in the file specified by filename. The bitmap can be in any
+format recognized by the gdk-pixbuf library; this includes most of the
+common bitmap formats (JPEG, PNG, BMP, GIF, PCX, PNM, TIFF, ...).
+
A value
+of "attach" indicates that the bitmap is an attachment to the Xournal file.
+The bitmap is in PNG format, and resides in a file whose name is derived
+from that of the main Xournal file by appending to it a dot and the contents
+of the filename attribute. For example, if the Xournal file is in
+file.xoj and the filename attribute is "bg_1.png"
+then the bitmap file is file.xoj.bg_1.png (Xournal saves attached
+bitmaps sequentially in files ...bg_1.png, ...bg_2.png, etc.)
+
A value of "clone" indicates that the bitmap is identical to the
+background of a previous page of the journal; the filename attribute
+then specifies the page number, starting with 0 for the first page. For
+example, if a filename value of "1" indicates that the
+background bitmap is identical to that of the second page.
+
PDF background: <background type="pdf" domain="..."
+filename="..." pageno="..." /> or
+<background type="pdf" pageno="..." />
+
The domain and filename attributes must be specified
+for the first page of the journal that uses a PDF background, and must
+be omitted subsequently for every other page that uses a PDF background.
+The domain attribute takes one of the standard values
+"absolute" and "attach"; the PDF document is to be found in the file
+specified by filename (if domain is "absolute"), or in the
+file whose name is obtained by appending a dot and the contents of the
+filename attribute to the name of the main Xournal file (if
+domain is "attach"). The pageno attribute specifies which
+page of the PDF file is used as background, starting with 1 for the first
+page of the PDF file.
+
+After the line specifying the background, the remainder of a <page> +section is occupied by one or more layer sections +
<layer> ... </layer>+describing the various strokes within a layer. Every page must +contain at least one layer; a layer may be empty. The successive layers +are listed in their stacking order, from bottom to top. + +
+A layer consist of a collection of items, listed in the order in which +they should be drawn +(from bottom-most to top-most). +As of the current version, the only legal contents within a layer are +strokes. The format of a stroke is: +
<stroke tool="..." color="..." width="..."> +... list of coordinates ... +</stroke> ++The tool attribute can take the values "pen", "highlighter", or +"eraser" depending on the tool used to create the stroke (pen, highlighter, +or whiteout eraser); a value of "highlighter" indicates that the stroke +should be painted in a partially transparent manner (Xournal uses an alpha +coefficient of 0.5). +The color attribute can take one of the standard values "black", +"blue", "red", "green", "gray", "lightblue", "lightgreen", "magenta", +"orange", "yellow", "white", or can specify a hexadecimal RGBA value in +the format "#rrggbbaa". The width attribute is a floating-point +number and specifies the width of the stroke in points (1/72 in). + +
+The list of coordinates is simply a succession of floating-point values, +separated by whitespace. +The number of given values must be even; consecutive pairs of values give +the x and y coordinates of each point along the stroke. +These values are expressed in points (1/72 in). The coordinates (0,0) +represent the top-left corner of the page: hence x is measured from the left +of the page, and y is measured from the top of the page. +
++Every stroke must contain at least two points (four floating point values). +Moreover, two consecutive points on the stroke should be spaced no more +than 5 units apart or so; longer line segments should be subdivided as +appropriate (otherwise the eraser tool will not interact properly with the +stroke). The default precision used by Xournal for the x,y coordinates is +0.01 unit (1/7200 in).