Re: Proposed W3C Spec Conventions

Hi, fantasai-

Thanks for your feedback!

I've incorporated it, and created a new draft:
  http://www.w3.org/People/Schepers/spec-conventions.html

It probably still needs work (maybe a lot of work), but I'm interested 
to hear more feedback.  At this point, I'm wondering where the best list 
to process feedback is... is there a WG this should be handled by?

Replies inline...

fantasai wrote (on 11/24/09 6:35 PM):
>
> 1. Implementing this should not break styling on existing specs.

Right, I've now explained in more detail that this styling is in a 
separate supplementary stylesheet.


> 2. Defining Instance of Term has its own element, it's called <dfn>.
>    Please use that and not <span><code>. If you're defining a bit
>    of code, then <dfn><code> would be appropriate, otherwise not.

Well spotted.  I've corrected the examples.


> 3. For cross-referenced terms, if you think <a> is insufficient on
>    its own, then per HTML5, I believe <i> would be the appropriate
>    element to use there.

I'm not sure I follow you.  Why would <i> be appropriate for a 
reference?  I realize that HTML5 dresses it up to be more semantic, but 
that seems a bit contrived to me... <i> just means "italic", and while 
it sometimes was used in the way described in HTML (pre-5), it was often 
not.  I'd prefer to steer clear of that one unless it's made a bit clearer.


>Also, IMHO <code> should also be acceptable
>    in place of <i> when marking up bits of code rather than bits of
>    English.
>
> 4. Use <code> for your code markup, not <span>. That means attributes,
>    elements, values, etc.

IIRC, <code> wasn't consistently stylable, which is why the SVG WG used 
the more complicated nesting of <span 
class="attr"><code>foo</code></span>... if there aren't issues anymore, 
I'd be very happy to simplify the markup (which I have done in the new 
draft).

I actually made a typo by leaving them out in the example, which I've 
now corrected.


> Did you know!? <code> can accept the 'class' and 'id' attributes.

Yes, I sometimes do that, but didn't in the rough draft document since I 
was trying to show code in an example block.  I could make an example 
that uses just <code class="foo">, if you think it would help clarify.


Regards-
-Doug

Received on Wednesday, 25 November 2009 07:42:31 UTC