Docutils/reStructuredText is ready to process PEPs
Python-developers, Pursuant to PEP 287, one of the deliverables of the just-released Docutils 0.2 (http://docutils.sf.net/) is a processing system for reStructuredText-format PEPs as an alternative to the current PEP processing. Here are examples of new-style PEPs (processed to HTML, with links to the source text as usual): - http://docutils.sf.net/spec/pep-0287.html (latest) - http://docutils.sf.net/spec/pep-0000.html (as a proof of concept because of its special processing) Compare to the old-style PEPs: - http://www.python.org/peps/pep-0287.html (update pending) - http://www.python.org/peps/pep-0000.html Existing old-style PEPs can coexist with reStructuredText PEPs indefinitely. What to do with new PEPs is a policy decision that doesn't have to be made immediately. PEP 287 puts forward a detailed rationale for reStructuredText PEPs; especially see the "Questions & Answers" section, items 4 through 7. In earlier correspondence Guido critiqued some style issues (since corrected) and said "I'm sure you can fix all these things with a simple style sheet change, and then I'm all for allowing Docutils for PEPs." I'd appreciate more critiques/suggestions on PEP formatting issues, no matter how small. Especially, please point out any HTML/stylesheet issues with the various browsers. I hereby formally request permission to deploy Docutils for PEPs on Python.org. Here's a deployment plan for your consideration: - Install the Docutils-modified version of Fredrik Lundh's nondist/peps/pep2html.py script into CVS, along with ancillary files. The modified pep2html.py auto-detects old-style and new-style PEPs and processes accordingly. (http://docutils.sf.net/tools/pep2html.py) - Install Docutils 0.2 on the server that does the PEP processing. I don't think it's necessary to put Docutils into Python's CVS. - Make up a README for the "peps" directory with instructions for installing Docutils and running the modified pep2html.py. - Modify PEP 1 (PEP Purpose and Guidelines) and PEP 9 (Sample PEP Template) with the new formatting instructions. - Make an announcement to the Python community. - I will maintain the software, convert current meta-PEPs to the new format as desired, handle PEP conversion updates, and assist other PEP authors to convert their PEPs if they wish. If this is acceptable, to begin I will need write access to CVS and shell access to the Python.org server (however that works; please let me know what I need to do). Once I have the necessary access, I will try to ensure a near-zero impact on the PythonLabs crew. Feedback is most welcome. -- David Goodger <goodger@users.sourceforge.net> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/
On Wed, 31 Jul 2002, David Goodger wrote:
I hereby formally request permission to deploy Docutils for PEPs on Python.org. Here's a deployment plan for your consideration:
I have just read the specification: http://docutils.sourceforge.net/spec/rst/reStructuredText.html It took a long time. Perhaps it seems not so big to others, but my personal opinion would be to recommend against this proposal until the specification fits in, say, 1000 lines and can be absorbed in ten minutes. For me, it violates the fits-in-my-brain principle: the spec is 2500 lines long, and supports six different kinds of references and five different kinds of lists (even lists with roman numerals!). It also violates the one-way-to-do-it principle: for example, there are a huge variety of ways to do headings, and two different syntaxes for drawing a table. I am not against structured text processing systems in general. I think that something of this flavour would be a great solution for PEPs and docstrings, and that David has done an impressive job on RST. It's just that RST is much too big (for me). -- ?!ng "This code is better than any code that doesn't work has any right to be." -- Roger Gregory, on Xanadu
Ka-Ping Yee <python-dev@zesty.ca>:
I am not against structured text processing systems in general. I think that something of this flavour would be a great solution for PEPs and docstrings, and that David has done an impressive job on RST. It's just that RST is much too big (for me).
And if we're going to pay the transition costs to move to a heavyweight markup, it ought to be DocBook, same direction GNOME and KDE and the Linux kernel and FreeBSD and PHP are going. -- <a href="http://www.tuxedo.org/~esr/">Eric S. Raymond</a>
On Thu, Aug 01, 2002, Eric S. Raymond wrote:
Ka-Ping Yee <python-dev@zesty.ca>:
I am not against structured text processing systems in general. I think that something of this flavour would be a great solution for PEPs and docstrings, and that David has done an impressive job on RST. It's just that RST is much too big (for me).
And if we're going to pay the transition costs to move to a heavyweight markup, it ought to be DocBook, same direction GNOME and KDE and the Linux kernel and FreeBSD and PHP are going.
Well, reST can generate DocBook easily enough. The problem I see with DocBook is the creation/editing side: XML is painful. Having written one presentation in pure XML/PythonPoint and another presentation in my home-grown structured text system that then got converted to XML for processing by PythonPoint, I'm a big believer in the *concept* of reST. What remains to be seen is whether reST works well enough in the Real World [tm]. -- Aahz (aahz@pythoncraft.com) <*> http://www.pythoncraft.com/ Project Vote Smart: http://www.vote-smart.org/
On Thu, 1 Aug 2002, Eric S. Raymond wrote:
Ka-Ping Yee <python-dev@zesty.ca>:
I am not against structured text processing systems in general. I think that something of this flavour would be a great solution for PEPs and docstrings, and that David has done an impressive job on RST. It's just that RST is much too big (for me).
And if we're going to pay the transition costs to move to a heavyweight markup, it ought to be DocBook, same direction GNOME and KDE and the Linux kernel and FreeBSD and PHP are going.
I would be very unhappy about having to enter and edit inline documentation in an XML-based markup language. RST is not what i would call heavyweight *markup*. It's just a heavy specification. There are too many cases to know. If you simplified RST in the following ways, we might have something i would consider reasonably-sized: - Choose one way to do headings. - Choose one way to do numbered and non-numbered lists. - Choose one way to do tables. - Drop bibliographic fields. - Drop RCS keyword processing. - Get rid of option lists (we already have definition lists). - Drop some fancy reference features (e.g. auto-numbered and auto-symbol footnotes, indirect references, substitutions). - Drop inline hyperlink references (we already have inline URLs). - Drop inline internal targets (we already have explicit targets). - Drop interpreted text (we already have inline literals). - Drop citations (we already have footnotes). - (Or, in summary -- instead of ten kinds of inline markup, we only need four: emphasis, literals, footnotes, and URLs.) - Simplify inline markup rules (way too many characters to know). Instead of 100 lines describing markup rules, two lines are sufficient: emphasis starts from " *" and stops at "*", literals go from " `" to "`", and footnotes go from " [" to "[". -- ?!ng "This code is better than any code that doesn't work has any right to be." -- Roger Gregory, on Xanadu
On Thu, 1 Aug 2002, Eric S. Raymond wrote:
Ka-Ping Yee <python-dev@zesty.ca>:
I am not against structured text processing systems in general. I think that something of this flavour would be a great solution for PEPs and docstrings, and that David has done an impressive job on RST. It's just that RST is much too big (for me).
And if we're going to pay the transition costs to move to a heavyweight markup, it ought to be DocBook, same direction GNOME and KDE and the Linux kernel and FreeBSD and PHP are going.
I would be very unhappy about having to enter and edit inline documentation in an XML-based markup language.
Agreed 110%. Perhaps Eric thought we were talking about the core Python docs? David was only talking about PEPs right now.
RST is not what i would call heavyweight *markup*. It's just a heavy specification. There are too many cases to know. If you simplified RST in the following ways, we might have something i would consider reasonably-sized:
- Choose one way to do headings. - Choose one way to do numbered and non-numbered lists. - Choose one way to do tables. - Drop bibliographic fields. - Drop RCS keyword processing. - Get rid of option lists (we already have definition lists). - Drop some fancy reference features (e.g. auto-numbered and auto-symbol footnotes, indirect references, substitutions). - Drop inline hyperlink references (we already have inline URLs). - Drop inline internal targets (we already have explicit targets). - Drop interpreted text (we already have inline literals). - Drop citations (we already have footnotes). - (Or, in summary -- instead of ten kinds of inline markup, we only need four: emphasis, literals, footnotes, and URLs.) - Simplify inline markup rules (way too many characters to know). Instead of 100 lines describing markup rules, two lines are sufficient: emphasis starts from " *" and stops at "*", literals go from " `" to "`", and footnotes go from " [" to "[".
Perhaps this could be a preferred subset? --Guido van Rossum (home page: http://www.python.org/~guido/)
Ka-Ping Yee wrote:
I would be very unhappy about having to enter and edit inline documentation in an XML-based markup language.
have you tried it? I suggest taking a look at 2.3's xmlrpclib.py module. does the comments that start with a single ## line look scary to you? it's javadoc-style markup, which is based on HTML. if you've ever written a webpage, you can learn the rest in a couple of minutes. </F>
On Mon, Aug 05, 2002, Fredrik Lundh wrote:
Ka-Ping Yee wrote:
I would be very unhappy about having to enter and edit inline documentation in an XML-based markup language.
have you tried it?
Yes.
I suggest taking a look at 2.3's xmlrpclib.py module.
does the comments that start with a single ## line look scary to you?
it's javadoc-style markup, which is based on HTML. if you've ever written a webpage, you can learn the rest in a couple of minutes.
That's not XML, and I wouldn't even call it XML-based. It's yet another structured text markup that includes bits of XML (or HTML or whatever) and can be converted to XML. I don't know what exactly you're using in xmlrpclib.py, but I took a look at the javadoc docs when the discussion of reST came up because I wanted to know what reST had that javadoc didn't (and vice-versa) -- it's clear to me that javadoc is at least somewhat limited compared to reST, and that using javadoc for any kind of heavily marked-up docs looks far uglier than reST. The part of reST that's as limited as what you're using in xmlrpclib.py can also be learned in a couple of minutes. -- Aahz (aahz@pythoncraft.com) <*> http://www.pythoncraft.com/ Project Vote Smart: http://www.vote-smart.org/
Aahz wrote:
have you tried it?
Yes.
Details, please. We've recently used javadoc/pythondoc in a relatively large Python project (currently 30ksloc python, about 350 pages extracted docs) with good results. Most people involved had some exposure to html, but not javadoc. I don't think we've seen any markup errors at all.
it's javadoc-style markup, which is based on HTML. if you've ever written a webpage, you can learn the rest in a couple of minutes.
That's not XML, and I wouldn't even call it XML-based.
It all ends up in an XML infoset, and the mapping is can be described in a single sentence. Close enough for me.
using javadoc for any kind of heavily marked-up docs looks far uglier than reST.
Why would anyone put heavily marked-up documentation in docstrings? Are you doing that? Any reason you cannot use a word processor (interactive or batch) for those parts?
The part of reST that's as limited as what you're using in xmlrpclib.py can also be learned in a couple of minutes.
Perhaps, but I already know HTML and JavaDoc; why waste brain cells on learning yet another homebrewn markup language? </F>
Ka-Ping Yee wrote:
I have just read the specification:
http://docutils.sourceforge.net/spec/rst/reStructuredText.html
It took a long time. Perhaps it seems not so big to others, but my personal opinion would be to recommend against this proposal until the specification fits in, say, 1000 lines and can be absorbed in ten minutes.
The specification is, as its title says, a *specification*. It's a detailed description of the markup, intended to guide the *developer* who is writing a parser or other tool. It's not user documentation. For that, see the quick reference at http://docutils.sf.net/docs/rst/quickref.html. It's only 1153 lines of HTML (with lots of blank lines and linebreaks, hand-written before the reStructuredText parser could handle everything). Perhaps you started at the wrong end. The best place to start is with "A ReStructuredText Primer" by Richard Jones, at http://docutils.sf.net/docs/rst/quickstart.html (which *is* generated from text). It's only 335 lines long :-). It leads to the quick reference, which leads to the spec itself. And there was this item of the "deployment plan": - Modify PEP 1 (PEP Purpose and Guidelines) and PEP 9 (Sample PEP Template) with the new formatting instructions. PEP 9 could contain or point to a short & to-the-point overview of the markup. I see no problem coming up a user document that's more complete than the "Primer" above but still weighs in at under 1000 lines. But with the docs mentioned above, it it necessary? You could also begin by perusing an example. Look at the markup in http://docutils.sf.net/spec/pep-0287.txt, marked up in reStructuredText in the intended way. With the exception of embedded references and targets (for which there is no plaintext equivalent), none of the markup there looks like markup, and should be very easy to follow. Now look at the processed result (http://docutils.sf.net/spec/pep-0287.html); I think the return is worth the investment.
For me, it violates the fits-in-my-brain principle: the spec is 2500 lines long, and supports six different kinds of references and five different kinds of lists (even lists with roman numerals!). It also violates the one-way-to-do-it principle: for example, there are a huge variety of ways to do headings, and two different syntaxes for drawing a table.
How many times have we heard this? "All we need are paragraphs and bullet lists." That line of argument has been going on for at least six years, and has hampered progress all along. IMHO, variety in markup is good and necessary. Artificially limiting the markup makes for limited usefulness. OTOH, I have no problem with mandating standard uses, like a standard set of section title adornments.
I am not against structured text processing systems in general. ... It's just that RST is much too big (for me).
Somehow I think that "size of the spec" is a specious argument. Take the Python spec, for example: many times the size of the reStructuredText spec and yet it arguably fits in many different sized brains. I know they're different things and I'm not implying they're the same; the markup is a much smaller thing. reStructuredText is very practical in its scope. Constructs are there because they're useful and *used*. If we removed all the items you list, we'd end up with a crippled markup of little use to anyone.
I think that something of this flavour would be a great solution for PEPs and docstrings, and that David has done an impressive job on RST.
Thank you. Anyhow, off to work. I'll follow up on further posts this evening. -- David Goodger <goodger@users.sourceforge.net> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/
On Thu, 1 Aug 2002, David Goodger wrote:
Ka-Ping Yee wrote:
It took a long time. Perhaps it seems not so big to others, but my personal opinion would be to recommend against this proposal until the specification fits in, say, 1000 lines and can be absorbed in ten minutes.
The specification is, as its title says, a *specification*. It's a detailed description of the markup, intended to guide the *developer* who is writing a parser or other tool. It's not user documentation.
Okay, i understand that it's a spec and not a user manual. I think the fact that it takes that much text to describe all of the rules does say something about its complexity, though. Other people may have different thresholds; it exceeds my threshold. But again i want to stress that i think the structured-text approach is good and i do not advocate abandoning the whole idea; i just want a simpler set of rules.
For me, it violates the fits-in-my-brain principle: the spec is 2500 lines long, and supports six different kinds of references and five different kinds of lists (even lists with roman numerals!). It also violates the one-way-to-do-it principle: for example, there are a huge variety of ways to do headings, and two different syntaxes for drawing a table.
How many times have we heard this? "All we need are paragraphs and bullet lists." That line of argument has been going on for at least six years, and has hampered progress all along.
Well, that depends what you mean by "progress"! :) There might be something to that line of argument, if it has a habit of cropping up. One can separate two issues here: 1. too much functionality (YAGNI) 2. too many ways of expressing the same functionality (TMTOWTDI) As for the first, there's some room to argue here. I happen to feel there are quite a few YAGNI features in RST, like the Roman numerals and the RCS keyword processing. Auto-numbering in particular takes RST in a direction that makes me uncomfortable -- it means that RST now has the potential for a compile-debug cycle. But as for the second, i just don't see any justification for it. Reducing the multiple ways to do headers and lists and tables doesn't cripple anything; it only makes RST simpler and easier to understand. I acknowledge that there is some question of opinion as to what is the "same" functionality, causing issues to slush over from #1 to #2. To me, using "1.", "(1)", or "1)" to number a list makes no semantic difference at all, and so it counts as redundancy. If you already have definition lists, why also have option lists and field lists? If you already have literals, why have interpreted text? If you already have both footnotes *and* inline URLs, why also have anonymous inline hyperlink references?
OTOH, I have no problem with mandating standard uses, like a standard set of section title adornments.
If you're going to recommend certain ways, why not just decide what to use and be done with it? When designing a new standard, there's no point starting out with parts of it already deprecated. -- ?!ng
Ka-Ping Yee <python-dev@zesty.ca>:
To me, using "1.", "(1)", or "1)" to number a list makes no semantic difference at all, and so it counts as redundancy.
I imagine the variations are there so that RST documents can be easily read in their own right. Having different styles of headings, list numbers, etc. for different levels aids readability. Each of these features is no doubt useful for one appplication or another, but we're talking about a fairly restricted application here. Docstrings are usually pretty short and not likely to require multiple levels of headings, lists, etc. So I'm in favour of choosing a subset to recommend, perhaps mandate. Maybe a slightly larger subset could be used for PEPs, since they're somewhat bigger. Greg Ewing, Computer Science Dept, +--------------------------------------+ University of Canterbury, | A citizen of NewZealandCorp, a | Christchurch, New Zealand | wholly-owned subsidiary of USA Inc. | greg@cosc.canterbury.ac.nz +--------------------------------------+
[Ping]
It took a long time. Perhaps it seems not so big to others, but my personal opinion would be to recommend against this proposal until the specification fits in, say, 1000 lines and can be absorbed in ten minutes.
[David]
The specification is, as its title says, a *specification*. It's a detailed description of the markup, intended to guide the *developer* who is writing a parser or other tool. It's not user documentation.
[Ping]
Okay, i understand that it's a spec and not a user manual. I think the fact that it takes that much text to describe all of the rules does say something about its complexity, though.
I prefer the term "rich" over "complex". ;-) Seriously, any significant technology requires a significant spec. Did you look at the primer and quick reference? - Primer: http://docutils.sf.net/docs/rst/quickstart.html - Quick reference: http://docutils.sf.net/docs/rst/quickref.html I wouldn't recommend the Language or Library Reference to a Python newbie either; they're references! I'd point them to the Tutorial. The primer above is reStructuredText's tutorial: short & sweet.
But again i want to stress that i think the structured-text approach is good and i do not advocate abandoning the whole idea; i just want a simpler set of rules.
Speaking from experience having hashed out all these issues over the last two years, "a simpler set of rules" won't work. Sure, a few conveniences could be trimmed from reStructuredText, and all we'd lose would be convenience. Go past that and the markup would become less useful. Cut everything you listed and the markup would be next to useless.
For me, it violates the fits-in-my-brain principle: the spec is 2500 lines long, and supports six different kinds of references and five different kinds of lists (even lists with roman numerals!). It also violates the one-way-to-do-it principle: for example, there are a huge variety of ways to do headings, and two different syntaxes for drawing a table.
How many times have we heard this? "All we need are paragraphs and bullet lists." That line of argument has been going on for at least six years, and has hampered progress all along.
Well, that depends what you mean by "progress"! :) There might be something to that line of argument, if it has a habit of cropping up.
"Progress" in auto-documentation tools for Python. "Progress" in a usable, successful structured plaintext markup. OTOH, there's been just as much pressure from the other direction: "The markup needs a construct for XYZ." reStructuredText is the result of working toward a practical, usable, and readable balance.
One can separate two issues here:
1. too much functionality (YAGNI) 2. too many ways of expressing the same functionality (TMTOWTDI)
As for the first, there's some room to argue here. I happen to feel there are quite a few YAGNI features in RST, like the Roman numerals and the RCS keyword processing.
What's the big deal about Roman numerals? Human beings have many ways to count; our markup should allow us the freedom to choose the style we like. Ask a lawyer if Roman numerals for lists are expendible. If *you* don't like them, don't use them. RCS keyword processing is *not* a syntax feature; it's for readability, so readers don't have that $RCS: cruft$ shoved in their faces.
Auto-numbering in particular takes RST in a direction that makes me uncomfortable -- it means that RST now has the potential for a compile-debug cycle.
That's true with *any* markup processing system. It's the price of the increased functionality and readability of the processed result. A small price, IMHO. The reStructuredText parser is very helpful with diagnostics, and can only improve with user feedback. I've volunteered to do the processing, so there should be no impact on anyone.
But as for the second, i just don't see any justification for it. Reducing the multiple ways to do headers and lists and tables doesn't cripple anything; it only makes RST simpler and easier to understand.
Headers: by "multiple ways", are you referring to the author's choice of underline style? Or to the choice for overline & underline versus underline-only? Perhaps, when reading the spec, it's overwhelming; so don't start with the spec! But I don't see the big deal in having variety. The true test is this: when you look at a reStructuredText title, in whatever style, does it scream out at you, "I am a title!"? Without knowing anything about the markup, most people would answer "yes, it does". The same is true for lists and tables too. I base this on reports from people who are using Docutils/reStructuredText in the real world, introducing it to non-technical users, and reporting nothing but positive experiences. Lists: see below. Tables: the "simple table" syntax was added recently, because although it's limited, it's much simpler to type and edit than the original "grid tables". But grid tables don't have the limitations, so it's practical to keep both constructs around.
I acknowledge that there is some question of opinion as to what is the "same" functionality, causing issues to slush over from #1 to #2.
To me, using "1.", "(1)", or "1)" to number a list makes no semantic difference at all, and so it counts as redundancy.
The variety of list styles is based on real-world usage. See "The Chicago Manual of Style", 14th edition, section 8.79 (page 315): every variation of list enumeration is right there in a single nested list. Any reasonable person looking at any of those list styles will understand what they mean. Different strokes for different folks. Variety is the spice of life, and a necessity for otherwise dry documentation.
If you already have definition lists, why also have option lists and field lists?
They're semantically different. Sure you could implement option & field lists with definition lists, just as you could implement definition lists with tables. Option lists are explicitly for command-line option descriptions. Field lists are for name-value pairs where the details matter, like database records or attributes of extension constructs (directives).
If you already have literals, why have interpreted text?
They're very different things. Literals are for monospaced, *uninterpreted*, unprocessed, computer I/O text. From PEP 287: 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. In PEPs, there is no use for interpreted text currently (so they wouldn't be mentioned in the new-style-PEP guide, except perhaps in a footnote saying so). In the future auto-documentation tool, interpreted text will do explicitly what pydoc does auto-magically: link Python identifiers to their definitions elsewhere. But because it's explicit, interpreted text will not be accidentally misinterpreted (as can happen in pydoc).
If you already have both footnotes *and* inline URLs, why also have anonymous inline hyperlink references?
Because inline live links are useful, but nobody wants to trip over a three-line URL in the middle of a sentence.
OTOH, I have no problem with mandating standard uses, like a standard set of section title adornments.
If you're going to recommend certain ways, why not just decide what to use and be done with it? When designing a new standard, there's no point starting out with parts of it already deprecated.
PEPs are just one application of Docutils/reStructuredText. I see no conflict here. Groups often use a technology in conjunction with a conventions guide limiting the local use of that technology, for the sake of consistency or simplicity. We have such guides for Python's C code and stdlib code. (Does the Python LaTeX documentation mandate a subset of LaTeX? I know it specifies *additional* macros to use.) In the case of PEPs, I think a guide recommending certain practices would be appropriate, rather than mandating that certain constructs *not* be used. Constructs not used in PEPs are useful in other applications. Nothing would be deprecated, just "not used in PEPs". -- David Goodger <goodger@users.sourceforge.net> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/
On Thu, 1 Aug 2002, David Goodger wrote:
Speaking from experience having hashed out all these issues over the last two years, "a simpler set of rules" won't work. Sure, a few conveniences could be trimmed from reStructuredText, and all we'd lose would be convenience. Go past that and the markup would become less useful. Cut everything you listed and the markup would be next to useless.
If you took reST and removed the features i listed, you would have a markup system with paragraphs, multi-level headings, nestable bullet lists and numbered lists, definition lists, literal blocks, block quotes, tables, inline emphasis, inline literals, footnotes, inline hyperlinks, and internal and external hyperlink targets. Sounds pretty powerful to me. I find it strange that you would call this "next to useless".
Auto-numbering in particular takes RST in a direction that makes me uncomfortable -- it means that RST now has the potential for a compile-debug cycle.
That's true with *any* markup processing system. It's the price of the increased functionality and readability of the processed result.
I don't want to have to debug my text. If the markup is simple enough, determining the output requires very little context (a line or two); this means i can be sure what i'm going to get. Auto-numbering expands the context so any part of the entire document can affect the transformation of another part of the document.
A small price, IMHO.
The difference between writing a document once and *knowing* that it's correct, and having to compile-test-debug a few times, is a big cost.
I've volunteered to do the processing, so there should be no impact on anyone.
Huh? I don't know what you mean here. The design of reST impacts everyone who has to read to write documents in it.
But as for the second, i just don't see any justification for it. Reducing the multiple ways to do headers and lists and tables doesn't cripple anything; it only makes RST simpler and easier to understand.
Headers: by "multiple ways", are you referring to the author's choice of underline style? Or to the choice for overline & underline versus underline-only?
Both. Why have an assortment of 32 random punctuation characters, for a total of 64 different ways to do a heading? Who's going to remember what the characters are, anyway? Pick one or two and stick to them. There are really only two obvious ones: '-' and '='. You can differentiate heading levels by indenting the heading, one space per level. It would be vastly easier to tell what level a heading was at by looking at its position, rather than running all the way back to the beginning of the document and counting the number of different heading styles that appear.
true test is this: when you look at a reStructuredText title, in whatever style, does it scream out at you, "I am a title!"? Without knowing anything about the markup, most people would answer "yes, it does".
That's a backwards argument. It's good that reST titles look like titles. But that doesn't mean reST has to recognize all possible things that might look like titles, as titles. It's a lot easier to say "just underline your title with a row of hyphens" than "choose one of the following list of 32 random punctuation marks to underline your title; and optionally overline it; oh, but actually we think you should use only the following subset of the 32 punctuation marks..."
If you already have definition lists, why also have option lists and field lists?
They're semantically different. Sure you could implement option & field lists with definition lists, just as you could implement definition lists with tables. Option lists are explicitly for command-line option descriptions. Field lists are for name-value pairs where the details matter, like database records or attributes of extension constructs (directives).
All three are about associating a list of things with their corresponding definitions. Distinguishing whether the things being defined are options or not is just as unnecessary as distinguishing shopping lists, to-do lists, hit lists, etc. -- ?!ng
On 1 Aug 2002 at 22:28, David Goodger wrote:
Seriously, any significant technology requires a significant spec.
The wheel?
Speaking from experience having hashed out all these issues over the last two years, "a simpler set of rules" won't work.
Ah, but you've been hashing it out with a group of people who *care* about things like this. Welcome to the larger world (where dinosaurs still roam). -- Gordon http://www.mcmillan-inc.com/
Speaking from experience having hashed out all these issues over the last two years, "a simpler set of rules" won't work.
Ah, but you've been hashing it out with a group of people who *care* about things like this. Welcome to the larger world (where dinosaurs still roam).
Funny, Ping doesn't strike me as a dinosaur. More as someone who enjoys a good argument. :-) --Guido van Rossum (home page: http://www.python.org/~guido/)
[David]
Seriously, any significant technology requires a significant spec.
[Gordon]
The wheel?
If the ISO were around at the time, yes!
Ah, but you've been hashing it out with a group of people who *care* about things like this. Welcome to the larger world (where dinosaurs still roam).
[Guido]
Funny, Ping doesn't strike me as a dinosaur. More as someone who enjoys a good argument. :-)
So that wasn't Abuse? What a relief! -- David Goodger <goodger@users.sourceforge.net> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/
On Fri, 2 Aug 2002, David Goodger wrote:
[Guido]
Funny, Ping doesn't strike me as a dinosaur. More as someone who enjoys a good argument. :-)
So that wasn't Abuse? What a relief!
Just to make sure you know: i don't argue only for the sake of arguing. I argue when i think it will make Python better. -- ?!ng
On Sat, Aug 03, 2002, Ka-Ping Yee wrote:
On Fri, 2 Aug 2002, David Goodger wrote:
[Guido]
Funny, Ping doesn't strike me as a dinosaur. More as someone who enjoys a good argument. :-)
So that wasn't Abuse? What a relief!
Just to make sure you know: i don't argue only for the sake of arguing. I argue when i think it will make Python better.
"That's what they all say." ;-) -- Aahz (aahz@pythoncraft.com) <*> http://www.pythoncraft.com/ Project Vote Smart: http://www.vote-smart.org/
Ka-Ping Yee wrote:
On Fri, 2 Aug 2002, David Goodger wrote:
[Guido]
Funny, Ping doesn't strike me as a dinosaur. More as someone who enjoys a good argument. :-)
So that wasn't Abuse? What a relief!
Just to make sure you know: i don't argue only for the sake of arguing. I argue when i think it will make Python better.
Understood and appreciated. My comment was just a lame attempt at humor. Apologies for omission of ";-)". -- David Goodger <goodger@users.sourceforge.net> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/
I would very much like to see reStructuredText, or some minor variation on it, move forward as a "standard" for doc-strings very soon. I have long lamented not having a prescribed format *and* an associated processing tool suite included in the standard library. Even if the format isn't perfect (I think it looks very good), it is time to pick a reasonable candidate and go. SciPy does not yet have a standard doc-string format. The .3 release of SciPy (we're at .2alpha) will primarily be a documentation/testing effort. I'd like to use the chosen standard so that we can auto-generate the reference manual without setting up some complex third party tools. The user documentation for SciPy may still end up in TeX (which is very hard for me to swallow) or Word (I know, I know) because of their power, but doc-strings need something simpler. If XML or something like that is chosen, we'd probably use it, but I'd be less excited because it doesn't read as well in plain text form. Also, it will be much harder to get the scientists that contribute modules to conform to this. I watched the doc-sig for many months a when SciPy was started, and there was a lot of discussion on the multitude of different choices. It seemed like 50% wanted a dirt simple mark up like Ka-Ping suggests, and 50% wanted TeX or XML for maximum power as Eric R. suggests. You can't satisfy both camps, but David seems to have balanced most of the issues very well. Looking at David's marked-up PEPs, they read very nicely as plain text. I'm fairly confident that, with these as an example and without reading the specification, I can write my own marked up document or doc-string with little effort. Diving into the longer spec is only needed if you want fancy stuff. There are no doubt millions of choices for marking up doc-strings. David's is quite reasonable, solves many problems with StructureText, *has a champion*, and looks to have a fairly good start on a tool suite. If another choice is as well balanced, *has a champion*, and has a prayer of having tools ready in the standard library soon, then lets consider it. Otherwise, the argument over the perfect markup choice has been kicked around enough over the last several years. Let's just tweak this one. I wish for less vertical white space and a simpler heading markup too, but, not so much that I'm willing to think through all this as thoroughly as David has. I no longer wish for a "perfect" markup, just a standard one -- and soon. On a related note, distutils is (far) less than perfect (sorry Greg), and I have cursed it on many occasions. However, it works, solves a huge problem, and (with modifications) made building the 130,000 or so lines of Python/C/Fortran code that is SciPy tractable in a platform independent way. Standardizing on reStructuredText will have similar impact. my 0.02, eric
-----Original Message----- From: python-dev-admin@python.org [mailto:python-dev-admin@python.org] On Behalf Of David Goodger Sent: Wednesday, July 31, 2002 8:17 PM To: python-dev@python.org Subject: [Python-Dev] Docutils/reStructuredText is ready to process PEPs
Python-developers,
Pursuant to PEP 287, one of the deliverables of the just-released Docutils 0.2 (http://docutils.sf.net/) is a processing system for reStructuredText-format PEPs as an alternative to the current PEP processing. Here are examples of new-style PEPs (processed to HTML, with links to the source text as usual):
- http://docutils.sf.net/spec/pep-0287.html (latest) - http://docutils.sf.net/spec/pep-0000.html (as a proof of concept because of its special processing)
Compare to the old-style PEPs:
- http://www.python.org/peps/pep-0287.html (update pending) - http://www.python.org/peps/pep-0000.html
Existing old-style PEPs can coexist with reStructuredText PEPs indefinitely. What to do with new PEPs is a policy decision that doesn't have to be made immediately. PEP 287 puts forward a detailed rationale for reStructuredText PEPs; especially see the "Questions & Answers" section, items 4 through 7.
In earlier correspondence Guido critiqued some style issues (since corrected) and said "I'm sure you can fix all these things with a simple style sheet change, and then I'm all for allowing Docutils for PEPs." I'd appreciate more critiques/suggestions on PEP formatting issues, no matter how small. Especially, please point out any HTML/stylesheet issues with the various browsers.
I hereby formally request permission to deploy Docutils for PEPs on Python.org. Here's a deployment plan for your consideration:
- Install the Docutils-modified version of Fredrik Lundh's nondist/peps/pep2html.py script into CVS, along with ancillary files. The modified pep2html.py auto-detects old-style and new-style PEPs and processes accordingly. (http://docutils.sf.net/tools/pep2html.py)
- Install Docutils 0.2 on the server that does the PEP processing. I don't think it's necessary to put Docutils into Python's CVS.
- Make up a README for the "peps" directory with instructions for installing Docutils and running the modified pep2html.py.
- Modify PEP 1 (PEP Purpose and Guidelines) and PEP 9 (Sample PEP Template) with the new formatting instructions.
- Make an announcement to the Python community.
- I will maintain the software, convert current meta-PEPs to the new format as desired, handle PEP conversion updates, and assist other PEP authors to convert their PEPs if they wish.
If this is acceptable, to begin I will need write access to CVS and shell access to the Python.org server (however that works; please let me know what I need to do). Once I have the necessary access, I will try to ensure a near-zero impact on the PythonLabs crew.
Feedback is most welcome.
-- David Goodger <goodger@users.sourceforge.net> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/
_______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev
Eric and Timothy, thank you for putting quite clearly what I am sometimes unable to express myself. -- David
"DG" == David Goodger <goodger@users.sourceforge.net> writes:
DG> I hereby formally request permission to deploy Docutils for DG> PEPs on Python.org. Here's a deployment plan for your DG> consideration: I'm sympathetic to your aims, but I have reservations. As lightweight as reST is, it's still too heavy for me. Ka-Ping described some of my feelings quite well so I won't repeat what he said. I like that PEPs are 70-odd column plain text, with just a few style guidelines to aid in the html generation tool, and to promote consistency. I think of PEPs as our RFCs and I'm dinosaurically attached to the RFC format, which has served standards bodies well for so long. I like that the plain text sources are readable and consistent, with virtually no rules that are hard to remember. More importantly for me, I find it easy to do editing passes on submitted PEPs in order to ensure consistency. The noisy markup in reST bothers me, although you've done a good job in minimizing the impact compared to other markup languages. Magical double colons, trailing underscores, etc. are jarring to me. I wonder how tools like ispell will handle some of it (I haven't tried it on your reST source versions). I made this suggestion privately to David, but I'll repeat it here. I'd be willing to accept that PEPs /may/ be written in reST as an alternative to plaintext, but not require it. I'd like for PEP authors to explicitly choose one or the other, preferrably by file extension (e.g. .txt for plain text .rst or .rest for reST). I'd also like for there to be two tools for generation derivative forms from the original source. I would leave pep2html.py alone. That's the tool that generates .html from .txt. I'd write a different tool that took a .rst file and generated both a .html file and a .txt file. The generated .txt file would have no markup and would conform to .txt PEP style as closely as possible. reST generated html would then have a link both to the original reST source, and to the plain text form. A little competition never hurt anyone. :) So I'd open it up and let PEP authors decide, and we can do a side-by-side comparison of which format folks prefer to use. -Barry
I made this suggestion privately to David, but I'll repeat it here. I'd be willing to accept that PEPs /may/ be written in reST as an alternative to plaintext, but not require it. I'd like for PEP authors to explicitly choose one or the other, preferrably by file extension (e.g. .txt for plain text .rst or .rest for reST). I'd also like for there to be two tools for generation derivative forms from the original source.
AFAICT that's all that David asked for. It's the only thing that makes sense; nobody's going to convert over 200 existing PEPs to reST.
I would leave pep2html.py alone. That's the tool that generates .html from .txt. I'd write a different tool that took a .rst file and generated both a .html file and a .txt file. The generated .txt file would have no markup and would conform to .txt PEP style as closely as possible. reST generated html would then have a link both to the original reST source, and to the plain text form.
I don't see why reST needs to produce .txt output. The reST source is readable enough.
A little competition never hurt anyone. :) So I'd open it up and let PEP authors decide, and we can do a side-by-side comparison of which format folks prefer to use.
Exactly. Let's do it. --Guido van Rossum (home page: http://www.python.org/~guido/)
Barry A. Warsaw wrote:
I like that PEPs are 70-odd column plain text, with just a few style guidelines to aid in the html generation tool, and to promote consistency. I think of PEPs as our RFCs and I'm dinosaurically attached to the RFC format, which has served standards bodies well for so long. I like that the plain text sources are readable and consistent, with virtually no rules that are hard to remember. More importantly for me, I find it easy to do editing passes on submitted PEPs in order to ensure consistency.
Why are PEPs converted to HTML at all then? (Semi-seriously :-) RFCs pre-date the Web, HTML, GUIs, and PCs. There is a great advantage in sticking to a text-based format, but the existing structure is very limited. RFCs are so 20th century; don't you think it's time to move on? ;-) Dinosaurs have a tendency to become extinct you know. Given a small amount of use, I think you'll find the rules easy to remember. There should be little effect on editing. At most, Emacs may need to be taught to recognize a bit more punctuation.
The noisy markup in reST bothers me, although you've done a good job in minimizing the impact compared to other markup languages.
It's a trade-off: functionality for markup intrusion. It's the functionality of the processed form that's important: inline live links; live links to & from footnotes; automatic tables of contents (with live links!); images (don't you just *cringe* when you see ASCII graphics?); pleasant, readable text. The markup is minimal, quickly and easily ignored.
I made this suggestion privately to David, but I'll repeat it here. I'd be willing to accept that PEPs /may/ be written in reST as an alternative to plaintext, but not require it.
Sure. I thought I'd emphasized that in my original post: it'd be an alternative, the two styles can coexist. If you want to keep PEP 0 as it is, that's fine. I converted it to show that its special processing was also supported.
I'd like for PEP authors to explicitly choose one or the other, preferrably by file extension (e.g. .txt for plain text .rst or .rest for reST).
I'm not keen on a new file extension (this issue has come up before). There's so much in place on many platforms that says .txt means text files, and reStructuredText files *are* text files, with just a bit of formal structure sprinkled over. Browsers know what to do with .txt files; they wouldn't know what to do with .rest or .rtxt files. Near-universal file naming conventions are not the place to innovate IMHO.
I'd also like for there to be two tools for generation derivative forms from the original source.
I would leave pep2html.py alone. That's the tool that generates .html from .txt.
See http://docutils.sf.net/tools/pep2html.py (based on revision 1.37 of Python's nondist/peps/pep2html.py). Other than abstracting the file I/O and some minor changes for consistency & legibility, the reStructuredText-specific part is just two functions. One checks for the format of the PEP, and the other calls Docutils to do the work. Even without a new file extension, there's no need for a separate tool.
I'd write a different tool that took a .rst file and generated both a .html file and a .txt file. The generated .txt file would have no markup and would conform to .txt PEP style as closely as possible. reST generated html would then have a link both to the original reST source, and to the plain text form.
Do we need a slightly less-structured text output? I don't think so, but I offered two alternative strategies in PEP 287: a) Keep the existing PEP section structure constructs (one-line section headers, indented body text). Subsections can either be forbidden, or supported with reStructuredText-style 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). Strategy (b) has been implemented; that's what the edited PEP 287 uses. I'd recommend against it, but if you insist on existing PEP structure, strategy (a) fits better although inconsistently (depending on the decision on subsections).
A little competition never hurt anyone. :) So I'd open it up and let PEP authors decide, and we can do a side-by-side comparison of which format folks prefer to use.
Sure. Once authors see what the new markup gives them, I'm sure there will be some converts. -- David Goodger <goodger@users.sourceforge.net> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/
"DG" == David Goodger <goodger@users.sourceforge.net> writes:
DG> Why are PEPs converted to HTML at all then? (Semi-seriously DG> :-) To brand them with a Python banner and give them some hyperlinks. <wink> DG> RFCs pre-date the Web, HTML, GUIs, and PCs. There is a great DG> advantage in sticking to a text-based format, but the existing DG> structure is very limited. RFCs are so 20th century; don't DG> you think it's time to move on? ;-) Dinosaurs have a tendency DG> to become extinct you know. They also become the oil that drives our engines of industry, to twist an analogy. :) An of course RFCs are also converted to html: http://www.faqs.org/rfcs/rfc2822.html DG> Given a small amount of use, I think you'll find the rules DG> easy to remember. There should be little effect on editing. DG> At most, Emacs may need to be taught to recognize a bit more DG> punctuation. We'll see! >> The noisy markup in reST bothers me, although you've done a >> good job in minimizing the impact compared to other markup >> languages. DG> It's a trade-off: functionality for markup intrusion. It's DG> the functionality of the processed form that's important: DG> inline live links; live links to & from footnotes; automatic DG> tables of contents (with live links!); images (don't you just DG> *cringe* when you see ASCII graphics?); pleasant, readable DG> text. The markup is minimal, quickly and easily ignored. Taken to the extreme, why do we even use a text based format at all? We could, of course, get all that by authoring the PEPs directly in HTML. >> I made this suggestion privately to David, but I'll repeat it >> here. I'd be willing to accept that PEPs /may/ be written in >> reST as an alternative to plaintext, but not require it. DG> Sure. I thought I'd emphasized that in my original post: it'd DG> be an alternative, the two styles can coexist. If you want to DG> keep PEP 0 as it is, that's fine. I converted it to show that DG> its special processing was also supported. Cool. >> I'd like for PEP authors to explicitly choose one or the other, >> preferrably by file extension (e.g. .txt for plain text .rst or >> .rest for reST). DG> I'm not keen on a new file extension (this issue has come up DG> before). There's so much in place on many platforms that says DG> .txt means text files, and reStructuredText files *are* text DG> files, with just a bit of formal structure sprinkled over. DG> Browsers know what to do with .txt files; they wouldn't know DG> what to do with .rest or .rtxt files. Near-universal file DG> naming conventions are not the place to innovate IMHO. Don't most servers default to text/plain for types they don't know? I'm pretty sure Apache does. If a file extension isn't acceptable, then I'd still want the determination of plaintext vs. reST to be explicit. The other alternative is to add a PEP header to specify. I'd propose calling it Content-Type: and use text/x-rest as the value. >> I'd also like for there to be two tools for generation >> derivative forms from the original source. I would leave >> pep2html.py alone. That's the tool that generates .html from >> .txt. DG> See http://docutils.sf.net/tools/pep2html.py (based on DG> revision 1.37 of Python's nondist/peps/pep2html.py). Other DG> than abstracting the file I/O and some minor changes for DG> consistency & legibility, the reStructuredText-specific part DG> is just two functions. One checks for the format of the PEP, DG> and the other calls Docutils to do the work. Even without a DG> new file extension, there's no need for a separate tool. Fair enough. Let's do this: send me a diff against v1.39 of pep2html.py. I just downloaded docutils-0.2, but I'm not sure of the best way to integrate this in the nondist/peps directory. - If we do the normal setup.py install, that's fine for my machine but it means that everyone who will be pushing out peps will have to do the same. - If we hack pep2html.py to put ./docutils-0.2 on sys.path, then we can just check this stuff into the peps directory and it should Just Work. We'd have to update it when new docutils releases are made. Suggestions? Mostly I'd like to hear from others who push out new PEP versions. Would you rather have to install a disutils package in the normal way locally, or would you rather have everything you need in the nondist/peps directory? OTOH, if plaintext PEPs work without having access to the docutils package, that would be fine too (another reason perhaps for an explicit flag). >> I'd write a different tool that took a .rst file and generated >> both a .html file and a .txt file. The generated .txt file >> would have no markup and would conform to .txt PEP style as >> closely as possible. reST generated html would then have a >> link both to the original reST source, and to the plain text >> form. DG> Do we need a slightly less-structured text output? Maybe not. I'd prefer to have it, but if I'm alone there then I'll give up that crusade (or at least call YAGNI for now). DG> I don't think so, but I offered two alternative strategies in DG> PEP 287: >> Keep the existing PEP section structure constructs (one-line >> section headers, indented body text). Subsections can either be >> forbidden, or supported with reStructuredText-style underlined >> headers in the indented body text. >> 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). DG> Strategy (b) has been implemented; that's what the edited PEP DG> 287 uses. I'd recommend against it, but if you insist on DG> existing PEP structure, strategy (a) fits better although DG> inconsistently (depending on the decision on subsections). a) might also mean you'd have to reflow paragraphs to fit in the column width restrictions. I'd prefer a) but it may be more problematic. Moot if YAGNI prevails. >> A little competition never hurt anyone. :) So I'd open it up >> and let PEP authors decide, and we can do a side-by-side >> comparison of which format folks prefer to use. DG> Sure. Once authors see what the new markup gives them, I'm DG> sure there will be some converts. Let's find out. -Barry
Barry A. Warsaw wrote:
An of course RFCs are also converted to html: http://www.faqs.org/rfcs/rfc2822.html
So they are. Pretty picture at the top, navigation bar at top & bottom, and a huge <PRE> in-between (with live RFC links at least). Impressive. ;-)
Taken to the extreme, why do we even use a text based format at all? We could, of course, get all that by authoring the PEPs directly in HTML.
To answer your hypothetical (I assume), it's because raw HTML/XML/SGML is unreadable to most people. Plaintext is a common denominator, useful because it's universally readable. But texts like RFCs and PEPs do have some structure; by formalizing that structure we can use it. Current PEPs are one up on RFCs, recognizing section titles for HTML. ReStructuredText just takes that further.
>> I'd like for PEP authors to explicitly choose one or the other, >> preferrably by file extension (e.g. .txt for plain text .rst or >> .rest for reST).
DG> I'm not keen on a new file extension (this issue has come up DG> before). There's so much in place on many platforms that says DG> .txt means text files, and reStructuredText files *are* text DG> files, with just a bit of formal structure sprinkled over. DG> Browsers know what to do with .txt files; they wouldn't know DG> what to do with .rest or .rtxt files. Near-universal file DG> naming conventions are not the place to innovate IMHO.
Don't most servers default to text/plain for types they don't know? I'm pretty sure Apache does.
I don't know the answer to that. There's still what the browser does with it at the client end, and what apps like Windows Explorer and Mac's File Exchange do with file extensions. I think those side-effects make keeping .txt worth it.
If a file extension isn't acceptable, then I'd still want the determination of plaintext vs. reST to be explicit. The other alternative is to add a PEP header to specify. I'd propose calling it Content-Type: and use text/x-rest as the value.
[Already replied to in private email; repeated here to elicit opinions.] Good idea. But the header "Content-Type: text/x-rest" seems to imply much more than is intended. PEP 258 proposes a __docformat__ variable to contain the name of the format being used for docstrings; perhaps a "Format:" header for PEPs? For example: Format: reStructuredText Alternatively: Format: RST I prefer "RST" to "rest", which is already used as an acronym for the "Representational State Transfer" protocol (see Paul Prescod's article at http://www.xml.com/pub/a/2002/02/20/rest.html). The existing format could be called "Plaintext" (or "PEP 1.0" ;-). Without the "Format:" header, "Plaintext" would be the default. [In his reply to the aforementioned private email,] Barry pointed out: Since the PEP headers are modeled on RFC 2822, I say we stick with established standards rather than invent our own. So "Content-Type: text/x-rest" seems natural, and for most related standards, if there is no Content-Type: header, text/plain is already the documented default. Looking at the relevant standards (RFC 2616 etc.) I see his point. Using "Content-type:" may seem like overkill now, but it's flexible and future-proof (!). The "charset:" part could also come in handy; already, there are some PEPs (including PEP 0) which implicitly use Latin-1. But "text/x-rst" would be better. :-)
Fair enough. Let's do this: send me a diff against v1.39 of pep2html.py.
Will do.
I just downloaded docutils-0.2, but I'm not sure of the best way to integrate this in the nondist/peps directory.
- If we do the normal setup.py install, that's fine for my machine but it means that everyone who will be pushing out peps will have to do the same.
- If we hack pep2html.py to put ./docutils-0.2 on sys.path, then we can just check this stuff into the peps directory and it should Just Work. We'd have to update it when new docutils releases are made.
The "docutils" package could be a subdirectory of nondist/peps under CVS. When pep2html.py is run, the current working directory is already on the path so "import docutils" should just work and no sys.path manipulation would be necessary. But Docutils is substantial and evolving. I don't mind keeping Python's repository in sync but would others object to the added files and CVS traffic? Eventually I hope for Docutils to go into the stdlib, but it's not ready for consideration yet. I agree with the direct email consensus that "python setup.py install" is best.
OTOH, if plaintext PEPs work without having access to the docutils package, that would be fine too (another reason perhaps for an explicit flag).
Your wish is my command. If Docutils isn't installed and pep2html.py is asked to process a reStructuredText PEP, it will report the problem and move on gracefully (no traceback).
DG> Sure. Once authors see what the new markup gives them, I'm DG> sure there will be some converts.
Let's find out.
Great. I'll work on pep2html.py, a README, and a new "Template" Meta-PEP including a recommended reStructuredText subset. -- David Goodger <goodger@users.sourceforge.net> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/
participants (11)
-
Aahz -
barry＠python.org -
David Goodger -
eric jones -
Eric S. Raymond -
Fredrik Lundh -
Gordon McMillan -
Greg Ewing -
Guido van Rossum -
Ka-Ping Yee -
Ka-Ping Yee