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 glabels was installed.  Glabels 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 glabels.)</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             "<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>).
  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    <replaceable>...templates...</replaceable>
  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;Alias brand="Avery" part="5160"/&gt;
  88     &lt;Alias brand="Avery" part="6233"/&gt;
  89   &lt;/Template&gt;
  90       </code>
  91     </section>
  92
  93     <section id="template-template-node">
  94       <title>Template Node</title>
  95
  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>
 102
 103 <table frame="all" rules="rows">
 104   <tr>
 105     <td><p>Property</p></td>  <td><p>Description</p></td>
 106   </tr>
 107   <tr>
 108     <td><p></p></td>  <td><p></p></td>
 109   </tr>
 110   <tr>
 111     <td><p>brand</p></td>  <td><p>Brand or manufacturer of stationary product. E.g. "Avery"</p></td>
 112   </tr>
 113   <tr>
 114     <td><p>part</p></td> <td><p>Part number or name of stationary product. E.g. "8160"</p></td>
 115   </tr>
 116   <tr>
 117     <td><p>size</p></td> <td><p>Size of sheet.  E.g., "US-Letter," "A4", ...</p></td>
 118   </tr>
 119   <tr>
 120     <td><p>description</p></td> <td><p>Description of stationary product.  E.g, "Mailing Labels."</p></td>
 121   </tr>
 122   <tr>
 123     <td><p>_description</p></td>  <td><p>Translatable description of stationary product. E.g, "Mailing Labels." (Only useful for predefined templates)</p></td>
 124   </tr>
 125   <tr>
 126     <td><p>width</p></td>  <td><p>Page width.  Only valid if size="Other"</p></td>
 127   </tr>
 128   <tr>
 129     <td><p>height</p></td>  <td><p>Page height.  Only valid if size="Other"</p></td>
 130   </tr>
 131 </table>
 132
 133 </section>
 134
 135     <section id="template-template-node">
 136       <title>Meta Node</title>
 137
 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>
 140
 141 <table frame="all" rules="rows">
 142   <tr>
 143     <td><p>Subnode</p></td>  <td><p>Description</p></td>
 144   </tr>
 145   <tr>
 146     <td><p></p></td>  <td><p></p></td>
 147   </tr>
 148   <tr>
 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>
 153   </tr>
 154   <tr>
 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>
 157   </tr>
 158 </table>
 159
 160 </section>
 161
 162     <section id="template-label-rectangle-node">
 163       <title>Label-rectangle Node</title>
 164
 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>
 168
 169 <table frame="all" rules="rows">
 170   <tr>
 171     <td><p>Property</p></td>  <td><p>Description</p></td>
 172   </tr>
 173   <tr>
 174     <td><p></p></td>  <td><p></p></td>
 175   </tr>
 176   <tr>
 177     <td><p>id</p></td>  <td><p>Reserved for future use.  Should always be 0.</p></td>
 178   </tr>
 179   <tr>
 180     <td><p>width</p></td> <td><p>Width of label/card</p></td>
 181   </tr>
 182   <tr>
 183     <td><p>height</p></td> <td><p>Heigth of label/card</p></td>
 184   </tr>
 185   <tr>
 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>
 187   </tr>
 188   <tr>
 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>
 192   </tr>
 193   <tr>
 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>
 197   </tr>
 198 </table>
 199
 200       <!-- ==== Figure ==== -->
 201       <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>
 205                 </media>
 206       </figure>
 207       <!-- ==== End of Figure ==== -->
 208         </section>
 209
 210     <section id="template-label-rectangle-node">
 211       <title>Label-ellipse Node</title>
 212
 213       <p>A <em>Label-ellipse</em> node describes the
 214         dimensions of a single label or business card that is elliptic
 215         in shape.</p>
 216
 217 <table frame="all" rules="rows">
 218   <tr>
 219     <td><p>Property</p></td>  <td><p>Description</p></td>
 220   </tr>
 221   <tr>
 222     <td><p></p></td>  <td><p></p></td>
 223   </tr>
 224   <tr>
 225     <td><p>id</p></td>  <td><p>Reserved for future use.  Should always be 0.</p></td>
 226   </tr>
 227   <tr>
 228     <td><p>width</p></td> <td><p>Width of the ellipse</p></td>
 229   </tr>
 230   <tr>
 231     <td><p>height</p></td> <td><p>Heigth of the ellipse</p></td>
 232   </tr>
 233   <tr>
 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>
 237   </tr>
 238 </table>
 239
 240       <!-- ==== Figure ==== -->
 241       <figure>
 242                 <desc>Label-ellipse parameters</desc>
 243                 <media type="image" src="figures/glabels-template-ellipse-label.png" mime="image/png" style="right">
 244                 </media>
 245       </figure>
 246       <!-- ==== End of Figure ==== -->
 247         </section>
 248
 249     <section id="template-label-round-node">
 250       <title>Label-round Node</title>
 251
 252       <p>A <em>Label-round</em> node describes the dimensions
 253         of a simple round label (not a CD).</p>
 254
 255 <table frame="all" rules="rows">
 256   <tr>
 257     <td><p>Property</p></td>  <td><p>Description</p></td>
 258   </tr>
 259   <tr>
 260     <td><p></p></td>  <td><p></p></td>
 261   </tr>
 262   <tr>
 263     <td><p>id</p></td>  <td><p>Reserved for future use.  Should always be 0.</p></td>
 264   </tr>
 265   <tr>
 266     <td><p>radius</p></td> <td><p>Radius (1/2 diameter) of label</p></td>
 267   </tr>
 268   <tr>
 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>
 272   </tr>
 273 </table>
 274
 275       <!-- ==== Figure ==== -->
 276       <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>
 280                 </media>
 281       </figure>
 282       <!-- ==== End of Figure ==== -->
 283     </section>
 284
 285     <section id="template-label-cd-node">
 286       <title>Label-cd Node</title>
 287
 288       <p>A <em>Label-round</em> node describes the dimensions
 289         of a CD, DVD, or business card CD.</p>
 290
 291 <table frame="all" rules="rows">
 292   <tr>
 293     <td><p>Property</p></td>  <td><p>Description</p></td>
 294   </tr>
 295   <tr>
 296     <td><p></p></td>  <td><p></p></td>
 297   </tr>
 298   <tr>
 299     <td><p>id</p></td>  <td><p>Reserved for future use.  Should always be 0.</p></td>
 300   </tr>
 301   <tr>
 302     <td><p>radius</p></td> <td><p>Outer radius of label</p></td>
 303   </tr>
 304   <tr>
 305     <td><p>hole</p></td>  <td><p>Radius of concentric hole</p></td>
 306   </tr>
 307   <tr>
 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>
 310   </tr>  <tr>
 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>
 313   </tr>  <tr>
 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>
 317   </tr>
 318 </table>
 319
 320               <!-- ==== Figure ==== -->
 321               <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>
 325                 </media>
 326               </figure>
 327               <!-- ==== End of Figure ==== -->
 328     </section>
 329
 330     <section id="template-markup">
 331       <title>Markup Nodes</title>
 332
 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 glabels 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>
 337
 338     <section id="template-markup-margin-node">
 339       <title>Markup-margin Node</title>
 340
 341       <p>A <em>Markup-margin</em> describes a margin along
 342         all edges of a label.</p>
 343
 344 <table frame="all" rules="rows">
 345   <tr>
 346     <td><p>Property</p></td>  <td><p>Description</p></td>
 347   </tr>
 348   <tr>
 349     <td><p></p></td>  <td><p></p></td>
 350   </tr>
 351   <tr>
 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>
 354   </tr>
 355 </table>
 356     </section>
 357
 358     <section id="template-markup-line-node">
 359       <title>Markup-line Node</title>
 360
 361       <p>A <em>Markup-line</em> describes a markup line.</p>
 362
 363 <table frame="all" rules="rows">
 364   <tr>
 365     <td><p>Property</p></td>  <td><p>Description</p></td>
 366   </tr>
 367   <tr>
 368     <td><p></p></td>  <td><p></p></td>
 369   </tr>
 370   <tr>
 371     <td><p>x1</p></td>  <td><p>x coordinate of 1st endpoint of the line segment.</p></td>
 372   </tr>
 373   <tr>
 374     <td><p>y1</p></td>  <td><p>y coordinate of 1st endpoint of the line segment.</p></td>
 375   </tr>
 376   <tr>
 377     <td><p>x2</p></td>  <td><p>x coordinate of 2st endpoint of the line segment.</p></td>
 378   </tr>
 379   <tr>
 380     <td><p>y2</p></td>  <td><p>y coordinate of 2st endpoint of the line segment.</p></td>
 381   </tr>
 382 </table>
 383     </section>
 384
 385     <section id="template-markup-circle-node">
 386       <title>Markup-circle Node</title>
 387
 388       <p>A <em>Markup-circle</em> describes a markup circle.</p>
 389
 390 <table frame="all" rules="rows">
 391   <tr>
 392     <td><p>Property</p></td>  <td><p>Description</p></td>
 393   </tr>
 394   <tr>
 395     <td><p></p></td>  <td><p></p></td>
 396   </tr>
 397   <tr>
 398     <td><p>x0</p></td>  <td><p>x coordinate of circle origin (center).</p></td>
 399   </tr>
 400   <tr>
 401     <td><p>y0</p></td>  <td><p>y coordinate of circle origin (center).</p></td>
 402   </tr>
 403   <tr>
 404     <td><p>radius</p></td>  <td><p>Radius of circle.</p></td>
 405   </tr>
 406 </table>
 407     </section>
 408
 409     <section id="template-markup-rect-node">
 410       <title>Markup-rect Node</title>
 411
 412       <p>A <em>Markup-rect</em> describes a markup rectangle.</p>
 413
 414 <table frame="all" rules="rows">
 415   <tr>
 416     <td><p>Property</p></td>  <td><p>Description</p></td>
 417   </tr>
 418   <tr>
 419     <td><p></p></td>  <td><p></p></td>
 420   </tr>
 421   <tr>
 422     <td><p>x1</p></td>  <td><p>x coordinate of upper left corner of rectangle.</p></td>
 423   </tr>
 424   <tr>
 425     <td><p>y1</p></td>  <td><p>y coordinate of upper left corner of rectangle.</p></td>
 426   </tr>
 427   <tr>
 428     <td><p>w</p></td>  <td><p>Width of rectangle.</p></td>
 429   </tr>
 430   <tr>
 431     <td><p>h</p></td>  <td><p>Height of rectangle.</p></td>
 432   </tr>
 433   <tr>
 434     <td><p>r</p></td>  <td><p>Radius of rounded corners of rectangle.</p></td>
 435   </tr>
 436 </table>
 437     </section>
 438
 439     <section id="template-markup-ellipse-node">
 440       <title>Markup-ellipse Node</title>
 441
 442       <p>A <em>Markup-ellipse</em> describes a markup ellipse.</p>
 443
 444 <table frame="all" rules="rows">
 445   <tr>
 446     <td><p>Property</p></td>  <td><p>Description</p></td>
 447   </tr>
 448   <tr>
 449     <td><p></p></td>  <td><p></p></td>
 450   </tr>
 451   <tr>
 452     <td><p>x1</p></td>  <td><p>x coordinate of upper left corner of ellipse.</p></td>
 453   </tr>
 454   <tr>
 455     <td><p>y1</p></td>  <td><p>y coordinate of upper left corner of ellipse.</p></td>
 456   </tr>
 457   <tr>
 458     <td><p>w</p></td>  <td><p>Width of ellipse.</p></td>
 459   </tr>
 460   <tr>
 461     <td><p>h</p></td>  <td><p>Height of ellipse.</p></td>
 462   </tr>
 463 </table>
 464     </section>
 465
 466     </section>
 467
 468     <section id="template-layout-node">
 469       <title>Layout Node</title>
 470
 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>
 477
 478 <table frame="all" rules="rows">
 479   <tr>
 480     <td><p>Property</p></td>  <td><p>Description</p></td>
 481   </tr>
 482   <tr>
 483     <td><p></p></td>  <td><p></p></td>
 484   </tr>
 485   <tr>
 486     <td><p>nx</p></td>  <td><p>Number of labels/cards across in the grid (horizontal)</p></td>
 487   </tr>
 488   <tr>
 489     <td><p>ny</p></td>  <td><p>Number of labels/cards across in the grid (vertical)</p></td>
 490   </tr>
 491   <tr>
 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>
 494   </tr>
 495   <tr>
 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>
 498   </tr>
 499   <tr>
 500     <td><p>dx</p></td>  <td><p>Horizontal pitch of grid.</p></td>
 501   </tr>
 502   <tr>
 503     <td><p>dy</p></td>  <td><p>Vertical pitch of grid.</p></td>
 504   </tr>
 505 </table>
 506
 507               <!-- ==== Figure ==== -->
 508               <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>
 512                 </media>
 513               </figure>
 514               <!-- ==== End of Figure ==== -->
 515     </section>
 516
 517     <section id="template-alias-node">
 518       <title>Alias Node</title>
 519
 520       <p>An <em>Alias</em> node provides the name of a
 521         product with the same size and layout characteristics as the
 522         parent template.</p>
 523
 524 <table frame="all" rules="rows">
 525   <tr>
 526     <td><p>Property</p></td>  <td><p>Description</p></td>
 527   </tr>
 528   <tr>
 529     <td><p></p></td>  <td><p></p></td>
 530   </tr>
 531   <tr>
 532     <td><p>brand</p></td>  <td><p>The brand or manufacturer of the equivalent product.</p></td>
 533   </tr>
 534   <tr>
 535     <td><p>part</p></td>  <td><p>The part number of the equivalent product.</p></td>
 536   </tr>
 537 </table>
 538
 539     </section>
 540
 541
 542 </page>