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
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user