[ANN] New documentation style sheet
The good folks at boost-docs have been working on improving the look-and-feel of Boost's documentation. This work is based largely on Rene Rivera's website redesign. The change went in to both HEAD and the release branch a few days ago. The biggest change is a smaller font. We've also improved readability by eliminating colored backgrounds, and improved the presentation of many elements of the Doxygen-generated reference sections. Please take a moment to have a look at the new docs: http://tinyurl.com/4b9gc. Compare to the style of the 1.33.1 docs here: http://tinyurl.com/rujfh. (I notice that there is some strangeness at the bottom of the libraries.html file the above link takes you to. There should be an alphabetized lists of libraries, and instead there is a fragment of the Boost.Concept_check documentation. That's clearly a bug, but it's not related to the style change.) Report any problems with the new style to boost-docs@lists.sourceforge.net. Thanks, -- Eric Niebler Boost Consulting www.boost-consulting.com
"Eric Niebler" <eric@boost-consulting.com> wrote
Please take a moment to have a look at the new docs: http://tinyurl.com/4b9gc. Compare to the style of the 1.33.1 docs here: http://tinyurl.com/rujfh.
Looks great! (and the absence of right justification is a major improvement, IMO) Regards, Arkadiy
"Arkadiy Vertleyb" <vertleyb@hotmail.com> wrote
"Eric Niebler" <eric@boost-consulting.com> wrote
Please take a moment to have a look at the new docs: http://tinyurl.com/4b9gc. Compare to the style of the 1.33.1 docs here: http://tinyurl.com/rujfh.
Looks great!
(and the absence of right justification is a major improvement, IMO)
Actally I would like to add a couple of things: 1) I did like shaded background for the code fragments. They used to split the document in parts, and made it more readable; 2) The font does feel a little too small to be comfortable to read. 3) What is this "Ctrl+" mentioned a few times before? It doesn't work in my IE. 4) View/Text size/Largest seem to affect only indexes, the other parts of the document remain unchanged. One last thing. My main requirement to any document is the ability to conveniantly print it out. This is totaly missing from HTML versions. In fact, I would much prefer a single HTML with anchors to what we have now. I guess PDFs are going to compensate for this. Will they be available? Regards, Arkadiy
Arkadiy Vertleyb wrote:
"Arkadiy Vertleyb" <vertleyb@hotmail.com> wrote
One last thing. My main requirement to any document is the ability to conveniantly print it out. This is totaly missing from HTML versions. In fact, I would much prefer a single HTML with anchors to what we have now. I guess PDFs are going to compensate for this. Will they be available?
Yes. BoostBook can generate PDFs as well. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
"Joel de Guzman" <joel@boost-consulting.com> wrote
Arkadiy Vertleyb wrote:
"Arkadiy Vertleyb" <vertleyb@hotmail.com> wrote
One last thing. My main requirement to any document is the ability to conveniantly print it out. This is totaly missing from HTML versions. In fact, I would much prefer a single HTML with anchors to what we have now. I guess PDFs are going to compensate for this. Will they be available?
Yes. BoostBook can generate PDFs as well.
But are they going to be built and made available, like currently HTMLs are? Regards, Arkadiy
Arkadiy Vertleyb wrote:
"Joel de Guzman" <joel@boost-consulting.com> wrote
Arkadiy Vertleyb wrote:
"Arkadiy Vertleyb" <vertleyb@hotmail.com> wrote
One last thing. My main requirement to any document is the ability to conveniantly print it out. This is totaly missing from HTML versions.
In
fact, I would much prefer a single HTML with anchors to what we have
now. I
guess PDFs are going to compensate for this. Will they be available?
Yes. BoostBook can generate PDFs as well.
But are they going to be built and made available, like currently HTMLs are?
If you ask me, I think the answer should be yes. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
One last thing. My main requirement to any document is the ability to conveniantly print it out. This is totaly missing from HTML versions. In fact, I would much prefer a single HTML with anchors to what we have now. I guess PDFs are going to compensate for this. Will they be available?
Yes. BoostBook can generate PDFs as well.
Sigh... only up to a point, I believe that images (png's etc) are not supported in PDF output. That'll make most of the Math lib docs unreadable in PDF format. Sincerely hoping someone proves me wrong.... John.
"John Maddock" <john@johnmaddock.co.uk> writes:
One last thing. My main requirement to any document is the ability to conveniantly print it out. This is totaly missing from HTML versions. In fact, I would much prefer a single HTML with anchors to what we have now. I guess PDFs are going to compensate for this. Will they be available?
Yes. BoostBook can generate PDFs as well.
Sigh... only up to a point, I believe that images (png's etc) are not supported in PDF output. That'll make most of the Math lib docs unreadable in PDF format.
Sincerely hoping someone proves me wrong....
Have you checked whether 0.91 beta supports them? http://xmlgraphics.apache.org/fop -- Dave Abrahams Boost Consulting www.boost-consulting.com
Sincerely hoping someone proves me wrong....
Have you checked whether 0.91 beta supports them?
Thanks for the link, looks like might do, but I haven't been able to get it working yet. John.
John Maddock wrote:
Sincerely hoping someone proves me wrong.... Have you checked whether 0.91 beta supports them?
Thanks for the link, looks like might do, but I haven't been able to get it working yet.
It works, but it takes a bit of hacking. Kids, don't try this at home. ;-) In addition to fop-0.91beta, you need to download a snapshot of the current docbook-xsl stylesheets from http://docbook.sourceforge.net/snapshots/. Next, you need to change your user-config.jam to point to these guys. Mine looks like: using boostbook : C:/cygwin/home/ericne/docbook-xsl-snapshot/ : C:/cygwin/home/ericne/docbook-dtd-4.2/ ; using fop : C:/cygwin/home/ericne/fop-0.91beta/fop.bat : C:/PROGRA~1/Java/j2re1.4.2_06 ; Next, you need to hack your doc's Jamfile.v2. Using xpressive as an example: boostbook standalone : xpressive : <xsl:param>fop1.extensions=1 <xsl:param>fop.extensions=0 ; Note the two xsl:params. After this, you should be ready to use fop-0.91beta to generate PDFs. Type "bjam --v2 pdf" and away you go. If you are embedding png files, fop will complain that it can't find them. Just copy them to where fop is looking for them (somewhere deep in the bin.v2 directory) and rerun. Looking at the end result, I can't say I think fop-0.91beta is an improvement. :-P Unless you *really* need to embed png files, I say stick with fop-0.20.X. -- Eric Niebler Boost Consulting www.boost-consulting.com
"Eric Niebler" <eric@boost-consulting.com> writes:
Looking at the end result, I can't say I think fop-0.91beta is an improvement. :-P Unless you *really* need to embed png files, I say stick with fop-0.20.X.
I expect that output is somewhat tunable. Is it just OOTB formatting that you think is no improvement, or does it look like there are more fundamental issues here? Care to post two PDFs for side-by-side comparison? Thanks, -- Dave Abrahams Boost Consulting www.boost-consulting.com
Arkadiy Vertleyb wrote:
"Arkadiy Vertleyb" <vertleyb@hotmail.com> wrote
One last thing. My main requirement to any document is the ability to conveniantly print it out. This is totaly missing from HTML versions. In fact, I would much prefer a single HTML with anchors to what we have now. I guess PDFs are going to compensate for this. Will they be available?
Yes. BoostBook can generate PDFs as well. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
Joel de Guzman <joel@boost-consulting.com> writes:
Arkadiy Vertleyb wrote:
"Arkadiy Vertleyb" <vertleyb@hotmail.com> wrote
One last thing. My main requirement to any document is the ability to conveniantly print it out. This is totaly missing from HTML versions. In fact, I would much prefer a single HTML with anchors to what we have now. I guess PDFs are going to compensate for this. Will they be available?
Yes. BoostBook can generate PDFs as well.
Let's just be clear so that nobody is confused: BoostBook doesn't generate anything. It's a document format. We need translators to turn BoostBook format into PDF format. Those translators exist, but as usual, they could be improved. -- Dave Abrahams Boost Consulting www.boost-consulting.com
"David Abrahams" <dave@boost-consulting.com> wrote
Joel de Guzman <joel@boost-consulting.com> writes:
Arkadiy Vertleyb wrote:
"Arkadiy Vertleyb" <vertleyb@hotmail.com> wrote
One last thing. My main requirement to any document is the ability to conveniantly print it out. This is totaly missing from HTML versions. In fact, I would much prefer a single HTML with anchors to what we have now. I guess PDFs are going to compensate for this. Will they be available?
Yes. BoostBook can generate PDFs as well.
Let's just be clear so that nobody is confused: BoostBook doesn't generate anything. It's a document format. We need translators to turn BoostBook format into PDF format. Those translators exist, but as usual, they could be improved.
Actually I am still confused :-( We have the typeof.qbk file in CVS, and we updated several other files so that the typeof documentation is now generated by Metacomm's bulds. The question is -- is this all that needs to be done for the typeof documentation to appear in 1.34 in both HTML and PDF format? If no, what else needs to be done? Regards, Arkadiy
Arkadiy Vertleyb wrote:
"David Abrahams" <dave@boost-consulting.com> wrote
Let's just be clear so that nobody is confused: BoostBook doesn't generate anything. It's a document format. We need translators to turn BoostBook format into PDF format. Those translators exist, but as usual, they could be improved.
Actually I am still confused :-(
We have the typeof.qbk file in CVS, and we updated several other files so that the typeof documentation is now generated by Metacomm's bulds.
The question is -- is this all that needs to be done for the typeof documentation to appear in 1.34 in both HTML and PDF format? If no, what else needs to be done?
Yes, that's all that's needed. QuickBook is a BoostBook authoring tool. It lets you write BoostBook documentation with simple mark-up syntax, and without having to read, write, or worry about XML. But it's really BoostBook under the covers, so you get the wholesome goodness of HTML/fo/PDF/man generation. HTH, -- Eric Niebler Boost Consulting www.boost-consulting.com
"Eric Niebler" <eric@boost-consulting.com> wrote
Arkadiy Vertleyb wrote:
"David Abrahams" <dave@boost-consulting.com> wrote
Let's just be clear so that nobody is confused: BoostBook doesn't generate anything. It's a document format. We need translators to turn BoostBook format into PDF format. Those translators exist, but as usual, they could be improved.
Actually I am still confused :-(
We have the typeof.qbk file in CVS, and we updated several other files so that the typeof documentation is now generated by Metacomm's bulds.
The question is -- is this all that needs to be done for the typeof documentation to appear in 1.34 in both HTML and PDF format? If no, what else needs to be done?
Yes, that's all that's needed. QuickBook is a BoostBook authoring tool. It lets you write BoostBook documentation with simple mark-up syntax, and without having to read, write, or worry about XML. But it's really BoostBook under the covers, so you get the wholesome goodness of HTML/fo/PDF/man generation.
Right, I understand, but my question really is -- do we get this "wholesome goodness" through some sort of centralized process, or are we supposed to build the PDF ourselves, an check it in? Regards, Arkadiy
"Arkadiy Vertleyb" <vertleyb@hotmail.com> writes:
Right, I understand, but my question really is -- do we get this "wholesome goodness" through some sort of centralized process, or are we supposed to build the PDF ourselves, an check it in?
You only need to provide the Jamfile and edit $BOOST_ROOT/doc/Jamfile.v2 to reference it. -- Dave Abrahams Boost Consulting www.boost-consulting.com
"David Abrahams" <dave@boost-consulting.com> wrote
"Arkadiy Vertleyb" <vertleyb@hotmail.com> writes:
Right, I understand, but my question really is -- do we get this "wholesome goodness" through some sort of centralized process, or are we supposed to build the PDF ourselves, an check it in?
You only need to provide the Jamfile and edit $BOOST_ROOT/doc/Jamfile.v2 to reference it.
OK, got it, thanks. Regards, Arkadiy
Arkadiy Vertleyb wrote:
"Eric Niebler" <eric@boost-consulting.com> wrote
Arkadiy Vertleyb wrote:
"David Abrahams" <dave@boost-consulting.com> wrote
Let's just be clear so that nobody is confused: BoostBook doesn't generate anything. It's a document format. We need translators to turn BoostBook format into PDF format. Those translators exist, but as usual, they could be improved. Actually I am still confused :-(
We have the typeof.qbk file in CVS, and we updated several other files so that the typeof documentation is now generated by Metacomm's bulds.
The question is -- is this all that needs to be done for the typeof documentation to appear in 1.34 in both HTML and PDF format? If no, what else needs to be done?
Yes, that's all that's needed. QuickBook is a BoostBook authoring tool. It lets you write BoostBook documentation with simple mark-up syntax, and without having to read, write, or worry about XML. But it's really BoostBook under the covers, so you get the wholesome goodness of HTML/fo/PDF/man generation.
Right, I understand, but my question really is -- do we get this "wholesome goodness" through some sort of centralized process, or are we supposed to build the PDF ourselves, an check it in?
The generation of pdf from Boostbook source is possible, but the open tools we are using to do this suffer from scalability issues. That is, it's unlikely you'll be able to just follow the instructions and get it to work without fo or some other step failing. And actually, the concept as applied to Boost as a whole has an issue with 'human scalability'. Have a look at: http://www.crystalclearsoftware.com/libraries/date_time/date_time.pdf This is the date-time Boostbook docs generated into pdf. You'll note that they weigh in at ~400 pages. About 3/4 of this is reference -- so there are about 100 pages of hand-written docs. There are currently about 20 Boostbook documented libs. So if we conservatively assume that they have 50 pages per library of non-reference docs that makes over 1000 pages for a unified Boost pdf file without ref docs. Of course this assumes you want to live without the reference and the other libs don't get converted to Boostbook. If all of Boost could be generated into pdf with all the references I believe you'd have conservatively over 5,000 pages -- and more likely over 10,000. The file would be very large and difficult to use. So I think the only rational approach is to provide multiple pdfs -- one per library and perhaps some common pdfs of build documentation or other key Boost common subjects. Trouble is that the current Boostbook build process is not really setup to generate per library pdfs. So in my view we really need to do some work on the Boostbook build infrastructure before pdf's become a realistic option. We also need to support Quickbook docs. And then there's the fact that most Boost libraries are NOT using Boostbook. So really there is a need for a massive documentation conversion project to get all of Boost uniformly available. As much as I'd like to see all this happen, I'm not holding my breath. We really need an organizer and a bunch of new volunteers with some actual time to spend to help with this sort of project -- assuming we could get everyone to agree on the need, goals, and approach, etc. We had alot of trouble recruiting for the original Boostbook project so I think Doug ended up doing the bulk of the work. So, I'm afraid that pdf boost docs will continue to be 'vaporware' for the time being. Jeff
| -----Original Message----- | From: boost-bounces@lists.boost.org | [mailto:boost-bounces@lists.boost.org] On Behalf Of Arkadiy Vertleyb | Sent: 07 April 2006 03:21 | To: boost@lists.boost.org | Subject: Re: [boost] [ANN] New documentation style sheet You can't please many of the viewers much of the time. | > (and the absence of right justification is a major improvement, IMO) Very strongly agree! | 2) The font does feel a little too small to be comfortable to read. | | 3) What is this "Ctrl+" mentioned a few times before? It | doesn't work in my IE. Try using Firefox - a MUCH better browser. Allows you to change the font size quickly. Provided the web designer doesn't think he knows better - too many of them arrogently do - making erroneous assumptions about everyoens screen size, layout, eyesight ... But even Firefox still can't print the whole document :-(( So a .pdf option is really very desirable indeed. Paul -- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB Phone and SMS text +44 1539 561830, Mobile and SMS text +44 7714 330204 mailto: pbristow@hetp.u-net.com http://www.hetp.u-net.com/index.html http://www.hetp.u-net.com/Paul%20A%20Bristow%20info.html
| -----Original Message----- | From: boost-bounces@lists.boost.org | [mailto:boost-bounces@lists.boost.org] On Behalf Of Eric Niebler | Sent: 06 April 2006 17:01 | To: Boost mailing list | Subject: [boost] [ANN] New documentation style sheet FWIW: The biggest apparent change is a smaller initial font. This doesn't help using Firefox and a 1600 x 1200 screen - the font is very feeble (thin) until a certain size increase (ctrl+) and it seems to be a different 'magnification'. (The old-style pages in Times Roman are still more readable IMO). | We've also improved readability by eliminating colored backgrounds, Agree eliminating colored backgrounds are a marked improvement. | improved the presentation of many elements of the Doxygen-generated | reference sections. Looks professional - much better than MS ;-) Paul -- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB Phone and SMS text +44 1539 561830, Mobile and SMS text +44 7714 330204 mailto: pbristow@hetp.u-net.com http://www.hetp.u-net.com/index.html http://www.hetp.u-net.com/Paul%20A%20Bristow%20info.html
The following program compiled with MSVC8 gives different results between intrinsics and boost type traits (in the wrong sense: as if the type traits library knew more about the classes than the compiler) It seems to me this is related to a bug in MSVC8 intrinsics which should not consider class two (see program below) as a POD type... The library should thus not use the __is_pod intrinsics... though I can not find in the standard a place where it is said that POD types should not have constructors... (but then class one should also be of pod type) Could someone please confirm/propose a fix? Thanks in advance, Charles-Antoine Giuliani #include <iostream> #include <boost/type_traits.hpp> struct one { one() :i(1) { } int i; }; struct two { one j; }; #define F(a) #a << ": " << (a) int main() { std::cout << F(__is_pod(one)) << '\n'; std::cout << F(boost::is_pod<one>::value) << '\n'; std::cout << '\n'; std::cout << F(__is_pod(two)) << '\n'; std::cout << F(boost::is_pod<two>::value) << '\n'; std::cout << '\n'; std::cout << F(__has_trivial_constructor(one)) << '\n'; std::cout << F(boost::has_trivial_constructor<one>::value) << '\n'; std::cout << '\n'; std::cout << F(__has_trivial_constructor(two)) << '\n'; std::cout << F(boost::has_trivial_constructor<two>::value) << '\n'; std::cout << '\n'; //Program output: //__is_pod(one): 0 //boost::is_pod<one>::value: 0 // //__is_pod(two): 1 //boost::is_pod<two>::value: 1 // //__has_trivial_constructor(one): 0 //boost::has_trivial_constructor<one>::value: 0 // //__has_trivial_constructor(two): 0 //boost::has_trivial_constructor<two>::value: 1 return 0; }
From: Thyfate [mailto:thyfate@free.fr]
The following program compiled with MSVC8 gives different results between intrinsics and boost type traits (in the wrong sense: as if the type traits library knew more about the classes than the compiler)
It seems to me this is related to a bug in MSVC8 intrinsics which should not consider class two (see program below) as a POD type... The library should thus not use the __is_pod intrinsics... though I can not find in the standard a place where it is said that POD types should not have constructors... (but then class one should also be of pod type)
Could someone please confirm/propose a fix?
We made a conscious decision to have the intrinsic match our internal notion of a pod. We knew that our notion of a pod was broken in a few ways, this being one of them. It wasn't clear to us that having __is_pod return something different than our internal notion of a pod was the right thing to do. Futhermore, we knew from experience fixing our internal notion of a pod was a breaking change, and a potentially serious one at that. In the past couple of weeks, we have been reviewing this decision to see what we can do without breaking too much code. -- Jason Shirk VC++ Compiler Team
The following program compiled with MSVC8 gives different results between intrinsics and boost type traits (in the wrong sense: as if the type traits library knew more about the classes than the compiler)
It seems to me this is related to a bug in MSVC8 intrinsics which should not consider class two (see program below) as a POD type... The library should thus not use the __is_pod intrinsics... though I can not find in the standard a place where it is said that POD types should not have constructors... (but then class one should also be of pod type)
Could someone please confirm/propose a fix?
I can't believe I left this one so long in my todo box before I spotted it again: sorry! You're quite right that __is_pod does appear to be buggy in this respect. I've done some more experimenting and it appears that: If the class "one" in your test: * has an explicit destructor, everything is OK. * has an explicit copy-constructor everthing is OK. * has an explicit assignment operator everything is OK. But if it has an explicit default constructor, even one with side-effects as your example shows, then it wrongly lables classes that encapsulate "one" as a POD. It's worse too: has_trivial_constructor has the same problem: classes that clearly do not have trivial constructors get wrongly labled as such (class "two" in your test). Darn, this is a problem, I think we're going to have to disable those two intrinsics for the next release. If we don't and has_trivial_constructor/is_pod are used to optimise-away constructor calls (one of their intended use case), then potentially calls to constructors with side effects will be omitted. Aside: I'm surprised that this matches VC++'s internal notion of POD-ness, doesn't that cause optimiser bugs in cases like this - destructors not being called when they should be? If not what use is this trait to anyone? I'm sure I must be missing something here given that I haven't actually seen VC++ to get this wrong when optimising .... Anyone else any thoughts? Thanks, John.
Thanks for your concern John. Type traits is one of the boost libraries which are most useful to me, and let me thank you and the boost team for it by the way. I am not sure I understand your point about the __has_trivial_constructor intrinsic being broken... it seems to work pretty fine to me ? Boost::is_pod and boost::has_trivial_constructor become broken because the first one use the intrinsic and the second one use the first one... As far as I am concerned, I patched boost/type_traits/intrinsics.hpp by commenting out the __is_pod intrinsic, and now everything seems working fine. Most of the time, code using is_pod can be refined to be more generic and only use the other intrinsics. I thus managed to remove all is_pod uses from my code and thus still always benefit from compiler information. Perhaps it would be possible to rebuild a non-broken is_pod using compiler information, based only on the other intrinsics ? Thanks, Charles-Antoine Giuliani -----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of John Maddock Sent: jeudi 20 avril 2006 11:58 To: boost@lists.boost.org Cc: Jason Shirk Subject: Re: [boost] Type_traits library/MSVC8 intrinsics : bug
The following program compiled with MSVC8 gives different results between intrinsics and boost type traits (in the wrong sense: as if the type traits library knew more about the classes than the compiler)
It seems to me this is related to a bug in MSVC8 intrinsics which should not consider class two (see program below) as a POD type... The library should thus not use the __is_pod intrinsics... though I can not find in the standard a place where it is said that POD types should not have constructors... (but then class one should also be of pod type)
Could someone please confirm/propose a fix?
I can't believe I left this one so long in my todo box before I spotted it again: sorry! You're quite right that __is_pod does appear to be buggy in this respect. I've done some more experimenting and it appears that: If the class "one" in your test: * has an explicit destructor, everything is OK. * has an explicit copy-constructor everthing is OK. * has an explicit assignment operator everything is OK. But if it has an explicit default constructor, even one with side-effects as your example shows, then it wrongly lables classes that encapsulate "one" as a POD. It's worse too: has_trivial_constructor has the same problem: classes that clearly do not have trivial constructors get wrongly labled as such (class "two" in your test). Darn, this is a problem, I think we're going to have to disable those two intrinsics for the next release. If we don't and has_trivial_constructor/is_pod are used to optimise-away constructor calls (one of their intended use case), then potentially calls to constructors with side effects will be omitted. Aside: I'm surprised that this matches VC++'s internal notion of POD-ness, doesn't that cause optimiser bugs in cases like this - destructors not being called when they should be? If not what use is this trait to anyone? I'm sure I must be missing something here given that I haven't actually seen VC++ to get this wrong when optimising .... Anyone else any thoughts? Thanks, John. _______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
I am not sure I understand your point about the __has_trivial_constructor intrinsic being broken... it seems to work pretty fine to me ?
Darn, you're right, thanks for the correction.
Boost::is_pod and boost::has_trivial_constructor become broken because the first one use the intrinsic and the second one use the first one...
Yup, that was what I was seeing.
As far as I am concerned, I patched boost/type_traits/intrinsics.hpp by commenting out the __is_pod intrinsic, and now everything seems working fine.
Most of the time, code using is_pod can be refined to be more generic and only use the other intrinsics. I thus managed to remove all is_pod uses from my code and thus still always benefit from compiler information.
Perhaps it would be possible to rebuild a non-broken is_pod using compiler information, based only on the other intrinsics ?
Yep, just done it: change intrinsics.hpp to contain: # define BOOST_IS_POD(T) (__is_pod(T) && __has_trivial_constructor(T)) and your test case passes now. I need to do some more testing, but that does look like a good fix. John.
On 4/6/06, Eric Niebler <eric@boost-consulting.com> wrote:
Please take a moment to have a look at the new docs: http://tinyurl.com/4b9gc. Compare to the style of the 1.33.1 docs here: http://tinyurl.com/rujfh.
Though overall I like the aesthetic improvements, I'll echo Paul's sentiments about the font size. http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/boostbook.cs... seems to specify the default paragraph font to 10 pt, which is much smaller than I like to have it ( I have the default font size in FireFox larger than the default ). If you replace the fixed font sizes with relative ones it'd be great. After forcing the font size up, it looks excellent. ~ SWMc
me22 wrote:
On 4/6/06, Eric Niebler <eric@boost-consulting.com> wrote:
Please take a moment to have a look at the new docs: http://tinyurl.com/4b9gc. Compare to the style of the 1.33.1 docs here: http://tinyurl.com/rujfh.
Though overall I like the aesthetic improvements, I'll echo Paul's sentiments about the font size.
http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/boostbook.cs... seems to specify the default paragraph font to 10 pt, which is much smaller than I like to have it ( I have the default font size in FireFox larger than the default ).
If you replace the fixed font sizes with relative ones it'd be great. After forcing the font size up, it looks excellent.
There's a fair number of people advocating smaller fonts and this lead to the tweaks you are seeing now. That is in fact the consensus if you read the voluminous discussions on the issue from way back. I used to prefer the bigger fonts, but after the tweaks, I do not want to go back anymore. After all, it's just a ctrl+ click away. (BTW, I tried the relative font sizes too, as part of my experiments that lead to the CSS changes we have now. The results weren't good. On some elements it became too small, others too big. Try it out with our benchmark: the QuickBook docs. You can find it at: /tools/quickbook/doc/html. Take note of all the element changes as you go.) Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
It looks nice, but several of the major libraries, including smart pointers, iterators, and tuples, are missing from the main table of contents. Joe Gottman
Joe Gottman wrote:
It looks nice, but several of the major libraries, including smart pointers, iterators, and tuples, are missing from the main table of contents.
These are the Nightly *Generated* Docs, so the only docs that show up here are in BoostBook format and need to be generated. The other libraries you mention have their docs in HTML format and generally use their own stylesheets. I admit it's confusing, though. It seems we don't have a site where the complete set of docs (generated and otherwise) is viewable. And this BoostBook ToC is incomplete and misleading. -- Eric Niebler Boost Consulting www.boost-consulting.com
Here's one man's opinion a) I prefer the larger fonts b) I don't like the detail for each libray. What I would like to see is an expandable index using the control Jonathon Turkanis made so that we would ahve one level visiable: +Any +Array +Date-Time +... c) Boost. before every library is redundant and annoying e) The libraries alphabetically could also have the same +/- expandability. f) It only includes the library generated by ? some procedure which I haven't had the time to figure out yet g)"Documentation for some of the libaries is available in alternative formats..." I thought the whole idea was to be able to make the documents once and have all the other formats generated automatically - So I would expect this sentence to read something like )"Documentation for the above listed libraries is also available in the following alternative formats" h) I never understood why we made a whole new system to do this rather than leveraging on something already developed like LaTex, Troff, or? I'm sure there's a good reason. I would be curious to know what it is Robert Ramey Eric Niebler wrote:
The good folks at boost-docs have been working on improving the look-and-feel of Boost's documentation. This work is based largely on Rene Rivera's website redesign. The change went in to both HEAD and the release branch a few days ago. The biggest change is a smaller font. We've also improved readability by eliminating colored backgrounds, and improved the presentation of many elements of the Doxygen-generated reference sections.
Please take a moment to have a look at the new docs: http://tinyurl.com/4b9gc. Compare to the style of the 1.33.1 docs here: http://tinyurl.com/rujfh.
(I notice that there is some strangeness at the bottom of the libraries.html file the above link takes you to. There should be an alphabetized lists of libraries, and instead there is a fragment of the Boost.Concept_check documentation. That's clearly a bug, but it's not related to the style change.)
Report any problems with the new style to boost-docs@lists.sourceforge.net.
Thanks,
Robert Ramey wrote:
Here's one man's opinion
a) I prefer the larger fonts
Noted.
b) I don't like the detail for each libray. What I would like to see is an expandable index using the control Jonathon Turkanis made so that we would ahve one level visiable: +Any +Array +Date-Time +...
Yep, that'd be nice. Are you volunteering? ;-)
c) Boost. before every library is redundant and annoying
Yep.
e) The libraries alphabetically could also have the same +/- expandability. f) It only includes the library generated by ? some procedure which I haven't had the time to figure out yet
BoostBook.
g)"Documentation for some of the libaries is available in alternative formats..." I thought the whole idea was to be able to make the documents once and have all the other formats generated automatically - So I would expect this sentence to read something like )"Documentation for the above listed libraries is also available in the following alternative formats"
Only BoostBook-based docs are available in other formats.
h) I never understood why we made a whole new system to do this rather than leveraging on something already developed like LaTex, Troff, or? I'm sure there's a good reason. I would be curious to know what it is
We are leveraging something called DocBook. It's an industry standard. BoostBook is a thin layer on top to give people constructs that are useful to people documenting C++ libraries. -- Eric Niebler Boost Consulting www.boost-consulting.com
Eric Niebler wrote:
Robert Ramey wrote:
Here's one man's opinion
a) I prefer the larger fonts
Noted.
It's funny. When we had bigger fonts, people complained and clamored for smaller fonts. Now, when we have smaller fonts, people complain and ask for bigger fonts. It's usual that we always state what we do not like. When we had the bigger fonts, no one expressed liking them. When people complained, no one expressed support for keeping them. This lead to a prior consensus that smaller is better. Now here we go again. There's simply no way to please everyone. And, since this is a matter of preference, I'd like to keep them as they are now. (don't get me wrong, I preferred bigger fonts before). ... Same thing with the shaded boxes ... I think the lesson here is that, by all means, try to express things that you like, as much as those that you don't. This will sort of balance things out since dislikes often sound louder. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
"Joel de Guzman" <joel@boost-consulting.com> wrote
It's funny. When we had bigger fonts, people complained and clamored for smaller fonts. Now, when we have smaller fonts, people complain and ask for bigger fonts. It's usual that we always state what we do not like. When we had the bigger fonts, no one expressed liking them. When people complained, no one expressed support for keeping them. This lead to a prior consensus that smaller is better. Now here we go again. There's simply no way to please everyone. And, since this is a matter of preference, I'd like to keep them as they are now. (don't get me wrong, I preferred bigger fonts before).
... Same thing with the shaded boxes ...
I think the lesson here is that, by all means, try to express things that you like, as much as those that you don't. This will sort of balance things out since dislikes often sound louder.
OK, once again, I LOVE the fact that the text is now left-aligned rather than justified. Please don't ever change that! Regards, Arkadiy
On 2006-04-07, Joel de Guzman <joel@boost-consulting.com> wrote:
Eric Niebler wrote:
Robert Ramey wrote:
Here's one man's opinion a) I prefer the larger fonts Noted. It's funny. When we had bigger fonts, people complained and clamored for smaller fonts. Now, when we have smaller fonts, people complain and ask for bigger fonts.
I have a problem with the small size of the fonts (Firefox, 1600x1200 screen resolution), but it is only a problem for me on code samples; in particular, the doxygen generated "Synopsis" section. I can't work out from the CSS whether the displayed text is 9pt or 90% of 9pt( i.e., 8pt). Whichever it is, it ain't right. (<http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/boost/hash.html> is the page I was looking at.) phil -- change name before "@" to "phil" for email
Phil Richards <news@derived-software.ltd.uk> writes:
I have a problem with the small size of the fonts (Firefox, 1600x1200 screen resolution), but it is only a problem for me on code samples; in particular, the doxygen generated "Synopsis" section. I can't work out from the CSS whether the displayed text is 9pt or 90% of 9pt( i.e., 8pt). Whichever it is, it ain't right. (<http://www.boost.org/regression-logs/cs-win32_metacomm/doc/html/boost/hash.html> is the page I was looking at.)
Looks great in Safari, FWIW. -- Dave Abrahams Boost Consulting www.boost-consulting.com
Vladislav Lazarenko wrote: [picture] Should that really read "An STL compliant hash function object", instead of mentioning the Standard Library and TR1? Regards, m Send instant messages to your online friends http://au.messenger.yahoo.com
Martin Wille <mw8329@yahoo.com.au> writes:
Vladislav Lazarenko wrote:
[picture]
Should that really read "An STL compliant hash function object",
That's what it says when I read it.
instead of mentioning the Standard Library and TR1?
It does neither when I read it. How are you looking at this message? -- Dave Abrahams Boost Consulting www.boost-consulting.com
Martin Wille wrote:
Vladislav Lazarenko wrote:
[picture]
Should that really read "An STL compliant hash function object", instead of mentioning the Standard Library and TR1?
No it shouldn't, I'll change it now. thanks, Daniel
On 4/6/06, Eric Niebler <eric@boost-consulting.com> wrote: > Please take a moment to have a look at the new docs: > http://tinyurl.com/4b9gc. Compare to the style of the 1.33.1 docs here: > http://tinyurl.com/rujfh. 1) I like the new design much better. Great work! 2) The fonts: the greatest improvement - not only smaller fonts improves usability on lower resolution, but also it looks great on relatively large (like mine). Besides - it is now, have much more aesthetic look - the older fonts were way too large... 3) The code snippets - I like the border around it, but I would like too see the background slightly shaded - to separate it apart from the rest of the text. Some times, code snippets are several pages long, and without shading it create come confusion about where code/text starts/ends. -- Best regards, Zigmar
participants (17)
-
Arkadiy Vertleyb -
Daniel James -
David Abrahams -
Eric Niebler -
Jason Shirk -
Jeff Garland -
Joe Gottman -
Joel de Guzman -
John Maddock -
Martin Wille -
me22 -
Paul A Bristow -
Pavel Antokolsky aka Zigmar -
Phil Richards -
Robert Ramey -
Thyfate -
Vladislav Lazarenko