Re: Documentation suggestions

Discussion in 'Python' started by Michael Spencer, Dec 6, 2005.

  1. A.M. Kuchling wrote:
    > Here are some thoughts on reorganizing Python's documentation, with
    > one big suggestion.
    >


    Thanks for raising this topic, and for your on-going efforts in this field.

    I use the compiled html help file provided by PythonWin, which includes all the
    core documentation. I usually use the index interface, not the table of
    contents (the main exception is the LibRef, see below). In this form, the
    structure of the documentation is less important than how good the index is.
    Unfortunately, the "additional documentation', including, in particular, your re
    HowTo is linked, but not indexed and is therefore less accessible.

    > The tutorial seems to be in pretty good shape because Raymond

    ....
    Agreed, but as you say below, there may be friendlier forms available for the
    first-timer.

    ....
    > There's another struggle within the LibRef: is it a reference or a
    > tutorial?


    I want it to help answer questions of the form "What's in the the library that
    might help me do x?" For this case, some of the current section structure is
    not that helpful. "Miscellaneous Services", in particular, gives no clue to
    treasures it contains. I would prefer, for example, to see the data structure
    modules: collections, heapq, array etc... given their own section.
    Documentation/testing, cmd/options might be other candidates to draw together
    currently related material more meaningfully.

    Does it list methods in alphabetical order so you can look
    > them up, or does it list them in a pedagogically useful order? I
    > think it has to be a reference;


    A reference, yes, but not necessarily alphabetical if another organization is
    more communicative. itertools is a good example where alphabetic presentation
    makes perfect sense, since the functions are more-or-less peers; the math
    functions are usefully classified by topic; textwrap presents most commonly-used
    functions first; several modules document classes before convenience functions.
    Each of these has its merits, and I don't see a lot of mileage in trying to
    standardize them, given how varied modules are. However, whatever the reference
    structure, examples add significantly to the value to me.

    ....

    > I suspect the Achilles' heel of the docs is the Language Reference.
    > Put aside the fact that it's not up to date with new-style classes and
    > other stuff; that would be fixable with some effort.
    >


    > To some degree, the guide is trying to be very formal; it's written
    > like a specification for an implementor, not a document that people
    > would read through. But there's no other way for people to learn
    > about all the special object methods like __add__; the tutorial can't
    > cover them all, and the LibRef doesn't describe them. So the newbie
    > is stuck.


    I find very little of value to me in the Language Ref. Special methods are the
    crucial exception. Perhaps they, together with a description of class semantics
    (including metaclasses and descriptors) could be moved to the Built-in types
    section of the LibRef, where some related material is already.

    I don't know whether the rest of the Language reference is of use to
    implementers, but given the proliferation of implementations beyond Cpython
    (Jython, IronPython, pypy) I would speculate that a formal specification is now
    more important rather than less. However, perhaps it would be possible to
    express the specification more succinctly via tests instead of a manual.

    ....
    >
    > Perhaps we need a friendlier counterpart to the RefGuide, something
    > like the 20-page introduction to Python at the beginning of Beazley's
    > Essential Reference:


    I did't know this source, but I just skimmed it at
    http://www.amazon.com/gp/reader/0735709017/ref=sib_dp_pt/103-1276064-0751851#reader-page
    (not sure if this is a session link), and I agree it's a very clear
    introduction. Probably better first reading than the existing tutorial.

    ....


    Michael
    Michael Spencer, Dec 6, 2005
    #1
    1. Advertising

  2. Michael Spencer wrote:
    > A.M. Kuchling wrote:
    >
    >> Here are some thoughts on reorganizing Python's documentation, with
    >> one big suggestion.
    >>

    >
    > Thanks for raising this topic, and for your on-going efforts in this field.
    >
    > I use the compiled html help file provided by PythonWin, which includes
    > all the core documentation. I usually use the index interface, not the
    > table of contents (the main exception is the LibRef, see below). In
    > this form, the structure of the documentation is less important than how
    > good the index is. Unfortunately, the "additional documentation',
    > including, in particular, your re HowTo is linked, but not indexed and
    > is therefore less accessible.
    >
    >> The tutorial seems to be in pretty good shape because Raymond

    >
    > ....
    > Agreed, but as you say below, there may be friendlier forms available
    > for the first-timer.
    >
    > ....
    >
    >> There's another struggle within the LibRef: is it a reference or a
    >> tutorial?

    >
    >
    > I want it to help answer questions of the form "What's in the the
    > library that might help me do x?" For this case, some of the current
    > section structure is not that helpful. "Miscellaneous Services", in
    > particular, gives no clue to treasures it contains. I would prefer, for
    > example, to see the data structure modules: collections, heapq, array
    > etc... given their own section. Documentation/testing, cmd/options might
    > be other candidates to draw together currently related material more
    > meaningfully.
    >
    > Does it list methods in alphabetical order so you can look
    >
    >> them up, or does it list them in a pedagogically useful order? I
    >> think it has to be a reference;

    >
    >
    > A reference, yes, but not necessarily alphabetical if another
    > organization is more communicative. itertools is a good example where
    > alphabetic presentation makes perfect sense, since the functions are
    > more-or-less peers; the math functions are usefully classified by topic;
    > textwrap presents most commonly-used functions first; several modules
    > document classes before convenience functions. Each of these has its
    > merits, and I don't see a lot of mileage in trying to standardize them,
    > given how varied modules are. However, whatever the reference
    > structure, examples add significantly to the value to me.
    >
    > ....
    >
    >> I suspect the Achilles' heel of the docs is the Language Reference.
    >> Put aside the fact that it's not up to date with new-style classes and
    >> other stuff; that would be fixable with some effort.
    >>

    >
    >> To some degree, the guide is trying to be very formal; it's written
    >> like a specification for an implementor, not a document that people
    >> would read through. But there's no other way for people to learn
    >> about all the special object methods like __add__; the tutorial can't
    >> cover them all, and the LibRef doesn't describe them. So the newbie
    >> is stuck.

    >
    >
    > I find very little of value to me in the Language Ref. Special methods
    > are the crucial exception. Perhaps they, together with a description of
    > class semantics (including metaclasses and descriptors) could be moved
    > to the Built-in types section of the LibRef, where some related material
    > is already.
    >
    > I don't know whether the rest of the Language reference is of use to
    > implementers, but given the proliferation of implementations beyond
    > Cpython (Jython, IronPython, pypy) I would speculate that a formal
    > specification is now more important rather than less. However, perhaps
    > it would be possible to express the specification more succinctly via
    > tests instead of a manual.
    >
    > ....
    >
    >>
    >> Perhaps we need a friendlier counterpart to the RefGuide, something
    >> like the 20-page introduction to Python at the beginning of Beazley's
    >> Essential Reference:

    >
    >
    > I did't know this source, but I just skimmed it at
    > http://www.amazon.com/gp/reader/0735709017/ref=sib_dp_pt/103-1276064-0751851#reader-page
    >
    > (not sure if this is a session link), and I agree it's a very clear
    > introduction. Probably better first reading than the existing tutorial.
    >
    > ....
    >
    >
    > Michael
    >

    I like the approach but more would be helpful for a current Python,
    especially with respect to types/classes. The book is based on Python 2.1.

    Colin W.
    Colin J. Williams, Dec 6, 2005
    #2
    1. Advertising

  3. On Tue, 06 Dec 2005 10:29:33 -0800,
    Michael Spencer <> wrote:
    > not that helpful. "Miscellaneous Services", in particular, gives no clue to
    > treasures it contains. I would prefer, for example, to see the data
    > structure modules: collections, heapq, array etc... given their own section.
    > Documentation/testing, cmd/options might be other candidates to draw together
    > currently related material more meaningfully.


    You're right; "Miscellaneous Services" is a grab-bag of stuff, and so
    are 'Generic OS Services' and 'Optional OS Services'. These chapters
    should be rearranged into more, smaller chapters.

    A patch for a draft reorganization is at http://www.python.org/sf/1375417

    --amk
    A.M. Kuchling, Dec 7, 2005
    #3
  4. A.M. Kuchling wrote:
    > On Tue, 06 Dec 2005 10:29:33 -0800,
    > Michael Spencer <> wrote:
    >> not that helpful. "Miscellaneous Services", in particular, gives no clue to
    >> treasures it contains. I would prefer, for example, to see the data
    >> structure modules: collections, heapq, array etc... given their own section.
    >> Documentation/testing, cmd/options might be other candidates to draw together
    >> currently related material more meaningfully.

    >
    > You're right; "Miscellaneous Services" is a grab-bag of stuff, and so
    > are 'Generic OS Services' and 'Optional OS Services'. These chapters
    > should be rearranged into more, smaller chapters.
    >
    > A patch for a draft reorganization is at http://www.python.org/sf/1375417
    >
    > --amk

    Thanks! That looks like a good start.

    I experimented with some more re-organization, but I don't see away to attach
    the resulting file in the SF comments, so I'll post it here instead.

    Michael



    % experimental re-organization of lib.tex,
    % from http://www.python.org/sf/1375417

    \tableofcontents

    % Chapter title:

    \input{libintro} % Introduction


    % =============
    % BUILT-INs
    % =============

    \input{libobjs} % Built-in Types, Exceptions and Functions
    \input{libfuncs}
    \input{libstdtypes}
    \input{libexcs}
    \input{libconsts}



    % =============
    % BASIC/GENERAL-PURPOSE OBJECTS
    % =============

    % General object services
    \input{libtypes}
    \input{libnew}
    \input{libweakref}
    \input{libcopy}
    \input{libpprint}
    \input{librepr}

    % Strings
    \input{libstrings} % String Services
    \input{libstring}
    \input{libre}
    \input{libreconvert}
    \input{libstruct} % also/better in File Formats?
    \input{libdifflib}
    \input{libfpformat}
    \input{libstringio}
    \input{libtextwrap}
    \input{libcodecs}
    \input{libunicodedata}
    \input{libstringprep}

    % Data types and structures
    %\input{libdata} % Data types and structures
    \input{libdatetime}
    \input{libcalendar}
    \input{libcollections}
    \input{libheapq}
    \input{libarray}
    \input{libsets}
    \input{libsched}
    \input{libmutex}
    \input{libqueue}
    \input{libuserdict} % From runtime. What happened to UserList and UserString?

    % Numeric/Mathematical modules
    \input{libdecimal}
    \input{libmath}
    \input{libcmath}
    \input{librandom}
    \input{libbisect} % is this needed here - more useful in Data types, like heapq?

    % Functions, Functional, Generators and Iterators
    \input{libitertools}
    \input{libfunctional}
    \input{liboperator} % from runtime - better with itertools and functional


    %\input{libmisc} % Miscellaneous Services


    % =============
    % DATA FORMATS
    % =============

    % % File formats
    \input{libcfgparser}
    \input{libnetrc}
    \input{librobotparser}
    \input{libcsv}
    \input{libstruct} % and in string?

    % Big move - include all the markup and internet formats here

    % MIME & email stuff
    \input{email}
    \input{libmailcap}
    \input{libmailbox}
    \input{libmhlib}
    \input{libmimetools}
    \input{libmimetypes}
    \input{libmimewriter}
    \input{libmimify}
    \input{libmultifile}
    \input{librfc822}

    % encoding stuff
    \input{libbase64}
    \input{libbinascii}
    \input{libbinhex}
    \input{libquopri}
    \input{libuu}
    \input{libxdrlib}

    \input{markup} % Structured Markup Processing Tools
    \input{libhtmlparser}
    \input{libsgmllib}
    \input{libhtmllib}
    \input{libpyexpat}
    \input{xmldom}
    \input{xmldomminidom}
    \input{xmldompulldom}
    \input{xmlsax}
    \input{xmlsaxhandler}
    \input{xmlsaxutils}
    \input{xmlsaxreader}
    % \input{libxmllib}

    \input{libcrypto} % Cryptographic Services
    \input{libhmac}
    \input{libhashlib}
    \input{libmd5}
    \input{libsha}

    % =============
    % FILE & DATABASE STORAGE
    % =============

    \input{liballos} % File-system services (XXX change header)
    \input{libos}
    \input{libposixpath} % os.path
    \input{libfileinput}
    \input{libstat}
    \input{libstatvfs}
    \input{libfilecmp}
    \input{libtempfile}
    \input{libglob}
    \input{libfnmatch}
    \input{liblinecache}
    \input{libshutil}
    \input{libdircache}

    % % Data compression and archiving
    \input{libzlib}
    \input{libgzip}
    \input{libbz2}
    \input{libzipfile}
    \input{libtarfile}

    %\input{libpersistence} % Persistent storage
    \input{libpickle}
    \input{libcopyreg} % really copy_reg % from runtime...
    \input{libshelve}
    \input{libmarshal}
    \input{libanydbm}
    \input{libwhichdb}
    \input{libdbm}
    \input{libgdbm}
    \input{libdbhash}
    \input{libbsddb}
    \input{libdumbdbm}


    % =============
    % OS
    % =============


    \input{liballos} % Generic Operating System Services
    \input{libtime}
    \input{libgetpass}
    \input{libcurses}
    \input{libascii} % curses.ascii
    \input{libcursespanel}
    \input{libplatform}
    \input{liberrno}

    % % Interprocess communication/networking
    \input{libsubprocess}
    \input{libsocket}
    \input{libsignal}
    \input{libpopen2}
    \input{libasyncore}
    \input{libasynchat}

    \input{libsomeos} % Optional Operating System Services
    \input{libselect}
    \input{libthread}
    \input{libthreading}
    \input{libdummythread}
    \input{libdummythreading}
    \input{libmmap}
    \input{libreadline}
    \input{librlcompleter}

    \input{libunix} % UNIX Specific Services
    \input{libposix}
    \input{libpwd}
    \input{libspwd}
    \input{libgrp}
    \input{libcrypt}
    \input{libdl}
    \input{libtermios}
    \input{libtty}
    \input{libpty}
    \input{libfcntl}
    \input{libpipes}
    \input{libposixfile}
    \input{libresource}
    \input{libnis}
    \input{libsyslog}
    \input{libcommands}


    % =============
    % NETWORK & COMMUNICATIONS
    % =============

    \input{internet} % Internet Protocols
    \input{libwebbrowser}
    \input{libcgi}
    \input{libcgitb}
    \input{liburllib}
    \input{liburllib2}
    \input{libhttplib}
    \input{libftplib}
    \input{libgopherlib}
    \input{libpoplib}
    \input{libimaplib}
    \input{libnntplib}
    \input{libsmtplib}
    \input{libsmtpd}
    \input{libtelnetlib}
    \input{liburlparse}
    \input{libsocksvr}
    \input{libbasehttp}
    \input{libsimplehttp}
    \input{libcgihttp}
    \input{libcookielib}
    \input{libcookie}
    \input{libxmlrpclib}
    \input{libsimplexmlrpc}
    \input{libdocxmlrpc}

    \input{netdata} % Internet Data Handling
    \input{libformatter}

    % =============
    % MULTIMEDIA
    % =============

    \input{libmm} % Multimedia Services
    \input{libaudioop}
    \input{libimageop}
    \input{libaifc}
    \input{libsunau}
    \input{libwave}
    \input{libchunk}
    \input{libcolorsys}
    \input{librgbimg}
    \input{libimghdr}
    \input{libsndhdr}
    \input{libossaudiodev}



    % =============
    % PROGRAM FRAMEWORKS/OPTIONS/GUI
    % =============
    \input{libgetopt}
    \input{liboptparse}
    \input{libcmd}
    \input{libshlex}
    \input{liblogging}
    \input{tkinter}
    % % Internationalization
    \input{libgettext}


    % =============
    % DEVELOPMENT TOOLS
    % =============
    % % Software development support
    \input{libpydoc}
    \input{libdoctest}
    \input{libunittest}
    \input{libtest}

    \input{libpdb} % The Python Debugger

    \input{libprofile} % The Python Profiler
    \input{libhotshot} % New profiler
    \input{libtimeit}


    % =============
    % PYTHON ENGINE
    % =============
    \input{libpython} % Python Runtime Services

    % Runtime services
    \input{libsys}
    \input{libbltin} % really __builtin__
    \input{libmain} % really __main__
    \input{libtraceback}
    \input{libinspect}
    \input{libgc}

    % Custom interpreter
    \input{libcode}
    \input{libcodeop}
    \input{librestricted} % Restricted Execution
    \input{librexec}
    \input{libbastion}

    % Runtime environment
    \input{libfpectl}
    \input{libatexit}
    \input{libsite}
    \input{libuser}
    \input{libfuture} % really __future__
    \input{libwarnings}
    \input{liblocale} % also in Internationalization

    % modules
    \input{libimp}
    \input{libzipimport}
    \input{libpkgutil}
    \input{libmodulefinder}


    % =============
    % PYTHON LANGUAGE & COMPILER
    % =============

    \input{language} % Python Language Services
    \input{libparser}
    \input{libsymbol}
    \input{libtoken}
    \input{libkeyword}
    \input{libtokenize}
    \input{libtabnanny}
    \input{libpyclbr}
    \input{libpycompile} % really py_compile
    \input{libcompileall}
    \input{libdis}
    \input{libpickletools}
    \input{distutils}

    \input{compiler} % compiler package


    % =============
    % OTHER PLATFORM-SPECIFIC STUFF
    % =============

    %\input{libamoeba} % AMOEBA ONLY

    %\input{libstdwin} % STDWIN ONLY

    \input{libsgi} % SGI IRIX ONLY
    \input{libal}
    \input{libcd}
    \input{libfl}
    \input{libfm}
    \input{libgl}
    \input{libimgfile}
    \input{libjpeg}
    %\input{libpanel}

    \input{libsun} % SUNOS ONLY
    \input{libsunaudio}

    \input{windows} % MS Windows ONLY
    \input{libmsvcrt}
    \input{libwinreg}
    \input{libwinsound}

    \appendix
    \input{libundoc}

    %\chapter{Obsolete Modules}
    %\input{libcmpcache}
    %\input{libcmp}
    %\input{libni}
    %\input{libregex}
    %\input{libregsub}

    \chapter{Reporting Bugs}
    \input{reportingbugs}

    \chapter{History and License}
    \input{license}
    Michael Spencer, Dec 7, 2005
    #4
  5. Michael Spencer

    Guest

    "Michael Spencer" <> wrote:
    > A.M. Kuchling wrote:
    > > On Tue, 06 Dec 2005 10:29:33 -0800,
    > > Michael Spencer <> wrote:
    > >> not that helpful. "Miscellaneous Services", in particular, gives no clue to
    > >> treasures it contains. I would prefer, for example, to see the data
    > >> structure modules: collections, heapq, array etc... given their own section.
    > >> Documentation/testing, cmd/options might be other candidates to draw together
    > >> currently related material more meaningfully.

    > >
    > > You're right; "Miscellaneous Services" is a grab-bag of stuff, and so
    > > are 'Generic OS Services' and 'Optional OS Services'. These chapters
    > > should be rearranged into more, smaller chapters.
    > >
    > > A patch for a draft reorganization is at http://www.python.org/sf/1375417
    > >
    > > --amk

    > Thanks! That looks like a good start.
    >
    > I experimented with some more re-organization, but I don't see away to attach
    > the resulting file in the SF comments, so I'll post it here instead.
    >
    > Michael

    --snip--
    > % =============
    > % BUILT-INs
    > % =============
    >
    > \input{libobjs} % Built-in Types, Exceptions and Functions
    > \input{libfuncs}
    > \input{libstdtypes}
    > \input{libexcs}
    > \input{libconsts}

    --snip--

    Is this intended as a standalone short term bandaid, or as
    part of a more serious attempt to fix the doc problems?

    The builtins section should be moved to the language
    reference manual. The material it documents is part
    of the language definition, not part of an add-on library.

    Worse, if it stays in the library reference manual, it will
    make it very difficult to fix the language reference manual,
    since core parts of the discussion of the language need
    to reference these builtins. Rather like a book on the
    history of World War 2 saying "For information on the
    D-day invasion, please refer to ...". Workable perhaps
    but not likely to impress anyone with the competance
    of its authors.

    There is long history of established prior art when it
    comes to documenting computer languages. Is it
    really necessary for Python to blaze new ground here?
    , Dec 7, 2005
    #5
  6. wrote:

    > The builtins section should be moved to the language
    > reference manual. The material it documents is part
    > of the language definition, not part of an add-on library.


    the standard library is not an add-on. you're confused.

    </F>
    Fredrik Lundh, Dec 7, 2005
    #6
  7. Michael Spencer

    Guest

    Fredrik Lundh wrote:
    > wrote:
    >
    > > The builtins section should be moved to the language
    > > reference manual. The material it documents is part
    > > of the language definition, not part of an add-on library.

    >
    > the standard library is not an add-on. you're confused.
    >
    > </F>


    Your probably talking about internal implementation.
    I'm talking about user's perception. A "python" that
    had a different set of builtins would not be python.
    That makes it more useful to view it as part of the
    language, not a library even if it happens to be
    implemented that way.
    , Dec 7, 2005
    #7
  8. wrote:

    > Fredrik Lundh wrote:
    > > wrote:
    > >
    > > > The builtins section should be moved to the language
    > > > reference manual. The material it documents is part
    > > > of the language definition, not part of an add-on library.

    > >
    > > the standard library is not an add-on. you're confused.

    >
    > Your probably talking about internal implementation.
    > I'm talking about user's perception. A "python" that
    > had a different set of builtins would not be python.
    > That makes it more useful to view it as part of the
    > language, not a library even if it happens to be
    > implemented that way.


    no, I'm talking about how things are used, not how things
    happen to look inside your head.

    you seem to think that everything that lives in the __builtin__
    module are fundamental parts of the language, but that any-
    thing that can be explicitly imported into a user module is an
    "add-on".

    that's not how things work. if you want to move "fundamental
    parts" to a different document, you have to move a lot more
    than just the functions in the __builtin__ module.

    </F>
    Fredrik Lundh, Dec 7, 2005
    #8
  9. Michael Spencer

    Ian Bicking Guest

    Fredrik Lundh wrote:
    > wrote:
    >
    > > The builtins section should be moved to the language
    > > reference manual. The material it documents is part
    > > of the language definition, not part of an add-on library.

    >
    > the standard library is not an add-on. you're confused.


    I think the point is that there is the core language, and from a user's
    perspective builtins and statements and syntax are all the same thing.
    When you import a module, it's more-or-less obvious where you find
    information about the module (the module index, of course). But
    "print", "sorted", and "list" are all equally "built in" in the mind of
    a new user. And frankly, though with experience I understand the
    categorization, I don't find it particularly compelling.

    A new and improved language reference document should deal with all of
    these together, I think.

    Ian
    Ian Bicking, Dec 7, 2005
    #9
  10. Ian Bicking wrote:

    > > the standard library is not an add-on. you're confused.

    >
    > I think the point is that there is the core language, and from a user's
    > perspective builtins and statements and syntax are all the same thing.
    > When you import a module, it's more-or-less obvious where you find
    > information about the module (the module index, of course). But
    > "print", "sorted", and "list" are all equally "built in" in the mind of
    > a new user.


    so are many standard modules (don't tell me that any real user will
    learn all the builtins before she writes her first import statement...)

    > A new and improved language reference document should deal with all of
    > these together, I think.


    wasn't the idea to get rid of the language reference altogether, and
    replace it with a better introduction ?

    </F>
    Fredrik Lundh, Dec 7, 2005
    #10
  11. Michael Spencer

    Guest

    Ian> I think the point is that there is the core language, and from a
    Ian> user's perspective builtins and statements and syntax are all the
    Ian> same thing. When you import a module, it's more-or-less obvious
    Ian> where you find information about the module (the module index, of
    Ian> course).

    I suspect I'd have a harder time living without the sys module than with
    many of the builtins. Then there's os, re, math, ... Some modules, like
    thread and sys, have to be linked into the interpreter. Are they "core" or
    "add on"? Once you start migrating stuff from the "add on" manual (Library
    Reference) to the "core" manual (Language Reference), where do you stop?

    Skip
    , Dec 7, 2005
    #11
  12. Michael Spencer

    Guest

    wrote:
    > Ian> I think the point is that there is the core language, and from a
    > Ian> user's perspective builtins and statements and syntax are all the
    > Ian> same thing. When you import a module, it's more-or-less obvious
    > Ian> where you find information about the module (the module index, of
    > Ian> course).
    >
    > I suspect I'd have a harder time living without the sys module than with
    > many of the builtins. Then there's os, re, math, ... Some modules, like
    > thread and sys, have to be linked into the interpreter. Are they "core" or
    > "add on"? Once you start migrating stuff from the "add on" manual (Library
    > Reference) to the "core" manual (Language Reference), where do you stop?


    I think a natural dividing line is "import". If you import it, it
    is in the Library refrence. If you don't, it is in the Language
    reference. The exception is sys, which could be
    - documented fully in the Language ref. as an exception.
    - documented as necessary in the Languge ref, and fully in
    the Library ref.

    Thread would be documented in the Library reference because
    - the fact that is is linked in the interpreter is invisable to me
    (the user).
    - I have to do "import thread" to use it.

    Sorry about the term "add-on". I know that is the wrong
    word, but couldn't think of anything better.
    , Dec 8, 2005
    #12
  13. Michael Spencer

    Guest

    Fredrik Lundh wrote:
    > Ian Bicking wrote:
    >
    > > > the standard library is not an add-on. you're confused.

    > >
    > > I think the point is that there is the core language, and from a user's
    > > perspective builtins and statements and syntax are all the same thing.
    > > When you import a module, it's more-or-less obvious where you find
    > > information about the module (the module index, of course). But
    > > "print", "sorted", and "list" are all equally "built in" in the mind of
    > > a new user.

    >
    > so are many standard modules (don't tell me that any real user will
    > learn all the builtins before she writes her first import statement...)


    If this is a reference manual (as opposed by a tutorial)
    then the order information is presented in is not guided
    by a user's order of use. It just needs to be presented
    coherently (so you can find what they want quickly (with
    the relevant material all together), and hopefuly in an
    order that minimizes forward references (so it can be
    read sequentially if desired). This order had been
    worked out by many previous language manuals and
    I think is equally usable for Python.

    > > A new and improved language reference document should deal with all of
    > > these together, I think.

    >
    > wasn't the idea to get rid of the language reference altogether, and
    > replace it with a better introduction ?


    Can an introduction provide the information the language
    reference provides (or maybe I am misunderstanding what
    you mean by introduction.)
    , Dec 8, 2005
    #13
  14. wrote:

    > > wasn't the idea to get rid of the language reference altogether, and
    > > replace it with a better introduction ?

    >
    > Can an introduction provide the information the language
    > reference provides (or maybe I am misunderstanding what
    > you mean by introduction.)


    from the post that opened this thread:

    "Perhaps we need a friendlier counterpart to the RefGuide, something
    like the 20-page introduction to Python at the beginning of Beazley's
    Essential Reference:

    * go over the statements one-by-one
    * go over the basic types and their methods
    * go over object semantics
    * cover some of the lexical material in chapter 2 of the RefGuide
    * overarching principles: go into a fair bit of detail, but
    not every corner case; make the text readable, not meticulously
    precise."

    </F>
    Fredrik Lundh, Dec 8, 2005
    #14
  15. On Thu, 8 Dec 2005 01:32:08 +0100, "Fredrik Lundh" <> wrote:

    > wrote:
    >
    >> > wasn't the idea to get rid of the language reference altogether, and
    >> > replace it with a better introduction ?

    >>
    >> Can an introduction provide the information the language
    >> reference provides (or maybe I am misunderstanding what
    >> you mean by introduction.)

    >
    >from the post that opened this thread:
    >
    > "Perhaps we need a friendlier counterpart to the RefGuide, something
    > like the 20-page introduction to Python at the beginning of Beazley's
    > Essential Reference:
    >
    > * go over the statements one-by-one
    > * go over the basic types and their methods
    > * go over object semantics
    > * cover some of the lexical material in chapter 2 of the RefGuide
    > * overarching principles: go into a fair bit of detail, but
    > not every corner case; make the text readable, not meticulously
    > precise."
    >

    I think discussion of python reference materials is not complete without
    mentioning the quick-reference at (e.g. for python 2.4)

    http://rgruet.free.fr/PQR24/PQR2.4.html

    which BTW is accessible from the python.org docs page (http://www.python.org/doc/)
    via the "Quick Reference Guide (off-site)" link to the quikc ref home page (other goodies too).

    http://rgruet.free.fr/#QuickRef

    IMO the first link above (or for whatever current version) would be nice to find
    on the documentation sidebar of python's home page (http://www.python.org/),
    maybe right below the "Beginner's Guide" link.

    (it's gotten nicer, so maybe I'll snag me a fresh offline-usable copy, and
    update my Start>Help menu ;-)

    Regards,
    Bengt Richter
    Bengt Richter, Dec 8, 2005
    #15
  16. Michael Spencer

    Ben Sizer Guest

    wrote:
    > wrote:
    > > I suspect I'd have a harder time living without the sys module than with
    > > many of the builtins. Then there's os, re, math, ... Some modules, like
    > > thread and sys, have to be linked into the interpreter. Are they "core" or
    > > "add on"? Once you start migrating stuff from the "add on" manual (Library
    > > Reference) to the "core" manual (Language Reference), where do you stop?

    >
    > I think a natural dividing line is "import". If you import it, it
    > is in the Library refrence.


    Exactly. I'm surprised this is even open to debate. Any built-in which
    will work without an import statement - no matter how it's implemented
    - should be documented as if it was part of the core language. And
    anything you have to explicitly ask for using import, should be in the
    library reference under the name of the module or package you're
    importing. In terms of knowing where to look for information on a
    feature, this is the most sensible approach. In no other language would
    I look to the library reference for something which does not appear on
    the surface to come from a library.

    As an aside, personally I rarely touch the sys module. I use re,
    random, threading, and even xml.dom.minidom more than sys.

    --
    Ben Sizer
    Ben Sizer, Dec 8, 2005
    #16
  17. On Wed, 07 Dec 2005 12:58:36 -0800,
    Michael Spencer <> wrote:
    > I experimented with some more re-organization, but I don't see away
    > to attach the resulting file in the SF comments, so I'll post it
    > here instead.


    I've attached your file to the patch. Some comments:

    > \input{libstruct} % also/better in File Formats?


    Struct operates on string input and produces string output, so I think
    it belongs in the string chapter where you've placed it. We need to
    add more cross-references, so File Formats should mention struct as a
    related module.

    > % Functions, Functional, Generators and Iterators
    > \input{libitertools}
    > \input{libfunctional}
    > \input{liboperator} % from runtime - better with itertools and functional


    > % encoding stuff

    ...
    > \input{libxdrlib}


    XDR is really more similar to struct or marshal, I think, but on the
    other hand it is an Internet RFC (#1014). Not sure where it should go...

    > \input{libsomeos} % Optional Operating System Services
    > \input{libselect}
    > \input{libthread}
    > \input{libthreading}
    > \input{libdummythread}
    > \input{libdummythreading}
    > \input{libmmap}
    > \input{libreadline}
    > \input{librlcompleter}




    > \input{libunix} % UNIX Specific Services
    > \input{libposix}
    > \input{libpwd}
    > \input{libspwd}
    > \input{libgrp}
    > \input{libcrypt}
    > \input{libdl}
    > \input{libtermios}
    > \input{libtty}
    > \input{libpty}
    > \input{libfcntl}
    > \input{libpipes}
    > \input{libposixfile}
    > \input{libresource}
    > \input{libnis}
    > \input{libsyslog}
    > \input{libcommands}
    >


    > \input{internet} % Internet Protocols


    I wonder if the Internet chapter should be split into "HTTP/Web Tools"
    (webbrowser, cgi, cgitb, httplib, urllib) and "Non-Web Protocols"
    (ftplib, gopherlib, smtp, all the rest).

    > \input{distutils}


    Distutils should probably be in Program Frameworks. Or it could just
    have a chapter of its own, or maybe there are enough modules for an
    "Application Support" chapter.

    --amk
    A.M. Kuchling, Dec 8, 2005
    #17
  18. Michael Spencer

    Guest

    amk> I wonder if the Internet chapter should be split into "HTTP/Web
    amk> Tools" (webbrowser, cgi, cgitb, httplib, urllib) and "Non-Web
    amk> Protocols" (ftplib, gopherlib, smtp, all the rest).

    Note that cgitb works just fine in a non-web environment. I would actually
    prefer it be renamed ("fancytb"?) and then stuck wherever the traceback
    module docs go.

    >> \input{distutils}


    amk> Distutils should probably be in Program Frameworks. Or it could just
    amk> have a chapter of its own, or maybe there are enough modules for an
    amk> "Application Support" chapter.

    There are currently 46 module index entries for the various parts of
    distutils. I think it would be helpful to reduce that number a bit...

    Skip
    , Dec 8, 2005
    #18
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Kenneth McDonald
    Replies:
    2
    Views:
    729
  2. A.M. Kuchling

    Documentation suggestions

    A.M. Kuchling, Dec 6, 2005, in forum: Python
    Replies:
    62
    Views:
    1,257
    A.M. Kuchling
    Dec 13, 2005
  3. Replies:
    3
    Views:
    279
    Paul Rubin
    Dec 7, 2005
  4. Fredrik Lundh

    Re: Documentation suggestions

    Fredrik Lundh, Dec 6, 2005, in forum: Python
    Replies:
    11
    Views:
    534
    A.M. Kuchling
    Dec 12, 2005
  5. kpd
    Replies:
    7
    Views:
    331
    Dennis Lee Bieber
    Mar 5, 2006
Loading...

Share This Page