[DOC-SIG] Python Library Reference in new HTML form

[Laurence Tratt]

>> Hmm... On my browser, H5 is relatively large. This is a problem; this 
>> sort of things is *so* browser dependent, I'm not too sure what the 
>> best things to do is. Perhaps H4?
> There is no browser-independent way to do this.  If you want to
> support minority browsers, this is difficult.  If you only need to
> support "major" browsers (IE, NS), it not too bad, but results in poor 
> markup ("tag abuse"):  <font size="+3">...</font> (or "+2", "+1",
> etc.).  Perhaps the best is simply something like <strong>...</strong> 
> ;-).

But Strong is generally just Bold... The concern was over font size. 
I tend to think of font size as something of last resort... I'm 
taking suggestions though :) The problem is that no matter what I do, 
it'll never look perfect on more than one browser; it's a question of 
getting acceptable on as many as possible, I suppose.

>> I'm not averse to using "_" although I think hard spaces 
>> are a little easier on the eye if your OS supports them. Perhaps two 
>> different versions, one with hard spaces and one with "_" should be 
>> included, or would people prefer just a dashed version? 
> Just decide on one and use it; don't have multiple versions.  That
> just confuses life.

Well I've used WinZip on one machine, and it coped with hard space 
OK, and then on another it went banannas sticking accented a 
characters in every where :/ I like hard spaces, but it looks as if 
I'll need to use dashes to maintain compatibility which is not what I 
wanted, but could be considered typical. As a great deal of people 
use WinZip (I use SparkFS, some people will use gzip then tar, but 
not many as a percentage I suspect) on Windows machines, it looks as 
if I'll have to uses dashes :(

>> This is, I think, one of the few (UserDict and UserLib are basically 
>> the same page) places where this happens. The only solution is to 
>> change these links after the conversion process. If it's any 
>> consolation, I'm not aware of any other mistakes in linking, 
>> although  
> There is one other place in the PLR where two modules share a
> section, so a similar symptom might show up there.  I'll move the
> separation of modules in separate sections up on the priority list.

It is quite confusing... There's anydbm and dumbdm, but I don't think 
there's any others... Quite a few lib*.tex files document more than 
one module within them, but that doesn't seem like a problem to me, 
at least.

>> But I can't be sure where they will be stored on the users computer 
>> :( When I release the source, it should be easy to quickly alter it 
> I'm not sure I like the idea, though.  It encourages reading the
> source as an alternative to documentation, which leads to poor
> documentation and too many users who misunderstand what's part of the
> public interface and what isn't.

I don't think I'd include it by default... It would be intimidating 
to novice users and a great deal of other users. Python does not need 
to be seen by the outside world to be "just another difficult to 
learn, technically minded language". But it could be an option if 
people want to make their own manuals...


Laurie

_______________
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
_______________