Re: [Boost-docs] The beauty of LATEX

Subject: Re: [Boost-docs] The beauty of LATEX
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2011-10-18 13:23:16

> -----Original Message-----
> From: boost-docs-bounces_at_[hidden] [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of
> Mateusz Loskot
> Sent: Tuesday, October 18, 2011 12:50 PM
> To: Discussion of Boost Documentation
> Subject: Re: [Boost-docs] The beauty of LATEX
> 
> On 18 October 2011 12:37, Paul A. Bristow <pbristow_at_[hidden]> wrote:
> > PS Just to give a concrete example of a reference section, I attach a
> > snip of a newly generated item from a reference section by a GSoC 2011
> > project's docs Checks C++ Reference Section.  You will see the (rather terse) info passed through (as well
> as the synopsis).
> 
> Template Parameters:
> iteration_sense - must meet the iteration_sense concept requirement
> 
> First, it should be possible to safely assume taht the right naming convention is used, so the name of
> template parameter indicates that it must meet certain requirements.
> IOW, user should not expect to see loose and random naming.

There's a lot of loose and random naming about!  It's difficult to avoid without very long names?

OK - this the first example that came to hand from newly regenerated stuff.

I said it was a bit terse - I should have said not very helpful!

> template <typename T1, typename T2, typename T2) modulus10_algorithm
> 
> unless T1, T2 and T3 are specific concept names.
> 
> Now, if the template parameter links to documentation of corresponding concept where the concept is
> defined The whole section "Template Parameters" is useless and, in all my incapability, I have tried to point it.
> 
> Otherwise, there will be plenty of repeated "Template Parameters" sections (or repeated entries)

Does that duplication matter?

When you are faced with a template in a *reference* section , I feel you should be able to get to where it is described, not have to find the concept first.

> and user won't get the picture that they are related in any way.

OK - so it could or should refer to a common concepts definition.

Paul

---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
[phone]  07714330204
pbristow_at_[hidden]