Re: The beauty of LATEX
"Paul A. Bristow" <[email protected]>
| Newsgroups | gmane.comp.lib.boost.documentation |
|---|---|
| Message-ID | <[email protected]> |
> -----Original Message----- > From: [email protected] [mailto:[email protected]] 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 <[email protected]> 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 +44 1539 561830 07714330204 [email protected]