At GVR's request.

Lib/onlinehelp.py

-"""
-Online help module. 
-
-This module is experimental and could be removed or radically changed
-at any time.
-
-It is intended specifically for the standard interpreter command 
-line but is intended to be compatible with and useful for other
-(e.g. GUI, handheld) environments. Help with those other environments is
-appreciated.
-
-Please remember to set PYTHONDOCS to the location of your HTML files:
-
-e.g. 
-set PYTHONDOCS=c:\python\docs
-PYTHONDOCS=/python/docs
-
-The docs directory should have a lib subdirectory with "index.html" in it.
-If it has *.tex then you have the documentation *source* distribution, not
-the runtime distribution.
-
-The module exposes one object: "help". "help" has a repr that does something
-useful if you just type:
-
->>> from onlinehelp import help
->>> help
-
-Of course one day the first line will be done automatically by site.py or
-something like that. help can be used as a function.
-
-The function takes the following forms of input:
-
-help( "string" ) -- built-in topic or global
-help( <ob> ) -- docstring from object or type
-help( "doc:filename" ) -- filename from Python documentation
-
-Type help to get the rest of the instructions.
-"""
-import htmllib # todo: add really basic tr/td support
-import formatter
-import os, sys
-import re
-
-prompt="--more-- (enter for more, q to quit) "
-
-topics={}   # all built-in (non-HTML, non-docstring) topics go in here
-commands="" # only used at the top level
-
-def topLevelCommand( name, description, text ):
-    """ this function is just for use at the top-level to make sure that
-        every advertised top-level topic has a description and every 
-        description has text. Maybe we can generalize it later."""
-
-    global commands
-    topics[name]=text
-
-    if description[0]=="[":
-        placeholder="(dummy)"
-    elif description[0]=="<":
-        placeholder="link"
-    else:
-        placeholder=""
-    commands=commands+'help( "%s" ) %s - %s\n' % \
-                                (name, placeholder, description )
-
-topLevelCommand( 
-"intro", 
-"What is Python? Read this first!",
-"""Welcome to Python, the easy to learn, portable, object oriented 
-programming language.
-
-[info on how to use help]
-
-[info on intepreter]"""
-)
-
-topLevelCommand( 
-"keywords", 
-"What are the keywords?", 
-"")
-
-topLevelCommand( 
-"syntax", 
-"What is the overall syntax?", 
-"[placeholder]")
-
-topLevelCommand( 
-"operators", 
-"What operators are available?", 
-"<doc:ref/operators.html>" )
-
-topLevelCommand( 
-"builtins", 
-"What functions, types, etc. are built-in?", 
-"<doc:lib/built-in-funcs.html>")
-
-topLevelCommand( "modules", 
-"What modules are in the standard library?", 
-"<doc:lib/lib.html>")
-
-topLevelCommand( 
-"copyright", 
-"Who owns Python?", 
-"[who knows]")
-
-topLevelCommand( 
-"moreinfo", 
-"Where is there more information?", 
-"[placeholder]")
-
-topLevelCommand( 
-"changes", 
-"What changed in Python 2.0?",
-"[placeholder]"
-)
-
-topLevelCommand( 
-"extensions", 
-"What extensions are installed?",
-"[placeholder]")
-
-topLevelCommand( 
-"faq", 
-"What questions are frequently asked?", 
-"[placeholder]")
-
-topLevelCommand( 
-"ack", 
-"Who has done work on Python lately?", 
-"[placeholder for list of people who contributed patches]")
-
-
-topics[ "prompt" ]="""<doc:tut/node4.html>"""
-topics[ "types" ]="""<doc:ref/types.html>"""
-topics["everything"]= \
-"""<pre>The help function allows you to read help on Python's various 
-functions, objects, instructions and modules. You have two options:
-
-1. Use help( obj ) to browse the help attached to some function, module
-class or other object. e.g. help( dir )
-
-2. Use help( "somestring" ) to browse help on one of the predefined 
-help topics, unassociated with any particular object:
-
-%s</pre>""" % commands
-
-topics[ "keywords" ]=\
-"""<pre>"if"       - Conditional execution
-"while"    - Loop while a condition is true
-"for"      - Loop over a sequence of values (often numbers)
-"try"      - Set up an exception handler
-"def"      - Define a named function
-"class"    - Define a class
-"assert"   - Check that some code is working as you expect it to.
-"pass"     - Do nothing
-"del"      - Delete a data value
-"print"    - Print a value
-"return"   - Return information from a function
-"raise"    - Raise an exception
-"break"    - Terminate a loop
-"continue" - Skip to the next loop statement
-"import"   - Import a module
-"global"   - Declare a variable global
-"exec"     - Execute some dynamically generated code
-"lambda"   - Define an unnamed function
-
-For more information, type e.g. help("assert")</pre>"""
-
-topics[ "if" ]="""<doc:ref/if.html>"""
-topics[ "while" ]="""<doc:ref/while.html>"""
-topics[ "for" ]="""<doc:ref/for.html>"""
-topics[ "try" ]="""<doc:ref/try.html>"""
-topics[ "def" ]="""<doc:ref/def.html>"""
-topics[ "class" ]="""<doc:ref/class.html>"""
-topics[ "assert" ]="""<doc:ref/assert.html>"""
-topics[ "pass" ]="""<doc:ref/pass.html>"""
-topics[ "del" ]="""<doc:ref/del.html>"""
-topics[ "print" ]="""<doc:ref/print.html>"""
-topics[ "return" ]="""<doc:ref/return.html>"""
-topics[ "raise" ]="""<doc:ref/raise.html>"""
-topics[ "break" ]="""<doc:ref/break.html>"""
-topics[ "continue" ]="""<doc:ref/continue.html>"""
-topics[ "import" ]="""<doc:ref/import.html>"""
-topics[ "global" ]="""<doc:ref/global.html>"""
-topics[ "exec" ]="""<doc:ref/exec.html>"""
-topics[ "lambda" ]="""<doc:ref/lambda.html>"""
-
-envir_var="PYTHONDOCS"
-
-class Help:
-    def __init__( self, out, line_length, docdir=None ):
-        self.out=out
-        self.line_length=line_length
-        self.Parser=htmllib.HTMLParser
-        self.Formatter=formatter.AbstractFormatter
-        self.Pager=Pager
-        self.Writer=formatter.DumbWriter
-        if os.environ.has_key(envir_var):
-            self.docdir=os.environ[envir_var]
-        else:
-            if os.environ.has_key("PYTHONHOME"):
-                pyhome=os.environ["PYTHONHOME"]
-            else:
-                pyhome=os.path.split( sys.executable )[0]
-            self.docdir=os.path.join( pyhome, "doc" )
-
-        testfile=os.path.join( 
-                os.path.join( self.docdir, "lib" ), "index.html")
-
-        if not os.path.exists( testfile ):
-            error = \
-"""Cannot find documentation directory %s. 
-Set the %s environment variable to point to a "doc" directory.
-It should have a subdirectory "Lib" with a file named "index.html".
-""" % (self.docdir, envir_var )
-            raise EnvironmentError, error
-
-    def __repr__( self ):
-        self( "everything" )
-        return ""
-
-    def __call__( self, ob, out=None ):
-        try:
-            self.call( ob, out )
-            return 1
-        except (KeyboardInterrupt, EOFError):
-            return 0
-
-    def call( self, ob, out ):
-        self.pager=out or self.Pager( self.out, self.line_length )
-
-        if type( ob ) in (type(""),type(u"")):
-            if ob.startswith( "<" ):
-                ob=ob[1:]
-            if ob.endswith( ">" ):
-                ob=ob[:-1]
-
-            self.write( 'Topic: help( "%s" )\n' % ob )
-
-            if ob.startswith("doc:"):
-                path=ob[4:]
-                fullpath=os.path.join( self.docdir, path )
-                data=open( fullpath ).read()
-                index=ob.rfind( "/" )
-                self.writeHTML( ob[:index], data )
-            else:
-                try:
-                    info=topics[ob]
-                    docrlmatch=re.search( "(<doc:[^>]+>)", info.split("\n")[0] )
-                    if docrlmatch: # a first-line redirect
-                        self( docrlmatch.group(1) )
-                    else:
-                        self.writeHTML( "", info )
-                except KeyError:
-                    glo=__builtins__.__dict__.get( ob, 0 )
-                    if glo:
-                        self( glo )
-                    else:
-                        sys.stderr.write( "No such topic "+`ob` )
-                        return None
-        else:
-            self.write( 'Topic: help( %s )\n' % ob )
-            if hasattr( ob, "__doc__" ):
-                self.writeText(ob.__doc__)
-            else:
-                self.writeText( type( ob ).__doc__ )
-    
-
-    def writeHTML( self, base,  str ):
-        parser=self.Parser(self.Formatter( self.Writer( self )))
-        parser.feed( str ) # calls self.write automatically
-        for i in range(  len( parser.anchorlist) ):
-            self.pager.write( "[%s] %s/%s\n" %(i+1, base,parser.anchorlist[i] ))
-        self.pager.flush()
-        self.out.write( "\n" )
-
-    def writeText( self, str ):
-        self.pager.write( str )
-        self.pager.flush()
-        self.out.write( "\n" )
-
-    def write( self, str ):
-        self.pager.write( str )
-
-from cStringIO import StringIO
-
-class Pager:
-    numlines=1
-
-    def __init__(self, out, pagesize=24, linestart="" ):
-        self.out=out
-        self.pagesize=pagesize
-        self.buf=StringIO()
-        self.linestart=linestart
-
-    def close(self ):
-        self.flush()
-
-    def flush(self ):
-        data=self.buf.getvalue().rstrip() # dump trailing ws
-        while data.endswith( "\n|" ): # dump trailing lines
-            data=data[:-2]
-        self.out.write( data )
-        self.buf=StringIO()
-
-    def write(self, str ):
-        lines=str.split( "\n" )
-        self.buf.write( lines[0] )
-        for line in lines[1:]:
-            self.buf.write( "\n| " )
-            self.buf.write( line )
-            if self.numlines and not self.numlines%(self.pagesize):
-                dat=self.buf.getvalue().strip()
-                self.out.write( "| " )
-                self.out.write( dat )
-                self.out.write( "\n" )
-                j=raw_input(prompt)
-                if j and j[0]=="q":
-                    raise EOFError
-                self.buf=StringIO()
-            self.numlines=self.numlines+1
-
-help=Help(sys.stdout,24)
-
-def test():
-    rc = 1
-    rc = rc and help( "everything" )
-    rc = rc and help( "exec" )
-    rc = rc and help( "doc:lib/unix.html" )
-    rc = rc and help( "doc:lib/module-tty.html" )
-    rc = rc and help( "doc:ref/print.html" )
-    rc = rc and help( "faq" )
-    rc = rc and help( dir )
-    repr( help )
-
-if __name__=="__main__":
-    if len( sys.argv )!=2:
-        print "Usage: %s <topic>   or   %s test" % ( sys.argv[0], sys.argv[0] )
-        sys.exit(0)
-    elif sys.argv[1]=="test":
-        test()
-    else:
-        help( sys.argv[1] )
-