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       <file>${prefix}/share/glabels/</file>,
  29       where <file>${prefix}</file> is usually something like
  30       <file>/usr/local</file> or <file>/usr</file> depending
  31       on the configuration option <file>prefix</file>.  gLabels will
  32       use all files of the form <file>*-templates.xml</file>
  33       or <file>*.template</file>, that it finds in
  34       <file>${prefix}/share/glabels/</file> and
  35       <file>${HOME}/.glabels/</file>.
  36       Additional templates can be added by creating additional
  37       <file>*.template</file> files in either of these directories.
  38       </p>
  39
  40     <p>The format for these files is defined in the DTD:
  41       <link href="http://glabels.sourceforge.net/doc/glabels-2.0.dtd.txt">glabels-2.2.dtd</link>.
  42       (This DTD also describes other XML formats used by glabels.)</p>
  43
  44     <section id="template-assumptions">
  45       <title>Assumptions/caveats</title>
  46       <list>
  47         <item>
  48           <p>A sheet contains only one size of label or card (if a sheet
  49             contains more than one size of item, it can be split into
  50              multiple templates for multiple pass printing)</p>
  51         </item>
  52         <item>
  53           <p>Distances can be expressed in units of <em>pt</em>,
  54             <em>in</em>, <em>mm</em>,
  55             <em>cm</em>, or <em>pc</em>.  For example:
  56             "<literal>1.0in</literal>" or "<literal>2.54cm</literal>".  If no
  57             units are specified, computer points (<em>pt</em>) will
  58             be assumed (1 <em>pt</em> =
  59             1/72 <em>in</em> = 0.352778 <em>mm</em>).
  60             </p>
  61         </item>
  62       </list>
  63     </section>
  64
  65     <section id="template-file">
  66       <title>Template Files</title>
  67
  68       <code>
  69 &lt;?xml version="1.0"?&gt;
  70 &lt;Glabels-templates&gt;
  71
  72    <replaceable>...templates...</replaceable>
  73
  74 &lt;/Glabels-templates&gt;
  75       </code>
  76     </section>
  77
  78
  79     <section id="template-example">
  80       <title>Example Template</title>
  81       <code>
  82   &lt;Template brand="Avery" part="8160" size="US-Letter" description="Mailing Labels"&gt;
  83     &lt;Meta category="label"/&gt;
  84     &lt;Meta category="mail"/&gt;
  85     &lt;Meta product_url="http://www.avery.com/avery/en_us/"/&gt;
  86     &lt;Label-rectangle id="0" width="189pt" height="72pt" round="5pt"&gt;
  87       &lt;Markup-margin size="5pt"/&gt;
  88       &lt;Layout nx="3" ny="10" x0="11.25pt" y0="36pt" dx="200pt" dy="72pt"/&gt;
  89     &lt;/Label-rectangle&gt;
  90     &lt;Alias brand="Avery" part="5160"/&gt;
  91     &lt;Alias brand="Avery" part="6233"/&gt;
  92   &lt;/Template&gt;
  93       </code>
  94     </section>
  95
  96     <section id="template-template-node">
  97       <title>Template Node</title>
  98
  99       <p>A <em>Template</em> node describes a single stationary
 100         product.  It must contain one instance of any type of Label node
 101         (<em>Label-rectangle</em>,
 102         <em>Label-round</em>, or <em>Label-cd</em>).
 103         This node can be followed by zero or more
 104         <em>Alias</em> nodes.</p>
 105
 106 <table frame="all" rules="rows">
 107   <tr>
 108     <td><p>Property</p></td>  <td><p>Description</p></td>
 109   </tr>
 110   <tr>
 111     <td><p></p></td>  <td><p></p></td>
 112   </tr>
 113   <tr>
 114     <td><p>brand</p></td>  <td><p>Brand or manufacturer of stationary product. E.g. "Avery"</p></td>
 115   </tr>
 116   <tr>
 117     <td><p>part</p></td> <td><p>Part number or name of stationary product. E.g. "8160"</p></td>
 118   </tr>
 119   <tr>
 120     <td><p>size</p></td> <td><p>Size of sheet.  E.g., "US-Letter," "A4", ...</p></td>
 121   </tr>
 122   <tr>
 123     <td><p>description</p></td> <td><p>Description of stationary product.  E.g, "Mailing Labels."</p></td>
 124   </tr>
 125   <tr>
 126     <td><p>_description</p></td>  <td><p>Translatable description of stationary product. E.g, "Mailing Labels." (Only useful for predefined templates)</p></td>
 127   </tr>
 128   <tr>
 129     <td><p>width</p></td>  <td><p>Page width.  Only valid if size="Other"</p></td>
 130   </tr>
 131   <tr>
 132     <td><p>height</p></td>  <td><p>Page height.  Only valid if size="Other"</p></td>
 133   </tr>
 134 </table>
 135
 136 </section>
 137
 138     <section id="template-template-node">
 139       <title>Meta Node</title>
 140
 141       <p>A <em>Meta</em> node contains some additional properties of that product.
 142         This node may appear more than once, with a subnode each.</p>
 143
 144 <table frame="all" rules="rows">
 145   <tr>
 146     <td><p>Subnode</p></td>  <td><p>Description</p></td>
 147   </tr>
 148   <tr>
 149     <td><p></p></td>  <td><p></p></td>
 150   </tr>
 151   <tr>
 152     <td><p>category</p></td>  <td><p>The category which this product is assigned to. The value
 153         of this category is used by the <app>gLabels'</app> template chooser to filter the
 154         view to display only mailing labels, or labels in common and suppress any other products
 155         which the user don't want to find. One product can be assigned to several categories.</p></td>
 156   </tr>
 157   <tr>
 158     <td><p>product_url</p></td> <td><p>This address points to the vendor's website. Ideally,
 159         the link shows the URL of that certain product, if available.</p></td>
 160   </tr>
 161 </table>
 162
 163 </section>
 164
 165     <section id="template-label-rectangle-node">
 166       <title>Label-rectangle Node</title>
 167
 168       <p>A <em>Label-rectangle</em> node describes the
 169         dimensions of a single label or business card that is rectangular
 170         in shape (may have rounded edges).</p>
 171
 172 <table frame="all" rules="rows">
 173   <tr>
 174     <td><p>Property</p></td>  <td><p>Description</p></td>
 175   </tr>
 176   <tr>
 177     <td><p></p></td>  <td><p></p></td>
 178   </tr>
 179   <tr>
 180     <td><p>id</p></td>  <td><p>Reserved for future use.  Should always be 0.</p></td>
 181   </tr>
 182   <tr>
 183     <td><p>width</p></td> <td><p>Width of label/card</p></td>
 184   </tr>
 185   <tr>
 186     <td><p>height</p></td> <td><p>Heigth of label/card</p></td>
 187   </tr>
 188   <tr>
 189     <td><p>round</p></td> <td><p>Radius of corners.  For items with square edges (business cards), the radius should be 0.</p></td>
 190   </tr>
 191   <tr>
 192     <td><p>x_waste</p></td>  <td><p>Amount of horizontal waste (over-print) to allow.  This is useful
 193                   for minimizing alignment problems when using non-white
 194                   backgrounds (e.g. images).</p></td>
 195   </tr>
 196   <tr>
 197     <td><p>y_waste</p></td>  <td><p>Amount of vertical waste (over-print) to allow.  This is useful
 198                   for minimizing alignment problems when using non-white
 199                   backgrounds (e.g. images).</p></td>
 200   </tr>
 201 </table>
 202
 203       <!-- ==== Figure ==== -->
 204                 <media type="image" src="figures/glabels-template-label.png" mime="image/png" style="right">
 205                 <p>Label-rectangle parameters</p>
 206                 </media>
 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                 <media type="image" src="figures/glabels-template-ellipse.png" mime="image/png" style="right">
 242                 <p>Label-ellipse parameters</p>
 243                 </media>
 244       <!-- ==== End of Figure ==== -->
 245         </section>
 246
 247     <section id="template-label-round-node">
 248       <title>Label-round Node</title>
 249
 250       <p>A <em>Label-round</em> node describes the dimensions
 251         of a simple round label (not a CD).</p>
 252
 253 <table frame="all" rules="rows">
 254   <tr>
 255     <td><p>Property</p></td>  <td><p>Description</p></td>
 256   </tr>
 257   <tr>
 258     <td><p></p></td>  <td><p></p></td>
 259   </tr>
 260   <tr>
 261     <td><p>id</p></td>  <td><p>Reserved for future use.  Should always be 0.</p></td>
 262   </tr>
 263   <tr>
 264     <td><p>radius</p></td> <td><p>Radius (1/2 diameter) of label</p></td>
 265   </tr>
 266   <tr>
 267     <td><p>waste</p></td>  <td><p>Amount of waste (over-print) to allow.  This is useful
 268                   for minimizing alignment problems when using non-white
 269                   backgrounds (e.g. images).</p></td>
 270   </tr>
 271 </table>
 272     </section>
 273
 274     <section id="template-label-cd-node">
 275       <title>Label-cd Node</title>
 276
 277       <p>A <em>Label-round</em> node describes the dimensions
 278         of a CD, DVD, or business card CD.</p>
 279
 280 <table frame="all" rules="rows">
 281   <tr>
 282     <td><p>Property</p></td>  <td><p>Description</p></td>
 283   </tr>
 284   <tr>
 285     <td><p></p></td>  <td><p></p></td>
 286   </tr>
 287   <tr>
 288     <td><p>id</p></td>  <td><p>Reserved for future use.  Should always be 0.</p></td>
 289   </tr>
 290   <tr>
 291     <td><p>radius</p></td> <td><p>Outer radius of label</p></td>
 292   </tr>
 293   <tr>
 294     <td><p>hole</p></td>  <td><p>Radius of concentric hole</p></td>
 295   </tr>
 296   <tr>
 297     <td><p>width</p></td> <td><p>If present, the label is clipped to the given width.
 298                   (Useful for "business card CDs").</p></td>
 299   </tr>  <tr>
 300     <td><p>heigth</p></td> <td><p>If present, the label is clipped to the given height.
 301                   (Useful for "business card CDs").</p></td>
 302   </tr>  <tr>
 303     <td><p>waste</p></td> <td><p>Amount of waste (over-print) to allow.  This is useful
 304                   for minimizing alignment problems when using non-white
 305                   backgrounds (e.g. images).</p></td>
 306   </tr>
 307 </table>
 308
 309               <!-- ==== Figure ==== -->
 310                 <media type="image" src="figures/glabels-template-cd.png" mime="image/png" style="right">
 311                 <p>CD label parameters</p>
 312                 </media>
 313               <!-- ==== End of Figure ==== -->
 314     </section>
 315
 316     <section id="template-markup-margin-node">
 317       <title>Markup-margin Node</title>
 318
 319       <p>A <em>Markup-margin</em> describes a margin along
 320         all edges of a label.</p>
 321
 322 <table frame="all" rules="rows">
 323   <tr>
 324     <td><p>Property</p></td>  <td><p>Description</p></td>
 325   </tr>
 326   <tr>
 327     <td><p></p></td>  <td><p></p></td>
 328   </tr>
 329   <tr>
 330     <td><p>size</p></td>  <td><p>Size of the margin.  I.e. the distance of the margin
 331                   line from the edge of the card/label.</p></td>
 332   </tr>
 333 </table>
 334     </section>
 335
 336     <section id="template-markup-line-node">
 337       <title>Markup-line Node</title>
 338
 339       <p>A <em>Markup-line</em> describes a markup line.</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>x1</p></td>  <td><p>x coordinate of 1st endpoint of the line segment.</p></td>
 350   </tr>
 351   <tr>
 352     <td><p>y1</p></td>  <td><p>y coordinate of 1st endpoint of the line segment.</p></td>
 353   </tr>
 354   <tr>
 355     <td><p>x2</p></td>  <td><p>x coordinate of 2st endpoint of the line segment.</p></td>
 356   </tr>
 357   <tr>
 358     <td><p>y2</p></td>  <td><p>y coordinate of 2st endpoint of the line segment.</p></td>
 359   </tr>
 360 </table>
 361     </section>
 362
 363     <section id="template-markup-circle-node">
 364       <title>Markup-circle Node</title>
 365
 366       <p>A <em>Markup-circle</em> describes a markup circle.</p>
 367
 368 <table frame="all" rules="rows">
 369   <tr>
 370     <td><p>Property</p></td>  <td><p>Description</p></td>
 371   </tr>
 372   <tr>
 373     <td><p></p></td>  <td><p></p></td>
 374   </tr>
 375   <tr>
 376     <td><p>x0</p></td>  <td><p>x coordinate of circle origin (center).</p></td>
 377   </tr>
 378   <tr>
 379     <td><p>y0</p></td>  <td><p>y coordinate of circle origin (center).</p></td>
 380   </tr>
 381   <tr>
 382     <td><p>radius</p></td>  <td><p>Radius of circle.</p></td>
 383   </tr>
 384 </table>
 385     </section>
 386
 387     <section id="template-markup-rect-node">
 388       <title>Markup-rect Node</title>
 389
 390       <p>A <em>Markup-rect</em> describes a markup rectangle.</p>
 391
 392 <table frame="all" rules="rows">
 393   <tr>
 394     <td><p>Property</p></td>  <td><p>Description</p></td>
 395   </tr>
 396   <tr>
 397     <td><p></p></td>  <td><p></p></td>
 398   </tr>
 399   <tr>
 400     <td><p>x1</p></td>  <td><p>x coordinate of upper left corner of rectangle.</p></td>
 401   </tr>
 402   <tr>
 403     <td><p>y1</p></td>  <td><p>y coordinate of upper left corner of rectangle.</p></td>
 404   </tr>
 405   <tr>
 406     <td><p>w</p></td>  <td><p>Width of rectangle.</p></td>
 407   </tr>
 408   <tr>
 409     <td><p>h</p></td>  <td><p>Height of rectangle.</p></td>
 410   </tr>
 411   <tr>
 412     <td><p>r</p></td>  <td><p>Radius of rounded corners of rectangle.</p></td>
 413   </tr>
 414 </table>
 415     </section>
 416
 417     <section id="template-layout-node">
 418       <title>Layout Node</title>
 419
 420       <p>A label node may contain multiple <em>Layout</em>
 421         children.  If labels are arranged in a simple grid pattern, only
 422         one layout is needed.  However, if labels are arranged in multiple
 423         grids, such as a running bond pattern, multiple
 424         <em>layout</em> tags can be used.  Note: a single label
 425         can always be treated as a grid of one.</p>
 426
 427 <table frame="all" rules="rows">
 428   <tr>
 429     <td><p>Property</p></td>  <td><p>Description</p></td>
 430   </tr>
 431   <tr>
 432     <td><p></p></td>  <td><p></p></td>
 433   </tr>
 434   <tr>
 435     <td><p>nx</p></td>  <td><p>Number of labels/cards across in the grid (horizontal)</p></td>
 436   </tr>
 437   <tr>
 438     <td><p>ny</p></td>  <td><p>Number of labels/cards across in the grid (vertical)</p></td>
 439   </tr>
 440   <tr>
 441     <td><p>x0</p></td>  <td><p>Distance from left edge of sheet to the left edge of
 442                   the left column of cards/labels in the layout.</p></td>
 443   </tr>
 444   <tr>
 445     <td><p>y0</p></td>  <td><p>Distance from the top edge of sheet to the top edge of
 446                   the top row of labels/cards in the layout.</p></td>
 447   </tr>
 448   <tr>
 449     <td><p>dx</p></td>  <td><p>Horizontal pitch of grid.</p></td>
 450   </tr>
 451   <tr>
 452     <td><p>dy</p></td>  <td><p>Vertical pitch of grid.</p></td>
 453   </tr>
 454 </table>
 455
 456               <!-- ==== Figure ==== -->
 457                 <media type="image" src="figures/glabels-template-layout.png" mime="image/png" style="right">
 458                 <p>Layout Parameters</p>
 459                 </media>
 460               <!-- ==== End of Figure ==== -->
 461     </section>
 462
 463     <section id="template-alias-node">
 464       <title>Alias Node</title>
 465
 466       <p>An <em>Alias</em> node provides the name of a
 467         product with the same size and layout characteristics as the
 468         parent template.</p>
 469
 470 <table frame="all" rules="rows">
 471   <tr>
 472     <td><p>Property</p></td>  <td><p>Description</p></td>
 473   </tr>
 474   <tr>
 475     <td><p></p></td>  <td><p></p></td>
 476   </tr>
 477   <tr>
 478     <td><p>brand</p></td>  <td><p>The brand or manufacturer of the equivalent product.</p></td>
 479   </tr>
 480   <tr>
 481     <td><p>part</p></td>  <td><p>The part number of the equivalent product.</p></td>
 482   </tr>
 483 </table>
 484
 485     </section>
 486
 487
 488 </page>