git.sur5r.net Git - glabels/blob - help/C/mancreate.page

   1 <page xmlns="http://projectmallard.org/1.0/"
   2       xmlns:e="http://projectmallard.org/experimental/"
   3       type="guide"
   4       id="mancreate">
   5
   6   <info>
   7     <link type="guide" xref="index#advanced"/>
   8     <revision pkgversion="3.0" version="0.1" date="2010-05-04" status="incomplete"/>
   9     <desc>
  10       Create your templates manually.
  11     </desc>
  12     <credit type="author">
  13       <name>Jim Evins</name>
  14       <email>evins@snaught.com</email>
  15     </credit>
  16     <credit type="author">
  17       <name>Mario Blättermann</name>
  18       <email>mariobl@gnome.org</email>
  19     </credit>
  20     <license>
  21       <p>Creative Commons Share Alike 3.0</p>
  22     </license>
  23   </info>
  24
  25     <title>Manually creating new templates</title>
  26
  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.
  35       </p>
  36
  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>
  40
  41     <section id="template-assumptions">
  42       <title>Assumptions/caveats</title>
  43       <list>
  44         <item>
  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>
  48         </item>
  49         <item>
  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             "<code>1.0in</code>" or "<code>2.54cm</code>".  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>).
  57             </p>
  58         </item>
  59       </list>
  60     </section>
  61
  62     <section id="template-file">
  63       <title>Template Files</title>
  64
  65       <code>
  66 &lt;?xml version="1.0"?&gt;
  67 &lt;Glabels-templates&gt;
  68
  69    <var>...templates...</var>
  70
  71 &lt;/Glabels-templates&gt;
  72       </code>
  73     </section>
  74
  75
  76     <section id="template-example">
  77       <title>Example Template</title>
  78       <code>
  79   &lt;Template brand="Avery" part="8160" size="US-Letter" description="Mailing Labels"&gt;
  80     &lt;Meta category="label"/&gt;
  81     &lt;Meta category="mail"/&gt;
  82     &lt;Meta product_url="http://www.avery.com/avery/en_us/"/&gt;
  83     &lt;Label-rectangle id="0" width="189pt" height="72pt" round="5pt"&gt;
  84       &lt;Markup-margin size="5pt"/&gt;
  85       &lt;Layout nx="3" ny="10" x0="11.25pt" y0="36pt" dx="200pt" dy="72pt"/&gt;
  86     &lt;/Label-rectangle&gt;
  87   &lt;/Template&gt;
  88       </code>
  89     </section>
  90
  91     <section id="template-template-node">
  92       <title><span translate="no">Template</span> Node</title>
  93
  94       <p>A <em><span translate="no">Template</span></em> node describes a single
  95         stationery product.  It must contain one instance of any type of Label node
  96         (<em><span translate="no">Label-rectangle</span></em>,
  97         <em><span translate="no">Label-round</span></em>, or
  98         <em><span translate="no">Label-cd</span></em>).</p>
  99
 100 <table frame="all" rules="rows">
 101   <tr>
 102     <td><p>Property</p></td>  <td><p>Description</p></td>
 103   </tr>
 104   <tr>
 105     <td><p></p></td>  <td><p></p></td>
 106   </tr>
 107   <tr>
 108     <td><p><span translate="no">brand</span></p></td>
 109     <td><p>Brand or manufacturer of stationery product. E.g. "Avery"</p></td>
 110   </tr>
 111   <tr>
 112     <td><p><span translate="no">part</span></p></td>
 113     <td><p>Part number or name of stationery product. E.g. "8160"</p></td>
 114   </tr>
 115   <tr>
 116     <td><p><span translate="no">size</span></p></td>
 117     <td><p>Size of sheet.  E.g., "US-Letter," "A4", ...</p></td>
 118   </tr>
 119   <tr>
 120     <td><p><span translate="no">description</span></p></td>
 121     <td><p>Description of stationery product.  E.g, "Mailing Labels."</p></td>
 122   </tr>
 123   <tr>
 124     <td><p><span translate="no">_description</span></p></td>
 125     <td><p>Translatable description of stationery product. E.g, "Mailing Labels."
 126            (Only useful for predefined templates)</p></td>
 127   </tr>
 128   <tr>
 129     <td><p><span translate="no">width</span></p></td>
 130     <td><p>Page width.  Only valid if size="Other"</p></td>
 131   </tr>
 132   <tr>
 133     <td><p><span translate="no">height</span></p></td>
 134     <td><p>Page height.  Only valid if size="Other"</p></td>
 135   </tr>
 136   <tr>
 137     <td><p><span translate="no">equiv</span></p></td>
 138     <td><p>Equivalent part number.  If this property is present, the template
 139            is a clone of another template of the same brand.  The template will
 140            inherit all properties, except brand and name from the other template.
 141            This equiv property must refer to a previously defined template --
 142            libglabels does not currently support forward references.</p></td>
 143   </tr>
 144 </table>
 145
 146 </section>
 147
 148     <section id="template-template-node">
 149       <title><span translate="no">Meta</span> Node</title>
 150
 151       <p>A <em><span translate="no">Meta</span></em> node contains some additional
 152            properties of that product.  This node may appear more than once, with a
 153            subnode each.</p>
 154
 155 <table frame="all" rules="rows">
 156   <tr>
 157     <td><p>Subnode</p></td>  <td><p>Description</p></td>
 158   </tr>
 159   <tr>
 160     <td><p></p></td>  <td><p></p></td>
 161   </tr>
 162   <tr>
 163     <td><p><span translate="no">category</span></p></td>
 164     <td><p>The category which this product is assigned to. The value
 165         of this category is used by the <app>gLabels'</app> template chooser to filter the
 166         view to display only mailing labels, or labels in common and suppress any other products
 167         which the user don't want to find.</p>
 168         <p>One product can be assigned to several categories.  You may choose from the
 169         following categories:</p>
 170         <list>
 171           <item><p><span translate="no">label</span></p></item>
 172           <item><p><span translate="no">round-label</span></p></item>
 173           <item><p><span translate="no">elliptical-label</span></p></item>
 174           <item><p><span translate="no">square-label</span></p></item>
 175           <item><p><span translate="no">rectangle-label</span></p></item>
 176           <item><p><span translate="no">card</span></p></item>
 177           <item><p><span translate="no">business-card</span></p></item>
 178           <item><p><span translate="no">media</span></p></item>
 179           <item><p><span translate="no">mail</span></p></item>
 180           <item><p><span translate="no">foldable</span></p></item>
 181         </list>
 182         <note><p>If you have any ideas for new categories, please send your suggestions to the
 183         developer's <link href="mailto:glabels-devel@lists.sourceforge.net">mailing list</link>
 184         of <app>gLabels</app>.
 185         </p></note>
 186     </td>
 187   </tr>
 188   <tr>
 189     <td><p><span translate="no">product_url</span></p></td>
 190     <td><p>This address points to the vendor's website. Ideally,
 191         the link shows the URL of that certain product, if available.</p></td>
 192   </tr>
 193 </table>
 194
 195 </section>
 196
 197     <section id="template-label-rectangle-node">
 198       <title><span translate="no">Label-rectangle</span> Node</title>
 199
 200       <p>A <em><span translate="no">Label-rectangle</span></em> node describes the
 201         dimensions of a single label or business card that is rectangular
 202         in shape (may have rounded edges).</p>
 203
 204 <table frame="all" rules="rows">
 205   <tr>
 206     <td><p>Property</p></td>  <td><p>Description</p></td>
 207   </tr>
 208   <tr>
 209     <td><p></p></td>  <td><p></p></td>
 210   </tr>
 211   <tr>
 212     <td><p><span translate="no">id</span></p></td>
 213     <td><p>Reserved for future use.  Should always be 0.</p></td>
 214   </tr>
 215   <tr>
 216     <td><p><span translate="no">width</span></p></td>
 217     <td><p>Width of label/card</p></td>
 218   </tr>
 219   <tr>
 220     <td><p><span translate="no">height</span></p></td>
 221     <td><p>Heigth of label/card</p></td>
 222   </tr>
 223   <tr>
 224     <td><p><span translate="no">round</span></p></td>
 225     <td><p>Radius of corners.  For items with square edges (business cards),
 226            the radius should be 0.</p></td>
 227   </tr>
 228   <tr>
 229     <td><p><span translate="no">x_waste</span></p></td>
 230     <td><p>Amount of horizontal waste (over-print) to allow.  This is useful
 231                   for minimizing alignment problems when using non-white
 232                   backgrounds (e.g. images).</p></td>
 233   </tr>
 234   <tr>
 235     <td><p><span translate="no">y_waste</span></p></td>
 236     <td><p>Amount of vertical waste (over-print) to allow.  This is useful
 237                   for minimizing alignment problems when using non-white
 238                   backgrounds (e.g. images).</p></td>
 239   </tr>
 240 </table>
 241
 242       <!-- ==== Figure ==== -->
 243       <figure>
 244                 <desc><span translate="no">Label-rectangle</span> parameters</desc>
 245                 <media type="image" src="figures/glabels-template-rect-label.png" mime="image/png" style="right">
 246                 <p><span translate="no">Label-rectangle</span> parameters</p>
 247                 </media>
 248       </figure>
 249       <!-- ==== End of Figure ==== -->
 250         </section>
 251
 252     <section id="template-label-rectangle-node">
 253       <title><span translate="no">Label-ellipse</span> Node</title>
 254
 255       <p>A <em><span translate="no">Label-ellipse</span></em> node describes the
 256         dimensions of a single label or business card that is elliptic
 257         in shape.</p>
 258
 259 <table frame="all" rules="rows">
 260   <tr>
 261     <td><p>Property</p></td>  <td><p>Description</p></td>
 262   </tr>
 263   <tr>
 264     <td><p></p></td>  <td><p></p></td>
 265   </tr>
 266   <tr>
 267     <td><p><span translate="no">id</span></p></td>
 268     <td><p>Reserved for future use.  Should always be 0.</p></td>
 269   </tr>
 270   <tr>
 271     <td><p><span translate="no">width</span></p></td>
 272     <td><p>Width of the ellipse</p></td>
 273   </tr>
 274   <tr>
 275     <td><p><span translate="no">height</span></p></td>
 276     <td><p>Heigth of the ellipse</p></td>
 277   </tr>
 278   <tr>
 279     <td><p><span translate="no">waste</span></p></td>
 280     <td><p>Amount of waste (over-print) to allow.  This is useful
 281                   for minimizing alignment problems when using non-white
 282                   backgrounds (e.g. images).</p></td>
 283   </tr>
 284 </table>
 285
 286       <!-- ==== Figure ==== -->
 287       <figure>
 288                 <desc><span translate="no">Label-ellipse</span> parameters</desc>
 289                 <media type="image" src="figures/glabels-template-ellipse-label.png" mime="image/png" style="right">
 290                 <p><span translate="no">Label-ellipse</span> parameters</p>
 291                 </media>
 292       </figure>
 293       <!-- ==== End of Figure ==== -->
 294         </section>
 295
 296     <section id="template-label-round-node">
 297       <title><span translate="no">Label-round</span> Node</title>
 298
 299       <p>A <em><span translate="no">Label-round</span></em> node describes the dimensions
 300         of a simple round label (not a CD).</p>
 301
 302 <table frame="all" rules="rows">
 303   <tr>
 304     <td><p>Property</p></td>  <td><p>Description</p></td>
 305   </tr>
 306   <tr>
 307     <td><p></p></td>  <td><p></p></td>
 308   </tr>
 309   <tr>
 310     <td><p><span translate="no">id</span></p></td>
 311     <td><p>Reserved for future use.  Should always be 0.</p></td>
 312   </tr>
 313   <tr>
 314     <td><p><span translate="no">radius</span></p></td>
 315     <td><p>Radius (1/2 diameter) of label</p></td>
 316   </tr>
 317   <tr>
 318     <td><p><span translate="no">waste</span></p></td>
 319     <td><p>Amount of waste (over-print) to allow.  This is useful
 320                   for minimizing alignment problems when using non-white
 321                   backgrounds (e.g. images).</p></td>
 322   </tr>
 323 </table>
 324
 325       <!-- ==== Figure ==== -->
 326       <figure>
 327                 <desc><span translate="no">Label-ellipse</span> parameters</desc>
 328                 <media type="image" src="figures/glabels-template-circle-label.png" mime="image/png" style="right">
 329                 <p><span translate="no">Label-ellipse</span> parameters</p>
 330                 </media>
 331       </figure>
 332       <!-- ==== End of Figure ==== -->
 333     </section>
 334
 335     <section id="template-label-cd-node">
 336       <title><span translate="no">Label-cd</span> Node</title>
 337
 338       <p>A <em><span translate="no">Label-cd</span></em> node describes the dimensions
 339         of a CD, DVD, or business card CD.</p>
 340
 341 <table frame="all" rules="rows">
 342   <tr>
 343     <td><p>Property</p></td>  <td><p>Description</p></td>
 344   </tr>
 345   <tr>
 346     <td><p></p></td>  <td><p></p></td>
 347   </tr>
 348   <tr>
 349     <td><p><span translate="no">id</span></p></td>
 350     <td><p>Reserved for future use.  Should always be 0.</p></td>
 351   </tr>
 352   <tr>
 353     <td><p><span translate="no">radius</span></p></td>
 354     <td><p>Outer radius of label</p></td>
 355   </tr>
 356   <tr>
 357     <td><p><span translate="no">hole</span></p></td>
 358     <td><p>Radius of concentric hole</p></td>
 359   </tr>
 360   <tr>
 361     <td><p><span translate="no">width</span></p></td>
 362     <td><p>If present, the label is clipped to the given width.
 363                   (Useful for "business card CDs").</p></td>
 364   </tr>
 365   <tr>
 366     <td><p><span translate="no">height</span></p></td>
 367     <td><p>If present, the label is clipped to the given height.
 368                   (Useful for "business card CDs").</p></td>
 369   </tr>
 370   <tr>
 371     <td><p><span translate="no">waste</span></p></td>
 372     <td><p>Amount of waste (over-print) to allow.  This is useful
 373                   for minimizing alignment problems when using non-white
 374                   backgrounds (e.g. images).</p></td>
 375   </tr>
 376 </table>
 377
 378               <!-- ==== Figure ==== -->
 379               <figure>
 380                 <desc><span translate="no">Label-cd</span> parameters</desc>
 381                 <media type="image" src="figures/glabels-template-cd-label.png" mime="image/png" style="right">
 382                 <p>CD label parameters</p>
 383                 </media>
 384               </figure>
 385               <!-- ==== End of Figure ==== -->
 386     </section>
 387
 388     <section id="template-markup">
 389       <title><span translate="no">Markup</span> Nodes</title>
 390
 391       <p>Templates may contain optional markup nodes.  These nodes are used to describe
 392       a simple set of markup lines that are visible in the <app>glabels</app> drawing canvas, but
 393       not visible when printed.  These lines can represent margins, fold lines, center lines,
 394       special areas, or other helpful hints to the user of a template.</p>
 395
 396     <section id="template-markup-margin-node">
 397       <title><span translate="no">Markup-margin</span> Node</title>
 398
 399       <p>A <em><span translate="no">Markup-margin</span></em> describes a margin along
 400         all edges of a label.</p>
 401
 402 <table frame="all" rules="rows">
 403   <tr>
 404     <td><p>Property</p></td>  <td><p>Description</p></td>
 405   </tr>
 406   <tr>
 407     <td><p></p></td>  <td><p></p></td>
 408   </tr>
 409   <tr>
 410     <td><p><span translate="no">size</span></p></td>
 411     <td><p>Size of the margin.  I.e. the distance of the margin
 412                   line from the edge of the card/label.</p></td>
 413   </tr>
 414 </table>
 415     </section>
 416
 417     <section id="template-markup-line-node">
 418       <title><span translate="no">Markup-line</span> Node</title>
 419
 420       <p>A <em><span translate="no">Markup-line</span></em> node describes a markup line.</p>
 421
 422 <table frame="all" rules="rows">
 423   <tr>
 424     <td><p>Property</p></td>  <td><p>Description</p></td>
 425   </tr>
 426   <tr>
 427     <td><p></p></td>  <td><p></p></td>
 428   </tr>
 429   <tr>
 430     <td><p><span translate="no">x1</span></p></td>
 431     <td><p>x coordinate of 1st endpoint of the line segment.</p></td>
 432   </tr>
 433   <tr>
 434     <td><p><span translate="no">y1</span></p></td>
 435     <td><p>y coordinate of 1st endpoint of the line segment.</p></td>
 436   </tr>
 437   <tr>
 438     <td><p><span translate="no">x2</span></p></td>
 439     <td><p>x coordinate of 2st endpoint of the line segment.</p></td>
 440   </tr>
 441   <tr>
 442     <td><p><span translate="no">y2</span></p></td>
 443     <td><p>y coordinate of 2st endpoint of the line segment.</p></td>
 444   </tr>
 445 </table>
 446     </section>
 447
 448     <section id="template-markup-circle-node">
 449       <title><span translate="no">Markup-circle</span> Node</title>
 450
 451       <p>A <em><span translate="no">Markup-circle</span></em> describes a markup circle.</p>
 452
 453 <table frame="all" rules="rows">
 454   <tr>
 455     <td><p>Property</p></td>  <td><p>Description</p></td>
 456   </tr>
 457   <tr>
 458     <td><p></p></td>  <td><p></p></td>
 459   </tr>
 460   <tr>
 461     <td><p><span translate="no">x0</span></p></td>
 462     <td><p>x coordinate of circle origin (center).</p></td>
 463   </tr>
 464   <tr>
 465     <td><p><span translate="no">y0</span></p></td>
 466     <td><p>y coordinate of circle origin (center).</p></td>
 467   </tr>
 468   <tr>
 469     <td><p><span translate="no">radius</span></p></td>
 470     <td><p>Radius of circle.</p></td>
 471   </tr>
 472 </table>
 473     </section>
 474
 475     <section id="template-markup-rect-node">
 476       <title><span translate="no">Markup-rect</span> Node</title>
 477
 478       <p>A <em><span translate="no">Markup-rect</span></em> describes a markup rectangle.</p>
 479
 480 <table frame="all" rules="rows">
 481   <tr>
 482     <td><p>Property</p></td>  <td><p>Description</p></td>
 483   </tr>
 484   <tr>
 485     <td><p></p></td>  <td><p></p></td>
 486   </tr>
 487   <tr>
 488     <td><p><span translate="no">x1</span></p></td>
 489     <td><p>x coordinate of upper left corner of rectangle.</p></td>
 490   </tr>
 491   <tr>
 492     <td><p><span translate="no">y1</span></p></td>
 493     <td><p>y coordinate of upper left corner of rectangle.</p></td>
 494   </tr>
 495   <tr>
 496     <td><p><span translate="no">w</span></p></td>
 497     <td><p>Width of rectangle.</p></td>
 498   </tr>
 499   <tr>
 500     <td><p><span translate="no">h</span></p></td>
 501     <td><p>Height of rectangle.</p></td>
 502   </tr>
 503   <tr>
 504     <td><p><span translate="no">r</span></p></td>
 505     <td><p>Radius of rounded corners of rectangle.</p></td>
 506   </tr>
 507 </table>
 508     </section>
 509
 510     <section id="template-markup-ellipse-node">
 511       <title><span translate="no">Markup-ellipse</span> Node</title>
 512
 513       <p>A <em><span translate="no">Markup-ellipse</span></em> describes a markup ellipse.</p>
 514
 515 <table frame="all" rules="rows">
 516   <tr>
 517     <td><p>Property</p></td>  <td><p>Description</p></td>
 518   </tr>
 519   <tr>
 520     <td><p></p></td>  <td><p></p></td>
 521   </tr>
 522   <tr>
 523     <td><p><span translate="no">x1</span></p></td>
 524     <td><p>x coordinate of upper left corner of ellipse.</p></td>
 525   </tr>
 526   <tr>
 527     <td><p><span translate="no">y1</span></p></td>
 528     <td><p>y coordinate of upper left corner of ellipse.</p></td>
 529   </tr>
 530   <tr>
 531     <td><p><span translate="no">w</span></p></td>
 532     <td><p>Width of ellipse.</p></td>
 533   </tr>
 534   <tr>
 535     <td><p><span translate="no">h</span></p></td>
 536     <td><p>Height of ellipse.</p></td>
 537   </tr>
 538 </table>
 539     </section>
 540
 541     </section>
 542
 543     <section id="template-layout-node">
 544       <title><span translate="no">Layout</span> Node</title>
 545
 546       <p>A label node may contain multiple <em><span translate="no">Layout</span></em>
 547         children.  If labels are arranged in a simple grid pattern, only
 548         one layout is needed.  However, if labels are arranged in multiple
 549         grids, such as a running bond pattern, multiple
 550         <em><span translate="no">Layout</span></em> tags can be used.
 551         Note: a single label can always be treated as a grid of one.</p>
 552
 553 <table frame="all" rules="rows">
 554   <tr>
 555     <td><p>Property</p></td>  <td><p>Description</p></td>
 556   </tr>
 557   <tr>
 558     <td><p></p></td>  <td><p></p></td>
 559   </tr>
 560   <tr>
 561     <td><p><span translate="no">nx</span></p></td>
 562     <td><p>Number of labels/cards across in the grid (horizontal)</p></td>
 563   </tr>
 564   <tr>
 565     <td><p><span translate="no">ny</span></p></td>
 566     <td><p>Number of labels/cards across in the grid (vertical)</p></td>
 567   </tr>
 568   <tr>
 569     <td><p><span translate="no">x0</span></p></td>
 570     <td><p>Distance from left edge of sheet to the left edge of
 571                   the left column of cards/labels in the layout.</p></td>
 572   </tr>
 573   <tr>
 574     <td><p><span translate="no">y0</span></p></td>
 575     <td><p>Distance from the top edge of sheet to the top edge of
 576                   the top row of labels/cards in the layout.</p></td>
 577   </tr>
 578   <tr>
 579     <td><p><span translate="no">dx</span></p></td>
 580     <td><p>Horizontal pitch of grid.</p></td>
 581   </tr>
 582   <tr>
 583     <td><p><span translate="no">dy</span></p></td>
 584     <td><p>Vertical pitch of grid.</p></td>
 585   </tr>
 586 </table>
 587
 588               <!-- ==== Figure ==== -->
 589               <figure>
 590                 <desc><span translate="no">Layout</span> parameters</desc>
 591                 <media type="image" src="figures/glabels-template-layout.png" mime="image/png" style="right">
 592                 <p><span translate="no">Layout</span> Parameters</p>
 593                 </media>
 594               </figure>
 595               <!-- ==== End of Figure ==== -->
 596     </section>
 597
 598
 599 </page>