[Patches] [ python-Patches-788509 ] Glossary

SourceForge.net noreply at sourceforge.net
Mon Sep 29 10:29:37 EDT 2003


Patches item #788509, was opened at 2003-08-14 00:04
Message generated for change (Comment added) made by fdrake
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=305470&aid=788509&group_id=5470

Category: Documentation
Group: Python 2.3
Status: Open
Resolution: None
Priority: 6
Submitted By: Skip Montanaro (montanaro)
Assigned to: Fred L. Drake, Jr. (fdrake)
Summary: Glossary

Initial Comment:
The topic of iterables came up on c.l.py recently.  One 

of the participants mentioned that "iterable" isn't listed

in the index of either the language or library reference

manuals.  A quick search didn't yield any obvious 

definition of what an iterable is.  (There may be something

I missed.  I wasn't terribly thorough in my search.)



The attached patch attempts to fix that omission by adding

a glossary to the language reference manual.  Maybe it 

should be a separate manual.  It doesn't seem like it

belongs in the tutorial, and the library reference manual

doesn't cover the language itself.



Keep, toss, throw darts at, or pass back for action.



S



----------------------------------------------------------------------

>Comment By: Fred L. Drake, Jr. (fdrake)
Date: 2003-09-29 10:29

Message:
Logged In: YES 
user_id=3066

The hyperlinks are now fixed.  It's up to Skip if he wants

to maintain a version of this in 2.3.x, but too late for 2.3.2.



Skip, please close this when you're satisfied (with the

state of the glossary).

----------------------------------------------------------------------

Comment By: Raymond Hettinger (rhettinger)
Date: 2003-09-28 03:37

Message:
Logged In: YES 
user_id=80475

Now, the hyperlinks need to be fixed.  They are all relative

to the tutorial directory.



Also, consider backporting the glossary to 2.3.2.

----------------------------------------------------------------------

Comment By: Skip Montanaro (montanaro)
Date: 2003-09-24 13:01

Message:
Logged In: YES 
user_id=44345

I checked in an initial glossary for the tutorial.  I'm sure it will 

need a fair amount of LaTeX work.  Fred, please feel free to

ping me on that.  I will be happy to do the work with some

guidance from you.  One thing I was hoping we could do is

generate links from other documentation into the tutorial, but

I have no idea how well LaTeX and latex2html support inter-

document links.  Another (simpler, though tedious) task will

be to "indexify" the tutorial, now that one is being generated.



----------------------------------------------------------------------

Comment By: Skip Montanaro (montanaro)
Date: 2003-09-24 09:09

Message:
Logged In: YES 
user_id=44345

I'm going to put this in the tutorial as Raymond suggested.  It

would be nice if there was a special \glossaryitem{} environment

that would allow easy linking to glossary entries from other

places in the documentation.  I'm not going to let its absence

hold me up.  It's just something to consider.

----------------------------------------------------------------------

Comment By: Raymond Hettinger (rhettinger)
Date: 2003-09-17 11:45

Message:
Logged In: YES 
user_id=80475

I recommend putting it in the tutorial.  As it stands now, the 

glossary can be profitability read A to Z after completing the 

tutorial.  It can serve to unify and solidify the ideas 

presented up to that point.



The reference manual is more encyclopedic and I think the 

glossary would be lost in a sea of entries.



Another alternative is to make it a stand-alone link from the 

main page:

     Tutorial (start here)        Ref Manual

     Lib Ref                           Glossary of Key Concepts



This patch is marked for Py2.4.  I recommend that it be 

added to Py2.3.1 also.

----------------------------------------------------------------------

Comment By: Skip Montanaro (montanaro)
Date: 2003-09-17 10:50

Message:
Logged In: YES 
user_id=44345

Agreed, it has been quite successful.  Fred,  I'll take this over

if you like, but I'd sort of like a pronouncement about where

the glossary should go.  My thought was that it would be an

appendix to the language reference manual.



----------------------------------------------------------------------

Comment By: Raymond Hettinger (rhettinger)
Date: 2003-09-17 01:20

Message:
Logged In: YES 
user_id=80475

The wiki was a success and the glossary looks ready for 

prime-time.  So go ahead and add it (or assign to me).

----------------------------------------------------------------------

Comment By: Skip Montanaro (montanaro)
Date: 2003-08-14 09:29

Message:
Logged In: YES 
user_id=44345

Agreed.  Any glossary with only one entry would be a bit thin.

Thanks for the new entry. :-)



----------------------------------------------------------------------

Comment By: Duncan Booth (duncanb)
Date: 2003-08-14 04:33

Message:
Logged In: YES 
user_id=74031

Sorry, but I'm going to throw darts at this. You need to have 

glossary entries for both 'iterable' and 'iterator', and you're 

current definition of 'iterable' is actually the definition 

of 'iterator' not of 'iterable'.



Try something like this:



\index{iterable{

\item[iterable] Any object which supports enumeration of a 

set of values by calling its \method{__iter__} which returns 

an iterator over those values. Examples include \class{file},

\class{list} and \class{dict} objects.  In the case of \class

{dict} objects, iteration is over the keys in the object.



\index{iterator}

\item[iterator] An object which supports enumeration of a

set of values by calling its \method{next} method and which

contains an \method{__iter__} method which returns the

object itself.  Examples: \class{file} is a iterable which is its 

own iterator. \class{list} and \class{dict} are iterables which 

create iterators of types which are not otherwise visible.



----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=305470&aid=788509&group_id=5470



More information about the Patches mailing list