Mailman 3 March 1998 - Doc-SIG

gendoc patch?
by Henk Jansen April 1, 1998

April 1, 1998

(My) gendoc can't handle the package import structure of python 1.5. (doc_collect.py issues an error at line 533). As Mark Hammond wrote to this list on Thu, 19 Feb 1998: >... Currently gendoc has been patched >to work in 1.5 by it's author Daniel Larsson. I presume that a newer/patched version must be around somewhere. I can't download this, however (I can't access Daniel Larsson's starship/crew account). Can anyone point the to this? Thanks, Henk. -- ----------------------------------------------------------------------- | Henk Jansen hjansen(a)math.tudelft.nl | | Delft University of Technology P.O.Box 5031 (Mekelweg 4) | | > Information Technoloy and Systems (ITS) 2600 GA Delft | | >> Mathematics (TWI) The Netherlands | | >>> Applied Analysis (TA) phone: +31(0)15.278.7295 | | >>>> Large Scale Models (WAGM) fax: +31(0)15.278.7209 | -----------------------------------------------------------------------

3 5

documentation release status
by Fred L. Drake March 27, 1998

March 27, 1998

Well, I remember saying that I'd get the docs out this week, but I'm being called out of town on fairly short notice for several days. I think next weekend is reasonable, however. The current state is that the HTML conversion has poorly formatted indexes, but that will only take a couple of hours work. These is a weird glitch in the PDF files that I don't understand yet, so that's a biggie. It may go out without new PDF files, with those following along when I get the process working better. They look fine, but the outline on the left doesn't always respond when clicked. I'll post again when I have something to report. -Fred -- Fred L. Drake, Jr. fdrake(a)cnri.reston.va.us Corporation for National Research Initiatives 1895 Preston White Drive Reston, VA 20191

1 0

Test message for doc-sig
by Ken Manheimer March 19, 1998

March 19, 1998

This is just a test message for members of the doc-sig. I will also be sending a separate message to the gui-sig, which should help you distinguish your memberships. To change your subscription for the doc-sig, visit: http://www.python.org/mailman/listinfo/doc-sig Ken Manheimer klm(a)python.org 703 620-8990 x268 (orporation for National Research |nitiatives # If you appreciate Python, consider joining the PSA! # # <http://www.python.org/psa/>. #

1 0

Re: [DOC-SIG] Python Library Reference in new HTML form
by Laurence Tratt March 19, 1998

March 19, 1998

>> 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? > Why should one have to look at the filenames? Because it can give you a very good clue as to what page you are going to be whisked off to. Say if your cursor is over xrange, which will be a link in most circumstances, most people won't know that it's a built in function, but if you look at the link in name, it'll say: "...Built-in functions/xrange.html" which gives the game away :) Laurie _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org _______________

1 0

Re: [DOC-SIG] Python Library Reference in new HTML form
by Laurence Tratt March 18, 1998

March 18, 1998

>> Eek. I bet it'll break my entire converter :) Is it a big markup >> change, or is it largely the same as before? > Probably, but it's not likely to be significant. Mostly, a bunch of > things that were marked \code{...} are marked with other names. Some > of the index things have been changed (mostly new ones added), and a > couple of new environments have been defined. "\," has been eveicted, > mostly to get LaTeX2HTML to get things right. What sort of things that were \code aren't \code any more? I have to admit I couldn't discern any obvious rules for \<character> and such like, so some rationalisation does seem sensible :) Any added index commands is almost certainly a good thing. I think there's a lot of scope for adding lots of things to the index. >> most people, but you'll always get a tiny minority who want it on >> A4.6 or some bizarre proprietary size, triple sided or something else > Oh, I want some of that triple-sided paper! Think mt employer will > spring for the fancy printers? ;-) It's Microsoft triple-sided paper. Guaranteed, and very user-friendly. Laurie _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org _______________

2 1

Re: [DOC-SIG] Python Library Reference in new HTML form
by Laurence Tratt March 18, 1998

March 18, 1998

>> 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 > Yes; the intent of my solution was to avoid dealing with the font > size at all. ;-) Oh, OK :) The original point was that the font size wasn't big enough... Perhaps it will come down to font size += ickiness. > The number of modules per .tex file should be entirely irrelevant, > but those which describe more than one, with the UserDict/UserList and > anydbm/dumbdbm exceptions, still use one \section{} for each module. > That's where the problem creeps in. Agreed. I'd have to get rid of my code that copes with that at the moment though ;) Laurie _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org _______________

1 0

Re: [DOC-SIG] Python Library Reference in new HTML form
by Laurence Tratt March 18, 1998

March 18, 1998

> Editor-based help can be a big plus, so it makes a lot of sense to > have a new conversion to do that. > With the coming release, the Module Index is directly addressable by > name, no "node####.html" cruft! That makes it bookmarkable, so > eliminates a least having to wade through the Table of Contents. It's > also a lot shorter, so it loads faster! That will be better. As far as I can see, though, the only way to get editor help is to do the splitting up of files that I've done. Unless each module has one monolithic page you can't really do #### sort of stuff, but having everything on one page would be horrendous. >> Hmmm, you should see the regular expression code I've got to do >> links. It's not very long, perhaps 3 or 4Kb, but already > Hm.. perhaps I shouldn't see it! Well, it works and it would be a lot worse if I parsed it manually :) > Most of the markup changes are to take advantage of the > newer markup I've defined, shift the whole mess to a more modern LaTeX > (version 2e instead of 2.09), and improve the general consistency of > the markup. Eek. I bet it'll break my entire converter :) Is it a big markup change, or is it largely the same as before? > The drive behind releasing it at this point it that I've promised it > to the people who wanted a LaTeX source release. Most of those > requests really just want it on A4 paper. (Maybe I should just > provide a PostScript version formatted for A4?) Personally I can't imagine printing out this sort of stuff on A4 but that's because I could never justify the expense and I find it as easy to look at it on screen. Surely postscript would be easier for most people, but you'll always get a tiny minority who want it on A4.6 or some bizarre proprietary size, triple sided or something else which means they'll want the source and not the "binary". Laurie _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org _______________

2 1

Re: [DOC-SIG] Python Library Reference in new HTML form
by Laurence Tratt March 18, 1998

March 18, 1998

>> 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(a)python.org administrivia to: doc-sig-request(a)python.org _______________

2 1

Re: [DOC-SIG] Python Library Reference in new HTML form
by Laurence Tratt March 18, 1998

March 18, 1998

>> I've (hopefully) just about completed a project for my platform to conver >> the Python Library Reference and Tutorial to a format specific to the >> platform. >I don't see where you mention what platform / format you were > originally targetting. Could you tell us about it? Um, it's Acorn RISC OS, and if you've actually heard of it, I'd be very impressed :) The format I converted it to is vaguely similar to HTML, but has several advantages in that it's searchable (and the searching is massively fast. It's virtually instantaneous on 2Mb of data, and it has to load it all from my not too fast hard disk), the program that displays it keeps windows nice and small so you can have them at the side of the screen whilst you're programming. The page splitting thing came from the fact that this was the way I could click "F1" on a function in my text editor, and get help on it straight away. > I will definately be taking a look at your version, but I'm a little > swamped right now. I'll stash a copy aside and take sneak peeks. ;-) I did guess that even if this is of no obvious help, it might give the next HTML generation of documentation some good ideas. > Were you aware of the module index in the last release? A single > page with a list of modules alphabetically sorted. Yes, but I find it's annoying to have to wade through things to get to what I want when really I want a front page where I can click on what I want straight away. Perhaps the order of the current manuals front page is more useful for total novices, but after that I think that most people probably find it a pain unless they know their way around it very well. It seems distinctly un-user-friendly, and slow. This is just my opinion, I could be wrong here :) > I have mixed feelings about extensive links, but a lot of that has > to do with the aweful presentation of web browsers. Well, I've kept to a fairly small subset of HTML. There's tables in there (obviously), but that's as difficult as it gets. There's no font size commands or anything else that makes things look good on one browser and awful on another. I only tested it out on Acorn Browse and ANT Fresco (no, you probably haven't heard of either of them), but I'll try Netscape later today. Hopefully, things will look OK. > CSS can help, but there does't appear to be a common understanding > among the browsers as to what "getting it right" means. Oh, the > font problems on Netscape/UNIX drive me bonkers! I think it is easy to get embroiled in platform specific stuff like this. I'm lucky; RISC OS has had a very good antianialised font manager in since 1988, so there's no problems. I kept things simple because I know that as soon as people start marking around with font size and font faces on most OSs, things start breaking down (Windows is horrendous with text that isn't relatively large, for example, because it doesn't antianialise text). > Future releases will improve the semantic content of the markup, > making it a little easier to create links automatically. Hmmm, you should see the regular expression code I've got to do links. It's not very long, perhaps 3 or 4Kb, but already unmaintainable :) > The version I'll be releasing shortly makes URLs "hot", but leaves > email addresses alone (though they are marked and could easily be > turned into hyperlinks). I do this to avoid swamping people with > mail. Fair point. What do other people think of this? > Good idea. And I've been wrestling with LaTeX2HTML indexing a lot > lately. ;-( Never run it. I had to look at it before I could guess what {\rm} meant :) > I guess my name is "somebody", then. ;-) I've been working on them > a bit, but I've been spending a fair amount of time lately on Q/A for > the LaTeX documents. My expectation is that I'll be able to generate > more usable SGML from them. The intention of the SGML conversion > project is to move toward SGML for the official documentation sources. > There's still a lot to do, though, mostly due to my schedule > constraints. Could you explain this a little more? I'm guessing that at the moment you're updating the LaTeX docs and once you've got those stable you'll convert them all to SGML, and use those as the base documentation? Sounds very sensible to me. LaTeX is not particularly easy to parse, I've found. >> 1) There's a .tar.gz file to download, it contains lots (nearly 2300 >> files if I'm being honest) files with 150ish directories at the >> top level > That is a lot of files.... It's an unusual system :) >> build from "this morning"), very slow but entirely in Python. I will >> release the source in the near future (hopefully within a month), >> but at > I look forward to this. I hope you had the good sense to ignore > partparse.py from the current distribution! ;-) (The LaTeX scanning > isn't really that bad, but the code is unmaintainable!) I'm afraid the code is about 99.8% based on me looking at LaTeX, guessing what the output would look like if I'd invented the language, then going about doing it. I had to look in the LaTeX2HTML source to guess what {\rm} could be, and every so often I referred to the original HTML documentation to check to see if something that I thought was wrong was intentional or not... This is probably not good programming practice :) Everything is a little fragile, because the parser was only ever intended to work with the PLR. > I plan to make available a documentation release in HTML, LaTeX, > PDF, and PostScript next week. Good. How much has been updated since the last release? Laurie _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org _______________

2 1

Re: [DOC-SIG] Python Library Reference in new HTML form
by Laurence Tratt March 18, 1998

March 18, 1998

>> Um, it's Acorn RISC OS, and if you've actually heard of it, I'd be >> very impressed :) > Sure has. Never seen one in real life, though (IIRC, the Acorn > web browser is about the only one that can handle all flavours of > the PNG image format, including all kinds of transparency). Coo. I'm impressed :) And yes, I think you're right about the Acorn browser. It's still in beta at the moment, but it's coming along nicely. Andrew Hodgkinson and co. seem to be going pretty well on it at the moment. It is, in RISC OS terms, pretty memory hungry though, taking up nearly a megabyte even when it's not doing a great deal. Though that's insignificant when compared to, say, IE or Netscape :) >> I did guess that even if this is of no obvious help, it might give >> the next HTML generation of documentation some good ideas. > FWIW, it looks like it would be very little work to adapt your stuff > to Microsoft's new HTML Help utility (a nifty little utility which packs > tons of HTML pages into a single archive, adds advanced indexing and > free-text search facilities, etc). Might give it a try later this week. Feel free. If there's any changes that need to be done (and I can do them), don't hesitate to ask. Once I've got a couple of things de-platform-specificed (is that a word?) from the source so to speak, I'll probably go ahead and release it. It's not too large. The whole thing, including the HTML outputter and the StrongHelp outputter (which is the original one for Acorn machines) is just over 90Kb and it clocks in at around 3000 lines. It's not a particuarly good example of exemplary programming practice, but that's because I thought initially I'd only do a small crude conversion, when what I wound up with was a very big, crude conversion. It's not so large that people shouldn't be able to find their way around it, if they need to. >> Windows is horrendous with text that isn't relatively large, for example, >> because it doesn't antianialise text). > Footnote: it does, if you have the Plus! extensions and a 15-bit or better > screen (the anti-aliaser can also be grabbed from microsoft.com). But I > usually use the free Verdana font (designed for the screen by one of the > world's leading typeface designers) -- it looks excellent at almost any size. The last time I saw Plus, it could only anti-alias text that was *larger* than a certain size which rather defeats the point :) That might, however, have been an example of a dodgy machine setup. Believe me, once you're used to antianialised text everywhere (except in text editors... it looks out of place with monospaced fonts) it's hard to go over to non-anti anialised. Laurie _______________ DOC-SIG - SIG for the Python Documentation Project send messages to: doc-sig(a)python.org administrivia to: doc-sig-request(a)python.org _______________

1 0