Dot in Boost Library Names?
[Background for those who don't know: a. when you write a book, the publisher sicks (or is it sics?) a copyeditor on your manuscript to clean up all the bad grammar, stylistic fauxes pas, and so on. To reject a change you mark it with "stet". b. Boost decided long ago, for reasons I don't recall, on a convention of writing library names with a period after Boost, as in: Boost.Python ] When the copyeditor went over the manuscript for C++ Template Metaprogramming, she very consistently took out the periods in library names like Boost.Python, Boost.Bind, etc. Her changes didn't seem to hurt the book seriously so rather than laboriously "stet" them all, I just let it go. I'm writing a foreword for Bjorn's book soon, so he sent me his manuscript. Bjorn consistently uses a different notation. I thought it made sense for us to get our story straight on how these names will be represented in publications. These were my ideas: - The names will be set in roman type - The library name will be capitalized - The period will only be used when the library name is not followed by the word "library": The great thing about Boost.Bind is that you can use it with member functions and function objects. The Boost Bind library was written by Peter Dimov. - The word "library" is not part of the library name and is therefore lowercased. Among the moderators and authors everyone agreed with the ideas, except that there was some discussion of whether and how the dot should be used. Some argued for never using the dot; some for always using it. An informal -1,0,1 poll was inconclusive: -1 votes +1 votes -------- -------- Never | 1 3 Always Except Before Library | 2 3 Always | 1 2 We all thought it would be a good idea to get feedback from the whole Boost community, **but I don't want this to suck up a lot of list bandwidth**, so I'm going to close voting at the end of 9/16 (my time). If you care how this comes out, please post your -1,0,+1 votes on the three options above. Please copy this part of the message into your reply and vote there: Never: Always Except Before Library: Always: This is a seemingly trivial issue that hardly deserves as much attention as we've already given it, so I'm crossing my fingers that we won't enter a bike shed with it ;-) Thanks, -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
David Abrahams wrote:
[...]
Never: -1 Always Except Before Library: +1 Always: 0
My vote: ^^^
This is a seemingly trivial issue that hardly deserves as much attention as we've already given it, so I'm crossing my fingers that we won't enter a bike shed with it ;-)
I think the bike shed should be yellow, and have a skylight. ;> Dave
David Abrahams wrote:
b. Boost decided long ago, for reasons I don't recall, on a convention of writing library names with a period after Boost, as in:
Boost.Python
In case someone else remembers I'd be interested in the rationale for that choice. After all, boost is about C++ with many libraries ending up as candidates for standardization, so it strikes me as odd to start names with an uppercase letter and to have something else than the double colon as a separator. Regards, Andreas
"Andreas Huber" <ah2003@gmx.net> writes:
David Abrahams wrote:
b. Boost decided long ago, for reasons I don't recall, on a convention of writing library names with a period after Boost, as in:
Boost.Python
In case someone else remembers I'd be interested in the rationale for that choice. After all, boost is about C++ with many libraries ending up as candidates for standardization, so it strikes me as odd to start names with an uppercase letter and to have something else than the double colon as a separator.
These are not C++ identifiers; they're names. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
David Abrahams <dave <at> boost-consulting.com> writes:
These are not C++ identifiers; they're names.
To me, this isn't a very good rationale but since we're already discussing that dreaded bicycle shed I won't argue any further ;-). Regards, Andreas
David Abrahams wrote:
In case someone else remembers I'd be interested in the rationale for that choice. After all, boost is about C++ with many libraries ending up as candidates for standardization, so it strikes me as odd to start names with an uppercase letter and to have something else than the double colon as a separator.
These are not C++ identifiers; they're names.
David.Abrahams Boost.Consulting Kresimir.Fresl Faculty.Of.Civil.Engineering Sorry. Can't resist.
Kresimir Fresl wrote:
[...] David.Abrahams Boost.Consulting
Kresimir.Fresl Faculty.Of.Civil.Engineering
Sorry. Can't resist.
Shouldn't that be: "Sorry.Can'tResist"? ;> MPL "is-a-member-of" Boost. Hence, "Boost.MPL". Abrahams "is-not-a-member-of" David. Hence, "David Abrahams". I see the dot operator as the member selection operator, which is why it seemed perfectly natural to me to name libraries with that format. Dave
David B. Held wrote:
Kresimir Fresl wrote:
[...] David.Abrahams Boost.Consulting
Kresimir.Fresl Faculty.Of.Civil.Engineering
Sorry. Can't resist.
Shouldn't that be: "Sorry.Can'tResist"? ;>
"Sorry. Can't resist." is not a name.
MPL "is-a-member-of" Boost. Hence, "Boost.MPL".
Abrahams "is-not-a-member-of" David. Hence, "David Abrahams".
I see the dot operator as the member selection operator, which is why it seemed perfectly natural to me to name libraries with that format.
Dave Abrahams wrote:
These are not C++ identifiers; they're names.
fres
Kresimir Fresl <fresl@master.grad.hr> writes:
David Abrahams wrote:
In case someone else remembers I'd be interested in the rationale for that choice. After all, boost is about C++ with many libraries ending up as candidates for standardization, so it strikes me as odd to start names with an uppercase letter and to have something else than the double colon as a separator.
These are not C++ identifiers; they're names.
David.Abrahams Boost.Consulting
Kresimir.Fresl Faculty.Of.Civil.Engineering
Sorry. Can't resist.
His question was analogous to asking why we don't write david::abrahams. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
David Abrahams <dave <at> boost-consulting.com> writes:
His question was analogous to asking why we don't write david::abrahams.
I hope it is obvious that it wasn't. There are many differences between the name of the human David Abrahams and the name of a C++ library that happens to reside in a certain namespace. But really, I hope we agree that the bicycle shed has been discussed more than enough already. Regards, Andreas
Andreas Huber <ah2003@gmx.net> writes:
David Abrahams <dave <at> boost-consulting.com> writes:
His question was analogous to asking why we don't write david::abrahams.
I hope it is obvious that it wasn't.
For the record, if it were obvious to me I wouldn't have asserted otherwise.
There are many differences between the name of the human David Abrahams and the name of a C++ library that happens to reside in a certain namespace.
But really, I hope we agree that the bicycle shed has been discussed more than enough already.
Agreed. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
David Abrahams wrote:
Kresimir Fresl <fresl@master.grad.hr> writes:
David Abrahams wrote: [...]
These are not C++ identifiers; they're names.
David.Abrahams [...]
His question was analogous to asking why we don't write david::abrahams.
No -- as far as I know, we write neither david::abrahams nor David.Abrahams. fres
Kresimir Fresl <fresl@master.grad.hr> writes:
David Abrahams wrote:
Kresimir Fresl <fresl@master.grad.hr> writes:
David Abrahams wrote: [...]
These are not C++ identifiers; they're names.
David.Abrahams [...]
His question was analogous to asking why we don't write david::abrahams.
No -- as far as I know, we write neither david::abrahams nor David.Abrahams.
Fair enough; he asked "why do we use a dot?" and "why don't we use scope resolution and lowercase?" The second question is the analogous one. I don't have an answer for the first one (or a position on whether dotting is good), other than -- as I wrote in my original message -- that there's historical precedent. That question was already answered as well as I know how, and when you "couldn't resist" -- which, BTW, I didn't appreciate -- I only tried to explain the reasons that the scope resolution operator and lowercase was inappropriate. not-justifying-the-dot-ly y'rs, -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
--- David Abrahams <dave@boost-consulting.com> wrote:
These were my ideas: [snip] - The word "library" is not part of the library name and is therefore lowercased.
All these years we've been spelling "Boost Graph Library" wrong?! Oh, well. Never: -1 Always Except Before Library: +1 Always: 0 Cromwell Enage _______________________________ Do you Yahoo!? Declare Yourself - Register online to vote today! http://vote.yahoo.com
"David Abrahams" <dave@boost-consulting.com> wrote in message news:ud60osh87.fsf@boost-consulting.com... | time). If you care how this comes out, please post your -1,0,+1 votes | on the three options above. Please copy this part of the message into | your reply and vote there: | | Never: | Always Except Before Library: | Always: never: 0 always before...: +1 always : -1 br Thorsten
"David Abrahams" <dave@boost-consulting.com> wrote:
These were my ideas:
- The names will be set in roman type
- The library name will be capitalized
- The period will only be used when the library name is not followed by the word "library":
time). If you care how this comes out, please post your -1,0,+1 votes
I'm too stupid or tired to figure out the voting convention, so I will state my opinion in English: - The dot convention is useful, as long as it can be applied to all boost libraries. Currently it works only with those with one-word names or which have standard nicknames or abbreviations: Boost.SmartPtr Boost.Regex Boost.Type Traits // Looks funny, but Boost.TypeTraits would work Boost.Greatest Common Divisor Least Common Multiple // ??? If the dotted versions of Boost library names will be appearing in books with some frequency, all libraries with multi-word names must be given some official abbreviation. E.g., Greatest Common Divisor Least Common Multiple could be 'Boost.GCD,' Boost.Gcd', 'Boost.GcdLcm' or something else. - The word 'library' should be omitted when the dot is used. - When not using the dot, 'library' should be capitalized. Otherwise, the name of the library has the feeling of an adjective, which is very strange to my ears: the *Boost Bind* library. Putting 'library' first sounds much better: The library Boost Bind. Best Regards, Jonathan
"Jonathan Turkanis" <technews@kangaroologic.com> writes:
- The dot convention is useful, as long as it can be applied to all boost libraries. Currently it works only with those with one-word names or which have standard nicknames or abbreviations:
Boost.SmartPtr Boost.Regex Boost.Type Traits // Looks funny,
Looks okay to me.
Boost.Greatest Common Divisor Least Common Multiple // ???
That looks funny even without the dot. The library name is too long.
If the dotted versions of Boost library names will be appearing in books with some frequency, all libraries with multi-word names must be given some official abbreviation. E.g., Greatest Common Divisor Least Common Multiple could be 'Boost.GCD,' Boost.Gcd', 'Boost.GcdLcm' or something else.
For these libraries, that's probably a good idea anyway. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
"Jonathan Turkanis" <technews@kangaroologic.com> writes:
"David Abrahams" <dave@boost-consulting.com> wrote:
These were my ideas:
- The names will be set in roman type
- The library name will be capitalized
- The period will only be used when the library name is not followed by the word "library":
time). If you care how this comes out, please post your -1,0,+1 votes
I'm too stupid or tired to figure out the voting convention, so I will state my opinion in English:
- The dot convention is useful, as long as it can be applied to all boost libraries. Currently it works only with those with one-word names or which have standard nicknames or abbreviations:
Boost.SmartPtr Boost.Regex Boost.Type Traits // Looks funny, but Boost.TypeTraits would work Boost.Greatest Common Divisor Least Common Multiple // ???
If the dotted versions of Boost library names will be appearing in books with some frequency, all libraries with multi-word names must be given some official abbreviation. E.g., Greatest Common Divisor Least Common Multiple could be 'Boost.GCD,' Boost.Gcd', 'Boost.GcdLcm' or something else.
- The word 'library' should be omitted when the dot is used.
- When not using the dot, 'library' should be capitalized. Otherwise, the name of the library has the feeling of an adjective, which is very strange to my ears: the *Boost Bind* library. Putting 'library' first sounds much better: The library Boost Bind.
Jonathan, Do you want to make a numeric vote, or should I just discard this information? I don't want to misread it, and it doesn't seem to take a definite position on the questions being polled. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
At the risk of discussing the bicycle shed, what about using the scope resolution operator? That, at least, would not be misconstrued by a copyeditor and would be in keeping with C++ syntax. Should that be rejected soundly, here's my vote on the period: Never: -1 Always Except Before Library: 0 Always: 1 -- Rob Stewart stewart@sig.com Software Engineer http://www.sig.com Susquehanna International Group, LLP using std::disclaimer;
Rob Stewart <stewart@sig.com> writes:
At the risk of discussing the bicycle shed, what about using the scope resolution operator? That, at least, would not be misconstrued by a copyeditor and would be in keeping with C++ syntax.
IMO it's very important to distinguish those things that are supposed to have meaning in code from those that are not. Using strongly C++-like syntax here would be confusing, since these things are not identifiers.
Should that be rejected soundly, here's my vote on the period:
Never: -1 Always Except Before Library: 0 Always: 1
-- Rob Stewart stewart@sig.com Software Engineer http://www.sig.com Susquehanna International Group, LLP using std::disclaimer; _______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
-- Dave Abrahams Boost Consulting http://www.boost-consulting.com
From: David Abrahams <dave@boost-consulting.com>
Rob Stewart <stewart@sig.com> writes:
At the risk of discussing the bicycle shed, what about using the scope resolution operator? That, at least, would not be misconstrued by a copyeditor and would be in keeping with C++ syntax.
IMO it's very important to distinguish those things that are supposed to have meaning in code from those that are not. Using strongly C++-like syntax here would be confusing, since these things are not identifiers.
Isn't that an argument against using the dot, too? I presumed it was the member selection operator as someone else pointed out. Also, my point was that *if* we use C++ notation -- assumed, I'll admit -- to join the parts, then the scope resolution operator is more appropriate. -- 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:
At the risk of discussing the bicycle shed, what about using the scope resolution operator? That, at least, would not be misconstrued by a copyeditor and would be in keeping with C++ syntax.
IMO it's very important to distinguish those things that are supposed to have meaning in code from those that are not. Using strongly C++-like syntax here would be confusing, since these things are not identifiers.
Isn't that an argument against using the dot, too?
Yes. Set in roman type and with caps on the library name it is less confusable and more like a Boost-trademark typographical convention, but yes it's still confusable. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
Rob Stewart wrote:
From: David Abrahams <dave@boost-consulting.com>
[...] IMO it's very important to distinguish those things that are supposed to have meaning in code from those that are not. Using strongly C++-like syntax here would be confusing, since these things are not identifiers.
Isn't that an argument against using the dot, too? I presumed it was the member selection operator as someone else pointed out.
Also, my point was that *if* we use C++ notation -- assumed, I'll admit -- to join the parts, then the scope resolution operator is more appropriate.
I would say that the "dot operator" definitely does not constitute "strongly C++-like syntax", since several other languages use it as well, to mean roughly the same thing (at least Java and VB, which are both fairly different from C++ and each other). So the dot operator seems to me to have a somewhat language-neutral connotation that most programmers in general intuitively understand, while the scope resolution operator smacks strongly of C++ to most people who see it, I suspect. Also, the period is used as a stylistic separator in other contexts, as well. E.g.: 320.555.2839 (phone numbers, IP addresses, filename extensions, etc.) One would be hard-pressed to find a single other use of :: outside of the programming realm. Dave
"David B. Held" <dheld@codelogicconsulting.com> writes:
Rob Stewart wrote:
From: David Abrahams <dave@boost-consulting.com>
[...] IMO it's very important to distinguish those things that are supposed to have meaning in code from those that are not. Using strongly C++-like syntax here would be confusing, since these things are not identifiers. Isn't that an argument against using the dot, too? I presumed it was the member selection operator as someone else pointed out. Also, my point was that *if* we use C++ notation -- assumed, I'll admit -- to join the parts, then the scope resolution operator is more appropriate.
I would say that the "dot operator" definitely does not constitute "strongly C++-like syntax", since several other languages use it as well, to mean roughly the same thing (at least Java and VB, which are both fairly different from C++ and each other). So the dot operator seems to me to have a somewhat language-neutral connotation that most programmers in general intuitively understand, while the scope resolution operator smacks strongly of C++ to most people who see it, I suspect.
Also, the period is used as a stylistic separator in other contexts, as well. E.g.: 320.555.2839 (phone numbers, IP addresses, filename extensions, etc.) One would be hard-pressed to find a single other use of :: outside of the programming realm.
If I'd had the time, that's what I would've said ;-) -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
Rob Stewart <stewart <at> sig.com> writes:
At the risk of discussing the bicycle shed, what about using the scope resolution operator? That, at least, would not be misconstrued by a copyeditor and would be in keeping with C++ syntax.
I had that opinion also until I realized that some boost libraries (like e.g. smart_ptr, thread, etc.) do not reside in their own namespace. So, it would be confusing to write boost::thread or boost::smart_ptr when refering to one of these libraries in a book. Regards, Andreas
From: Andreas Huber <ah2003@gmx.net>
Rob Stewart <stewart <at> sig.com> writes:
At the risk of discussing the bicycle shed, what about using the scope resolution operator? That, at least, would not be misconstrued by a copyeditor and would be in keeping with C++ syntax.
I had that opinion also until I realized that some boost libraries (like e.g. smart_ptr, thread, etc.) do not reside in their own namespace. So, it would be confusing to write boost::thread or boost::smart_ptr when refering to one of these libraries in a book.
I'm confused. Those references to the libraries would be spelled Boost::SmartPtr (or whatever) and Boost::Thread, right? -- Rob Stewart stewart@sig.com Software Engineer http://www.sig.com Susquehanna International Group, LLP using std::disclaimer;
Rob Stewart wrote:
I'm confused. Those references to the libraries would be spelled Boost::SmartPtr (or whatever) and Boost::Thread, right?
That would be one possibility. However I think the double colon still hints too much in the direction that there is a namespace called Boost::Thread. Boosters of course know that namespace identifiers are lowercase, but an outsider maybe doesn't. Since we can't consistently name libs after the namespace they're residing in I now totally agree with Dave that we should choose a naming convention that has obviously nothing to do with C++ identifiers whatsoever. Plus, Dave's convention has the advantage that only very few people need to change the names in the docs/books, etc. Personally, I would have preferred boost::fsm a lot over Boost.FSM but it's not *that* important, is it? Regards, Andreas
Andreas Huber wrote:
[...] Plus, Dave's convention has the advantage that only very few people need to change the names in the docs/books, etc. Personally, I would have preferred boost::fsm a lot over Boost.FSM but it's not *that* important, is it?
The convention I use is that when talking about the entire library, go with Boost.LibraryName, and when talking about a specific component, use boost::component_name. That's because there's times when I want to talk about boost::bind() in particular, disregarding the other elements in the Boost.Bind library, and Boost libraries often contain a type that has the same name as the library, but also other types that one might want to talk about individually. Dave
"David B. Held" <dheld@codelogicconsulting.com> writes:
Andreas Huber wrote:
[...] Plus, Dave's convention has the advantage that only very few people need to change the names in the docs/books, etc. Personally, I would have preferred boost::fsm a lot over Boost.FSM but it's not *that* important, is it?
The convention I use is that when talking about the entire library, go with Boost.LibraryName, and when talking about a specific component, use boost::component_name. That's because there's times when I want to talk about boost::bind() in particular, disregarding the other elements in the Boost.Bind library, and Boost libraries often contain a type that has the same name as the library, but also other types that one might want to talk about individually.
I take the latter for granted. It wouldn't make any sense to refer to Boost.Bind when you really meant boost::bind. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
"Andreas Huber" <ah2003@gmx.net> writes:
Rob Stewart wrote:
I'm confused. Those references to the libraries would be spelled Boost::SmartPtr (or whatever) and Boost::Thread, right?
That would be one possibility. However I think the double colon still hints too much in the direction that there is a namespace called Boost::Thread. Boosters of course know that namespace identifiers are lowercase, but an outsider maybe doesn't. Since we can't consistently name libs after the namespace they're residing in I now totally agree with Dave that we should choose a naming convention that has obviously nothing to do with C++ identifiers whatsoever. Plus, Dave's convention has the advantage that only very few people need to change the names in the docs/books, etc.
Does that change your vote? -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
David Abrahams <dave <at> boost-consulting.com> writes:
"Andreas Huber" <ah2003 <at> gmx.net> writes:
That would be one possibility. However I think the double colon still hints too much in the direction that there is a namespace called Boost::Thread. Boosters of course know that namespace identifiers are lowercase, but an outsider maybe doesn't. Since we can't consistently name libs after the namespace they're residing in I now totally agree with Dave that we should choose a naming convention that has obviously nothing to do with C++ identifiers whatsoever. Plus, Dave's convention has the advantage that only very few people need to change the names in the docs/books, etc.
Does that change your vote?
I guess you ask because of the word "totally". Sorry, not *that* totally ;-). When I wrote "Dave's convention" I meant the one with captitalized names and one dot between the names (Boost.Python) as opposed to the one I preferred (boost::python). This has nothing to do with the vote. Regards, Andreas
Andreas Huber <ah2003@gmx.net> writes:
David Abrahams <dave <at> boost-consulting.com> writes:
"Andreas Huber" <ah2003 <at> gmx.net> writes:
That would be one possibility. However I think the double colon still hints too much in the direction that there is a namespace called Boost::Thread. Boosters of course know that namespace identifiers are lowercase, but an outsider maybe doesn't. Since we can't consistently name libs after the namespace they're residing in I now totally agree with Dave that we should choose a naming convention that has obviously nothing to do with C++ identifiers whatsoever. Plus, Dave's convention has the advantage that only very few people need to change the names in the docs/books, etc.
Does that change your vote?
I guess you ask because of the word "totally". Sorry, not *that* totally ;-). When I wrote "Dave's convention" I meant the one with captitalized names and one dot between the names (Boost.Python) as opposed to the one I preferred (boost::python). This has nothing to do with the vote.
Thanks for clarifying. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
David Abrahams <dave <at> boost-consulting.com> writes:
time). If you care how this comes out, please post your -1,0,+1 votes on the three options above. Please copy this part of the message into your reply and vote there:
Never: Always Except Before Library: Always:
Never: -1 Always Except Before Library: 0 Always: 1 Regards, Andreas
Here's the vote from the at-large membership: Never: -1 -1 -1 0 0 0 -1 -1 1 = -4 Always Except Before Library: +1 +1 +1 +1 +1 +1 0 0 0 = +6 Always: 0 0 0 -1 -1 -1 +1 +1 0 = -1 Even adding the votes from moderators and authors, this picture only changes slightly: Never: -2 Always Except Before Library: +7 Always: 0 I asked Jonathan Turkanis if he wanted to make a numeric vote, but now it's clear to me that it can't change anything significantly. This vote confirms my original suggestion: - Librfary names will be set in roman type - The library name will be capitalized - The period will only be used when the library name is not followed by the word "library". For example: The great thing about Boost.Bind is that you can use it with member functions and function objects. The Boost Bind library was written by Peter Dimov. - The word "library" is not part of the library name and is therefore lowercased. If anyone can suggest a good place (somewhere in http://www.boost.org/more/writingdoc/ probably) to put this information, I'd be indebted. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
"David Abrahams" <dave@boost-consulting.com> wrote in message:
I asked Jonathan Turkanis if he wanted to make a numeric vote, but now it's clear to me that it can't change anything significantly.
Thanks for the courtesy -- I'm just now reading my messages. Jonathan
participants (12)
-
Andreas Huber -
Cromwell Enage -
Daniel James -
David Abrahams -
David B. Held -
Jonathan Turkanis -
Jurko Gospodnetic -
Kresimir Fresl -
Michael van der Westhuizen -
Rob Stewart -
Stefan Slapeta -
Thorsten Ottosen