Hi. The recent flamewar on c.l.py about lack of man pages got me thinking about a new "backend" for Python documentation, which would reflect Python's nature, while being amenable for auto-processing. The basic format would be POD (Perl's plain old documentation format), which is quite easy to parse. The Pythonic namespace hierarchy (package->module->object->methods) could be reflected in directory structure I.e., urllib/ ---.pod (general information about the module) urlopen.pod URLOpener/ ---.pod (general information about the class) __init__.pod (description of init method) Then, use of pod2man/pod2text with appropriate wrapping would mean I could have pythondoc urllib (show urllib/---.pod) pythondoc urllib.URLOpener.__init__ (show urllib/URLOpener/__init__.pod) I would be all-to-happy in helping to write such a back-end, we just need to make sure 1. The front-end is stable, and easily parsable (SGML ain't, XML is) 2. The front-end has enough information to do that easily (not really sure) What do you think? A preliminary module to make genereating PODS look just like generating XML (so the convertor would be written the way XML->XML translators are written) is in http://starship.python.net/crew/moshez/POD.py (It's not thoroughly debugged, but it passed the simple _test() well enough) -- Moshe Zadka <mzadka@geocities.com>. I'm not anti-Microsoft -- Microsoft is anti-me (Anonymous Coward on /.)
Moshe> The basic format would be POD (Perl's plain old documentation Moshe> format), which is quite easy to parse. The Pythonic namespace Moshe> hierarchy (package->module->object->methods) could be reflected Moshe> in directory structure ... Moshe> I would be all-to-happy in helping to write such a back-end, ... ... Moshe> What do you think? In theory, it's a reasonable proposal, however I worry about having yet another place to write documentation. For module docs we currently have the library ref manual and the inline doc strings. For your proposal to fly, not only would you have to be a strong motivating force in getting it implemented, it would have to replace one of the other current documentation formats somehow. Skip Montanaro | http://www.mojam.com/ skip@mojam.com | http://www.musi-cal.com/~skip/ 847-971-7098
On Fri, 20 Aug 1999, Skip Montanaro wrote:
In theory, it's a reasonable proposal, however I worry about having yet another place to write documentation. For module docs we currently have the library ref manual and the inline doc strings. For your proposal to fly, not only would you have to be a strong motivating force in getting it implemented, it would have to replace one of the other current documentation formats somehow.
Reread the proposal. I'm talking about automatic conversion from the nativ Python format. My proposal is horrible for native writing of documentation, just like info. -- Moshe Zadka <mzadka@geocities.com>. I'm not anti-Microsoft -- Microsoft is anti-me (Anonymous Coward on /.)
participants (2)
-
Moshe Zadka -
Skip Montanaro