Re: [boost] GIL - Generic Image Library Review - Begins October 5

From: Andy Little (andy_at_[hidden])
Date: 2006-10-07 11:52:43

"David Abrahams" <dave_at_[hidden]> wrote in message 
news:873ba0w7ck.fsf_at_pereiro.luannocracy.com...
> "Andy Little" <andy_at_[hidden]> writes:
>
>>>> http://permalink.gmane.org/gmane.comp.lib.boost.devel/144195
>>>>
>>>> para 5
>>>
>>> ? I don't see anything there that amounts to "specifically telling you
>>> not to use Concept docs."
>>
>> Concepts arent an established convention.
>
> Yes they certainly are.  Maybe you mean in-language concept support is
> not an established convention?
>
>> Read Doug Gregors post. They havent been finalised.
>
> I'm quite aware of that.
>
>> I knew exactly what you meant in that and other discussions.
>
> Apparently not.  If you're referring to this:
>
>  FWIW, once we have concept support in the language we will be using
>  pseudosignatures rather than valid expressions to express syntactic
>  constraints, so we can expect that to change.  In the meantime,
>  though, the things that can be expressed using established
>  conventions should be so expressed.
>
> what I meant was that, although there is a well-established convention
> for documenting concepts, it's very likely that the conventions for
> documenting concepts will change in the near future.  Then I go on to
> reiterate my general (not specific) position that established
> conventions should be used wherever applicable.
>
> This is *not* specifically telling you not to use proposed concept
> declaration syntax in documentation any more than it's specifically
> telling you not to insert emoticons into your concept tables.
>
> If you had specifically raised the topic of using the new proposed
> concept language syntax to do documentation, I would have said the
> following things about it, specifically (I did consider this issue, so
> I know what I was thinking):
>
>  1. It's an interesting idea
>
>  2. You'd have to write some very careful introductory material that
>     explains to people how to interpret it, or at least makes
>     reference to a particular proposal paper.
>
>  3. Don't forget to express semantic requirements, which don't have a
>     place in concept description syntax (I think that has changed in
>     more recent proposals)
>
>  4. Especially if you're not all that familiar with how to document
>     concepts, I think it would probably be a good idea to go with the
>     existing conventions, and only do something more adventurous once
>     you're very comfortable with the sorts of things that need to be
>     expressed in a concept specification.  For one thing, there are
>     lots more examples out there of the existing convention to work
>     from.
>
>  5. Anyone doing this instead of following the convention ought to
>     be able to supply a good reason for doing it.
>
> In other words, I wouldn't have rejected the idea out-of-hand, but I'd
> have asked you to justify your choice and suggested that you might
> want to hold off until you had more experience writing concepts.
>
>> Also I can say with a large amount of certainty that if I had
>> presented PQS for another review, and had used Concept
>> documentation, then it would be pointed out by you or others that I
>> had been specifically told not to do so.
>>
>> Now I shall sit back and watch the goalposts move as if by magic ...
>
> Thought experiment #1: is there possible outcome here -- other than me
> conceding that I "specifically told you" something I never said or
> meant to say -- that would convince you the goalposts aren't being
> moved?
>
> Thought experiment #2: what does someone who makes such a remark hope
> to accomplish by it, and what does it _actually_ accomplish?

I don't think there is anything I want to say in response.

I hope the bullet points will be useful to those considering writing Concept 
documentation.

regards
Andy Little