Re: [Boost-docs] The beauty of LATEX

Subject: Re: [Boost-docs] The beauty of LATEX
From: Mateusz Łoskot (mateusz_at_[hidden])
Date: 2011-10-18 13:45:17

On 18 October 2011 14:23, Paul A. Bristow <pbristow_at_[hidden]> wrote:
>> 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?

True. It also touches matter of style and personal preferences, unfortunately.

>> 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?

It does not matter as long as it's linked to related concept, IMO.

> 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.

Yes, but one-liner is usually good when you re-refer to the reference.
When one reads it for first time, one-liner is not enough and there
should be link to more comprehensive
documentation about parameter.

>> 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.

Yes, I've tried to lay down this requirement, but I (mis)called it convention.

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net
Charter Member of OSGeo, http://osgeo.org
Member of ACCU, http://accu.org