Super all-comprehensive specs/overview page

[Brad Fitzpatrick]

On Mon, 27 Jun 2005, Paul Crowley wrote:

> Fantastic!  That must have been hard work, Brad, that's great!

BML made it much easier than it'd seem at first glance.  I defined a bunch
of document-local templates to simplify it.

> We should probably refer to "simple mode" or "stupid mode" or "stateless
> mode" rather than "dumb mode" in the protocol specs.  "dumb" strictly
> means without the power of speech, and of course in that sense there are
> many intelligent dumb people.  It could be argued that "dumb terminals"
> don't say anything, though they pass on the keystrokes of their
> operators, but "dumb consumers" are more talkative than the other sort.
>   You can accuse me of being PC if you like, but it's been bothering me
> for a bit.  "stateless mode" has the advantage of being more descriptive
> too...

I agree "stateless" is a better word, and is arguably more PC, though you
must acknowledge that "dumb" has a more popular definition in recent times
than it once did (mute).  In fact, WordNet's top definition is:

  adj 1: slow to learn or understand; lacking intellectual acuity;

So I'd say between popular culture and some dictionaries catching up to
it, the PC argument can go away.

Then the question is whether "stateless" being a better word outweighs the
advantage of calling the stateless mode "dumb" in that it might deter
people to might otherwise be happy implementing only "stateless mode".
If a mildly naive programmer wrote a library, saw it work, and didn't
understand why "stateless" was so bad, he/she might release it happily.
But would that same person release it so happily knowing that it only
worked "in dumb mode"?

> It might be good to link to the output of my example generator, if
> that's still up to date with the protocol specs:
>
> http://hacks.ciphergoth.org/openid
>
> (Feel free to copy - actually I encourage it...)
>
> There are some "same as checkid_immediate" notes missing.

Will fix.

> A "lifetime" of 0 doesn't necessarily mean a signature mismatch; it
> could mean that the token has expired, or that there's some other problem.

Will fix.

> A slight preference for s[w/][with]g since this isn't natural to everyone.

Done.

> Having read to the end now, this is really great work!  I particularly
> like little touches like "if it's a GET request w/ no arguments, show a
> 200 text/html saying..." - not something we've discussed on the list,
> but something really worth getting right.  Thanks again!

Maybe not on the list, but you'd previously linked it from the Wiki.  It
was part of the error handling document.

- Brad