Mailman 3 December 1998 - Doc-SIG

RE: [Doc-SIG] An 'apropos' utility for documentations
by John Skaller Dec. 12, 1998

Dec. 12, 1998

At 23:06 10/12/98 -0500, Tim Peters wrote: >> And then I saw the TODO list Ken put up. >> Which is excellent! So, if there were a way to >> make an _online_ list of every function, class, and module >> in the library, with the current docstring, and allow >> everyone to add docstrings over the Internet, like the TODO list, >> we'd have more people able to make small contributions. > >I have no idea how to implement that (specifically getting the latest >contributions back into the sources), I agree. This is nasty. But I think it can be done for _python_ modules fairly easily. For C modules, it will require manual patching. For Python modules, the parser can identify not only what a docstring is, and which object to plug it into (module, class, function) but also when there is NO docstring .. and hence a place where one COULD be put. If the parser was temporarily stuffed with by <wink>ing a lot at it, it could generate a file of all the docstring insertion points: be they existing docstrings, or a place docstrings could be put. See below for an alternative. >> [There are some interesting issues here, such as foreign >> language docstrings. Why English?] > >Because only a handful of misfits speak Australian <wink>. 'viously, notu. ucntevn spell Strine right, mate. Youse'dseemorecrickt. -------------------- I've been thinking <woops!> about internationalisation. Really, a docstring should be a dictionary, keyed by language. There's another way to do this, however, which requires a bit of internal Python support and provides other advantages. Suppose, whenever an interned string literal was about to be used, it was looked up in a table for an equivalent in the users native language. If no equivalent is found, the original is used. But if one is found, it is substituted. For example: print "Hello",name will print "Guten morgen John" if the locale sets the native language to German, and the following function (or something like it) has been executed: set_equivalent_literal("English", "Hello", "German", "Guten morgen") The general idea is that you can write your program in your native language, and someone can provide a table of equivalents for one or more other languages -- not necessarily the author. With this idea, it should be possible to have docstrings in more than one language, even if the author only used their native language. It would also support 'internationalising' programs _without_ having to replace every literal in the program with a function call. This is only an idea! Hmm. Another idea. Just for docstrings. How about a special __get_docstring__ hook that would do the conversion for docstrings? In particular, it could lookup docstrings in places _other_ than the standard place (bound to the object). ------------------------------------------------------- John Skaller email: skaller(a)maxtal.com.au http://www.maxtal.com.au/~skaller phone: 61-2-96600850 snail: 10/1 Toxteth Rd, Glebe NSW 2037, Australia

1 0

Re: [Doc-SIG] An 'apropos' utility for documentations
by Fredrik Lundh Dec. 11, 1998

Dec. 11, 1998

>A Wiki would be a pretty good way to collect docstrings. > >http://c2.com/cgi/wiki?FrontPage in python, that's a "groupmind": http://starship.skyport.net/crew/scharf/GroupMind/GroupMind.cgi?req=home /F

2 1

Re: [Doc-SIG] An 'apropos' utility for documentations
by John Skaller Dec. 11, 1998

Dec. 11, 1998

At 13:26 9/12/98 -0500, Fred L. Drake wrote: >My response: > I think this would be really nice to have. As far as I'm aware, >such systems are still largely research projects, with some >applications having reached deployment (you point to good examples). >To do this for the Python documentation (defined as broadly as >needed), the most-needed thing to accomplish this is someone who can >donate time and know-how. I've been thinking for a while on the following somewhat related problem: a lot of library docstrings are missing. It's all very well for Guido to ask for patches, but this has to be the most inconvenient update mechanism around. And then I saw the TODO list Ken put up. Which is excellent! So, if there were a way to make an _online_ list of every function, class, and module in the library, with the current docstring, and allow everyone to add docstrings over the Internet, like the TODO list, we'd have more people able to make small contributions. [There are some interesting issues here, such as foreign language docstrings. Why English?] Anyhow, the same mechanism could help to build a Python 'thesarus', at least for the standard distribution. Do you have any idea how long it took me to find the function that copies files?? I knew it was there, somewhere. But the silly thing is called 'filecopy' not 'copyfile', <g> and it's hidden away in a module with an apparently unrelated name. 'shutils'. ------------------------------------------------------- John Skaller email: skaller(a)maxtal.com.au http://www.maxtal.com.au/~skaller phone: 61-2-96600850 snail: 10/1 Toxteth Rd, Glebe NSW 2037, Australia

3 2

Possible Howto gui, narrative functions in computer , sciences
by Manuel Gutierrez Algaba Dec. 10, 1998

Dec. 10, 1998

In www.ctv.es/USERS/irmina I've put the 'documentation' of my project Lritaunas Peki. Well, it's a very peculiar documentation. In fact, I've done it keeping in mind that it could be as a STRUCTURED-PROGRAMMING-HOWTO. I mean, I'd like you to take a look at it and that you tell me if it's worth as a HOWTO, or how could it be improved to become to a HOWTO ? It's not finished but I'd like your opinion. It illustrates the cicle of software programming. And it brings another interesting points. First one: Should all GUI program documentations be similar to Lritaunas Peki's ? I think so, because it's a very straight forward method of knowing how the programmer did the program and what were his thoughts and strategies. I mean it's documentation for Maintainers. Second point: Right now , we're discusing the posibility of making an advanced 'apropos' utility (in the doc list), so the documentation of python library/programs get much better. Well, doing this piece of documentation ( Lritaunas Peki ) I've realised something. Do you know what 'narrative functions' are ? Well, early in this century ( or in lates 1800 ) a Russian studied the traditional Russian stories and he found that they have a similar structure, in fact all they were composed of such functions as: initial-situation, unbalancing-action, balancing-action,... and so. If you think that the millions of the stories of the world are composed of such small set of things, then it makes me wonder that programs , specially GUI can be described in sets of computational functions. Well, what about start talking about ( for example in the context of Lritaunas ) : input-section , labels output-section, words transform-section, words, grammar direct-gui-section If we find such set, and we apply it to the improved-apropos idea, we can get all the functions of a class or of a program sorted by its role in the system. You could have a very direct idea, just reading how are placed this functions. Just think in a class with many functions, some of them will read the arguments of the class, some others will be internal interfaces in the own class. Some other just print results... As a matter of fact when we read a program we get that information, what about putting it explicity for higher level documentation programs? Regards/Saludos Manolo ------------- My addresses / mis direcciones: www.ctv.es/USERS/irmina ---> lritaunas peki project/proyecto in python www.ctv.es/USERS/irmina/pyttex.htm ---> page of spanish users of latex / pagina de usuarios en espanyol de latex www.ctv.es/USERS/irmina/texpython.htm --> page of drawing utility for tex / pagina de utilidad de dibujo para Latex "...abandoneis el campo y vuestras casas y acudais a defender el mar y la ciudad...no lamentarse por las casas o la tierra, sino por las vidas humanas, pues aquellas no nos proporcionan hombres, sino los hombres aquellas "-Pericles

1 0

An 'apropos' utility for documentations
by Manuel Gutierrez Algaba Dec. 9, 1998

Dec. 9, 1998

Dear folks, I'm a Linux user that always has a bad time when installing a new package or reading the mastodontic documentation that most programs include. This morning I have a simply idea that I'd like you to consider and to comment. Do you know Unix command 'apropos' ? Well, the idea is to do an apropos command ( written in python of course) containing all the 'concepts' and tips related with the documentation of a program. Exactly, imagine that your program can be installed in AIX, Linux, and MS-dos,and for every platform it needs certain procedures. Well, apart from a description in a README file with the differences. It'd be easy to build a database as: core_of_it.py : AIX, Linux, MS-DOS, config.py, ../bin/files, setup, structures, socket This information could be introduced on line by the author, or it could be generated automatically ( at least part of it ). The fields of the database could be grouped so more complex searchs could be done ... Or the fields themselves could be entries in the database. Is it already done ? Can any of the maintainers of documentation of programs consider this feature ? Do you think is useful ? Do you think is easy to do ? Regards/Saludos Manolo ------------- My addresses / mis direcciones: www.ctv.es/USERS/irmina ---> lritaunas peki project/proyecto in python www.ctv.es/USERS/irmina/pyttex.htm ---> page of spanish users of latex / pagina de usuarios en espanyol de latex www.ctv.es/USERS/irmina/texpython.htm --> page of drawing utility for tex / pagina de utilidad de dibujo para Latex

3 4