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 _______________________________________________ Doc-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/doc-sig
