Skip to content

Commit 06675f8

Browse files
j-evinsj-evins
authored
Create template style guide and minor updates to templates and docs (#314)
* Add style guide for creating product template submissions. * Some updates to TODO.md. (#270) * Remove Meta nodes with deprecated product_url attributes.
1 parent 226841f commit 06675f8

19 files changed

+167
-876
lines changed

‎docs/CONTRIBUTING.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ How To Contribute to gLabels
2626

2727
### Would you like to submit new product templates?
2828

29-
* Before submitting, please read [PRODUCT-TEMPLATES.md](PRODUCT-TEMPLATES.md) located in this directory.
29+
* Before submitting, please read [PRODUCT-TEMPLATES.md](PRODUCT-TEMPLATES.md) and [TEMPLATE-STYLE.md](TEMPLATE-STYLE.md) located in this directory.
3030

3131
* [Open an issue](https://github.com/j-evins/glabels-qt/issues/new) and attach your completed product template file(s).
3232

‎docs/PRODUCT-TEMPLATES.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
Manually Creating Product Templates
22
===================================
33

4-
This document is a reference for manually creating *gLabels* product templates.
4+
This document is a reference for manually creating *gLabels* product templates. See
5+
[TEMPLATE-STYLE.md](TEMPLATE-STYLE.md) located in this directory for style guidelines
6+
for product template submissions.
57

68
*gLabels* searches for templates in several locations as described here:</p>
79

@@ -83,7 +85,7 @@ Property | Type | Description
8385
*_description* | string | Translatable description of stationery product. Used in predefined labels instead of description.
8486
*width* | distance | Page width. Only valid if `size="other"` or `size="roll"`.
8587
*height* | distance | Page height. Only valid if `size="other"`. Value is ignored if `size="roll"`.
86-
*equiv* | string | 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.
88+
*equiv* | string | 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 *part* from the other template. This equiv property must refer to a previously defined template - *gLabels* does not currently support forward references.
8789

8890
### Guidelines for Creating Product Descriptions
8991

‎docs/TEMPLATE-STYLE.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
gLabels Product Template Style Guide
2+
====================================
3+
4+
This file describes the prefered style for product template submissions. See
5+
[PRODUCT-TEMPLATES.md](PRODUCT-TEMPLATES.md) located in this directory for detailed
6+
systax documentation.
7+
8+
9+
Organization
10+
------------
11+
12+
Template files are located in the [templates](../templates/) directory. The following
13+
is the naming convention for these files:
14+
15+
<pre><i>brand</i>-<i>class</i>-templates.xml</pre>
16+
17+
Where *brand* is the lowercase brand name, and *class* is the media size class (currently
18+
`iso`, `us`, and `other`).
19+
20+
Templates should be sorted in [natural order](https://en.wikipedia.org/wiki/Natural_sort_order)
21+
by part number within each file. An exception to this rule is to group equivalent templates
22+
directly below their referenced template. For example:
23+
24+
```xml
25+
<Template brand="Avery" part="5126" size="US-Letter" _description="Shipping labels">
26+
<Meta category="label"/>
27+
<Meta category="rectangle-label"/>
28+
<Meta category="mail"/>
29+
<Label-rectangle id="0" width="8.5in" height="5.5in" round="0in" x_waste="0in" y_waste="0in">
30+
<Markup-margin size="9pt"/>
31+
<Layout nx="1" ny="2" x0="0in" y0="0in" dx="0in" dy="5.5in"/>
32+
</Label-rectangle>
33+
</Template>
34+
35+
<Template brand="Avery" part="5526" equiv="5126"/>
36+
<Template brand="Avery" part="8126" equiv="5126"/>
37+
<Template brand="Avery" part="15516" equiv="5126"/>
38+
<Template brand="Avery" part="18126" equiv="5126"/>
39+
40+
41+
<Template brand="Avery" part="5159" size="US-Letter" _description="Address labels">...
42+
```
43+
44+
When creating a new template file, it must be added to the variable template_files in
45+
the [CMakeLists.txt](../templates/CMakeLists.txt) file in this same directory.
46+
47+
48+
*Template* Node Attributes
49+
--------------------------
50+
51+
### *brand* Attribute
52+
53+
This is the brand name or manufacturer of the product. It must match one of the vendors
54+
in the [vendors.xml](../templates/vendors.xml) file. Add a new vendor line if it does not
55+
currently exist.
56+
57+
58+
### *part* Attribute
59+
60+
This is the actual part number of the product. This is usually a short set of numbers and/or
61+
letters. This is not a description or name of the product. The following are examples
62+
of part numbers:
63+
64+
- `5160`
65+
- `WL-102`
66+
- `J8435B`
67+
68+
Sometimes a product includes multiple label types, either as separate sheets or different
69+
types of labels on the same sheet. In these cases, providing a short suffix to part number
70+
is acceptable. For example:
71+
72+
- `3274.1`, `3274.2`, and `3274.3`
73+
- `5931-Disc`, and `5931-Spine`
74+
75+
76+
### *_description* Attribute
77+
78+
- Descriptions should be short. They should describe what the product is in very simple terms
79+
without being too detailed. They should not describe details such as size, quantity, layout,
80+
color, or material. The description should not include brand or part number information.
81+
Size, quantity, layout, brand, and part number are described by other elements of the
82+
template - do not repeat them in the description.
83+
84+
- If at all possible, try to reuse descriptions from other templates (this keeps the
85+
number of unique strings that need translation to a minimum).
86+
87+
- Don't repeat the brand or part number in the description.
88+
89+
- Only capitalize the first word of the description.
90+
91+
The following are good bad descriptions:
92+
93+
| description | Good/Bad | Notes |
94+
|:-------------------------|:--------:|:----------------------------------------------|
95+
| `Address labels` | ✅ | |
96+
| `Address Labels` | ❌ | Capitalized second word of description. |
97+
| `Business cards` | ✅ | |
98+
| `Multipurpose labels` | ✅ | |
99+
| `CD/DVD labels` | ✅ | |
100+
| `19mm x 30mm labels` | ❌ | Don't include size information. |
101+
| `Labels 15 per sheet` | ❌ | Don't include layout or quantity information. |
102+
| `Dymo continuous labels` | ❌ | Don't include brand or part number. |
103+
104+
105+
106+
*Meta* Node Attributes
107+
----------------------
108+
109+
### *category* Attribute
110+
111+
- All templates should include all appropriate `<Meta category=...` nodes.
112+
- Categories must match one of the existing categories in the [categories.xml](../templates/categories.xml) file. Do not add new categories!
113+
- All templates should include either a `<Meta category="label"/>` or `<Meta category="card"/>` node.
114+
115+
116+
### *product_url* Attribute
117+
118+
Unfortunately, manufacturer websites are constantly being updated and rearranged, rendering such deep URLs obsolete very quickly. Therefore,
119+
use of this attribute is deprecated.
120+

‎docs/TODO.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ To Do List for gLabels 4.0 -- 2019-10-07
3939

4040

4141

42-
To Do List for post gLabels 4.0 -- 2019-03-17
42+
To Do List for post gLabels 4.0 -- 2026-02-18
4343
=============================================
4444

4545
- [ ] Create a "built-in" merge source
@@ -71,4 +71,14 @@ To Do List for post gLabels 4.0 -- 2019-03-17
7171
The current built-in fixed margin seems to confuse people when dealing with
7272
different horizontal and vertical alignments.
7373

74+
- [ ] Add support for arbitrary DPI when defining templates. Some label
75+
printers use native units in their label specifications (e.g. pins, pixels, etc.)
76+
This would look something like this
7477

78+
`... dpi="300" ... width="525d" height="350d" ...`
79+
80+
These would be converted to model::Distance when parsing.
81+
82+
- [ ] Resurrect the evolution and vcard backends. This would be optional based
83+
on availability.
84+

‎templates/avery-iso-templates.xml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,6 @@
6161
<Template brand="Avery" part="L4785" size="A4" _description="Name badge labels">
6262
<Meta category="label"/>
6363
<Meta category="rectangle-label"/>
64-
<Meta product_url="http://www.avery.co.uk/avery/en_gb/Products/Naming/Self-Adhesive-Name-Badges/White-self-adhesive-name-badges_L4785_20.htm"/>
6564
<Label-rectangle id="0" width="80mm" height="50mm" round="4mm" x_waste="7.5mm" y_waste="2.5mm">
6665
<Markup-margin size="1mm"/>
6766
<Layout nx="2" ny="5" x0="18mm" y0="13mm" dx="95mm" dy="55mm"/>

0 commit comments

Comments
 (0)