Re: HTML 5 Authoring Guidelines Proposal

Kornel Lesinski wrote:
> On Fri, 23 Nov 2007 01:56:19 -0000, Lachlan Hunt 
> <lachlan.hunt@lachy.id.au> wrote:
> 
>>    I thought it would be worthwhile getting started on this and 
>> presenting a proposal.  So I wrote up a brief proposal for HTML 5 
>> Authoring Guidelines and checked it into CVS.  At this stage, it's 
>> very rough draft and effectively just an outline of how it could be 
>> written.
> 
> I think it looks too much like the specification.

Yes, the style will be improved eventually.  Any assistance with this 
would be appreciated.

> Especially elements are introduced in the same manner: using laconic description of a few 
> technical properties. That's fine for the spec, but in tutorial I'd 
> prefer element properties described in prose and examples,

It's important to have that information available for quick reference in 
addition to longer prose that provides more detail.

> Another problem: not using full namespace declarations in examples may 
> lead authors to believe that XML/XHTML5 has "magic" prefixes for SVG and 
> XHTML. If you want to avoid repetition of namespace declarations, I 
> suggest choosing a prefix that clearly doesn't look like part of the 
> spec, e.g. <example-svg:circle> or <my-svg:circle> instead of <svg:circle>.

I want authors to be able to copy and paste as much as possible and in 
cases where small fragments are presented and expected to be 
incorporated into a larger document, I don't think it will be necessary 
to always repeat the namespace declarations.  However, in such cases, I 
would probably include a brief note about namespaces immediately after, 
linking to the explanation.

Anyway, we'll see how it works out.  If, after there actually are 
examples using namespace prefixes, that method doesn't work out well, it 
can be changed.

> Why use quotes for all attribute values in HTML examples?  AFAIK unquoted
> values are conformant and interoperable. Quotes on all attributes may 
> falsely suggest that HTML has same rules as XML in this regard and that 
> omitting quotes is deprecated/non-conformant (is it?).

Note that it says "Unless explicitly stated otherwise for a specific 
purpose".  I will explain all about quotes in the syntax section. 
However, it's useful to have a consistent style throughout the guide and 
encourage authors to be consistent in their own work.  Many people have 
expressed the desire to promote a common markup style and double quotes 
are clearly the most popular, so using that as the convention makes the 
most sense.

-- 
Lachlan Hunt - Opera Software
http://lachy.id.au/
http://www.opera.com/

Received on Friday, 23 November 2007 23:23:09 UTC