Re: [Boost-docs] stl mini-review

Subject: Re: [Boost-docs] stl mini-review
From: Stjepan Rajko (stipe_at_[hidden])
Date: 2007-07-27 20:09:58

[i just replied to this on the old list, so resending on the new
one... sorry if you get this twice]

On 7/24/07, Andrew Sutton <asutton_at_[hidden]> wrote:
>
> I completely rewrote the DefaultConstructible concept doc this
> morning - it's taken 3 this morning. Please, re-review that one page:
> it's here (and it's committed this time).
>
> http://tinyurl.com/2rb477
>
> [snip]
>
> Again, please re-review that one page... Back to graph docs for me.
>

Hey, I just started writing some concepts docs for my own docs, so I
looked at your source to try to mimic the structure as much as
possible (since I like your layout).

One question - for links to docs, you use for example:

[template StdDestructible[] [link
standards.concepts.utilities.destructible [^Destructible]]]

and then [StdDestructible] in the text where you want the Destructible link.

What I've mostly seen so far is something like:

[def __std_destructible__ [link
standards.concepts.utilities.destructible [^Destructible]]]

and then __std_destructible__ in the text where you want the Destructible link.

Since we're setting uniformity / best practices, is there a benefit to
using one over the other?  Should we recommend one or leave it up to
the author's preference?

One think I like about the latter approach is that if you write
__std_destructible__ wrong, or you haven't defined the link yet, you
get a pretty conspicuous underlined _std_destructible_ in the
resulting docs that indicates something is wrong.  With the
[StdDestructible] approach, would you just get StdDestructible in the
text if the template is not defined?

Stjepan