Rene Rivera wrote:
Eric Niebler wrote:
Rene Rivera wrote:
One of the problems with tabular layout I noticed, from looking at
all the docs, is that it creates inconsistent tab points as your
example shows. From my experience tabular layouts only work when you
have strict control of the horizontal tab points and hence can make
them look consistent. Otherwise the effect is of a lower quality
page, and harder to read as it makes one jump around left to right to
follow the tabs.
Wow, I couldn't disagree more. For me, the different column widths
visually separate the parameters variable list from the
returns/requires/throws variable list. This is exactly what the
fop/PDF transforms do by default, and I think the result is very
intuitive and easy to read.
Do you really expect all columns to have the same widths everywhere?
No. But I expect similar information tables to be the same. That is, if
they look the same in style, the should follow the same sizing and
spacing. In this particular case they both look like bold term plus
regular text next to it. So I expect all the text to be at the same
indent position.
Ah, but in the example I gave, they are not "similar information
tables". One is a list of paramter names and their meanings, the rest is
information about the function's contract (requirements, postconditions,
returns, throws, notes, etc.). The information is logically separate.
Making it stylistically identical would make it all run together and be
confusing.
That goes double if I didn't tabularize the variable list. In that case,
there would be no way to tell where the parameter list ends and the
contact description begins. But in that case, perhaps there is something
else we could do to set them appart visually. Might be good to do that
regardless.
I must be misinterpreting you. What are you saying exactly? Where else
in our docs do we micromanage with table widths as you suggest? An
example might help.
The example I have is of my own style, of course ;-) From the Parameter
docs (and hence any other docutils docs) of the info section at the top,
before:
<http://www.boost.org/libs/parameter/doc/html/index.html>
After:
<http://boost.redshift-software.com/doc/libs/1_33_1/libs/parameter/doc/html/index.html>
Clearly, these things all belong in the same table to begin with. They
group together logically. I don't see this as an example of anything but
a doc bug. Hacking the table widths is the wrong fix, IMO. There should
be just one table, and if there were it would look fine.
--
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
