Re: Proposed W3C Spec Conventions

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 <schepers@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

Received on Friday, 27 November 2009 08:29:33 UTC