[Tutor] Documentation concerns.

[Jorge Godoy]

Magnus Lyck=E5 <magnus@thinkware.se> writes:

> Perhaps the Python documentation needs to contain even more
> suggestions to try out and experiment with features.

IMHO it would benefit a lot of examples.

E.g.:  Perl's first page on the CGI module:

----------------------------------------------------------------------
CGI(3)                User Contributed Perl Documentation               C=
GI(3)

NAME
       CGI - Simple Common Gateway Interface Class

SYNOPSIS
         # CGI script that creates a fill-out form
         # and echoes back its values.

         use CGI qw/:standard/;
         print header,
               start_html('A Simple Example'),
               h1('A Simple Example'),
               start_form,
               "What's your name? ",textfield('name'),p,
               "What's the combination?", p,
               checkbox_group(-name=3D>'words',
                              -values=3D>['eenie','meenie','minie','moe']=
,
                              -defaults=3D>['eenie','minie']), p,
               "What's your favorite color? ",
               popup_menu(-name=3D>'color',
                          -values=3D>['red','green','blue','chartreuse'])=
,p,
               submit,
               end_form,
               hr;

          if (param()) {
              print "Your name is",em(param('name')),p,
                    "The keywords are: ",em(join(", ",param('words'))),p,
                    "Your favorite color is ",em(param('color')),
                    hr;
          }

ABSTRACT
       This perl library uses perl5 objects to make it easy to create Web
----------------------------------------------------------------------

The SYNOPSIS gives you examples of how to use objects, how they
work. The documentation goes on and explain the more intricated uses
of such a module.


Python's CGI first page:

----------------------------------------------------------------------
Python Library Documentation: module cgi

NAME
    cgi - Support module for CGI (Common Gateway Interface) scripts.

FILE
    /usr/lib/python2.2/cgi.py

DESCRIPTION
    This module defines a number of utilities for use by CGI scripts
    written in Python.

CLASSES
    FieldStorage
    MiniFieldStorage
    UserDict.UserDict
        FormContentDict
            FormContent
            SvFormContentDict
                InterpFormContentDict

    class FieldStorage
     |  Store a sequence of fields, reading multipart/form-data.
     |
     |  This class provides naming, typing, files stored on disk, and
     |  more.  At the top level, it is accessible like a dictionary, whos=
e
     |  keys are the field names.  (Note: None can occur as a field name.=
)
     |  The items are either a Python list (if there's multiple values) o=
r
     |  another FieldStorage or MiniFieldStorage object.  If it's a singl=
e
     |  object, it has the following attributes:
     |
     |  name: the field name, if specified; otherwise None
     |
     |  filename: the filename, if specified; otherwise None; this is the
     |      client side filename, *not* the file name on which it is
----------------------------------------------------------------------

There's no indication on, how to import the module ("import cgi"?
"from cgi import *"?), on how to start a simple cgi with it, etc.=20


I try putting usage examples on my docs. They help me reminding how to
use something --- it doesn't matter how good is the description,
sometimes you just want to see one example using the function --- and
will certainly help other people too.



See you,
--=20
Godoy.    <godoy@metalab.unc.edu>