[Doc-SIG] Creating howto directory in Python CVS

[A.M. Kuchling]

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