Boost logo

Boost :

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


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk