Hi, Simon-
Thanks for the comments, replies inline...
Simon Pieters wrote (on 11/27/09 2:42 AM):
On Fri, 27 Nov 2009 00:47:42 +0100, Doug Schepers <schep...@w3.org> wrote:
* 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.
That was my original approach, and how I currently do this in DOM3
Events, but upon reading Gregory's comments, I thought it would be
better for accessibility to use <em>. It does make sense to do so,
since the passages are being emphasized, but I could go either way. I'd
like to hear what people who read specs using a screen-reader say.
* 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: "?
I looked over a few specs, and that doesn't currently seem to be what's
done in practice (usually specs say "For example," or "As an example,"),
and "Example:" strikes me as particularly stilted. I don't feel too
strongly about it, though, and if others agree with you, I'm fine with
adopting that.
Isn't To Do redundant with Issue?
To Do is a little more specific than issue. Issue implies a problem of
some sort, while To Do indicates that the editor wants the reader to
know that something needs to go in that section, but hasn't gotten
around to it yet. For example, an editor might use To Do as a
placeholder for a diagram or example that clarifies the existing prose,
or for an empty section that just has a heading.
Is it intended that they use the same class name?
Yes, that's why it's a subcategory of Issue.
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.
An @id on a <var> seems useful (though not always), but I agree about
cross-references... I didn't mean to imply that.
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.
I'm not sure where you got the idea that I recommend every <p> gets an
id. I'll try to clarify that.
Having
id=""s on headings and definitions goes a long way. Notes, warnings,
issues and examples are reasonable candidates.
Yes, these are the most important ones.
Personally I'd prefer <dfn>s non-italic and bold (possibly <dt><dfn>
italic and bold), and xrefs as non-italic link-looking.
Okay, I'll keep a straw poll running on this bikeshed. I'm not married
to the current style of any of this, and I hope we can get a designer to
make it look like it wasn't designed by a geek (which, surprise!, it
was). Italics can be annoying for term references, I agree, but I would
like something to set them apart from normal links.
The Markup terms (should be called something else since <code> isn't
just used for markup)
Suggestions? (Note that I'm not saying <code> is only used for marking
up markup... just that markup should use that.)
has classes for elements and properties, but this
doesn't cover the various kinds of concepts that specs would like to use
<code> for.
This document is not trying to solve every case, just the major ones;
too many rules, and it will be too complicated to get adopted. If you
provide a list of things you think are missing, I'll consider those, too.
I'd suggest having lone <code> for elements, properties, and
everything else that doesn't have a fancy style,
I definitely want to distinguish between element names, and attributes
and properties names.
and <code class="value"> and <code class="string">
for the blueish background.
I'm drawing a blank where class="string" would be used... can you clarify?
<var> is misplaced and has the wrong style since variables aren't
necessarily code. For example, it's common for algorithms to use variables.
It's under "Code and Related Technical Terms"... a variable in an
algorithm is still a technical term. However, if you can think of a
better heading, I'll consider that.
Regards-
-Doug Schepers
W3C Team Contact, SVG and WebApps WGs
