Request for guidance on documentation
I have now made two passes through the docs for the new curses module, correcting minor errors and adding explanatory material. The question is what to do next, and that turns on whether discursive tutorial sections are are considered fit for inclusion in the library reference. If they are, I'll rewrite the existing curses HOWTO and slide it in there, perhaps adding some stuff from the "Introduction to ncurses" HTML tutorial I wrote lo those many moons ago for the ncurses distribution. Can anybody point me at the TeX source for the curses HOWTO? Also, I'm not sure where the material for curses.textbox should go. New section? Or a subsection in the curses document? -- <a href="http://www.tuxedo.org/~esr">Eric S. Raymond</a> 'Faith' means not _wanting_ to know what is true. -- Nietzsche, Der Antichrist
On Thu, Jul 27, 2000 at 05:38:59PM -0400, Eric S. Raymond wrote:
correcting minor errors and adding explanatory material. The question is what to do next, and that turns on whether discursive tutorial sections are are considered fit for inclusion in the library reference.
That's up to Fred to decide. I suspect the answer is no, since it would make the library reference too large and ungainly if every section had a tutorial. Regular expressions, socket programming, and XML processing are all sizable topics in their own right that would be covered. I will re-raise the idea of adding the HOWTOs to the documentation subtree, though; Fred & I have discussed it before, and decided not to for reasons that I can't remember.
Can anybody point me at the TeX source for the curses HOWTO?
I'l mail it to you privately.
Also, I'm not sure where the material for curses.textbox should go. New section? Or a subsection in the curses document?
Probably a subsection, but again, Fred has final ruling on that. --amk
On Thu, Jul 27, 2000 at 05:38:59PM -0400, Eric S. Raymond wrote:
correcting minor errors and adding explanatory material. The question is what to do next, and that turns on whether discursive tutorial sections are are considered fit for inclusion in the library reference.
Andrew Kuchling writes:
That's up to Fred to decide. I suspect the answer is no, since it would make the library reference too large and ungainly if every
Hey, it's large & unweildy now. ;-) But I think you're right. Improving the curses HOWTO separately from the reference documentation makes sense.
I will re-raise the idea of adding the HOWTOs to the documentation subtree, though; Fred & I have discussed it before, and decided not to for reasons that I can't remember.
I don't recall exactly, but I think it had a bit to do with the release scheduling (perhaps this was when the documentation was release lockstep with CPython?) and editorial control -- as long as you're willing to act as HOWTO editor, you should be able to release regardless of whether there's anything new to release in the standard library. Eric again:
Also, I'm not sure where the material for curses.textbox should go. New section? Or a subsection in the curses document?
curses.textbox should be documented in a \section like any other module. It can be placed in libcurses.tex along with the other curses-related modules. Is curses.wrapper documented, or is it an implementation detail? -Fred -- Fred L. Drake, Jr. <fdrake at beopen.com> BeOpen PythonLabs Team Member
On Fri, 28 Jul 2000, Fred L. Drake, Jr. wrote:
I don't recall exactly, but I think it had a bit to do with the release scheduling (perhaps this was when the documentation was release lockstep with CPython?) and editorial control -- as long as you're willing to act as HOWTO editor, you should be able to release regardless of whether there's anything new to release in the standard library.
Neither of those reasons are enough not to put the HOWTOs in the CVS tree. Editors can keep the version in the CVS current via the patch manager, and release them as they need to. However, people who d/l Python will automatically download the HOWTOs. Think of perldoc lol (lists of lists) -- definitely "HOWTO" material, but in the Perl standard docs. -- Moshe Zadka <moshez@math.huji.ac.il> There is no IGLU cabal. http://advogato.org/person/moshez
Moshe Zadka writes:
Neither of those reasons are enough not to put the HOWTOs in the CVS tree. Editors can keep the version in the CVS current via the patch manager, and release them as they need to. However, people who d/l Python will automatically download the HOWTOs. Think of perldoc lol (lists of lists) -- definitely "HOWTO" material, but in the Perl standard docs.
I'm happy to have them under CVS; I think the big issue is *where*. I'm not convinced they belong in the same portion of the tree as the standard documentation. Here's a thought: we currently have dist/ src/ Doc/ Instead, we could have: dist/ docs/ howto/ standard/ src/ The howto/ tree could be the howto collection Andrew maintains, and standard/ could be the XML version of the documentation once I've converted everything (which just shouldn't been in src/ to begin with). The documentation tools would become a separate component (which I've been thinking about for a while now), used by both the standard documentation and the howtos. Another option would be to simply create a new SourceForge project for HOWTO documents. That would be Andrew's baby, so would have to be his preferred approach. -Fred -- Fred L. Drake, Jr. <fdrake at beopen.com> BeOpen PythonLabs Team Member
On Fri, Jul 28, 2000 at 10:06:00AM -0400, Fred L. Drake, Jr. wrote:
Instead, we could have: dist/ docs/ howto/ standard/ src/
If you want to do this reorganization, fine, but it seems like it'll be a long way off. Why not just put them in nondist/doc/howto? (Other documentation could be put in nondist/doc -- I could even dig out the grimoire and add it, if someone would be interested in updating and maintaining it.) On the other hand, the documentation maintainers might be a different set of people from code maintainers, and we might not want them checking in code changes, so having the docs as a completely separate project would allow finer control of this. On the third hand, we do have the python-checkins list to keep an eye on what's happening. I'd vote for nondist/doc/howto. --amk
On the other hand, the documentation maintainers might be a different set of people from code maintainers, and we might not want them checking in code changes, so having the docs as a completely separate project would allow finer control of this. On the third hand, we do have the python-checkins list to keep an eye on what's happening.
I'd vote for nondist/doc/howto.
Short term, definitely. Long term, I feel that making it a separate SF project might be a good idea. --Guido van Rossum (home page: http://www.pythonlabs.com/~guido/)
Fred L. Drake, Jr. <fdrake@beopen.com>:
I'm happy to have them under CVS; I think the big issue is *where*. I'm not convinced they belong in the same portion of the tree as the standard documentation. Here's a thought: we currently have
dist/ src/ Doc/
Instead, we could have:
dist/ docs/ howto/ standard/ src/
The howto/ tree could be the howto collection Andrew maintains, and standard/ could be the XML version of the documentation once I've converted everything (which just shouldn't been in src/ to begin with).
This seems eminently reasonable to me. -- <a href="http://www.tuxedo.org/~esr">Eric S. Raymond</a> "They that can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety." -- Benjamin Franklin, Historical Review of Pennsylvania, 1759.
Moshe Zadka <moshez@math.huji.ac.il>:
Neither of those reasons are enough not to put the HOWTOs in the CVS tree. Editors can keep the version in the CVS current via the patch manager, and release them as they need to. However, people who d/l Python will automatically download the HOWTOs. Think of perldoc lol (lists of lists) -- definitely "HOWTO" material, but in the Perl standard docs.
I agree. There should be a HOWTO directory in the CVS tree. -- <a href="http://www.tuxedo.org/~esr">Eric S. Raymond</a> Strict gun laws are about as effective as strict drug laws...It pains me to say this, but the NRA seems to be right: The cities and states that have the toughest gun laws have the most murder and mayhem. -- Mike Royko, Chicago Tribune
Fred L. Drake, Jr. <fdrake@beopen.com>:
curses.textbox should be documented in a \section like any other module. It can be placed in libcurses.tex along with the other curses-related modules.
Ah! I didn't realize multiple suggestions could live in the same file under our conventions. Guess I'll have to go reread the Documentation HOWTO.
Is curses.wrapper documented, or is it an implementation detail?
I'll document it. -- <a href="http://www.tuxedo.org/~esr">Eric S. Raymond</a> No matter how one approaches the figures, one is forced to the rather startling conclusion that the use of firearms in crime was very much less when there were no controls of any sort and when anyone, convicted criminal or lunatic, could buy any type of firearm without restriction. Half a century of strict controls on pistols has ended, perversely, with a far greater use of this weapon in crime than ever before. -- Colin Greenwood, in the study "Firearms Control", 1972
Eric S. Raymond writes:
Ah! I didn't realize multiple suggestions could live in the same file under our conventions. Guess I'll have to go reread the Documentation HOWTO.
Multiple sections can live in the same file if they are sufficiently tightly related. For example, curses and curses.ascii, pyexpat and pyexpat.errors, pickle and cPickle, StringIO and cStringIO. I don't know that this is discussed in "Documenting Python," but should be; I'll fix that for Python 2.0. -Fred -- Fred L. Drake, Jr. <fdrake at beopen.com> BeOpen PythonLabs Team Member
On Sat, 29 Jul 2000, Fred L. Drake, Jr. wrote:
Eric S. Raymond writes:
Ah! I didn't realize multiple suggestions could live in the same file under our conventions. Guess I'll have to go reread the Documentation HOWTO.
Multiple sections can live in the same file if they are sufficiently tightly related. For example, curses and curses.ascii, pyexpat and pyexpat.errors, pickle and cPickle, StringIO and cStringIO. I don't know that this is discussed in "Documenting Python," but should be; I'll fix that for Python 2.0.
Let me just say what Fred said in a different way: from the processing engine POV, there's just *one file* with lots of include directives. The division into file is just to make life easier for us -- so if two sections are related, it's easier to keep them in the same file. -- Moshe Zadka <moshez@math.huji.ac.il> There is no IGLU cabal. http://advogato.org/person/moshez
Moshe Zadka writes:
Let me just say what Fred said in a different way: from the processing engine POV, there's just *one file* with lots of include directives. The division into file is just to make life easier for us -- so if two sections are related, it's easier to keep them in the same file.
Almost, but not quite. The division into files allows us to reorganize the sections into chapters differently with simple edits; I've found that very useful a couple of times! -Fred -- Fred L. Drake, Jr. <fdrake at beopen.com> BeOpen PythonLabs Team Member
participants (6)
-
Andrew Kuchling -
Andrew Kuchling -
Eric S. Raymond -
Fred L. Drake, Jr. -
Guido van Rossum -
Moshe Zadka