First, sorry I couldn't post much earlier... It's been a very busy week. Second, I need to clarify some aspect of the doc styles, and specifically about the new web site docs. And also give some comment to Matias styles.
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. How that happens is that the ZIP archives for all the release are put on the web server. The doc section pages, when requested to open one of the version specific doc files, opens a specific archive and expands+reads the file into memory. It then post processes that file, on the fly, stripping out all of the header and footer content. It also does some number of cleanups and fixing in the content itself. Currently that is done via structured regex search+replace manipulation, but I'll be changing that at some point to do DOM manipulations now that the server has PHP5. The doc is then incorporated back into the web page one sees with the standard header and footer for the web site. The CSS used is entirely different than the one in the document at this point, since it comes from the standard web site style! The style used for the docs is designed, and inherited, from the style for the rest of the site (exemplar page <http://beta.boost.org/development/exemplar.html>). There are additional styles to handle the variety of elements and changes over time that the Boost docs have had, and are still having ;-) The presentation architecture has some consequences for Matias styles, and other author's styles... They will *only* be visible in the downloaded release, iff they are generated by the authors themselves. The content of the header, i.e. the search box, will not be available on the web site. And hence will *only* be available in the downloaded release. This also happens to be the one context under which it's likely not usable as the person might not have network access. Changes to the style of the docs are less likely to make it to the web site than changes to the release style. This is intentional, as it's important to keep a consistent look & feel on the web site. Both for usability and presentation quality of the web site. It means that changes to the web site style have to arbitrated even more than changes to the release doc styles. 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. 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. 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. 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>.) 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. 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. I see that Matias needs to make some of the elements of the images a bit darker in this respect. 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. -- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org - grafik/redshift-software.com -- 102708583/icq - grafikrobot/aim - grafikrobot/yahoo ------------------------------------------------------------------------- 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
