Let me introduce myself. I am an experienced programmer with a plethora of languages under my belt (C/C++, Pascal, the dreaded BASIC, Lisp/Scheme, Perl, csh/ksh/bash scripting, AppleScript, and others in passing). I delved into Python about a year ago, and loved it. I have 3 years intense experience in an SGML analysis/design/processing environment. I have been reading the Doc SIG digests for about a week, plus some back issues from the archive. Please forgive me if I cover old ground. I am about to release a set of (relatively small) open-source libraries & tools. I have been using the docstring mechanism for internal documentation all along, and was delighted to find there were tools available to extract & mark up docstrings into something usable as documentation. Imagine my relief when I learned that I didn't *have* to use TeX if I wanted to use standard tools! As a newbie, without any affiliation to one approach or another, I thought I'd give you some opinions about the current docstring discussions. Please take it as a vote from a typical (atypical?) member of the intended audience. No offense to anyone is intended (nor, I hope, taken). They take a little getting used to, but the rules of Structured Text (as at http://www.python.org/sigs/doc-sig/stext.html) are easy to apply. I wouldn't want to see much more tagging than this, however. I use docstrings as working documentation, to be written in parallel with (ok, slightly *after*) writing the code. And I refer to this documentation also, so it **must** be readable (see? I'm already using the StructText conventions!). The docstring documentation (as output by the tools) would only be a start for final publication-quality documentation, however, so I'm not worried about lack of fine-tweaking control. HTML is great for quick & dirty user documentation or for on-screen display, but its formatting-oriented tagging makes it next to useless for anything more ambitious. I am pleased to hear that an effort is underway to create an SGML/XML DTD, a la DocBook (PyBook?) or whatever. Specifics: - I would not use any kind of [tag content] or tag[content] or <tag/content/ explicit tagging. It's too confusing when reading the code itself. It's a fine line that must not be crossed if this docstring proposal is going to be used widely. - I do like the output of Ka-Ping Yee's manpy very much (colouring aside :-). When will it be available? This is what I call "usable" documentation. Little more is needed at this level. - Edward Welbourne's example (below) makes sense to me. Using quotes as implicit "code" tagging would interfere with using them as explicit content, and I don't see a better candidate than # on my keyboard. However, I am uncomfortable with the "!" (exclamation point). Is there a reason why ":" (colon) shouldn't be used? I think "mode : string" looks a lot more natural. Arguments: mode ! string -- the file access mode string ... If #mode#'s first letter is #'r'#, #file# must exist. -- David Goodger (pronounced as in "badger", but good) dgoodger@bigfoot.com