[uf-discuss] entry permalink in hatom

[Tantek Ç elik]

On 1/4/06 1:23 PM, "Scott Reynen" <scott at randomchaos.com> wrote:

> Tantek Çelik wrote:
> 
>> Copying it though violates the DRY principle and unnecessarily
>> introduces a
>> risk of introducing errors/changes from the spec.
> 
> Are we really applying the DRY principle to documentation?

To specification, in particular.


> Nobody  
> uses rel-bookmark because nobody knows about it because nobody reads
> W3C specs in their entirety.

Or certainly the 80% don't :)


> I think the benefits of explaining the
> elements of meaningful XHTML [1] clearly outweigh the risks of
> straying from the spec.  If we don't understand a section of the spec
> well enough to explain it to others, how can we expect to build
> microformats on top of XHTML?
>
> [1] http://tantek.com/presentations/2005/03/elementsofxhtml/

If you're talking about tutorials, then yes, you are absolutely correct,
the more the merrier, with each hopefully improving on those that came
before it.


>> We should not duplicate things from other specs, we should
>> reference them.
> 
> False dichotomy.  We can both reference them and further explain them
> within the contexts of microformats.

Yes.


>> Thus perhaps we need a required reading section where we at least
>> list:
>>  Specifications:
>>  - HTML 4.01: http://w3.org/tr/html401
>>  - XHTML 1.0: http://w3.org/tr/xhtml1
> 
> Those two specs are hundreds of pages long.  That's a hefty
> prerequisite to impose on someone who just wants to make their weblog
> markup a bit more semantic.

I should have been more clear.

We need a required reading section for anyone wishing to work on a new
microformat.

For users of course we want easier tools and documentation.  Hence the
creators and examples.


>> Alternatively, one might say that the use of rel="bookmark" for blog
>> permalinks is worthy of documenting as an explicit example, since
>> the HTML 4.01 spec makes no reference to blogs or permalinks.
> 
> I would lean this way, but I don't think this conversation is worth
> having until a rel-bookmark wiki page actually exists.  Right now
> we're discussing whether or not a hypothetical explanation of rel-
> bookmark is better than the W3C explanation.

An explanation is different from a specification.

I would welcome a tutorial on rel-bookmark on microformats.org -- let's just
be very clear that it is NOT a new microformat, nor would it be a
specification.

Perhaps we could call it:

 http://microformats.org/wiki/rel-bookmark-tutorial

Other suggestions for indicating that something is a explicitly an
informative tutorial rather than a specification (I'm not saying we have to
always append "-tutorial", but naming conventions tend to be useful,
especially when one could easily confuse a /wiki/rel-bookmark page as being
a specification since the URL looks like other /wiki/rel-* pages).

Thanks for the clarification Scott,

Tantek