[Python-Dev] Playing with a new theme for the docs

[Stephen J. Turnbull]

On Wed, Mar 28, 2012 at 4:45 AM, PJ Eby <pje at telecommunity.com> wrote:

> [ body { width: 65em; } ] won't work - it'll make the entire page
> that width, instead of just text paragraphs.

True (I realized that might be bad in many cases later -- should have
tested first rather than posting something  random), but despite your
argument, "p { max-width: 40em; }" will be good
enough to handle pages where the designer leaves text width up to the
user.  Pages (or parts thereof) where the designer fubars the format
for you are not my problem, they're *your* problem.  "Be careful what
you ask for, because you just might get it."

Also, this is UI, in an environment where poor UI is easily worked
around with a flick of your mouse.  A improvement in 90% of the cases
is a 90% improvement -- there won't be any fatal problems in the 10%
where designers choose a max-width that's 200% of your personal
max-width or whatever.

> Your analogy is backwards: virtualenv is a generic,
> does-it-all-for-you, no need to touch it solution.

If you want to phrase it as an analogy, mine is

    virtualenv :: do-it-*for*-you :: site-specified max-width

but

    dump-it-in-a-directory :: DIY :: user-specified CSS.

The point of the analogy is that you're being inconsistent by using
dump-it-in-a-directory yourself but recommending site-specified
max-width for the Python docs.

It's true I'm being similarly inconsistent in a sense (using
virtualenv myself but recommending user CSS for Python docs).
However, in this discussion, there are more important things than
consistency.  I think there are an awful lot of people who need
reliable deployment, consistent with their development environments,
so it makes sense to have Ian package it up for us as "virtualenv",
and for it to be somewhat inflexible in its rules for doing so.  OTOH,
AFAICS those who use maximized windows for everything are a relatively
small minority who will be well-served by a simple workaround, and
there are gains to having the flexibility for the rest of us.

The big problem from my point of view with the user CSS "solution" to
the maximized-window problem is that common browsers don't make this
easy to do.  Cf. Terry Reedy's post
asking how to specify user CSS for Firefox (where it's actually easy
enough to do once you know how, but evidently not very discoverable).
However, if you're in a sufficiently small minority (as I believe you
are), it makes sense for Georg to (regretfully<wink/>) ask you to use
personal CSS to tell your browser about your preference.

> User CSS and window sizes have to specified per-site.

They do?  But *you* don't, you just maximize your window.  So only a
few sites will need specification in any case, those whose max-width
exceeds tolerable bounds for you.  And a personal max-width will
affect only unbounded pages unless you use "! important".

The point of user CSS is not to get optimality, which is a
content-dependent problem for negotiation between user and designer,
and sometimes one side or the other takes absolute priority.  It's to
ensure that users with special needs (very nearsighted users, users
who prefer to work always in a maximized browser window) don't get
screwed by extreme designs.

> (Note that it doesn't suffice to use a small
> window to get optimal wrap width:

I don't believe in optimal wrap width, and as far as I know, neither
do the 1% of designers.  I don't even *have* a personal optimal wrap
width, although max height is almost always close enough to optimal.
But I sometimes maximize the width of my browser window to get even
more of the "structure" of text viewable in it, or reduce it to make
word-for-word reading more efficient.

Again, the problem here is not "suboptimal".  AFAICS, it's preventing
a few people who have evolved personal workflows adapted to a common
design pattern that's not appropriate for documentation (IMO YMMV)
from getting *pessimal* results.  I believe that you can get what you
need with user CSS in the case of no max-width (let's not forget that
you and R. David Murray may prefer different values!), while many
use-cases would want no max-width.  But "p { max-width: none !
important; }" would not work well for us, since it would override all
designers who set max-width.

> I think we should just agree to disagree; there's virtually
> no way I'm going to be convinced on either of these points.

Hey, I'm an economist: de gustibus non est disputandum.

Convincing you is not my goal; I want to convince Georg!  *Policy*
needs to be for the greatest good of the greatest number, and Georg
IMO should set max-width, or not, as that makes reading the
documentation more effective for the most people.  I prefer "not",
assuming it doesn't completely trash its usability for you and David
(and assuming you're in as small a minority as I believe you to be).