[Doc-SIG] Re: ping Ping
Sat, 17 Mar 2001 12:30:05 -0800 (PST)
On Sat, 17 Mar 2001, Edward Welbourne wrote:
> Hello, Ping, where are you ?
> We need your response to our gabblings.
I'm sorry i haven't had time to really particpate in this discussion
this past week. I've been watching all the e-mail go by but haven't
formulated my responses yet. I was originally considering writing my
own PEP if i could find the time.
Thanks for the invitation.
My general feeling about all of the syntax ideas that have been going
back and forth is that i'm a little afraid of their complexity. When
i have a moment i'll try to get a handle on what rules are currently
on the table and see how many there are, but i'll definitely want to
keep them minimal.
> ah. So: Edward, Tibs and I, who have done this week's talking, all
> agree on a position which puts `API docs' into the source file and puts
> tutorials, reference docs, etc. elsewhere.
I will maintain the opposing position for now, as devil's advocate.
Here are some points to consider, just off the top of my head:
- Just to be clear, the suggestion on the table is only to
move the library ref manual into the modules, not the
language reference or anything like that.
- If documentation lives in the modules, we can guarantee
that any user of the module has the information they
need to understand and use it properly.
- Allowing extended documentation in a module does not
preclude other people from writing other documents,
tutorials, books, etc. on a particular topic.
- If documentation for a module doesn't live in the module
itself, how will a user find it? One source of motivation
for this suggestion was running "perldoc CGI" -- having a
copy of CGI.pm guarantees that you have an instantly
available and fairly comprehensive description of all the
things you can do with CGI.pm.
- Keeping modules and associated docs in the same file helps
to ensure that the two are in sync when you distribute or
edit the file. (It's not possible to have different
versions of the code and the docs at the same time; it's
less likely that someone will check in changes to one
without updating the other, etc.)