Launchpad itself

Bug #175482
Comment #3

Comment 3 for bug 175482

Revision history for this message

Leonard Richardson (leonardr) wrote on 2007-12-20:

Hopefully this little essay will clear things up. I've found a few errors, most of them stemming from incorrect use of the "alternate" relationship between links.

= Feeds =

There are three URLs mentioned in the interface. The only problem here
is that "alternate_url" is used incorrectly.

site_url: Only used internally as a root address. Shows up indirectly
as the root of the URL to the icon.

url: The URL to the feed resource itself. So for:

http://feeds.launchpad.net/ubuntu/announcements.atom

the url would be:

http://feeds.launchpad.net/ubuntu/announcements.atom

and in the feed document I expect to see:

which is correct.

alternate_url: The URL to a resource that is the human-readable
equivalent of the feed. So for:

http://feeds.launchpad.net/ubuntu/announcements.atom

the alternate_url would be:

http://launchpad.net/ubuntu/+announcements

Both those URLs are in some sense "the same thing": the list of announcments
for Ubuntu. In http://launchpad.net/ubuntu/+announcements we see this
markup:

Similarly, in http://feeds.launchpad.net/ubuntu/announcements.atom
I expect to see this markup:

Instead I see this, which is wrong, and probably causing some
confusion.

The Ubuntu project is not 'the same thing' as the list of Ubuntu
announcements. This would be acceptable (if suboptimal) if
https://launchpad.net/ubuntu were the only place you could go to see
Ubuntu announcements, but fortunately we have
https://launchpad.net/ubuntu/+announcements. The alternate_url should
be changed.

= Entries =

You've got one URL here, link_alternate, which is used
incorrectly. There are also two other URLs you could use here, one of
which (link_via) will do what you're currently using link_alternate
for.

link_self (NEW): This isn't present but I thought I'd mention it. This
is the link to the Atom entry itself. It's analogous to the "url"
you've defined for a feed. If it were present, it look like this in
the Atom feed at
https://feeds.launchpad.net/ubuntu/announcements.atom:

It's not present because you don't give individual announcements
their own URLs. We're going to start doing something like this for
web services, but you don't have to.

link_alternate: Analogous to the feed's alternate_url. Currently the
feed's alternate_url is wrong and this is wrong in an analogous way.

This is the URL to a different representation of 'the same thing' as
this entry. Right now it looks like this:

This is wrong; http://www.ubuntu.com/news/macedonia-school-computers
is not 'the same thing' as the second entry in the Ubuntu
announcements feed. Obviously the other couldn't exist without the
one, but they're not 'the same'. For instance,
http://www.ubuntu.com/news/macedonia-school-computers was published
on 2007-11-20 and the feed entry that links to it was published on
2007-12-06. http://www.ubuntu.com/news/macedonia-school-computers
contains more information than the feed entry. And so on.

There is a URL that is 'the same thing' as that feed entry, and it's
http://launchpad.net/ubuntu/+announcement/2. That URL is an HTML
representation of the Launchpad announcement, and the feed entry is
an Atom representation of the same announcement. So I would expect
the Atom entry to say this:

link_via (NEW): OK, what about
http://www.ubuntu.com/news/macedonia-school-computers? You can
mention it in the body of the entry, but you can mention a lot of
links in the body of an entry and it would be nice to have some
structured way of saying "this link has a special relationship to
this entry". Fortunately, "alternate" is not the only possible
relationship between URLs. We can choose another relationship and use
it as the value of "rel" in a second <link> tag.

Looking at the web side of things, I see that the difference between
https://launchpad.net/ubuntu/+announcement/2 and
http://www.ubuntu.com/news/macedonia-school-computers is presented as
the difference between "Permalink" and "Read more...". This implies
that the external URL is the original source of the announcement. I
recommend using the relationship "via" for this. The Atom standard
says this about "via":

   The value "via" signifies that the IRI in the value of the href
   attribute identifies a resource that is the source of the
   information provided in the containing element.

So the Atom entry would look like this:

I recommend calling this link_via, by analogy to link_alternate.

id: Also, I think your entry IDs are wrong--not invalid but wrong
by analogy. Your entry IDs look like this:

tag:launchpad.net,2007-12-06:/+announcements/2

That /+announcements implies you're trying to make an analogy between
the tag and a URL on the real Launchpad site. But
https://launchpad.net/ubuntu/+announcements/2 doesn't work. It's
https://launchpad.net/ubuntu/+announcement/2. The current tag: URI is
valid because it doesn't need to mean anything, just be
self-consistent. But if you want to make an analogy between the tag:
URI and an http: URL (which is a good idea), you should use a valid
URL fragment.

Hopefully this little essay will clear things up. I've found a few errors, most of them stemming from incorrect use of the "alternate" relationship between links.

= Feeds =

There are three URLs mentioned in the interface. The only problem here
is that "alternate_url" is used incorrectly.

site_url: Only used internally as a root address. Shows up indirectly
as the root of the URL to the icon.

url: The URL to the feed resource itself. So for:

http://feeds.launchpad.net/ubuntu/announcements.atom

the url would be:

http://feeds.launchpad.net/ubuntu/announcements.atom

and in the feed document I expect to see:

which is correct.

alternate_url: The URL to a resource that is the human-readable
 equivalent of the feed. So for:

http://feeds.launchpad.net/ubuntu/announcements.atom

the alternate_url would be:

http://launchpad.net/ubuntu/+announcements

Both those URLs are in some sense "the same thing": the list of announcments
 for Ubuntu. In http://launchpad.net/ubuntu/+announcements we see this
 markup:

Similarly, in http://feeds.launchpad.net/ubuntu/announcements.atom
 I expect to see this markup:

Instead I see this, which is wrong, and probably causing some
 confusion.

The Ubuntu project is not 'the same thing' as the list of Ubuntu
 announcements. This would be acceptable (if suboptimal) if
 https://launchpad.net/ubuntu were the only place you could go to see
 Ubuntu announcements, but fortunately we have
 https://launchpad.net/ubuntu/+announcements. The alternate_url should
 be changed.

= Entries =

You've got one URL here, link_alternate, which is used
incorrectly. There are also two other URLs you could use here, one of
which (link_via) will do what you're currently using link_alternate
for.

link_self (NEW): This isn't present but I thought I'd mention it. This
 is the link to the Atom entry itself. It's analogous to the "url"
 you've defined for a feed. If it were present, it look like this in
 the Atom feed at
 https://feeds.launchpad.net/ubuntu/announcements.atom:

It's not present because you don't give individual announcements
 their own URLs. We're going to start doing something like this for
 web services, but you don't have to.

link_alternate: Analogous to the feed's alternate_url. Currently the
 feed's alternate_url is wrong and this is wrong in an analogous way.

This is the URL to a different representation of 'the same thing' as
 this entry. Right now it looks like this:

This is wrong; http://www.ubuntu.com/news/macedonia-school-computers
 is not 'the same thing' as the second entry in the Ubuntu
 announcements feed. Obviously the other couldn't exist without the
 one, but they're not 'the same'. For instance,
 http://www.ubuntu.com/news/macedonia-school-computers was published
 on 2007-11-20 and the feed entry that links to it was published on
 2007-12-06. http://www.ubuntu.com/news/macedonia-school-computers
 contains more information than the feed entry. And so on.

There is a URL that is 'the same thing' as that feed entry, and it's
 http://launchpad.net/ubuntu/+announcement/2. That URL is an HTML
 representation of the Launchpad announcement, and the feed entry is
 an Atom representation of the same announcement. So I would expect
 the Atom entry to say this:

link_via (NEW): OK, what about
 http://www.ubuntu.com/news/macedonia-school-computers? You can
 mention it in the body of the entry, but you can mention a lot of
 links in the body of an entry and it would be nice to have some
 structured way of saying "this link has a special relationship to
 this entry". Fortunately, "alternate" is not the only possible
 relationship between URLs. We can choose another relationship and use
 it as the value of "rel" in a second <link> tag.

Looking at the web side of things, I see that the difference between
 https://launchpad.net/ubuntu/+announcement/2 and
 http://www.ubuntu.com/news/macedonia-school-computers is presented as
 the difference between "Permalink" and "Read more...". This implies
 that the external URL is the original source of the announcement. I
 recommend using the relationship "via" for this. The Atom standard
 says this about "via":

The value "via" signifies that the IRI in the value of the href
   attribute identifies a resource that is the source of the
   information provided in the containing element.

So the Atom entry would look like this:

I recommend calling this link_via, by analogy to link_alternate.

id: Also, I think your entry IDs are wrong--not invalid but wrong
 by analogy. Your entry IDs look like this:

tag:launchpad.net,2007-12-06:/+announcements/2

That /+announcements implies you're trying to make an analogy between
 the tag and a URL on the real Launchpad site. But
 https://launchpad.net/ubuntu/+announcements/2 doesn't work. It's
 https://launchpad.net/ubuntu/+announcement/2. The current tag: URI is
 valid because it doesn't need to mean anything, just be
 self-consistent. But if you want to make an analogy between the tag:
 URI and an http: URL (which is a good idea), you should use a valid
 URL fragment.