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