[Poll] New look-n-feel for Boost documentation
Joel de Guzman and I, with the help of many smart folks on the boost-docs list[*], have been working on improving the look-n-feel of Boost's documentation. We're ready to commit the new style, but wanted to check here first. Volodya was good enough to put up a copy of Boost's docs with the new style applied. You can preview them here: http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ Please say whether you like the new style or not. If not, be specific about why. If you are the author of Boost documentation, please have a look at your docs in the new style and see if anything is out of place. [*] Thanks to Doug Gregor, Vladimir Prus, Dave Abrahams, Reece Dunn, Jeff Garland, Rene Rivera and others for their valuable feedback regarding the new style. -- Eric Niebler Boost Consulting www.boost-consulting.com
"Eric Niebler" <eric@boost-consulting.com> wrote in message news:415AD685.8010900@boost-consulting.com...
Joel de Guzman and I, with the help of many smart folks on the boost-docs list[*], have been working on improving the look-n-feel of Boost's documentation. We're ready to commit the new style, but wanted to check here first.
Volodya was good enough to put up a copy of Boost's docs with the new style applied. You can preview them here: http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/
Please say whether you like the new style or not. If not, be specific about why.
Looks quite good to me. I have just two comments: - I think making the headings and hyperlinks blue may eventually cause blue overdose. - The navigation controls, i.e., the arrow and the house icon, should not have bright blue borders. I recommend that the img elements have their border attributes set to 0. In other words, <a accesskey="h" href="index.html"> <img src="images/home.png" alt="Home"> </a> should be <a accesskey="h" href="index.html"> <img border="0" src="images/home.png" alt="Home"> </a> Jonathan
Eric Niebler ha escrito:
Joel de Guzman and I, with the help of many smart folks on the boost-docs list[*], have been working on improving the look-n-feel of Boost's documentation. We're ready to commit the new style, but wanted to check here first.
Volodya was good enough to put up a copy of Boost's docs with the new style applied. You can preview them here: http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/
The bibliography section of Boost.Lambda (http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/lambda.html) has disproportionately large fonts. Joaquín M López Muñoz Telefónica, Investigación y Desarrollo
"Eric Niebler" <eric@boost-consulting.com> writes:
Please say whether you like the new style or not. If not, be specific about why.
As you know, I like it. The left margin should be bigger for code examples than for regular text, though. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
On Wed, Sep 29, 2004 at 08:36:37AM -0700, Eric Niebler wrote:
Joel de Guzman and I, with the help of many smart folks on the boost-docs list[*], have been working on improving the look-n-feel of Boost's documentation. We're ready to commit the new style, but wanted to check here first.
Volodya was good enough to put up a copy of Boost's docs with the new style applied. You can preview them here: http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/
Please say whether you like the new style or not. If not, be specific about why.
I don't want to go into aesthetics, but overall I like it. However, the W3C HTML validator <URL:http://validator.w3.org> does not like the pages... I don't know much about BoostBook and how the HTML pages are generated, but is it possible to add a doctype and fix the remaining errors? IMHO a group like Boost should aim where reasonable for code conforming to the respective standards - be it C++ or HTML. Regards Christoph -- http://www.informatik.tu-darmstadt.de/TI/Mitarbeiter/cludwig.html LiDIA: http://www.informatik.tu-darmstadt.de/TI/LiDIA/Welcome.html
"Eric Niebler" <eric@boost-consulting.com> wrote in message news:415AD685.8010900@boost-consulting.com... | | Joel de Guzman and I, with the help of many smart folks on the | boost-docs list[*], have been working on improving the look-n-feel of | Boost's documentation. We're ready to commit the new style, but wanted | to check here first. | | Volodya was good enough to put up a copy of Boost's docs with the new | style applied. You can preview them here: | http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ | | Please say whether you like the new style or not. If not, be specific | about why. Looks fairly ok, but I like the style Jonathan Turkanis used for his docs better. There is no general color coding scheme AFAICT, this often make code a lot easier to read. It would be cool if the tool could parse all code snippets and add a common color-coding to all examples etc. br Thorsten
"Thorsten Ottosen" <nesotto@cs.auc.dk> wrote in message news:cjesfp$tpm$1@sea.gmane.org... | There is no general color coding scheme AFAICT, this often make code a lot | easier to read. | It would be cool if the tool could parse all code snippets and add a common | color-coding to all examples etc. also, for use with hyper-linked code, it would be nice if I could just write <code-block> template<class T > struct X { template< class U > U <link href="...." >foo<l/ink>() { return U(); } }; <code-block> and that this resulted in a color-coded code with a link. br Thorsten
Eric Niebler wrote:
Joel de Guzman and I, with the help of many smart folks on the boost-docs list[*], have been working on improving the look-n-feel of Boost's documentation. We're ready to commit the new style, but wanted to check here first. [...]
I think it looks great! Good work, guys. I agree with Dave that code should be indented for better readability. I'm ambivalent about colors, but I like blue, so I don't have a problem with the colors chosen. I also like the idea of collecting all the documentation into one large hyperdocument. It makes Boost look more like a serious collection of libraries rather than a hodgepodge thrown together. Making all the docs look consistent goes a long way towards that. I also agree with Thorsten that it would be nice to get an automagic syntax highlighter in the toolchain that preprocessed code blocks to produce some nice color-highlighted html. It would be really nice if it emitted code on a fairly fine-grained scale (lots of syntactic elements) so that there is plenty of flexibility for writing custom css configs for your favorite syntax-highlighting setup (that way, ambitious people could view the code in the docs in the same scheme that, say, their IDE uses). Of course, I have no idea how much work that would be, and I'm not exactly in a position to volunteer the time right now, but it seems to me that Wave must already have some of the capability, given that it knows enough C++ to do preprocessing. The question is, what do library authors have to do to write docs in this new format? Dave
"David B. Held" <dheld@codelogicconsulting.com> writes:
Eric Niebler wrote:
Joel de Guzman and I, with the help of many smart folks on the boost-docs list[*], have been working on improving the look-n-feel of Boost's documentation. We're ready to commit the new style, but wanted to check here first. [...]
I think it looks great! Good work, guys. I agree with Dave that code should be indented for better readability. I'm ambivalent about colors, but I like blue, so I don't have a problem with the colors chosen.
Y'know, I like blue too, but it shouldn't be used for non-links. Section headings should be black, just like the rest of the non-linked text. Black on white reads much more easily (yes, according to research) and that applies to headers as well as body text.
I also like the idea of collecting all the documentation into one large hyperdocument. It makes Boost look more like a serious collection of libraries rather than a hodgepodge thrown together. Making all the docs look consistent goes a long way towards that. I also agree with Thorsten that it would be nice to get an automagic syntax highlighter in the toolchain that preprocessed code blocks to produce some nice color-highlighted html. It would be really nice if it emitted code on a fairly fine-grained scale (lots of syntactic elements) so that there is plenty of flexibility for writing custom css configs for your favorite syntax-highlighting setup (that way, ambitious people could view the code in the docs in the same scheme that, say, their IDE uses). Of course, I have no idea how much work that would be, and I'm not exactly in a position to volunteer the time right now, but it seems to me that Wave must already have some of the capability, given that it knows enough C++ to do preprocessing.
You have to be careful about that. We could easily make things worse for many people by making the wrong color choices. In that case, black would be better. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
David Abrahams wrote:
[...] You have to be careful about that. We could easily make things worse for many people by making the wrong color choices. In that case, black would be better.
Black could be the default. But by marking the code with XML tags, someone who wished to view the docs with a custom stylesheet could see the code in all its syntax-highlighted glory. Isn't that the whole point of customizable stylesheets? Dave
"David B. Held" <dheld@codelogicconsulting.com> writes:
David Abrahams wrote:
[...] You have to be careful about that. We could easily make things worse for many people by making the wrong color choices. In that case, black would be better.
Black could be the default. But by marking the code with XML tags, someone who wished to view the docs with a custom stylesheet could see the code in all its syntax-highlighted glory. Isn't that the whole point of customizable stylesheets?
Users can apply their own stylesheets to a website?? -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
--- David Abrahams <dave@boost-consulting.com> wrote:
Users can apply their own stylesheets to a website??
For Mozilla 1.6 or higher, you can try the steps outlined at <http://www.oreillynet.com/pub/a/network/2000/06/30/magazine/mozilla_stylesheets.html?page=2>. (If the link is too long, just Google the terms "mozilla user style sheet" and you'll eventually get there.) For IE or Opera, try <http://www.squarefree.com/userstyles/user-style-sheets.html>. Cheers, Cromwell Enage _______________________________ Do you Yahoo!? Declare Yourself - Register online to vote today! http://vote.yahoo.com
David Abrahams wrote:
[...] Users can apply their own stylesheets to a website??
Depends on how sophisticated they are. ;) Granted, browsers do not yet support on-the-fly stylesheet selection. However, suppose that the Boost stylesheet is put in a well-known location in the Boost hierarchy (like the root). If all Boost docs use the link format to refer to the stylesheet, all a user has to do is download Boost and replace the stylesheet with her own. That's exactly what I would do if docs had embedded XML tags in code for syntax highlighting purposes. Dave
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of David Abrahams Sent: Wednesday, September 29, 2004 4:59 PM To: boost@lists.boost.org Subject: [boost] Re: [Poll] New look-n-feel for Boost documentation
<snipped> Most of the meat of my comments is at the bottom, not inlined, so please look there before dismissing this as a minor crank post. <g>
Y'know, I like blue too, but it shouldn't be used for non-links. Section headings should be black, just like the rest of the non-linked text. Black on white reads much more easily (yes, according to research) and that applies to headers as well as body text.
Yes, but pure white backgrounds pixellate something fierce; whether it bugs you or not depends on your neurophysical makeup. I can't stand it, personally, and often modify pages I capture to be just a little off in some desaturated direction. Other research shows that the one color both sexes uniformly like is teal, so it's no surprise that my backdrops are very pale, desaturated teal, leaning in the blue direction. For brief periods I can live with white; long reading, though.... How about a background color like RGB: 213, 244, 244? That's barely noticeable to most people, but goes a long way towards reducing pixellation and eye-strain. Doesn't interfere with any of the current color choices for text, either.
I also like the idea of collecting all the documentation into one large hyperdocument. It makes Boost look more like a serious collection of libraries rather than a hodgepodge thrown together. Making all the docs look consistent goes a long way towards that. I also agree with Thorsten that it would be nice to get an automagic syntax highlighter in the toolchain that preprocessed code blocks to produce some nice color-highlighted html. It would be really nice if it emitted code on a fairly fine-grained scale (lots of syntactic elements) so that there is plenty of flexibility for writing custom css configs for your favorite syntax-highlighting setup (that way, ambitious people could view the code in the docs in the same scheme that, say, their IDE uses). Of course, I have no idea how much work that would be, and I'm not exactly in a position to volunteer the time right now, but it seems to me that Wave must already have some of the capability, given that it knows enough C++ to do preprocessing.
You have to be careful about that. We could easily make things worse for many people by making the wrong color choices. In that case, black would be better.
I agree with most of the comments here, and would also prefer black text, no matter what the background. On the HTML pages, I'd personally prefer font choices that are just a bit thicker-looking, maybe one font size larger (it's hell going from 20/10 vision to what I have now), but I realize that that's a personal preference, and wouldn't do more than note that some of the text is particularly small and hard-to-see at even 1280x1024 resolution. The issue I would raise, though, is accessibility. I'm not personally affected by this, but my wife's position forces her to deal with it at all times, so I'm always aware of such issues. In particular, the use of frames in the sample links could be a problem, and I suspect that no one's given accessibility much thought. Certainly it makes web sites much harder to maintain, and leads to web code that's anything but elegant. Still, I'll toss out the following links, and apologies to anyone (possibly *everyone*) here who's already thoroughly familiar with it. First, there's the W3C/WAI, http://www.w3.org/TR/WCAG10/#gl-own-interface Note specifically Para. 2.2. Then there are the Federal standards: Section 508 Standard §1194.21 http://www.section508.gov/index.cfm?FuseAction=Content&ID=12 The problem with frames specifically, nice though they can be, is that they prevent a number of operations necessary for software for the disabled to function. As just one example, they prevent bookmarking. They also can interfere with a number of other mandated items, but the list would be too long to bother with here. If this is regarded as an issue, I'd merely suggest reading through the appropriate documents. Boost may not be under the restrictions imposed on government sites (yet), but it seems to me that if the goal is to get as much Boost code into the next official spec as possible, it could become an issue, as the governing bodies (I know, preaching to the Chorister and Organist, let alone the choir <g>) definitely have government relationships. Incidentally, the laws in the UK are completely different, and more restrictive than those here. I don't have a link at hand for UK requirements, but the most simple web search will turn up hits by the score.
David Abrahams wrote:
"David B. Held" <dheld@codelogicconsulting.com> writes:
Eric Niebler wrote:
Joel de Guzman and I, with the help of many smart folks on the boost-docs list[*], have been working on improving the look-n-feel of Boost's documentation. We're ready to commit the new style, but wanted to check here first. [...]
I think it looks great! Good work, guys. I agree with Dave that code should be indented for better readability. I'm ambivalent about colors, but I like blue, so I don't have a problem with the colors chosen.
Y'know, I like blue too, but it shouldn't be used for non-links. Section headings should be black, just like the rest of the non-linked text. Black on white reads much more easily (yes, according to research) and that applies to headers as well as body text.
I do not know what the study is but I find black very boring. I find the blue headings actualy more pleasurable to read. I'd wish for the blue if you don't have a strong opinion. I really like the W3C style blue headings. I agreed on the grey tables with hesitation. Now everything is turning back to monochommatic grey again. Gimme back my blues... I love the blues.... Cheers, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
Joel wrote:
Y'know, I like blue too, but it shouldn't be used for non-links. Section headings should be black, just like the rest of the non-linked text. Black on white reads much more easily (yes, according to research) and that applies to headers as well as body text.
I do not know what the study is but I find black very boring. I find the blue headings actualy more pleasurable to read. I'd wish for the blue if you don't have a strong opinion. I really like the W3C style blue headings. I agreed on the grey tables with hesitation. Now everything is turning back to monochommatic grey again. Gimme back my blues... I love the blues....
I second that. Sure, for main text black-on-white is the only choice. But blue headers make the look less visually boring. - Volodya
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Vladimir Prus Sent: Thursday, September 30, 2004 12:15 AM To: boost@lists.boost.org Subject: [boost] Re: Re: [Poll] New look-n-feel for Boost documentation
Joel wrote:
Y'know, I like blue too, but it shouldn't be used for non-links. Section headings should be black, just like the rest of the non-linked text. Black on white reads much more easily (yes, according to research) and that applies to headers as well as body text.
I do not know what the study is but I find black very boring. I find the blue headings actualy more pleasurable to read. I'd wish for the blue if you don't have a strong opinion. I really like the W3C style blue headings. I agreed on the grey tables with hesitation. Now everything is turning back to monochommatic grey again. Gimme back my blues... I love the blues....
I second that. Sure, for main text black-on-white is the only choice. But blue headers make the look less visually boring.
I tend to agree, although I'd go for a more contrasty blue. I'd like to toss out a book title here (with no intent of offending either artists or programmers present, but face it, most of us fall in the latter category): "Pantone Guide to Communicating with Color" by Leatrice Eiseman, ISBN 0-9666383-2-8. Usually goes for around $40 US, and is a pretty good intro to color psychology, with lots of visual schemes presented. Maybe a scheme like this (only major colors here; I'm not trying to design the entire doc style <g>): Major headings: 0x006699 (dark blue-teal) Backdrop: 0xEDFFFF (very pale blue-teal) Box 1: 0xC1EAFC (desaturated light blue) Box 2: 0xD5EEF4 (very desaturated light blue) Contrast Color: 0xFF7856 (hot orange) Body Text: 0x000000 (black) I think most people will find this a very pleasing combination that's not wildly different from the existing one. Just a bit perkier and easier on the eyes. I've got a sample page done in PhotoShop kicked up in front of me right now, and frankly, after coming up with it, I believe I'll work a more involved version of it into the product I support, as I find that I'm rather pleased with it myself. Other colors that could have worked as secondaries, as for the table boxes, would have been shades of green. The real trick in keeping the kind of look the BoostBook already has is simply to keep colors middlin' desaturated, while maintaining sufficient contrast between foreground and background elements to make them stand out, without causing eye flicker at the boundaries. This scheme does that nicely. You wouldn't use the "contrast color" much; just when you really wanted to emphasize something, because it really leaps out. You likely wouldn't use it for a backdrop, even desaturated, unless you didn't mind a block of heavy color, and you'd have to provide a very contrasty color for text within it, probably white. The problem with many colors is that when you lighten and desaturate them heavily, they start to look very pastel and dreamy. It's actually fairly difficult to come up with a scheme that doesn't; blues do it better, which is likely one of the reasons a lot of people seem to be gravitating to blue-ish schemes here. Desaturated purple goes all to easily to colors like chartreuse and lavender, and bright orange to something like a washed-out pumpkin; with colors like that, it's better to keep them fairly saturated and contrast the text in the opposite direction. I tried, while picking the colors above, to stick to the web-safe colors, but you really can't come up with a very satisfactory scheme, as they're so limited, particularly in the teal end of the spectrum. In particular, there's nothing in the blue or teal range that's really light enough to use as a backdrop (well, I use heavier ones on my own machines, but I suspect a number of people would find them too colorful, and they do drop contrast if you're using any colored text (and here I speak from a fair bit of experience designing color schemes for things like syntax highlighters and ad copy). If there are any real artists reading this, feel free to correct me on anything I was wrong or misleading about; I'm always willing to learn new tricks myself. And as a Parthian shot, I note over my mount's hindquarters that this is all just a suggestion, and not a criticism. Reid
Reid Sweatman wrote:
Maybe a scheme like this (only major colors here; I'm not trying to design the entire doc style <g>):
Major headings: 0x006699 (dark blue-teal) Backdrop: 0xEDFFFF (very pale blue-teal) Box 1: 0xC1EAFC (desaturated light blue) Box 2: 0xD5EEF4 (very desaturated light blue) Contrast Color: 0xFF7856 (hot orange) Body Text: 0x000000 (black)
I think most people will find this a very pleasing combination that's not wildly different from the existing one. Just a bit perkier and easier on the eyes. I've got a sample page done in PhotoShop kicked up in front of me right now, and frankly, after coming up with it, I believe I'll work a more involved version of it into the product I support, as I find that I'm rather pleased with it myself.
Can we take a peek at the sample page? Cheers, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Joel Sent: Friday, October 01, 2004 4:22 AM To: boost@lists.boost.org Subject: Re: [boost] Re: Re: [Poll] New look-n-feel for Boost documentation
Reid Sweatman wrote:
Maybe a scheme like this (only major colors here; I'm not trying to design the entire doc style <g>):
Major headings: 0x006699 (dark blue-teal) Backdrop: 0xEDFFFF (very pale blue-teal) Box 1: 0xC1EAFC (desaturated light blue) Box 2: 0xD5EEF4 (very desaturated light blue) Contrast Color: 0xFF7856 (hot orange) Body Text: 0x000000 (black)
I think most people will find this a very pleasing combination that's not wildly different from the existing one. Just a bit perkier and easier on the eyes. I've got a sample page done in PhotoShop kicked up in front of me right now, and frankly, after coming up with it, I believe I'll work a more involved version of it into the product I support, as I find that I'm rather pleased with it myself.
Can we take a peek at the sample page?
Sure. Where should I post it? It's a really, really simple page, just a quick graphic, not HTML or PHP. Perhaps the term "page" might have been misleading. It's just a background, a smattering of text, and two colored boxes. Reid
Joel <joel@boost-consulting.com> writes:
David Abrahams wrote:
"David B. Held" <dheld@codelogicconsulting.com> writes:
Eric Niebler wrote:
Joel de Guzman and I, with the help of many smart folks on the boost-docs list[*], have been working on improving the look-n-feel of Boost's documentation. We're ready to commit the new style, but wanted to check here first. [...]
I think it looks great! Good work, guys. I agree with Dave that code should be indented for better readability. I'm ambivalent about colors, but I like blue, so I don't have a problem with the colors chosen. Y'know, I like blue too, but it shouldn't be used for non-links. Section headings should be black, just like the rest of the non-linked text. Black on white reads much more easily (yes, according to research) and that applies to headers as well as body text.
I do not know what the study is but I find black very boring.
Red or orange would *really* be exciting. In this case, boring is good. Black on white has the highest contrast and thus is most legible.
I find the blue headings actualy more pleasurable to read. I'd wish for the blue if you don't have a strong opinion. I really like the W3C style blue headings. I agreed on the grey tables with hesitation. Now everything is turning back to monochommatic grey again. Gimme back my blues... I love the blues....
Me too, in music. The blue text isn't horrible, but cold colors tend to recede into the background. I think that's the opposite of what you want from a section header. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
David Abrahams wrote:
Joel <joel@boost-consulting.com> writes:
David Abrahams wrote:
I think it looks great! Good work, guys. I agree with Dave that code should be indented for better readability. I'm ambivalent about colors, but I like blue, so I don't have a problem with the colors chosen.
Y'know, I like blue too, but it shouldn't be used for non-links. Section headings should be black, just like the rest of the non-linked text. Black on white reads much more easily (yes, according to research) and that applies to headers as well as body text.
I do not know what the study is but I find black very boring.
Red or orange would *really* be exciting. In this case, boring is good. Black on white has the highest contrast and thus is most legible.
Indeed they would. However, we do not want to elicit excitement. We only want to draw out mild pleasure which black does not give. Colors have a psychological effect and we do not want the effects of red or orange in this case, but they *DO* stand out above dull black. IMO, blue is a good balance. "Blue relaxes our nervous system. It has a sobering effect on the mind and can cause people to be more contemplative, which is the opposite reaction as red." "Blue surroundings, if not too dark, increase productivity. Studies show that students score higher, weightlifters lift heavier weights in blue rooms. People retain more when reading information written in blue text." (reference: http://tinyurl.com/4zscu) Now, that last point is contrary to the study you mentioned, and I agree with it.
I find the blue headings actualy more pleasurable to read. I'd wish for the blue if you don't have a strong opinion. I really like the W3C style blue headings. I agreed on the grey tables with hesitation. Now everything is turning back to monochommatic grey again. Gimme back my blues... I love the blues....
Me too, in music.
The blue text isn't horrible, but cold colors tend to recede into the background. I think that's the opposite of what you want from a section header.
Not for me, and I am sure for many others. The text is already in black and a different color for the headings make them stand out pretty well, but not too much, as in the case where you have it in red or orange. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
Joel <joel@boost-consulting.com> writes:
"Blue relaxes our nervous system. It has a sobering effect on the mind and can cause people to be more contemplative, which is the opposite reaction as red."
"Blue surroundings, if not too dark, increase productivity. Studies show that students score higher, weightlifters lift heavier weights in blue rooms. People retain more when reading information written in blue text."
(reference: http://tinyurl.com/4zscu)
Now, that last point is contrary to the study you mentioned, and I agree with it.
I don't see any contradiction there. Blue can have all those effects and still be harder to read. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
David Abrahams wrote:
Joel <joel@boost-consulting.com> writes:
"Blue relaxes our nervous system. It has a sobering effect on the mind and can cause people to be more contemplative, which is the opposite reaction as red."
"Blue surroundings, if not too dark, increase productivity. Studies show that students score higher, weightlifters lift heavier weights in blue rooms. People retain more when reading information written in blue text."
(reference: http://tinyurl.com/4zscu)
Now, that last point is contrary to the study you mentioned, and I agree with it.
I don't see any contradiction there. Blue can have all those effects and still be harder to read.
Really? When people retain more information from reading text, I would surmise that that's because the stress and tension is lessened, as in the case when our nervous system is relaxed. How can it be the opposite? Cheers, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
Joel <joel@boost-consulting.com> writes:
David Abrahams wrote:
Joel <joel@boost-consulting.com> writes:
"Blue relaxes our nervous system. It has a sobering effect on the mind and can cause people to be more contemplative, which is the opposite reaction as red."
"Blue surroundings, if not too dark, increase productivity. Studies show that students score higher, weightlifters lift heavier weights in blue rooms. People retain more when reading information written in blue text."
(reference: http://tinyurl.com/4zscu)
Now, that last point is contrary to the study you mentioned, and I agree with it. I don't see any contradiction there. Blue can have all those effects and still be harder to read.
Really? When people retain more information from reading text, I would surmise that that's because the stress and tension is lessened, as in the case when our nervous system is relaxed. How can it be the opposite?
People pay more attention to hard things than easy ones? -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
David Abrahams wrote:
Joel <joel@boost-consulting.com> writes: [...]
Really? When people retain more information from reading text, I would surmise that that's because the stress and tension is lessened, as in the case when our nervous system is relaxed. How can it be the opposite?
People pay more attention to hard things than easy ones?
Then we should ask whether it's better to make the docs easy to read or easy to remember. ;) Dave
David B. Held wrote:
I think it looks great! Good work, guys.
Thanks!
I agree with Dave that code should be indented for better readability.
OK. I'll work on that, and I'll fix the other problems people here have noticed, too. I also agree with
Thorsten that it would be nice to get an automagic syntax highlighter in the toolchain that preprocessed code blocks to produce some nice color-highlighted html.
A clarification: all we're talking about at this point is changing the style-sheet (boostbook.css) that the HTML documentation uses. We're not changing any existing HTML to mark up code blocks with syntax-highlighting. But keep reading ...
The question is, what do library authors have to do to write docs in this new format?
Nothing, since this is not a new format. It's just a new style-sheet applied to the existing HTML. Once we check the new CSS in, the docs will automatically pick up this new style. Aside: You and Thorsten will be interested in a tool that Joel and I have been working on. It's a authoring tool for BoostBook, and it will automatically syntax-highlight code sections. Look for an announcement here in the next few days. Note: the tool does *not* mark up existing HTML/XML, but it probably wouldn't be too hard to split that part out into its own tool. -- Eric Niebler Boost Consulting www.boost-consulting.com
Eric Niebler wrote:
Joel de Guzman and I, with the help of many smart folks on the boost-docs list[*], have been working on improving the look-n-feel of Boost's documentation. We're ready to commit the new style, but wanted to check here first.
Volodya was good enough to put up a copy of Boost's docs with the new style applied. You can preview them here: http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/
Please say whether you like the new style or not. If not, be specific about why.
Speaking strictly as a user of these pages, I think it's definitely an improvement, much cleaner, and better from where we were. I would however suggest that an option (and only as an option) be provided to view a chapter in one page rather than having to navigate back and forth (with <- , -> at the bottom of the pages). Even better still, the "Table of Contents" for each chapter, if it were to appear on each page of the chapter would be very desirable, most useful and convenient. On the whole, an excellent job to date, and I definitely appreciate the effort, as would others I undoubtedly presume.
If you are the author of Boost documentation, please have a look at your docs in the new style and see if anything is out of place.
[*] Thanks to Doug Gregor, Vladimir Prus, Dave Abrahams, Reece Dunn, Jeff Garland, Rene Rivera and others for their valuable feedback regarding the new style.
-- Manfred Doudar MetOcean Engineers
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Manfred Doudar Sent: Wednesday, September 29, 2004 7:12 PM To: boost@lists.boost.org Subject: Re: [boost] [Poll] New look-n-feel for Boost documentation
Eric Niebler wrote:
Joel de Guzman and I, with the help of many smart folks on the boost-docs list[*], have been working on improving the
look-n-feel of
Boost's documentation. We're ready to commit the new style, but wanted to check here first.
Volodya was good enough to put up a copy of Boost's docs with the new style applied. You can preview them here: http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/
Please say whether you like the new style or not. If not, be specific about why.
Speaking strictly as a user of these pages, I think it's definitely an improvement, much cleaner, and better from where we were.
I would however suggest that an option (and only as an option) be provided to view a chapter in one page rather than having to navigate back and forth (with <- , -> at the bottom of the pages). Even better still, the "Table of Contents" for each chapter, if it were to appear on each page of the chapter would be very desirable, most useful and convenient.
<snipped> I agree, especially with the remark concerning a single-page option; why not turn that into a "print version" if possible? The two things I note are that the numbering is left-justified, which isn't the norm for a TOC, and that the items B, C, and D at the bottom of the first page don't correlate syntactically with anything else on the page in an obvious manner, and beg the obvious question concerning A. Reid
Reid Sweatman wrote:
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Manfred Doudar Sent: Wednesday, September 29, 2004 7:12 PM To: boost@lists.boost.org Subject: Re: [boost] [Poll] New look-n-feel for Boost documentation
Eric Niebler wrote:
Joel de Guzman and I, with the help of many smart folks on the boost-docs list[*], have been working on improving the
look-n-feel of
Boost's documentation. We're ready to commit the new style, but wanted to check here first.
Volodya was good enough to put up a copy of Boost's docs with the new style applied. You can preview them here: http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/
Please say whether you like the new style or not. If not, be specific about why.
Speaking strictly as a user of these pages, I think it's definitely an improvement, much cleaner, and better from where we were.
I would however suggest that an option (and only as an option) be provided to view a chapter in one page rather than having to navigate back and forth (with <- , -> at the bottom of the pages). Even better still, the "Table of Contents" for each chapter, if it were to appear on each page of the chapter would be very desirable, most useful and convenient.
<snipped>
I agree, especially with the remark concerning a single-page option; why not turn that into a "print version" if possible?
Does ability to generate PDF output amounts to "print version"? Personally, I find PDF output which can be printed with one click one of the killer features of BoostBook. - Volodya
Vladimir Prus wrote:
Reid Sweatman wrote:
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Manfred Doudar Sent: Wednesday, September 29, 2004 7:12 PM To: boost@lists.boost.org Subject: Re: [boost] [Poll] New look-n-feel for Boost documentation
Eric Niebler wrote:
Joel de Guzman and I, with the help of many smart folks on the boost-docs list[*], have been working on improving the
look-n-feel of
Boost's documentation. We're ready to commit the new style,
but wanted
to check here first.
Volodya was good enough to put up a copy of Boost's docs
with the new
style applied. You can preview them here: http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/
Please say whether you like the new style or not. If not,
be specific
about why.
Speaking strictly as a user of these pages, I think it's definitely an improvement, much cleaner, and better from where we were.
I would however suggest that an option (and only as an option) be provided to view a chapter in one page rather than having to navigate back and forth (with <- , -> at the bottom of the pages). Even better still, the "Table of Contents" for each chapter, if it were to appear on each page of the chapter would be very desirable, most useful and convenient.
<snipped>
I agree, especially with the remark concerning a single-page option; why not turn that into a "print version" if possible?
Does ability to generate PDF output amounts to "print version"? Personally, I find PDF output which can be printed with one click one of the killer features of BoostBook.
As long as we can print that's ok by me, but on the otherhand, it's always a convenience to be printer-friendly with HTML -- Manfred Doudar MetOcean Engineers
Manfred Doudar wrote:
Vladimir Prus wrote:
Reid Sweatman wrote:
Eric Niebler wrote:
Joel de Guzman and I, with the help of many smart folks on the boost-docs list[*], have been working on improving the look-n-feel of Boost's documentation. We're ready to commit the new style, but wanted to check here first.
Volodya was good enough to put up a copy of Boost's docs with the new style applied. You can preview them here: http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/
Please say whether you like the new style or not. If not, be specific about why.
Speaking strictly as a user of these pages, I think it's definitely an improvement, much cleaner, and better from where we were.
I would however suggest that an option (and only as an option) be provided to view a chapter in one page rather than having to navigate back and forth (with <- , -> at the bottom of the pages). Even better still, the "Table of Contents" for each chapter, if it were to appear on each page of the chapter would be very desirable, most useful and convenient.
<snipped>
I agree, especially with the remark concerning a single-page option; why not turn that into a "print version" if possible?
Does ability to generate PDF output amounts to "print version"? Personally, I find PDF output which can be printed with one click one of the killer features of BoostBook.
As long as we can print that's ok by me, but on the otherhand, it's always a convenience to be printer-friendly with HTML
Indeed. And this is very easy to do: place all the colouring/"screen"-specific styles inside a @media screen{ ... } block in the CSS code and the printer stuff in @media print{ ... } Therefore, placing the link colours in screen will ensure they do not appear blue or whatever in the printed versions. Regards, Reece
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Vladimir Prus Sent: Thursday, September 30, 2004 12:17 AM To: boost@lists.boost.org Subject: [boost] RE: [Poll] New look-n-feel for Boost documentation
<snipped>
I agree, especially with the remark concerning a single-page option; why not turn that into a "print version" if possible?
Does ability to generate PDF output amounts to "print version"? Personally, I find PDF output which can be printed with one click one of the killer features of BoostBook.
Yeah, it certainly does, and I didn't mean to knock that feature. I just figured that if you're going to the trouble of creating a single-page version, you're effectively doing most of the things necessary (not all, certainly, but most) for a "print" version of the more conventional variety, so why not leverage it for the benefit of anyone who doesn't want PDF? I only made the suggestion because it's the sort of thing that, if implemented early on, is very little extra work. Reid
Manfred Doudar <manfred.doudar@metoceanengineers.com> writes:
Even better still, the "Table of Contents" for each chapter, if it were to appear on each page of the chapter would be very desirable, most useful and convenient.
Wouldn't the JavaScript tree control solve that problem? -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
David Abrahams wrote:
Manfred Doudar <manfred.doudar@metoceanengineers.com> writes:
Even better still, the "Table of Contents" for each chapter, if it were to appear on each page of the chapter would be very desirable, most useful and convenient.
Wouldn't the JavaScript tree control solve that problem?
That would be better; though design within the context of a frames/ no-frames option should then be considered, and the implications that has for printing from HTML (say: forcing the tree to be non-printable if using frames? - just a thought). -- Manfred Doudar MetOcean Engineers
Please say whether you like the new style or not. If not, be specific about why.
I like the overall look, but for longer stretches of text a serif typeface would be easier on the eyes. I'd suggest either not overriding the browser's font settings for paragraph text, or using a serif font. Regards, Rogier
Eric Niebler wrote:
Joel de Guzman and I, with the help of many smart folks on the boost-docs list[*], have been working on improving the look-n-feel of Boost's documentation. We're ready to commit the new style, but wanted to check here first.
Volodya was good enough to put up a copy of Boost's docs with the new style applied. You can preview them here: http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/
Please say whether you like the new style or not. If not, be specific about why.
I don't like the use of sans-serif fonts, I find it difficult to read. -- Daniel Wallin
"Eric Niebler" <eric@boost-consulting.com> wrote:
Joel de Guzman and I, with the help of many smart folks on the boost-docs list[*], have been working on improving the look-n-feel of Boost's documentation. We're ready to commit the new style, but wanted to check here first.
Volodya was good enough to put up a copy of Boost's docs with the new style applied. You can preview them here: http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/
Please say whether you like the new style or not. If not, be specific about why.
Everything is indented, as if I am looking at a piece of paper. Indenting some things (like code examples) to make them stand out is ok, but don't indent everything. The web is not paper. Indenting wastes screen real estate. It looks fine in lynx, which usually covers most accessibility concerns. Cheers, Walter Landry wlandry@ucsd.edu
Walter Landry wrote:
"Eric Niebler" <eric@boost-consulting.com> wrote:
Joel de Guzman and I, with the help of many smart folks on the boost-docs list[*], have been working on improving the look-n-feel of Boost's documentation. We're ready to commit the new style, but wanted to check here first.
Volodya was good enough to put up a copy of Boost's docs with the new style applied. You can preview them here: http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/
Please say whether you like the new style or not. If not, be specific about why.
Everything is indented, as if I am looking at a piece of paper. Indenting some things (like code examples) to make them stand out is ok, but don't indent everything. The web is not paper. Indenting wastes screen real estate.
That's not indenting. That's a margin. White space is good. Screen real estate is cheap in this day and age of large color monitors. A good monitor is just about the same price as a good desk (or lower). Yet, you don't fill your desk with stuff to the edges just to save desk "real estate". I think that's called "tidiness". That said, I think a bit narrower margin is ok. Definitely not the inch or so margin we typically have on printed paper, yet, IMO, space on paper should be considered a more precious "real estate". Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
Eric Niebler wrote:
Joel de Guzman and I, with the help of many smart folks on the boost-docs list[*], have been working on improving the look-n-feel of Boost's documentation. We're ready to commit the new style, but wanted to check here first.
Volodya was good enough to put up a copy of Boost's docs with the new style applied. You can preview them here: http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/
Please say whether you like the new style or not. If not, be specific about why.
I tried it with the text-only browser lynx. In general all looks perfectly readable, but I do notice one strangeness: snippets of code which should have a larger left margin than the text actually have no left margin at all. Eg: $ lynx http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/program_options.tutorial.html#... Cut and paste from that page gives a fair view of how it is rendered by lynx: Getting Started The first example is the simplest possible: it only handles two options. Here's the source code (the full program is in "example/first.cpp"): // Declare the supported options. po::options_description desc("Allowed options"); desc.add_options() ("help", "produce help message") ("compression", po::value<int>(), "set compression level") ; This isn't a problem of your new stylesheet in particular. The same behaviour is found when using the .css file in boost cvs. However, it would be nice if this could be improved. Regards, Angus
Angus Leeming wrote:
Eric Niebler wrote: [...]
Please say whether you like the new style or not. If not, be specific about why.
I tried it with the text-only browser lynx. In general all looks perfectly readable, but I do notice one strangeness: snippets of code which should have a larger left margin than the text actually have no left margin at all.
I confirm that for lynx and for links2 (in text mode and in graphical mode). elinks displays normal text and code in an unreadable color this could be a problem with the settings here, though); I think the indentation is similar to lynx and links2 (really hard to tell). w3m left aligns text and code. The documentation looks very nice in Mozilla with my usual feature deprived settings (no colours, no pictures, no JavaScript). Regards, m
From: "Eric Niebler" <eric@boost-consulting.com>
Joel de Guzman and I, with the help of many smart folks on the boost-docs list[*], have been working on improving the look-n-feel of Boost's documentation. We're ready to commit the new style, but wanted to check here first.
Thanks to all those involved. Generally, the new style is clean, professional, and attractive. I do have a few complaints, however. 1. My browser's "always underline links" setting is not being respected. I prefer links to be underlined so they are more visible. Color alone is not an indication. In case it matters, by user agent string is: Mozilla/5.0 (X11; U; SunOS sun4u; en-US; rv:1.0.1) Gecko/20020920 Netscape/7.0 2. My browser's link colors are not being honored. Thus, the link color isn't my normal link color and they don't change to indicate when I've visited them. 3. Sans serif text is harder to read. You should use a font with serifs for the body text and sans serif fonts for headings. 4. Some things don't adapt well to differing resolutions and font sizes. Consider the preferred/portable syntax table at http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/function.tutorial.html#id47806.... At my default settings, I see half of the second column. Were the table not offset so far, I'd see the whole thing. However, it is clear that things are set to not wrap (non-breaking spaces, perhaps?), so the side-by-side presentation means the table is likely to be wide and trigger scrolling. The second preferred/portable syntax entry in that section recognizes the problem and uses two tables, one above the other. Were it not for the extra large offset, the "Preferred syntax" table would fit at my default settings. The point is that while you cannot control a reader's resolution or font choices, and scrolling is inevitable, reducing the offset and avoiding wide, non-wrapping layouts is superior. 5. In http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/function.tutorial.html#id47841..., a list is introduced with, "Three such libraries are summarized below:," but there are no bullets setting off the three paragraphs. Is this a Boost.Function documentation issue or is this a consequence of the new style? If the latter, there should be bullets to clearly delineate each item. 6. At the bottom of that same page, links to boost::ref refer to here: http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/reference_wrapper.html#id44466..., which says nothing about "boost::ref." References to that name appear earlier in the linked document. Again, I don't know whether this is an issue with the Boost.Function documentation or the new style, but it will be a source of confusion. 7. The links to the documentation should probably be encoded by the author similarly to those in the C++ Standard. That is, instead of id444666, the link name could be "ref.desc.ctor" or something. 8. When looking at http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ref.reference.html#header.boos..., there's no indication that there is documentation on boost::reference_wrapper. The link mentioned in 6 got me to the documentation page, but when I went up to http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ref..html, and then to http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ref.reference.html, I was unsure how to get back to http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ref.reference.html#header.boos..., since the link was in the "Header" section. Is this a consequence of the documentation or the new style? I'd prefer to see something like this in the "Reference" section or a "Description" section: reference_wrapper - <brief> ref - <brief> cref - <brief> is_reference_wrapper - <brief> unwrap_reference - <brief> where the names are the same links as in the Header section. 9. Headings and links should not share the same color, whatever choice you make for them. Blue is the traditional link color, but, as I said above, I don't like my colors being overridden. 10. I don't like "pure" white backgrounds. The teal suggestion made earlier would be good. An off-white would be fine, too. -- Rob Stewart stewart@sig.com Software Engineer http://www.sig.com Susquehanna International Group, LLP using std::disclaimer;
On Sep 30, 2004, at 8:51 AM, Rob Stewart wrote:
4. Some things don't adapt well to differing resolutions and font sizes. Consider the preferred/portable syntax table at
http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ function.tutorial.html#id478061. At my default settings, I see half of the second column. Were the table not offset so far, I'd see the whole thing. However, it is clear that things are set to not wrap (non-breaking spaces, perhaps?), so the side-by-side presentation means the table is likely to be wide and trigger scrolling. The second preferred/portable syntax entry in that section recognizes the problem and uses two tables, one above the other. Were it not for the extra large offset, the "Preferred syntax" table would fit at my default settings. The point is that while you cannot control a reader's resolution or font choices, and scrolling is inevitable, reducing the offset and avoiding wide, non-wrapping layouts is superior.
Those tables themselves are absolutely horrible, and should be replaced with something less restrictive. Unfortunately, I don't have a better way to present equivalent alternative code snippets.
5. In
http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ function.tutorial.html#id478410, a list is introduced with, "Three such libraries are summarized below:," but there are no bullets setting off the three paragraphs. Is this a Boost.Function documentation issue or is this a consequence of the new style? If the latter, there should be bullets to clearly delineate each item.
I see bullets in Safari (?)
6. At the bottom of that same page, links to boost::ref refer to here:
http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ reference_wrapper.html#id444666, which says nothing about "boost::ref." References to that name appear earlier in the linked document. Again, I don't know whether this is an issue with the Boost.Function documentation or the new style, but it will be a source of confusion.
It's the documentation for "ref", which is grouped with reference_wrapper. If there is a problem here, it's not with the stylesheet.
7. The links to the documentation should probably be encoded by the author similarly to those in the C++ Standard. That is, instead of id444666, the link name could be "ref.desc.ctor" or something.
We're working on that.
8. When looking at
http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ ref.reference.html#header.boost.ref.hpp, there's no indication that there is documentation on boost::reference_wrapper. The link mentioned in 6 got me to the documentation page, but when I went up to http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ref..html, and then to http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ref.reference.html, I was unsure how to get back to
http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ ref.reference.html#header.boost.ref.hpp, since the link was in the "Header" section. Is this a consequence of the documentation or the new style? I'd prefer to see something like this in the "Reference" section or a "Description" section:
reference_wrapper - <brief> ref - <brief> cref - <brief> is_reference_wrapper - <brief> unwrap_reference - <brief>
where the names are the same links as in the Header section.
BoostBook has always been this way; the new look-n-feel does not change that. Would these links be in addition to the prototypes already provided? Doug
From: Doug Gregor <dgregor@cs.indiana.edu>
On Sep 30, 2004, at 8:51 AM, Rob Stewart wrote:
4. Some things don't adapt well to differing resolutions and font sizes. Consider the preferred/portable syntax table at
http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ function.tutorial.html#id478061. At my default settings, I see half of the second column. Were the table not offset so far, I'd see the whole thing. However, it is clear that things are set to not wrap (non-breaking spaces, perhaps?), so the side-by-side presentation means the table is likely to be wide and trigger scrolling. The second preferred/portable syntax entry in that section recognizes the problem and uses two tables, one above the other. Were it not for the extra large offset, the "Preferred syntax" table would fit at my default settings. The point is that while you cannot control a reader's resolution or font choices, and scrolling is inevitable, reducing the offset and avoiding wide, non-wrapping layouts is superior.
Those tables themselves are absolutely horrible, and should be replaced with something less restrictive. Unfortunately, I don't have a better way to present equivalent alternative code snippets.
Wouldn't this be just as useful? <H3>Preferred Syntax</H3> <code>boost::function<float (int x, int y)> f;</code> <H3>Portable Syntax</H3> <code>boost::function2<float, int, int> f;</code>
5. In
http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ function.tutorial.html#id478410, a list is introduced with, "Three such libraries are summarized below:," but there are no bullets setting off the three paragraphs. Is this a Boost.Function documentation issue or is this a consequence of the new style? If the latter, there should be bullets to clearly delineate each item.
I see bullets in Safari (?)
I couldn't reproduce it using just the HTML that appears there. That led me to the CSS. There I found: ul { list-style-image: url(images/bullet.gif); text-align: justify; } I then tried looking at http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/images/bullet.gif and got a 404.
8. When looking at
http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ ref.reference.html#header.boost.ref.hpp, there's no indication that there is documentation on boost::reference_wrapper. The link mentioned in 6 got me to the documentation page, but when I went up to http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ref..html, and then to http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ref.reference.html, I was unsure how to get back to
http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/ ref.reference.html#header.boost.ref.hpp, since the link was in the "Header" section. Is this a consequence of the documentation or the new style? I'd prefer to see something like this in the "Reference" section or a "Description" section:
reference_wrapper - <brief> ref - <brief> cref - <brief> is_reference_wrapper - <brief> unwrap_reference - <brief>
where the names are the same links as in the Header section.
BoostBook has always been this way; the new look-n-feel does not change that. Would these links be in addition to the prototypes already provided?
Yes. As shown above, they are presented as documentation links. As currently presented by BoostBook, I'd expect the links to take me to code. They are, after all, in the "Header" section. -- Rob Stewart stewart@sig.com Software Engineer http://www.sig.com Susquehanna International Group, LLP using std::disclaimer;
Thanks for the detailed reply. Comments inline... Rob Stewart wrote:
1. My browser's "always underline links" setting is not being respected. <snip>
2. My browser's link colors are not being honored. <snip>
These specific design issues can be revisited, but the larger question is of a style-sheet overriding browser defaults. Are you against any website creating a distinct look-n-feel by customizing settings such as these?
3. Sans serif text is harder to read. You should use a font with serifs for the body text and sans serif fonts for headings.
This issue was discussed on the boost-docs list. I put up a side-by-side comparison of serif and sans-serif documentation, and without exception, everyone there found sans-serif to be both more attractive *and* easier to read than serif, even those who initially expressed doubt. If you feel strongly about this point, I suggest you re-open the discussion on boost-docs. Many people you would need to convice loiter there.
4. Some things don't adapt well to differing resolutions and font sizes. Consider the preferred/portable syntax table at http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/function.tutorial.html#id47806.... At my default settings, I see half of the second column. Were the table not offset so far, I'd see the whole thing.
<snip> I can reduce the margin used by tables. Thanks.
5. In http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/function.tutorial.html#id47841..., a list is introduced with, "Three such libraries are summarized below:," but there are no bullets setting off the three paragraphs.
CSS bug. I'll fix it. The other issues you mention do not have anything to do with the style sheet. Thanks. -- Eric Niebler Boost Consulting www.boost-consulting.com
From: "Eric Niebler" <eric@boost-consulting.com>
Rob Stewart wrote:
1. My browser's "always underline links" setting is not being respected. <snip>
2. My browser's link colors are not being honored. <snip>
These specific design issues can be revisited, but the larger question is of a style-sheet overriding browser defaults. Are you against any website creating a distinct look-n-feel by customizing settings such as these?
I set those options for a reason. I don't like it when different web sites usurp my settings and decide what links should look like. Each site has its own ideas about how they should look, so it's hard to know what is and isn't a link at any given site.
3. Sans serif text is harder to read. You should use a font with serifs for the body text and sans serif fonts for headings.
This issue was discussed on the boost-docs list. I put up a side-by-side comparison of serif and sans-serif documentation, and without exception, everyone there found sans-serif to be both more attractive *and* easier to read than serif, even those who initially expressed doubt. If you feel strongly about this point, I suggest you re-open the discussion on boost-docs. Many people you would need to convice loiter there.
Perhaps it has to do with the serif and sans-serif fonts selected. I overrode the CSS settings to use my default settings which means New Century Schoolbook as the serif face (and Helvetica as the sans-serif face). The serif text was far more readable. What serif face did you specify, if any, in your test? I also realize that it may not be possible to select a good, portable, reasonably short set of serif faces to get good cross platform results (not to mention that I don't think you can specify a list of fonts, with faces and sizes, to try until one is found on a given platform). That may mean specifying nothing more than serif and hoping that the user has defined a good default. -- Rob Stewart stewart@sig.com Software Engineer http://www.sig.com Susquehanna International Group, LLP using std::disclaimer;
Eric Niebler wrote:
3. Sans serif text is harder to read. You should use a font with serifs for the body text and sans serif fonts for headings.
This issue was discussed on the boost-docs list. I put up a side-by-side comparison of serif and sans-serif documentation, and without exception, everyone there found sans-serif to be both more attractive *and* easier to read than serif, even those who initially expressed doubt. If you feel strongly about this point, I suggest you re-open the discussion on boost-docs. Many people you would need to convice loiter there.
Here are the points raised in the boost-docs list: <Eric Niebler> The choice of font has a strong influence on the look and feel. I encourage everyone to take a second to compare the serif style to the sans-serif and say which they like better. (My vote goes for sans-serif.) <Rene Rivera> Definitely sans-serif is best. Any typographer will tell you that for low-res situations sans-serif is always the best choice. If you have the luxury of high-res typesetting of a book printing, then can you go serif. <Joel de Guzman> Sans-Serif is best for 72-DPI text. Serif gives a more traditional look on printed text and I wouldn't mind seing serif in PDFs. On screen, I tend to use a bigger serif font to make it easier to read. The extra strokes on small fonts (e.g times) cause eye fatigue. Sans-serif keeps it simple, but not simpler. <Dave Abrahams> I like the sans-serif font, even though I haven't seen your choice of serif font. FWIW, though, choice of font *within* serif/sans-serif can have a profound impact too. <Vladimir Prus> Looking at the experiment, I'd say sans-serif is indeed better. And PDF output uses serif for body text anyway. ...... Obviously, I am with the sans-serif camp. I could go on and actually cite and provide you with links that will substantiate the sans-serif choice, but it's very easy to google. Try "serif sans serif choice typographer" and you'll find lots of info regarding which is best for screen and print. To save you from the trouble, you will find something like: <http://tinyurl.com/5emyz> Serif or sans serif? For continuous reading in print, serif fonts are generally more readable than sans serif. However, on the web, the opposite is true. Serifs are tiny, subtle strokes which, on screen in a small size, become a rather crude series of little square bitmaps. Their absence makes the font more readable. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
Joel wrote:
Obviously, I am with the sans-serif camp. I could go on and actually cite and provide you with links that will substantiate the sans-serif choice, but it's very easy to google. Try "serif sans serif choice typographer" and you'll find lots of info regarding which is best for screen and print. To save you from the trouble, you will find something like:
Serif or sans serif? For continuous reading in print, serif fonts are generally more readable than sans serif. However, on the web, the opposite is true. Serifs are tiny, subtle strokes which, on screen in a small size, become a rather crude series of little square bitmaps. Their absence makes the font more readable.
BTW, it's not a coincidnce that the top 10 sites (e.g): www.yahoo.com www.msn.com www.google.com www.passport.net www.microsoft.com www.ebay.com www.offeroptimizer.com www.amazon.com www.fastclick.com www.go.com all use sans-serif. These big guys hire graphic designers. I'd really push for boost, as a whole (docs/web pages), to switch to sans-serif. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
Serif or sans serif? For continuous reading in print, serif fonts are generally more readable than sans serif. However, on the web, the opposite is true. Serifs are tiny, subtle strokes which, on screen in a small size, become a rather crude series of little square bitmaps. Their absence makes the font more readable.
BTW, it's not a coincidnce that the top 10 sites (e.g):
www.yahoo.com www.msn.com www.google.com www.passport.net www.microsoft.com www.ebay.com www.offeroptimizer.com www.amazon.com www.fastclick.com www.go.com
all use sans-serif. These big guys hire graphic designers. I'd really push for boost, as a whole (docs/web pages), to switch to sans-serif.
My message, at least, was about long stretches of text, not about websites with a few phrases. I'm OK with sans serif for headings, links, table of contents, and what have you. Interestingly, one of the companies you linked to offers both a browser and a word processor that by default use a serif font. Do you own a single book that is printed in a sans serif font? There is also such a thing as x-height interacting with legibility. A font like Georgia (an MS "core font") is great for on-screen reading IMHO. I'm not sure what fonts were compared. Times vs. Helvetica (or Times New Roman vs. Arial) would not be a fair comparison. Bottom line: surely your browser's default setting is to use a sans serif font; I use a serif font; why override that setting? Regards, Rogier
Rogier van Dalen <rogiervd@gmail.com> writes:
Do you own a single book that is printed in a sans serif font?
Books have far higher resolution than screens, so the same arguments don't apply. Serifs in books are much lighter than the rest of the letter, but onscreen, at normal viewing sizes, everything is 1 pixel wide. And don't get me started on antialiased gray "thin" lines. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com
Rogier van Dalen wrote:
Do you own a single book that is printed in a sans serif font?
Yes, and I like it a lot. But then again, that's not the point. -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
On 9/29/04 11:36 AM, "Eric Niebler" <eric@boost-consulting.com> wrote:
Joel de Guzman and I, with the help of many smart folks on the boost-docs list[*], have been working on improving the look-n-feel of Boost's documentation. We're ready to commit the new style, but wanted to check here first.
Volodya was good enough to put up a copy of Boost's docs with the new style applied. You can preview them here: http://zigzag.lvk.cs.msu.su/~ghost/boost_docs/
Please say whether you like the new style or not. If not, be specific about why.
It's OK. But I don't think you should have anything non-link (like your headers) look similar to links. Also, I hate the "no underline until roll-over" type of links. Underline all the time, please.
If you are the author of Boost documentation, please have a look at your docs in the new style and see if anything is out of place.
[*] Thanks to Doug Gregor, Vladimir Prus, Dave Abrahams, Reece Dunn, Jeff Garland, Rene Rivera and others for their valuable feedback regarding the new style.
-- Daryle Walker Mac, Internet, and Video Game Junkie darylew AT hotmail DOT com
Daryle Walker wrote:
It's OK. But I don't think you should have anything non-link (like your headers) look similar to links.
It doesn't. Have you checked recently?
Also, I hate the "no underline until roll-over" type of links. Underline all the time, please.
That is not the best option for Boost documentation, IMO. The link text is often a C++ identifier containing underscores, which get lost when the link text is underlined. Besides, Boost documentation is heavily cross-linked, and having a phrase underlined on nearly every line makes it hard to read. The color is enough to set off links from the rest of the text, and underline on mouse hover confirms it if there is any doubt. The result is less eye fatigue over long periods of reading. -- Eric Niebler Boost Consulting www.boost-consulting.com
participants (22)
-
Angus Leeming -
Bronek Kozicki -
Christoph Ludwig -
Cromwell Enage -
Daniel Wallin -
Daryle Walker -
David Abrahams -
David B. Held -
Doug Gregor -
Eric Niebler -
Joaquín Mª López Muñoz -
Joel -
Jonathan Turkanis -
Manfred Doudar -
Martin Wille -
Reece Dunn -
Reid Sweatman -
Rob Stewart -
Rogier van Dalen -
Thorsten Ottosen -
Vladimir Prus -
Walter Landry