Subject: Re: Proposal: PaceSyntaxGuidelines

From: Mark Nottingham <[email-masked]>
Date: Fri, 9 Jul 2004 23:01:31 -0700

Can we hold off on this one until we've solidified what the format and 
protocol are first? Even then, I'm not sure it's a great idea to put 
purely stylistic naming conventions into the spec...

On Jun 27, 2004, at 9:51 AM, Asbjørn Ulsberg wrote:

>
> I've created PaceSyntaxGuidelines to get some specification text out 
> of the SyntaxGuidelines[1]:
>
> <url: http://www.intertwingly.net/wiki/pie/PaceSyntaxGuidelines>
>
> == Abstract ==
>
> [AsbjornUlsberg] Try to define a naming principle for the Atom syntax. 
> This supersedes the SyntaxGuidelines with a concrete specification 
> proposal. All future updates of the SyntaxGuidelines will happen here.
>
> == Status ==
>
> Open.
>
> == Rationale ==
>
> This pace tries to define some simple syntax guidelines, which should 
> apply to the Atom format -- both existing and future extensions of it. 
> Except where explicitly stated otherwise, all examples provided are 
> fictional: the elements and attributes given, may or may not exist in 
> the Atom Format syntax.
>
> == Proposal ==
>
> Replace (the currently empty) section 7 with the following:
>
> === 7 Guidelines for Extending Atom ===
>
> [This section is non-normative]. Extending Atom should follow these 
> syntax guidelines:
>
> ==== 7.1 Naming ====
>
> Names should be all lower-case, and if possible, one word only. If 
> names need to be two or more words, they should be separated with a 
> hyphen.
>
> Element Example:
> <create-entry />
>
> Attribute Example:
> <link service-type="..." />
>
> Enumerated Attribute or Element Values Example:
> <link rel="in-reply-to" ... />
>
> ==== 7.2 Common element usage ====
>
> The following actual elements should only be used in the ways 
> specified below.
>
> * link: Purposes of link elements are specified by a list of legal 
> values for link/@rel, and we are considering allowing extensions to 
> specify additional values. If the external resource being referred to 
> is not one that would make sense to present to the user as a clickable 
> link, some other element should be used instead. For example, link is 
> used to point to an alternate representation of the content of the 
> entry, to the next set of entries in a feed, etc. The link element is 
> not appropriate for pointing to things like a stylesheet for the feed, 
> an XSL template, etc., which are not intended for viewing by the user.
>
> ==== 7.3 Common attribute names ====
>
> The following attribute names should be used only in the ways 
> specified below. For attributes with other purposes, please choose 
> another name:
>
> * href: specifies the URI of something that will usually be 
> conceptually external to the entry, such as a PDF report on a website 
> to which the entry refers.
> * src: specifies the URI of some external entity intended to be 
> "imported into" the entry--something that is conceptually an integral 
> part of the entry. For example, <content src="..." />.
> * type: specifies a MIME type, such as "text/html" or "image/jpeg".
>
> ==== 7.4 How to embed content ====
>
> This section tries to explain how different data types of XML 
> documents should be embedded in Atom documents.
>
> ===== 7.4.1 Presentable content =====
>
> This is content that will be visually, audibly or in some other way, 
> presented to the user. It is not hidden behind the scenes, and it is 
> not insignificant for various presentations of an Atom entry. It is 
> valuable information the visual or audible representation needs or 
> somehow can utilize in the user interface.
>
> This content should be embedded in Atom as element values:
> <title>I am a visually or audibly presentable piece of text!</title>
>
> ===== 7.4.2 Non-presentable content =====
>
> This is content that will be completely hidden from the user. The user 
> should never have to need or care what the hidden content is, unless 
> he or she is doing debugging or some other developmental activities 
> with the document.
>
> This content should be embedded in Atom as attribute values:
> <link rel="alternate" />
>
> ===== 7.4.3 «Nice to know» content =====
>
> This is content that may or may not be presented to the user. Whether 
> it should be presented or not, is defined by the situation.
>
> This content can be in either elements or attributes.
>
> - Depending on the use-case. If a value will be presented to the user 
> in more than 50% of the use-cases, it should be embedded as an element 
> value. If it is presented to the user in less than 50% of the 
> use-cases, it should be embedded as an attribute value. The method of 
> embedding must be either as an element or attribute value; it cannot 
> be both.
>
> == Impacts ==
>
> This impacts how new Atom elements, attributes or enumerated values 
> are syntactically constructed. It may also impact the current 
> specification if it consists of anything breaking these guidelines. 
> The current finding is that the atom:url element and title attribute 
> breaks these guidelines to some extent.
>
> ____
> [1] <url: http://www.intertwingly.net/wiki/pie/SyntaxGuidelines>
>
> -- 
> Asbjørn Ulsberg         -=|=-        [email-masked]
> «He's a loathsome offensive brute, yet I can't look away»
>

--
Mark Nottingham     http://www.mnot.net/

---

From: Asbjørn Ulsberg <[email-masked]>
Date: Sun, 11 Jul 2004 00:56:41 +0200

On Fri, 9 Jul 2004 23:01:31 -0700, Mark Nottingham <[email-masked]> wrote:

> protocol are first?

No one is refusing anyone from creating a future pace to fix the  
potentially errors in this guideline. It's just the same as with the  
<link> discussion. We can't halt all movement just because we haven't  
figured out if <link rel="something" href="..."> is supposed to be  
<something href="..."> or not. We specify link constructs as being a  
<link> element until that discussion has reached some kind of consensus.

The same goes for this guideline. It fits the current format  
specification, and is bound to change when the format changes. I don't see  
what pausing the guidelines until the format is done would help anything.

> Even then, I'm not sure it's a great idea to put purely stylistic naming
> conventions into the spec...

Is it a problem that the guidelines are purely stylistic? There's nothing  
stopping anyone from creating a non-stylistic section about extending Atom.

---

From: Mark Nottingham <[email-masked]>
Date: Sat, 10 Jul 2004 16:42:13 -0700

On Jul 10, 2004, at 3:56 PM, Asbjørn Ulsberg wrote:

>> Can we hold off on this one until we've solidified what the format 
>> and protocol are first?
>
> specification, and is bound to change when the format changes. I don't 
> see what pausing the guidelines until the format is done would help 
> anything.

> Is it a problem that the guidelines are purely stylistic? There's 
> nothing stopping anyone from creating a non-stylistic section about 
> extending Atom.

Let me be clear. I'm not convinced that this is useful material to 
include in the specification. Furthermore,  attempting to improve it to 
sufficient quality will distract from the technical work we're 
undertaking now, and I don't see how this information actually improves 
the specification, the quality of Atom extensions, or the 
interoperability of implementations.

That isn't to say that it doesn't have its uses; it may be perfectly 
suitable material for inclusion in a primer, style guide or 
explanatory, non-WG article. It's just that it's extraneous to the 
specification itself. Does HTTP give style guides for naming new HTTP 
headers? HTML for extension attributes?

---

From: Asbjørn Ulsberg <[email-masked]>
Date: Mon, 12 Jul 2004 18:32:57 +0200

On Sat, 10 Jul 2004 16:42:13 -0700, Mark Nottingham <[email-masked]> wrote:

> include in the specification.

Ah, ok. Then let's see if that's the consensus, and if so, withdraw the  
proposal as it is, and repropose it as a non-normative appendix.

> Furthermore,  attempting to improve it to sufficient quality

Are you implying that the current quality sucks? ;)

> and I don't see how this information actually improves the
> specification, the quality of Atom extensions, or the

This guideline only makes the current Atom format and its extensions more  
uniform and consistent, that's all.

> Does HTTP give style guides for naming new HTTP headers?

Unfortunately; no.

> HTML for extension attributes?

Unfortunately; no.