From cbarton at metavr.com  Fri Aug 10 06:52:56 2007
From: cbarton at metavr.com (Campbell Barton)
Date: Fri, 10 Aug 2007 14:52:56 +1000
Subject: [Doc-SIG] Best way to contribute
Message-ID: <46BBEF28.4040506@metavr.com>

Hi, Id like to contribute some changes to the C/API docs

http://docs.python.org/api/api.html

I mailed my changes to docs at python.org but only got an auto-reply.

Would the best way to submit changes be to checkout Python, edit the tex 
file in the Doc/api directory and submit a patch?

Should I submit the patch to the tracker or to this list?

-- 
Campbell J Barton (ideasman42)

From fdrake at acm.org  Fri Aug 10 07:30:38 2007
From: fdrake at acm.org (Fred Drake)
Date: Fri, 10 Aug 2007 01:30:38 -0400
Subject: [Doc-SIG] Best way to contribute
In-Reply-To: <46BBEF28.4040506@metavr.com>
References: <46BBEF28.4040506@metavr.com>
Message-ID: <D35CFC0E-8A5C-4B4A-AA93-AB912169F5ED@acm.org>

On Aug 10, 2007, at 12:52 AM, Campbell Barton wrote:
> Hi, Id like to contribute some changes to the C/API docs
>
> http://docs.python.org/api/api.html
>
> I mailed my changes to docs at python.org but only got an auto-reply.

There have been some substantial changes in how the docs at python.org  
address is handled recently, so resending would be fine, but we can  
answer here as well.

We're about to move away from using LaTeX for the documentation, so  
LaTeX patches probably aren't the best approach any more.

Perhaps you could re-send the changes to docs at python.org, or send  
them here.  We do appreciate your interest in contributing.


   -Fred

-- 
Fred Drake   <fdrake at acm.org>




From skip at pobox.com  Sat Aug 11 15:41:09 2007
From: skip at pobox.com (skip at pobox.com)
Date: Sat, 11 Aug 2007 08:41:09 -0500
Subject: [Doc-SIG] British or American spellings?
Message-ID: <18109.48245.315505.370898@montanaro.dyndns.org>


In the core Python documentation should we strive for some consistency in
spelling where British and American English differ (e.g., "favor"
vs. "favour")?

Skip

From lac at openend.se  Sat Aug 11 17:45:31 2007
From: lac at openend.se (Laura Creighton)
Date: Sat, 11 Aug 2007 17:45:31 +0200
Subject: [Doc-SIG] British or American spellings?
In-Reply-To: Message from skip@pobox.com of "Sat, 11 Aug 2007 08:41:09 CDT."
	<18109.48245.315505.370898@montanaro.dyndns.org> 
References: <18109.48245.315505.370898@montanaro.dyndns.org> 
Message-ID: <200708111545.l7BFjVho025530@theraft.openend.se>

In a message of Sat, 11 Aug 2007 08:41:09 CDT, skip at pobox.com writes:
>
>In the core Python documentation should we strive for some consistency in
>spelling where British and American English differ (e.g., "favor"
>vs. "favour")?
>
>Skip

I don't think so.  There are actually more than 2 variants -- Canadian
English (mostly-like-British-English but with a few differences),
Australian English (ditto, but a different set of differences), and
so on and so forth.  If you come to English as a second language, and
read a lot of English on the web, your internal model of 'what is
the way to spell this' contains words from each dictionary, and amounts
to a personal dialect.  (There are many people I know who like to
spell 'centre' like this, but spell theatre 'theater'.  Whether
you like 'anaethetist', 'anesthetist', 'anesthesiologist' or
'anaesthesioligist' has a lot to do with what it was called where you
studied medicine, rather than where you learned how to speak English.)
Pretty much everybody I know speaks of 'computer programs', not
'computer programmes', even those people who are writing them as
part of their job in implementing some sort of governmental 
programme.

Thus not only do actual speakers of 'British English' differ in how
they spell things, they also differ from what a conscientuous 
native speaker of non-British English -- or a program -- believes
is correct British English spelling.

The upshot is that you cannot automate the process -- run tests every
night against what Open Office thinks is proper spelling, for instance --
without getting both false positives and false negatives.  Open Office
would like you to believe that in British English there are no words
ending in ize -- but my OED lists 'synthesize' first -- but also allows
'synthesise' (which is how I spell it) and 'synthetize' and 'synthetise'.
Those last 2 just look like typos to me.

So, all you can realistically do is ask people to do as good a job as
they can.  The question then becomes, do we want to create the
language police to go over what is produced.  This is what many
journals do, and is one function of a professional editor -- somebody
who is so certain that his or her usage is correct that by changing
everything to suit their internal stadard, they will produce a
result which is pleasing to their readership (or its publishers)?

I think that this would be a bad idea. Having perfectly correct
spelling 'corrected' by a person or program who thought they knew
better is one of the great aggravations of modern life. (The usage of
'aggravation' to mean 'exasperation', by the way, is not accepted as
correct usage some places, where they only want 'something that makes
a thing worse'.  Most aggravating!)  I think that we risk alienating
and losing volunteers if we create the language police.

Plus I don't mind finding evidence that this is a community effort,
and that there are Americans using python. :-)  I suspect that they
don't mind discovering that non-Americans use python, too.  

I think that anything more than 'try to be consistent with the spelling
that went before when modifying a page' is asking too much.  And I
wouldn't worry too much if even that turns out to be too hard to notice.

Laura


From aahz at pythoncraft.com  Sat Aug 11 20:11:28 2007
From: aahz at pythoncraft.com (Aahz)
Date: Sat, 11 Aug 2007 11:11:28 -0700
Subject: [Doc-SIG] British or American spellings?
In-Reply-To: <200708111545.l7BFjVho025530@theraft.openend.se>
References: <18109.48245.315505.370898@montanaro.dyndns.org>
	<200708111545.l7BFjVho025530@theraft.openend.se>
Message-ID: <20070811181128.GA17744@panix.com>

On Sat, Aug 11, 2007, Laura Creighton wrote:
>
> I think that anything more than 'try to be consistent with the spelling
> that went before when modifying a page' is asking too much.  And I
> wouldn't worry too much if even that turns out to be too hard to notice.

+1
-- 
Aahz (aahz at pythoncraft.com)           <*>         http://www.pythoncraft.com/

"And if that makes me an elitist...I couldn't be happier."  --JMS

From lewiemann at gmail.com  Mon Aug 13 00:40:54 2007
From: lewiemann at gmail.com (Lea Wiemann)
Date: Sun, 12 Aug 2007 18:40:54 -0400
Subject: [Doc-SIG] Best way to contribute
In-Reply-To: <D35CFC0E-8A5C-4B4A-AA93-AB912169F5ED@acm.org>
References: <46BBEF28.4040506@metavr.com>
	<D35CFC0E-8A5C-4B4A-AA93-AB912169F5ED@acm.org>
Message-ID: <55af6d7f0708121540h3322cf2fr1dbe0de54d7367e@mail.gmail.com>

On 8/10/07, Fred Drake <fdrake at acm.org> wrote:

> We're about to move away from using LaTeX for the documentation, so
> LaTeX patches probably aren't the best approach any more.

Regarding the move to reStructuredText, even at the point where the
tool-chain is stable, it will take some time till the migration
actually happens.  I'd assume that an *optimistic* time-line for
moving to the complete documentation to reStructuredText is a couple
months from now.

So don't discourage contribtions in LaTeX too early. ;-)  We'll have
(more or less automatic) conversion tools in place anyway.

Best wishes,

    Lea

From alan.green at cardboard.nu  Mon Aug 13 02:21:13 2007
From: alan.green at cardboard.nu (Alan Green)
Date: Mon, 13 Aug 2007 10:21:13 +1000
Subject: [Doc-SIG] Best way to contribute
In-Reply-To: <46BBEF28.4040506@metavr.com>
References: <46BBEF28.4040506@metavr.com>
Message-ID: <c6fc3cde0708121721s5e37486buad29c46c3e79fd3b@mail.gmail.com>

Hi Campbell,

I contributed a small amount of documentation, several years ago. It
took many months before someone had the time to pick up the change,
review it and approve it.

If it's something you don't need feedback on, I'd counsel patience. If
you do need feedback, then it might be best to get in touch with some
of the developers working in the area that you'd like to document.

Cheers,

Alan.

On 8/10/07, Campbell Barton <cbarton at metavr.com> wrote:
> Hi, Id like to contribute some changes to the C/API docs
>
> http://docs.python.org/api/api.html
>
> I mailed my changes to docs at python.org but only got an auto-reply.
>
> Would the best way to submit changes be to checkout Python, edit the tex
> file in the Doc/api directory and submit a patch?
>
> Should I submit the patch to the tracker or to this list?
>
> --
> Campbell J Barton (ideasman42)
> _______________________________________________
> Doc-SIG maillist  -  Doc-SIG at python.org
> http://mail.python.org/mailman/listinfo/doc-sig
>


-- 
Alan Green
alang at bright-green.com - http://bright-green.com

From skip at pobox.com  Mon Aug 13 03:27:49 2007
From: skip at pobox.com (skip at pobox.com)
Date: Sun, 12 Aug 2007 20:27:49 -0500
Subject: [Doc-SIG] Best way to contribute
In-Reply-To: <c6fc3cde0708121721s5e37486buad29c46c3e79fd3b@mail.gmail.com>
References: <46BBEF28.4040506@metavr.com>
	<c6fc3cde0708121721s5e37486buad29c46c3e79fd3b@mail.gmail.com>
Message-ID: <18111.45973.500013.936131@montanaro.dyndns.org>


    Campbell> Hi, Id like to contribute some changes to the C/API docs
    Campbell> 
    Campbell> http://docs.python.org/api/api.html
    Campbell> 
    Campbell> I mailed my changes to docs at python.org but only got an
    Campbell> auto-reply.
    Campbell>
    Campbell> Would the best way to submit changes be to checkout Python,
    Campbell> edit the tex file in the Doc/api directory and submit a patch?
    Campbell> 
    Campbell> Should I submit the patch to the tracker or to this list?

    Alan> I contributed a small amount of documentation, several years
    Alan> ago. It took many months before someone had the time to pick up
    Alan> the change, review it and approve it.

Any patches should be submitted to SourceForge with attached diffs to the
Subversion repositry (in the relatively near future the new Roundup-based
tracker will replace SF).  There are many people who read and respond to
those submissions who aren't subscribed to this mailing list.

-- 
Skip Montanaro - skip at pobox.com - http://www.webfast.com/~skip/

From g.brandl at gmx.net  Mon Aug 13 08:13:31 2007
From: g.brandl at gmx.net (Georg Brandl)
Date: Mon, 13 Aug 2007 08:13:31 +0200
Subject: [Doc-SIG] Best way to contribute
In-Reply-To: <55af6d7f0708121540h3322cf2fr1dbe0de54d7367e@mail.gmail.com>
References: <46BBEF28.4040506@metavr.com>	<D35CFC0E-8A5C-4B4A-AA93-AB912169F5ED@acm.org>
	<55af6d7f0708121540h3322cf2fr1dbe0de54d7367e@mail.gmail.com>
Message-ID: <f9osq9$kjm$1@sea.gmane.org>

Lea Wiemann schrieb:
> On 8/10/07, Fred Drake <fdrake at acm.org> wrote:
> 
>> We're about to move away from using LaTeX for the documentation, so
>> LaTeX patches probably aren't the best approach any more.
> 
> Regarding the move to reStructuredText, even at the point where the
> tool-chain is stable, it will take some time till the migration
> actually happens.  I'd assume that an *optimistic* time-line for
> moving to the complete documentation to reStructuredText is a couple
> months from now.

I wouldn't think so :)

If you look in svn.python.org/projects/doctools, the replacement trees are
already there and waiting to be moved into python/Doc -- they are maintained
in parallel at the moment. Conversion to HTML is stable and the Web version
won't be needed for many months. By that time, a PDF conversion will also be
in place.

I had in mind to write a switch announcement in the next few days.

Georg

-- 
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.


From lewiemann at gmail.com  Thu Aug 16 20:21:50 2007
From: lewiemann at gmail.com (Lea Wiemann)
Date: Thu, 16 Aug 2007 14:21:50 -0400
Subject: [Doc-SIG] Best way to contribute
In-Reply-To: <f9osq9$kjm$1@sea.gmane.org>
References: <46BBEF28.4040506@metavr.com>	<D35CFC0E-8A5C-4B4A-AA93-AB912169F5ED@acm.org>	<55af6d7f0708121540h3322cf2fr1dbe0de54d7367e@mail.gmail.com>
	<f9osq9$kjm$1@sea.gmane.org>
Message-ID: <46C495BE.5000901@gmail.com>

Georg Brandl wrote:

> the replacement trees are
> already there and waiting to be moved into python/Doc

Woah, I'm sorry I completely missed that -- I hadn't been following
python-dev.  Anyways, thanks for the great work, I'm glad to see it
switched over!

Best wishes,

    Lea

From andre.roberge at gmail.com  Fri Aug 17 06:54:21 2007
From: andre.roberge at gmail.com (Andre Roberge)
Date: Fri, 17 Aug 2007 01:54:21 -0300
Subject: [Doc-SIG] Great job on new docs; small error report included
Message-ID: <7528bcdd0708162154g4207b8f6r7c11b992824bb40a@mail.gmail.com>

Hi everyone,

First of all, congrats to Georg Brandl and whomever else helped him in
getting the docs in the new format; it looks *much* better.

In perusing the doc (using a development version of Crunchy) I found
some small mistakes in the way that it was formatted.  I've included
my notes in a rather cryptic fashion - if needed (and if I get the
time), I could probably get a proper bug report but I'd rather not
wait until then and risk forgetting about it.

==========
in both
http://docs.python.org/dev/tutorial/controlflow.html
and
http://docs.python.org/dev/3.0/tutorial/controlflow.html

last code example
-----begin code-----
>>> def my_function():
...     """Do nothing, but document it.
...
...     No, really, it doesn't do anything....
   """
...     pass
...
>>> print my_function.__doc__
Do nothing, but document it.

   No, really, it doesn't do anything.
-----------end-------

Note how the continuation line "..." are misplaced after the word "anything".
(The source file is ok - this is *much* easier to see on the page than
in this email).  This seems to be a parsing bug in the tool used to
create the html page.


=======
http://docs.python.org/dev/tutorial/stdlib.html
http://docs.python.org/dev/3.0/tutorial/stdlib.html

under Internet access
-----
>>> import urllib2
>>> for line in urllib2.urlopen('http://tycho.usno.navy.mil/cgi-bin/timer.pl'):
...     if 'EST' in line or 'EDT' in line:  # look for Eastern Time
...         print line

<BR>Nov. 25, 09:43:32 PM EST

>>> import smtplib
>>> server = smtplib.SMTP('localhost')
>>> server.sendmail('soothsayer at example.org', 'jcaesar at example.org',
"""To: jcaesar at example.org
From: soothsayer at example.org

Beware the Ides of March.
""")
>>> server.quit()
------------

The "..." are missing before each line of the triple quoted string.
(The error is in the source file)

Aside: I could not get the second example to work on my Mac (it gave
me a traceback when I tried to create a server)
=================
Suggestion for changes:
in http://docs.python.org/dev/3.0/tutorial/controlflow.html  (twice on
that page)
http://docs.python.org/dev/3.0/tutorial/errors.html  (once on that page)

There is no need to define raw_input(); simply use input(), which will
effectively have the same role that raw_input() currently has.

Hope it helps,

Andr? (Roberge)

From g.brandl at gmx.net  Fri Aug 17 07:59:21 2007
From: g.brandl at gmx.net (Georg Brandl)
Date: Fri, 17 Aug 2007 07:59:21 +0200
Subject: [Doc-SIG] Great job on new docs; small error report included
In-Reply-To: <7528bcdd0708162154g4207b8f6r7c11b992824bb40a@mail.gmail.com>
References: <7528bcdd0708162154g4207b8f6r7c11b992824bb40a@mail.gmail.com>
Message-ID: <fa3dfl$2ls$1@sea.gmane.org>

Andre Roberge schrieb:
> Hi everyone,
> 
> First of all, congrats to Georg Brandl and whomever else helped him in
> getting the docs in the new format; it looks *much* better.

Thanks!

> In perusing the doc (using a development version of Crunchy) I found
> some small mistakes in the way that it was formatted.  I've included
> my notes in a rather cryptic fashion - if needed (and if I get the
> time), I could probably get a proper bug report but I'd rather not
> wait until then and risk forgetting about it.
> 
> ==========
> in both
> http://docs.python.org/dev/tutorial/controlflow.html
> and
> http://docs.python.org/dev/3.0/tutorial/controlflow.html
> 
> last code example
> -----begin code-----
>>>> def my_function():
> ...     """Do nothing, but document it.
> ...
> ...     No, really, it doesn't do anything....
>    """
> ...     pass
> ...
>>>> print my_function.__doc__
> Do nothing, but document it.
> 
>    No, really, it doesn't do anything.
> -----------end-------
> 
> Note how the continuation line "..." are misplaced after the word "anything".
> (The source file is ok - this is *much* easier to see on the page than
> in this email).  This seems to be a parsing bug in the tool used to
> create the html page.

Indeed, it's a bug in the console lexer of Pygments, should be fixed now
(and the docs will be correct next time a rebuild of that file triggers).

> =======
> http://docs.python.org/dev/tutorial/stdlib.html
> http://docs.python.org/dev/3.0/tutorial/stdlib.html
> 
> under Internet access
> -----
>>>> import urllib2
>>>> for line in urllib2.urlopen('http://tycho.usno.navy.mil/cgi-bin/timer.pl'):
> ...     if 'EST' in line or 'EDT' in line:  # look for Eastern Time
> ...         print line
> 
> <BR>Nov. 25, 09:43:32 PM EST
> 
>>>> import smtplib
>>>> server = smtplib.SMTP('localhost')
>>>> server.sendmail('soothsayer at example.org', 'jcaesar at example.org',
> """To: jcaesar at example.org
> From: soothsayer at example.org
> 
> Beware the Ides of March.
> """)
>>>> server.quit()
> ------------
> 
> The "..." are missing before each line of the triple quoted string.
> (The error is in the source file)
> 
> Aside: I could not get the second example to work on my Mac (it gave
> me a traceback when I tried to create a server)

The smtplib example requires a mailserver running on localhost. This is
not too common for desktop machines, so I added a note.

> =================
> Suggestion for changes:
> in http://docs.python.org/dev/3.0/tutorial/controlflow.html  (twice on
> that page)
> http://docs.python.org/dev/3.0/tutorial/errors.html  (once on that page)
> 
> There is no need to define raw_input(); simply use input(), which will
> effectively have the same role that raw_input() currently has.

Indeed.

> Hope it helps,

Always,
Georg

-- 
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.


From alcides at ideias3.com  Sat Aug 18 16:52:46 2007
From: alcides at ideias3.com (Alcides Fonseca)
Date: Sat, 18 Aug 2007 15:52:46 +0100
Subject: [Doc-SIG] Python Documentation OpenSearch
In-Reply-To: <230a59a50708180641x7c031aa1r4aceef1bd499e626@mail.gmail.com>
References: <230a59a50708180641x7c031aa1r4aceef1bd499e626@mail.gmail.com>
Message-ID: <230a59a50708180752v5c661662vbfd126853dae9406@mail.gmail.com>

First of all congrats on the new documentation system. I love the design.

Just a tiny suggestion: I'd like to add this search to firefox/flock/ie7...
and unfortunately the website doesn't contain  OpenSearch.

I was wondering if you can add it.

I've posted a simple way of adding it to any website:
http://alcides.ideias3.com/blog/56

But if you want, I can make that for you.

Please reply to me also, because I didn't subscribed the mailing list.

Thanks

Alcides
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.python.org/pipermail/doc-sig/attachments/20070818/6572f93d/attachment.htm