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
