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.
This commit is contained in:
Jaye Evins
GitHub
@@ -26,7 +26,7 @@ How To Contribute to gLabels
|
||||
|
||||
### Would you like to submit new product templates?
|
||||
|
||||
* Before submitting, please read [PRODUCT-TEMPLATES.md](PRODUCT-TEMPLATES.md) located in this directory.
|
||||
* Before submitting, please read [PRODUCT-TEMPLATES.md](PRODUCT-TEMPLATES.md) and [TEMPLATE-STYLE.md](TEMPLATE-STYLE.md) located in this directory.
|
||||
|
||||
* [Open an issue](https://github.com/j-evins/glabels-qt/issues/new) and attach your completed product template file(s).
|
||||
|
||||
|
||||
@@ -1,7 +1,9 @@
|
||||
Manually Creating Product Templates
|
||||
===================================
|
||||
|
||||
This document is a reference for manually creating *gLabels* product templates.
|
||||
This document is a reference for manually creating *gLabels* product templates. See
|
||||
[TEMPLATE-STYLE.md](TEMPLATE-STYLE.md) located in this directory for style guidelines
|
||||
for product template submissions.
|
||||
|
||||
*gLabels* searches for templates in several locations as described here:</p>
|
||||
|
||||
@@ -83,7 +85,7 @@ Property | Type | Description
|
||||
*_description* | string | Translatable description of stationery product. Used in predefined labels instead of description.
|
||||
*width* | distance | Page width. Only valid if `size="other"` or `size="roll"`.
|
||||
*height* | distance | Page height. Only valid if `size="other"`. Value is ignored if `size="roll"`.
|
||||
*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.
|
||||
*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.
|
||||
|
||||
### Guidelines for Creating Product Descriptions
|
||||
|
||||
|
||||
@@ -0,0 +1,120 @@
|
||||
gLabels Product Template Style Guide
|
||||
====================================
|
||||
|
||||
This file describes the prefered style for product template submissions. See
|
||||
[PRODUCT-TEMPLATES.md](PRODUCT-TEMPLATES.md) located in this directory for detailed
|
||||
systax documentation.
|
||||
|
||||
|
||||
Organization
|
||||
------------
|
||||
|
||||
Template files are located in the [templates](../templates/) directory. The following
|
||||
is the naming convention for these files:
|
||||
|
||||
<pre><i>brand</i>-<i>class</i>-templates.xml</pre>
|
||||
|
||||
Where *brand* is the lowercase brand name, and *class* is the media size class (currently
|
||||
`iso`, `us`, and `other`).
|
||||
|
||||
Templates should be sorted in [natural order](https://en.wikipedia.org/wiki/Natural_sort_order)
|
||||
by part number within each file. An exception to this rule is to group equivalent templates
|
||||
directly below their referenced template. For example:
|
||||
|
||||
```xml
|
||||
<Template brand="Avery" part="5126" size="US-Letter" _description="Shipping labels">
|
||||
<Meta category="label"/>
|
||||
<Meta category="rectangle-label"/>
|
||||
<Meta category="mail"/>
|
||||
<Label-rectangle id="0" width="8.5in" height="5.5in" round="0in" x_waste="0in" y_waste="0in">
|
||||
<Markup-margin size="9pt"/>
|
||||
<Layout nx="1" ny="2" x0="0in" y0="0in" dx="0in" dy="5.5in"/>
|
||||
</Label-rectangle>
|
||||
</Template>
|
||||
|
||||
<Template brand="Avery" part="5526" equiv="5126"/>
|
||||
<Template brand="Avery" part="8126" equiv="5126"/>
|
||||
<Template brand="Avery" part="15516" equiv="5126"/>
|
||||
<Template brand="Avery" part="18126" equiv="5126"/>
|
||||
|
||||
|
||||
<Template brand="Avery" part="5159" size="US-Letter" _description="Address labels">...
|
||||
```
|
||||
|
||||
When creating a new template file, it must be added to the variable template_files in
|
||||
the [CMakeLists.txt](../templates/CMakeLists.txt) file in this same directory.
|
||||
|
||||
|
||||
*Template* Node Attributes
|
||||
--------------------------
|
||||
|
||||
### *brand* Attribute
|
||||
|
||||
This is the brand name or manufacturer of the product. It must match one of the vendors
|
||||
in the [vendors.xml](../templates/vendors.xml) file. Add a new vendor line if it does not
|
||||
currently exist.
|
||||
|
||||
|
||||
### *part* Attribute
|
||||
|
||||
This is the actual part number of the product. This is usually a short set of numbers and/or
|
||||
letters. This is not a description or name of the product. The following are examples
|
||||
of part numbers:
|
||||
|
||||
- `5160`
|
||||
- `WL-102`
|
||||
- `J8435B`
|
||||
|
||||
Sometimes a product includes multiple label types, either as separate sheets or different
|
||||
types of labels on the same sheet. In these cases, providing a short suffix to part number
|
||||
is acceptable. For example:
|
||||
|
||||
- `3274.1`, `3274.2`, and `3274.3`
|
||||
- `5931-Disc`, and `5931-Spine`
|
||||
|
||||
|
||||
### *_description* Attribute
|
||||
|
||||
- Descriptions should be short. They should describe what the product is in very simple terms
|
||||
without being too detailed. They should not describe details such as size, quantity, layout,
|
||||
color, or material. The description should not include brand or part number information.
|
||||
Size, quantity, layout, brand, and part number are described by other elements of the
|
||||
template - do not repeat them in the description.
|
||||
|
||||
- If at all possible, try to reuse descriptions from other templates (this keeps the
|
||||
number of unique strings that need translation to a minimum).
|
||||
|
||||
- Don't repeat the brand or part number in the description.
|
||||
|
||||
- Only capitalize the first word of the description.
|
||||
|
||||
The following are good bad descriptions:
|
||||
|
||||
| description | Good/Bad | Notes |
|
||||
|:-------------------------|:--------:|:----------------------------------------------|
|
||||
| `Address labels` | ✅ | |
|
||||
| `Address Labels` | ❌ | Capitalized second word of description. |
|
||||
| `Business cards` | ✅ | |
|
||||
| `Multipurpose labels` | ✅ | |
|
||||
| `CD/DVD labels` | ✅ | |
|
||||
| `19mm x 30mm labels` | ❌ | Don't include size information. |
|
||||
| `Labels 15 per sheet` | ❌ | Don't include layout or quantity information. |
|
||||
| `Dymo continuous labels` | ❌ | Don't include brand or part number. |
|
||||
|
||||
|
||||
|
||||
*Meta* Node Attributes
|
||||
----------------------
|
||||
|
||||
### *category* Attribute
|
||||
|
||||
- All templates should include all appropriate `<Meta category=...` nodes.
|
||||
- Categories must match one of the existing categories in the [categories.xml](../templates/categories.xml) file. Do not add new categories!
|
||||
- All templates should include either a `<Meta category="label"/>` or `<Meta category="card"/>` node.
|
||||
|
||||
|
||||
### *product_url* Attribute
|
||||
|
||||
Unfortunately, manufacturer websites are constantly being updated and rearranged, rendering such deep URLs obsolete very quickly. Therefore,
|
||||
use of this attribute is deprecated.
|
||||
|
||||
+11
-1
@@ -39,7 +39,7 @@ To Do List for gLabels 4.0 -- 2019-10-07
|
||||
|
||||
|
||||
|
||||
To Do List for post gLabels 4.0 -- 2019-03-17
|
||||
To Do List for post gLabels 4.0 -- 2026-02-18
|
||||
=============================================
|
||||
|
||||
- [ ] Create a "built-in" merge source
|
||||
@@ -71,4 +71,14 @@ To Do List for post gLabels 4.0 -- 2019-03-17
|
||||
The current built-in fixed margin seems to confuse people when dealing with
|
||||
different horizontal and vertical alignments.
|
||||
|
||||
- [ ] Add support for arbitrary DPI when defining templates. Some label
|
||||
printers use native units in their label specifications (e.g. pins, pixels, etc.)
|
||||
This would look something like this
|
||||
|
||||
`... dpi="300" ... width="525d" height="350d" ...`
|
||||
|
||||
These would be converted to model::Distance when parsing.
|
||||
|
||||
- [ ] Resurrect the evolution and vcard backends. This would be optional based
|
||||
on availability.
|
||||
|
||||
Reference in New Issue
Block a user