On 4/7/2013 5:12 AM, Mostafa wrote:

On Sat, 06 Apr 2013 13:54:35 -0700, Nathan Ridge wrote:

[snip]

...

However, I agree that this should be made more explicit, because just looking at the page for BOOST_PP_OVERLOAD, one may not know what the '(v)' signifies. Perhaps the '(v)' could be a link to the paragraph I quoted?

Thank you for the explanation. That was exactly my situation, I too was wondering what the '(v)' meant and indeed tried clicking on it, then looked for a footnote, but in the just attributed it to some documentation typo.

...

Perhaps the '(v)' could be a link to the paragraph I quoted?

That would certainly be very helpful. How does one bring this to the attention of the maintainer(s)?

I am one of the maintainers, as I did work adding variadic macro support to Boost PP with Paul Mensonides help. I do think that linking to some other page or anchor each time you click the "(v)" is redundant. There are many places in the Boost PP doc that use the "(v)" notation and I would have to link or anchor each one of them. I also found out an anchor on another page does not work well with the way the Boost PP docs are setup.

On 4/9/2013 2:59 AM, Mostafa wrote:

On Sun, 07 Apr 2013 15:35:52 -0700, Edward Diener wrote:

...

On 4/7/2013 5:12 AM, Mostafa wrote:

...

On Sat, 06 Apr 2013 13:54:35 -0700, Nathan Ridge wrote:

[snip]

...

However, I agree that this should be made more explicit, because just looking at the page for BOOST_PP_OVERLOAD, one may not know what the '(v)' signifies. Perhaps the '(v)' could be a link to the paragraph I quoted?

Thank you for the explanation. That was exactly my situation, I too was wondering what the '(v)' meant and indeed tried clicking on it, then looked for a footnote, but in the just attributed it to some documentation typo.

...

Perhaps the '(v)' could be a link to the paragraph I quoted?

That would certainly be very helpful. How does one bring this to the attention of the maintainer(s)?

I am one of the maintainers, as I did work adding variadic macro support to Boost PP with Paul Mensonides help. I do think that linking to some other page or anchor each time you click the "(v)" is redundant.

Isn't that the whole point of citations? Instead of repeating in place, one links to a bibliography, or some other section of text?

...

There are many places in the Boost PP doc that use the "(v)" notation and I would have to link or anchor each one of them. I also found out an anchor on another page does not work well with the way the Boost PP docs are setup.

If I were to peruse the BOOST_PP_OVERLOAD reference, how would I know what '(v)' meant? If it's not clickable, then I would look for the citation's body at the bottom of the page, or in the bibliography, neither of which exist. Hence I'm left scrounging the whole document until by luck I come across its definition.

My experience as a casual user of the library,

I added, on the Boost trunk, a link each time (v) appears in Boost PP to this area, as a named anchor, of the variadic macro topic: "Notation For Variadic Macros In the documentation, headers which have variadic macros, and variadic macros themselves, have a notation of '(v)' appended to them. For the variadic macros themselves this signifies that BOOST_PP_VARIADICS must be 1 for those variadic macros to be usable. For variadic macros which have a non-variadic equivalent, the non-variadic equivalent will be used if BOOST_PP_VARIADICS is set to 0 and the non-variadic version of the macro does not have a '(v)' appended to its name in the documentation." If you get the latest from Boost trunk it should satisfy what you want regarding the (v) notation. If Paul Mensonides is OK with this, the documentation change can be added to the next Boost release.

On 4/14/2013 12:18 AM, Paul Mensonides wrote:

On 4/13/2013 8:41 PM, Edward Diener wrote:

...

I added, on the Boost trunk, a link each time (v) appears in Boost PP to this area, as a named anchor, of the variadic macro topic:

"Notation For Variadic Macros In the documentation, headers which have variadic macros, and variadic macros themselves, have a notation of '(v)' appended to them. For the variadic macros themselves this signifies that BOOST_PP_VARIADICS must be 1 for those variadic macros to be usable. For variadic macros which have a non-variadic equivalent, the non-variadic equivalent will be used if BOOST_PP_VARIADICS is set to 0 and the non-variadic version of the macro does not have a '(v)' appended to its name in the documentation."

If you get the latest from Boost trunk it should satisfy what you want regarding the (v) notation. If Paul Mensonides is OK with this, the documentation change can be added to the next Boost release.

Looks fine to me.

Thanks.

On 4/14/2013 5:01 AM, Mostafa wrote:

On Sat, 13 Apr 2013 20:41:31 -0700, Edward Diener wrote:

...

On 4/9/2013 2:59 AM, Mostafa wrote:

...

On Sun, 07 Apr 2013 15:35:52 -0700, Edward Diener wrote:

...

On 4/7/2013 5:12 AM, Mostafa wrote:

...

On Sat, 06 Apr 2013 13:54:35 -0700, Nathan Ridge wrote:

[snip]

...

However, I agree that this should be made more explicit, because just looking at the page for BOOST_PP_OVERLOAD, one may not know what the '(v)' signifies. Perhaps the '(v)' could be a link to the paragraph I quoted?

Thank you for the explanation. That was exactly my situation, I too was wondering what the '(v)' meant and indeed tried clicking on it, then looked for a footnote, but in the just attributed it to some documentation typo.

...

Perhaps the '(v)' could be a link to the paragraph I quoted?

That would certainly be very helpful. How does one bring this to the attention of the maintainer(s)?

I am one of the maintainers, as I did work adding variadic macro support to Boost PP with Paul Mensonides help. I do think that linking to some other page or anchor each time you click the "(v)" is redundant.

Isn't that the whole point of citations? Instead of repeating in place, one links to a bibliography, or some other section of text?

...

There are many places in the Boost PP doc that use the "(v)" notation and I would have to link or anchor each one of them. I also found out an anchor on another page does not work well with the way the Boost PP docs are setup.

If I were to peruse the BOOST_PP_OVERLOAD reference, how would I know what '(v)' meant? If it's not clickable, then I would look for the citation's body at the bottom of the page, or in the bibliography, neither of which exist. Hence I'm left scrounging the whole document until by luck I come across its definition.

My experience as a casual user of the library,

I added, on the Boost trunk, a link each time (v) appears in Boost PP to this area, as a named anchor, of the variadic macro topic:

"Notation For Variadic Macros In the documentation, headers which have variadic macros, and variadic macros themselves, have a notation of '(v)' appended to them. For the variadic macros themselves this signifies that BOOST_PP_VARIADICS must be 1 for those variadic macros to be usable. For variadic macros which have a non-variadic equivalent, the non-variadic equivalent will be used if BOOST_PP_VARIADICS is set to 0 and the non-variadic version of the macro does not have a '(v)' appended to its name in the documentation."

Thanks, I think that will be helpful to new users of the library. Another question, what does the sentence:

"For variadic macros which have a non-variadic equivalent, the non-variadic equivalent will be used if BOOST_PP_VARIADICS is set to 0 and the non-variadic version of the macro does not have a '(v)' appended to its name in the documentation."

mean? Would not non-variadic versions of macros by definition not have '(v)' appended to their names? The last clause seems redundant to me. Am I right, or am I missing something?

It is redundant. Updated on Boost trunk.