Re: [boost] [function types] New tag type logic [update]

From: Tobias Schwinger (tschwinger_at_[hidden])
Date: 2005-06-30 19:27:26

Rob Stewart wrote:
> From: Tobias Schwinger <tschwinger_at_[hidden]>
> 
>>    The kinds of types to be synthesised and complex classification queries are
>>    described by *tag* types.
>>
>>    A tag encapsulates one or more aspects of the kind of type. Tags that represent
>>    the variations of a single aspect are called *aspect tags*.
>>
>>or:
>>
>>    The kinds of types to be synthesised and complex classification queries are
>>    described by *tag* types. A tag encapsulates one or more aspects of the kind of
>>    type.
>>
>>    Tags that represent the variations of a single aspect are called *aspect tags*.
> 
> 
> I wouldn't keep either break.  Here's a variation of the
> sentences you wrote above (besides putting all three sentences in
> one paragraph).
> 
>    Complex classification queries and the kinds of types you can
>    synthesize are described by *tag* types.  A tag represents one
>    or more aspects of a type's kind.  Tags that represent the
>    variations of a single aspect are called *aspect tags*.
> 
> The first sentence, as you wrote it, was a bit awkward.  While
> reading it, one first things the conjunction "and" combines
> "synthesized" and "complex."  Reading on, one realizes that it is
> combining "kinds" and "queries."  My rewrite should eliminate
> that problem.

This is a good point. I'm not entirely satisfied with your rewrite because more 
aggressive restructuring might even be better:

   The library uses *tag* types in order to represent or query a type's kind; a
   tag encapsulates one or more aspects of it.

   Tags that represent the variations of a single aspect are called *aspect tags*.

Works?

> 
> Also, I don't see the value in having two (or three) paragraphs
> for this text.
> 

Well, I'ld like to keep two paragraphs, one for each defintion.

I find this kind of structuring helpful when reading documentation myself and I 
believe I'm not the only one. But I sometimes seem to overdo it when writing...

Thanks,

Tobias