From d01059a9394ccd36623f0c51da82d215363a2542 Mon Sep 17 00:00:00 2001 From: Jim Evins Date: Mon, 27 Mar 2017 02:44:48 -0400 Subject: [PATCH] Started fleshing out PRODUCT-TEMPLATES.md. --- docs/PRODUCT-TEMPLATES.md | 566 ++++++++++++++++++++ docs/images/glabels-template-rect-label.png | Bin 0 -> 7924 bytes 2 files changed, 566 insertions(+) create mode 100644 docs/images/glabels-template-rect-label.png diff --git a/docs/PRODUCT-TEMPLATES.md b/docs/PRODUCT-TEMPLATES.md index 302b3d9..b56fe07 100644 --- a/docs/PRODUCT-TEMPLATES.md +++ b/docs/PRODUCT-TEMPLATES.md @@ -1,7 +1,573 @@ +Manually Creating Product Templates +=================================== + +This document is a reference for manually creating *gLabels* product templates. + +*gLabels* searches for templates in several locations as described here:

+ + +Location | Description +-----------------------------------------|----------------------------------------- +${prefix}/share/libglabels-qt/templates/ | Predefined templates distributed with glabels. +${XDG_CONFIG_HOME}/libglabels/templates | User defined templates created with the gLabels Template Designer. +${HOME}/.glabels | Manually created templates should be placed here. + + + +Assumptions/caveats +------------------- + +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). + +Distances can be expressed in units of *pt*, *in1*, *mm*, *cm*, or *pc*. For example: +`"1.0in"` or `"2.54cm"`. If no units are specified, computer points (*pt*) will +be assumed (1 *pt* = 1/72 *in* = 0.352778 *mm*). + + +Template Files +-------------- + +A template file contains a single *Glabels-templates* top-level node. + +```xml + + + + ...one or more templates... + + +``` + +An example template file containing a single *Template* node: + +```xml + + + + + + +``` + +*Template* Node +--------------- + +A *Template* node describes a single stationery product. It must contain exactly one instance of +a label node, either *Label-rectangle*, *Label-round*, *Label-ellipse* or *Label-cd*. + +Property | Description +---------------|------------ +*brand* | Brand or manufacturer of stationery product. E.g. "Avery". +*part* | Part number or name of stationery product. E.g. "8160". +*size* | Paper size. Must match an ID defined in *paper-sizes.xml* or "Other". E.g. "A4". +*description* | Description of stationery product. E.g, "Mailing Labels". +*_description* | Translatable description of stationery product. Used in predefined labels instead of description. +*width* | Page width. Only valid if `size="Other"`. +*height* | Page height. Only valid if `size="Other"`. +*equiv* | Equivalent part number. If this property is present, the template is a clone of another template of the same brand. The template will inherit all properties, except brand and name from the other template. This equiv property must refer to a previously defined template - *gLabels* does not currently support forward references. + ### Guidelines for Creating Product Descriptions +If creating templates to be distributed with *gLabels*, please use the following guidelines. + * If possible, Reuse the description of a similar product * Only capitalize the first word of description * Keep descriptions general * Do not repeat the part number or name in the description + +*Meta* Node +----------- + +A *Meta* node contains some additional information about the template. A *Template* node may contain zero +or more *Meta* nodes. Only one property should be defined per *Meta* node. + +Property | Description +--------------|------------ +*category* | A category for the template. A template can belong to multiple categories by simply adding multiple *Meta* nodes to the parent *Template* node. The category must match an existing ID defined in categories.xml. E.g. `category="media"` +*product_url* | A URL pointing to the vendor's webpage for the specific product, if available. + + +*Label-rectangle* Node +---------------------- + +A *Label-rectangle* node describes the dimensions of a single label or business card that is rectangular +in shape (may have rounded edges). + +Property | Description +--------------|------------ +*id* | Reserved for future use. Should always be 0. +*width* | Width of label or card. E.g. `width="29mm"` +*height* | Height of label or card. E.g. `height="100mm"` +*round* | Radius of corners. For items with square edges (business cards), the radius should be 0. +*x_waste* | Amount of horizontal waste (over-print) to allow. This is useful for minimizing alignment problems when using non-white backgrounds (e.g. images). +*y_waste* | Amount of vertical waste (over-print) to allow. + +![Label-rectangle properties](images/glabels-template-rect-label.png) + + + + + +
+ *Label-ellipse* Node + +

A *Label-ellipse* node describes the + dimensions of a single label or business card that is elliptic + in shape.

+ + + + + + + + + + + + + + + + + + + + + + + + +

Property

Description

*id*

Reserved for future use. Should always be 0.

*width*

Width of the ellipse

*height*

Height of the ellipse

*waste*

Amount of waste (over-print) to allow. This is useful + for minimizing alignment problems when using non-white + backgrounds (e.g. images).

+ + +
+ Label-ellipse parameters + +

*Label-ellipse* parameters

+ +
+ + +
+ + + + + + + + +
+ *Label-round* Node + +

A *Label-round* node describes the dimensions + of a simple round label (not a CD).

+ + + + + + + + + + + + + + + + + + + + +

Property

Description

*id*

Reserved for future use. Should always be 0.

*radius*

Radius (1/2 diameter) of label

*waste*

Amount of waste (over-print) to allow. This is useful + for minimizing alignment problems when using non-white + backgrounds (e.g. images).

+ + +
+ *Label-ellipse* parameters + +

*Label-ellipse* parameters

+ +
+ + +
+ + + + + + + + +
+ *Label-cd* Node + +

A *Label-cd* node describes the dimensions + of a CD, DVD, or business card CD.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Property

Description

*id*

Reserved for future use. Should always be 0.

*radius*

Outer radius of label

*hole*

Radius of concentric hole

*width*

If present, the label is clipped to the given width. + (Useful for "business card CDs").

*height*

If present, the label is clipped to the given height. + (Useful for "business card CDs").

*waste*

Amount of waste (over-print) to allow. This is useful + for minimizing alignment problems when using non-white + backgrounds (e.g. images).

+ + +
+ *Label-cd* parameters + +

CD label parameters

+ +
+ + +
+ + + + + + + + +
+ *Markup* Nodes + +

Templates may contain optional markup nodes. These nodes are used to describe + a simple set of markup lines that are visible in the glabels drawing canvas, but + not visible when printed. These lines can represent margins, fold lines, center lines, + special areas, or other helpful hints to the user of a template.

+ + + + + +
+ *Markup-margin* Node + +

A *Markup-margin* describes a margin along + all edges of a label.

+ + + + + + + + + + + + +

Property

Description

*size*

Size of the margin. I.e. the distance of the margin + line from the edge of the card/label.

+
+ + + + + + + + +
+ *Markup-line* Node + +

A *Markup-line* node describes a markup line.

+ + + + + + + + + + + + + + + + + + + + + + + + +

Property

Description

*x1*

x coordinate of 1st endpoint of the line segment.

*y1*

y coordinate of 1st endpoint of the line segment.

*x2*

x coordinate of 2nd endpoint of the line segment.

*y2*

y coordinate of 2nd endpoint of the line segment.

+
+ + + + + + + + +
+ *Markup-circle* Node + +

A *Markup-circle* describes a markup circle.

+ + + + + + + + + + + + + + + + + + + + +

Property

Description

*x0*

x coordinate of circle origin (center).

*y0*

y coordinate of circle origin (center).

*radius*

Radius of circle.

+
+ + + + + + + + +
+ *Markup-rect* Node + +

A *Markup-rect* describes a markup rectangle.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Property

Description

*x1*

x coordinate of upper left corner of rectangle.

*y1*

y coordinate of upper left corner of rectangle.

*w*

Width of rectangle.

*h*

Height of rectangle.

*r*

Radius of rounded corners of rectangle.

+
+ + + + + + + + +
+ *Markup-ellipse* Node + +

A *Markup-ellipse* describes a markup ellipse.

+ + + + + + + + + + + + + + + + + + + + + + + + +

Property

Description

*x1*

x coordinate of upper left corner of ellipse.

*y1*

y coordinate of upper left corner of ellipse.

*w*

Width of ellipse.

*h*

Height of ellipse.

+
+ + + + +
+ + + + + + + + +
+ *Layout* Node + +

A label node may contain multiple *Layout* + children. If labels are arranged in a simple grid pattern, only + one layout is needed. However, if labels are arranged in multiple + grids, such as a running bond pattern, multiple + *Layout* tags can be used.

+

A common example for multiple layouts is a sheet with three + CD labels:

+ + +
+ CD label sheet + +

CD label sheet

+ +
+ + +

The two labels on the left edge can be assigned to a grid, assuming we + can define the coordinates for the top left label and the distance to + the second label properly. The distance to the left edge is common to + these labels. The third one on the right edge has no common distance + values with the other ones, that's why we have to define a second layout, + with unique coordinates for the top left corner of that label.

+ + +

You can define multiple layouts only if the labels on the sheet + have the same shape. If your sheet contains different shapes, you have + to define each shape in another template separately. Future versions + of gLabels will probably be able to concatenate such sheets + with different shapes within a single template.

+ + + +

A single label can always be treated as a grid of one.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Property

Description

*nx*

Number of labels/cards across in the grid (horizontal)

*ny*

Number of labels/cards across in the grid (vertical)

*x0*

Distance from left edge of sheet to the left edge of + the left column of cards/labels in the layout.

*y0*

Distance from the top edge of sheet to the top edge of + the top row of labels/cards in the layout.

*dx*

Horizontal pitch of grid.

*dy*

Vertical pitch of grid.

+ + +
+ *Layout* parameters + +

Layout Parameters

+ +
+ + +
+ + + + + + + + + + + + + diff --git a/docs/images/glabels-template-rect-label.png b/docs/images/glabels-template-rect-label.png new file mode 100644 index 0000000000000000000000000000000000000000..e9d5b0304842b8a259853d79da79b63fc16cdbad GIT binary patch literal 7924 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