A test of various structure and formatting styles.
Goal: A consistent structure that results in an easy to read document and that is appropriate for HTML5.
The structures of the attribute and property sections are completely different. They should be merged, taking the best part of each. In particular:
Current:
Attribute definitions:
<div class="adef-list">
<p><em>Attribute definitions:</em></p>
<dl>
<dt id="LinearGradientElementGradientUnitsAttribute"><span
class="adef">gradientUnits</span> = "<em>userSpaceOnUse</em> |
<em>objectBoundingBox</em>"</dt>
<dd>Defines the coordinate system for attributes <a>'x1'</a>,
y1'</a>, <a>'x2'</a> and <a>'y2'</a>.<br/>
If <span class="attr-value">gradientUnits="userSpaceOnUse"</span>,
<a>'x1'</a>, <a>'y1'</a>, <a>'x2'</a> and <a>'y2'</a>
represent values in the coordinate system that results
from taking the current user coordinate system in place at
the time when the gradient element is referenced (i.e.,
the user coordinate system for the element referencing the
gradient element via a <a>'fill'</a> or <a>'stroke'</a>
property) and then applying the transform specified by
attribute <a>'gradientTransform'</a>.<br/>
If <span class="attr-value">gradientUnits="objectBoundingBox"</span>,
the user coordinate system for attributes
<a>'x1'</a>, <a>'y1'</a>, <a>'x2'</a> and <a>'y2'</a> is
established using the bounding box of the element to which
the gradient is applied
(see <a href="coords.html#ObjectBoundingBox">Object
bounding box units</a>) and then applying the transform
specified by attribute <a>'gradientTransform'</a>.<br/>
When <span class="attr-value">gradientUnits="objectBoundingBox"</span>
and <a>'gradientTransform'</a> is the
identity matrix, the normal of the linear gradient is
perpendicular to the gradient vector in object bounding box
space (i.e., the abstract coordinate system where (0,0) is
at the top/left of the object bounding box and (1,1) is at
the bottom/right of the object bounding box). When the object's bounding
box is not square, the gradient normal which is initially perpendicular
to the gradient vector within object bounding box space may render
non-perpendicular relative to the gradient vector in user space. If the
gradient vector is parallel to one of the axes of the bounding box, the
gradient normal will remain perpendicular. This transformation is due to
application of the non-uniform scaling transformation from bounding box
space to user space.</br>
If attribute <a>'gradientUnits'</a> is not specified, then
the effect is as if a value of
<span class="attr-value">'objectBoundingBox'</span> were
specified.<br/>
<span class="anim-target"><a href="animate.html#Animatable">Animatable</a>:
yes.</span></dd>
</dl>
</div>
Problems:
Suggested structure
Defines the coordinate system for attributes 'x1', 'y1', 'x2' and 'y2'.
If gradientUnits="userSpaceOnUse", 'x1', 'y1', 'x2' and 'y2' represent values in the coordinate system that results from taking the current user coordinate system in place at the time when the gradient element is referenced (i.e., the user coordinate system for the element referencing the gradient element via a 'fill' or 'stroke' property) and then applying the transform specified by attribute 'gradientTransform'.
If gradientUnits="objectBoundingBox", the user coordinate system for attributes 'x1', 'y1', 'x2' and 'y2' is established using the bounding box of the element to which the gradient is applied (see Object bounding box units) and then applying the transform specified by attribute 'gradientTransform'.
When gradientUnits="objectBoundingBox" and 'gradientTransform' is the identity matrix, the normal of the linear gradient is perpendicular to the gradient vector in object bounding box space (i.e., the abstract coordinate system where (0,0) is at the top/left of the object bounding box and (1,1) is at the bottom/right of the object bounding box). When the object's bounding box is not square, the gradient normal which is initially perpendicular to the gradient vector within object bounding box space may render non-perpendicular relative to the gradient vector in user space. If the gradient vector is parallel to one of the axes of the bounding box, the gradient normal will remain perpendicular. This transformation is due to application of the non-uniform scaling transformation from bounding box space to user space.
<h3>Attributes:</h3>
<dl class="adef-list">
<dt id="LinearGradientElementGradientUnitsAttribute"><span class="propdef-title attr-name">gradientUnits</span></dt>
<dd>
<p>
Defines the coordinate system for attributes <a>'x1'</a>,
<a>'y1'</a>, <a>'x2'</a> and <a>'y2'</a>.
</p>
<dl class="propdef_new">
<dt>Value</dt> <dd>userSpaceOnUse | objectBoundingBox</dd>
<dt>Initial</dt> <dd>objectBoundingBox</dd>
<dt><a>Animatable</a></dt> <dd>yes</dd>
</dl>
<dl class="prop-value">
<dt>userSpaceOnUse</dt>
<dd>
<p>
If <span class="attr-value">gradientUnits="userSpaceOnUse"</span>,
<a>'x1'</a>, <a>'y1'</a>, <a>'x2'</a> and <a>'y2'</a>
represent values in the coordinate system that results
from taking the current user coordinate system in place at
the time when the gradient element is referenced (i.e.,
the user coordinate system for the element referencing the
gradient element via a <a>'fill'</a> or <a>'stroke'</a>
property) and then applying the transform specified by
attribute <a>'gradientTransform'</a>.
</p>
</dd>
<dt>objectBoundingBox</dt>
<dd>
<p>
If <span class="attr-value">gradientUnits="objectBoundingBox"</span>,
the user coordinate system for attributes
<a>'x1'</a>, <a>'y1'</a>, <a>'x2'</a> and <a>'y2'</a> is
established using the bounding box of the element to which
the gradient is applied
(see <a href="coords.html#ObjectBoundingBox">Object
bounding box units</a>) and then applying the transform
specified by attribute <a>'gradientTransform'</a>.
</p>
<p>
When <span class="attr-value">gradientUnits="objectBoundingBox"</span>
and <a>'gradientTransform'</a> is the
identity matrix, the normal of the linear gradient is
perpendicular to the gradient vector in object bounding box
space (i.e., the abstract coordinate system where (0,0) is
at the top/left of the object bounding box and (1,1) is at
the bottom/right of the object bounding box). When the object's bounding
box is not square, the gradient normal which is initially perpendicular
to the gradient vector within object bounding box space may render
non-perpendicular relative to the gradient vector in user space. If the
gradient vector is parallel to one of the axes of the bounding box, the
gradient normal will remain perpendicular. This transformation is due to
application of the non-uniform scaling transformation from bounding box
space to user space.
</p>
</dd>
</dd>
<dt id="LinearGradientElementGradientTransformAttribute"><span class="propdef-title attr-name">gradientTransform</span></dt>
<dd>
...
</dd>
</dl>
Current:
Paragraph of explanation.
| Value: | <opacity-value> | inherit |
| Initial: | 1 |
| Applies to: | 'stop' elements |
| Inherited: | no |
| Percentages: | N/A |
| Media: | visual |
| Animatable: | yes |
<p>
Paragraph of explanation.
</p>
<div class="propdef">
<dl>
<dt id="StopOpacityProperty"><span class="propdef-title prop-name">'stop-opacity'</span></dt>
<dd>
<table summary="stop-opacity property" class="propinfo"
cellspacing="0" cellpadding="0">
<tr valign="baseline">
<td><em>Value:</em> </td>
<td><opacity-value> | <a class="noxref"
href="http://www.w3.org/TR/2008/REC-CSS2-20080411/cascade.html#value-def-inherit">
<span
class="value-inst-inherit noxref">inherit</span></a></td>
</tr>
<tr valign="baseline">
<td><em>Initial:</em> </td>
<td>1</td>
</tr>
<tr valign="baseline">
<td><em>Applies to:</em> </td>
<td><a>'stop'</a> elements</td>
</tr>
<tr valign="baseline">
<td><em>Inherited:</em> </td>
<td>no</td>
</tr>
<tr valign="baseline">
<td><em>Percentages:</em> </td>
<td>N/A</td>
</tr>
<tr valign="baseline">
<td><em>Media:</em> </td>
<td>visual</td>
</tr>
<tr valign="baseline">
<td><em><a
href="animate.html#Animatable">Animatable</a>:</em> </td>
<td>yes</td>
</tr>
</table>
</dd>
</dl>
</div>
<dl>
<dt><span class="prop-value"><opacity-value></span></dt>
<dd>The uniform opacity setting to be applied across an ...</dd>
</dl>
Problems:
Suggested structure:
Paragraph of explanation.
<h3>Properties:</h3>
<dl class="pdef-list">
<dt id="StopOpacityProperty"><span class="propdef-title prop-name">'stop-opacity'</span></dt>
<dd>
<p>
Paragraph of explanation.
</p>
<dl class="propdef">
<dt>Value</dt> <dd><opacity-value> | <a class="noxref">inherit</a></dd>
<dt>Initial</dt> <dd>1</dd>
<dt>Applies to</dt> <dd><a>'stop'</a> elements</dd>
<dt>Inherited</dt> <dd>no</dd>
<dt>Percentages</dt> <dd>N/A</dd>
<dt>Media</dt> <dd>visual</dd>
<dt><a>Animatable</a></dt> <dd>yes</dd>
</dl>
<dl class="prop-value">
<dt><opacity-value></dt>
<dd>See <opacity-value> in ....</dd>
</dl>
</dd>
</dl>
Here is what some other specifications do. Most other specifications are much simpler, often just a single chapter or section. They can afford to be more verbose.
CSS3 Fonts uses tables for properties, first row is name. It uses dl for property values.
| Name: | font-family |
| Value: | [[ <family-name> | <generic-family> ] [, <family-name> | <generic-family>]* ] | inherit |
| Initial: | depends on user agent |
| Applies to: | all elements |
| Inherited: | yes |
| Percentages: | N/A |
| Media: | visual |
| Computed value: | as specified |
CSS3 Transforms uses tables for properties, first row is name. It also uses <dl> for property values.
transform’ Property A two-dimensional transformation is applied to the coordinate system an
element renders in through the ‘transform’
property. This property contains a list of transform functions. The final
transformation value for a coordinate system is obtained by converting
each function in the list to its corresponding matrix (either defined in
this specification or by reference to the SVG specification), then
multiplying the matrices.
| Name: | transform |
| Value: | none | <transform-function> [ <transform-function> ]* |
| Initial: | none |
| Applies to: | block-level and atomic inline-level elements |
| Inherited: | no |
| Percentages: | refer to the size of the element's border box |
| Media: | visual |
| Computed value: | Same as specified value. |