"Eric Niebler" <[EMAIL PROTECTED]> writes: > Joel de Guzman wrote: >> Joao(IIRC) and I expressed support for it. I think it looks nice. >> However, Dave does have a point. And his point is about consistency. >> You showed me how consistency with the boxes (code, tables, TOCs, >> blurbs), however different they may be in terms of function, can >> improve the docs. And it did, significantly! Perhaps this applies >> here too? That said, I'm not so sure I like Rene's layout either, so >> I'm half-half. Maybe you can cook a variation of your scheme that >> is more consistent with the rest of the doc layout? > > I *heart* consistency. :-) But with which part of the rest of the doc > layout is the function description inconsistent?
Pick any other place where there are multiple levels of hierarchy: nowhere else is there a bold heading marker next to another bold heading marker. Yes, the term is a heading marker because there can in principle be multiple paragraphs of definition. > I'm not trying to be > difficult, it's a serious question. Dave's example was bogus, IMO -- an > apples to oranges comparison. > > I've done a before and after to make this discussion a little less abstract. > > Tabularized function descriptions: > http://boost-sandbox.sf.net/libs/xpressive/doc/html/boost/xpressive/cpp_regex_traits.html > > Definition list-ified function descriptions: > http://boost-sandbox.sf.net/libs/xpressive/doc/html/boost/xpressive/cpp_regex_traits2.html > > (Sorry for the long URLs. TunyURL is down at the moment.) > > Fact: with definition lists, less fits on the screen. And it's no easier > on my eyes, either, but that's subjective. It would be a *lot* easier to look at if the definitions were moved closer to the terms, as I've mentioned several times. > Not even the C++ standard > uses definition list-style layout for function descriptions, FWIW. Those look like definition lists to me, even if HTML doesn't format DL's that way. There just doesn't happen to be a line break between the term and the definition, which is no big deal for me. They're certainly not tables. More importantly, there's no additional level of hierarchy to the right. -- Dave Abrahams Boost Consulting www.boost-consulting.com ------------------------------------------------------- This SF.Net email is sponsored by xPML, a groundbreaking scripting language that extends applications into web and mobile media. Attend the live webcast and join the prime developer group breaking into this new coding territory! http://sel.as-us.falkag.net/sel?cmd=lnk&kid=110944&bid=241720&dat=121642 _______________________________________________ Boost-docs mailing list [email protected] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs
