On Fri, 27 Nov 2009 00:47:42 +0100, Doug Schepers <schep...@w3.org> wrote:
Hi, Gregory-
You expressed interest and provided feedback on Karl's typographic
conventions for specifications several months ago. We have picked up
that effort again, and I've tried to integrate all the feedback gathered
at that time.
In response to your comments, I've made the following changes:
* semantic tags such as <em>, <strong>, <dfn>, <var>, <code>, etc.
wherever possible, rather than <span> or <div>
I think inline notes, warnings and examples etc should use <span> rather
than <em>; the label is enough to notify the reader that it's different
from the surrounding prose, and you might want to use emphasis inside.
* named colors rather than numerical color codes
* prefaced notes, issues, and other categories with prose labels in the
document, rather than relying on text inserted by CSS; CSS insertions
are now used only for emphasis symbols
I presume editors will not fancy writing the labels by hand, so a tool
like Anolis will probably be used to insert them. Is there a reason why
inline examples don't have the label "Example: "?
Isn't To Do redundant with Issue? Is it intended that they use the same
class name?
Regarding id=""s, here I'll also assume that a tool like Anolis will
generate id=""s. However, I don't see any reason to id=""ify all content
that is covered by a category, as the document suggests; for instance I
wouldn't put an id="" on <var>s or xrefs. If every <p> gets an
auto-generated id="", then they're very likely to change as the spec is
being edited, which makes them not so useful to link to anyway. Having
id=""s on headings and definitions goes a long way. Notes, warnings,
issues and examples are reasonable candidates.
Personally I'd prefer <dfn>s non-italic and bold (possibly <dt><dfn>
italic and bold), and xrefs as non-italic link-looking.
The Markup terms (should be called something else since <code> isn't just
used for markup) has classes for elements and properties, but this doesn't
cover the various kinds of concepts that specs would like to use <code>
for. I'd suggest having lone <code> for elements, properties, and
everything else that doesn't have a fancy style, and <code class="value">
and <code class="string"> for the blueish background.
<var> is misplaced and has the wrong style since variables aren't
necessarily code. For example, it's common for algorithms to use variables.
If you would review the most recent draft of the documentation [1] and
the stylesheet [2] for accessibility concerns, I would appreciate it.
[1] http://www.w3.org/People/Schepers/spec-conventions.html
[2] http://www.w3.org/StyleSheets/TR/w3c-tr.css
--
Simon Pieters
Opera Software
