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? 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. Not even the C++ standard
uses definition list-style layout for function descriptions, FWIW.
The change to the XSLT is simple, so that's not a concern. The usability
of the docs is my #1 priority. So ... opinions on this? Let's hear 'em.
--
Eric Niebler
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
