> Did my suggestion to alter pydoc output so it always contains a link to the
> enclosing module's documentation not seem like a reasonable compromise?

I actually don't understand how that would help.  The ``pydoc time`` output doesn't include any information about the formatting codes (at least, on my system).

Also, ``pydoc`` isn't available on Windows systems, is it?  It isn't on mine; is that a quirk of my setup?

> Another problem with embedding the format codes in the docstring is that it
> opens up a Pandora's box of other stuff that might be reasonable to include
> in other docstrings, but should probably just be documented in one place
> (perhaps with references elsewhere).  For example, maybe we should add the
> list of signals to the docstrings for signal.signal and os.kill (pretty
> platform-dependent) or add all the format possibilities to the docstring for
> the format() builtin (brand new and probably not well-known to very many
> users).  I'm sure there are other candidates.  It can be difficult to know
> where to draw the line.

Yes, certainly, in one place - but isn't it logical for the docstring to be that one place?  Universal convenient access, and the least risk that it will get out of synch with the code.

Here's where I would suggest drawing the line: if the method is unusable without the information, and it's not easy to guess or remember, and it's relatively concise, it should be in the docstring.

Is that a Pandora's box or a set of good suggestions?  :)  Probably not stuff that is strongly platform-dependent, but for format(), for example, I think that's a good idea.  I don't think there's anything wrong with setting a precedent that could lead to more useful docstrings in several different places.

Anyway, I would settle for a suggestion in the docstring to run ``man strftime``, but only if there's some Windows equivalent; does anybody know of one?