1 <page xmlns="http://projectmallard.org/1.0/"
2 xmlns:e="http://projectmallard.org/experimental/"
7 <link type="guide" xref="index#advanced"/>
8 <revision pkgversion="3.0" version="0.1" date="2010-05-04" status="incomplete"/>
10 Create your templates manually.
12 <credit type="author">
13 <name>Jim Evins</name>
14 <email>evins@snaught.com</email>
16 <credit type="author">
17 <name>Mario Blättermann</name>
18 <email>mariobl@gnome.org</email>
21 <p>Creative Commons Share Alike 3.0</p>
25 <title>Manually creating new templates</title>
27 <p>Predefined templates are defined by XML files located in
28 either <file>/usr/share/libglabels-3.0/templates/</file> or
29 <file>/usr/local/share/libglabels-3.0/templates/</file>,
30 depending on where <app>glabels</app> was installed. <app>Glabels</app> will
31 also search for user defined templates in the directory
32 <file>${HOME}/.config/libglabels/templates/</file>. User
33 defined template files should be named with a
34 <file>*.template</file> extension.
37 <p>The format for these files is defined in the DTD:
38 <link href="http://glabels.org/xmlns/2.3/glabels-2.3.dtd.txt">glabels-2.3.dtd</link>.
39 (This DTD also describes other XML formats used by <app>glabels</app>.)</p>
41 <section id="template-assumptions">
42 <title>Assumptions/caveats</title>
45 <p>A sheet contains only one size of label or card (if a sheet
46 contains more than one size of item, it can be split into
47 multiple templates for multiple pass printing)</p>
50 <p>Distances can be expressed in units of <em>pt</em>,
51 <em>in</em>, <em>mm</em>,
52 <em>cm</em>, or <em>pc</em>. For example:
53 "<literal>1.0in</literal>" or "<literal>2.54cm</literal>". If no
54 units are specified, computer points (<em>pt</em>) will
55 be assumed (1 <em>pt</em> =
56 1/72 <em>in</em> = 0.352778 <em>mm</em>).
62 <section id="template-file">
63 <title>Template Files</title>
66 <?xml version="1.0"?>
67 <Glabels-templates>
69 <replaceable>...templates...</replaceable>
71 </Glabels-templates>
76 <section id="template-example">
77 <title>Example Template</title>
79 <Template brand="Avery" part="8160" size="US-Letter" description="Mailing Labels">
80 <Meta category="label"/>
81 <Meta category="mail"/>
82 <Meta product_url="http://www.avery.com/avery/en_us/"/>
83 <Label-rectangle id="0" width="189pt" height="72pt" round="5pt">
84 <Markup-margin size="5pt"/>
85 <Layout nx="3" ny="10" x0="11.25pt" y0="36pt" dx="200pt" dy="72pt"/>
86 </Label-rectangle>
87 <Alias brand="Avery" part="5160"/>
88 <Alias brand="Avery" part="6233"/>
93 <section id="template-template-node">
94 <title>Template Node</title>
96 <p>A <em>Template</em> node describes a single stationary
97 product. It must contain one instance of any type of Label node
98 (<em>Label-rectangle</em>,
99 <em>Label-round</em>, or <em>Label-cd</em>).
100 This node can be followed by zero or more
101 <em>Alias</em> nodes.</p>
103 <table frame="all" rules="rows">
105 <td><p>Property</p></td> <td><p>Description</p></td>
108 <td><p></p></td> <td><p></p></td>
111 <td><p>brand</p></td> <td><p>Brand or manufacturer of stationary product. E.g. "Avery"</p></td>
114 <td><p>part</p></td> <td><p>Part number or name of stationary product. E.g. "8160"</p></td>
117 <td><p>size</p></td> <td><p>Size of sheet. E.g., "US-Letter," "A4", ...</p></td>
120 <td><p>description</p></td> <td><p>Description of stationary product. E.g, "Mailing Labels."</p></td>
123 <td><p>_description</p></td> <td><p>Translatable description of stationary product. E.g, "Mailing Labels." (Only useful for predefined templates)</p></td>
126 <td><p>width</p></td> <td><p>Page width. Only valid if size="Other"</p></td>
129 <td><p>height</p></td> <td><p>Page height. Only valid if size="Other"</p></td>
135 <section id="template-template-node">
136 <title>Meta Node</title>
138 <p>A <em>Meta</em> node contains some additional properties of that product.
139 This node may appear more than once, with a subnode each.</p>
141 <table frame="all" rules="rows">
143 <td><p>Subnode</p></td> <td><p>Description</p></td>
146 <td><p></p></td> <td><p></p></td>
149 <td><p>category</p></td> <td><p>The category which this product is assigned to. The value
150 of this category is used by the <app>gLabels'</app> template chooser to filter the
151 view to display only mailing labels, or labels in common and suppress any other products
152 which the user don't want to find. One product can be assigned to several categories.</p></td>
155 <td><p>product_url</p></td> <td><p>This address points to the vendor's website. Ideally,
156 the link shows the URL of that certain product, if available.</p></td>
162 <section id="template-label-rectangle-node">
163 <title>Label-rectangle Node</title>
165 <p>A <em>Label-rectangle</em> node describes the
166 dimensions of a single label or business card that is rectangular
167 in shape (may have rounded edges).</p>
169 <table frame="all" rules="rows">
171 <td><p>Property</p></td> <td><p>Description</p></td>
174 <td><p></p></td> <td><p></p></td>
177 <td><p>id</p></td> <td><p>Reserved for future use. Should always be 0.</p></td>
180 <td><p>width</p></td> <td><p>Width of label/card</p></td>
183 <td><p>height</p></td> <td><p>Heigth of label/card</p></td>
186 <td><p>round</p></td> <td><p>Radius of corners. For items with square edges (business cards), the radius should be 0.</p></td>
189 <td><p>x_waste</p></td> <td><p>Amount of horizontal waste (over-print) to allow. This is useful
190 for minimizing alignment problems when using non-white
191 backgrounds (e.g. images).</p></td>
194 <td><p>y_waste</p></td> <td><p>Amount of vertical waste (over-print) to allow. This is useful
195 for minimizing alignment problems when using non-white
196 backgrounds (e.g. images).</p></td>
200 <!-- ==== Figure ==== -->
202 <desc>Label-rectangle parameters</desc>
203 <media type="image" src="figures/glabels-template-rect-label.png" mime="image/png" style="right">
204 <p>Label-rectangle parameters</p>
207 <!-- ==== End of Figure ==== -->
210 <section id="template-label-rectangle-node">
211 <title>Label-ellipse Node</title>
213 <p>A <em>Label-ellipse</em> node describes the
214 dimensions of a single label or business card that is elliptic
217 <table frame="all" rules="rows">
219 <td><p>Property</p></td> <td><p>Description</p></td>
222 <td><p></p></td> <td><p></p></td>
225 <td><p>id</p></td> <td><p>Reserved for future use. Should always be 0.</p></td>
228 <td><p>width</p></td> <td><p>Width of the ellipse</p></td>
231 <td><p>height</p></td> <td><p>Heigth of the ellipse</p></td>
234 <td><p>waste</p></td> <td><p>Amount of waste (over-print) to allow. This is useful
235 for minimizing alignment problems when using non-white
236 backgrounds (e.g. images).</p></td>
240 <!-- ==== Figure ==== -->
242 <desc>Label-ellipse parameters</desc>
243 <media type="image" src="figures/glabels-template-ellipse-label.png" mime="image/png" style="right">
246 <!-- ==== End of Figure ==== -->
249 <section id="template-label-round-node">
250 <title>Label-round Node</title>
252 <p>A <em>Label-round</em> node describes the dimensions
253 of a simple round label (not a CD).</p>
255 <table frame="all" rules="rows">
257 <td><p>Property</p></td> <td><p>Description</p></td>
260 <td><p></p></td> <td><p></p></td>
263 <td><p>id</p></td> <td><p>Reserved for future use. Should always be 0.</p></td>
266 <td><p>radius</p></td> <td><p>Radius (1/2 diameter) of label</p></td>
269 <td><p>waste</p></td> <td><p>Amount of waste (over-print) to allow. This is useful
270 for minimizing alignment problems when using non-white
271 backgrounds (e.g. images).</p></td>
275 <!-- ==== Figure ==== -->
277 <desc>Label-ellipse parameters</desc>
278 <media type="image" src="figures/glabels-template-circle-label.png" mime="image/png" style="right">
279 <p>Label-ellipse parameters</p>
282 <!-- ==== End of Figure ==== -->
285 <section id="template-label-cd-node">
286 <title>Label-cd Node</title>
288 <p>A <em>Label-round</em> node describes the dimensions
289 of a CD, DVD, or business card CD.</p>
291 <table frame="all" rules="rows">
293 <td><p>Property</p></td> <td><p>Description</p></td>
296 <td><p></p></td> <td><p></p></td>
299 <td><p>id</p></td> <td><p>Reserved for future use. Should always be 0.</p></td>
302 <td><p>radius</p></td> <td><p>Outer radius of label</p></td>
305 <td><p>hole</p></td> <td><p>Radius of concentric hole</p></td>
308 <td><p>width</p></td> <td><p>If present, the label is clipped to the given width.
309 (Useful for "business card CDs").</p></td>
311 <td><p>heigth</p></td> <td><p>If present, the label is clipped to the given height.
312 (Useful for "business card CDs").</p></td>
314 <td><p>waste</p></td> <td><p>Amount of waste (over-print) to allow. This is useful
315 for minimizing alignment problems when using non-white
316 backgrounds (e.g. images).</p></td>
320 <!-- ==== Figure ==== -->
322 <desc>Label-cd parameters</desc>
323 <media type="image" src="figures/glabels-template-cd-label.png" mime="image/png" style="right">
324 <p>CD label parameters</p>
327 <!-- ==== End of Figure ==== -->
330 <section id="template-markup">
331 <title>Markup Nodes</title>
333 <p>Templates may contain optional markup nodes. These nodes are used to describe
334 a simple set of markup lines that are visible in the <app>glabels</app> drawing canvas, but
335 not visible when printed. These lines can represent margins, fold lines, center lines,
336 special areas, or other helpful hints to the user of a template.</p>
338 <section id="template-markup-margin-node">
339 <title>Markup-margin Node</title>
341 <p>A <em>Markup-margin</em> describes a margin along
342 all edges of a label.</p>
344 <table frame="all" rules="rows">
346 <td><p>Property</p></td> <td><p>Description</p></td>
349 <td><p></p></td> <td><p></p></td>
352 <td><p>size</p></td> <td><p>Size of the margin. I.e. the distance of the margin
353 line from the edge of the card/label.</p></td>
358 <section id="template-markup-line-node">
359 <title>Markup-line Node</title>
361 <p>A <em>Markup-line</em> describes a markup line.</p>
363 <table frame="all" rules="rows">
365 <td><p>Property</p></td> <td><p>Description</p></td>
368 <td><p></p></td> <td><p></p></td>
371 <td><p>x1</p></td> <td><p>x coordinate of 1st endpoint of the line segment.</p></td>
374 <td><p>y1</p></td> <td><p>y coordinate of 1st endpoint of the line segment.</p></td>
377 <td><p>x2</p></td> <td><p>x coordinate of 2st endpoint of the line segment.</p></td>
380 <td><p>y2</p></td> <td><p>y coordinate of 2st endpoint of the line segment.</p></td>
385 <section id="template-markup-circle-node">
386 <title>Markup-circle Node</title>
388 <p>A <em>Markup-circle</em> describes a markup circle.</p>
390 <table frame="all" rules="rows">
392 <td><p>Property</p></td> <td><p>Description</p></td>
395 <td><p></p></td> <td><p></p></td>
398 <td><p>x0</p></td> <td><p>x coordinate of circle origin (center).</p></td>
401 <td><p>y0</p></td> <td><p>y coordinate of circle origin (center).</p></td>
404 <td><p>radius</p></td> <td><p>Radius of circle.</p></td>
409 <section id="template-markup-rect-node">
410 <title>Markup-rect Node</title>
412 <p>A <em>Markup-rect</em> describes a markup rectangle.</p>
414 <table frame="all" rules="rows">
416 <td><p>Property</p></td> <td><p>Description</p></td>
419 <td><p></p></td> <td><p></p></td>
422 <td><p>x1</p></td> <td><p>x coordinate of upper left corner of rectangle.</p></td>
425 <td><p>y1</p></td> <td><p>y coordinate of upper left corner of rectangle.</p></td>
428 <td><p>w</p></td> <td><p>Width of rectangle.</p></td>
431 <td><p>h</p></td> <td><p>Height of rectangle.</p></td>
434 <td><p>r</p></td> <td><p>Radius of rounded corners of rectangle.</p></td>
439 <section id="template-markup-ellipse-node">
440 <title>Markup-ellipse Node</title>
442 <p>A <em>Markup-ellipse</em> describes a markup ellipse.</p>
444 <table frame="all" rules="rows">
446 <td><p>Property</p></td> <td><p>Description</p></td>
449 <td><p></p></td> <td><p></p></td>
452 <td><p>x1</p></td> <td><p>x coordinate of upper left corner of ellipse.</p></td>
455 <td><p>y1</p></td> <td><p>y coordinate of upper left corner of ellipse.</p></td>
458 <td><p>w</p></td> <td><p>Width of ellipse.</p></td>
461 <td><p>h</p></td> <td><p>Height of ellipse.</p></td>
468 <section id="template-layout-node">
469 <title>Layout Node</title>
471 <p>A label node may contain multiple <em>Layout</em>
472 children. If labels are arranged in a simple grid pattern, only
473 one layout is needed. However, if labels are arranged in multiple
474 grids, such as a running bond pattern, multiple
475 <em>layout</em> tags can be used. Note: a single label
476 can always be treated as a grid of one.</p>
478 <table frame="all" rules="rows">
480 <td><p>Property</p></td> <td><p>Description</p></td>
483 <td><p></p></td> <td><p></p></td>
486 <td><p>nx</p></td> <td><p>Number of labels/cards across in the grid (horizontal)</p></td>
489 <td><p>ny</p></td> <td><p>Number of labels/cards across in the grid (vertical)</p></td>
492 <td><p>x0</p></td> <td><p>Distance from left edge of sheet to the left edge of
493 the left column of cards/labels in the layout.</p></td>
496 <td><p>y0</p></td> <td><p>Distance from the top edge of sheet to the top edge of
497 the top row of labels/cards in the layout.</p></td>
500 <td><p>dx</p></td> <td><p>Horizontal pitch of grid.</p></td>
503 <td><p>dy</p></td> <td><p>Vertical pitch of grid.</p></td>
507 <!-- ==== Figure ==== -->
509 <desc>Layout parameters</desc>
510 <media type="image" src="figures/glabels-template-layout.png" mime="image/png" style="right">
511 <p>Layout Parameters</p>
514 <!-- ==== End of Figure ==== -->
517 <section id="template-alias-node">
518 <title>Alias Node</title>
520 <p>An <em>Alias</em> node provides the name of a
521 product with the same size and layout characteristics as the
524 <table frame="all" rules="rows">
526 <td><p>Property</p></td> <td><p>Description</p></td>
529 <td><p></p></td> <td><p></p></td>
532 <td><p>brand</p></td> <td><p>The brand or manufacturer of the equivalent product.</p></td>
535 <td><p>part</p></td> <td><p>The part number of the equivalent product.</p></td>