From Edward Welbourne Tue Apr 4 12:26:24 2000 From: Edward Welbourne (Edward Welbourne) Date: Tue, 4 Apr 2000 12:26:24 +0100 (BST) Subject: [Doc-SIG] doc-sig/types-sig clash? In-Reply-To: <14426.29270.837380.905106@dolphin.mojam.com> References: <14426.29270.837380.905106@dolphin.mojam.com> Message-ID: <200004041126.MAA10928@lsls4p.lsl> > One of the proposals regarding typing seems to be inserting stuff into > doc strings. The doc-sig's current working scheme's keyword:ed hierarchical aspects should make some kind of type-info expressible, which could be useful to types-sig: but types-sig hasn't been presuming it particularly. Its mentions of doc-strings don't seem to presume anything dire (I think). The main impact types-sig's current ideas are apt to have on doc-strings is that there *may* be an extra place where one can add them. Where a module (or class) says that `this name in my namespace is to have that type', there may also be scope for a doc-string saying `and here is what I understand my attribute with that name as meaning' ... which would mean we can separate this from the doc of the object in question (which just says what the object does, regardless of who remembers it under what name and what they will use it for), if we want. decl reset: """Resets the module: platform-specific""" def() # This says: it's a func, takes no args, returns nothing if os.name == 'nt': def reset(): """Makes sure the registry knows we're available""" # one implementation elif os.name == 'mac': def reset(): """Nothing to do.""" pass elif os.name == 'posix': def reset(): """Relaunches the daemon (kills old daemon if present).""" # another implementation else: def reset(): """Failure-implementation""" raise os.error, "I don't know how to reset() myself" If it's any comfort, I'm a doc-sig regular being nosy about types-sig and I don't see any conflicts between the two at present. It might be worth types-sig bearing in mind, however, that doc-sig now has a draft spec (waiting for David to find some free time, which might have to wait until the seasonal time-abyss has passed) which provides *scope for* rich hierarchical data (anything XML could do, but written pythonically) in the doc-string ... potentially describing arguments in rich detail ... this could be interesting to those who want *static* type-information to play with. See: http://www.python.org/pipermail/doc-sig/ notably Nov and Dec 1999, notably things talking about `docstring grammar', subject to the usual tendency for threads to meander relative to their subject lines. I don't remember a doc-sig decision about *what* the `Argument:' section would contain, only that there surely will be one and it wouldn't hurt for types-sig to be nosy about it. Fortunately, I detect plenty of overlap between populations on these sigs. > ... private sandbox. Heh. No, the whole mess is Gdo's sandbox, and he's made it public ;^) Eddy. From Edward Welbourne Tue Apr 4 14:37:19 2000 From: Edward Welbourne (Edward Welbourne) Date: Tue, 4 Apr 2000 14:37:19 +0100 (BST) Subject: [Doc-SIG] doc-sig/types-sig clash? In-Reply-To: <200004041126.MAA10928@lsls4p.lsl> References: <14426.29270.837380.905106@dolphin.mojam.com> <200004041126.MAA10928@lsls4p.lsl> Message-ID: <200004041337.OAA06613@lsls4p.lsl> oops ... I'm sat at a machine rigged up for a final check that everything will be working next year ... and my mail headers seem to be confusing pipermail ... sorry about any inconvenience with that ! Eddy. From Edward Welbourne Wed Apr 5 12:29:46 2000 From: Edward Welbourne (Edward Welbourne) Date: Wed, 5 Apr 2000 12:29:46 +0100 (BST) Subject: [Doc-SIG] Documentation systems for other languages In-Reply-To: <14430.37284.507421.983098@weyr.cnri.reston.va.us> References: <14430.37284.507421.983098@weyr.cnri.reston.va.us> Message-ID: <200004051129.MAA20636@lsls4p.lsl> > If there are other systems that are interesting, Occam, specifically the *folding* idiom, as applied to docs in this case. [Imagine, in a paper page on which your code is written, making sideways folds in the paper below each line of text; then you can hide a chunk of the page from view by concertina-ing up that bit of the page.] For a pythonic system, folding would mean taking any fairly large chunk of code or doc (sharing a common base indent) and providing for it to be *displayed* (by the IDE) either (open fold) as the whole chunk or (closed fold) as a single line carrying (typically encoded as a comment) some text that says what's in the fold. In between, of course, we have the fold open but some portions of its contents folded out of sight. Most modern directory-browsers display directory tree hierarchies in a way instantly recognisable to anyone who ever used a folded editor. Shape Data, here in Cambridge, have a (roughly) C source-system using folded files, implemented in-house (by Alan Smith), in which one obvious kind of fold is the doc-fold (but I doubt they've ever thought about publishing it, and it may have passed out of use in the decade or so since I left them). I've heard rumours of a folded-HTML browser. Folding would be a natural idiom for XML (except that it wouldn't be so line-oriented). In many ways it's a particularly natural idiom for indentation-alert languages. A python IDE could implement a folding idiom without necessarily changing the source file: this would integrate naturally with the indentation-based structure. i.e. even if the language and doc tools don't believe in folding, the IDE could offer it. > I'll be glad to add them to the list. But I don't know of anywhere with web pages about folded editors. > So far, all of these are for source-embedded docs, Folded fits that bill, with the twist that a long doc-string (such as verbose folk might write) doesn't carry the penalty of (e.g.) the function name-and-arguments line being on a different page (or screen-full) from the implementation. Eddy. From mhammond@skippinet.com.au Mon Apr 3 23:58:41 2000 From: mhammond@skippinet.com.au (Mark Hammond) Date: Tue, 4 Apr 2000 08:58:41 +1000 Subject: [Doc-SIG] HTML versions of documentation. Message-ID: It would be great if I could get HTML versions of the documentation from the CVS tex versions.. So I started to have a look into the build process. It looks a little complicated, and attempting to perform it on Windows sounds like I would be blazing trails that are better left as old-growth :-) So, I guess my questions are (stop as soon as you can answer "yes" :-) * Has anyone built HTML on Windows? If so and its not too painful, this is my simplest route. * Does anyone know of a CRON job that already does this? * If all else fails, would someone be able to respond to my calls for help should I attempt to perform this automatically on starship (sort of a-la DA's tarballing of CVS)? Does anyone know why starship _wouldnt_ be able to build the .html? Mark. From pf@artcom-gmbh.de Tue Apr 4 08:36:28 2000 From: pf@artcom-gmbh.de (Peter Funk) Date: Tue, 4 Apr 2000 09:36:28 +0200 (MEST) Subject: [Doc-SIG] HTML versions of documentation. In-Reply-To: from Mark Hammond at "Apr 4, 2000 8:58:41 am" Message-ID: Hi! Mark Hammond : > It would be great if I could get HTML versions of the documentation > from the CVS tex versions.. [...] > * If all else fails, would someone be able to respond to my calls > for help should I attempt to perform this automatically on starship > (sort of a-la DA's tarballing of CVS)? Does anyone know why > starship _wouldnt_ be able to build the .html? Since I can't get CVS through our firewall, I have to download the CVS tarballs from Davids account. I do this once a week or so. Building the HTML simply requires to type 'make html' on my SuSE Linux box. ... After installing the "right" version of l2h! Selecting the version of 'latex2html' was the critical part. You definitely need l2h98_2beta6 which is still available on the net. Fred was very responsive on my attempts to get this going. But beware, Fred just started to fold the 1.5.2p2 branch back into the main tree. May be you should wait one or two more days. Regards, Peter From fdrake@acm.org Tue Apr 4 17:26:06 2000 From: fdrake@acm.org (Fred L. Drake, Jr.) Date: Tue, 4 Apr 2000 12:26:06 -0400 (EDT) Subject: [Doc-SIG] HTML versions of documentation. In-Reply-To: References: Message-ID: <14570.6046.944793.305932@seahag.cnri.reston.va.us> Mark Hammond : > It would be great if I could get HTML versions of the documentation > from the CVS tex versions.. [...] > * If all else fails, would someone be able to respond to my calls > for help should I attempt to perform this automatically on starship > (sort of a-la DA's tarballing of CVS)? Does anyone know why > starship _wouldnt_ be able to build the .html? I actually hope to host this myself on python.org as part of the Doc-SIG area, but haven't gotten around to it. Hopefully in the next couple of weeks. The "long HTML" version I promised in my work plan hasn't been dropped on the distribution site, most immediately because I haven't written the README to go with it. ;( That shouldn't take quite as long. Peter Funk writes: > Building the HTML simply requires to type 'make html' on my SuSE Linux > box. ... After installing the "right" version of l2h! Selecting the > version of 'latex2html' was the critical part. You definitely need > l2h98_2beta6 > which is still available on the net. This is still the case. It all requires Unix, but some of the scripts are moving from shell scripts to Python, which should make it easier to use under Windows (eventually). The SGML/XML processes *will* be usable under Windows pretty much from the start (I'll take that as a requirement!). > Fred was very responsive on my attempts to get this going. > But beware, Fred just started to fold the 1.5.2p2 branch back > into the main tree. May be you should wait one or two more days. I think the merge is pretty much done, but I've not proofread the result yet. This will occur someday. ;) I'm currently pretty swamped with various happenings here. -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives From mhammond@skippinet.com.au Thu Apr 6 03:11:55 2000 From: mhammond@skippinet.com.au (Mark Hammond) Date: Thu, 6 Apr 2000 12:11:55 +1000 Subject: [Doc-SIG] HTML versions of documentation. In-Reply-To: Message-ID: That for your comment (and Fred's): > But beware, Fred just started to fold the 1.5.2p2 branch back > into the main tree. May be you should wait one or two more days. Yes - this was exactly why I was looking for a daily job - so that I can actually _read_ these new changes :-) It sounds like Fred does have something planned in the future, so Im happy to let him get all his 1.6 stuff sorted before he deals with cruft like this! Thanks, Mark. From fdrake@acm.org Thu Apr 6 16:14:29 2000 From: fdrake@acm.org (Fred L. Drake, Jr.) Date: Thu, 6 Apr 2000 11:14:29 -0400 (EDT) Subject: [Doc-SIG] Unicode documentation Message-ID: <14572.43477.808865.740573@seahag.cnri.reston.va.us> I've added Marc-Andre Lemburg's documentation updates for Unicode to the CVS repository. I still have a bunch of other patches and bug reports to deal with, but I'm going to do some paying work for a few hours now. ;) -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives From den@analyt.chem.msu.ru Tue Apr 18 11:25:05 2000 From: den@analyt.chem.msu.ru (Denis S. Otkidach) Date: Tue, 18 Apr 2000 13:25:05 +0300 Subject: [Doc-SIG] tut.tex errors and typos References: <14572.43477.808865.740573@seahag.cnri.reston.va.us> Message-ID: <00fe01bfa920$5cee1e20$a8d1d0c3@chem.msu.ru> Hi! While translating tutorial into Russian I have encountered some errors and typos. Here they are. (Sorry for bad English -- it's not my native language.) tut.tex, l:2078 > \emph{first} time the module is imported somewhere.\footnote{ > In fact function definitions are also `statements' that are > `executed'; the execution enters the function name in the > module's global symbol table. ^^^^^^ local tut.tex, l:2096 > script, for that matter). The imported module names are placed in the > importing module's global symbol table. ^^^^^^ local Here is an example demonstrating that names are introduced in local symbol table: >>> def f(): ... import string ... >>> string Traceback (innermost last): File "", line 1, in ? NameError: string >>> f() >>> string Traceback (innermost last): File "", line 1, in ? NameError: string >>> ============================================================================ === tut.tex, l:3509 > Data attributes may be referenced by methods as well as by ordinary > users (``clients'') of an object. In other words, classes are not > usable to implement pure abstract data types. In fact, nothing in > Python makes it possible to enforce data hiding --- it is all based > upon convention. (On the other hand, the Python implementation, > written in C, can completely hide implementation details and control > access to an object if necessary; this can be used by extensions to > Python written in C.) > > > Clients should use data attributes with care --- clients may mess up > invariants maintained by the methods by stamping on their data > attributes. Note that clients may add data attributes of their own to > an instance object without affecting the validity of the methods, as > long as name conflicts are avoided --- again, a naming convention can > save a lot of headaches here. I propose something like the folowing: Some classes require data attributes to be hidden to avoid accidential corruption of object invariant. You can hide attributes using names prefixed with at least two uderscores and with at most one underscore --- such attributes are private and are accessible from instance methods only. (In fact you can access private data attributes using special name convention, but this won't be accidential. See also section \ref{private}.) ============================================================================ === tut.tex, l:3582 > Methods may reference global names in the same way as ordinary > functions. The global scope associated with a method is the module > containing the class definition. (The class itself is never used as a ^^^^^ function (usually the same as containing class definition) Here is an example: module.py: ---------- gv = "module" def f(self): global gv print gv prog.py: -------- import module gv="prog" class c: m=module.f o=c() o.m() result of prog.py execution: ---------------------------- module ============================================================================ === tut.tex, l:2797 > Strings can easily be written to and read from a file. Numbers take a > bit more effort, since the \method{read()} method only returns > strings, which will have to be passed to a function like > \function{string.atoi()}, which takes a string like \code{'123'} and ^^^^^^^^^^^^^ int() > returns its numeric value 123. However, when you want to save more string.atoi() is deprecated. ============================================================================ === Just a typo... tut.tex, l:750 > characters. This lead to very much confusion especially with respect > to internalization (usually written as \samp{i18n} --- \character{i} + ^^^^^^^^^^^^^^^ internationalization > 18 characters + \character{n}) of software. Unicode solves these ============================================================================ === tut.tex, l:768 > \begin{verbatim} > >>> u'Hello\\u0020World !' ^^^ \u (at least Russian-enabled LaTeX eat it) > u'Hello World !' > \end{verbatim} > > The escape sequence \code{\\u0020} indicates to insert the Unicode ^^^ \e u \\ causes linebreak ============================================================================ === tut.tex, l:799 > Apart from these standard encodings, Python provides a whole set of > other ways of creating Unicod strings on the basis of a known ^^^^^^ Unicode > encoding. With best regards, Denis.