Python-by-example - new online guide to Python Standard Library

[AK]

CM wrote:
> On Apr 2, 2:50 pm, AK <andrei.... at gmail.com> wrote:
>> Terry Reedy wrote:
>>> "AK" <andrei.... at gmail.com> wrote in message
>>> news:47f2d018$0$6517$4c368faf at roadrunner.com...
>>> || I'll be glad to hear comments/suggestions/etc:
>>> |
>>> |http://www.lightbird.net/py-by-example/
>>> Using - as the example/return delimiter does not work.
>>> If you do not want to substantially lengthen the document by going to
>>>>>> sqrt(9)
>>> 3
>>> then use Python's a comment symbol.
>>> sqrt(9) # 3
>>> -or-
>>> sqrt(9) # returns 3 (but I think I prefer the first)
>>> which clearly is not an arithmetic expression and which can be
>>> cut-and-pasted into the interactive interpreter.  This also works nicely
>>> for invalid examples.
>>> sqrt(-9) # raises ValueError
>>> Terry Jan Reedy
>> Thanks to everybody who replied, I will implement the change as per
>> Terry's advice. I'm still considering whether to use the standard
>> interpreter syntax, i.e. >>> ... \n result; my reason for not doing that
>> is that I will often have a whole screen of function / result lines and
>> if I were to add a new line for the result, that'd make two pages out of
>> one, which I think is a bit too much. In current docs there are not so
>> many examples, so that space is not multiplied quite so much, and using
>>   interactive interpreter way of showing result is not nearly as much of
>> a problem. However, I'm still thinking this over and it seems that
>> almost everyone wants to see it done in that way, I might still go for
>> two lines. I'll also be posting updates as the work progresses..
>>
>> thx,
>>
>> --
>>   -ak
>>    Tobu |http://www.lightbird.net/tobu/| Freeform DB / Tagger / PIM
>>    Python-by-Example |http://www.lightbird.net/py-by-example/| Guide
>> to LibRef
> 
> You should also change the look of the page to be more high-contrast.
> The grayish text in a gray box and the light green text...all too
> subtle to see.  Not easy for well-sighted people let alone those with
> poorer vision.  Try make things visually very obvious, bolded headers,
> etc.  If so, and with the change of showing the result not with an "-"
> symbol, it will be much stronger.  Thank you for doing it.

Okay, will do. In fact this is the second time in as many days that I 
get a comment on my proposed designs to use more contrasted text vs. 
background (in fact, for the other design about 3-4 people mentioned 
this topic). I really had no idea many people have trouble with that. To 
me, less contrasted text looks smoother and more aesthetically pleasing 
to the eye, unless I have to read 3 pages or more of condensed text. I 
also do eye excercises religiously every day:-), so this may train the 
eyes to see small details better, but I design for other people to use, 
therefore I will of course try to make it as easy to read for as many 
people as possible.. Thanks for the comment! I will update the site 
tomorrow morning with all the changes..


-- 
  -ak
   Tobu | http://www.lightbird.net/tobu/ | Freeform DB / Tagger / PIM
   Python-by-Example | http://www.lightbird.net/py-by-example/ | Guide 
to LibRef