From: Jim Evins Date: Wed, 8 Dec 2010 03:54:08 +0000 (-0500) Subject: Cleanup of "Manually creating new templates" page. X-Git-Tag: glabels-2_3_1~69 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=81d3f3f11939e6feba33cfe6db56529e2ed7f2fd;p=glabels Cleanup of "Manually creating new templates" page. --- diff --git a/help/C/mancreate.page b/help/C/mancreate.page index 4e1a090a..cd2a57b0 100644 --- a/help/C/mancreate.page +++ b/help/C/mancreate.page @@ -23,60 +23,119 @@ - Manually creating new templates - -

Predefined templates are defined by XML files located in - either /usr/share/libglabels-3.0/templates/ or - /usr/local/share/libglabels-3.0/templates/, - depending on where glabels was installed. Glabels will - also search for user defined templates in the directory - ${HOME}/.config/libglabels/templates/. User - defined template files should be named with a - *.template extension. -

- -

The format for these files is defined in the DTD: - glabels-2.3.dtd. - (This DTD also describes other XML formats used by glabels.)

- -
- 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, - in, 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 - - + Manually creating new templates + + + + + + +

This page is a reference guide to manually creating gLabels templates. + gLabels templates are defined in simple XML files as described in the DTD: + glabels-2.3.dtd + (this DTD also describes other XML files used by gLabels).

+ +

Manually created template files should be placed in the ${HOME}/.glabels + and be named with a .template extension.

+ + +

gLabels searches for templates in several other locations as defined here:

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

Location

Description

${prefix}/share/libglabels-3.0/templates

Predefined templates distributed with gLabels.

+

${prefix} is usually /usr or /usr/local, + depending on where gLabels was installed.

${XDG_CONFIG_HOME}/libglabels/templates

User defined templates created with the gLabels Template Designer. + Do not put manually created templates in this directory.

+

If ${XDG_CONFIG_HOME} is not defined, it defaults to + ${HOME}/.config.

${HOME}/.glabels

User defined templates that have been created manually should be placed in this + directory. + Older versions of the gLabels Template Designer (prior to 3.0) + would also put templates in this directory.

+ + +

Completed template files can be sent to the + gLabels template + mailing list + for possible inclusion in future versions of gLabels.

+ + + + + + + + + +
+ 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, + in, 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 version="1.0"?> <Glabels-templates> - ...templates... - -</Glabels-templates> - -
+ ...templates... +</Glabels-templates> -
+ Example Template - + Example gLabels template file containing a single + Template node. + +<?xml version="1.0"?> +<Glabels-templates> + <Template brand="Avery" part="8160" size="US-Letter" description="Mailing Labels"> <Meta category="label"/> <Meta category="mail"/> @@ -86,515 +145,629 @@ <Layout nx="3" ny="10" x0="11.25pt" y0="36pt" dx="200pt" dy="72pt"/> </Label-rectangle> </Template> - -
- -
- <span its:translate="no">Template</span> Node - -

A Template node describes a single - stationery product. It must contain one instance of any type of Label node - (Label-rectangle, - Label-round, 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

Size of sheet. E.g., "US-Letter," "A4", ...

description

Description of stationery product. E.g, "Mailing Labels."

_description

Translatable description of stationery product. E.g, "Mailing Labels." - (Only useful for predefined templates)

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 -- - libglabels does not currently support forward references.

- -
- -
- <span its:translate="no">Meta</span> Node - -

A Meta node contains some additional - properties of that product. This node may appear more than once, with a - subnode each.

- - - - - - - - - - - - - - - - -

Subnode

Description

category

The category which this product is assigned to. The value - of this category is used by the gLabels' template chooser to filter the - view to display only mailing labels, or labels in common and suppress any other products - which the user don't want to find.

-

One product can be assigned to several categories. You may choose from the - following categories:

- -

label

 -

round-label

 -

elliptical-label

 -

square-label

 -

rectangle-label

 -

card

 -

business-card

 -

media

 -

mail

 -

foldable

 - -

If you have any ideas for new categories, please send your suggestions to the - developer's mailing list - of gLabels. -

-

product_url

This address points to the vendor's website. Ideally, - the link shows the URL of that certain product, if available.

- -
- -
- <span its:translate="no">Label-rectangle</span> 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/card

height

Heigth of label/card

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. This is useful - for minimizing alignment problems when using non-white - backgrounds (e.g. images).

- - -
- Label-rectangle parameters - -

Label-rectangle parameters

- -
- -
- -
- <span its:translate="no">Label-ellipse</span> 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

Heigth 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

- -
- -
- -
- <span its:translate="no">Label-round</span> 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

- -
- -
- -
- <span its:translate="no">Label-cd</span> 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

- -
- -
- -
- <span its:translate="no">Markup</span> 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.

+</Glabels-templates> + + +
+ + + + + + + + + +
+ <span its:translate="no">Template</span> Node + +

A Template node describes a single + stationery product. It must contain one instance of any type of Label node + (Label-rectangle, + Label-round, 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

Size of sheet. + E.g., "US-Letter", "A4", ... +

description

Description of stationery product. E.g, "Mailing Labels."

_description

Translatable description of stationery product. E.g, "Mailing Labels." + (Only useful for predefined templates)

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.

+ +
+ + + + + + + + +
+ <span its:translate="no">Meta</span> Node + +

A Meta node contains some additional + information about the template. A Template + node may contain zero or more Meta nodes.

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

Subnode

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. + Template categories are used by the gLabels New Label + Dialog to filter the results of template searches.

+ +

The value of this category must match a predefined category ID defined in + the file ${prefix}/libglabels-3.0/templates/categories.xml. + Currently defined category IDs include:

+ +

label

 +

round-label

 +

elliptical-label

 +

square-label

 +

rectangle-label

 +

card

 +

business-card

 +

media

 +

mail

 +

foldable

 + + + +

product_url

A URL pointing to the vendor's webpage for the specific product, if available.

+ +

Suggestions for additional categories can be sent to the + gLabels developer's + mailing list.

+

Product URLs may be of limited use, because they may not be permanent.

+ + +
+ + + + + + + + +
+ <span its:translate="no">Label-rectangle</span> 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/card

height

Heigth of label/card

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. This is useful + for minimizing alignment problems when using non-white + backgrounds (e.g. images).

+ + +
+ Label-rectangle parameters + +

Label-rectangle parameters

+ +
+ + +
+ + + + + + + + +
+ <span its:translate="no">Label-ellipse</span> 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

Heigth 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

+ +
+ + +
+ + + + + + + + +
+ <span its:translate="no">Label-round</span> 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

+ +
+ + +
+ + + + + + + + +
+ <span its:translate="no">Label-cd</span> 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

+ +
+ + +
+ + + + + + + + +
+ <span its:translate="no">Markup</span> 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.

+ + + + +
<span its:translate="no">Markup-margin</span> 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.

+

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.

+ + + + + + +
<span its:translate="no">Markup-line</span> 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 2st endpoint of the line segment.

y2

y coordinate of 2st endpoint of the line segment.

+

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 2st endpoint of the line segment.

y2

y coordinate of 2st endpoint of the line segment.

+ + + + + + +
<span its:translate="no">Markup-circle</span> 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.

+

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.

+ + + + + + +
<span its:translate="no">Markup-rect</span> 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.

+

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.

+ + + + + + +
<span its:translate="no">Markup-ellipse</span> 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.

-
- -
- -
- <span its:translate="no">Layout</span> 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. - Note: 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

- -
- +

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.

+ + + + +
+ + + + + + + + +
+ <span its:translate="no">Layout</span> 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 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

+ +
+ + +
+ + +