Re: Proposed W3C Spec Conventions

Hi Norm,

On Feb 19, 2010, at 16:42 , Norman Walsh wrote:
> Because I'm generating HTML from DocBook, I'm getting slightly
> different markup (which is not surprising). Here's what I get for an
> example, for example:
> 
> <div class="example-wrapper" id="ex1">
> <div class="title">Example&#160;1.&#160;A simple, linear
> XInclude/Validate pipeline</div>
> <div class="example">
> <div class="programlisting">
> <pre><code>
> &lt;p:declare-step xmlns:p="http://www.w3.org/ns/xproc"
>                name="xinclude-and-validate"
>                version="1.0"&gt;
> ...
> </code></pre>
> </div>
> </div>
> </div>
> </div>
> 
> I think I prefer my markup, the extra levels of wrapper provide
> flexibility (even if the class names are a bit long).
> 
> But the proposed conventions don't need the additional flexibility, so
> I can't decide if I should craft CSS that implements the same
> conventions using my markup, or change what I generate to match what
> the standard CSS expects.

I'm not against flexibility but looking at the above I wonder if there are cases in which you have more than one example per example wrapper? If not (and I'm inclined to think that that level of structuring is unnecessary), then I think it ought to be simplified so that any content apart from the title is the example. I also think that it can be further simplified by having class='programlisting' directly on the <pre> and dropping its parent. I understand that it likely requires more smarts in the XSLT generator, but without having looked at it I'm guessing that it's doable. One thing that could be neat would be if the source could specify the type of the "programlisting". In ReSpec I use that to provide content-specific syntax highlighting which can sometimes make examples easier to read.

There's one thing that I like a lot about your approach and which I think the conventions should cater to: example titles. It's not clear from the conventions whether the first item in a .example should always be <strong>Example:</strong> or if it could contain a title, and if it did whether that would work with the white-on-bright-orange text (and further, if that would work for inline examples — I tend to think it ought to be only for blocks).

In general, I'd like to propose that in the currently suggested conventions where we have inline / single-paragraph / block we drop the "single-paragraph" option. I find it to be a bit neither here nor there, and too many options makes the whole less readable. I think we'd be better off, for warnings, notes, examples, etc. with using inline for obviously short content that flows with a surrounding paragraph, and blocks for lengthier content that would feature and optional (but recommended) title.

-- 
Robin Berjon - http://berjon.com/

Received on Sunday, 21 February 2010 02:22:55 UTC