[Python-Dev] Which doc is authoritative? [was: Deprecating string exceptions]

...

...

...

...

"Skip" == Skip Montanaro writes:

Skip> I'd then advocate that the module doc string simply refer to Skip> the libref docs for the hierarchy. Except that as I understand it, the libref docs are separate from the sources, and written in a different language. I know that Emacs and XEmacs manuals are continuously different from the docstrings, and the docstrings are usually more accurate for two reasons: (1) The docstrings are written by people who have just implemented the behavior described, in a form which does not require shifting mental gears. {C,Lisp} -> Texinfo is hard to get right. Requires validating-by-doc-build, so, ok, I can do that later<wink>. (2) Docstrings are a perfect forum for the "many eyes" to make small contributions, and we get a lot of them. It is counterproductive to say "this is no good without a corresponding Texinfo patch." NB. Unlike Emacs Lisp, whose definition is "emergent" from the development process, Python (as I understand it) has a more formal definition process, even for the libraries. So Skip has a good solid theoretical basis for his position IMHO. just-trying-to-confuse-you-with-facts-ly y'rs -- Institute of Policy and Planning Sciences http://turnbull.sk.tsukuba.ac.jp University of Tsukuba Tennodai 1-1-1 Tsukuba 305-8573 JAPAN Don't ask how you can "do" free software business; ask what your business can "do for" free software.