I've just finished my 2nd rewrite of the Boost Getting Started Guide. The quality of this crucial document shapes our users' first experiences with Boost, and for many, determines whether they use Boost or give up in frustration. I really need feedback on what I've done, **especially from experienced Boosters** who can vett my statements for accuracy. I have already received some really valuable input from this group and poured it into this 2nd rewrite. There were, however, quite a few problems I discovered by chance through communications with experienced Boosters who haven't given me feedback on the guide. I'm wonder what problems I'm still missing, and I hope you can tell me. You can review the guide at http://www.boost-consulting.com/boost/more/getting_started.html. Thank you for your time, -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams <dave@boost-consulting.com> writes:
You can review the guide at http://www.boost-consulting.com/boost/more/getting_started.html.
In the Unix section for built libraries, your example library is named as if it was built using msvc: c++ -I /path/to/boost_1_34_0 example.cpp -o example \ ~/boost/lib/libboost_regex-msvc-7.1-mt-d-1_34.a I would imagine that something more likely to appear on a Unix/Linux system, such as libboost_regex-gcc-3.4-mt-d-1_34.a would be a better example. Anthony -- Anthony Williams Software Developer Just Software Solutions Ltd http://www.justsoftwaresolutions.co.uk
Anthony Williams <anthony_w.geo@yahoo.com> writes:
David Abrahams <dave@boost-consulting.com> writes:
You can review the guide at http://www.boost-consulting.com/boost/more/getting_started.html.
In the Unix section for built libraries, your example library is named as if it was built using msvc:
c++ -I /path/to/boost_1_34_0 example.cpp -o example \ ~/boost/lib/libboost_regex-msvc-7.1-mt-d-1_34.a
Thanks, but I think you need to refresh your browser. That string is not in the document anymore. -- Dave Abrahams Boost Consulting www.boost-consulting.com
Anthony Williams wrote:
In the Unix section for built libraries, your example library is named as if it was built using msvc:
c++ -I /path/to/boost_1_34_0 example.cpp -o example \ ~/boost/lib/libboost_regex-msvc-7.1-mt-d-1_34.a
I would imagine that something more likely to appear on a Unix/Linux system, such as libboost_regex-gcc-3.4-mt-d-1_34.a would be a better example.
I personally just type g++ example.cpp -o example -lboost_regex
Mathias Gaunard <mathias.gaunard@etu.u-bordeaux1.fr> writes:
Anthony Williams wrote:
In the Unix section for built libraries, your example library is named as if it was built using msvc:
c++ -I /path/to/boost_1_34_0 example.cpp -o example \ ~/boost/lib/libboost_regex-msvc-7.1-mt-d-1_34.a
I would imagine that something more likely to appear on a Unix/Linux system, such as libboost_regex-gcc-3.4-mt-d-1_34.a would be a better example.
I personally just type g++ example.cpp -o example -lboost_regex
You must have used some other method of producing binaries than we use in the Getting Started Guide (e.g. method 3 at http://boost-consulting.com/boost/more/getting_started.html#get-boost). That command wouldn't work with libraries produced using the default "versioned" layout. -- Dave Abrahams Boost Consulting www.boost-consulting.com
----- Mensaje original ----- De: David Abrahams <dave@boost-consulting.com> Fecha: Lunes, Diciembre 11, 2006 9:57 pm Asunto: [boost] Attention Boosters Para: boost@lists.boost.org
I've just finished my 2nd rewrite of the Boost Getting Started Guide. The quality of this crucial document shapes our users' first experiences with Boost, and for many, determines whether they use Boost or give up in frustration.
A couple of minutia: 1 "Header organization" sidenote: I tend to parse the sentence "Don't look in these directories and expect to find anything you can use" as "(Don't look ...) and (expect to find ...)" rather than the intended "Don't (look ... and expect to find ...)". If I'm not the only misparser, I'd suggest an unambiguous rewriting. 3. Section 6.3: "or you're a *nix user who wants want to build..." Joaquín M López Muñoz Telefónica, Investigación y Desarrollo
"JOAQUIN LOPEZ MU?Z" <joaquin@tid.es> writes:
----- Mensaje original ----- De: David Abrahams <dave@boost-consulting.com> Fecha: Lunes, Diciembre 11, 2006 9:57 pm Asunto: [boost] Attention Boosters Para: boost@lists.boost.org
I've just finished my 2nd rewrite of the Boost Getting Started Guide. The quality of this crucial document shapes our users' first experiences with Boost, and for many, determines whether they use Boost or give up in frustration.
A couple of minutia:
1 "Header organization" sidenote: I tend to parse the sentence "Don't look in these directories and expect to find anything you can use" as "(Don't look ...) and (expect to find ...)" rather than the intended "Don't (look ... and expect to find ...)". If I'm not the only misparser, I'd suggest an unambiguous rewriting.
3. Section 6.3: "or you're a *nix user who wants want to build..."
All fixed, thanks. -- Dave Abrahams Boost Consulting www.boost-consulting.com
Thing that is bothering me: " doc/ ...............A subset of all Boost library docs" ^^^^^^ why it's a subset? I want all documentation for my freshly downloaded boost. 1. Are some libraries undocumented? 2. Is their documentation placed elsewhere? Where? Oh I see the point "4. Don't be distracted by the doc/ subdirectory... Start with libs/index.html". This explains a bit, but better not to have to explain anything. I opt for ,,merging'' doc/ and libs/index.html. So that a causal downloader will have an access to *whole* documentation from doc/index. It could be done as simply as copying libs/index.html to doc/index.html I guess that doc/ is a documentation written in a new format, and the documentation in libs/ uses old format. So this doc/index.html will stay there until the rest of documentation is converted to new format (if ever). It's just for convenience. Also I noticed that the redirections are wrong in *many* documentation files. For example - a person without a network connection, but with downloaded and installed boost opens a file doc/html/any.html and what happens? A failed redirection to http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/any.html This file should contain a redirection to locally instaled file. Maybe this is out of the scope of your post, but this difficulty in browsing documentation always annoyed me, when the network was slow or down. -- Janek Kozicki |
Janek Kozicki wrote:
Also I noticed that the redirections are wrong in *many* documentation files. For example - a person without a network connection, but with downloaded and installed boost opens a file doc/html/any.html and what happens?
A failed redirection to http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/any.html
This file should contain a redirection to locally instaled file.
I am pretty sure this is only because you are viewing it in a preliminary stage. Usually there are placeholder stubs until the whole documentation set is being built. In a normal release these files should be local. Roland
Roland Schwarz said: (by the date of Mon, 11 Dec 2006 23:10:28 +0100)
This file should contain a redirection to locally instaled file.
I am pretty sure this is only because you are viewing it in a preliminary stage. Usually there are placeholder stubs until the whole documentation set is being built. In a normal release these files should be local.
Yes, it's a CVS HEAD checkout. Can you tell me how to build this documentation, or point where to look, to learn that? -- Janek Kozicki |
Janek Kozicki <janek_listy@wp.pl> writes:
Thing that is bothering me:
" doc/ ...............A subset of all Boost library docs" ^^^^^^
why it's a subset? I want all documentation for my freshly downloaded boost.
You get it; that directory just happens to be a subset. The point is to keep people from looking there, as they often do, for complete documentation.
1. Are some libraries undocumented? 2. Is their documentation placed elsewhere? Where?
Oh I see the point "4. Don't be distracted by the doc/ subdirectory... Start with libs/index.html". This explains a bit, but better not to have to explain anything.
Yes it would be much better. Too bad; we have a misleading directory structure.
I opt for ,,merging'' doc/ and libs/index.html. So that a causal downloader will have an access to *whole* documentation from doc/index. It could be done as simply as copying libs/index.html to doc/index.html
You think that if I look in doc/ and see documentation files for about 10 libraries, the presence of an index file whose contents I might never even look at is going to leave me less confused?
I guess that doc/ is a documentation written in a new format, and the documentation in libs/ uses old format. So this doc/index.html will stay there until the rest of documentation is converted to new format (if ever).
It's just for convenience.
I would use a redirect if I didn't want it to be massively inconvenient for developers/maintainers.
Also I noticed that the redirections are wrong in *many* documentation files. For example - a person without a network connection, but with downloaded and installed boost opens a file doc/html/any.html and what happens?
It goes to the Boost website, IIRC. I'm sorry, but if there *is* a problem here, it is not an area I'm trying to address right now. I just need to get the Getting Started document in shape. For anything outside that scope, if you would step up and address it yourself I and the whole community would be grateful.
A failed redirection to http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/any.html
This file should contain a redirection to locally instaled file.
I think what you get in a Boost distro is slightly different from what's in the CVS. Try downloading the 1.33.1 distro... but anyway, really, I can't focus on this issue right now.
Maybe this is out of the scope of your post, but this difficulty in browsing documentation always annoyed me, when the network was slow or down.
Understood. Please volunteer to help fix problems in this area; I really would appreciate it. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams said: (by the date of Mon, 11 Dec 2006 18:01:23 -0500)
Janek Kozicki <janek_listy@wp.pl> writes:
Oh I see the point "4. Don't be distracted by the doc/ subdirectory... Start with libs/index.html". This explains a bit, but better not to have to explain anything.
Yes it would be much better. Too bad; we have a misleading directory structure.
I see that this subset is a quickbook documentation. Maybe simply rename directory doc/ into qbk_doc/ or quickbook.doc/ or doc.qbk/ or something that will indicate that it's that new format? I think that with this name the directory structure will be less misleading. Consider this: boost_1_34_0/ .................The "boost root directory" index.htm .........A copy of www.boost.org starts here boost/ .........................All Boost Header files libs/ ..........Documentation, .cpps, etc., by library * index.html ........Library documentation starts here (1) algorithm/ any/ array/ ...more libraries... status/ .........................Boost-wide test suite tools/ ...........Utilities, e.g. bjam, quickbook, bcp more/ ..........................Policy documents, etc. doc.qbk/ ...............A subset of Boost library docs * '*' marks modified lines. I removed "Tests" because I felt that you wanted to keep below 80 columns, and because IMHO "Tests" is the least interesting for the target audience of this guide. This is only a suggestion. After reading this list third (or fourth) time I noticed the line (1). Was I blind before? I don't know, I wasn't seeing this earlier. Maybe just make the word "documentation" bold in (1) and disregard changes marked by '*'. I dunno.
Maybe this is out of the scope of your post, but this difficulty in browsing documentation always annoyed me, when the network was slow or down.
Understood. Please volunteer to help fix problems in this area; I really would appreciate it.
Yes I would, the problem I see is that after downloading from CVS, the quickbook docs have to be built (ie. they are not in place for offline browsing). The simplest solution is to add a short README file in this directory which will explain how to build the docs. I don't know how to build them :) If someone will tell me how to build qbk docs for offline browsing, I will gladly submit a patch with README file. -- Janek Kozicki |
Janek Kozicki <janek_listy@wp.pl> writes:
David Abrahams said: (by the date of Mon, 11 Dec 2006 18:01:23 -0500)
Janek Kozicki <janek_listy@wp.pl> writes:
Oh I see the point "4. Don't be distracted by the doc/ subdirectory... Start with libs/index.html". This explains a bit, but better not to have to explain anything.
Yes it would be much better. Too bad; we have a misleading directory structure.
I see that this subset is a quickbook documentation.
No, it's BoostBook.
Maybe simply rename directory doc/ into qbk_doc/ or quickbook.doc/ or doc.qbk/ or something that will indicate that it's that new format?
Renaming directories in CVS is not simple. That will have to wait until we transition to SVN. Anyway, again, this is outside the scope of what I'm trying to do with this document.
I think that with this name the directory structure will be less misleading. Consider this:
boost_1_34_0/ .................The "boost root directory" index.htm .........A copy of www.boost.org starts here boost/ .........................All Boost Header files libs/ ..........Documentation, .cpps, etc., by library * index.html ........Library documentation starts here (1) algorithm/ any/ array/ ...more libraries... status/ .........................Boost-wide test suite tools/ ...........Utilities, e.g. bjam, quickbook, bcp more/ ..........................Policy documents, etc. doc.qbk/ ...............A subset of Boost library docs *
'*' marks modified lines. I removed "Tests" because I felt that you wanted to keep below 80 columns, and because IMHO "Tests" is the least interesting for the target audience of this guide.
This is only a suggestion. After reading this list third (or fourth) time I noticed the line (1). Was I blind before? I don't know, I wasn't seeing this earlier.
Maybe just make the word "documentation" bold in (1) and disregard changes marked by '*'. I dunno.
Thanks for the suggestions. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
You can review the guide at http://www.boost-consulting.com/boost/more/getting_started.html.
C:\Program Files\boost\boost_1_34_0> bjam \ --build-dir=%TEMP%\build-boost \ --toolset=msvc stage is pretty odd. Even if it worked, and it doesn't, why would we want to split the line in such a way in the guide?
"Peter Dimov" <pdimov@mmltd.net> writes:
David Abrahams wrote:
You can review the guide at http://www.boost-consulting.com/boost/more/getting_started.html.
C:\Program Files\boost\boost_1_34_0> bjam \ --build-dir=%TEMP%\build-boost \ --toolset=msvc stage
is pretty odd. Even if it worked, and it doesn't,
What's wrong with it, please?
why would we want to split the line in such a way in the guide?
* In part, it was instinct. When writing C++TMP we had a 65-column limit for code samples * In order to avoid making it too wide to read without scrolling in all reasonably-sized browser windows. I really hate that. * The original version of the guide had one more sidebar, which would have collided with that text. I'm open to changes, though. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
"Peter Dimov" <pdimov@mmltd.net> writes:
David Abrahams wrote:
You can review the guide at http://www.boost-consulting.com/boost/more/getting_started.html.
C:\Program Files\boost\boost_1_34_0> bjam \ --build-dir=%TEMP%\build-boost \ --toolset=msvc stage
is pretty odd. Even if it worked, and it doesn't,
What's wrong with it, please?
How am I supposed to enter that? bjam \ <enter> executes "bjam \". \ is a valid path under Windows. What version of 'cmd' are you using that lets you splice lines in this way?
"Peter Dimov" <pdimov@mmltd.net> writes:
David Abrahams wrote:
"Peter Dimov" <pdimov@mmltd.net> writes:
David Abrahams wrote:
You can review the guide at http://www.boost-consulting.com/boost/more/getting_started.html.
C:\Program Files\boost\boost_1_34_0> bjam \ --build-dir=%TEMP%\build-boost \ --toolset=msvc stage
is pretty odd. Even if it worked, and it doesn't,
What's wrong with it, please?
How am I supposed to enter that? bjam \ <enter> executes "bjam \". \ is a valid path under Windows. What version of 'cmd' are you using that lets you splice lines in this way?
Oh, crud, I guess I just assumed that it works. Okay, looks like I have to unwrap all those lines. Thanks. -- Dave Abrahams Boost Consulting www.boost-consulting.com
----Original Message---- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of David Abrahams Sent: 12 December 2006 13:53 To: boost@lists.boost.org Subject: Re: [boost] Attention Boosters
"Peter Dimov" <pdimov@mmltd.net> writes:
David Abrahams wrote:
You can review the guide at http://www.boost-consulting.com/boost/more/getting_started.html.
C:\Program Files\boost\boost_1_34_0> bjam \ --build-dir=%TEMP%\build-boost \ --toolset=msvc stage
is pretty odd. Even if it worked, and it doesn't,
What's wrong with it, please?
\ does not escape a newline for the Windows XP command prompt (I can't remember about COMMAND.COM). If the user types everything after the > to the command prompt, she will invoke bjam with a single argument of a literal backslash, and then attempt to invoke a program called --build-dir (which will, probably, fail). Note that \ also doesn't escape a newline within a batch file. A little experimentation suggests that you need: C:\Program Files\boost\boost_1_34_0> bjam ^ More? --build-dir=%TEMP%\build-boost ^ More? --toolset=msvc stage It will fit within your 65 character limit with: C:\Program Files\boost\boost_1_34_0> bjam ^ More? --build-dir=%TEMP%\build-boost --toolset=msvc stage -- Martin Bonner Pi Technology, Milton Hall, Ely Rd, Cambridge, CB24 6WZ, ENGLAND +44 (0) 1223 203894
David Abrahams wrote:
I really need feedback on what I've done,
First to say: I would like to have seen something of similar quality on my first encounter to boost! Section 4) Why is only Boost.Python hyperlinked? Section 6.3) I was always wondering what this "stage" really means. I stopped wondering since then, because I never had a need for it. A bit explanation would be nice. You are also omitting install target, why? Isn't install something more likely to be used? Section 7.3) Library naming: mingw is different, since bbv2 it uses .a files for static libs, and no import libraries (altough it did in bbv1 I believe). Section 8) Jam Reference links to 404 Section 9) I have no idea what you want to tell by: One way to name a directory you know about is to write .... And yes, I hope the mingw naming issue can be resolved before 1.34 release. Regards Roland
Roland Schwarz wrote:
David Abrahams wrote:
I really need feedback on what I've done,
First to say: I would like to have seen something of similar quality on my first encounter to boost!
Section 4) Why is only Boost.Python hyperlinked?
Oops, this might sound unintentional rude. Sorry, instead my intent was to express my admiration for the clear and concise made up of the tutorial. Thank you so much. I think this will lead to better user experience than ever. Roland
Roland Schwarz said: (by the date of Mon, 11 Dec 2006 23:16:48 +0100)
Roland Schwarz wrote:
David Abrahams wrote:
I really need feedback on what I've done,
First to say: I would like to have seen something of similar quality on my first encounter to boost!
Section 4) Why is only Boost.Python hyperlinked?
maybe change that line into: * Boost.Python (special case) where the word "special case" is hyperlinked. Or sth like that... -- Janek Kozicki |
Janek Kozicki <janek_listy@wp.pl> writes:
Roland Schwarz said: (by the date of Mon, 11 Dec 2006 23:16:48 +0100)
Roland Schwarz wrote:
David Abrahams wrote:
I really need feedback on what I've done,
First to say: I would like to have seen something of similar quality on my first encounter to boost!
Section 4) Why is only Boost.Python hyperlinked?
maybe change that line into:
* Boost.Python (special case)
where the word "special case" is hyperlinked. Or sth like that...
But it's not a special case; the link just takes you to the main Boost.Python docs. -- Dave Abrahams Boost Consulting www.boost-consulting.com
Roland Schwarz <roland.schwarz@chello.at> writes:
Roland Schwarz wrote:
David Abrahams wrote:
I really need feedback on what I've done,
First to say: I would like to have seen something of similar quality on my first encounter to boost!
Section 4) Why is only Boost.Python hyperlinked?
Oops, this might sound unintentional rude.
It didn't; it's a legit question. Should I link everything or nothing or is inconsistency just fine?
Sorry, instead my intent was to express my admiration for the clear and concise made up of the tutorial. Thank you so much. I think this will lead to better user experience than ever.
Thank you for your kind sentiments. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams said: (by the date of Mon, 11 Dec 2006 18:23:31 -0500)
Roland Schwarz <roland.schwarz@chello.at> writes:
Roland Schwarz wrote:
David Abrahams wrote:
I really need feedback on what I've done,
First to say: I would like to have seen something of similar quality on my first encounter to boost!
Section 4) Why is only Boost.Python hyperlinked?
Oops, this might sound unintentional rude.
It didn't; it's a legit question. Should I link everything or nothing or is inconsistency just fine?
Because the context is "Boost libraries that can't be used without separate compilation", we have two cases: - if the linked docs will explain how to perform a separate compilation of the library, then link all of them. - if they do not explain how to perform a separate compilation then do not link. I'd prefer that each of them linked to an anchor (or part of documentation) of respective ilbrary which explains how to perform compilation of that library. Then someone will read the "getting started" and will say - oh, I need only filesystem and I don't want to wait till everything compiles. I will separately compile just this one, and he clicks the link. -- Janek Kozicki |
Janek Kozicki <janek_listy@wp.pl> writes:
I'd prefer that each of them linked to an anchor (or part of documentation) of respective ilbrary which explains how to perform compilation of that library.
Then someone will read the "getting started" and will say - oh, I need only filesystem and I don't want to wait till everything compiles. I will separately compile just this one, and he clicks the link.
I really don't want to complicate the getting started guide with instructions for compiling a subset of the libraries, and the individual library documentation will in most cases not give those instructions either. Simplicity, simplicity, simplicity, or we will lose much of our audience. Hmm... we'll also lose our audience if they have to wait through a long build process :(. Maybe I need to say something about building individual libraries and variants. -- Dave Abrahams Boost Consulting www.boost-consulting.com
Roland Schwarz <roland.schwarz@chello.at> writes:
David Abrahams wrote:
I really need feedback on what I've done,
First to say: I would like to have seen something of similar quality on my first encounter to boost!
:)
Section 4) Why is only Boost.Python hyperlinked?
No particular reason.
Section 6.3)
I was always wondering what this "stage" really means. I stopped wondering since then, because I never had a need for it. A bit explanation would be nice.
I think the document explains exactly what it means: Boost.Build will place the Boost binaries in the stage/ subdirectory of your build directory. If you are wondering about the origin of the word, I don't know. I would prefer a "libs" target, personally.
You are also omitting install target, why?
Because it's more complicated.
Isn't install something more likely to be used?
Not really. Install is just like stage except that it copies the libraries *and the headers* into an installation directory tree. You already have the headers, and installing to a useful location probably means you need root privileges, which not everybody has. I'd say "stage" is much more universally applicable.
Section 7.3) Library naming: mingw is different,
How so? I can't document it if I don't know.
since bbv2 it uses .a files for static libs, and no import libraries (altough it did in bbv1 I believe).
Oh... are you just saying that MinGW is treated differently w.r.t. the /Extension/ tag? I suppose that Cygwin GCC is also treated differently. I'll have to adjust that, thank you. Does it use .dll for dynamic libraries? What if you *want* to generate an import lib?
Section 8) Jam Reference links to 404
Thanks.
Section 9) I have no idea what you want to tell by: One way to name a directory you know about is to write
Oh. I am trying to help GUI-only people who don't know how to navigate the directory tree. I was assuming some people think the world begins with "My Documents" and don't know how to write its path. Am I being overprotective? Even if there *are* people like that out there, if I can't say sometihng intelligible it only hurts, so I'm inclined to remove it.
....
And yes, I hope the mingw naming issue can be resolved before 1.34 release.
Me 2. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams said: (by the date of Mon, 11 Dec 2006 18:16:50 -0500)
Section 9) I have no idea what you want to tell by: One way to name a directory you know about is to write
Oh. I am trying to help GUI-only people who don't know how to navigate the directory tree. I was assuming some people think the world begins with "My Documents" and don't know how to write its path. Am I being overprotective?
Even if there *are* people like that out there, if I can't say sometihng intelligible it only hurts, so I'm inclined to remove it.
In my experience, people that I've met, who think that the world starts at "My Documents" give a blank stare when I start talking about writing programs myself. Word "compilation" is a buzzword. IMHO you can remove this :) No wait. Actually it contains an information I didn't know about(*) - namely - what is %HOMEDRIVE%%HOMEPATH%, so maybe just rephrase this: Replace "One way to name ..." with ---- "To set current directory to your "My Documents" folder type: cd %HOMEDRIVE%%HOMEPATH% this can be useful if you got lost in the directory tree" ---- (*) I feel like I should explain myself - I removed windows partition from my hdd in 1999, and currently I use windows only occasionally in vmware :) -- Janek Kozicki |
Janek Kozicki wrote:
"To set current directory to your "My Documents" folder type:
cd %HOMEDRIVE%%HOMEPATH%
this can be useful if you got lost in the directory tree"
%HOMEDRIVE%%HOMEPATH% is actually the parent of the default location of "My Documents", C:\Documents and Settings\pdimov on this machine. I missed the "sibling" in Dave's text too on first reading.
"Peter Dimov" <pdimov@mmltd.net> writes:
Janek Kozicki wrote:
"To set current directory to your "My Documents" folder type:
cd %HOMEDRIVE%%HOMEPATH%
this can be useful if you got lost in the directory tree"
%HOMEDRIVE%%HOMEPATH% is actually the parent of the default location of "My Documents",
C:\Documents and Settings\pdimov
on this machine. I missed the "sibling" in Dave's text too on first reading.
Well, according to info I just Googled up, %HOMEDRIVE%%HOMEPATH% is your "Documents and Settings" folder, but your "My Documents" folder can actually be located elsewhere, even on a different drive. So I guess I'm dropping this part. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
You can review the guide at http://www.boost-consulting.com/boost/more/getting_started.html.
In 6.3, you say: Change your current directory to the Boost root directory and invoke bjam as follows: bjam --build-dir=build-directory \ --toolset=toolset-name stage but then the Unix example is given as: $ cd ~/boost_1_34_0 $ bjam --build-dir=~/build-boost --prefix=~/boost and doesn't follow the instruction above. It omits --toolset and includes --prefix without explanation.
I've only had a glance over it, and it looks good to me. Would it be appropriate for this document to include a paragraph (in its introduction) entitled "Why use Boost?" Remember we discussed this at length a while back as being another thing that can put new users off using Boost in the first place. (I notice that there is still nothing on the Boost homepage to this effect other than a couple of lines on what Boost is. The homepage reads to me as if anyone visiting it already knows that they want to use Boost.) Paul
Paul Giaccone <paulg@cinesite.co.uk> writes:
I've only had a glance over it, and it looks good to me.
Would it be appropriate for this document to include a paragraph (in its introduction) entitled "Why use Boost?" Remember we discussed this at length a while back as being another thing that can put new users off using Boost in the first place.
Sorry, *what* could put new users off?
(I notice that there is still nothing on the Boost homepage to this effect other than a couple of lines on what Boost is. The homepage reads to me as if anyone visiting it already knows that they want to use Boost.)
Interesting point. I'm preparing a new Boost Consulting website for launch soon; it has quite a bit of material about "why boost?" It seems to me that what you're describing doesn't belong in the Getting Started document, but on the front page. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
Paul Giaccone <paulg@cinesite.co.uk> writes:
I've only had a glance over it, and it looks good to me.
Would it be appropriate for this document to include a paragraph (in its introduction) entitled "Why use Boost?" Remember we discussed this at length a while back as being another thing that can put new users off using Boost in the first place.
Sorry, *what* could put new users off?
Sorry, I should have been clearer. The absence of some text headed "Why use Boost?" might put users off.
(I notice that there is still nothing on the Boost homepage to this effect other than a couple of lines on what Boost is. The homepage reads to me as if anyone visiting it already knows that they want to use Boost.)
Interesting point.
I'm preparing a new Boost Consulting website for launch soon; it has quite a bit of material about "why boost?"
It seems to me that what you're describing doesn't belong in the Getting Started document, but on the front page.
Indeed, and that was what I was arguing for in the "Why use Boost" thread, but it didn't seem to come to anything at the time. Paul
Paul Giaccone <paulg@cinesite.co.uk> writes:
It seems to me that what you're describing doesn't belong in the Getting Started document, but on the front page.
Indeed, and that was what I was arguing for in the "Why use Boost" thread, but it didn't seem to come to anything at the time.
Well it should be at least linked to from the homepage. In any case, that's a separate issue. -- Dave Abrahams Boost Consulting www.boost-consulting.com
"Peter Dimov" <pdimov@mmltd.net> writes:
David Abrahams wrote:
You can review the guide at http://www.boost-consulting.com/boost/more/getting_started.html.
In 6.3, you say:
Change your current directory to the Boost root directory and invoke bjam as follows:
bjam --build-dir=build-directory \ --toolset=toolset-name stage
but then the Unix example is given as:
$ cd ~/boost_1_34_0 $ bjam --build-dir=~/build-boost --prefix=~/boost
and doesn't follow the instruction above. It omits --toolset and includes --prefix without explanation.
Good eye! Thanks, I'll fix that. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
You can review the guide at http://www.boost-consulting.com/boost/more/getting_started.html.
The document suddenly changed while I was reviewing it ;-O. Some remaining comments: 1. Introduction =============== Why "*nix?" and not "Shell", "Shell environment", "UNIX-style shell environment" or "others?" 2. Get Boost ============ 1.2.3... 4. checkout a branch from the CVS? 3. The structure of a Boost Distribution ======================================== I'm not sure it's a good idea to put a single command line option in one line -I/path/to/boost_1_34_0 maybe an exemplary compiler invocation works better ("I enter -I... and nothing happens"). "Even Windows users can use forward slashes in #include directives; your compiler doesn't care". The recommendation to use forward slashes should be either stronger or left out. Appendix ======== How about "Open the Finder, select Applications, open the Utilities folder and double click Terminal" for the MacOS X case (guessing that there might be MacOS developers without a UNIX background)? Layout notes (viewed with Firefox): =================================== The big font for the filesystem structure seems one font size too many for my eye. It looks a bit better for the code blocks (probably because the text isn't bold), but I still believe using a single font size will look best. With some window width "C:\Progam Files\boost\boost_1_34_0" floats into the "Header Organization" column ('pre' won't break - and preformatting isn't really needed, so 'tt' or an equivalent style should be enough). The code could use some syntax highlighting for the final version (which you might have planned anyway). Regards, Tobias
Tobias Schwinger <tschwinger@neoscientists.org> writes:
David Abrahams wrote:
You can review the guide at http://www.boost-consulting.com/boost/more/getting_started.html.
The document suddenly changed while I was reviewing it ;-O. Some remaining comments:
1. Introduction ===============
Why "*nix?" and not "Shell", "Shell environment", "UNIX-style shell environment" or "others?"
Any number of reasons, some of which I addressed in messages to this list earlier today.
2. Get Boost ============
1.2.3... 4. checkout a branch from the CVS?
Why should I give that as an option? I could also add "buy a DVD from Boost Consulting" if I'm going to add that. The point is not to describe every way you might acquire Boost, but to point people at the two easiest supported ways and describe the third way that many people are tempted to use but that might not be easy for us to support.
3. The structure of a Boost Distribution ========================================
I'm not sure it's a good idea to put a single command line option in one line
-I/path/to/boost_1_34_0
maybe an exemplary compiler invocation works better ("I enter -I... and nothing happens").
Do you really think people will copy that line into their shell without even reading the sentence that surrounds it? If I give an example invocation that will be wrong for some people too: I type "c++ -Ic:\boost" and it tells me: "c++: command not found." I'd rather not be specific if it makes me wrong.
"Even Windows users can use forward slashes in #include directives; your compiler doesn't care".
The recommendation to use forward slashes should be either stronger or left out.
Why? It's not a recommendation. It's a note designed to de-confuse windows users who use the sample code in the tutorial. I don't mean to evangelize the use of forward slashes, so I don't want to strengthen it. I don't want to leave it out because people will be confused.
Appendix ========
How about "Open the Finder, select Applications, open the Utilities folder and double click Terminal" for the MacOS X case (guessing that there might be MacOS developers without a UNIX background)?
Don't you have to select "new window" from the finder menu before you can select Applications? The other problem here is that, to do these people justice I have to explain everything I tell the Windows people, e.g. about the current directory, and then that part becomes a Unix-universal section on using the shell. I'm thinking that maybe MacOS programmers who don't know how to use a shell are not a big enough audience to warrant lengthening the tutorial document.
Layout notes (viewed with Firefox): ===================================
The big font for the filesystem structure seems one font size too many for my eye. It looks a bit better for the code blocks (probably because the text isn't bold), but I still believe using a single font size will look best.
Am I using multiple font sizes? I'm not a CSS expert and would be happy to have help with this.
With some window width "C:\Progam Files\boost\boost_1_34_0" floats into the "Header Organization" column
I noticed.
('pre' won't break -
That's not the problem; it should break before the "C:"
and preformatting isn't really needed, so 'tt' or an equivalent style should be enough).
Oh, heh, I'm not sure I can control that so easily. It looks like docutils puts a <pre>...</pre> around all "inline literals" (text formatted with <tt>...</tt>). Maybe I'll ask about that on the docutils mailing list, but maybe not: even without <pre> I can make it collide :(
The code could use some syntax highlighting for the final version (which you might have planned anyway).
Nope, I hadn't. Docutils doesn't syntax-highlight C++. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
Tobias Schwinger <tschwinger@neoscientists.org> writes:
David Abrahams wrote:
You can review the guide at http://www.boost-consulting.com/boost/more/getting_started.html.
The document suddenly changed while I was reviewing it ;-O. Some remaining comments:
1. Introduction ===============
Why "*nix?" and not "Shell", "Shell environment", "UNIX-style shell environment" or "others?"
Any number of reasons, some of which I addressed in messages to this list earlier today.
I must've missed it - never mind - it doesn't make up an entire headline anymore.
2. Get Boost ============
1.2.3... 4. checkout a branch from the CVS?
Why should I give that as an option?
There are two possible reasons that might or might not matter to you: - critical bug fixes can be deployed easily - if users fix bugs they can easily create a patch and send us
3. The structure of a Boost Distribution ========================================
I'm not sure it's a good idea to put a single command line option in one line
-I/path/to/boost_1_34_0
maybe an exemplary compiler invocation works better ("I enter -I... and nothing happens").
Do you really think people will copy that line into their shell without even reading the sentence that surrounds it?
Well, I wouldn't bet on people won't, at least... People unfamiliar with a command might not know what "adding to the command line" exactly means.
If I give an example invocation that will be wrong for some people too:
I type "c++ -Ic:\boost" and it tells me: "c++: command not found."
I'd rather not be specific if it makes me wrong.
Still, a concrete example that is "wrong" for most people is often better than hard-to-get abstract wisdom that applies everywhere...
"Even Windows users can use forward slashes in #include directives; your compiler doesn't care".
The recommendation to use forward slashes should be either stronger or left out.
Why?
"Ah, interesting - I'm developing for Windows - so I'll use backslashes for consistency with my OS' file system... Didn't know that would work, before..."
It's not a recommendation. It's a note designed to de-confuse windows users who use the sample code in the tutorial. I don't mean to evangelize the use of forward slashes, so I don't want to strengthen it.
Why not? There is only one right and portable way
I don't want to leave it out because people will be confused.
and it isn't clear which one it is. It might add more confusion than it resolves, elsewhere.
Appendix ========
How about "Open the Finder, select Applications, open the Utilities folder and double click Terminal" for the MacOS X case (guessing that there might be MacOS developers without a UNIX background)?
Don't you have to select "new window" from the finder menu before you can select Applications?
It depends... s/Open the Finder/Open a finder window/ would be more accurate.
The other problem here is that, to do these people justice I have to explain everything I tell the Windows people, e.g. about the current directory, and then that part becomes a Unix-universal section on using the shell.
I'm thinking that maybe MacOS programmers who don't know how to use a shell are not a big enough audience to warrant lengthening the tutorial document.
Isn't there some external document that could be linked to for the "cd/ls tutorial"?
Layout notes (viewed with Firefox): ===================================
The big font for the filesystem structure seems one font size too many for my eye. It looks a bit better for the code blocks (probably because the text isn't bold), but I still believe using a single font size will look best.
Am I using multiple font sizes? I'm not a CSS expert and would be happy to have help with this.
I wouldn't call myself a CSS expert. Anyway, as four eyes see more than two, I can have a look at the details this evening (GMT+1) if no real CSS expert stands up until then. It might have to do with different defaults of different browsers that "shine through" if not overridden explicitly.
With some window width "C:\Progam Files\boost\boost_1_34_0" floats into the "Header Organization" column
I noticed.
('pre' won't break -
That's not the problem; it should break before the "C:"
and preformatting isn't really needed, so 'tt' or an equivalent style should be enough).
Oh, heh, I'm not sure I can control that so easily. It looks like docutils puts a <pre>...</pre> around all "inline literals" (text formatted with <tt>...</tt>). Maybe I'll ask about that on the docutils mailing list, but maybe not: even without <pre> I can make it collide :(
Hmmm... Maybe setting the 'overflow' attribute will work.
The code could use some syntax highlighting for the final version (which you might have planned anyway).
Nope, I hadn't. Docutils doesn't syntax-highlight C++.
In case you can pass through verbatim HTML, e.g. http://spirit.sourceforge.net/repository/applications/cpp_to_html.zip could be used to get the job done. Regards, Tobias
Tobias Schwinger wrote:
David Abrahams wrote:
Tobias Schwinger <tschwinger@neoscientists.org> writes:
David Abrahams wrote:
You can review the guide at http://www.boost-consulting.com/boost/more/getting_started.html.
<snip>
With some window width "C:\Progam Files\boost\boost_1_34_0" floats into the "Header Organization" column
I noticed.
('pre' won't break -
That's not the problem; it should break before the "C:"
and preformatting isn't really needed, so 'tt' or an equivalent style should be enough).
Oh, heh, I'm not sure I can control that so easily. It looks like docutils puts a <pre>...</pre> around all "inline literals" (text formatted with <tt>...</tt>). Maybe I'll ask about that on the docutils mailing list, but maybe not: even without <pre> I can make it collide :(
Hmmm... Maybe setting the 'overflow' attribute will work.
No, sorry I mixed things up. Here is the solution: Changing "white-space: pre" to "white-space: pre-wrap" for the affected styles does the trick. Internet Explorer doesn't support "pre-wrap" but it doesn't matter here because a) pre elements have hard-wired "white-space: pre" semantics with this browser b) Internet Explorer doesn't have the problem in the first place Regards, Tobias
Tobias Schwinger wrote:
Hmmm... Maybe setting the 'overflow' attribute will work.
No, sorry I mixed things up.
Here is the solution: Changing "white-space: pre" to "white-space: pre-wrap" for the affected styles does the trick.
Internet Explorer doesn't support "pre-wrap" but it doesn't matter here because a) pre elements have hard-wired "white-space: pre" semantics with this browser b) Internet Explorer doesn't have the problem in the first place
This solution only works if the text /can/ be broken. So if you the region becomes too small (so that the text can't be broken down any further) the collision still occurs. Setting "overflow: hidden" for 'pre.literal-block' will hide the text that doesn't fit (which might be prettier, but doesn't really solve the problem). To make long words (e.g. "Files\boost\boost_1_34_0") breakable you'll have to convince your documentation system to inject wbr tags into the text to provide predetermined breaking points (e.g. "Files\<wbr/>boost\<wbr/>boost_1_34_0" can break after every backslash). Regards, Tobias
Tobias Schwinger <tschwinger@neoscientists.org> writes:
No, sorry I mixed things up.
Here is the solution: Changing "white-space: pre" to "white-space: pre-wrap" for the affected styles does the trick.
Please propose a specific patch to the stylesheet. I tried to make this change but it had no effect. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
Please propose a specific patch to the stylesheet. I tried to make this change but it had no effect.
OK, here is the patch. It also resolves an Internet Explorer issue that causes the border of the first code block to show up on the right side of the TOC and gives tables consistent indentation. The patch is hereby put under Boost license (IOW use the parts you like ;-P ). Regards, Tobias --- ../rst.css.bak Wed Dec 13 22:33:08 2006 +++ ../rst.css Thu Dec 14 00:25:55 2006 @@ -95,8 +95,23 @@ color: red ; font-weight: bold } -div.topic { - margin: 2em } +/* Here is a workaround for what seems to be an Internet Explorer box model + issue. IE's currently disfunctional > selector is used as a conditional. */ + +div.topic, div.sidebar { + margin: 2em ; + margin-right: 1em /* IE only */ } + +* > /* not for IE */ div.topic, div.sidebar { + margin-right: 2em } + +/* Consistent indentation for tables, unless for footnotes */ + +table { + margin: 2em; } + +table.footnote { + margin: none } dt { font-weight: bold @@ -131,16 +146,17 @@ { MARGIN-LEFT: 2em; FONT-FAMILY: Courier; + white-space: pre-wrap; } CODE { FONT-FAMILY: Courier; - white-space: pre; + white-space: pre-wrap; } .pre { FONT-FAMILY: Courier; - white-space: pre; + white-space: pre-wrap; } .index { @@ -231,6 +247,7 @@ pre.literal-block, pre.doctest-block { margin-left: 2em ; margin-right: 2em ; +/* font-size: smaller; */ background-color: #eeeeee } span.class { @@ -264,9 +281,6 @@ span.option-argument { font-style: italic } - -span.pre { - white-space: pre } span.problematic { color: red }
Tobias Schwinger wrote:
David Abrahams wrote:
Please propose a specific patch to the stylesheet. I tried to make this change but it had no effect.
OK, here is the patch. It also resolves an Internet Explorer issue that causes the border of the first code block to show up on the right side of the TOC and gives tables consistent indentation. The patch is hereby put under Boost license (IOW use the parts you like ;-P ).
Did it help, then? Here is the full file (so I can safely delete my copy). Regards, Tobias
Tobias Schwinger <tschwinger@neoscientists.org> writes:
Tobias Schwinger wrote:
David Abrahams wrote:
Please propose a specific patch to the stylesheet. I tried to make this change but it had no effect.
OK, here is the patch. It also resolves an Internet Explorer issue that causes the border of the first code block to show up on the right side of the TOC and gives tables consistent indentation. The patch is hereby put under Boost license (IOW use the parts you like ;-P ).
Did it help, then?
I'm afraid not; it doesn't prevent collisions. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
OK, here is the patch. It also resolves an Internet Explorer issue that causes the border of the first code block to show up on the right side of the TOC and gives tables consistent indentation. The patch is hereby put under Boost license (IOW use the parts you like ;-P ).
Did it help, then?
I'm afraid not; it doesn't prevent collisions.
Strange - maybe the Linux version (guessing from the news header) displays things differently... Here are some screenshots taken with Firefox/Windows. I'm CCing to your email in case the list won't accept it. Regards, Tobias
Tobias Schwinger wrote:
David Abrahams wrote:
Tobias Schwinger <tschwinger@neoscientists.org> writes:
Layout notes (viewed with Firefox): ===================================
The big font for the filesystem structure seems one font size too many for my eye. It looks a bit better for the code blocks (probably because the text isn't bold), but I still believe using a single font size will look best.
Am I using multiple font sizes? I'm not a CSS expert and would be happy to have help with this.
I wouldn't call myself a CSS expert. Anyway, as four eyes see more than two, I can have a look at the details this evening (GMT+1) if no real CSS expert stands up until then. It might have to do with different defaults of different browsers that "shine through" if not overridden explicitly.
Using "font-size: smaller" for 'pre.literal-block' makes things look much better on my system (Firefox & IE / Windows). Regards, Tobias
Tobias Schwinger <tschwinger@neoscientists.org> writes:
Using "font-size: smaller" for 'pre.literal-block' makes things look much better on my system (Firefox & IE / Windows).
In my FireFox it makes code blocks look too small. -- Dave Abrahams Boost Consulting www.boost-consulting.com
Tobias Schwinger wrote:
David Abrahams wrote:
Tobias Schwinger <tschwinger@neoscientists.org> writes:
David Abrahams wrote:
You can review the guide at http://www.boost-consulting.com/boost/more/getting_started.html.
Layout notes (viewed with Firefox): ===================================
I also noticed that the double quotes seem to need some escaping for Internet Explorer to display them properly (a tiny piece of a screenshot is attached to this post). Regards, Tobias
Tobias Schwinger <tschwinger@neoscientists.org> writes:
I also noticed that the double quotes seem to need some escaping for Internet Explorer to display them properly (a tiny piece of a screenshot is attached to this post).
What kind of escaping? -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
Tobias Schwinger <tschwinger@neoscientists.org> writes:
I also noticed that the double quotes seem to need some escaping for Internet Explorer to display them properly (a tiny piece of a screenshot is attached to this post).
What kind of escaping?
I don't know whether you or the documentation system generated those opening and closing double quote characters ('“' and '”'), which seem to be undefined for the font used by Internet Explorer. In case of the former just using regular double quotes will do the trick. In case of the latter I've no idea. Regards, Tobias
Tobias Schwinger <tschwinger@neoscientists.org> writes:
2. Get Boost ============
1.2.3... 4. checkout a branch from the CVS?
Why should I give that as an option?
There are two possible reasons that might or might not matter to you:
- critical bug fixes can be deployed easily - if users fix bugs they can easily create a patch and send us
I don't want to encourage people to use an un-released snapshot of Boost in the **getting started** guide. Other options can be discussed elsewhere.
maybe an exemplary compiler invocation works better ("I enter -I... and nothing happens").
Do you really think people will copy that line into their shell without even reading the sentence that surrounds it?
Well, I wouldn't bet on people won't, at least...
People unfamiliar with a command might not know what "adding to the command line" exactly means.
If I give an example invocation that will be wrong for some people too:
I type "c++ -Ic:\boost" and it tells me: "c++: command not found."
I'd rather not be specific if it makes me wrong.
Still, a concrete example that is "wrong" for most people is often better than hard-to-get abstract wisdom that applies everywhere...
Sorry, I just disagree that it will help overall.
"Even Windows users can use forward slashes in #include directives; your compiler doesn't care".
The recommendation to use forward slashes should be either stronger or left out.
Why?
"Ah, interesting - I'm developing for Windows - so I'll use backslashes for consistency with my OS' file system... Didn't know that would work, before..."
You're welcome to make that choice.
It's not a recommendation. It's a note designed to de-confuse windows users who use the sample code in the tutorial. I don't mean to evangelize the use of forward slashes, so I don't want to strengthen it.
Why not?
Because style evangelism is out-of-place and off-purpose in this document.
There is only one right and portable way
That sort of position is anathema to me. In some environments, portability counts for nothing and looking familiar to other Windows programmers counts for everything.
I don't want to leave it out because people will be confused.
and it isn't clear which one it is.
I can't tell what you're referring to here.
It might add more confusion than it resolves, elsewhere.
Sorry, I have no idea what you mean.
I'm thinking that maybe MacOS programmers who don't know how to use a shell are not a big enough audience to warrant lengthening the tutorial document.
Isn't there some external document that could be linked to for the "cd/ls tutorial"?
That would be great. If you could find me a good and stable link I'd be grateful. Likewise for Windows, for that matter. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
Tobias Schwinger <tschwinger@neoscientists.org> writes:
2. Get Boost ============
1.2.3... 4. checkout a branch from the CVS?
Why should I give that as an option?
There are two possible reasons that might or might not matter to you:
- critical bug fixes can be deployed easily - if users fix bugs they can easily create a patch and send us
I don't want to encourage people to use an un-released snapshot of Boost in the **getting started** guide. Other options can be discussed elsewhere.
Oh, I was talking about the already-released branches, of course, but it only makes sense in case we back-port any fixes (that's what I meant with "might or might not matter", above).
"Even Windows users can use forward slashes in #include directives; your compiler doesn't care".
The recommendation to use forward slashes should be either stronger or left out.
Why?
"Ah, interesting - I'm developing for Windows - so I'll use backslashes for consistency with my OS' file system... Didn't know that would work, before..."
You're welcome to make that choice.
I see (16.2.2: "How [...] the header is identified is implementation-defined"). Sorry for the noise.
I'm thinking that maybe MacOS programmers who don't know how to use a shell are not a big enough audience to warrant lengthening the tutorial document.
Isn't there some external document that could be linked to for the "cd/ls tutorial"?
That would be great. If you could find me a good and stable link I'd be grateful. Likewise for Windows, for that matter.
Hard to find. Seems that "good" is enough of a K.O. criterion for most of the documents out there ;-(. Regards, Tobias
David Abrahams writes:
Tobias Schwinger <tschwinger@neoscientists.org> writes:
The code could use some syntax highlighting for the final version (which you might have planned anyway).
Nope, I hadn't. Docutils doesn't syntax-highlight C++.
Not out-of-box, but easy enough to add: http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/252170 (not to suggest that you should spend any time on it). -- Aleksey Gurtovoy MetaCommunications Engineering
Aleksey Gurtovoy <agurtovoy@meta-comm.com> writes:
Dave wrote:
Docutils doesn't syntax-highlight C++.
Not out-of-box, but easy enough to add: http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/252170 (not to suggest that you should spend any time on it).
Great to know; thanks! -- Dave Abrahams Boost Consulting www.boost-consulting.com
On 12/13/06, David Abrahams <dave@boost-consulting.com> wrote:
Aleksey Gurtovoy <agurtovoy@meta-comm.com> writes:
Dave wrote:
Docutils doesn't syntax-highlight C++.
Not out-of-box, but easy enough to add: http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/252170 (not to suggest that you should spend any time on it).
Great to know; thanks!
There is another powerful tool: http://pykleur.pocoo.org/ I used it for Py++ documentation. The main difference is that pykleur is written in Python only ( no need to compile extensions ). -- Roman Yakovenko C++ Python language binding http://www.language-binding.net/
"Roman Yakovenko" <roman.yakovenko@gmail.com> writes:
On 12/13/06, David Abrahams <dave@boost-consulting.com> wrote:
Aleksey Gurtovoy <agurtovoy@meta-comm.com> writes:
Dave wrote:
Docutils doesn't syntax-highlight C++.
Not out-of-box, but easy enough to add: http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/252170 (not to suggest that you should spend any time on it).
Great to know; thanks!
There is another powerful tool: http://pykleur.pocoo.org/ I used it for Py++ documentation. The main difference is that pykleur is written in Python only ( no need to compile extensions ).
Sweet! -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
I've just finished my 2nd rewrite of the Boost Getting Started Guide. The quality of this crucial document shapes our users' first experiences with Boost, and for many, determines whether they use Boost or give up in frustration.
I really need feedback on what I've done, **especially from experienced Boosters** who can vett my statements for accuracy. I have already received some really valuable input from this group and poured it into this 2nd rewrite. There were, however, quite a few problems I discovered by chance through communications with experienced Boosters who haven't given me feedback on the guide. I'm wonder what problems I'm still missing, and I hope you can tell me.
You can review the guide at http://www.boost-consulting.com/boost/more/getting_started.html.
Thank you for your time,
hi dave, this is very nice ... but ... 4) why is only boost python "hyper linked"? 5) I'd actually would swap 5.2 and 5.3 ... i think most windows users prefer using stuff in an ide an not on the cmdline, so using IDE should come before cmdline. 5.4 i guess you mean most of the "deprecated" stuff msvc tells us about? if so, i'd explicitly state them here (and how to get living/rid of it), or else i wouldn't be sure, wheter i can just ignore them or i missed warnings/errors that actually matter. (i guess it's vc2005 only?) what i actually like ... is all the new example stuff: on windows (...) it looks like "..." and on *nix it should look like "..." this is EXACTLY was i was looking for, in the original 'getting started' guide, so... thanks for boost and all *YOUR* new effords regarding it. -- thx, dave
David Klein <dave_chp@gmx.de> writes:
David Abrahams wrote:
I've just finished my 2nd rewrite of the Boost Getting Started Guide. The quality of this crucial document shapes our users' first experiences with Boost, and for many, determines whether they use Boost or give up in frustration.
I really need feedback on what I've done, **especially from experienced Boosters** who can vett my statements for accuracy. I have already received some really valuable input from this group and poured it into this 2nd rewrite. There were, however, quite a few problems I discovered by chance through communications with experienced Boosters who haven't given me feedback on the guide. I'm wonder what problems I'm still missing, and I hope you can tell me.
You can review the guide at http://www.boost-consulting.com/boost/more/getting_started.html.
Thank you for your time,
hi dave, this is very nice ... but ...
4) why is only boost python "hyper linked"?
No reason. Asked and answered in a previous message.
5) I'd actually would swap 5.2 and 5.3 ... i think most windows users prefer using stuff in an ide an not on the cmdline, so using IDE should come before cmdline.
True, but the IDE instructions are much more complicated than the cmdline instructions. I've been using the principle that when the tracks bifurcate, branches are ordered from shortest to longest, to make it easier to find the branch you want.
5.4 i guess you mean most of the "deprecated" stuff msvc tells us about?
Not just that.
if so, i'd explicitly state them here (and how to get living/rid of it), or else i wouldn't be sure, wheter i can just ignore them or i missed warnings/errors that actually matter. (i guess it's vc2005 only?)
No, it's lots of compilers. GCC is a particular problem because you can't silence its warnings in code. If there's something you'd like to see stated explicitly there, you'd better state explicitly what it is :)
what i actually like ... is all the new example stuff: on windows (...) it looks like "..." and on *nix it should look like "..."
this is EXACTLY was i was looking for, in the original 'getting started' guide, so...
thanks for boost and all *YOUR* new effords regarding it.
:) You're welcome. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams <dave@boost-consulting.com> writes:
4) why is only boost python "hyper linked"?
No reason. Asked and answered in a previous message.
This might have seemed ungrateful; sorry. I appreciate your feedback; I'm just short of time and sleep.
5) I'd actually would swap 5.2 and 5.3 ... i think most windows users prefer using stuff in an ide an not on the cmdline, so using IDE should come before cmdline.
True, but the IDE instructions are much more complicated than the cmdline instructions. I've been using the principle that when the tracks bifurcate, branches are ordered from shortest to longest, to make it easier to find the branch you want.
Does that make sense or should I have used a different criterion? I think, ultimately, it would be best if we had a separate document for each platform/environment. Unfortunately I don't currently have the technology to do that (though maybe I will switch to QuickBook and get what I need). -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
David Abrahams <dave@boost-consulting.com> writes:
4) why is only boost python "hyper linked"? No reason. Asked and answered in a previous message.
This might have seemed ungrateful; sorry. I appreciate your feedback; I'm just short of time and sleep.
Don't worry, no offense taken.
5) I'd actually would swap 5.2 and 5.3 ... i think most windows users prefer using stuff in an ide an not on the cmdline, so using IDE should come before cmdline. True, but the IDE instructions are much more complicated than the cmdline instructions. I've been using the principle that when the tracks bifurcate, branches are ordered from shortest to longest, to make it easier to find the branch you want.
Does that make sense or should I have used a different criterion?
Well yes it does, but I probably would have ordered by "most common use" or something like that. Regarding ordering, i noticed a minor inconsistency in the build sample | get/build boost | link to boost layout. 5.x *nix windows 6.x windows *nix 7.x windows *nix I'd reorder to start with the same OS in every paragraph.
I think, ultimately, it would be best if we had a separate document for each platform/environment. Unfortunately I don't currently have the technology to do that (though maybe I will switch to QuickBook and get what I need).
BTW, just spotted a small typo: 7.2 Link to a Boost Library On *nix The o is uppercase in the 7.2 headline and the content box. -- regards, dave
David Klein <dave_chp@gmx.de> writes:
David Abrahams wrote:
David Abrahams <dave@boost-consulting.com> writes:
4) why is only boost python "hyper linked"? No reason. Asked and answered in a previous message.
This might have seemed ungrateful; sorry. I appreciate your feedback; I'm just short of time and sleep.
Don't worry, no offense taken.
5) I'd actually would swap 5.2 and 5.3 ... i think most windows users prefer using stuff in an ide an not on the cmdline, so using IDE should come before cmdline. True, but the IDE instructions are much more complicated than the cmdline instructions. I've been using the principle that when the tracks bifurcate, branches are ordered from shortest to longest, to make it easier to find the branch you want.
Does that make sense or should I have used a different criterion?
Well yes it does, but I probably would have ordered by "most common use" or something like that.
In that case we should always start with Windows. I tried a consistent organization, but it just wasn't working. For some user, the instructions she's looking for are too far away. How important is this?
BTW, just spotted a small typo: 7.2 Link to a Boost Library On *nix The o is uppercase in the 7.2 headline and the content box.
Thanks, fixed. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
In that case we should always start with Windows.
I tried a consistent organization, but it just wasn't working. For some user, the instructions she's looking for are too far away. How important is this?
I don't think its much of a problem, because of the content box. Hm, maybe a better idea is reordering like this ... windows build sample build boost link to boost *nix build sample build boost link to boost ... so all information for 1 toolset is 'just a scroll away' ;)
I think, ultimately, it would be best if we had a separate document for each platform/environment.
And you could just 'rip' these paragraphs out and replace them with a link, when you're actually going to write these seperate docs. -- regards, dave
David Klein <dave_chp@gmx.de> writes:
David Abrahams wrote:
In that case we should always start with Windows.
I tried a consistent organization, but it just wasn't working. For some user, the instructions she's looking for are too far away. How important is this?
I don't think its much of a problem, because of the content box.
Hm, maybe a better idea is reordering like this ...
windows build sample build boost link to boost
*nix build sample build boost link to boost
... so all information for 1 toolset is 'just a scroll away' ;)
I think, ultimately, it would be best if we had a separate document for each platform/environment.
And you could just 'rip' these paragraphs out and replace them with a link, when you're actually going to write these seperate docs.
Now that the document structure has settled down, it looks like I may be able to achieve separate documents. I'll try to get to it before the weekend... -- Dave Abrahams Boost Consulting www.boost-consulting.com
"David Abrahams" <dave@boost-consulting.com> wrote in message news:87lkleyww8.fsf@pereiro.luannocracy.com...
You can review the guide at http://www.boost-consulting.com/boost/more/getting_started.html.
4. The only Boost libraries that can't be used without separate compilation are ... Boost.Test
This is not exactly true for Boost.Test. Boost.Test supplies inline versions for all components. This need to be somehow reflected to avoid confusion. Also since you put a link on Boost.Python, I think we need to set the link for each library in the list that refer to the compilation page/description for appropriate library
7. ... Boost.Python users should read that library's own build documentation as there are several library-specific issues to consider
I understand that you are best familiar with your own library, but I believe this statement needs to be made generic. The same could be said about Boost.Test and am sure other libraries have their quirks.If in addition to the genric statrment we add links to build doc for each standalone lib as I suggested above it should be good enough.
7.3 Library naming ...
-vc71 Toolset tag: identifies the toolset and version used to build the binary.
Do I understand correctly that you streamlined names for msvc based toolsets? Doesn't toolset tag here should refer to msvc either?
9. Appendix...
In several places this appendix sounds kinda silly, like you are writing it for the 6 year old computer novice, and not a computer programmer IMO. The same "press Return key" could be recommended for linux user either isn't it?
"Gennadiy Rozental" <gennadiy.rozental@thomson.com> writes:
"David Abrahams" <dave@boost-consulting.com> wrote in message news:87lkleyww8.fsf@pereiro.luannocracy.com...
You can review the guide at http://www.boost-consulting.com/boost/more/getting_started.html.
4. The only Boost libraries that can't be used without separate compilation are ... Boost.Test
Thanks for looking at this, Gennadiy,
This is not exactly true for Boost.Test. Boost.Test supplies inline versions for all components. This need to be somehow reflected to avoid confusion.
So Boost.Test *doesn't* require separate compilation? If that's the case, I'll remove it from the list and add a mention of it to the paragraph at the bottom of the box
Also since you put a link on Boost.Python, I think we need to set the link for each library in the list that refer to the compilation page/description for appropriate library
That's a good idea. The Boost.Python link currently just refers to its front page... ...On second thought, I'm not sure. I don't want to flood people with information or lead them to believe that they need to read all those pages before they can build the Boost libraries. Maybe I should just remove the link from Boost.Python. What about that?
7. ... Boost.Python users should read that library's own build documentation as there are several library-specific issues to consider
I understand that you are best familiar with your own library, but I believe this statement needs to be made generic.
I don't believe so. The case of Boost.Python is an outlier: a. There is a very strange thing that happens with build variants b. Using the static library will in most cases cost functionality and c. Unlike all other Boost libraries, auto-link chooses the dynamic library by default. That said, by the same logic I used above, I could remove that note. It's not needed in order to complete the tutorial.
The same could be said about Boost.Test and am sure other libraries have their quirks.If in addition to the genric statrment we add links to build doc for each standalone lib as I suggested above it should be good enough.
I'm very concerned about adding needless complication to this introductory document. Maybe in the section 8 that would be an appropriate place for links to library-specific build/configuration documentation.
7.3 Library naming ...
-vc71 Toolset tag: identifies the toolset and version used to build the binary.
Do I understand correctly that you streamlined names for msvc based toolsets?
I don't know what you mean. I didn't streamline anything.
Doesn't toolset tag here should refer to msvc either?
Sorry, I don't understand.
9. Appendix...
In several places this appendix sounds kinda silly, like you are writing it for the 6 year old computer novice, and not a computer programmer IMO. The same "press Return key" could be recommended for linux user either isn't it?
From reading user comments over the years I was given to believe that there's a community of GUI-only Windows users for whom command-line tools are utterly foreign; this section was designed to serve them. That said, I have no way of knowing what the appropriate level of detail is for those people. If this group is sure I've aimed at an inappropriate level, I'm happy to change it. Let's see what others think.
-- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams <dave@boost-consulting.com> writes:
"Gennadiy Rozental" <gennadiy.rozental@thomson.com> writes:
This is not exactly true for Boost.Test. Boost.Test supplies inline versions for all components. This need to be somehow reflected to avoid confusion.
So Boost.Test *doesn't* require separate compilation?
If that's the case, I'll remove it from the list and add a mention of it to the paragraph at the bottom of the box
Gennadiy, can you please confirm the status? Does Boost.Test require separate compilation? If not, what should I say about it? Thanks, -- Dave Abrahams Boost Consulting www.boost-consulting.com
"David Abrahams" <dave@boost-consulting.com> wrote in message news:87slfltf8p.fsf@pereiro.luannocracy.com...
"Gennadiy Rozental" <gennadiy.rozental@thomson.com> writes:
"David Abrahams" <dave@boost-consulting.com> wrote in message news:87lkleyww8.fsf@pereiro.luannocracy.com...
You can review the guide at http://www.boost-consulting.com/boost/more/getting_started.html.
4. The only Boost libraries that can't be used without separate compilation are ... Boost.Test
Thanks for looking at this, Gennadiy,
This is not exactly true for Boost.Test. Boost.Test supplies inline versions for all components. This need to be somehow reflected to avoid confusion.
So Boost.Test *doesn't* require separate compilation?
If that's the case, I'll remove it from the list and add a mention of it to the paragraph at the bottom of the box
Well. As usual the picture is gray :o) The statement "Boost.Test can't be used without separate compilation" is incorrect: all Boost.Test component have inline verstion But: 1. Some (most?) boost libraries *will* require offline library for their unit tests to work 2. It's not required but recommended to precompile at least UTF
The same could be said about Boost.Test and am sure other libraries have their quirks.If in addition to the genric statrment we add links to build doc for each standalone lib as I suggested above it should be good enough.
I'm very concerned about adding needless complication to this introductory document. Maybe in the section 8 that would be an appropriate place for links to library-specific build/configuration documentation.
Summary of Boost.Test build instructions should be located here libs/test/doc/compilation.html I will try to put it there soon Gennadiy
Gennadiy Rozental said: (by the date of Thu, 14 Dec 2006 03:02:05 -0500)
So Boost.Test *doesn't* require separate compilation?
If that's the case, I'll remove it from the list and add a mention of it to the paragraph at the bottom of the box
Well. As usual the picture is gray :o)
Under this URL http://boost-consulting.com/boost/libs/test/doc/usage/generic.html there is written: ---- Prefer offline compiled libraries to the inline included components If you are just want to write quick simple test in environment where you never used Boost.Test before - yes, use included components. But if you plan to use Boost.Test on permanent basis, small investment of time needed to build (if not build yet), install and change you makefiles/project settings will soon return to you in a form of shorter compilation time. Why do you need to make your compiler do the same work over and over again? ---- -- Janek Kozicki |
"Gennadiy Rozental" <gennadiy.rozental@thomson.com> writes:
"David Abrahams" <dave@boost-consulting.com> wrote in message news:87slfltf8p.fsf@pereiro.luannocracy.com...
"Gennadiy Rozental" <gennadiy.rozental@thomson.com> writes:
"David Abrahams" <dave@boost-consulting.com> wrote in message news:87lkleyww8.fsf@pereiro.luannocracy.com...
You can review the guide at http://www.boost-consulting.com/boost/more/getting_started.html.
4. The only Boost libraries that can't be used without separate compilation are ... Boost.Test
Thanks for looking at this, Gennadiy,
This is not exactly true for Boost.Test. Boost.Test supplies inline versions for all components. This need to be somehow reflected to avoid confusion.
So Boost.Test *doesn't* require separate compilation?
If that's the case, I'll remove it from the list and add a mention of it to the paragraph at the bottom of the box
Well. As usual the picture is gray :o)
The statement "Boost.Test can't be used without separate compilation" is incorrect: all Boost.Test component have inline verstion
Which is the default? If I just compile against the Boost.Test headers will it work, or do I need to set some #define? I need to know so I can tell people what they have to do.
But:
1. Some (most?) boost libraries *will* require offline library for their unit tests to work
Are you just saying that if you want to test Boost, you'll need the separate Boost.Test binary? I don't see why that would matter one bit to the reader, since it's built automatically and on demand by the build system when you run the tests.
2. It's not required but recommended to precompile at least UTF
Why? I need to know so I can tell people why they should care.
I'm very concerned about adding needless complication to this introductory document. Maybe in the section 8 that would be an appropriate place for links to library-specific build/configuration documentation.
Summary of Boost.Test build instructions should be located here libs/test/doc/compilation.html I will try to put it there soon
Thank you. -- Dave Abrahams Boost Consulting www.boost-consulting.com
"David Abrahams" <dave@boost-consulting.com> wrote in message news:87ejr28kzc.fsf@pereiro.luannocracy.com...
"Gennadiy Rozental" <gennadiy.rozental@thomson.com> writes:
"David Abrahams" <dave@boost-consulting.com> wrote in message news:87slfltf8p.fsf@pereiro.luannocracy.com...
"Gennadiy Rozental" <gennadiy.rozental@thomson.com> writes:
"David Abrahams" <dave@boost-consulting.com> wrote in message news:87lkleyww8.fsf@pereiro.luannocracy.com...
You can review the guide at http://www.boost-consulting.com/boost/more/getting_started.html.
4. The only Boost libraries that can't be used without separate compilation are ... Boost.Test
Thanks for looking at this, Gennadiy,
This is not exactly true for Boost.Test. Boost.Test supplies inline versions for all components. This need to be somehow reflected to avoid confusion.
So Boost.Test *doesn't* require separate compilation?
If that's the case, I'll remove it from the list and add a mention of it to the paragraph at the bottom of the box
Well. As usual the picture is gray :o)
The statement "Boost.Test can't be used without separate compilation" is incorrect: all Boost.Test component have inline verstion
Which is the default? If I just compile against the Boost.Test headers will it work, or do I need to set some #define?
There is no default. You could use either of them. It all depends on what header you are including Test module with #include <boost/test/unit_test.hpp> Will need an offline library The same test module but with #include <boost/test/included/unit_test.hpp> won't need an offline library.
I need to know so I can tell people what they have to do.
But:
1. Some (most?) boost libraries *will* require offline library for their unit tests to work
Are you just saying that if you want to test Boost, you'll need the separate Boost.Test binary? I don't see why that would matter one bit to the reader, since it's built automatically and on demand by the build system when you run the tests.
I don't share yet your optimism on expecting all Boost users to learn and use Boost.Build system. But you may have a point here.
2. It's not required but recommended to precompile at least UTF
Why?
The UTF is comparatively heavyweight component. Would you prefer Boost.Python users to include all your sources into their project and compile them every time? That's why I say it's preferable in a long term to build standalone library. I do provide an "included" option, but mostly as a helper for the "very hurry" users. Gennadiy
Gennadiy Rozental said: (by the date of Thu, 14 Dec 2006 23:22:52 -0500)
Which is the default? If I just compile against the Boost.Test headers will it work, or do I need to set some #define?
There is no default. You could use either of them. It all depends on what header you are including
Test module with #include <boost/test/unit_test.hpp>
Will need an offline library
The same test module but with #include <boost/test/included/unit_test.hpp>
won't need an offline library.
Uh, yesterday I've read some part of the docs and I haven't seen this information mentioned there. Is is there, where? Maybe I have missed it. Also I really miss a reference. Currently the only way to learn about Boost.Test interface is to search through examples. How do I know if examples cover all commands provided by Boost.Test ? For example http://boost-consulting.com/boost/libs/test/doc/usage/generic.html says: "It's really easy to switch to automatic registration." But there is not a signle word how to do this ,,easy'' task. -- Janek Kozicki |
"Gennadiy Rozental" <gennadiy.rozental@thomson.com> writes:
Which is the default? If I just compile against the Boost.Test headers will it work, or do I need to set some #define?
There is no default. You could use either of them. It all depends on what header you are including
Test module with #include <boost/test/unit_test.hpp>
Will need an offline library
The same test module but with #include <boost/test/included/unit_test.hpp>
won't need an offline library.
Hmm, okay. I'd have done that with a preprocessor switch so when people decide to start using the separate binary they don't have to change their source files... but it's your party.
Are you just saying that if you want to test Boost, you'll need the separate Boost.Test binary? I don't see why that would matter one bit to the reader, since it's built automatically and on demand by the build system when you run the tests.
I don't share yet your optimism on expecting all Boost users to learn and use Boost.Build system.
I don't have any such optimism. I just don't expect anyone to be able to successfully run Boost unit tests without Boost.Build, and even if some few people could succeed at it, I wouldn't want to discuss that case in this document.
2. It's not required but recommended to precompile at least UTF
Why?
The UTF is comparatively heavyweight component. Would you prefer Boost.Python users to include all your sources into their project and compile them every time?
I don't care; whatever works for my users works for me.
That's why I say it's preferable in a long term to build standalone library. I do provide an "included" option, but mostly as a helper for the "very hurry" users.
OK, thanks for clarifying. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams said: (by the date of Fri, 15 Dec 2006 08:14:20 -0500)
"Gennadiy Rozental" <gennadiy.rozental@thomson.com> writes:
I don't share yet your optimism on expecting all Boost users to learn and use Boost.Build system.
I don't have any such optimism. I just don't expect anyone to be able to successfully run Boost unit tests without Boost.Build, and even if some few people could succeed at it, I wouldn't want to discuss that case in this document.
Oh, no. I already started to think that I could use Boost.Test in my own project. But changing current build system to bjam is a thing I'd prefer to avoid :( -- Janek Kozicki |
"Janek Kozicki" <janek_listy@wp.pl> wrote in message news:20061215154723.5537ee14@absurd...
David Abrahams said: (by the date of Fri, 15 Dec 2006 08:14:20 -0500)
"Gennadiy Rozental" <gennadiy.rozental@thomson.com> writes:
I don't share yet your optimism on expecting all Boost users to learn and use Boost.Build system.
I don't have any such optimism. I just don't expect anyone to be able to successfully run Boost unit tests without Boost.Build, and even if some few people could succeed at it, I wouldn't want to discuss that case in this document.
Oh, no. I already started to think that I could use Boost.Test in my own project. But changing current build system to bjam is a thing I'd prefer to avoid :(
Latest Boost.Test docs will contain building instruction for all cases. Gennadiy
Janek Kozicki <janek_listy@wp.pl> writes:
David Abrahams said: (by the date of Fri, 15 Dec 2006 08:14:20 -0500)
"Gennadiy Rozental" <gennadiy.rozental@thomson.com> writes:
I don't share yet your optimism on expecting all Boost users to learn and use Boost.Build system.
I don't have any such optimism. I just don't expect anyone to be able to successfully run Boost unit tests without Boost.Build, and even if some few people could succeed at it, I wouldn't want to discuss that case in this document.
Oh, no. I already started to think that I could use Boost.Test in my own project. But changing current build system to bjam is a thing I'd prefer to avoid :(
"Boost unit tests" == "the tests in libs/*/test/Jamfile.v2", not your own tests. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams said: (by the date of Fri, 15 Dec 2006 13:42:36 -0500)
Janek Kozicki <janek_listy@wp.pl> writes:
Oh, no. I already started to think that I could use Boost.Test in my own project. But changing current build system to bjam is a thing I'd prefer to avoid :(
"Boost unit tests" == "the tests in libs/*/test/Jamfile.v2", not your own tests.
thanks, I feel relieved :) -- Janek Kozicki |
"David Abrahams" <dave@boost-consulting.com> wrote in message news:871wn12teb.fsf@pereiro.luannocracy.com...
"Gennadiy Rozental" <gennadiy.rozental@thomson.com> writes:
Which is the default? If I just compile against the Boost.Test headers will it work, or do I need to set some #define?
There is no default. You could use either of them. It all depends on what header you are including
Test module with #include <boost/test/unit_test.hpp>
Will need an offline library
The same test module but with #include <boost/test/included/unit_test.hpp>
won't need an offline library.
Hmm, okay. I'd have done that with a preprocessor switch so when people decide to start using the separate binary they don't have to change their source files... but it's your party.
Hmm, It does make sense. I will do this for next release. Gennadiy
The quality of this crucial document shapes our users' first experiences with Boost, and for many, determines whether they use Boost or give up in frustration. It's not about what you have wrote, but about what you did not write. So its just a suggestion.
If this document is for the boost begginers, isn't is good to show which library is 'easy' to start? I know it is a bit controversial subject, but it is almost clear that, at least for C++ beginners (and maybe for most of the 'ordinary' C++ programmers) libraries like MPL or spirit is difficult. While libraries like boost:timer and shared_ptr is easy to use. So my suggestion is to make some section like "where to start?" and make some pointers like.... for C++ beginners, try shared_ptr, boost::timer, etc for those interested in functional programming, see function, bind.... for those interested in numerical programming, see random, uBLAS and so on and on. Hope this help. -- Satoshi Fujimoto <fujim@be.to>
----Original Message---- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Satoshi Fujimoto Sent: 12 December 2006 07:23 To: boost@lists.boost.org Subject: Re: [boost] Attention Boosters
The quality of this crucial document shapes our users' first experiences with Boost, and for many, determines whether they use Boost or give up in frustration. It's not about what you have wrote, but about what you did not write. So its just a suggestion.
If this document is for the boost begginers, isn't is good to show which library is 'easy' to start? I know it is a bit controversial subject, but it is almost clear that, at least for C++ beginners (and maybe for most of the 'ordinary' C++ programmers) libraries like MPL or spirit is difficult. While libraries like boost:timer and shared_ptr is easy to use.
So my suggestion is to make some section like "where to start?" and make some pointers like....
for C++ beginners, try shared_ptr, boost::timer, etc
I disagree. I think most people will download boost because they have a particular problem to solve and hope that boost will help them solve it, and not because they think "I ought to use boost". If the problem they have is that they neeed some sort of parser, telling them to start with boost::timer is just wasting their time.
for those interested in functional programming, see function, bind.... for those interested in numerical programming, see random, uBLAS
Of course that sort of description is useful, but not, I think, in "Getting Started". By the time people get here, they have already decided they want to use a particular library (or libraries), and just want to know how to get past all the tedium of getting the libraries and includes in the right place. (Remember this was the point of the original "Hello World" - it's a trivial program, but getting it to compile and execute is/was non-trivial.)
and so on and on.
Hope this help.
-- Martin Bonner Pi Technology, Milton Hall, Ely Rd, Cambridge, CB24 6WZ, ENGLAND +44 (0) 1223 203894
Martin Bonner wrote:
----Original Message---- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Satoshi Fujimoto
So my suggestion is to make some section like "where to start?" and make some pointers like....
for C++ beginners, try shared_ptr, boost::timer, etc
I disagree. I think most people will download boost because they have a particular problem to solve and hope that boost will help them solve it, and not because they think "I ought to use boost". If the problem they have is that they neeed some sort of parser, telling them to start with boost::timer is just wasting their time.
I second that. I think it is important to promote boost not as a heavy monolith, but as a set of modules. That is not only a matter of perception. I believe it would benefit the whole project if things were handled in a more modular way. While the technicalities of that are off-topic for this discussion, I believe that it would help everybody if boost was perceived as a repository of useful, but largely independent libraries.
for those interested in functional programming, see function, bind.... for those interested in numerical programming, see random, uBLAS
Of course that sort of description is useful, but not, I think, in "Getting Started". By the time people get here, they have already decided they want to use a particular library (or libraries), and just want to know how to get past all the tedium of getting the libraries and includes in the right place. (Remember this was the point of the original "Hello World" - it's a trivial program, but getting it to compile and execute is/was non-trivial.)
Right. And to follow up on the above theme, people continue to ask how to set up not boost as a whole, but the parts they are interested in. ("How can I install boost.python but not boost.serialization ?", say.) I do understand that as of boost 1.34 boost is not modular in that way, and so the Getting Started guide should document what boost is, not what it could be. Still, there is room to modularize boost on a perceptional level as a start. Thanks, Stefan -- ...ich hab' noch einen Koffer in Berlin...
Stefan Seefeld <seefeld@sympatico.ca> writes:
And to follow up on the above theme, people continue to ask how to set up not boost as a whole, but the parts they are interested in. ("How can I install boost.python but not boost.serialization ?", say.)
I do understand that as of boost 1.34 boost is not modular in that way,
It isn't? That's news to me. -- Dave Abrahams Boost Consulting www.boost-consulting.com
Thanks for the comment.
If the problem they have is that they neeed some sort of parser, telling them to start with boost::timer is just wasting their time. Yes. I agree, and that's not my point.
By the time people get here, they have already decided they want to use a particular library (or libraries), and just want to know how to get past all the tedium of getting the libraries and includes in the right place. (Remember this was the point of the original "Hello World" - it's a trivial program, but getting it to compile and execute is/was non-trivial.) I understand your point. But is this the document for people who "already" decided to use boost? No. I dont think so.
The quality of this crucial document shapes our users' first experiences with Boost, and for many, determines whether they use Boost or give up in frustration. It means that this document is not for those who have already decided to use boost, but for
David Abraham said at the first post as follows; those who wants to know what boost is, or what boost can do, to decide whether they use boost or not. So it is not tirvial to show what kind of modules do boost have, and what kind of functions boost have. From my personal experience, whenever I found some C++ libraries that seems useful, I first read "getting started" or else document to see what can be done. Not how to compile build, etc. And current boost web site do not have this kind pointers like what I said in the last e-mail.
for C++ beginners, try shared_ptr, boost::timer, etc for those interested in functional programming, see function, bind.... for those interested in numerical programming, see random, uBLAS and so on and on.
Hope this help. -- Satoshi Fujimoto <fujim@be.to>
Satoshi Fujimoto <fujim@be.to> writes:
The quality of this crucial document shapes our users' first experiences with Boost, and for many, determines whether they use Boost or give up in frustration. It's not about what you have wrote, but about what you did not write. So its just a suggestion.
If this document is for the boost begginers, isn't is good to show which library is 'easy' to start? I know it is a bit controversial subject, but it is almost clear that, at least for C++ beginners (and maybe for most of the 'ordinary' C++ programmers) libraries like MPL or spirit is difficult. While libraries like boost:timer and shared_ptr is easy to use.
So my suggestion is to make some section like "where to start?" and make some pointers like....
for C++ beginners, try shared_ptr, boost::timer, etc for those interested in functional programming, see function, bind.... for those interested in numerical programming, see random, uBLAS and so on and on.
Such material might be a great idea, but I think it is outside the scope of this particular document. There ought to be a "what next?" document, but that's a separate thing. -- Dave Abrahams Boost Consulting www.boost-consulting.com
Thanks Dave. I have some problem: ./configure --prefix=/usr/local/src/boost.hg/stage --with-icu Building Boost.Jam with toolset gcc... tools/jam/src/bin.linux/bjam Detecting Python version... 2.4 Detecting Python root... /usr Unicode/ICU support for Boost.Regex?... yes. Generating Makefile... [nbecker@nbecker3 boost.hg]$ make ./tools/jam/src/bin.linux/bjam -sPYTHON_ROOT=/usr -sPYTHON_VERSION=2.4 -sHAVE_ICU=1 -sTOOLS=gcc warning: Python location is not configured warning: the Boost.Python library won't be built Building Boost.Regex with the optional Unicode/ICU support disabled. Please refer to the Boost.Regex documentation for more information (and if you don't know what ICU is then you probably don't need it). The mpi module has not been initialized; MPI libraries will not be built. hint: add "using mpi ;" to user-config.jam to enable MPI support. make: *** [all] Interrupt
On Dec 12, 2006, at 8:49 AM, Neal Becker wrote:
Thanks Dave. I have some problem: ./configure --prefix=/usr/local/src/boost.hg/stage --with-icu Building Boost.Jam with toolset gcc... tools/jam/src/bin.linux/bjam Detecting Python version... 2.4 Detecting Python root... /usr Unicode/ICU support for Boost.Regex?... yes. Generating Makefile... [nbecker@nbecker3 boost.hg]$ make ./tools/jam/src/bin.linux/bjam -sPYTHON_ROOT=/usr - sPYTHON_VERSION=2.4 -sHAVE_ICU=1 -sTOOLS=gcc warning: Python location is not configured warning: the Boost.Python library won't be built Building Boost.Regex with the optional Unicode/ICU support disabled. Please refer to the Boost.Regex documentation for more information (and if you don't know what ICU is then you probably don't need it). The mpi module has not been initialized; MPI libraries will not be built. hint: add "using mpi ;" to user-config.jam to enable MPI support.
You must be using a *very* recent checkout of Boost from the CVS trunk (not RC_1_34_0), because I just checked in that MPI logic last night :) Anyway, the configure script needs to be updated for BBv2, because it is incorrectly passing information about your Python installation along to bjam (the BBv1 way doesn't work). I'll try to get this fixed soon. Cheers, Doug
Douglas Gregor wrote:
On Dec 12, 2006, at 8:49 AM, Neal Becker wrote:
Thanks Dave. I have some problem: ./configure --prefix=/usr/local/src/boost.hg/stage --with-icu Building Boost.Jam with toolset gcc... tools/jam/src/bin.linux/bjam Detecting Python version... 2.4 Detecting Python root... /usr Unicode/ICU support for Boost.Regex?... yes. Generating Makefile... [nbecker@nbecker3 boost.hg]$ make ./tools/jam/src/bin.linux/bjam -sPYTHON_ROOT=/usr - sPYTHON_VERSION=2.4 -sHAVE_ICU=1 -sTOOLS=gcc warning: Python location is not configured warning: the Boost.Python library won't be built Building Boost.Regex with the optional Unicode/ICU support disabled. Please refer to the Boost.Regex documentation for more information (and if you don't know what ICU is then you probably don't need it). The mpi module has not been initialized; MPI libraries will not be built. hint: add "using mpi ;" to user-config.jam to enable MPI support.
You must be using a *very* recent checkout of Boost from the CVS trunk (not RC_1_34_0), because I just checked in that MPI logic last night :)
Anyway, the configure script needs to be updated for BBv2, because it is incorrectly passing information about your Python installation along to bjam (the BBv1 way doesn't work). I'll try to get this fixed soon.
Where are beginner instructions for using bbv2? bbv1 is removed. I guessed that putting using python : 2.4 ; into user-config.jam would at least get python going, but I can't seem to convince bbv2 that I want ICU.
Neal Becker <ndbecker2@gmail.com> writes:
Where are beginner instructions for using bbv2? bbv1 is removed.
I guessed that putting
using python : 2.4 ;
into user-config.jam would at least get python going,
You probably only need using python ; Cheers, -- Dave Abrahams Boost Consulting www.boost-consulting.com
Neal Becker <ndbecker2@gmail.com> writes:
Thanks Dave. I have some problem: ./configure --prefix=/usr/local/src/boost.hg/stage --with-icu Building Boost.Jam with toolset gcc... tools/jam/src/bin.linux/bjam Detecting Python version... 2.4 Detecting Python root... /usr Unicode/ICU support for Boost.Regex?... yes. Generating Makefile... [nbecker@nbecker3 boost.hg]$ make ./tools/jam/src/bin.linux/bjam -sPYTHON_ROOT=/usr -sPYTHON_VERSION=2.4 -sHAVE_ICU=1 -sTOOLS=gcc warning: Python location is not configured warning: the Boost.Python library won't be built Building Boost.Regex with the optional Unicode/ICU support disabled. Please refer to the Boost.Regex documentation for more information (and if you don't know what ICU is then you probably don't need it). The mpi module has not been initialized; MPI libraries will not be built. hint: add "using mpi ;" to user-config.jam to enable MPI support. make: *** [all] Interrupt
Is that Interrupt from you pressing ^C, or something else? If the former, then what, specifically, is the problem you're having? -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
You can review the guide at http://www.boost-consulting.com/boost/more/getting_started.html.
Hi David, Thank you for the great document. It should help ease users into Boost. I just have a couple of suggestions/comments. In Section 4, would it be more intuitive to list those libraries that are header-only? The topic heading is "Header-Only Libraries," but the list is non-header-only libraries. Also, in terms of deciding if they need to compile boost, having a list of libraries that *don't* require compilation might be more useful. In Section 6.3, the Unix command line is missing --toolset. Some of the comments in that section (specifically the Note) imply that --toolset is mandatory. Is it not needed? David
David Walthall <walthall@stanfordalumni.org> writes:
David Abrahams wrote:
You can review the guide at http://www.boost-consulting.com/boost/more/getting_started.html.
Hi David,
Thank you for the great document. It should help ease users into Boost. I just have a couple of suggestions/comments.
In Section 4, would it be more intuitive to list those libraries that are header-only?
Yes, but the list would be too long and too hard to maintain.
The topic heading is "Header-Only Libraries," but the list is non-header-only libraries. Also, in terms of deciding if they need to compile boost, having a list of libraries that *don't* require compilation might be more useful.
Agreed, but IMO it's impractical.
In Section 6.3, the Unix command line is missing --toolset. Some of the comments in that section (specifically the Note) imply that --toolset is mandatory. Is it not needed?
Thanks, Peter D. already pointed that one out. -- Dave Abrahams Boost Consulting www.boost-consulting.com
This document looks good in lynx, even "My name is your name" is readable. ./configure --help should be probably explained at the same level of details as 'don't type $' or 'hold down the control key and press "Z"'. It prints more then one standard text screen and you would either teach users to Shift-PageUp, Shift-PageDown (Scroll followed by PageUp/PageDown and then Scroll again on FreeBSD) or use ./configure --help | more. I see a lot of badly formatted C: \Program`` \ ``Files\boost\boost_1_34_0\lib\ in the document. -- Alexander Nasonov http://nasonov.blogspot.com
Alexander Nasonov <alnsn@yandex.ru> writes:
This document looks good in lynx, even "My name is your name" is readable.
:)
./configure --help should be probably explained at the same level of details as 'don't type $' or 'hold down the control key and press "Z"'. It prints more then one standard text screen and you would either teach users to Shift-PageUp, Shift-PageDown (Scroll followed by PageUp/PageDown and then Scroll again on FreeBSD) or use ./configure --help | more.
Hmm, it's hard to do that in a way that will work everywhere. Rene, what about building some kind of "more" functionality into the Boost.Build help system?
I see a lot of badly formatted C: \Program`` \ ``Files\boost\boost_1_34_0\lib\ in the document.
Got it, thanks. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
Alexander Nasonov <alnsn@yandex.ru> writes:
./configure --help should be probably explained at the same level of details as 'don't type $' or 'hold down the control key and press "Z"'. It prints more then one standard text screen and you would either teach users to Shift-PageUp, Shift-PageDown (Scroll followed by PageUp/PageDown and then Scroll again on FreeBSD) or use ./configure --help | more.
Hmm, it's hard to do that in a way that will work everywhere. Rene, what about building some kind of "more" functionality into the Boost.Build help system?
Ah, seems like a very bad idea to me. I think writing code that is so platform dependent and is commonly known to be available as the separate utility "more" will create more problems than it would solve. A better idea is to add that functionality to the configure script itself. Just have it figure out a paging program to use to send such output to. Personally I wouldn't add such a thing at all. I would think you would be hard pressed to find Unix users who don't know how to use "more", or use a terminal/shell window with a scroll bar. -- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org - grafik/redshift-software.com -- 102708583/icq - grafikrobot/aim - grafikrobot/yahoo
Rene Rivera <grafikrobot@gmail.com> writes:
A better idea is to add that functionality to the configure script itself. Just have it figure out a paging program to use to send such output to.
Works for configure but not for "bjam --help"
Personally I wouldn't add such a thing at all. I would think you would be hard pressed to find Unix users who don't know how to use "more", or use a terminal/shell window with a scroll bar.
Probably true. Good call; let's not do it. -- Dave Abrahams Boost Consulting www.boost-consulting.com
Rene Rivera wrote:
Ah, seems like a very bad idea to me. I think writing code that is so platform dependent and is commonly known to be available as the separate utility "more" will create more problems than it would solve.
I completely agree.
A better idea is to add that functionality to the configure script itself. Just have it figure out a paging program to use to send such output to.
Does it really a problem that more is unavailable? In other words, why introduce more complexity when it's enough to instruct people to use more or their favorite pager?
Personally I wouldn't add such a thing at all. I would think you would be hard pressed to find Unix users who don't know how to use "more", or use a terminal/shell window with a scroll bar.
I wouldn't do either but I can easily imagine new generation C++ developer who just installed Fedora/Ubuntu/etc, opened KDevelop or other IDE and would like to play with boost but has no idea yet how to use bash. Boost's getting started guide would be a first bash guide for them ;-) -- Alexander Nasonov http://nasonov.blogspot.com I hate war as only a soldier who has lived it can, only as one who has seen its brutality, its futility, its stupidity. -- Dwight Eisenhower -- This quote is generated by: /usr/pkg/bin/curl -L http://tinyurl.com/veusy \ | sed -e 's/^document\.write(.//' -e 's/.);$/ --/' \ -e 's/<[^>]*>//g' -e 's/^More quotes from //' \ | fmt | tee ~/.signature-quote
Alexander Nasonov <alnsn@yandex.ru> writes:
Rene Rivera wrote:
Ah, seems like a very bad idea to me. I think writing code that is so platform dependent and is commonly known to be available as the separate utility "more" will create more problems than it would solve.
I completely agree.
A better idea is to add that functionality to the configure script itself. Just have it figure out a paging program to use to send such output to.
Does it really a problem that more is unavailable? In other words, why introduce more complexity when it's enough to instruct people to use more or their favorite pager?
Because that introduces complexity into the instructions.
Personally I wouldn't add such a thing at all. I would think you would be hard pressed to find Unix users who don't know how to use "more", or use a terminal/shell window with a scroll bar.
I wouldn't do either but I can easily imagine new generation C++ developer who just installed Fedora/Ubuntu/etc, opened KDevelop or other IDE and would like to play with boost but has no idea yet how to use bash. Boost's getting started guide would be a first bash guide for them ;-)
Please, no! I want to keep the scope of the document limited, not try to teach everything under the sun. -- Dave Abrahams Boost Consulting www.boost-consulting.com
Hello, That's a nice installation guide. Since you are targeting beginners, I would add two sections: 1. uninstall Boost. If it is easy to clean up, more people may be tempted to give it a try. 2. upgrade from an older version. Also, beginners may wonder if it is possible to have different versions of Boost on the same system. "David Abrahams" <dave@boost-consulting.com> wrote in message news:87lkleyww8.fsf@pereiro.luannocracy.com...
I've just finished my 2nd rewrite of the Boost Getting Started Guide. The quality of this crucial document shapes our users' first experiences with Boost, and for many, determines whether they use Boost or give up in frustration.
I really need feedback on what I've done, **especially from experienced Boosters** who can vett my statements for accuracy. I have already received some really valuable input from this group and poured it into this 2nd rewrite. There were, however, quite a few problems I discovered by chance through communications with experienced Boosters who haven't given me feedback on the guide. I'm wonder what problems I'm still missing, and I hope you can tell me.
You can review the guide at http://www.boost-consulting.com/boost/more/getting_started.html.
Thank you for your time,
-- Dave Abrahams Boost Consulting www.boost-consulting.com
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
"John Christopher" <jcxxr@yahoo.com> writes:
Hello, That's a nice installation guide. Since you are targeting beginners, I would add two sections: 1. uninstall Boost. If it is easy to clean up, more people may be tempted to give it a try.
Hm. It's easy to explain how to clean up unless you use special options like --libdir and --includedir. I'm not sure I know how to give those instructions in a way that doesn't complicate the document. I think that's a whole 'nother page.
2. upgrade from an older version. Also, beginners may wonder if it is possible to have different versions of Boost on the same system.
Well, it is, but that's not a very beginnerish thing to want to do, is it? Also, I normally take "upgrading" to mean replacing an earlier version with a later one. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams said: (by the date of Mon, 11 Dec 2006 15:56:23 -0500) can you, please, add a link to boost docs (http://www.boost.org/libs/libraries.htm) in section 8 ? -- Janek Kozicki |
participants (22)
-
"JOAQUIN LOPEZ MU?Z" -
Aleksey Gurtovoy -
Alexander Nasonov -
Anthony Williams -
David Abrahams -
David Klein -
David Walthall -
Douglas Gregor -
Gennadiy Rozental -
Janek Kozicki -
John Christopher -
Martin Bonner -
Mathias Gaunard -
Neal Becker -
Paul Giaccone -
Peter Dimov -
Rene Rivera -
Roland Schwarz -
Roman Yakovenko -
Satoshi Fujimoto -
Stefan Seefeld -
Tobias Schwinger