Re: [Python-Dev] Escaping docs markup in NEWS entries?
On Mon, May 1, 2017 at 5:03 AM, Wes Turner wrote: > Where would be a good place for test cases for an rst_escape() function? > Docutils? > > https://github.com/westurner/dotfiles/blob/develop/scripts/git-changelog.py I'd say that the test cases for any function should reside in the same project/codebase as the function itself. Where do you intend the function to reside? I'm not certain what rst_escape() is supposed to do; what is its purpose? The docstrings of rst_escape() as well as the git-changelog.py module lack such explanations. I am also uncertain if this is necessary, based on the remainder of the thread. Perhaps it would be better to fix this "make suspicious" so that it doesn't produce spurious results? (Note: I am unclear on exactly what "make suspicious" is supposed to do, or why.) I apologize for the azure hue of my answers, to questions that came from out of the blue. ;-) David Goodger <http://python.net/~goodger> > - rst_escape # YMMV > - $ git-changelog.py -r "release/0.3.14" --hdr= "+"` > > On Monday, May 1, 2017, Nick Coghlan wrote: >> >> On 1 May 2017 at 17:13, Martin Panter wrote: >> > On 1 May 2017 at 06:37, Nick Coghlan wrote: >> >> Hi folks, >> >> >> >> I'm trying to write a NEWS entry that explains that the >> >> ":func:`bytes`" cross-references have changed to refer to the type >> >> descriptions by default (matching other builtin container types), so >> >> you now need to use ``:ref:`func-bytes`" to refer to the old target in >> >> the list of builtin functions (if you really want that for some >> >> reason). >> >> >> >> Unfortunately, my first two attempts both cause warnings in "make >> >> suspicious" with the following output: >> > >> > What is the full output? Usually it includes instructions to add false >> > positives to Doc/tools/susp-ignored.csv; maybe that is all you have to >> > do? >> >> You're right, that would be likely be the way to go if I decided to >> keep the escaped markup. >> >> However... >> >> >> My fallback plan is to just include the unescaped markup in the NEWS >> >> entry (rather than trying to make it readable even in rendered form), >> >> but I figured I'd ask for advice here first. >> > >> > I thought the NEWS file was mainly regarded as plain text, so it would >> > be important to avoid ugly RST markup like backslashes if possible. >> >> ... I think you're right on this point, so it makes more sense to skip >> the escaping entirely, >> and just use the correct link markup in the NEWS entry. > > How convenient. >> >> >> Cheers, >> Nick. >> >> -- >> Nick Coghlan | [email protected] | Brisbane, Australia >> ___ >> Python-Dev mailing list >> [email protected] >> https://mail.python.org/mailman/listinfo/python-dev >> Unsubscribe: >> https://mail.python.org/mailman/options/python-dev/wes.turner%40gmail.com ___ Python-Dev mailing list [email protected] https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] question about docstring formatting
On Thu, May 28, 2009 at 09:06, Jeremy Hylton wrote:
> A question came up at work about docstring formatting. It relates to
> the description of the summary line in PEP 257.
>
> http://www.python.org/dev/peps/pep-0257/
> """Multi-line docstrings consist of a summary line just like a
> one-line docstring, followed by a blank line, followed by a more
> elaborate description. The summary line may be used by automatic
> indexing tools; it is important that it fits on one line and is
> separated from the rest of the docstring by a blank line. The summary
> line may be on the same line as the opening quotes or on the next
> line. The entire docstring is indented the same as the quotes at its
> first line (see example below)."""
>
> It says that the summary line may be used by automatic indexing tools,
> but is there any evidence that such a tool actually exists? Or was
> there once upon a time? If there are no such tools, do we still think
> that it is important that it fits on line line?
There are several auto-documentation tools out there, like Sphinx and
epydoc, and the stdlib's pydoc. Historically there were other tools,
like HappyDoc ad Pythondoc. I'm not up on these or other tools, so I
don't know if or how that part of PEP 257 applies.
The point of the one-line summary was to allow for tooltips and
compact tables of contents.
Even if there were no supporting tools, I think it is useful to
express the intent of a class/method/function in a single line. The
process of distilling the description down can, in itself, be
illuminating. To imitate the Zen: if the code can't be described in a
short sentence, it may be too complicated.
I'm not saying that this should be enforced in any way. It's just a
guideline. If a tool needs a short summary and the docstring doens't
have a one-liner, I'd expect the tool just to take the first line and
add ellipsis ("...").
--
David Goodger <http://python.net/~goodger>
___
Python-Dev mailing list
[email protected]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] python-ideas on gmane
[Georg Brandl] > is there any objection against making python-ideas available on gmane? It's already there. That's how I read it. -- David Goodger <http://python.net/~goodger> signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] call for PEPs
I'm one of the PEP editors at the end of peps-at-python-dot-org; Barry Warsaw is the other. Since before PyCon, I haven't had time for PEP number assignments, editing, and checkins. I don't follow python-dev or python-3000 closely, so I only recently learned of the April 30 deadline for PEPs. I'd like to get all the outstanding PEPs checked in, but I need help. There are a bunch of draft PEPs in my inbox, but I can't trust it because some have already been checked in, and others have since been updated or become obsolete. Please re-send the latest drafts (as attachments!) of any outstanding PEPs to peps-at-python-dot-org. Include the dates of any postings of the PEP to python-dev, python-3000, or python-list (in the Post-History header). Be sure to read and follow PEP 1 (PEP Purpose and Guidelines; http://www.python.org/dev/peps/pep-0001/) for details on what to include. Posting a draft PEP to a python-* mailing list IS NOT SUFFICIENT. It must be sent to peps-at-python-dot-org. Committers (those with commit access to Python's SVN) are welcome to add PEPs themselves. Just take the next available number from PEP 0 (which must be updated). BTW, with PSF and PyCon duties (I'm chairing PyCon 2008), I don't see my availability for PEP editing increasing any time soon. A new PEP Editor would be welcome! -- David Goodger <http://python.net/~goodger> ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] \u and \U escapes in raw unicode string literals
Guido van Rossum python.org> writes:
> I'd like to hear from anyone who has access to *real code* that uses
> \u or \U in a raw unicode string.
Docutils uses it in the docutils.parsers.rst.states module, Body class:
patterns = {
'bullet': ur'[-+*\u2022\u2023\u2043]( +|$)',
...
attribution_pattern = re.compile(ur'(---?(?!-)|\u2014) *(?=[^ \n])')
-- David Goodger <http://python.net/~goodger>
___
Python-Dev mailing list
[email protected]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] \u and \U escapes in raw unicode string literals
> Guido van Rossum python.org> writes:
> > I'd like to hear from anyone who has access to *real code* that uses
> > \u or \U in a raw unicode string.
David Goodger python.org> writes:
> Docutils uses it in the docutils.parsers.rst.states module, Body class:
>
> patterns = {
> 'bullet': ur'[-+*\u2022\u2023\u2043]( +|$)',
> ...
>
> attribution_pattern = re.compile(ur'(---?(?!-)|\u2014) *(?=[^ \n])')
Although admittedly, these don't *have* to be raw strings, since they don't
contain backslashes as regexp syntax. They were made raw by reflex, because
they contain regular expressions.
-- DG
___
Python-Dev mailing list
[email protected]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] \u and \U escapes in raw unicode string literals
> On 5/11/07, David Goodger <[EMAIL PROTECTED]> wrote:
> > Docutils uses it in the docutils.parsers.rst.states module, Body class:
> >
> > patterns = {
> > 'bullet': ur'[-+*\u2022\u2023\u2043]( +|$)',
> > ...
> >
> > attribution_pattern = re.compile(ur'(---?(?!-)|\u2014) *(?=[^ \n])')
On 5/11/07, Guido van Rossum <[EMAIL PROTECTED]> wrote:
> But wouldn't it be just as handy to teach the re module about \u and
> \U, just as it already knows about \x (and \123 octals)?
Could be. I'm just providing examples, as requested.
I leave the heavy thinking to others ;-)
--
David Goodger <http://python.net/~goodger>
___
Python-Dev mailing list
[email protected]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [PEPs] Email addresses in PEPs?
On 8/20/07, Brett Cannon <[EMAIL PROTECTED]> wrote: > I believe email addresses are automatically obfuscated as part of the > HTML generation process, but one of the PEP editors can correct me if > I am wrong. Yes, email addresses are obfuscated in PEPs. For example, in PEPs 0 & 12, my address is encoded as "goodger at python.org" (the "@" is changed to " at " and further obfuscated from there). More tricks could be played, but that would only decrease the usefulness of addresses for legitimate purposes. Spam is a fact of life. People just have to deal with it. -- David Goodger <http://python.net/~goodger> ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] PyCon 2008: Call for Talk & Tutorial Proposals
Proposals for PyCon 2008 talks & tutorials are now being accepted. The deadline for proposals is November 16. PyCon 2008 will be held in Chicago, Illinois, USA, from March 13-20. Please see the full announcement here: http://pycon.blogspot.com/2007/10/call-for-talk-tutorial-proposals.html -- David Goodger <http://python.net/~goodger> ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] Only one week left for PyCon proposals!
There is only one week left for PyCon tutorial & scheduled talk proposals. If you've been thinking about making a proposal, now's the time! Tutorial details and instructions here: http://us.pycon.org/2008/tutorials/proposals/ Scheduled talk details and instructions here: http://us.pycon.org/2008/conference/proposals/ The deadline is Friday, November 16. Don't put it off any longer! PyCon 2008: http://us.pycon.org -- David Goodger PyCon 2008 Chair signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] Last chance for PyCon talk & tutorial proposals!
Thanks to all the proposal authors so far, we have received lots of proposals for PyCon talks & tutorials. But we'd like to have even more. Alas, the proposal submission deadline should have been set after a weekend, not before. So we have decided to extend the proposal submission deadline to Monday, November 19 at midnight (Chicago time). This gives you a *whole extra weekend* to write up your talk and tutorial ideas! If you've been procrastinating, stop! Get started on a proposal instead! See the call for conference talk proposals: http://us.pycon.org/2008/conference/proposals/ Topic ideas: http://wiki.python.org/moin/Talk_Subjects http://wiki.python.org/moin/PyCon2007/Feedback#head-e2dca74d1492e49fae11550e6cbc40fa18a17f40 See the call for tutorial proposals http://us.pycon.org/2008/tutorials/proposals/ Topic ideas from the PyCon 2007 feedback: http://wiki.python.org/moin/PyCon2007/Feedback/TutorialIdeas I hope to see (and hear) you at PyCon 2008! http://us.pycon.org -- David Goodger, PyCon 2008 Chair signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] PyCon 2008 Registration Open!
I am pleased to announce that PyCon 2008 registration is now open! http://us.pycon.org/2008/registration/ Early-bird registration is open until February 20, so there's one month to register at the low rates. Regular on-line registration will be available from February 21 through March 7. PyCon 2008 will be held from March 13 through 20 in Chicago: * Tutorials: Thursday, March 13 * Conference: Friday, March 14, through Sunday, March 16 * Sprints: Monday, March 17 through Thursday, March 20 Register early, especially if you'd like to attend a tutorial or three, as tutorials fill up early. And yes, you heard that correctly -- this year, we have three tutorial sessions: morning, afternoon, and evening. There are 29 great tutorials to choose from. More about the tutorials soon, but for now, you can check out the descriptions yourself here: http://us.pycon.org/2008/tutorials/schedule/ The talk schedule is also up (in a preliminary form), although some changes are expected: http://us.pycon.org/2008/conference/schedule/ Hotel reservations are also open: https://www.cteusa.com/pycon1/ The rate is $99/night plus tax ($112/night net), also until February 20. More hotel information is here: http://us.pycon.org/2008/registration/hotel/ See the PyCon web site for complete details: http://us.pycon.org/2008/ Thanks to the PyCon organizers for developing the software, providing the website content, testing & debugging. PyCon is a community conference, of, by, and for the Python community. There is still much to do, and you can help! http://us.pycon.org/2008/helping/ See you in Chicago! David Goodger PyCon 2008 Chair signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] PyCon: deadline for hotel reservations and early-bird registration coming soon!
If you haven't registered for PyCon yet, now is the time! The early-bird registration deadline is February 20, one week away. After that, the price for registration will be going up. http://us.pycon.org/2008/registration/ The deadline for hotel reservations at the conference rate is also February 20. Act now, because the regular rate is considerably higher! http://us.pycon.org/2008/registration/hotel/ A reminder to tutorial and talk speakers: you are responsible for your own registration and hotel reservations. So don't delay! PyCon 2008: March 14-16, 2008 (& tutorials March 13, & sprints March 17-20) David Goodger PyCon 2008 Chair signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [PyCon-Organizers] us.pycon.org down?
On Thu, Jul 3, 2008 at 13:12, Facundo Batista <[EMAIL PROTECTED]> wrote: > (sorry for the crossposting) > > Do you know what happened with "http://us.pycon.org/";? Not sure. The machine is still up (it serves www.pycon.org as well). Either something is misconfigured, or a process can't start, or something... I'll ask Jeff Rush (whose machine it's on) and Doug Napoleone (who knows more about the server than I, and has admin access) to look into it. -- David Goodger <http://python.net/~goodger> ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [PyCon-Organizers] us.pycon.org down?
On Thu, Jul 3, 2008 at 13:32, David Goodger <[EMAIL PROTECTED]> wrote: > On Thu, Jul 3, 2008 at 13:12, Facundo Batista <[EMAIL PROTECTED]> wrote: >> (sorry for the crossposting) >> >> Do you know what happened with "http://us.pycon.org/";? > > Not sure. The machine is still up (it serves www.pycon.org as well). > Either something is misconfigured, or a process can't start, or > something... > > I'll ask Jeff Rush (whose machine it's on) and Doug Napoleone (who > knows more about the server than I, and has admin access) to look into > it. Jeff fixed it. URL rewriting was off by mistake. -- David Goodger <http://python.net/~goodger> ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [Pydotorg] Should we help pythonmac.org?
> Guido van Rossum wrote: >> Alternatively, I just got mail from Bob Ippolito indicating that he'd >> be happy to hand over the domain to the PSF. It's got quite a bit more >> on it than Python distros, and it's a fairly popular resource for Mac >> users I imagine. However macports.org seems to have more Python stuff, >> and has a more recent version of 2.5. (2.5.2). Perhaps we should link >> to macports.org instead? I strongly recommend that we *NOT* make macports.org the main, official Mac OS X version of Python. Secondary is fine, but not primary. Macports is what the name says: it's a system of Mac ports of Linux packages, mostly command-line only. Those who want/need it know about it or will find it easily, while those who don't need it would only be confused by it. The official Mac Python should be an OS X application, with an icon, living in /Applications, ideally with a Mac-standard editor app (the 2.5.1 I have has IDLE), etc. Unfortunately, I can only recommend. I don't know anything about building Mac apps. -- David Goodger <http://python.net/~goodger> ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] PyCon 2009 registration is now open!
Register here: http://us.pycon.org/2009/register/ Information (rates etc.): http://us.pycon.org/2009/registration/ Hotel information & reservations: http://us.pycon.org/2009/about/hotel/ Early bird registration ends February 21, so don't delay! -- David Goodger, PyCon 2009 Chair ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] Re: Subscribing to PEP updates
[Nick Coghlan] Someone asked on python-list about getting notifications of changes to PEP's. As a low-effort solution, would it be possible to add a Sourceforge mailing list hook just for checkins to the nondist/peps directory? -0 Probably possible, but not no-effort, so even if it gets a favorable reaction someone needs to do some work. Why not just subscribe to python-checkins and filter out everything *but* nondist/peps? As PEP editor, that's what I do (although I filter manually/visually, since I'm also interested in other checkins). -- David Goodger <http://python.net/~goodger> signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Combining the best of PEP 288 and PEP 325: generator exceptions and cleanup
[Guido van Rossum] > I believe that in the discussion about PEP 343 vs. Nick's PEP 3XX > (http://members.iinet.net.au/~ncoghlan/public/pep-3XX.html, still > awaiting PEP moderator approval I believe?) ... Nick hasn't submitted it for a PEP number yet. -- David Goodger <http://python.net/~goodger> signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] r43613 - python/trunk/Doc/lib/libcsv.tex
[regarding the examples in the last section of libcsv.tex] [Walter Dörwald] > These classes will have problems with various non-charmap encodings. > (E.g. the writer will write multiple BOMS for UTF-16). IMHO it would be > better to use the new incremental codecs in these examples. Could you fix it? I'm not familiar with the incremental codecs. -- David Goodger <http://python.net/~goodger> signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Dropping __init__.py requirement for subpackages
Sounds a bit like the tail wagging the dog. I thought the Google geeks were a smart bunch. ISTM that something like Phillip Eby's code would be the most expedient solution. I would add one extension: if a package directory without an __init__.py file *is* encountered, an empty __init__.py file should automatically be created (and perhaps even "svn add" or equivalent called), and the code should loudly complain "Packages need __init__.py files, noob!" Add sound and light effects for extra credit. -- David Goodger <http://python.net/~goodger> ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] new PEP type: Process
Barry Warsaw and I, the PEP editors, have been discussing the need for a new PEP type lately. Martin von Löwis' PEP 347 was a prime example of a PEP that didn't fit into the existing Standards Track and Informational categories. We agreed upon a new "Process" PEP type. For more information, please see PEP 1 (http://www.python.org/peps/pep-0001.html) -- the type of which has also been changed to Process. Other good examples of Process PEPs are the release schedule PEPs, and I understand there may be a new one soon. (Please cc: any PEP-related mail to [EMAIL PROTECTED]) -- David Goodger <http://python.net/~goodger> signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] new PEP type: Process
[Aahz] > Go ahead and make PEP 6 a Process PEP. Done! -- David Goodger <http://python.net/~goodger> signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] setdefault's second argument
[Tim Peters]
> Dang! I may have just found a use, in Zope's
> lib/python/docutils/parsers/rst/directives/images.py (which is part
> of docutils, not really part of Zope):
>
> figwidth = options.setdefault('figwidth')
> figclass = options.setdefault('figclass')
> del options['figwidth']
> del options['figclass']
If a feature is available, it *will* eventually be used!
Whose law is that?
> I'm still thinking about what that's trying to do <0.5 wink>.
The code needs to store the values of certain dict entries, then
delete them. This is because the "options" dict is passed on to
another function, where those entries are not welcome. The code above
is simply shorter than this:
if options.has_key('figwidth'):
figwidth = options['figwidth']
del options['figwidth']
# again for 'figclass'
Alternatively,
try:
figwidth = options['figwidth']
del options['figwidth']
except KeyError:
pass
It saves between one line and three lines of code per entry. But
since those entries are probably not so common, it would actually be
faster to use one of the above patterns.
> Assuming options is a dict-like thingie, it probably meant to do:
>
> figwidth = options.pop('figwidth', None)
> figclass = options.pop('figclass', None)
Yes, but the "pop" method was only added in Python 2.3. Docutils
currently maintains compatibility with Python 2.1, so that's RIGHT
OUT!
> David, are you married to that bizarre use of setdefault ?
No, not at all. In fact, I will vehemently deny that I ever wrote
such code, and will continue to do so until someone looks up its
history and proves that I'm guilty, which I probably am.
--
David Goodger <http://python.net/~goodger>
signature.asc
Description: OpenPGP digital signature
___
Python-Dev mailing list
[email protected]
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] PEP submission broken?
[Bryan Olson] > Though I tried to submit a (pre-) PEP in the proper form through the > proper channels, it has disappeared into the ether. Indeed, it has; I can't find it in my mailbox. Could you re-send the latest text? I'll review it right away. > From what I can tell, We need to address fixing the > PEP process before there is any point in working on PEP's, Email is imperfect; just send it again. And "[EMAIL PROTECTED]" doesn't help ;-) -- David Goodger <http://python.net/~goodger> signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] PEP submission broken?
[Nick Coghlan] > Would it be worth having a PEP category on the RFE tracker, rather than > submitting pre-PEP's directly to the PEP editors? Couldn't hurt. -- David Goodger <http://python.net/~goodger> signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] CVS repository mostly closed now
You can also remove CVS write privileges from project members. It's a good way to prevent accidental checkins. -- David Goodger <http://python.net/~goodger> signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[Python-Dev] PyCon TX 2006: Early-bird registration ends Dec. 31!
Early bird registration for PyCon TX 2006 ends on December 31st, so there are only a few days LEFT. To register, please visit: http://us.pycon.org/TX2006/Registration You can still register after Dec. 31st, but the cost will go up by US$65 (US$25 for students). This year PyCon will feature a day of tutorials before the three days of regular presentations. Course outlines for all the tutorials have been posted; see http://wiki.python.org/moin/PyCon2006/Tutorials All of the PyCon tutorials are still open for new registrations, but space is limited, and we suspect they'll all be filled up by the time early-bird registration closes. Don't forget to book your hotel room, too. PyCon TX 2006 is being held at a Dallas/Addison hotel, and we have negotiated a special low rate: http://us.pycon.org/Addison/Hotels We hope to see you in Texas! -- David Goodger (on behalf of A.M. Kuchling, Chair, PyCon 2006) signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [Doc-SIG] that library reference, again
On 12/29/05, Fredrik Lundh <[EMAIL PROTECTED]> wrote: > however, given that the discussion that led up to this has been dead for > almost a week, You mean since Christmas? > I'm beginning to fear that I've wasted my time on a project > that nobody's interested in. Could be. I don't see HTML+PythonDoc as a significant improvement over LaTeX. Yes, I'm biased. So are you. > are we stuck with latex for the foreseeable future? Until we have something clearly and significantly better, yes. -- David Goodger <http://python.net/~goodger> ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [Doc-SIG] that library reference, again
[Fredrik Lundh] >>> I'm beginning to fear that I've wasted my time on a project >>> that nobody's interested in. [David Goodger] >> Could be. I don't see HTML+PythonDoc as a significant improvement >> over LaTeX. [Fredrik Lundh] > Really? Yes, really. > Have you read my list of goals? Yes, and I mostly agree with most of them. One is worded in a very slanted way: * Build on existing non-Python-specific documentation standards and tools, where possible (basic html, javadoc, xhtml modules, etc). It seems that this goal is specifically written to exclude ReST. Javadoc is only a standard in the Java world. LaTeX *is* an existing language-independent standard, and has a much longer history than javadoc. I'd re-write the above goal as: * Build on existing documentation standards and tools, where possible. Another goal is highly biased toward XML-style markup: * Make it trivial to do basic rendering to HTML (a few re.sub calls should suffice), to enable simple tools (CGI scripts, etc) to be able to render reference documentation. This is the tail wagging the dog. This item is under-specified: * Make is easy to do advanced rendering to HTML, XHTML or XML models (e.g. typographic issues, navigation, dynamic styling, etc.). No more -- dashes and silly ``quotes''. The second sentence lacks a rationale. What's wrong with "-- dashes"? What's "silly" about "``quotes''"? Your list is missing an important goal: * Easy to read. The final paragraph of the "Project Goals" section lacks context and contains a false statement: The semantic model should be simple, python-oriented, and more detailed than today. For example, while a ReST-based solution knows that open in a given context should be rendered in bold, and a LaTeX-based solution knows that the given open is a function, the PythonDoc model also knows that it refers to the os.open function, rather than the built-in open function. The reference to ReST is wrong here; ReST certainly can know the semantics of a given identifier. I'd like to see an example of how the HTML+PythonDoc markup indicates that a particular "open" is os.open and not __builtins__.open. > Does LaTeX address all of them? Perhaps not. So? It works well enough. > Does ReST? Not currently, but so what? I didn't propose ReST as an alternative to LaTeX for Python's documentation. All I'm saying is that the proposed HTML+PythonDoc markup is not significantly better than the status quo. I don't think there's enough benefit to make leaving LaTeX worthwhile. IOW: -1 on replacing LaTeX with HTML+PythonDoc. > If not, can you explain why they're not important. > >> Yes, I'm biased. So are you. > > I don't think you understand the problem, so your bias is > irrelevant. This is all about semantics, not presentation markup. I don't think you understand ReST except superficially. In any case, ReST is irrelevant to this discussion. I do not consider ReST a suitable replacement for LaTeX in Python's docs at present. My bias is simple: I am against wasting the time and effort required to replace one form of verbose markup with a different but equivalent form. The proposed solution is no better than the status quo. I agree with the people who have stated that they find the direct writing of HTML painful. IMO, the markup itself is almost irrelevant. As others have stated, writing good documentation is hard. People will latch on to any excuse to avoid it, and markup is convenient. But even if the docs had no markup whatsoever, if they were written in plain text like RFCs, I doubt there would be significantly more patch contributions. Plain text patches are already accepted; perhaps this fact needs more emphasis, but that's all. > We know that you have big hats over in ReST-land; now show us some > cattle. Moo. Or would you prefer the Buddhist "mu"? What *are* you talking about? -- David Goodger <http://python.net/~goodger> signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] [Doc-SIG] that library reference, again
[David Goodger] >> The second sentence lacks a rationale. What's wrong with "-- >> dashes"? What's "silly" about "``quotes''"? [Fredrik Lundh] > don't you know *anything* about typography ? Yes, for a layman, I know plenty. I am not a typographer though. Simply put, your "list of goals" provides no context for your statements. *I* know that "--" is turned into an en-dash in TeX, and that "``these''" are turned into curly quotes. So? What's "silly" about that? Spell it out, man! And what about 99% of the people who read your page? They won't know the first thing about what you're talking about. >> The reference to ReST is wrong here; ReST certainly can know the >> semantics of a given identifier. > >> I don't think you understand ReST except superficially. > > That's why I'm listening to people who've tried to use ReST for this > purpose. They've all failed. Maybe they also only understood ReST > superficially. Perhaps, since ReST is *not* designed as a semantic markup language. It's designed as an implicit markup language, with explicit extensions for semantic markup. In any case, ReST is *not* being proposed here. > Or maybe it's because ReST is created by people who have a very > shallow understanding of the issues involved in writing structured > reference documentation. Your guess is as good as mine. Why does Fredrik find it necessary to descend to personal insults? Your guess is as good as mine. > Support for quick turnaround, edit via the web, richer semantic > information, and a larger existing toolbase isn't better than the > status quo ? Those would be good features. Those features are not mentioned in your list of goals though! (http://effbot.org/zone/pythondoc-lib.htm) AFAICT, you just went off on a tangent to create a new markup language, which we don't need. > The problem is that the WORKFLOW doesn't work. So fix the workflow. Something like Ian Bicking's Commentary system, or something more specific to Python's docs, seems to fit the bill. > It's the workflow that's the real problem here, but you cannot fix > the workflow without fixing the markup. I disagree. The markup doesn't need an overhaul to fix the workflow. > I assume this means that we're going to keep getting more "ReST can > certainly do this but we're not going to show anyone how" posts from > the ReST camp ? You assume incorrectly. I'm not talking about ReST. I'm not proposing ReST for anything. Please ignore the fact that I'm the author of ReST; I never brought it up, I never proposed it. *You* are the one harping on it. I'm just against an arbitrary and unnecessary change of markup in Python's docs. > Your reply makes it obvious that you don't understand the issues > involved here, nor how the goals address them. Your reply, and your regular descent to personal insults, make it excruciatingly obvious that you're a troll. I hesitated before first replying to this thread, suspecting (from past experience) that this would be the response I'd get. From now on, I'll avoid feeding this particular troll. > I'd say that the fact that you're asking this should disqualify you > from ever working on documentation tools again... Your writing malicious crap like this ought to disqualify you from ever participating in python-dev discussions again. Fredrik, we all know that you you are a superb developer who makes wonderful contributions to Python. We also know that when faced with disagreement (and sometimes, seemingly, without any provocation at all) you are a malicious prick. -- David Goodger <http://python.net/~goodger> signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] r42015 - peps/trunk
> Author: david.goodger > Date: Thu Jan 12 04:33:16 2006 > New Revision: 42015 > > Modified: >peps/trunk/ (props changed) > Log: > add external link to Docutils public repo -- always up-to-date I just deleted the static copy of the "docutils" directory from the "peps" repository, and added in an external link (svn:externals 'docutils svn://svn.berlios.de/docutils/trunk/docutils/docutils'). This way, the external code should always be up-to-date. You may need to manually delete your peps/trunk/docutils directory to get this to work though -- SVN leaves subdirectories behind which hinder the externals update. Please let me know if this causes any problems. Thanks. -- David Goodger <http://python.net/~goodger> signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] r42015 - peps/trunk
[M.-A. Lemburg] > Question: why do we need docutils in the peps/trunk/ directory > in the first place ? It's a convenience, so that a separate Docutils download & install (& maintain) isn't necessary for those who process reST-format PEPs. -- David Goodger <http://python.net/~goodger> signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] r42015 - peps/trunk
On 1/12/06, M.-A. Lemburg <[EMAIL PROTECTED]> wrote: > Hmm, shouldn't these things be tracked under external/ ?! What do you mean exactly? A new "external" directory? SVN provides a built-in mechanism for tracking external repositories, via the "svn:externals" property, and that's what I used. -- David Goodger <http://python.net/~goodger> ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] r42015 - peps/trunk
On 1/12/06, M.-A. Lemburg <[EMAIL PROTECTED]> wrote: > I know, but I wouldn't expect SVN to query other servers > than svn.python.org inside the standard repository > directories. > > AFAIK, this is a first in the Python repository. True, and worth discussing. Luckily the PEPs repository is a low-traffic, non-core area, so it's not urgent. > Not sure if it's such a good idea. >From my point of view, it's a time-saver. No more manual updates! They were a pain, and rarely got done. > Branching and tagging > doesn't work with external resources in Subversion, > so things can become inconsistent. How so? The "svn:externals" property is treated the same as any other, and is copied along with everything else by "svn copy". > Also, what if you break the code in the berlios repo > or the server is not reachable ? If the code in the repo ever breaks, it will be fixed within minutes. The server being unreachable is only a problem for initial checkouts; updates will just keep the code that was already there. In my experience, the berlios.de SVN server has rarely been unreachable. If there's a problem, we can always back out the svn:externals property and install the package. That having been said, I do see the value of installing a packaged release. We just released Docutils 0.4 a few days ago; I could install that statically. An alternative is to use svn:externals to link to a specific revision (via the -r option); I could link to the 0.4 release revision. This would solve the repo-breakage issue, but not the server-unreachability issue. I don't think these issues are major, but I wouldn't mind terribly if we decide to go with a static install. > A release copy in the > external/ dir would solve all these issues. That's basically what we had before (except no explicity "external" directory), but it was always out of date. The "docutils" package was directly in the trunk, for ease of import by the pep2html.py front end (easy to work around, but why bother?). Another minor nit with the old way: updates "polluted" the python-checkins list. -- David Goodger <http://python.net/~goodger> ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] r42015 - peps/trunk
> [David Goodger] >> An alternative is to use svn:externals to link to a specific >> revision (via the -r option); [Tim Peters] > Yes. please. Done. -- David Goodger <http://python.net/~goodger> signature.asc Description: OpenPGP digital signature ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
