Citations

On Thu, 2011-05-05 at 01:16 -0400, Jeremy Bicha wrote:
> j1mc and I were talking about citing AskUbuntu. While it basically falls
> under the same license as the Gnome and Ubuntu docs, the site founder
> requires very specific attribution[1] which I don't think is well suited
> to the way our user docs work (but that's a different conversation). A
> bigger issue is that it doesn't look like Mallard has sufficient
> attribution support.
> 
> There are two already existing tags that could do this, <comment> and
> <credit> but credit seems like the better choice to me. I suggest adding
> a minimum of <link> and <title> to credit and maybe even <p>'s.

So I've been thinking about this quite a bit. Jim and I had
talked about the same thing on IRC before. We can certainly
discuss adding things to the content model of credit, but I
don't think it solves your immediate problem.

The credit element is informational. There's no requirements
on display. I don't want to start requiring that. I'm not
opposed to displaying credits in Yelp. I'm just opposed to
specifying that credits must be displayed. And if you need
to comply with a license, you need required behavior.

The comment element isn't right. It's for writers and editors
to leave notes for each other. The user never sees comments.

A note style could work. We wouldn't even have to put that in
the specification. (At least as a requirement. The spec does
*recommend* some note styles now.) But I think the most common
place to put legal mumbo-jumbo like this is at the bottom of
the page. And you can't put blocks down there if you've got
sections. I'd want to see these at the very very bottom, even
below automatic links. We don't have an element that can do
that right now.

What I'd proposed to Jim a while back is allowing the cite
element at the bottom of the page. This could work, but I've
thought of something I like better.

I propose we add a new element, colophon. It would be a formal
element: title (optional) and block content. It would only be
allowed as the last child of page. (Should we allow multiple?)
Its purpose is to hold text that should be displayed but which
is really not part of the main flow.

This is more general-purpose than a specialized element that is
strictly for citations. You might use it for feedback links. Or
thanks to your mom for all her support. Or pictures of kittens.
I don't know. Kittens are cute though.

Is the name "colophon" right? I think it's semantically right.
It serves the same purpose as a colophon in a book. It could be
confusing to people coming from DocBook, because the colophon
element in DocBook is "bigger", on par with chapters, whereas
this would be a small block container, on par with notes.

> By the way, I was able to stuff a link in <email> without validation
> failing so maybe the schema needs to sniff for basic email syntax there.

That might be worthwhile in a secondary Schematron rule. Mallard
intentionally allows all inline elements in any inline context.
It's important for internationalization. There could be a sort
of restricted inline set that doesn't include e.g. link. There's
always a trade-off between strictness and readability in schemas.
I erred on the side of readability.

Although email addresses are arguably no more text content than
URLs, and maybe credit emails should have just been attributes.
(I actually think they were in a very early version.)

(Personally, I tend to view the contents of credit as pseudo-RDF.
It allows external elements, and I generally recommend using that
in an RDF-like way.)

> And the other issue is that Yelp doesn't expose any of this info to end
> users who want to see it, even in the "editor-mode" that is not an
> editor. I think there needs to be a balance with cluttering the help but
> I don't believe we're really meeting the basic attribution requirements
> of CC-BY-SA either.
> 
> [1] http://blog.stackoverflow.com/2009/06/attribution-required/

As a side note, I think this is a really bad requirement on
how attribution should be provided. They can't retroactively
enforce this on any content added on their site before the
blog post was published. That's up to the contributors.

More importantly, the requirements are pretty hefty. They
remind me of the advertising clause in the old BSD license.
It's not so bad when you're just republishing near-verbatim
copy from one site. But imagine if you were remixing content
from 20 different sites, by 100 different authors, and they
all had this kind of attribution requirement. Your document
would have more attribution than content.

--
Shaun