1 <?xml version="1.0" encoding="utf-8"?>
2 <page xmlns="http://projectmallard.org/1.0/" xmlns:e="http://projectmallard.org/experimental/" xmlns:its="http://www.w3.org/2005/11/its" type="guide" id="mancreate" xml:lang="nl">
5 <link type="guide" xref="index#advanced"/>
6 <revision pkgversion="3.0" version="0.1" date="2010-05-04" status="incomplete"/>
7 <revision pkgversion="3.0.1" version="0.1" date="2011-06-20" status="incomplete"/>
9 Create your templates manually.
11 <credit type="author">
12 <name>Jim Evins</name>
13 <email>evins@snaught.com</email>
15 <credit type="author">
16 <name>Mario Blättermann</name>
17 <email>mario.blaettermann@gmail.com</email>
20 <p>Creative Commons Share Alike 3.0</p>
24 <title>Manually creating new templates</title>
28 <!-- ****************** -->
29 <!-- BEGIN Introduction -->
30 <!-- ****************** -->
31 <p>This page is a reference guide to manually creating <app>gLabels</app> templates.
32 <app>gLabels</app> templates are defined in simple XML files as described in the DTD:
33 <link href="http://glabels.org/xmlns/2.3/glabels-2.3.dtd.txt">glabels-2.3.dtd</link>
34 (this DTD also describes other XML files used by <app>gLabels</app>).</p>
36 <p>Manually created template files should be placed in the <file>${HOME}/.glabels</file>
37 and be named with a <file>.template</file> extension.</p>
39 <note style="advanced">
40 <p><app>gLabels</app> searches for templates in several other locations as defined here:</p>
41 <table frame="all" rules="rows">
43 <td><p>Location</p></td>
44 <td><p>Description</p></td>
51 <td its:translate="no"><p><file>${prefix}/share/libglabels-3.0/templates</file></p></td>
52 <td><p>Predefined templates distributed with <app>gLabels</app>.</p>
53 <p><file>${prefix}</file> is usually <file>/usr</file> or <file>/usr/local</file>,
54 depending on where <app>gLabels</app> was installed.</p></td>
57 <td its:translate="no"><p><file>${XDG_CONFIG_HOME}/libglabels/templates</file></p></td>
58 <td><p>User defined templates created with the <app>gLabels</app> <gui>Template Designer</gui>.
59 <em>Do not put manually created templates in this directory.</em></p>
60 <p>If <file>${XDG_CONFIG_HOME}</file> is not defined, it defaults to <file>${HOME}/.config</file>.</p></td>
63 <td its:translate="no"><p><file>${HOME}/.glabels</file></p></td>
64 <td><p>User defined templates that have been created manually should be placed in this
66 Older versions of the <app>gLabels</app> <gui>Template Designer</gui> (prior to 3.0)
67 would also put templates in this directory.</p></td>
72 <note><p>Completed template files can be sent to the
73 <app>gLabels</app> template
74 <link href="mailto:glabels-templates@lists.sourceforge.net">mailing list</link>
75 for possible inclusion in future versions of <app>gLabels</app>.</p>
77 <!-- ****************** -->
78 <!-- END Introduction -->
79 <!-- ****************** -->
82 <!-- ***************** -->
83 <!-- BEGIN Assumptions -->
84 <!-- ***************** -->
85 <section id="template-assumptions">
86 <title>Assumptions/caveats</title>
89 <p>A sheet contains only one size of label or card (if a sheet
90 contains more than one size of item, it can be split into
91 multiple templates for multiple pass printing)</p>
94 <p>Distances can be expressed in units of <code>pt</code>, <code>in</code>,
95 <code>mm</code>, <code>cm</code>, or <code>pc</code>. For example:
96 "<code>1.0in</code>" or "<code>2.54cm</code>". If no
97 units are specified, computer points (<code>pt</code>) will
98 be assumed (1 <em>pt</em> =
99 1/72 <em>in</em> = 0.352778 <em>mm</em>).
104 <!-- ***************** -->
105 <!-- END Assumptions -->
106 <!-- ***************** -->
110 <!-- ******************** -->
111 <!-- BEGIN Template Files -->
112 <!-- ******************** -->
113 <section id="template-file">
114 <title>Template Files</title>
116 <p>A template file contains a single <code>Glabels-templates</code> top-level
119 <code mime="text/xml">
120 <?xml version="1.0"?>
121 <Glabels-templates>
123 <var>...templates...</var>
125 </Glabels-templates></code>
128 <title>Example Template</title>
129 <desc>Example <app>gLabels</app> template file containing a single
130 <code>Template</code> node.</desc>
131 <code mime="text/xml" its:translate="no">
132 <?xml version="1.0"?>
133 <Glabels-templates>
135 <Template brand="Avery" part="8160" size="US-Letter" description="Mailing Labels">
136 <Meta category="label"/>
137 <Meta category="mail"/>
138 <Meta product_url="http://www.avery.com/avery/en_us/"/>
139 <Label-rectangle id="0" width="189pt" height="72pt" round="5pt">
140 <Markup-margin size="5pt"/>
141 <Layout nx="3" ny="10" x0="11.25pt" y0="36pt" dx="200pt" dy="72pt"/>
142 </Label-rectangle>
145 </Glabels-templates></code>
149 <!-- ******************** -->
150 <!-- END Template Files -->
151 <!-- ******************** -->
155 <!-- ******************** -->
156 <!-- BEGIN Template Node -->
157 <!-- ******************** -->
158 <section id="template-template-node">
159 <title><code>Template</code> Node</title>
161 <p>A <code>Template</code> node describes a single
162 stationery product. It must contain one instance of any type of Label node
163 (<code>Label-rectangle</code>,
164 <code>Label-round</code>, or
165 <code>Label-cd</code>).</p>
167 <table frame="all" rules="rows">
169 <td><p>Property</p></td> <td><p>Description</p></td>
172 <td><p/></td> <td><p/></td>
175 <td its:translate="no"><p><code>brand</code></p></td>
176 <td><p>Brand or manufacturer of stationery product. E.g. "Avery"</p></td>
179 <td its:translate="no"><p><code>part</code></p></td>
180 <td><p>Part number or name of stationery product. E.g. "8160"</p></td>
183 <td its:translate="no"><p><code>size</code></p></td>
184 <td><p>Size of sheet.
185 E.g., "<code>US-Letter</code>", "<code>A4</code>", ...
189 <td its:translate="no"><p><code>description</code></p></td>
190 <td><p>Description of stationery product. E.g, "Mailing Labels."</p></td>
193 <td its:translate="no"><p><code>_description</code></p></td>
194 <td><p>Translatable description of stationery product. E.g, "Mailing Labels."
195 (Only useful for predefined templates)</p></td>
198 <td its:translate="no"><p><code>width</code></p></td>
199 <td><p>Page width. Only valid if size="Other"</p></td>
202 <td its:translate="no"><p><code>height</code></p></td>
203 <td><p>Page height. Only valid if size="Other"</p></td>
206 <td its:translate="no"><p><code>equiv</code></p></td>
207 <td><p>Equivalent part number. If this property is present, the template
208 is a clone of another template of the same brand. The template will
209 inherit all properties, except brand and name from the other template.
210 This equiv property must refer to a previously defined template -
211 <app>gLabels</app> does not currently support forward references.</p></td>
216 <!-- ******************** -->
217 <!-- END Template Node -->
218 <!-- ******************** -->
221 <!-- ******************** -->
222 <!-- BEGIN Meta Node -->
223 <!-- ******************** -->
224 <section id="meta-template-node">
225 <title><code>Meta</code> Node</title>
227 <p>A <code>Meta</code> node contains some additional
228 information about the template. A <code>Template</code>
229 node may contain zero or more <code>Meta</code> nodes.</p>
231 <table frame="all" rules="rows">
233 <td><p>Subnode</p></td> <td><p>Description</p></td>
236 <td><p/></td> <td><p/></td>
239 <td its:translate="no"><p><code>category</code></p></td>
240 <td><p>A category for the template.
241 A template can belong to multiple categories by simply adding multiple
242 <code>Meta</code> nodes to the parent
243 <code>Template</code> node.
244 Template categories are used by the <app>gLabels</app> <gui>New Label
245 Dialog</gui> to filter the results of template searches.</p>
247 <p>The value of this category must match a predefined category ID defined in
248 the file <file>${prefix}/libglabels-3.0/templates/categories.xml</file>.
249 Currently defined category IDs include:</p>
251 <item its:translate="no"><p><code>label</code></p></item>
252 <item its:translate="no"><p><code>round-label</code></p></item>
253 <item its:translate="no"><p><code>elliptical-label</code></p></item>
254 <item its:translate="no"><p><code>square-label</code></p></item>
255 <item its:translate="no"><p><code>rectangle-label</code></p></item>
256 <item its:translate="no"><p><code>card</code></p></item>
257 <item its:translate="no"><p><code>business-card</code></p></item>
258 <item its:translate="no"><p><code>media</code></p></item>
259 <item its:translate="no"><p><code>mail</code></p></item>
260 <item its:translate="no"><p><code>foldable</code></p></item>
261 <item its:translate="no"><p><code>photo</code></p></item>
268 <td its:translate="no"><p><code>product_url</code></p></td>
269 <td><p>A URL pointing to the vendor's webpage for the specific product, if available.</p></td>
273 <note><p>Suggestions for additional categories can be sent to the
274 <app>gLabels</app> developer's
275 <link href="mailto:glabels-devel@lists.sourceforge.net">mailing list</link>.</p>
276 <p>Product URLs may be of limited use, because they may not be permanent.</p>
280 <!-- ******************** -->
281 <!-- END Meta Node -->
282 <!-- ******************** -->
285 <!-- ************************** -->
286 <!-- BEGIN Label-rectangle Node -->
287 <!-- ************************** -->
288 <section id="template-label-rectangle-node">
289 <title><code>Label-rectangle</code> Node</title>
291 <p>A <code>Label-rectangle</code> node describes the
292 dimensions of a single label or business card that is rectangular
293 in shape (may have rounded edges).</p>
295 <table frame="all" rules="rows">
297 <td><p>Property</p></td> <td><p>Description</p></td>
300 <td><p/></td> <td><p/></td>
303 <td its:translate="no"><p><code>id</code></p></td>
304 <td><p>Reserved for future use. Should always be 0.</p></td>
307 <td its:translate="no"><p><code>width</code></p></td>
308 <td><p>Width of label/card</p></td>
311 <td its:translate="no"><p><code>height</code></p></td>
312 <td><p>Height of label/card</p></td>
315 <td its:translate="no"><p><code>round</code></p></td>
316 <td><p>Radius of corners. For items with square edges (business cards),
317 the radius should be 0.</p></td>
320 <td its:translate="no"><p><code>x_waste</code></p></td>
321 <td><p>Amount of horizontal waste (over-print) to allow. This is useful
322 for minimizing alignment problems when using non-white
323 backgrounds (e.g. images).</p></td>
326 <td its:translate="no"><p><code>y_waste</code></p></td>
327 <td><p>Amount of vertical waste (over-print) to allow. This is useful
328 for minimizing alignment problems when using non-white
329 backgrounds (e.g. images).</p></td>
333 <!-- ==== Figure ==== -->
335 <desc><code>Label-rectangle</code> parameters</desc>
336 <media its:translate="no" type="image" src="figures/glabels-template-rect-label.png" mime="image/png" style="right">
337 <p><code>Label-rectangle</code> parameters</p>
340 <!-- ==== End of Figure ==== -->
343 <!-- ************************** -->
344 <!-- END Label-rectangle Node -->
345 <!-- ************************** -->
348 <!-- ************************ -->
349 <!-- BEGIN Label-ellipse Node -->
350 <!-- ************************ -->
351 <section id="template-label-ellipse-node">
352 <title><code>Label-ellipse</code> Node</title>
354 <p>A <code>Label-ellipse</code> node describes the
355 dimensions of a single label or business card that is elliptic
358 <table frame="all" rules="rows">
360 <td><p>Property</p></td> <td><p>Description</p></td>
363 <td><p/></td> <td><p/></td>
366 <td its:translate="no"><p><code>id</code></p></td>
367 <td><p>Reserved for future use. Should always be 0.</p></td>
370 <td its:translate="no"><p><code>width</code></p></td>
371 <td><p>Width of the ellipse</p></td>
374 <td its:translate="no"><p><code>height</code></p></td>
375 <td><p>Height of the ellipse</p></td>
378 <td its:translate="no"><p><code>waste</code></p></td>
379 <td><p>Amount of waste (over-print) to allow. This is useful
380 for minimizing alignment problems when using non-white
381 backgrounds (e.g. images).</p></td>
385 <!-- ==== Figure ==== -->
387 <desc><span>Label-ellipse</span> parameters</desc>
388 <media type="image" src="figures/glabels-template-ellipse-label.png" mime="image/png" style="right">
389 <p><code>Label-ellipse</code> parameters</p>
392 <!-- ==== End of Figure ==== -->
395 <!-- ************************ -->
396 <!-- END Label-ellipse Node -->
397 <!-- ************************ -->
400 <!-- ********************** -->
401 <!-- BEGIN Label-round Node -->
402 <!-- ********************** -->
403 <section id="template-label-round-node">
404 <title><code>Label-round</code> Node</title>
406 <p>A <code>Label-round</code> node describes the dimensions
407 of a simple round label (not a CD).</p>
409 <table frame="all" rules="rows">
411 <td><p>Property</p></td> <td><p>Description</p></td>
414 <td><p/></td> <td><p/></td>
417 <td its:translate="no"><p><code>id</code></p></td>
418 <td><p>Reserved for future use. Should always be 0.</p></td>
421 <td its:translate="no"><p><code>radius</code></p></td>
422 <td><p>Radius (1/2 diameter) of label</p></td>
425 <td its:translate="no"><p><code>waste</code></p></td>
426 <td><p>Amount of waste (over-print) to allow. This is useful
427 for minimizing alignment problems when using non-white
428 backgrounds (e.g. images).</p></td>
432 <!-- ==== Figure ==== -->
434 <desc><code>Label-ellipse</code> parameters</desc>
435 <media its:translate="no" type="image" src="figures/glabels-template-circle-label.png" mime="image/png" style="right">
436 <p><code>Label-ellipse</code> parameters</p>
439 <!-- ==== End of Figure ==== -->
442 <!-- ********************** -->
443 <!-- END Label-round Node -->
444 <!-- ********************** -->
447 <!-- ******************* -->
448 <!-- BEGIN Label-cd Node -->
449 <!-- ******************* -->
450 <section id="template-label-cd-node">
451 <title><code>Label-cd</code> Node</title>
453 <p>A <code>Label-cd</code> node describes the dimensions
454 of a CD, DVD, or business card CD.</p>
456 <table frame="all" rules="rows">
458 <td><p>Property</p></td> <td><p>Description</p></td>
461 <td><p/></td> <td><p/></td>
464 <td its:translate="no"><p><code>id</code></p></td>
465 <td><p>Reserved for future use. Should always be 0.</p></td>
468 <td its:translate="no"><p><code>radius</code></p></td>
469 <td><p>Outer radius of label</p></td>
472 <td its:translate="no"><p><code>hole</code></p></td>
473 <td><p>Radius of concentric hole</p></td>
476 <td its:translate="no"><p><code>width</code></p></td>
477 <td><p>If present, the label is clipped to the given width.
478 (Useful for "business card CDs").</p></td>
481 <td its:translate="no"><p><code>height</code></p></td>
482 <td><p>If present, the label is clipped to the given height.
483 (Useful for "business card CDs").</p></td>
486 <td its:translate="no"><p><code>waste</code></p></td>
487 <td><p>Amount of waste (over-print) to allow. This is useful
488 for minimizing alignment problems when using non-white
489 backgrounds (e.g. images).</p></td>
493 <!-- ==== Figure ==== -->
495 <desc><code>Label-cd</code> parameters</desc>
496 <media its:translate="no" type="image" src="figures/glabels-template-cd-label.png" mime="image/png" style="right">
497 <p>CD label parameters</p>
500 <!-- ==== End of Figure ==== -->
503 <!-- ******************* -->
504 <!-- END Label-cd Node -->
505 <!-- ******************* -->
508 <!-- ***************** -->
509 <!-- BEGIN Markup Node -->
510 <!-- ***************** -->
511 <section id="template-markup">
512 <title><code>Markup</code> Nodes</title>
514 <p>Templates may contain optional markup nodes. These nodes are used to describe
515 a simple set of markup lines that are visible in the <app>glabels</app> drawing canvas, but
516 not visible when printed. These lines can represent margins, fold lines, center lines,
517 special areas, or other helpful hints to the user of a template.</p>
520 <!-- ======================== -->
521 <!-- BEGIN Markup-margin Node -->
522 <!-- ======================== -->
523 <section id="template-markup-margin-node">
524 <title><code>Markup-margin</code> Node</title>
526 <p>A <code>Markup-margin</code> describes a margin along
527 all edges of a label.</p>
529 <table frame="all" rules="rows">
531 <td><p>Property</p></td> <td><p>Description</p></td>
534 <td><p/></td> <td><p/></td>
537 <td its:translate="no"><p><code>size</code></p></td>
538 <td><p>Size of the margin. I.e. the distance of the margin
539 line from the edge of the card/label.</p></td>
543 <!-- ======================== -->
544 <!-- END Markup-margin Node -->
545 <!-- ======================== -->
548 <!-- ====================== -->
549 <!-- BEGIN Markup-line Node -->
550 <!-- ====================== -->
551 <section id="template-markup-line-node">
552 <title><code>Markup-line</code> Node</title>
554 <p>A <code>Markup-line</code> node describes a markup line.</p>
556 <table frame="all" rules="rows">
558 <td><p>Property</p></td> <td><p>Description</p></td>
561 <td><p/></td> <td><p/></td>
564 <td its:translate="no"><p><code>x1</code></p></td>
565 <td><p>x coordinate of 1st endpoint of the line segment.</p></td>
568 <td its:translate="no"><p><code>y1</code></p></td>
569 <td><p>y coordinate of 1st endpoint of the line segment.</p></td>
572 <td its:translate="no"><p><code>x2</code></p></td>
573 <td><p>x coordinate of 2nd endpoint of the line segment.</p></td>
576 <td its:translate="no"><p><code>y2</code></p></td>
577 <td><p>y coordinate of 2nd endpoint of the line segment.</p></td>
581 <!-- ====================== -->
582 <!-- END Markup-line Node -->
583 <!-- ====================== -->
586 <!-- ======================== -->
587 <!-- BEGIN Markup-circle Node -->
588 <!-- ======================== -->
589 <section id="template-markup-circle-node">
590 <title><code>Markup-circle</code> Node</title>
592 <p>A <code>Markup-circle</code> describes a markup circle.</p>
594 <table frame="all" rules="rows">
596 <td><p>Property</p></td> <td><p>Description</p></td>
599 <td><p/></td> <td><p/></td>
602 <td its:translate="no"><p><code>x0</code></p></td>
603 <td><p>x coordinate of circle origin (center).</p></td>
606 <td its:translate="no"><p><code>y0</code></p></td>
607 <td><p>y coordinate of circle origin (center).</p></td>
610 <td its:translate="no"><p><code>radius</code></p></td>
611 <td><p>Radius of circle.</p></td>
615 <!-- ======================== -->
616 <!-- END Markup-circle Node -->
617 <!-- ======================== -->
620 <!-- ====================== -->
621 <!-- BEGIN Markup-rect Node -->
622 <!-- ====================== -->
623 <section id="template-markup-rect-node">
624 <title><code>Markup-rect</code> Node</title>
626 <p>A <code>Markup-rect</code> describes a markup rectangle.</p>
628 <table frame="all" rules="rows">
630 <td><p>Property</p></td> <td><p>Description</p></td>
633 <td><p/></td> <td><p/></td>
636 <td its:translate="no"><p><code>x1</code></p></td>
637 <td><p>x coordinate of upper left corner of rectangle.</p></td>
640 <td its:translate="no"><p><code>y1</code></p></td>
641 <td><p>y coordinate of upper left corner of rectangle.</p></td>
644 <td its:translate="no"><p><code>w</code></p></td>
645 <td><p>Width of rectangle.</p></td>
648 <td its:translate="no"><p><code>h</code></p></td>
649 <td><p>Height of rectangle.</p></td>
652 <td its:translate="no"><p><code>r</code></p></td>
653 <td><p>Radius of rounded corners of rectangle.</p></td>
657 <!-- ====================== -->
658 <!-- END Markup-rect Node -->
659 <!-- ====================== -->
662 <!-- ========================= -->
663 <!-- BEGIN Markup-ellipse Node -->
664 <!-- ========================= -->
665 <section id="template-markup-ellipse-node">
666 <title><code>Markup-ellipse</code> Node</title>
668 <p>A <code>Markup-ellipse</code> describes a markup ellipse.</p>
670 <table frame="all" rules="rows">
672 <td><p>Property</p></td> <td><p>Description</p></td>
675 <td><p/></td> <td><p/></td>
678 <td its:translate="no"><p><code>x1</code></p></td>
679 <td><p>x coordinate of upper left corner of ellipse.</p></td>
682 <td its:translate="no"><p><code>y1</code></p></td>
683 <td><p>y coordinate of upper left corner of ellipse.</p></td>
686 <td its:translate="no"><p><code>w</code></p></td>
687 <td><p>Width of ellipse.</p></td>
690 <td its:translate="no"><p><code>h</code></p></td>
691 <td><p>Height of ellipse.</p></td>
695 <!-- ========================= -->
696 <!-- END Markup-ellipse Node -->
697 <!-- ========================= -->
700 <!-- ***************** -->
701 <!-- END Markup Node -->
702 <!-- ***************** -->
705 <!-- ***************** -->
706 <!-- BEGIN Layout Node -->
707 <!-- ***************** -->
708 <section id="template-layout-node">
709 <title><code>Layout</code> Node</title>
711 <p>A label node may contain multiple <code>Layout</code>
712 children. If labels are arranged in a simple grid pattern, only
713 one layout is needed. However, if labels are arranged in multiple
714 grids, such as a running bond pattern, multiple
715 <code>Layout</code> tags can be used.</p>
716 <p>A common example for multiple layouts is a sheet with three
719 <!-- ==== Figure ==== -->
721 <desc>CD label sheet</desc>
722 <media its:translate="no" type="image" src="figures/layouts-cdlabel.png" mime="image/png" style="right">
723 <p>CD label sheet</p>
726 <!-- ==== End of Figure ==== -->
728 <p>The two labels on the left edge can be assigned to a grid, assuming we
729 can define the coordinates for the top left label and the distance to
730 the second label properly. The distance to the left edge is common to
731 these labels. The third one on the right edge has no common distance
732 values with the other ones, that's why we have to define a second layout,
733 with unique coordinates for the top left corner of that label.</p>
736 <p>You can define multiple layouts only if the labels on the sheet
737 have the same shape. If your sheet contains different shapes, you have
738 to define each shape in another template separately. Future versions
739 of <app>gLabels</app> will probably be able to concatenate such sheets
740 with different shapes within a single template.</p>
744 <p>A single label can always be treated as a grid of one.</p>
747 <table frame="all" rules="rows">
749 <td><p>Property</p></td> <td><p>Description</p></td>
752 <td><p/></td> <td><p/></td>
755 <td its:translate="no"><p><code>nx</code></p></td>
756 <td><p>Number of labels/cards across in the grid (horizontal)</p></td>
759 <td its:translate="no"><p><code>ny</code></p></td>
760 <td><p>Number of labels/cards across in the grid (vertical)</p></td>
763 <td its:translate="no"><p><code>x0</code></p></td>
764 <td><p>Distance from left edge of sheet to the left edge of
765 the left column of cards/labels in the layout.</p></td>
768 <td its:translate="no"><p><code>y0</code></p></td>
769 <td><p>Distance from the top edge of sheet to the top edge of
770 the top row of labels/cards in the layout.</p></td>
773 <td its:translate="no"><p><code>dx</code></p></td>
774 <td><p>Horizontal pitch of grid.</p></td>
777 <td its:translate="no"><p><code>dy</code></p></td>
778 <td><p>Vertical pitch of grid.</p></td>
782 <!-- ==== Figure ==== -->
784 <desc><code>Layout</code> parameters</desc>
785 <media its:translate="no" type="image" src="figures/glabels-template-layout.png" mime="image/png" style="right">
786 <p><span>Layout</span> Parameters</p>
789 <!-- ==== End of Figure ==== -->
792 <!-- ***************** -->
793 <!-- END Layout Node -->
794 <!-- ***************** -->