git.sur5r.net Git - glabels/blob - web/doc/templates-2.0/index.php

   1 <?php include "../../common_php.inc"; ?>
   2
   3 <?php gLabelsHeader("docs"); ?>
   4
   5 <h1 class="doc">Defining new gLabels templates for gLabels 2.0.x</h1>
   6
   7 <p>
   8 Predefined templates are defined by XML files located in
   9 <i>${prefix}/share/glabels/</i>,
  10 where <i>${prefix}</i> is usually something like
  11 <i>/usr/local</i> or <i>/usr</i> depending
  12 on the configuration option <i>prefix</i>.  gLabels will
  13 use all files of the form <i>*-templates.xml</i> or <i>*.template</i>,
  14 that it finds in <i>${prefix}/share/glabels/</i> and <i>${HOME}/.glabels/</i>.
  15 Additional templates can be added by creating additional
  16 <i>*.template</i> files in either of these directories.
  17 </p>
  18 <ul>
  19   <li>The format for these files is defined in the DTD: <?a("/doc/glabels-2.0.dtd.txt","glabels-2.0.dtd");?>. (This DTD also describes other XML formats used by glabels.)</li>
  20 </ul>
  21
  22 <h2>Assumptions/caveats</h2>
  23 <ul>
  24   <li>A sheet contains only one size of label or card (if a sheet contains more than one size of item, it can be split into multiple templates for multiple pass printing)</li>
  25   <li>Distances can be expressed in units of <i>pt</i>, <i>in</i>, <i>mm</i>, <i>cm</i>, or <i>pc</i>.  For example: "1.0in" or "2.54cm".  If no units are specified, computer points (<i>pt</i>) will be assumed (1 pt = 1/72 in = 0.352778 mm).</li>
  26 </ul>
  27
  28
  29 <h2><i>*-templates.xml</i> and <i>*.template</i> files</h2>
  30 <div class="codebox">
  31 &lt;?xml version="1.0"?&gt;
  32 &lt;Glabels-templates&gt;
  33
  34    ...<i>templates</i>...
  35
  36 &lt;/Glabels-templates&gt;
  37 </div>
  38
  39
  40 <h2>Example Template</h2>
  41 <div class="codebox">
  42   &lt;Template name="Avery 8160" size="US-Letter" description="Mailing Labels"&gt;
  43     &lt;Label-rectangle id="0" width="189" height="72" round="5"&gt;
  44       &lt;Markup-margin size="5"/&gt;
  45       &lt;Layout nx="3" ny="10" x0="11.25" y0="36" dx="200" dy="72"/&gt;
  46     &lt;/Label-rectangle&gt;
  47     &lt;Alias name="Avery 5160"/&gt;
  48     &lt;Alias name="Avery 6233"/&gt;
  49   &lt;/Template&gt;
  50 </div>
  51
  52
  53 <h2>Template Node</h2>
  54 <p>
  55 A <i>Template</i> node describes a single stationary product.  It must contain
  56 one instance of any type of Label node (<i>Label-rectangle</i>,
  57 <i>Label-round</i>, or <i>Label-cd</i>).  This node can be followed by zero
  58 or more <i>Alias</i> nodes.
  59 </p>
  60 <h3>Properties</h3>
  61 <table border="1">
  62   <tr>
  63     <td valign="top">name</td>
  64     <td>Name or part # of stationary product.  E.g. "Avery 8160"</td>
  65   </tr>
  66   <tr>
  67     <td valign="top">size</td>
  68     <td>Size of sheet.  E.g., "US-Letter," "A4", ...</td>
  69   </tr>
  70   <tr>
  71     <td valign="top">description</td>
  72     <td>Description of stationary product.  E.g, "Mailing Labels."</td>
  73   </tr>
  74   <tr>
  75     <td valign="top">_description</td>
  76     <td>Translatable description of stationary product.  E.g, "Mailing Labels." (Only useful for predefined templates)</td>
  77   </tr>
  78   <tr>
  79     <td valign="top">width</td>
  80     <td>Page width.  Only valid if size="Other"</td>
  81   </tr>
  82   <tr>
  83     <td valign="top">height</td>
  84     <td>Page height.  Only valid if size="Other"</td>
  85   </tr>
  86 </table>
  87
  88 <h2>Label-rectangle Node</h2>
  89 <p>
  90 A <i>Label-rectangle</i> node describes the dimensions of a single label or
  91 business card that is rectangular in shape (may have rounded edges).
  92 </p>
  93 <h3>Properties</h3>
  94 <table border="1">
  95   <tr>
  96     <td valign="top">id</td>
  97     <td>Reserved for future use.  Should always be 0.</td>
  98   </tr>
  99   <tr>
 100     <td valign="top">width</td>
 101     <td>Width of label/card</td>
 102   </tr>
 103   <tr>
 104     <td valign="top">height</td>
 105     <td>Height of label/card</td>
 106   </tr>
 107   <tr>
 108     <td valign="top">round</td>
 109     <td>Radius of corners.  For items with square edges (business cards)
 110         , the radius should be 0.</td>
 111   </tr>
 112   <tr>
 113     <td valign="top">x_waste</td>
 114     <td>Amount of horizontal waste (over-print) to allow.  This is useful for minimizing alignment problems when using non-white backgrounds (e.g. images).</td>
 115   </tr>
 116   <tr>
 117     <td valign="top">y_waste</td>
 118     <td>Amount of vertical waste (over-print) to allow.  This is useful for minimizing alignment problems when using non-white backgrounds (e.g. images).</td>
 119   </tr>
 120 </table>
 121 <br />
 122 <?img("glabels-template-label.png","Label illustration");?>
 123
 124 <h2>Label-round Node</h2>
 125 <p>
 126 A <i>Label-round</i> node describes the dimensions of a simple round label (not a CD).
 127 </p>
 128 <h3>Properties</h3>
 129 <table border="1">
 130   <tr>
 131     <td valign="top">id</td>
 132     <td>Reserved for future use.  Should always be 0.</td>
 133   </tr>
 134   <tr>
 135     <td valign="top">radius</td>
 136     <td>Radius (1/2 diameter) of label</td>
 137   </tr>
 138   <tr>
 139     <td valign="top">waste</td>
 140     <td>Amount of waste (over-print) to allow.  This is useful for minimizing alignment problems when using non-white backgrounds (e.g. images).</td>
 141   </tr>
 142 </table>
 143
 144 <h2>Label-cd Node</h2>
 145 <p>
 146 A <i>Label-cd</i> node describes the dimensions of a CD, DVD, or business card
 147 CD.
 148 </p>
 149 <h3>Properties</h3>
 150 <table border="1">
 151   <tr>
 152     <td valign="top">id</td>
 153     <td>Reserved for future use.  Should always be 0.</td>
 154   </tr>
 155   <tr>
 156     <td valign="top">radius</td>
 157     <td>Outer radius of label</td>
 158   </tr>
 159   <tr>
 160     <td valign="top">hole</td>
 161     <td>Radius of concentric hole</td>
 162   </tr>
 163   <tr>
 164     <td valign="top">width</td>
 165     <td>If present, the label is clipped to the given width.  (Useful for "business card CDs").</td>
 166   </tr>
 167   <tr>
 168     <td valign="top">height</td>
 169     <td>If present, the label is clipped to the given height.  (Useful for "business card CDs").</td>
 170   </tr>
 171   <tr>
 172     <td valign="top">waste</td>
 173     <td>Amount of waste (over-print) to allow.  This is useful for minimizing alignment problems when using non-white backgrounds (e.g. images).</td>
 174   </tr>
 175 </table>
 176 <br />
 177 <?img("glabels-template-cd.png","CD Label illustration");?>
 178
 179
 180 <h2>Markup-margin Node</h2>
 181 <p>
 182 A <i>Markup-margin</i> describes a margin along all edges of a label.
 183 </p>
 184 <h3>Properties</h3>
 185 <table border="1">
 186   <tr>
 187     <td valign="top">size</td>
 188     <td>Size of the margin.  I.e. the distance of the margin line from the
 189         edge of the card/label.</td>
 190   </tr>
 191 </table>
 192
 193
 194 <h2>Markup-line Node</h2>
 195 <p>
 196 A <i>Markup-line</i> describes a markup line.
 197 </p>
 198 <h3>Properties</h3>
 199 <table border="1">
 200   <tr>
 201     <td valign="top">x1</td>
 202     <td>x coordinate of 1st endpoint of the line segment.</td>
 203   </tr>
 204   <tr>
 205     <td valign="top">y1</td>
 206     <td>y coordinate of 1st endpoint of the line segment.</td>
 207   </tr>
 208   <tr>
 209     <td valign="top">x2</td>
 210     <td>x coordinate of 2nd endpoint of the line segment.</td>
 211   </tr>
 212   <tr>
 213     <td valign="top">y2</td>
 214     <td>y coordinate of 2nd endpoint of the line segment.</td>
 215   </tr>
 216 </table>
 217
 218 <h2>Markup-circle Node</h2>
 219 <p>
 220 A <i>Markup-circle</i> describes a markup circle.
 221 </p>
 222 <h3>Properties</h3>
 223 <table border="1">
 224   <tr>
 225     <td valign="top">x0</td>
 226     <td>x coordinate of circle origin (center).</td>
 227   </tr>
 228   <tr>
 229     <td valign="top">y0</td>
 230     <td>y coordinate of circle origin (center).</td>
 231   </tr>
 232   <tr>
 233     <td valign="top">radius</td>
 234     <td>Radius of circle.</td>
 235   </tr>
 236 </table>
 237
 238 <h2>Layout Node</h2>
 239 <p>
 240 A label node may contain multiple <i>Layout</i> children.  If labels are layed out in
 241 a simple grid pattern, only one layout is needed.  However, if labels are
 242 layed out in multiple grids, such as a running bond pattern, multiple
 243 <i>layout</i> tags can be used.  Note: a single label can always be treated as
 244 a grid of one.
 245 </p>
 246 <h3>Properties</h3>
 247 <table border="1">
 248   <tr>
 249     <td valign="top">nx</td>
 250     <td>Number of labels/cards across in the grid (horizontal)</td>
 251   </tr>
 252   <tr>
 253     <td valign="top">ny</td>
 254     <td>Number of labels/cards up and down in the grid (vertical)</td>
 255   </tr>
 256   <tr>
 257     <td valign="top">x0</td>
 258     <td>Distance from left edge of sheet to the left edge of the left
 259         column of cards/labels in the layout.</td>
 260   </tr>
 261   <tr>
 262     <td valign="top">y0</td>
 263     <td>Distance from the top edge of sheet to the top edge of
 264         the top row of labels/cards in the layout.</td>
 265   </tr>
 266   <tr>
 267     <td valign="top">dx</td>
 268     <td>Horizontal pitch of grid.</td>
 269   </tr>
 270   <tr>
 271     <td valign="top">dy</td>
 272     <td>Vertical pitch of grid.</td>
 273   </tr>
 274 </table>
 275 <br />
 276 <?img("glabels-template-layout.png","Layout illustration");?>
 277
 278 <h2>Alias Node</h2>
 279 <h3>Properties</h3>
 280 <table border="1">
 281   <tr>
 282     <td valign="top">name</td>
 283     <td>The name or part # of a product with the same size and layout
 284         characteristics.</td>
 285   </tr>
 286 </table>
 287
 288 <br />
 289
 290
 291 <?php gLabelsFooter(); ?>