On 6/13/07, John Maddock <[EMAIL PROTECTED]> wrote: > Rene Rivera wrote: > > The big warning about the docs, as they are presented on the beta web > > site: They override, disregard, and literally throw away the style > > information in the source docs. > > I thought that one of Matias's aims was to develop "one true style" suitable > for the web, Boostbook .css and pdf formats. Especially now that more and > more of Boost is getting "quickbooked".
I have started a new thread. This subject is deemed important. > > Now, commenting on Matias doc style <http://tinyurl.com/2hxdsm>... > > > > I like the navigation icons. The one change I would make would be to > > the home icon. It's outline is not as clearly a house as the > > black&white > > one. Which takes a bit more visual effort in noticing what it is. It > > also looks like if the house icon is simplified a bit it would be just > > as easy to create a vector version of it as it looks like it would be > > of the others. I'm guessing, but it looks like the software Matias > > uses is already operating with vector sources. > > I agree that's probably the weekest of them: but still better than the > Docbook default IMO. I have never work with vector editors, it will be nice if someone can jump in and make a proof of concept of different svg navigation icons. > > Not specific to Matias doc style, but the BoostBook style. The > > headings are too big. This is likely because of the usual style > > escalation > > present in so many documents. > > I disagree, and find the heading in the website syle too small. Sorry. Same here, It seems that we have different tastes :) I like the blue boostbook theme a lot. The green one is strongly based on it. > > Irrespective of the code colorings, I don't like the code background > > color, nor the heavy border around it. The use of such heavy style > > elements should be reserved for attracting attention only. For example > > in sidebar notes, warning texts, etc. And I've mentioned this before; > > Having it in the regular flow of text interrupts reading and > > comprehension. In that it obscures the over all structure of the > > document. > > Difficult one this, I'm very much in the "less is more" camp here, but I do > find that a slight tint to code blocks helps out. I'm neutral on the border > issue. We can reduce the border shadow from 3px to 2px... 1px makes a lot of difference there. > > The size of the code text is too large. This again elevates the code > > in importance above the regular text. IMO the code text size should > > always be either the same, or preferably smaller than the regular > > text. The reason I say preferably is because it's very hard to tell > > size equality between two different font families. In particular, > > even though the two sizes Matias is using might be the same, the > > Courier font looks bigger because it has wider characters. I.e. it > > looks like it occupies more space. (Contrasting example from the web > > site style http://tinyurl.com/35lg32.) > > I agree the code should be smaller than the body text, and I believe it is: > 9pt rather than 10pt, and IMO about right. Maybe I'm just getting old, but > I find the web page you reference really rather hard to read: in the code > blocks especially the font is too small I like to have the same size for the code but I have no strong opinion here. I do not like it to be as small as it is in beta docs, I have troubles reading it. > > This one is just an overall warning... For the code coloring, and with > > much everything else in text, one has to avoid to an extreme overusing > > style elements. For code this means that we should prefer using a > > style that *doesn't* bold, italicize, underline, and colors the > > majority of > > the text. Color and style should only be used for elucidating > > structure and meaning. > > I think we all agree on that. Yep. > > And another general issue... We have to keep in mind the less > > fortunate people who don't have the full capacity of their eyes. So > > avoid using light text on a light background, and of course the > > inverse. I.e. avoid low contrast arrangements. > > Also agree, the code comments being the main culprit. Ok, it was a very bad idea :( But it was fixed by John. > > I see that Matias > > needs to make some of the elements of the images a bit darker in this > > respect. You are right about that. I will change some of them. > > This also applies > > to the code block background color. Having a colored background > > decreases the dynamic range one has to play with, as it reduces the > > difference in luminance between the background and foreground. > > Nod. Agree, but being fair we have use a very very light green here. The dynamic range has not been reduced significantly. And we can even used a lighter one. I think that all this discussion is positive. Best Regards Matias ------------------------------------------------------------------------- This SF.net email is sponsored by DB2 Express Download DB2 Express C - the FREE version of DB2 express and take control of your XML. No limits. Just data. Click to get it now. http://sourceforge.net/powerbar/db2/ _______________________________________________ Boost-docs mailing list [email protected] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs
