On Thu, Oct 27, 2011 at 7:35 AM, Tavmjong Bah <tavmjong@free.fr> wrote:
> 0. Editing instructions need to be on a Wiki!!
>
> Including style information, best practices, etc. Took me a while
> to figure out how to update my HG checkout (pull followed by update).
For example, the CSSWG has a pretty thorough set of instructions for
how to edit a spec at
<http://wiki.csswg.org/spec#specification-editing>. (This was largely
driven by Tantek getting frustrated when he rejoined the group, and
spending a night writing the guide from input by Elika and others).
> 1. Change HTML headers to HTML5
>
> <?xml version="1.0" encoding="utf-8"?>
> <!DOCTYPE html>
> <html xmlns="http://www.w3.org/1999/xhtml">
>
> or
>
> <!DOCTYPE html>
> <html xmlns="http://www.w3.org/1999/xhtml">
> <meta charset="UTF-8"/>
Or just:
<!doctype html>
<html>
<meta charset=utf-8>
? (Yay unquoted attributes!)
> 3. Add Typographic conventions section?
>
> See:
> http://www.w3.org/TR/html5/introduction.html#typographic-conventions
>
> Pick better colors!! Yellow on green = yuck!
The CSSWG recently revamped its spec conventions based on the input of
one of our members who is a fairly skilled designer. It's undergoing
a trial run in several currently-edited specs like
<http://dev.w3.org/csswg/css3-values>.
I find it pretty attractive, personally. We could take the same or a
similar design for SVG specs.
> 4. Allow notes/comments/issues.
>
> For example, how do we note that the Java Language Bindings
> are not available as indicated in Appendix C?
This is also part of the CSSWG standard spec lexicon. Notes are
span/p/div with class=note, issues are span/p/div with class=issue,
examples are div with class=example. Each of these have a
representative appearance from our style sheet.
> 5. Set standards for figures:
>
> Recommended size.
> Common font-family, font-size, color scheme.
>
> Contrast the first figure in Chapter 13 with last figure
> in Chapter 11.
>
>
> 6. <edit:example> doesn't center caption under figure.
>
>
> 7. How to do figure captions?
The CSSWG also has a class=figure in our stylesheet that handles most
of these issues in a consistent way. That doesn't help with text
*within* an image, but as long as the image is, itself, SVG, one can
apply similar or otherwise consistent default styling.
In conclusion, I think just putting together a better stylesheet,
perhaps cribbed from the CSSWG's new stylesheet, would help make the
spec look a lot better. Where the SVG spec has unique design
requirements (for example, SVG's property definitions contain much
different information than CSS's), we can either extrapolate from
those styles or convince Divya (the CSSWG designer) to help out with
something new.
~TJ