When discussing libraries in public that are under development but not yet accepted into Boost, I think it's problematic to refer to "The Boost <whatever> library" or "Boost.<whatever>" without qualification. Our peer-review process is respected, and these libraries are not yet officially blessed by Boost. I don't want to dilute the value of Boost acceptance. Can we please make a habit of prepending "The proposed" or something similar? For example, I suggest "The proposed Boost Interfaces library." Thanks! P.S. I hope it's obvious, but I don't think the documentation for the proposed library ought to resort to such contortions. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
When discussing libraries in public that are under development but not yet accepted into Boost, I think it's problematic to refer to "The Boost <whatever> library" or "Boost.<whatever>" without qualification. Our peer-review process is respected, and these libraries are not yet officially blessed by Boost. I don't want to dilute the value of Boost acceptance. Can we please make a habit of prepending "The proposed" or something similar? For example, I suggest "The proposed Boost Interfaces library.
I understand the problem. With the interfaces library, the documentation contains a prominent disclaimer, and so does every source file. I can't think of anything better right now, but to me "proposed" suggests that the libray is in the review queue.
Thanks!
Jonathan
----- Original Message ----- From: "Jonathan Turkanis" <technews@kangaroologic.com> To: <boost@lists.boost.org> Sent: Saturday, March 05, 2005 10:42 AM Subject: [boost] Re: Naming Proposed Libraries
David Abrahams wrote:
When discussing libraries in public that are under development but not yet accepted into Boost, I think it's problematic to refer to "The Boost <whatever> library" or "Boost.<whatever>" without qualification. Our peer-review process is respected, and these libraries are not yet officially blessed by Boost. I don't want to dilute the value of Boost acceptance. Can we please make a habit of prepending "The proposed" or something similar? For example, I suggest "The proposed Boost Interfaces library.
I understand the problem. With the interfaces library, the documentation contains a prominent disclaimer, and so does every source file.
I can't think of anything better right now, but to me "proposed" suggests that the libray is in the review queue.
Thanks!
I have been definitely guilty of being careless in this regards to referencing proposed libraries in public, and I will be more careful in the future. I assume though that this mailing list itself is not sufficiently "public" to warrant the more verbose naming? I think the BIL is as clear in its documentation as can be reasonably expected. Whether or not a library is in a review queue is not really a significant concern is it, as it doesn't take any special requirements to get into the queue? Christopher Diggins Object Oriented Template Library (OOTL) http://www.ootl.org
On Sat, 05 Mar 2005 11:12:53 -0500, christopher diggins wrote
Whether or not a library is in a review queue is not really a significant concern is it, as it doesn't take any special requirements to get into the queue?
Just a request from the author(s) gets you in the queue. At that point there will probably be some evaluation by the review wizard and others to see if the library is really ready. We've seen alot of folks over the years post good ideas, get something good started, and then never follow through. So, to me, asking for a review marks a significant milestone -- that the authors are really ready to go to the next step. Jeff
christopher diggins <cdiggins@videotron.ca> writes:
----- Original Message ----- From: "Jonathan Turkanis" <technews@kangaroologic.com> To: <boost@lists.boost.org> Sent: Saturday, March 05, 2005 10:42 AM Subject: [boost] Re: Naming Proposed Libraries
David Abrahams wrote:
When discussing libraries in public that are under development but not yet accepted into Boost, I think it's problematic to refer to "The Boost <whatever> library" or "Boost.<whatever>" without qualification. Our peer-review process is respected, and these libraries are not yet officially blessed by Boost. I don't want to dilute the value of Boost acceptance. Can we please make a habit of prepending "The proposed" or something similar? For example, I suggest "The proposed Boost Interfaces library.
I understand the problem. With the interfaces library, the documentation contains a prominent disclaimer, and so does every source file.
I can't think of anything better right now, but to me "proposed" suggests that the libray is in the review queue.
Thanks!
I have been definitely guilty of being careless in this regards to referencing proposed libraries in public, and I will be more careful in the future. I assume though that this mailing list itself is not sufficiently "public" to warrant the more verbose naming?
Quite the contrary IMO, though it's even more important in fora outside this one.
I think the BIL is as clear in its documentation as can be reasonably expected.
As I tried to indicate, I am *not* particularly concerned about the library docs and source, though it's nice if they disclaim. I'm concerned with the perception engendered by casual conversation.
Whether or not a library is in a review queue is not really a significant concern is it, as it doesn't take any special requirements to get into the queue?
Not a significant concern for me. -- Dave Abrahams Boost Consulting www.boost-consulting.com
From: "Jonathan Turkanis" <technews@kangaroologic.com>
David Abrahams wrote:
When discussing libraries in public that are under development but not yet accepted into Boost, I think it's problematic to refer to "The Boost <whatever> library" or "Boost.<whatever>" without qualification. Our peer-review process is respected, and these libraries are not yet officially blessed by Boost. I don't want to dilute the value of Boost acceptance. Can we please make a habit of prepending "The proposed" or something similar? For example, I suggest "The proposed Boost Interfaces library.
I have noticed the problem, but since such libraries may not be accepted, isn't it wrong to put Boost in the name, even if qualified?
I understand the problem. With the interfaces library, the documentation contains a prominent disclaimer, and so does every source file.
That's a terrific approach, but it does mean you have to remember to remove the disclaimers when the library enters the review queue.
I can't think of anything better right now, but to me "proposed" suggests that the libray is in the review queue.
Agreed. How about just omitting "Boost?" At this point, the "Boost Interfaces Library" is just the "Turkanis Interfaces Library" or the "Interfaces Library," right? IOW, make it wrong to modify a library name with "Boost" until it has been accepted (though the documentation can be written as if it had been accepted, with disclaimers initially). -- Rob Stewart stewart@sig.com Software Engineer http://www.sig.com Susquehanna International Group, LLP using std::disclaimer;
Rob Stewart wrote:
I have noticed the problem, but since such libraries may not be accepted, isn't it wrong to put Boost in the name, even if qualified?
I really agree with this, and I don't think a disclaimer or the "proposed" is strong enough at all, and I think the feared dilution is already occurring. I have wondered at every review why reviewed libraries come with docs that already have the boost name (and logo!) on them, completely indistinguishable from an accepted library. At the first review, being new to all this, I surmised that boost was some kind of old-boy's club, where it was given that libraries that went up for review would be accepted, and that the real task in getting "in" to boost was more a political one: to schmooze your way in to getting your library reviewed at all... Now I see that it's not accurate, but it wasn't a good impression, it really erodes the value of the name "boost". troy d. straszheim
"troy d. straszheim" <troy@resophonic.com> writes:
Rob Stewart wrote:
I have noticed the problem, but since such libraries may not be accepted, isn't it wrong to put Boost in the name, even if qualified?
I really agree with this, and I don't think a disclaimer or the "proposed" is strong enough at all, and I think the feared dilution is already occurring. I have wondered at every review why reviewed libraries come with docs that already have the boost name (and logo!) on them, completely indistinguishable from an accepted library.
Others obviously feel differently, but that *really* doesn't bother me, and I don't want to make busywork for library authors by forcing them to make more trivial changes than neccessary when a library is accepted.
At the first review, being new to all this, I surmised that boost was some kind of old-boy's club, where it was given that libraries that went up for review would be accepted
Sometimes I fear that we may be accepting too many libraries because people want to be nice, and the only people doing reviews have a strong interest in getting the functionality in some form. Just a vague concern, no real evidence.
and that the real task in getting "in" to boost was more a political one: to schmooze your way in to getting your library reviewed at all... Now I see that it's not accurate, but it wasn't a good impression, it really erodes the value of the name "boost".
Wow, that really says something. Thanks for the perspective. -- Dave Abrahams Boost Consulting www.boost-consulting.com
Rob Stewart <stewart@sig.com> writes:
How about just omitting "Boost?" At this point, the "Boost Interfaces Library" is just the "Turkanis Interfaces Library" or the "Interfaces Library," right? IOW, make it wrong to modify a library name with "Boost" until it has been accepted (though the documentation can be written as if it had been accepted, with disclaimers initially).
Fine with me. -- Dave Abrahams Boost Consulting www.boost-consulting.com
Rob Stewart wrote:
From: "Jonathan Turkanis" <technews@kangaroologic.com>
I understand the problem. With the interfaces library, the documentation contains a prominent disclaimer, and so does every source file.
That's a terrific approach, but it does mean you have to remember to remove the disclaimers when the library enters the review queue.
I think keeping the disclaimer until acceptance would be better. With the iostreams library removing the disclaimer from the source files just took just a few seconds; removing it from HTML documents was a little harder so I stopped putting disclaimers on each documentation file.
I can't think of anything better right now, but to me "proposed" suggests that the libray is in the review queue.
Agreed.
How about just omitting "Boost?" At this point, the "Boost Interfaces Library" is just the "Turkanis Interfaces Library"
Uncle Jonathan's Home-Style Interface Library?
or the "Interfaces Library," right? IOW, make it wrong to modify a library name with "Boost" until it has been accepted (though the documentation can be written as if it had been accepted, with disclaimers initially).
I think having a name which sounds good is important for a library, even in the early stages. Also, changing the name after the library has acquired a significant body of users, or after articles have been written about it, is confusing and may slow the libraries adoption by more users. In the case at hand, I believe "Interfaces Library" is a lousy name. If I were naming the library with no though to its possible future acceptance into boost, I might call it "C++ with Interfaces" (the name of Christopher's article). If it were eventually accepted into Boost, I'd change the name to Boost.Interfaces, but the de facto name, at least for a while, would be "Boost.Interfaces (formerly C++ with Interfaces)." To sum up, I prefer Dave's original suggestion, the "[proposed/contemplated/suggested] Boost Interfaces Library". Jonathan
"Jonathan Turkanis" <technews@kangaroologic.com> writes:
In the case at hand, I believe "Interfaces Library" is a lousy name. If I were naming the library with no though to its possible future acceptance into boost, I might call it "C++ with Interfaces" (the name of Christopher's article). If it were eventually accepted into Boost, I'd change the name to Boost.Interfaces, but the de facto name, at least for a while, would be "Boost.Interfaces (formerly C++ with Interfaces)."
To sum up, I prefer Dave's original suggestion, the "[proposed/contemplated/suggested] Boost Interfaces Library".
As far as I'm concerned, people can choose any one of the ways to talk/type that makes it clear that it's not yet an official Boost library. We don't have to all agree on a convention. -- Dave Abrahams Boost Consulting www.boost-consulting.com
From: David Abrahams <dave@boost-consulting.com>
"Jonathan Turkanis" <technews@kangaroologic.com> writes:
To sum up, I prefer Dave's original suggestion, the "[proposed/contemplated/suggested] Boost Interfaces Library".
As far as I'm concerned, people can choose any one of the ways to talk/type that makes it clear that it's not yet an official Boost library. We don't have to all agree on a convention.
The acceptable mailing list and documentation practices should be documented, no? A section under "Effective Posting" (in more/discussion_policy.htm) would be useful to document appropriate subject tagging as well as this point. Here's a suggestion for consideration: <H2>Effective Posting</H2> <H3>Subjects</H3> Always start your subject with <KBD>[boost]</KBD>. Many use that tag to filter incoming mail. If your post is regarding a specific Boost library, add a <KBD>[</KBD><I>name</I><KBD>]</KBD> tag, where <I>name</I> is the library name in all lower case. <H3>Referencing Libraries</H3> Boost libraries are named <I>Boost.Name</I> or <I>The Boost Name Library</I>, where <I>Name</I> is the full name of the library. Libraries that are candidates for inclusion in Boost, whether at the conceptual stage or in the review queue, can be referenced without the <I>Boost</I> modifier or with the addition of <I>Candidate, </I>as in <I>Boost Candidate.Name</I> or <I>The Candidate Boost Name Library</I>. <H3>Quoting</H3> (insert existing text on quoting) <H3>Referencing Previous Messages</H3> (insert existing text on referencing messages) <H3>Effective Communications</H3> (insert existing text on grammar, social engineering, etc.) -- Rob Stewart stewart@sig.com Software Engineer http://www.sig.com Susquehanna International Group, LLP using std::disclaimer;
Rob Stewart wrote:
Here's a suggestion for consideration:
<H2>Effective Posting</H2> <H3>Subjects</H3> Always start your subject with <KBD>[boost]</KBD>. Many use that tag to filter incoming mail.
The list itself adds that already. -- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org - grafik/redshift-software.com - 102708583/icq
Rob Stewart <stewart@sig.com> writes:
From: David Abrahams <dave@boost-consulting.com>
"Jonathan Turkanis" <technews@kangaroologic.com> writes:
To sum up, I prefer Dave's original suggestion, the "[proposed/contemplated/suggested] Boost Interfaces Library".
As far as I'm concerned, people can choose any one of the ways to talk/type that makes it clear that it's not yet an official Boost library. We don't have to all agree on a convention.
The acceptable mailing list and documentation practices should be documented, no? A section under "Effective Posting" (in more/discussion_policy.htm) would be useful to document appropriate subject tagging as well as this point.
Good idea.
Here's a suggestion for consideration:
<H2>Effective Posting</H2> <H3>Subjects</H3> Always start your subject with <KBD>[boost]</KBD>. Many use that tag to filter incoming mail.
Overkill. NObody relies on that now because Boost mail doesn't typically have that tag. People can sort based on Original-X-From or Reply-To. Many of us read it in a GMane newsgroup and it would just clutter our subject lines. Subject lines ought to start with the library/topic name as you suggest below.
If your post is regarding a specific Boost library, add a <KBD>[</KBD><I>name</I><KBD>]</KBD> tag, where <I>name</I> is the library name in all lower case.
<H3>Referencing Libraries</H3> Boost libraries are named <I>Boost.Name</I> or <I>The Boost Name Library</I>,
We decided "library" was not part of of the name and should be lowercased. Clearly "the" should be lowercased. http://article.gmane.org/gmane.comp.lib.boost.devel/110005 I suggest you fold this information into your suggested doc patch ;-)
where <I>Name</I> is the full name of the library. Libraries that are candidates for inclusion in Boost, whether at the conceptual stage or in the review queue, can be referenced without the <I>Boost</I> modifier or with the addition of <I>Candidate, </I>as in <I>Boost Candidate.Name</I>
Seems contorted. What's wrong with Boost.Name candidate or candidate Boost.Name ? And why are you capitalizing "candidate?"
or <I>The Candidate Boost Name Library</I>.
That's fine. -- Dave Abrahams Boost Consulting www.boost-consulting.com
From: David Abrahams <dave@boost-consulting.com>
Rob Stewart <stewart@sig.com> writes:
Here's a suggestion for consideration:
<H2>Effective Posting</H2> <H3>Subjects</H3> Always start your subject with <KBD>[boost]</KBD>. Many use that tag to filter incoming mail.
Overkill. NObody relies on that now because Boost mail doesn't typically have that tag. People can sort based on Original-X-From or Reply-To. Many of us read it in a GMane newsgroup and it would just clutter our subject lines. Subject lines ought to start with the library/topic name as you suggest below.
Every message I get from the list includes it and my procmail recipe relies on it, so clearly you overstated the case with "NObody." That said, it seems "[boost]" is added automatically by the list server, which I wondered about, but figured someone would let me know.
If your post is regarding a specific Boost library, add a <KBD>[</KBD><I>name</I><KBD>]</KBD> tag, where <I>name</I> is the library name in all lower case.
<H3>Referencing Libraries</H3> Boost libraries are named <I>Boost.Name</I> or <I>The Boost Name Library</I>,
We decided "library" was not part of of the name and should be lowercased. Clearly "the" should be lowercased.
I couldn't remember.
I suggest you fold this information into your suggested doc patch ;-)
I figured that was coming, too.
where <I>Name</I> is the full name of the library. Libraries that are candidates for inclusion in Boost, whether at the conceptual stage or in the review queue, can be referenced without the <I>Boost</I> modifier or with the addition of <I>Candidate, </I>as in <I>Boost Candidate.Name</I>
Seems contorted. What's wrong with
Boost.Name candidate
or
candidate Boost.Name
I was trying to ensure "Boost" wasn't connected too closely. With your version, "Boost.Name" still stands out since they are juxtaposed and capitalized. I was trying to make "Boost Candidate" akin to "Boost" in modifying a library name.
And why are you capitalizing "candidate?"
Because I was making the name "Boost Candidate.Name" rather than "Boost.Name." It could be "Boost.Candidate.Name," too.
or <I>The Candidate Boost Name Library</I>.
That's fine.
But, if I follow your comments from above, neither "The" nor "Library" should be capitalized, right? Then, there's still the question of whether "Candidate" should be capitalized. -- Rob Stewart stewart@sig.com Software Engineer http://www.sig.com Susquehanna International Group, LLP using std::disclaimer;
Rob Stewart <stewart@sig.com> writes:
From: David Abrahams <dave@boost-consulting.com>
Rob Stewart <stewart@sig.com> writes:
Here's a suggestion for consideration:
<H2>Effective Posting</H2> <H3>Subjects</H3> Always start your subject with <KBD>[boost]</KBD>. Many use that tag to filter incoming mail.
Overkill. NObody relies on that now because Boost mail doesn't typically have that tag. People can sort based on Original-X-From or Reply-To. Many of us read it in a GMane newsgroup and it would just clutter our subject lines. Subject lines ought to start with the library/topic name as you suggest below.
Every message I get from the list includes it and my procmail recipe relies on it, so clearly you overstated the case with "NObody."
Okay, sorry. I guess GMane is helpfully stripping it for me.
That said, it seems "[boost]" is added automatically by the list server, which I wondered about, but figured someone would let me know.
Okay, we're good.
where <I>Name</I> is the full name of the library. Libraries that are candidates for inclusion in Boost, whether at the conceptual stage or in the review queue, can be referenced without the <I>Boost</I> modifier or with the addition of <I>Candidate, </I>as in <I>Boost Candidate.Name</I>
Seems contorted. What's wrong with
Boost.Name candidate
or
candidate Boost.Name
I was trying to ensure "Boost" wasn't connected too closely. With your version, "Boost.Name" still stands out since they are juxtaposed and capitalized. I was trying to make "Boost Candidate" akin to "Boost" in modifying a library name.
Well, my intention is to make things clear, but not to make people write/speak unnaturally. I don't want to be heavyhanded about this. I would like to see one other person agree with you that it's a good idea before including it in the document.
And why are you capitalizing "candidate?"
Because I was making the name "Boost Candidate.Name" rather than "Boost.Name." It could be "Boost.Candidate.Name," too.
or <I>The Candidate Boost Name Library</I>.
That's fine.
But, if I follow your comments from above, neither "The" nor "Library" should be capitalized, right?
Right
Then, there's still the question of whether "Candidate" should be capitalized.
Well, if anyone buys into your version with the dot that puts "candidate" in the middle, you can capitalize it in that context as far as I'm concerned. Otherwise, it's just an adjective and should be lowercase. -- Dave Abrahams Boost Consulting www.boost-consulting.com
From: David Abrahams <dave@boost-consulting.com>
Rob Stewart <stewart@sig.com> writes:
From: David Abrahams <dave@boost-consulting.com>
Rob Stewart <stewart@sig.com> writes:
where <I>Name</I> is the full name of the library. Libraries that are candidates for inclusion in Boost, whether at the conceptual stage or in the review queue, can be referenced without the <I>Boost</I> modifier or with the addition of <I>Candidate, </I>as in <I>Boost Candidate.Name</I>
Seems contorted. What's wrong with
Boost.Name candidate
or
candidate Boost.Name
I was trying to ensure "Boost" wasn't connected too closely. With your version, "Boost.Name" still stands out since they are juxtaposed and capitalized. I was trying to make "Boost Candidate" akin to "Boost" in modifying a library name.
Well, my intention is to make things clear, but not to make people write/speak unnaturally. I don't want to be heavyhanded about this. I would like to see one other person agree with you that it's a good idea before including it in the document.
I've heard from no one for or against my ideas, or yours for that matter. Does anyone have an opinion on how this should be codified? What do you think should be the official naming convention?
And why are you capitalizing "candidate?"
Because I was making the name "Boost Candidate.Name" rather than "Boost.Name." It could be "Boost.Candidate.Name," too.
or <I>The Candidate Boost Name Library</I>.
That's fine.
But, if I follow your comments from above, neither "The" nor "Library" should be capitalized, right?
Right
Then, there's still the question of whether "Candidate" should be capitalized.
Well, if anyone buys into your version with the dot that puts "candidate" in the middle, you can capitalize it in that context as far as I'm concerned. Otherwise, it's just an adjective and should be lowercase.
So, the question remains: Is "Boost Candidate.Name" instead of "Boost.Name" a good idea in message traffic prior to acceptance? (For that matter, Boost.Book and QuickBook could be modified to generate such names automatically, with a switch that indicates that a library has not yet been accepted.) If you don't like that, do you think "candidate Boost.Name" is good enough? My concern is that "candidate," being lower case, will pale next to "Boost.Name" and so lose its value. There's also the question of whether "candidate" is the right word. One could make a case for "proposed," "tentative," and other words. Is there any reason to have a different modifier for libraries in the review queue as compared to those simply under development with aspirations to be reviewed? For example, the former case could readily use "candidate" or "proposed," whereas the latter is not properly a Boost candidate, since it hasn't yet been proposed for review, and so might better be described as "potential." Dave has made the case for not requiring name changes in documentation. If it can be done easily enough via Boost.Book and QuickBook, I think it is reasonable to expect it in documentation generated with those tools. However, since the use of those tools is not required, then it would be simplest and most consistent to simply state that documentation need not alter Boost.Name. Let me know what you think should be our naming requirements. Once we reach consensus, I'll create a diff for more/discussion_policy.htm to capture them. -- Rob Stewart stewart@sig.com Software Engineer http://www.sig.com Susquehanna International Group, LLP using std::disclaimer;
Rob Stewart <stewart@sig.com> writes:
Well, my intention is to make things clear, but not to make people write/speak unnaturally. I don't want to be heavyhanded about this. I would like to see one other person agree with you that it's a good idea before including it in the document.
I've heard from no one for or against my ideas, or yours for that matter. Does anyone have an opinion on how this should be codified? What do you think should be the official naming convention?
I don't have an opinion; I don't think we need an official naming convention. I just want people to distinguish accepted from proposed libraries in their speaking and writing. No need to make a big production of it.
So, the question remains: Is "Boost Candidate.Name" instead of "Boost.Name" a good idea in message traffic prior to acceptance?
I should think my opinion would be obvious by now: "Boost Candidate.Name" is better than "Boost.Name" for that purpose. OTOH I don't care if someone wants to say "proposed Boost.Name" or whatever.
(For that matter, Boost.Book and QuickBook could be modified to generate such names automatically, with a switch that indicates that a library has not yet been accepted.)
Overhead. Complication. This is a simple thing; no need to make it into something big.
If you don't like that, do you think "candidate Boost.Name" is good enough? My concern is that "candidate," being lower case, will pale next to "Boost.Name" and so lose its value.
It's not that imporant.
There's also the question of whether "candidate" is the right word. One could make a case for "proposed," "tentative," and other words.
Those are fine with me too.
Is there any reason to have a different modifier for libraries in the review queue as compared to those simply under development with aspirations to be reviewed? For example, the former case could readily use "candidate" or "proposed," whereas the latter is not properly a Boost candidate, since it hasn't yet been proposed for review, and so might better be described as "potential."
Dave has made the case for not requiring name changes in documentation. If it can be done easily enough via Boost.Book and QuickBook, I think it is reasonable to expect it in documentation generated with those tools. However, since the use of those tools is not required, then it would be simplest and most consistent to simply state that documentation need not alter Boost.Name.
Let me know what you think should be our naming requirements. Once we reach consensus, I'll create a diff for more/discussion_policy.htm to capture them.
The requirements should be "distinguish accepted boost libraries from things someone hopes will be in Boost, someday." Beyond that, I don't care. -- Dave Abrahams Boost Consulting www.boost-consulting.com
From: David Abrahams <dave@boost-consulting.com>
Rob Stewart <stewart@sig.com> writes:
Well, my intention is to make things clear, but not to make people write/speak unnaturally. I don't want to be heavyhanded about this. I would like to see one other person agree with you that it's a good idea before including it in the document.
I've heard from no one for or against my ideas, or yours for that matter. Does anyone have an opinion on how this should be codified? What do you think should be the official naming convention?
I don't have an opinion; I don't think we need an official naming convention. I just want people to distinguish accepted from proposed libraries in their speaking and writing. No need to make a big production of it.
So, the question remains: Is "Boost Candidate.Name" instead of "Boost.Name" a good idea in message traffic prior to acceptance?
I should think my opinion would be obvious by now: "Boost Candidate.Name" is better than "Boost.Name" for that purpose. OTOH I don't care if someone wants to say "proposed Boost.Name" or whatever.
I didn't do a very good job in my message, but I started out by using "your" to refer to you, and from that point forward, I was referring to everyone in order to seek feedback. Yes, I already knew your opinions on the matter. I'm sorry for the confusion.
(For that matter, Boost.Book and QuickBook could be modified to generate such names automatically, with a switch that indicates that a library has not yet been accepted.)
Overhead. Complication. This is a simple thing; no need to make it into something big.
Yes, I can understand your thinking that this would be too much if you think nothing formal need be done in the first place.
If you don't like that, do you think "candidate Boost.Name" is good enough? My concern is that "candidate," being lower case, will pale next to "Boost.Name" and so lose its value.
It's not that imporant.
What about those that expressed the opinion that using "Boost.Name" diluted the value of Boost acceptance? Is candidate Boost.Name really good enough? Notice that "candidate" can be separated from "Boost.Name" as I did it in the last sentence. Doesn't that make "Boost.Name" stand out and suggest official status? OTOTH, Boost Candidate.Name offers no room for such confusion.
Is there any reason to have a different modifier for libraries in the review queue as compared to those simply under development with aspirations to be reviewed? For example, the former case could readily use "candidate" or "proposed," whereas the latter is not properly a Boost candidate, since it hasn't yet been proposed for review, and so might better be described as "potential."
Dave has made the case for not requiring name changes in documentation. If it can be done easily enough via Boost.Book and QuickBook, I think it is reasonable to expect it in documentation generated with those tools. However, since the use of those tools is not required, then it would be simplest and most consistent to simply state that documentation need not alter Boost.Name.
Let me know what you think should be our naming requirements. Once we reach consensus, I'll create a diff for more/discussion_policy.htm to capture them.
The requirements should be "distinguish accepted boost libraries from things someone hopes will be in Boost, someday." Beyond that, I don't care.
If your laissez faire approach is acceptable to folks, then I agree. If something a little more formal is desirable, then something else is needed. I'd like to see some consensus from folks on the list. -- Rob Stewart stewart@sig.com Software Engineer http://www.sig.com Susquehanna International Group, LLP using std::disclaimer;
Rob Stewart wrote:
The requirements should be "distinguish accepted boost libraries from things someone hopes will be in Boost, someday." Beyond that, I don't care.
If your laissez faire approach is acceptable to folks, then I agree. If something a little more formal is desirable, then something else is needed. I'd like to see some consensus from folks on the list.
I agree with Dave that there is no need for a formal convention. Jonathan
Hi Rob & All, My 2 cents: "Boost Candidate.Library" seems awkward. As David suggested, a precise English description in email (using "proposed", "candidate" or whatever) should be adequate. All docs and code should look as it will if accepted, with a possible disclaimer on the front page of the docs and/or comments in the main header. Not (entirely) serious: As we are all C++ folks, we could use more compact syntax. Say, "--Boost.Library" or "?Boost.Library?" or maybe even "!Boost.Library" to convey the desired semantics. :) Don --- Rob Stewart <stewart@sig.com> wrote:
If your laissez faire approach is acceptable to folks, then I agree. If something a little more formal is desirable, then something else is needed. I'd like to see some consensus from folks on the list.
__________________________________ Do you Yahoo!? Yahoo! Small Business - Try our new resources site! http://smallbusiness.yahoo.com/resources/
David Abrahams wrote:
Rob Stewart <stewart@sig.com> writes:
(For that matter, Boost.Book and QuickBook could be modified to generate such names automatically, with a switch that indicates that a library has not yet been accepted.)
Overhead. Complication. This is a simple thing; no need to make it into something big.
Using QuickBook, no modification is needed. Example: [def __pizzalib__ Candidate Pizza Library] The __pizzalib__ provides an infrastructure to easily make all sorts of pizza variations using extreme template meta programming. Warning: Salami not included. When Pizza Lib gets accepted, just tweak the def. Cheers, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
On Thu, 24 Mar 2005 11:02:19 +0800, Joel de Guzman wrote
David Abrahams wrote:
Rob Stewart <stewart@sig.com> writes:
(For that matter, Boost.Book and QuickBook could be modified to generate such names automatically, with a switch that indicates that a library has not yet been accepted.)
Overhead. Complication. This is a simple thing; no need to make it into something big.
Using QuickBook, no modification is needed. Example:
[def __pizzalib__ Candidate Pizza Library]
The __pizzalib__ provides an infrastructure to easily make all sorts of pizza variations using extreme template meta programming. Warning: Salami not included.
When Pizza Lib gets accepted, just tweak the def.
As much as I'm a quickbook fan, we can't expect library developers to use it. Also, I wouldn't want to discourage authors from using the Boost directory structure or practices during the dev phase as I think someone suggested earlier in this thread. Using boost practices makes it easier for all of us to evaluate, develop, etc. So I'm with Dave on this -- a simple 'candidate' (or similar designation) in emails works. Jeff
Jeff Garland wrote:
On Thu, 24 Mar 2005 11:02:19 +0800, Joel de Guzman wrote
David Abrahams wrote:
Rob Stewart <stewart@sig.com> writes:
(For that matter, Boost.Book and QuickBook could be modified to generate such names automatically, with a switch that indicates that a library has not yet been accepted.)
Overhead. Complication. This is a simple thing; no need to make it into something big.
Using QuickBook, no modification is needed. Example:
[def __pizzalib__ Candidate Pizza Library]
The __pizzalib__ provides an infrastructure to easily make all sorts of pizza variations using extreme template meta programming. Warning: Salami not included.
When Pizza Lib gets accepted, just tweak the def.
As much as I'm a quickbook fan, we can't expect library developers to use it. Also, I wouldn't want to discourage authors from using the Boost directory structure or practices during the dev phase as I think someone suggested earlier in this thread. Using boost practices makes it easier for all of us to evaluate, develop, etc. So I'm with Dave on this -- a simple 'candidate' (or similar designation) in emails works.
I'm also with Dave on this. I just wanted to say that if someone wants to "generate such names automatically", she can easily do it and there's no overhead and complication in doing so, using QuickBook. No big deal either way, AFAICT. Cheers, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
David Abrahams wrote:
The requirements should be "distinguish accepted boost libraries from things someone hopes will be in Boost, someday." Beyond that, I don't care.
I'm with that. Or to put it another way... Either: don't say it's a Boost library, or say that it's not a Boost library :-) -- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org - grafik/redshift-software.com - 102708583/icq
From: David Abrahams <dave@boost-consulting.com>
Rob Stewart <stewart@sig.com> writes:
Well, my intention is to make things clear, but not to make people write/speak unnaturally. I don't want to be heavyhanded about this. I would like to see one other person agree with you that it's a good idea before including it in the document.
I've heard from no one for or against my ideas, or yours for that matter. Does anyone have an opinion on how this should be codified? What do you think should be the official naming convention?
I don't have an opinion; I don't think we need an official naming convention. I just want people to distinguish accepted from proposed libraries in their speaking and writing. No need to make a big production of it.
It seems I took the ideas of the original discussion too far. The consensus seems to be that folks just want to make sure a library isn't named as if it's part of Boost, but they don't care too much how that's done.
Let me know what you think should be our naming requirements. Once we reach consensus, I'll create a diff for more/discussion_policy.htm to capture them.
The requirements should be "distinguish accepted boost libraries from things someone hopes will be in Boost, someday." Beyond that, I don't care.
Here's my take, then: _____________________________________________________ Library Names Please avoid confusion between libraries that have been accepted by Boost and those that have not. Here are some suggested approaches to accomplish that (the first one is probably your best choice): * the LibName library * the proposed Boost.LibName library * the candidate Boost.LibName library * the your adjective here Boost.LibName library Note that this naming only applies to discussions, not to the documentation, directory structure, or even identifiers in the code. _____________________________________________________ Below is the diff against the current discussion_policy.htm at boost.org. I took the liberty of correcting the heading case for several of the sections on the page, while I was there. *** 32,43 **** <dl> <dt><a href="#acceptable">Acceptable Topics</a><dd> <dt><a href="#unacceptable">Unacceptable Topics</a><dd> <dt><a href="#quoting">Effective Posting</a><dd> <dt><a href="#behavior">Prohibited Behavior</a><dd> <dt><a href="#culture">Culture</a><dd> </dl> ! <h2><a name="acceptable"></a>Acceptable topics</h2> <ul> <li>Queries to determine interest in a possible library submission.</li> <li>Technical discussions about a proposed or existing library, including bug --- 32,44 ---- <dl> <dt><a href="#acceptable">Acceptable Topics</a><dd> <dt><a href="#unacceptable">Unacceptable Topics</a><dd> + <dt><a href="#lib_names">Library Names</a><dd> <dt><a href="#quoting">Effective Posting</a><dd> <dt><a href="#behavior">Prohibited Behavior</a><dd> <dt><a href="#culture">Culture</a><dd> </dl> ! <h2><a name="acceptable"></a>Acceptable Topics</h2> <ul> <li>Queries to determine interest in a possible library submission.</li> <li>Technical discussions about a proposed or existing library, including bug *************** *** 49,55 **** </ul> <p>Other topics related to boost development may be acceptable, at the discretion of moderators. If unsure, go ahead and post. The moderators will let you know.</p> ! <h2><a name="unacceptable"></a>Unacceptable topics</h2> <ul> <li>Advertisements for commercial products.</li> <li>Requests for help getting non-boost code to compile with your compiler. --- 50,56 ---- </ul> <p>Other topics related to boost development may be acceptable, at the discretion of moderators. If unsure, go ahead and post. The moderators will let you know.</p> ! <h2><a name="unacceptable"></a>Unacceptable Topics</h2> <ul> <li>Advertisements for commercial products.</li> <li>Requests for help getting non-boost code to compile with your compiler. *************** *** 58,63 **** --- 59,78 ---- newsgroup instead.</li> <li>Job offers.</li> <li>Requests for solutions to homework assignments.</ul> + <h2><a name="lib_names"></a>Library Names</h2> + <p>Please avoid confusion between libraries that have been + accepted by Boost and those that have not. Here are some + suggested approaches to accomplish that (the first one is + probably your best choice): + <ul> + <li><i>the LibName library</i></li> + <li><i>the proposed Boost.LibName library</i></li> + <li><i>the candidate Boost.LibName library</i></li> + <li><i>the </i>your adjective here<i> Boost.LibName library</i></li> + </ul> + <p>Note that this naming only applies to discussions, not to the + documentation, directory structure, or even identifiers in the + code. <h2><a name="quoting"></a>Effective Posting</h2> <p>Please <b>prune extraneous quoted text</b> from replies so that *************** *** 137,143 **** the <a href="http://news.gmane.org/gmane.comp.lib.boost.devel">GMane web interface</a>. ! <h2><a name="behavior"></a>Prohibited behavior</h2> <p>Prohibited behavior will not be tolerated. The moderators will ban postings by abusers.</p> <h3>Flame wars</h3> --- 152,158 ---- the <a href="http://news.gmane.org/gmane.comp.lib.boost.devel">GMane web interface</a>. ! <h2><a name="behavior"></a>Prohibited Behavior</h2> <p>Prohibited behavior will not be tolerated. The moderators will ban postings by abusers.</p> <h3>Flame wars</h3> *************** *** 171,177 **** language, or abbreviations, they may not be understood by all readers. Re-read your message before submitting it.</p> ! <h2>Guidelines for effective discussions</h2> <p>Apply social engineering to prevent heated technical discussion from degenerating into a shouting match, and to actively encourage the cooperation upon which Boost depends.</p> --- 186,192 ---- language, or abbreviations, they may not be understood by all readers. Re-read your message before submitting it.</p> ! <h2>Guidelines for Effective Discussions</h2> <p>Apply social engineering to prevent heated technical discussion from degenerating into a shouting match, and to actively encourage the cooperation upon which Boost depends.</p> -- Rob Stewart stewart@sig.com Software Engineer http://www.sig.com Susquehanna International Group, LLP using std::disclaimer;
Rob Stewart <stewart@sig.com> writes:
From: David Abrahams <dave@boost-consulting.com>
Rob Stewart <stewart@sig.com> writes:
Well, my intention is to make things clear, but not to make people write/speak unnaturally. I don't want to be heavyhanded about this. I would like to see one other person agree with you that it's a good idea before including it in the document.
I've heard from no one for or against my ideas, or yours for that matter. Does anyone have an opinion on how this should be codified? What do you think should be the official naming convention?
I don't have an opinion; I don't think we need an official naming convention. I just want people to distinguish accepted from proposed libraries in their speaking and writing. No need to make a big production of it.
It seems I took the ideas of the original discussion too far. The consensus seems to be that folks just want to make sure a library isn't named as if it's part of Boost, but they don't care too much how that's done.
Let me know what you think should be our naming requirements. Once we reach consensus, I'll create a diff for more/discussion_policy.htm to capture them.
The requirements should be "distinguish accepted boost libraries from things someone hopes will be in Boost, someday." Beyond that, I don't care.
Here's my take, then: _____________________________________________________ Library Names
Please avoid confusion between libraries that have been accepted by Boost and those that have not. Here are some suggested approaches to accomplish that (the first one is probably your best choice):
* the LibName library * the proposed Boost.LibName library * the candidate Boost.LibName library * the your adjective here Boost.LibName library
Note that this naming only applies to discussions, not to the documentation, directory structure, or even identifiers in the code.
It was a good start. I mangled it (sorry ;->) and then checked in / uploaded. Hope you like my changes. -- Dave Abrahams Boost Consulting www.boost-consulting.com
Arkadiy Vertleyb wrote:
"Rob Stewart" <stewart@sig.com> wrote
So, the question remains: Is "Boost Candidate.Name" instead of "Boost.Name" a good idea in message traffic prior to acceptance?
What about just "Name" ?
It may not be clear from "Name" that it represents a library (e.g. "FSM"); or it may not be clear which library is intended (e.g. "iostreams" or "algorithms" could refer to a boost library or a standard library). Libraries with disctinctive names, such as Spirit, don't have this problems. But consider the candidate Boost Interfaces library (which started this discussion). If I write: "I'm working to make Interfaces easier to use" many people might have no idea that I'm talking about a specific library under development. But if I say "I'm working to make the candidate Boost Interfaces library easier to use" it's perfectly clear. Jonathan
Jonathan Turkanis wrote:
Arkadiy Vertleyb wrote:
"Rob Stewart" <stewart@sig.com> wrote
So, the question remains: Is "Boost Candidate.Name" instead of "Boost.Name" a good idea in message traffic prior to acceptance?
What about just "Name" ?
It may not be clear from "Name" that it represents a library (e.g. "FSM"); or it may not be clear which library is intended (e.g. "iostreams" or "algorithms" could refer to a boost library or a standard library).
Libraries with disctinctive names, such as Spirit, don't have this problems. But consider the candidate Boost Interfaces library (which started this discussion). If I write:
"I'm working to make Interfaces easier to use"
many people might have no idea that I'm talking about a specific library under development. But if I say
"I'm working to make the candidate Boost Interfaces library easier to use"
it's perfectly clear.
Yes it's clear.. But so is what I would think most people would write if they did not use the Boost label: "I'm working to make Interfaces Library easier to use" So even though I agree that using just "Name" is not effectual.. I also don't think removing "Boost" deprives anyone of accurately communicating what they are talking about. -- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org - grafik/redshift-software.com - 102708583/icq
Rene Rivera <grafik.list@redshift-software.com> writes:
Yes it's clear.. But so is what I would think most people would write if they did not use the Boost label:
"I'm working to make Interfaces Library easier to use"
So even though I agree that using just "Name" is not effectual.. I also don't think removing "Boost" deprives anyone of accurately communicating what they are talking about.
True. At least for libs with a single author, "Joe's Interfaces library" works pretty well. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
Rene Rivera <grafik.list@redshift-software.com> writes:
Yes it's clear.. But so is what I would think most people would write if they did not use the Boost label:
"I'm working to make Interfaces Library easier to use"
So even though I agree that using just "Name" is not effectual.. I also don't think removing "Boost" deprives anyone of accurately communicating what they are talking about.
True. At least for libs with a single author, "Joe's Interfaces library" works pretty well.
You mean we're back to Uncle Jonathan's Home-Style Interface library? Jonathan
"Jonathan Turkanis" <technews@kangaroologic.com> writes:
David Abrahams wrote:
When discussing libraries in public that are under development but not yet accepted into Boost, I think it's problematic to refer to "The Boost <whatever> library" or "Boost.<whatever>" without qualification. Our peer-review process is respected, and these libraries are not yet officially blessed by Boost. I don't want to dilute the value of Boost acceptance. Can we please make a habit of prepending "The proposed" or something similar? For example, I suggest "The proposed Boost Interfaces library.
I understand the problem. With the interfaces library, the documentation contains a prominent disclaimer, and so does every source file.
That's more that I would normally ask for.
I can't think of anything better right now, but to me "proposed" suggests that the libray is in the review queue.
I don't know why. "Proposed" might mean it's just a glimmer in someone's eye. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
"Jonathan Turkanis" <technews@kangaroologic.com> writes:
I can't think of anything better right now, but to me "proposed" suggests that the libray is in the review queue.
I don't know why. "Proposed" might mean it's just a glimmer in someone's eye.
"At the moment it's just a notion, but with a bit of backing I think I could turn it into concept, and then an idea." Here are some other suggestions: - contemplated ("the contemplated database library") - suggested ("the suggested process control library") - planned ("the planned sockets library") - proposed ("the proposed typeof library") - prophesied ("the prophesied big int library") - fantasized ("the fantasized GUI library") Let me say that I did not intend to dillute the Boost name; in fact, I thought I was being extraordinarily careful. Jonathan
"Jonathan Turkanis" <technews@kangaroologic.com> writes:
David Abrahams wrote:
"Jonathan Turkanis" <technews@kangaroologic.com> writes:
I can't think of anything better right now, but to me "proposed" suggests that the libray is in the review queue.
I don't know why. "Proposed" might mean it's just a glimmer in someone's eye.
"At the moment it's just a notion, but with a bit of backing I think I could turn it into concept, and then an idea."
Not everyone knows all the key lines from Annie Hall by heart ;-)
Here are some other suggestions:
- contemplated ("the contemplated database library") - suggested ("the suggested process control library") - planned ("the planned sockets library") - proposed ("the proposed typeof library") - prophesied ("the prophesied big int library") - fantasized ("the fantasized GUI library")
Let me say that I did not intend to dillute the Boost name; in fact, I thought I was being extraordinarily careful.
I understand; to have put all those disclaimers in the docs and code, you must have been extraordinarily careful. And I didn't mean to pick on you. There have been _many_ other examples. It was just time to say something about it. I'm pretty happy with the idea of leaving out the word "Boost" until a library is accepted, FWIW, if we can agree to it. -- Dave Abrahams Boost Consulting www.boost-consulting.com
Jonathan Turkanis wrote:
David Abrahams wrote:
"Jonathan Turkanis" <technews@kangaroologic.com> writes:
I can't think of anything better right now, but to me "proposed" suggests that the libray is in the review queue.
I don't know why. "Proposed" might mean it's just a glimmer in someone's eye.
"At the moment it's just a notion, but with a bit of backing I think I could turn it into concept, and then an idea."
Here are some other suggestions:
- contemplated ("the contemplated database library") - suggested ("the suggested process control library") - planned ("the planned sockets library") - proposed ("the proposed typeof library") - prophesied ("the prophesied big int library") - fantasized ("the fantasized GUI library")
Let me say that I did not intend to dillute the Boost name; in fact, I thought I was being extraordinarily careful.
- candidate (IMO, is the right word) Cheers, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
David Abrahams wrote:
"Jonathan Turkanis" <technews@kangaroologic.com> writes:
I can't think of anything better right now, but to me "proposed" suggests that the libray is in the review queue.
I don't know why. "Proposed" might mean it's just a glimmer in someone's eye.
Prior to boost, I didn't even place Spirit in boost's namespace to avoid confusion. At the time, when mentioning boost, I say that Spirit is a "boost candidate". Prior to boost, Spirit was called just Spirit. Now, it's called Boost.Spirit. The pre-catenation gave it special meaning. :-) Cheers, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
Joel de Guzman wrote:
David Abrahams wrote:
"Jonathan Turkanis" <technews@kangaroologic.com> writes:
I can't think of anything better right now, but to me "proposed" suggests that the libray is in the review queue.
I don't know why. "Proposed" might mean it's just a glimmer in someone's eye.
Prior to boost, I didn't even place Spirit in boost's namespace to avoid confusion.
Using the boost namespace prior to acceptance may help to detect naming conflicts early in some cases.
At the time, when mentioning boost, I say that Spirit is a "boost candidate".
Sounds reasonable.
Prior to boost, Spirit was called just Spirit.
Not everyone can think of suich cool names, though ;-)
Now, it's called Boost.Spirit. The pre-catenation gave it special meaning. :-)
Jonathan
David Abrahams wrote:
Can we please make a habit of prepending "The proposed" or something similar? For example, I suggest "The proposed Boost Interfaces library."
Thanks!
P.S. I hope it's obvious, but I don't think the documentation for the proposed library ought to resort to such contortions.
Although having the library docs have a note saying that it's a proposed library would be nice. And including some indication of where in the review process it's at, like if it's planned to be reviewed, or just mentioned on the list, etc. -- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org - grafik/redshift-software.com - 102708583/icq
David Abrahams wrote:
When discussing libraries in public that are under development but not yet accepted into Boost, I think it's problematic to refer to "The Boost <whatever> library" or "Boost.<whatever>" without qualification. Our peer-review process is respected, and these libraries are not yet officially blessed by Boost. I don't want to dilute the value of Boost acceptance. Can we please make a habit of prepending "The proposed" or something similar? For example, I suggest "The proposed Boost Interfaces library."
Thanks!
P.S. I hope it's obvious, but I don't think the documentation for the proposed library ought to resort to such contortions.
FWIW, it would probably be trivial to support this distinction in QuickBook. One possibility would be adding a "doc_approval_date" member to the grammar, so that whenever "doc_approval_date" is left unspecified QuickBook can add a variety of consistent indications that the library is still at the "proposed" stage. We could even support generating "beta" versions of the docs with such warnings disabled... And this wouldn't require any contortions on the part of the proposed library's author (presuming, of course, that they are using QuickBook for documentation ;) )! - james -- __________________________________________________________ James Fowler, Open Sea Consulting http://www.OpenSeaConsulting.com, Marietta, Georgia, USA Do C++ Right. http://www.OpenCpp.org, opening soon!
participants (11)
-
Arkadiy Vertleyb -
christopher diggins -
David Abrahams -
Don G -
James Fowler -
Jeff Garland -
Joel de Guzman -
Jonathan Turkanis -
Rene Rivera -
Rob Stewart -
troy d. straszheim