Mailman 3 March 2002 - Doc-SIG

Error in pyexpat docs
by uche.ogbuji＠fourthought.com July 9, 2002

July 9, 2002

An excerpt from the Python 2.0 docs for pyexpat: """ ParseFile (file) Parse XML data reading from the object file. file only needs to provide the read(nbytes) method, returning the empty string when there's no more data. [snip] The following attributes contain values relating to the most recent error encountered by an xmlparser object, and will only have correct values once a call to Parse() or ParseFile() has raised a xml.parsers.expat.error exception. ErrorByteIndex Byte index at which an error occurred. [etc.] """ The wrong, "xml.parsers.expat" is the first indicator that there might be a problem, yet I took the docs at their word and wrapped the call to ParseFile in a blanket try/except, only to find that no exception of any sort is ever raised by ParseFile. It turns out that ParseFile actually returns 0 on error, returning 1 otherwise. The first matter is that the code and the docs need to be reconciled. However, I would _much_ rather prefer that things were as in the docs. I think ParseFile should raise an exception rather than return an error flag. Interestingly enough, this is the same argument I had with a colleague just last week. -- Uche Ogbuji Principal Consultant uche.ogbuji(a)fourthought.com +1 303 583 9900 x 101 Fourthought, Inc. http://Fourthought.com 4735 East Walnut St, Ste. C, Boulder, CO 80301-2537, USA Software-engineering, knowledge-management, XML, CORBA, Linux, Python

3 2

[��] �� ྲ�� Ұ�
by slrlfl2000 March 30, 2002

March 30, 2002

1 0

[development doc updates]
by Fred L. Drake March 29, 2002

March 29, 2002

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ Started to update the Extending & Embedding manual with information on the new support for types. There's still a long way to go -- contributions welcome!

2 1

"Don't Kill Opera" documentation release
by Fred L. Drake, Jr. March 29, 2002

March 29, 2002

I've just made an "emergency" release of the 2.2 documentation (based on the release22-maint branch in CVS. If you use Opera 6.01, you can now feel a little safer on python.org. ;-) -Fred -- Fred L. Drake, Jr. <fdrake at acm.org> PythonLabs at Zope Corporation

1 0

New PEP: reStructuredText Standard Docstring Format
by David Goodger March 28, 2002

March 28, 2002

Please comment on this new PEP. I intend to post it to comp.lang.python & python-dev later this week, but wanted the Doc-SIG's reaction first. Any chance at consensus? Do the "docstring format goals" truly reflect the goals of the group? Any questions or answers to add to the Q & A? Any glaring omissions? Barry, could I get a PEP number please? Thank you. -- David Goodger goodger(a)users.sourceforge.net Open-source projects: - Python Docstring Processing System: http://docstring.sourceforge.net - reStructuredText: http://structuredtext.sourceforge.net - The Go Tools Project: http://gotools.sourceforge.net PEP: Title: reStructuredText Standard Docstring Format Version: $Revision$ Last-Modified: $Date$ Author: goodger(a)users.sourceforge.net (David Goodger) Discussions-To: doc-sig(a)python.org Status: Draft Type: Informational Created: 2002-03-25 Post-History: Abstract This PEP proposes that the reStructuredText [1]_ markup be adopted as the standard markup format for plaintext documentation in Python docstrings, and (optionally) for PEPs and ancillary documents as well. reStructuredText is a rich and extensible yet easy-to-read, what-you-see-is-what-you-get plaintext markup syntax. Only the low-level syntax of docstrings is addressed here. This PEP is not concerned with docstring semantics or processing at all. Goals These are the generally accepted goals for a docstring format, as discussed in the Python Documentation Special Interest Group (Doc-SIG) [2]_: 1. It must be easy to type with any standard text editor. 2. It must be readable to the casual observer. 3. It must not need to contain information which can be deduced from parsing the module. 4. It must contain sufficient information (structure) so it can be converted to any reasonable markup format. 5. It must be possible to write a module's entire documentation in docstrings, without feeling hampered by the markup language. [[Are these in fact the goals of the Doc-SIG members? Anything to add?]] reStructuredText meets and exceeds all of these goals, and sets its own goals as well, even more stringent. See "Features" below. The goals of this PEP are as follows: 1. To establish a standard docstring format by attaining "accepted" status (Python community consensus; BDFL pronouncement). Once reStructuredText is a Python standard, all effort can be focused on tools instead of arguing for a standard. Python needs a standard set of documentation tools. 2. To address any related concerns raised by the Python community. 3. To encourage community support. As long as multiple competing markups are out there, the development community remains fractured. Once a standard exists, people will start to use it, and momentum will inevitably gather. 4. To consolidate efforts from related auto-documentation projects. It is hoped that interested developers will join forces and work on a joint/merged/common implementation. 5. (Optional.) To adopt reStructuredText as the standard markup for PEPs. One or both of the following strategies may be applied: a) Keep the existing PEP section structure constructs (one-line section headers, indented body text). Subsections can either be forbidden or supported with underlined headers in the indented body text. b) Replace the PEP section structure constructs with the reStructuredText syntax. Section headers will require underlines, subsections will be supported out of the box, and body text need not be indented (except for block quotes). Support for RFC822 headers will be added to the reStructuredText parser (unambiguous given a specific context: the first contiguous block of a PEP document). It may be desired to concretely specify what over/underline styles are allowed for PEP section headers, for uniformity. 6. (Optional.) To adopt reStructuredText as the standard markup for README-type files and other standalone documents in the Python distribution. Rationale The __doc__ attribute is called a documentation string, or docstring. It is often used to summarize the interface of the module, class or function. The lack of a standard syntax for docstrings has hampered the development of standard tools for extracting docstrings and transforming them into documentation in standard formats (e.g., HTML, DocBook, TeX). There have been a number of proposed markup formats and variations, and many tools tied to these proposals, but without a standard docstring format they have failed to gain a strong following and/or floundered half-finished. The adoption of a standard will, at the very least, benefit docstring processing tools by preventing further "reinventing the wheel". Throughout the existence of the Doc-SIG, consensus on a single standard docstring format has never been reached. A lightweight, implicit markup has been sought, for the following reasons (among others): 1. Docstrings written within Python code are available from within the interactive interpreter, and can be 'print'ed. Thus the use of plaintext for easy readability. 2. Programmers want to add structure to their docstrings, without sacrificing raw docstring readability. Unadorned plaintext cannot be transformed ('up-translated') into useful structured formats. 3. Explicit markup (like XML or TeX) is widely considered unreadable by the uninitiated. 4. Implicit markup is aesthetically compatible with the clean and minimalist Python syntax. Proposed alternatives have included: - XML [3]_, SGML [4]_, DocBook [5]_, HTML [6]_, XHTML [7]_ XML and SGML are explicit, well-formed meta-languages suitable for all kinds of documentation. XML is a variant of SGML. They are best used behind the scenes, because they are verbose, difficult to type, and too cluttered to read comfortably as source. DocBook, HTML, and XHTML are all applications of SGML and/or XML, and all share the same basic syntax and the same shortcomings. - TeX [8]_ TeX is similar to XML/SGML in that it's explicit, not very easy to write, and not easy for the uninitiated to read. - Perl POD [9]_ Most Perl modules are documented in a format called POD -- Plain Old Documentation. This is an easy-to-type, very low level format with strong integration with the Perl parser. Many tools exist to turn POD documentation into other formats: info, HTML and man pages, among others. However, the POD syntax takes after Perl itself in terms of readability. - JavaDoc [10]_ Special comments before Java classes and functions serve to document the code. A program to extract these, and turn them into HTML documentation is called javadoc, and is part of the standard Java distribution. However, the only output format that is supported is HTML, and JavaDoc has a very intimate relationship with HTML, using HTML tags for most markup. Thus it shares the readability problems of HTML. - Setext [11]_, StructuredText [12]_ Early on, variants of Setext (Structure Enhanced Text), including Zope Corp's StructuredText, were proposed for Python docstring formatting. Hereafter these variants will collectively be call 'STexts'. STexts have the advantage of being easy to read without special knowledge, and relatively easy to write. Although used by some (including in most existing Python auto-documentation tools), until now STexts have failed to become standard because: - STexts have been incomplete. Lacking "essential" constructs that people want to use in their docstrings, STexts are rendered less than ideal. Note that these "essential" constructs are not universal; everyone has their own requirements. - STexts have been sometimes surprising. Bits of text are marked up unexpectedly, leading to user frustration. - SText implementations have been buggy. - Most STexts have have had no formal specification except for the implementation itself. A buggy implementation meant a buggy spec, and vice-versa. - There has been no mechanism to get around the SText markup rules when a markup character is used in a non-markup context. Proponents of implicit STexts have vigorously opposed proposals for explicit markup (XML, HTML, TeX, POD, etc.), and the debates have continued off and on since 1996 or earlier. reStructuredText is a complete revision and reinterpretation of the SText idea, addressing all of the problems listed above. Features Rather than repeating or summarizing the extensive reStructuredText spec, please read the originals available from http://structuredtext.sourceforge.net/spec/ (.txt & .html files). Reading the documents in following order is recommended: - An Introduction to reStructuredText [13]_ - Problems With StructuredText [14]_ (optional, if you've used StructuredText; it explains many markup decisions made) - reStructuredText Markup Specification [15]_ - A Record of reStructuredText Syntax Alternatives [16]_ (explains markup decisions made independently of StructuredText) - reStructuredText Directives [17]_ There is also a "Quick reStructuredText" user reference [18]_. A summary of features addressing often-raised docstring markup concerns follows: - A markup escaping mechanism. Backslashes (``\``) are used to escape markup characters when needed for non-markup purposes. However, the inline markup recognition rules have been constructed in order to minimize the need for backslash-escapes. For example, although asterisks are used for *emphasis*, in non-markup contexts such as "*" or "(*)" or "x * y", the asterisks are not interpreted as markup and are left unchanged. For many non-markup uses of backslashes (e.g., describing regular expressions), inline literals or literal blocks are applicable; see the next item. - Markup to include Python source code and Python interactive sessions: inline literals, literal blocks, and doctest blocks. Inline literals use ``double-backquotes`` to indicate program I/O or code snippets. No markup interpretation (including backslash-escape [``\``] interpretation) is done within inline literals. Literal blocks (block-level literal text, such as code excerpts or ASCII graphics) are indented, and indicated with a double-colon ("::") at the end of the preceding paragraph (right here -->):: if literal_block: text = 'is left as-is' spaces_and_linebreaks = 'are preserved' markup_processing = None Doctest blocks begin with ">>> " and end with a blank line. Neither indentation nor literal block double-colons are required. For example:: Here's a doctest block: >>> print 'Python-specific usage examples; begun with ">>>"' Python-specific usage examples; begun with ">>>" >>> print '(cut and pasted from interactive sessions)' (cut and pasted from interactive sessions) - Markup that isolates a Python identifier: interpreted text. Text enclosed in single backquotes is recognized as "interpreted text", whose interpretation is application-dependent. In the context of a Python docstring, the default interpretation of interpreted text is as Python identifiers. The text will be marked up with a hyperlink connected to the documentation for the identifier given. Lookup rules are the same as in Python itself: LGB namespace lookups (local, global, builtin). The "role" of the interpreted text (identifying a class, module, function, etc.) is determined implicitly from the namespace lookup. For example:: class Keeper(Storer): """ Extend `Storer`. Class attribute `instances` keeps track of the number of `Keeper` objects instantiated. """ instances = 0 """How many `Keeper` objects are there?""" def __init__(self): """ Extend `Storer.__init__()` to keep track of instances. Keep count in `self.instances` and data in `self.data`. """ Storer.__init__(self) self.instances += 1 self.data = [] """Store data in a list, most recent last.""" def storedata(self, data): """ Extend `Storer.storedata()`; append new `data` to a list (in `self.data`). """ self.data = data Each piece of interpreted text is looked up according to the local namespace of the block containing its docstring. - Markup that isolates a Python identifier and specifies its type: interpreted text with roles. Although the Python source context reader is designed not to require explicit roles, they may be used. To classify identifiers explicitly, the role is given along with the identifier in either prefix or suffix form:: Use :method:`Keeper.storedata` to store the object's data in `Keeper.data`:instance_attribute:. The syntax chosen for roles is verbose, but necessarily so (if anyone has a better alternative, please post it to the Doc-SIG). The intention of the markup is that there should be little need to use explicit roles; their use is to be kept to an absolute minimum. - Markup for "tagged lists" or "label lists": field lists. Field lists represent a mapping from field name to field body. These are mostly used for extension syntax, such as "bibliographic field lists" (representing document metadata such as author, date, and version) and extension attributes for directives (see below). They may be used to implement docstring semantics, such as identifying parameters, exceptions raised, etc.; such usage is beyond the scope of this PEP. A modified RFC822 syntax is used, with a colon *before* as well as *after* the field name. Field bodies are more versatile as well; they may contain multiple field bodies (even nested field lists). For example:: :Date: 2002-03-22 :Version: 1 :Authors: - Me - Myself - I Standard RFC822 header syntax cannot be used for this construct because it is ambiguous. A word followed by a colon at the beginning of a line is common in written text. However, with the addition of a well-defined context, such as when a field list invariably occurs at the beginning of a document (e.g., PEPs and email messages), standard RFC822 header syntax can be used. - Markup extensibility: directives and substitutions. Directives are used as an extension mechanism for reStructuredText, a way of adding support for new block-level constructs without adding new syntax. Directives for images, admonitions (note, caution, etc.), and tables of contents generation (among others) have been implemented. For example, here's how to place an image:: .. image:: mylogo.png Substitution definitions allow the power and flexibility of block-level directives to be shared by inline text. For example:: The |biohazard| symbol must be used on containers used to dispose of medical waste. .. |biohazard| image:: biohazard.png - Section structure markup. Section headers in reStructuredText use adornment via underlines (and possibly overlines) rather than indentation. For example:: This is a Section Title ======================= This is a Subsection Title -------------------------- This paragraph is in the subsection. This is Another Section Title ============================= This paragraph is in the second section. Questions & Answers Q: Is reStructuredText rich enough? A: Yes, it is for most people. If it lacks some construct that is require for a specific application, it can be added via the directive mechansism. If a common construct has been overlooked and a suitably readable syntax can be found, it can be added to the specification and parser. Q: Is reStructuredText *too* rich? A: No. Since the very beginning, whenever a markup syntax has been proposed on the Doc-SIG, someone has complained about the lack of support for some construct or other. The reply was often something like, "These are docstrings we're talking about, and docstrings shouldn't have complex markup." The problem is that a construct that seems superfluous to one person may be absolutely essential to another. reStructuredText takes the opposite approach: it provides a rich set of implicit markup constructs (plus a generic extension mechanism for explicit markup), allowing for all kinds of documents. If the set of constructs is too rich for a particular application, the unused constructs can either be removed from the parser (via application-specific overrides) or simply omitted by convention. Q: Why not use indentation for section structure, like StructuredText does? Isn't it more "Pythonic"? A: Guido van Rossum wrote the following in a 2001-06-13 Doc-SIG post: I still think that using indentation to indicate sectioning is wrong. If you look at how real books and other print publications are laid out, you'll notice that indentation is used frequently, but mostly at the intra-section level. Indentation can be used to offset lists, tables, quotations, examples, and the like. (The argument that docstrings are different because they are input for a text formatter is wrong: the whole point is that they are also readable without processing.) I reject the argument that using indentation is Pythonic: text is not code, and different traditions and conventions hold. People have been presenting text for readability for over 30 centuries. Let's not innovate needlessly. See "Section Structure via Indentation" in "Problems With StructuredText" [14 ]_ for further elaboration. Q: Why use reStructuredText for PEPs? What's wrong with the existing standard? A: The existing standard for PEPs is very limited in terms of general expressibility, and referencing is especially lacking for such a reference-rich document type. PEPs are currently converted into HTML, but the results (mostly monospaced text) are less than attractive, and most of the value-added potential of HTML is untapped. Making reStructuredText the standard markup for PEPs will enable much richer expression, including support for section structure, inline markup, graphics, and tables. In several PEPs there are ASCII graphics diagrams, which are all that plaintext documents can support. Since PEPs are made available in HTML form, the ability to include proper diagrams would be immediately useful. Current PEP practices allow for reference markers in the form "[1]" in the text, and the footnotes/references themselves are listed in a section toward the end of the document. There is currently no hyperlinking between the reference marker and the footnote/reference itself (it would be possible to add this to pep2html.py, but the "markup" as it stands is ambiguous and mistakes would be inevitable). A PEP with many references (such as this one ;-) requires a lot of flipping back and forth. When revising a PEP, often new references are added or unused references deleted. It is painful to renumber the references, since it has to be done in two places and can have a cascading effect (insert a single new reference 1, and every other reference has to be renumbered; always adding new references to the end is suboptimal). It is easy for references to go out of sync. PEPs use references for two purposes: simple URL references and footnotes. reStructuredText differentiates between the two. A PEP might contain references like this:: Abstract This PEP proposes a adding frungible doodads [1] to the core. It extends PEP 9876 [2] via the BCA [3] mechanism. References and Footnotes [1] http://www.doodads.org/frungible.html [2] PEP 9876, Let's Hope We Never Get Here http://www.python.org/peps/pep-9876.html [3] "Bogus Complexity Addition" Reference 1 is a simple URL reference. Reference 2 is a footnote containing text and a URL. Reference 3 is a footnote containing text only. Rewritten using reStructuredText, this PEP could look like this:: Abstract ======== This PEP proposes a adding `frungible doodads`_ to the core. It extends PEP 9876 [#pep9876] via the BCA [#] mechanism. .. _frungible doodads: http://www.doodads.org/frungible.html .. [#pep9876] `PEP 9876`__, Let's Hope We Never Get Here __ http://www.python.org/peps/pep-9876.html .. [#] "Bogus Complexity Addition" URLs and footnotes can be defined close to their references if desired, making them easier to read in the source text, and making the PEPs easier to revise. The "References and Footnotes" section can be auto-generated with a document tree transform. Footnotes from throughout the PEP would be gathered and displayed under a standard header. If URL references should likewise be written out explicitly (in citation form), another tree transform could be used. URL references can be named ("frungible doodads"), and can be referenced from multiple places in the document without additional definitions. When converted to HTML, references will be replaced with inline hyperlinks (HTML <A> tags). The two footnotes are automatically numbered, so they will always stay in sync. The first footnote also contains an internal reference name, "pep9876", so it's easier to see the connection between reference and footnote in the source text. Named footnotes can be referenced multiple times, maintaining consistent numbering. The "#pep9876" footnote could also be written in the form of a citation:: It extends PEP 9876 [PEP9876]_ ... .. [PEP9876] `PEP 9876`_, Let's Hope We Never Get Here Footnotes are numbered, whereas citations use text for their references. Q: Wouldn't it be better to keep the docstring and PEP proposals separate? A: The PEP markup proposal is an option to this PEP. It may be removed if it is deemed that there is no need for PEP markup. The PEP markup proposal could be made into a separate PEP if necessary. If accepted, PEP 1, PEP Purpose and Guidelines [19]_, and PEP 9, Sample PEP Template [20]_ will be updated. It seems natural to adopt a single consistent markup standard for all uses of plaintext in Python. Q: The existing pep2html.py script converts the existing PEP format to HTML. How will the new-format PEPs be converted to HTML? A: One of the deliverables of the Docutils project [21]_ will be a new version of pep2html.py with integrated reStructuredText parsing. The Docutils project will support PEPs with a "PEP Reader" component, including all functionality currently in pep2html.py (auto-recognition of PEP & RFC references). Q: Who's going to convert the existing PEPs to reStructuredText? A: A call for volunteers will be put out to the Doc-SIG and greater Python communities. If insufficient volunteers are forthcoming, I (David Goodger) will convert the documents myself, perhaps with some level of automation. A transitional system whereby both old and new standards can coexist will be easy to implement (and I pledge to implement it if necessary). Q: Why use reStructuredText for README and other ancillary files? A: The same reasoning used for PEPs above applies to README and other ancillary files. By adopting a standard markup, these files can be converted to attractive cross-referenced HTML and put up on python.org. Developers of Python projects can also take advantage of this facility for their own documentation. References and Footnotes [1] http://structuredtext.sourceforge.net/ [2] http://www.python.org/sigs/doc-sig/ [3] http://www.w3.org/XML/ [4] http://www.oasis-open.org/cover/general.html [5] http://docbook.org/tdg/en/html/docbook.html [6] http://www.w3.org/MarkUp/ [7] http://www.w3.org/MarkUp/#xhtml1 [8] http://www.tug.org/interest.html [9] http://www.perldoc.com/perl5.6/pod/perlpod.html [10] http://java.sun.com/j2se/javadoc/ [11] http://docutils.sourceforge.net/mirror/setext.html [12] http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage [13] An Introduction to reStructuredText http://structuredtext.sourceforge.net/spec/introduction.txt [14] Problems with StructuredText http://structuredtext.sourceforge.net/spec/problems.txt [15] reStructuredText Markup Specification http://structuredtext.sourceforge.net/spec/reStructuredText.txt [16] A Record of reStructuredText Syntax Alternatives http://structuredtext.sourceforge.net/spec/alternatives.txt [17] reStructuredText Directives http://structuredtext.sourceforge.net/spec/directives.txt [18] Quick reStructuredText http://structuredtext.sourceforge.net/docs/quickref.html [19] PEP 1, PEP Guidelines, Warsaw, Hylton http://www.python.org/peps/pep-0001.html [20] PEP 9, Sample PEP Template, Warsaw http://www.python.org/peps/pep-0009.html [21] http://docutils.sourceforge.net/ [22] PEP 216, Docstring Format, Zadka http://www.python.org/peps/pep-0216.html Copyright This document has been placed in the public domain. Acknowledgements Some text is borrowed from PEP 216, Docstring Format, by Moshe Zadka [22]_. Special thanks to all members past & present of the Python Doc-SIG. Local Variables: mode: indented-text indent-tabs-mode: nil sentence-end-double-space: t fill-column: 70 End:

3 5

RE: New PEP: reStructuredText Standard Docstring Format
by Moore, Paul March 28, 2002

March 28, 2002

(Third try at this - I'm groping for a way to express my point here...) I only really have one issue with the document, which is that it reads a little too much like it's trying to be the "how to write your comments" section of a programming standard. Wait - before you start throwing rocks at me, let me explain... As I was reading it, I had no complaint with any of the details, but there was this nagging feeling in the back of my mind saying "Why should I agree to these rules? Even Guido doesn't have the right to tell *me* how to write my documentation!" There isn't enough emphasis on why using reST in my docstrings provides *me* with benefit. At the end of the day, we're all pretty selfish about how we write our code - we document the bits we think we, personally, might not understand later, and we excuse the areas where we skip documentation with the excuse that "it's obvious". (OK, maybe it's just me - but I suspect most people have a little bit of this attitude) I'd suggest that you add a "Benefits" section, explaining the advantages to the individual programmer - *not* to the community as a whole - of the proposal. My characterisation of the benefits would be: - The proposed format (reST) is entirely readable in plaintext format, and many of the markup forms match common usage (e.g., ``*emphasis*``), so there is no significant downside to using it (beyond the initial learning curve) [1]_ - Tools will become available in the (hopefully near) future, which will allow me to generate HTML for online help, and PDF/DocBook/LaTeX (?) for printed documentation, essentially "for free" from the existing docstrings. [2]_ - Other automated tools will understand my documentation strings, and be able to respect my formatting requirements [3]_ .. [1] Actually, it's arguable that the similarity to "existing practice" makes getting the syntax right *harder*. I never get footnote syntax right without checking (and I may have got this lot wrong!) This may be because of all the recent changes, but it is still something that probably needs covering in a Q&A. "Q: Won't the superficial similarity to existing markup conventions cause problems, and result in people writing invalid markup (and not noticing, because the plaintext looks natural)?" .. [2] It's pretty important *not* to give the impression that these tools could be "vapourware". People are cynical... .. [3] This one's vague - I'm sort of thinking about pydoc. Interestingly (and possibly relevantly) it's not clear to me that these benefits are overwhelming. It's more a case of the cost being minimal [4]_, and the potential benefits being reasonable. Maybe we need to focus more strongly on getting tools working. Something on the level of "look - I generated a help file and some printed documentation, and pydoc produces well-formatted information - all without doing anything more than using reST in my docstrings". People respond better to demonstrations than to standards... .. [4] Which argues that people may well end up only using subsets of the full reST spec - just the bits they remember or find particularly hard to express any other way [5]_ ... .. [5] So we need to consider how the dps will cope with the sort-of reST which may be written by (for example) someone who didn't know that reST had a table construct, and just typed in a table in a "natural" ASCII-art form. In other words, how forgiving is reST going to be of "not quite right" constructs? I know the tools are coming (and I'm not doing much to help, so I shouldn't criticise). But I'm a little concerned that a standard without supporting "gee whizz" tools could turn some people off the idea, rather than generating enthusiasm... Paul. PS I just noticed that I manually numbered the footnotes in this message - even though I needed to renumber at one point. In practice, I don't think I'd ever use the ``[#]`` notation for auto-numbering. It's too hard to follow in "raw text" form. Just a data point...

3 3

Re: [Doc-SIG] New PEP: reStructuredText Standard Docstring Format
by Johannes L. Gijsbers March 27, 2002

March 27, 2002

> I shoulda known that *someone* would try out that URL. > And I shoulda guessed that such a site exists. I've > changed it to www.frungible-doodads.org. > > Is there a URL equivalent of a 555-prefix telephone > number? One that's guaranteed *not* to exist, therefore > safe to use in examples, movies, and TV shows? Actually, there is. Check http://www.example.com. There was someone before you who thought of this, it even made it into RFC2606. jlg _____________________________________________________________________ // free anonymous email || forums \\ subZINE || anonymous browsing subDIMENSION -- http://www.subdimension.com

1 0

[development doc updates]
by Fred L. Drake March 26, 2002

March 26, 2002

The development version of the documentation has been updated: http://python.sourceforge.net/devel-docs/ Minor update; shows how the "What's New" document is linked in.

1 0

[development doc updates]
by Fred L. Drake March 25, 2002

March 25, 2002

The development version of the documentation has been updated: http://python.sourceforge.net/maint-docs/ Documentation for Python 2.2.1 release candidate 2.

1 0

[development doc updates]
by Fred L. Drake March 24, 2002

March 24, 2002

The development version of the documentation has been updated: http://python.sourceforge.net/csstest-docs/ This is the experimental formatting for the documentation. This version should work better for Opera users; it should work fine for Opera 6, and works (slightly) better than it did for Opera 5. There's probably no change for other browsers.

1 0