From amk at amk.ca  Mon Aug 29 03:46:50 2005
From: amk at amk.ca (A.M. Kuchling)
Date: Sun, 28 Aug 2005 21:46:50 -0400
Subject: [Doc-SIG] Creating howto directory in Python CVS
Message-ID: <20050829014650.GA17077@rogue.amk.ca>

I'd like to (finally) check in the HOWTOs into the main Python CVS;
I've begun writing new ones like the Unicode HOWTO, and it would be
good if more people had access to them.  

Since they probably won't be added to the documentation set, they
should go in nondist/ in CVS.  nondist/howto/ seems too high-level,
though; any objection to creating nondist/doc/ and putting a howto/
directory in it?  Then we have a natural place to add other
documentation that isn't part of the core set.

--amk


From fdrake at acm.org  Mon Aug 29 05:26:14 2005
From: fdrake at acm.org (Fred L. Drake, Jr.)
Date: Sun, 28 Aug 2005 23:26:14 -0400
Subject: [Doc-SIG] Creating howto directory in Python CVS
In-Reply-To: <20050829014650.GA17077@rogue.amk.ca>
References: <20050829014650.GA17077@rogue.amk.ca>
Message-ID: <200508282326.15142.fdrake@acm.org>

On Sunday 28 August 2005 21:46, A.M. Kuchling wrote:
 > I'd like to (finally) check in the HOWTOs into the main Python CVS;
 > I've begun writing new ones like the Unicode HOWTO, and it would be
 > good if more people had access to them.

I'm fine with this, but we should probably figure out a better way to deal 
with publishing them.  Using SourceForge for this hasn't been the most 
successful spot, I suspect.

 > Since they probably won't be added to the documentation set, they

Actually, they'd probably get a lot more maintenance if they had more 
exposure.  Perhaps there should be a directory like Doc/howtos/, and the 
documentation index for distributed docs would include a link to a secondary 
index that exposes those documents.  There could then be a link there to the 
"latest version" of the howto docs published on python.org.


  -Fred

-- 
Fred L. Drake, Jr.   <fdrake at acm.org>

From amk at amk.ca  Mon Aug 29 15:28:07 2005
From: amk at amk.ca (A.M. Kuchling)
Date: Mon, 29 Aug 2005 09:28:07 -0400
Subject: [Doc-SIG] Creating howto directory in Python CVS
In-Reply-To: <200508282326.15142.fdrake@acm.org>
References: <20050829014650.GA17077@rogue.amk.ca>
	<200508282326.15142.fdrake@acm.org>
Message-ID: <20050829132807.GA19783@rogue.amk.ca>

On Sun, Aug 28, 2005 at 11:26:14PM -0400, Fred L. Drake, Jr. wrote:
> I'm fine with this, but we should probably figure out a better way to deal 
> with publishing them.  Using SourceForge for this hasn't been the most 
> successful spot, I suspect.

Actually they're on amk.ca now.  People find them pretty well -- type
"regular expression" into Google and the HOWTO is the top hit; it's
the second hit for "regular expressions".  I'd have no objection to
moving them to python.org hosting, but no pressing desire to do so.

My motivations:
	* it would be nice to have more people scanning the edits I make.
	* Python CVS would be more visible to people making translations.
	  (People occasionally send me e-mails asking for the LaTeX source.)

> exposure.  Perhaps there should be a directory like Doc/howtos/, and the 
> documentation index for distributed docs would include a link to a secondary 
> index that exposes those documents.  There could then be a link there to the 
> "latest version" of the howto docs published on python.org.

One complication: I'm writing new HOWTOs in ReST, though the older
ones are still in LaTeX.  This would introduce a new requirement to
the documentation toolchain; it might be easier to put them in
nondist/ and not the main docs.  But I'll defer to you; where would
you like me to create a howto/ directory?

--amk

From fdrake at acm.org  Mon Aug 29 19:30:02 2005
From: fdrake at acm.org (Fred L. Drake, Jr.)
Date: Mon, 29 Aug 2005 13:30:02 -0400
Subject: [Doc-SIG] Creating howto directory in Python CVS
In-Reply-To: <20050829132807.GA19783@rogue.amk.ca>
References: <20050829014650.GA17077@rogue.amk.ca>
	<200508282326.15142.fdrake@acm.org>
	<20050829132807.GA19783@rogue.amk.ca>
Message-ID: <200508291330.03227.fdrake@acm.org>

On Monday 29 August 2005 09:28, A.M. Kuchling wrote:
 > Actually they're on amk.ca now.  People find them pretty well -- type
 > "regular expression" into Google and the HOWTO is the top hit; it's
 > the second hit for "regular expressions".  I'd have no objection to
 > moving them to python.org hosting, but no pressing desire to do so.

Ok, that's really an unrelated issue anyway.  If people find them without 
problems, there's no need to change it and break links.

 > My motivations:
 >  * it would be nice to have more people scanning the edits I make.
 >  * Python CVS would be more visible to people making translations.
 >    (People occasionally send me e-mails asking for the LaTeX source.)

Both would be nice, indeed.

 > One complication: I'm writing new HOWTOs in ReST, though the older
 > ones are still in LaTeX.  This would introduce a new requirement to
 > the documentation toolchain; it might be easier to put them in
 > nondist/ and not the main docs.  But I'll defer to you; where would
 > you like me to create a howto/ directory?

It's only a requirement if we actually format them using the existing 
toolchain.  :-)  It is something to keep in mind.

How about this:  Create Doc/howto/ as part of the main checkout, so the howtos 
come along with the rest of the docs.  This addresses your motivations, 
regardless of how the howtos get formatted or published.  We can deal with 
toolchain issues as time allows.  It's likely we'd add the LaTeX documents to 
the build early, and the ReST docs once the toolchain grows the necessary 
bits.

I think this would work out just fine for Python and the docs.

I note that for the "What's New" document you like to retain authorship rather 
than succumb to group maintenance.  I'd like that not to be the case for the 
howtos, especially since the starting documents come from a variety of 
contributors.


  -Fred

-- 
Fred L. Drake, Jr.   <fdrake at acm.org>

From lac at strakt.com  Mon Aug 29 19:38:15 2005
From: lac at strakt.com (Laura Creighton)
Date: Mon, 29 Aug 2005 19:38:15 +0200
Subject: [Doc-SIG] Creating howto directory in Python CVS
In-Reply-To: Message from "Fred L. Drake, Jr." <fdrake@acm.org> 
	of "Mon, 29 Aug 2005 13:30:02 EDT." <200508291330.03227.fdrake@acm.org> 
References: <20050829014650.GA17077@rogue.amk.ca>
	<200508282326.15142.fdrake@acm.org>
	<20050829132807.GA19783@rogue.amk.ca>
	<200508291330.03227.fdrake@acm.org> 
Message-ID: <200508291738.j7THcFSV004240@ratthing-b246.strakt.com>

In a message of Mon, 29 Aug 2005 13:30:02 EDT, "Fred L. Drake, Jr." writes:
>On Monday 29 August 2005 09:28, A.M. Kuchling wrote:
> > Actually they're on amk.ca now.  People find them pretty well -- type
> > "regular expression" into Google and the HOWTO is the top hit; it's
> > the second hit for "regular expressions".  I'd have no objection to
> > moving them to python.org hosting, but no pressing desire to do so.
>
>Ok, that's really an unrelated issue anyway.  If people find them without
> 
>problems, there's no need to change it and break links.

I had a small problem with reg-exp how to the other day.
what decided me against report it to amk was the idea that I didn't
want to bother him personally about a personal page.  If they were
on python.org I would have sent my 'wish you had explained this
better' bit and my example of how to for sure.

Laura


From amk at amk.ca  Mon Aug 29 20:02:35 2005
From: amk at amk.ca (A.M. Kuchling)
Date: Mon, 29 Aug 2005 14:02:35 -0400
Subject: [Doc-SIG] Creating howto directory in Python CVS
In-Reply-To: <200508291330.03227.fdrake@acm.org>
References: <20050829014650.GA17077@rogue.amk.ca>
	<200508282326.15142.fdrake@acm.org>
	<20050829132807.GA19783@rogue.amk.ca>
	<200508291330.03227.fdrake@acm.org>
Message-ID: <20050829180235.GB23157@rogue.amk.ca>

On Mon, Aug 29, 2005 at 01:30:02PM -0400, Fred L. Drake, Jr. wrote:
> How about this: Create Doc/howto/ as part of the main checkout, so
> the howtos come along with the rest of the docs.  This addresses
> your motivations, regardless of how the howtos get formatted or
> published.  We can deal with toolchain issues as time allows.  

OK.  I'll commit that this evening.  I'll then make a brief pass over
the documents to check they're OK for 2.5 (e.g. the sorting howto
should mention the key= argument added in 2.4).

> It's likely we'd add the LaTeX documents to the build early, and the ReST
> docs once the toolchain grows the necessary bits.

That's reasonable.  I'll commit them all just to keep things in one
place, and the default target will leave the ReST versions
unprocessed; I can run "make rest" or similar to build my HTML
versions.

> I note that for the "What's New" document you like to retain
> authorship rather than succumb to group maintenance.  I'd like that
> not to be the case for the howtos, especially since the starting
> documents come from a variety of contributors.

It's a fair point, but one I'd like to discuss some more.  The problem
with group ownership is that it holds you back from making larger
reorganizations; I wouldn't feel able to sit up and reorganize, say,
dist.tex, because I don't "own" that document, or to rip material out
because I personally feel it's uninteresting.  

It also means there isn't really an author's voice in the text.  I own
"What's New", and Raymond seems to effectively own the tutorial these
days, so each of us has a free hand in rearranging and rewriting them.
In the "What's New" there are changes I don't describe because I think
they're not worth mentioning to a regular user, and I often make
recommendations that are personal opinion, not stemming from PEP 8 or
a BDFL ruling or some 'official' source.  For example: in the PEP342
section I just added, I suggest always using parens in code with yield
expressions such as i=(yield 12) because IMHO the code is clearer and
I don't want to explain the *actual* rules for when parens are
required and not.

I would be happy to allow other people to commit changes to the howtos
with my name on them, as long as I can turn around and *rip out their
changes* if the changes don't match my editorial goal for that
particular document.  If someone else wants to maintain a howto, then
their goals would take precedence, of course, and they can then rip
out any edits I happened to make.  Fred, are you OK with an
arrangement like that?

I haven't taken over the ones without my name on them; those can
either be taken over by their authors, if they're willing, or left as
they are.

--amk

From fdrake at acm.org  Mon Aug 29 20:03:39 2005
From: fdrake at acm.org (Fred L. Drake, Jr.)
Date: Mon, 29 Aug 2005 14:03:39 -0400
Subject: [Doc-SIG] Creating howto directory in Python CVS
In-Reply-To: <200508291738.j7THcFSV004240@ratthing-b246.strakt.com>
References: <20050829014650.GA17077@rogue.amk.ca>
	<200508291330.03227.fdrake@acm.org>
	<200508291738.j7THcFSV004240@ratthing-b246.strakt.com>
Message-ID: <200508291403.39641.fdrake@acm.org>

On Monday 29 August 2005 13:38, Laura Creighton wrote:
 > I had a small problem with reg-exp how to the other day.
 > what decided me against report it to amk was the idea that I didn't
 > want to bother him personally about a personal page.  If they were
 > on python.org I would have sent my 'wish you had explained this
 > better' bit and my example of how to for sure.

Good point.  I suspect many people would rather complain to an "anonymous" 
address or issue collector.  Being able to report problems in the Python 
collector or to the docs at python.org address might help gather suggestions 
and error reports.


  -Fred

-- 
Fred L. Drake, Jr.   <fdrake at acm.org>

From ianb at colorstudy.com  Mon Aug 29 20:09:22 2005
From: ianb at colorstudy.com (Ian Bicking)
Date: Mon, 29 Aug 2005 13:09:22 -0500
Subject: [Doc-SIG] Creating howto directory in Python CVS
In-Reply-To: <20050829180235.GB23157@rogue.amk.ca>
References: <20050829014650.GA17077@rogue.amk.ca>	<200508282326.15142.fdrake@acm.org>	<20050829132807.GA19783@rogue.amk.ca>	<200508291330.03227.fdrake@acm.org>
	<20050829180235.GB23157@rogue.amk.ca>
Message-ID: <43134F52.8010803@colorstudy.com>

A.M. Kuchling wrote:
>>I note that for the "What's New" document you like to retain
>>authorship rather than succumb to group maintenance.  I'd like that
>>not to be the case for the howtos, especially since the starting
>>documents come from a variety of contributors.
> 
> 
> It's a fair point, but one I'd like to discuss some more.  The problem
> with group ownership is that it holds you back from making larger
> reorganizations; I wouldn't feel able to sit up and reorganize, say,
> dist.tex, because I don't "own" that document, or to rip material out
> because I personally feel it's uninteresting.  

Maybe it would be better to identify yourself as "editor" instead of 
"author".


-- 
Ian Bicking  /  ianb at colorstudy.com  /  http://blog.ianbicking.org

From amk at amk.ca  Mon Aug 29 20:16:36 2005
From: amk at amk.ca (A.M. Kuchling)
Date: Mon, 29 Aug 2005 14:16:36 -0400
Subject: [Doc-SIG] Creating howto directory in Python CVS
In-Reply-To: <200508291738.j7THcFSV004240@ratthing-b246.strakt.com>
References: <20050829014650.GA17077@rogue.amk.ca>
	<200508282326.15142.fdrake@acm.org>
	<20050829132807.GA19783@rogue.amk.ca>
	<200508291330.03227.fdrake@acm.org>
	<200508291738.j7THcFSV004240@ratthing-b246.strakt.com>
Message-ID: <20050829181636.GA23400@rogue.amk.ca>

On Mon, Aug 29, 2005 at 07:38:15PM +0200, Laura Creighton wrote:
> want to bother him personally about a personal page.  If they were
> on python.org I would have sent my 'wish you had explained this
> better' bit and my example of how to for sure.

Really?  Hm, I should add a paragraph that encourages people to submit
comments.  (I expect comments from everything I publish on the web,
though I don't necessarily answer them -- instead they pile up in a
mailbox until the next time I work on whatever the page is.)

And I *would* be interested in hearing your suggestion.  I'd like to
revisit the Regex howto in a few months, adding exercises and whatever
other updates I can think of.

--amk

From lac at strakt.com  Mon Aug 29 22:56:48 2005
From: lac at strakt.com (Laura Creighton)
Date: Mon, 29 Aug 2005 22:56:48 +0200
Subject: [Doc-SIG] Creating howto directory in Python CVS
In-Reply-To: Message from "Fred L. Drake, Jr." <fdrake@acm.org> 
	of "Mon, 29 Aug 2005 14:03:39 EDT." <200508291403.39641.fdrake@acm.org> 
References: <20050829014650.GA17077@rogue.amk.ca>
	<200508291330.03227.fdrake@acm.org>
	<200508291738.j7THcFSV004240@ratthing-b246.strakt.com>
	<200508291403.39641.fdrake@acm.org> 
Message-ID: <200508292056.j7TKumb7024144@theraft.strakt.com>

In a message of Mon, 29 Aug 2005 14:03:39 EDT, "Fred L. Drake, Jr." writes:
>On Monday 29 August 2005 13:38, Laura Creighton wrote:
> > I had a small problem with reg-exp how to the other day.
> > what decided me against report it to amk was the idea that I didn't
> > want to bother him personally about a personal page.  If they were
> > on python.org I would have sent my 'wish you had explained this
> > better' bit and my example of how to for sure.
>
>Good point.  I suspect many people would rather complain to an "anonymous
>" 
>address or issue collector.  Being able to report problems in the Python 
>collector or to the docs at python.org address might help gather suggesti
>ons 
>and error reports.
>
>
>  -Fred
>
>-- 
>Fred L. Drake, Jr.   <fdrake at acm.org>

By the way, my use case was 'having split your thing nicely up into
6 named groups, how do you write them out again as the same groups
in a different order'

Ie take a file:

dog animal bites
fish animal doesn't
book object doesn't

and turn it into:

an animal that bites is a dog
an animal that doesn't bite is a fish
an object that doesn't bite is a book
 ....

I actually was stuffing docstrings from python2.4 into Pypy.  :-)

There must be a way to do this which deosn't involve assigning to
python variables, but i never found it in time.  But after futzing
around a bunch, i concluded that the regexp how to was short on
how to actually batch precess a file making a set of substutions based
on the matches you found.

Which I wish I knew how to do better.

thanks all,
Laura

From lac at strakt.com  Mon Aug 29 23:02:54 2005
From: lac at strakt.com (Laura Creighton)
Date: Mon, 29 Aug 2005 23:02:54 +0200
Subject: [Doc-SIG] Creating howto directory in Python CVS
In-Reply-To: Message from "A.M. Kuchling" <amk@amk.ca> of "Mon,
	29 Aug 2005 14:16:36 EDT." <20050829181636.GA23400@rogue.amk.ca> 
References: <20050829014650.GA17077@rogue.amk.ca>
	<200508282326.15142.fdrake@acm.org>
	<20050829132807.GA19783@rogue.amk.ca>
	<200508291330.03227.fdrake@acm.org>
	<200508291738.j7THcFSV004240@ratthing-b246.strakt.com>
	<20050829181636.GA23400@rogue.amk.ca> 
Message-ID: <200508292102.j7TL2s7c025279@theraft.strakt.com>

In a message of Mon, 29 Aug 2005 14:16:36 EDT, "A.M. Kuchling" writes:
>On Mon, Aug 29, 2005 at 07:38:15PM +0200, Laura Creighton wrote:
>> want to bother him personally about a personal page.  If they were
>> on python.org I would have sent my 'wish you had explained this
>> better' bit and my example of how to for sure.
>
>Really?  Hm, I should add a paragraph that encourages people to submit
>comments.  (I expect comments from everything I publish on the web,
>though I don't necessarily answer them -- instead they pile up in a
>mailbox until the next time I work on whatever the page is.)

You already have this paragraph.  I read it.  I wrote the mail to 
you.  I then said, oh what the heck, it is a small change and I
already know the man is so damn busy with more important things
that my tiny addition looks like whining.  And I do not want amk
to think that I am a whiner.  So I never sent it to you.

I have no idea how often this happens, but I am willing to admit it,
which I figure is sort of rare.

Laura