Re: Proposed W3C Spec Conventions

On Fri, 27 Nov 2009 00:47:42 +0100, Doug Schepers <schepers@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

Received on Friday, 27 November 2009 07:44:51 UTC