[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.
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.
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:
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.
<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.
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.