ftp.pasteur.org/FAQ//ftp-pasteur-org-FAQ.zip/FAQ/perl-faq/ptk-faq/part1

Internet Message Format | 1997-06-01 | 40.2 KB

Path: senator-bedfellow.mit.edu!bloom-beacon.mit.edu!gatech!csulb.edu!hammer.uoregon.edu!news-xfer.netaxs.com!news.maxwell.syr.edu!news.cis.ohio-state.edu!nntp.sei.cmu.edu!bb3.andrew.cmu.edu!goldenapple.srv.cs.cmu.edu!rochester!cornellcs!newsstand.cit.cornell.edu!lnsnews.lns.cornell.edu!lns62.lns.cornell.edu!PVHP
From: [e-mail] (Peter Prymmer)
Newsgroups: comp.lang.perl.tk,comp.lang.perl.announce,comp.answers,news.answers
Subject: comp.lang.perl.tk FAQ part1 of 5
Followup-To: comp.lang.perl.tk
Date: Sun, 01 Jun 1997 06:38:24 GMT
Organization: Wilson Lab, Cornell U., Ithaca, NY, 14853
Lines: 989
Approved: [e-mail] (Peter Prymmer)
Expires: Thu, 31 Jul 1997 06:38:04 GMT
Message-ID: <[e-mail]>
Reply-To: [e-mail]
NNTP-Posting-Host: lns62.lns.cornell.edu
Xref: senator-bedfellow.mit.edu comp.lang.perl.tk:4655 comp.lang.perl.announce:639 comp.answers:26267 news.answers:103808

Summary: comp.lang.perl.tk Frequently Asked Questions.
Archive-name: perl-faq/ptk-faq/part1
Posting-Frequency: monthly
Last-modified: Date: Sat May 31 16:48:37 1997
URL: http://w4.lns.cornell.edu/~pvhp/ptk/ptkFAQ.html
Version: 1.00_07

URL (Hypertext-split): http://w4.lns.cornell.edu/~pvhp/ptk/ptkTOC.html
URL (Plaintext): http://w4.lns.cornell.edu/~pvhp/ptk/ptkFAQ.txt
Image-supplement: http://w4.lns.cornell.edu/~pvhp/ptk/ptkIMG.html
ftp-Archive: ftp://ftp.ccd.bnl.gov/pub/ptk/ptkFAQ.txt
ftp-Archive: ftp://rtfm.mit.edu/pub/usenet/perl-faq/ptk-faq/
e-mail-Archive: [e-mail]

Perl/Tk FAQ part 1 of 5 - Getting Started
*****************************************



 ______________________________________________________________________



 6. How do I build it?

 In general, building perl/Tk requires:

  1. A made & installed perl (requires a C language compiler). You may
    need different versions of perl depending on which version of Tk you
    wish to run.
  2. A C language compiler for the Tk code itself.
  3. A linkable Xlib (.o, .so, .a, etc.) for X-windows.

 Perl/Tk has been successfully built using various vendors' cc compilers, as
 well as with the free GNU gcc compiler. A make utility of some sort (make/
 gmake) will be extremely helpful.

 Step - by - step the commands to build the Tk extension to Perl are (for the
 dynamically linked version) roughly as follows:

  1. make install # the appropriate version of perl.
  2. uninstall # prior versions of the Tk extension to perl.
  3. gunzip -c Tk400.202.tar.gz | tar xvf - (options to tar
    may vary esp. on SysV)
  4. cd Tk400.200
  5. read INSTALL
  6. perl Makefile.PL
  7. make
  8. make test
  9. make install

 For the statically linked version you would `make tkperl` just after
 executing the `make` step and before the `make test` step.

 Note carefully that this process leaves behind a large amount of
 documentation and examples in various sub-directories. You are strongly
 encouraged to look carefully through your build tree for docs, examples, etc.
 and keep those valuable files in a safe place. You might consider tar-ing them
 off and installing in a webserver directory tree.

 A relatively easy way to determine if the perl on your system allows for
 dynamic linking was mentioned by Kenneth Albanowski
 <[e-mail]>. If the following does not say "dl_none.xs" then you
 probably do have dynamically linked perl (or perhaps a very non-Unixy perl):

     perl -e 'use Config; print $Config{dlsrc},"\n"'

 (thanks to Paul Lussier <[e-mail]> for the correction!).

 Here is a little more detailed discussion of each the steps just given:

  o Install Perl Read the Tk files (Tk*/README, etc.) for info on which
    version of perl is required for the perl/Tk kit you obtained.) For code
    locations see a CPAN site (separate question in this FAQ), the actual
    installation instructions come bundled in the perl***.tar.gz
    distribution file. (Perl Configure & make troubles are beyond the
    scope of this FAQ - please see the Perl FAQ itself or the INSTALL file
    for more help with this critical step.)
    You can install perl almost anywhere you like by specifying the
    -Dprefix=/path argument to sh Configure
  o Unpack perl/Tk outside the Perl distribution
    (i.e. outside the perl build, perl install, or perl lib areas).
    gunzip Tk400.202.tar.gz
    tar -xvf Tk400.202.tar
    (Your tar program may not take -xvf. The resultant Tk400.202/
    area will be referred to as your ``Tk build'' directory throughout this
    document.)
  o Read INSTALL carefully
    cd Tk400.202
    pager INSTALL
    where pager is the program you use to scroll through text files more
    or less. Be sure to read it and don't just pound away on the spacebar.
  o If necessary remove any previously installed version of perl/Tk
    If you had a previously working version of Tk installed, you may need
    to resurrect the Makefile for it and execute:
    make uninstall
    make realclean
    before you unpack the new version. (The uninstall target of
    MakeMaker is relatively new so please be careful here.)
  o Have perl generate a custom Makefile.
    perl Makefile.PL
    (see below for more on this step.)
  o Compile.
    make
    (if and only if building static: make tkperl
  o Test.
    make test
  o Install.
    make install
  o Play with it.
    basic_demo
    (modify #! line if necessary, or specify /path/to/perl
    ./basic_demo)
    (warning if you build Tk-b9.01 with perl5.002gamma then change the
    line in basic_demo from
    use lib ./blib;
    to
    use lib qw(blib/arch blib/lib);)
  o Save the documentation and examples in a safe accessible place.
    use tar, cp, mv, chmod or whatever you prefer to save the valuable
    ancillary files from your Tk build tree.

 On the perl Makefile.PL step it may be necessary to give explicit
 locations of the required X11 libraries and/or include headers. For example:

     perl Makefile.PL X11=/usr/local/X11R5

 or perhaps different directory tree specification is necessary with your X
 installation:

     perl Makefile.PL X11INC=/usr/local/share/X11R5/include \
                      X11LIB=/usr/local/arch/X11R5/lib

 There are system and site dependencies in all of the above steps. However, the
 largest single source of build trouble comes from not using the latest versions
 of the various utilities (C compiler, make, etc.). In particular ensure that
 when you say perl Makefile.PL that the perl that gets invoked is up to
 date - use which perl (or whence perl) and perl -v to determine this.
 If necessary specify the full path name to your perl5 interpreter/compiler.
 (Some people do not rm their older perl interpreters when upgrading to a more
 recent version - beware.)

 If you still run into trouble take a look at the INSTALL, the README and the
 README file for your specific system (e.g. README.AIX, README.OSF, etc.).
 You might also find your system mentioned in the ptk hyper-mail archive at:

     http://www.rosat.mpe-garching.mpg.de/mailing-lists/ptk/
 or
     http://pubweb.bnl.gov/~ptk/
 or
     ftp://ftp.ccd.bnl.gov/pub/ptk/archives/

 or the Perl 5 Porters page at one of the following URLs:

     http://www.rosat.mpe-garching.mpg.de/mailing-lists/Perl5-Porters/
     http://www.hut.fi/~jhi/perl5-porters.html

 If you wish to discuss your Tk build problems with others run and save the
 output from the myConfig script in the Tk build directory (the output may
 already be in the myConfig.out file from your perl/Tk build directory), as
 well as the myconfig script in your perl build directory (or the output of perl
 -V with a capitol V). It is often helpful to include the output of either (or both)
 of these scripts in your discussion.

 Presented here are the beginnings of a list of problems associated with
 building perl/Tk on various platforms (for help building perl itself please refer
 to the Perl FAQ). This list is in no way complete nor authoritative (nor is it
 necessarily even up-to-date!) but simply lists problems people have reported.
 Keep in mind that your installation may differ (e.g. location differences such
 as /usr/bin/perl vs. /usr/local/bin/perl) even if its the same
 platform listed here:

 A Sampling of Perl/Tk Platforms:
 ++++++++++++++++++++++++++++++++

 AIX:
    As of perl5.002b & Tk-b9.01 README.AIX says no patching is
    necessary.

    For Tk-b8: modifying the perl.exp file may be necessary. There is a
    patch in Tk-b8/README.AIX. It may be necessary to make
    regen_headers after the patch.
 FreeBSD:
    Nate Patwardhan <[e-mail]> reports no trouble at all with
    Tk400.200 on FreeBSD-2.1.5 or FreeBSD-2.2.1.
 HPUX:
    For Tk-b11: One person reports a need to add #define
    TIMEOFDAY_TZ to the tkConfig.h header file in order to compile on
    HPUX 9.05.

    Previous versions: Most people seem to prefer the dynamic linking
    afforded by a recent version of the gcc compiler on this system.
 Linux:
    John C. Wingenbach indicates that should you encounter an error
    message like Cannot find -lX11 anywhere at ./myConfig
    line 184 when running your perl Makefile.PL (under Slakware
    3.0) that you should be more specific about -l/path/to/libX11.a.
    Adam Wasserman <[e-mail]> has graciously
    provided a compilation of Linux compilation trials & tribulations. It is
    an (as yet un-edited) document available at:
    http://w4.lns.cornell.edu/~pvhp/ptk/hints/linux_compile.txt
 MachTen:
    Mark Pease <[e-mail]> mentions that:
    I was able to get Tk-b11.02 running under MachTen 2.2 perl5.002_01.
    I did need to make one change to get a round a MachTen problem. In
    pTk/tclUnix.h, pwd.h is included, but it is also included in pTk/tkPort.h
    (which is included in Lang.h, which is use by tclUnixUtil.c, whew!)

    MachTen's pwd.h can't be included more that once or you get an
    error.

    It looked to me like tclUnix.h was only used in tclUnixUtil.c, so I
    commented out the #include <pwd.h> in tclUnix.h.
 NetBSD:
    Jesus M. Gonzalez <[e-mail]> mentions success with:
    Tk-b11.01 compiles, installs and runs just out of the box in
    NetBSD-1.1/i386. I just followed the INSTALL instructions.
 NeXTSTEP:
    Gerd Knops recently posted a discussion of the steps to get perl
    running on several NeXTSTEPs to p5p.
 OS/2:
    Ilya Zakharevich <[e-mail]> has compiled a
    modified form of Tk-b11.02 to work with the Xfree86 client/server
    package, as well more advanced versions working with the Open32 PM
    package.
 OSF/1:
    As of perl5.002b & Tk-b9.01 you will probably be able to follow the
    usual instructions. John Stoffel <[e-mail]> reports that if you
    use gcc (rather than cc) you should use at least version 2.7.2

    For Tk-b8: make is reputedly not up to the task on this system.
    Tk-b8/README.OSF recommends gmake instead.
    Stephane Bortzmeyer <[e-mail]> reports a successful
    build with Perl 5.001m, xsubpp 1.922, MakeMaker 4.23. He points
    out that it was necessary for him to upgrade the xsubpp and
    MakeMaker that he received with his copy of Perl5.001m.
 SCO:
    For Tk-b8: Eric J. Bohm <[e-mail]> reported a need to
    comment out line(s) from myConfig and GNUMakefiles using GNU
    make 3.67. (See Tk-b8/README.SCO for specifics.)
 SGI (Irix):
    For Tk-b11.02: Phillip Moore <[e-mail]> reports a clean
    build on IRIX 5.3.

    Matthew Black <[e-mail]> recently mentioned a need to apply
    "patchSG0000596" to get perl sockets to work. His message was
    copyrighted and is not included here. Send e-mail to him to find out
    where the get "patchSG0000596".
 Suns:
    SunOS (BSD):
    For Tk-b10 on SunOS 4.1.3_U1
    using SparcWorks acc 3.0.1 Frederick L. Wagner <[e-mail]>
    reports needing to use the perl malloc rather than the system malloc()
    when building perl.
    For Tk-b8: Tom Tignor <[e-mail]> reports the following on
    SunOS (sun4m sparc): Tue, 28 Nov 1995 13:19:42
    In trying to make, I got a "write: argument mismatch" error for the file
    ptK/Lang.h. I looked at the file and found the offending function,
    Tcl_GetOpenFile, which has a third argument called "doWrite" (not
    "write") in tkGlue.c. I changed the argument from "write" to "doWrite"
    in Lang.h and it's compiling fine (for the moment. :)
    Solaris (System V):
    For Tk-b8: There is trouble getting perl to use Socket routines (i.e.
    trouble with make perl itself not necessarily trouble with Tk-b8). See
    the perl FAQ for more info or the .shar file that Tom Christiansen
    occasionally posts to comp.lang.perl.misc. Further information on perl
    inter process communication can be found in the perlipc* files at:
    ftp://ftp.perl.com/perl/info/everything_to_know/.
 SVR4:
    For Tk-b8: Martha G. Armour and Len Reed report on two separate
    hardware platforms running SVR4 - extensive details in
    Tk-b8/README.SVR4. Interestingly, they report no trouble at all on
    Linux.
 Ultrix:
    Peter Prymmer reports that with Tk-b11 it was necessary to change
    the line in Makefile.PL that reads:
    'LIBS' => ["$xlib -lX11 -lpt -lsocket -lnsl -lm"],
    to read:
    'LIBS' => ["$xlib -lX11 -lpt -lsocket -lnsl -lm
    -ldnet"],
    because of a newer X11 in /usr/local that needed the DECnet protocol
    linking.

    John Stoffel reports a successful build of static Tk-b10 on Ultrix 4.5.
 Windows NT:
    Nick Ing-Simmons reports success with the alpha Tk404.000 kit,
    perl5.004, and Visual C++.

 non-Unix(ish)es:
 ++++++++++++++++

 Information on non-Unix(ish) perl platforms may be obtained from
 newsgroups and email lists as well as a few world wide web sites. For example,
 try the Perl 5 Porters (p5p) [page|archives] at one of:

     http://www.rosat.mpe-garching.mpg.de/mailing-lists/Perl5-Porters/
     http://www.hut.fi/~jhi/perl5-porters.html

 In general your non-Unix platform must be able to support perl 5 and Xlib (a
 C compiler and a make utility are tremendously useful too). If you want to run
 perl/Tk on another computer and simply have the display show up on yours
 then all you need on your computer is an "X server" The long list of UNIX and
 non-unix perl 5 ports, Tcl/Tk ports, and Perl/Tk ports that used to appear in
 this FAQ has now moved to a separate web page at:

     http://w4.lns.cornell.edu/~pvhp/ptk/ptkPORT.html

 ______________________________________________________________________



 7. Where is the Documentation?

 A great deal of Perl/Tk documentation gets installed as part of the Tk
 extension building process. Hence, a great deal of documentation is probably
 residing on your computer already.

 More documentation is "in the works": there are several books dealing with
 perl/Tk in progress, an ongoing magazine column and a growing FAQ (the
 document you are presently reading).

 The additional material you may want to look at can be split into Perl/Tk, Perl,
 Tcl/Tk, and X documentation categories:

 Perl/Tk Specific Documentation
 ++++++++++++++++++++++++++++++

 The man pages
 -------------

 With up to date Tk build kits the various perl/Tk pod documents are converted
 to your systems' helpfile format and installed as part of the perl/Tk "make
 install" process. If you have a recent verion of perl/Tk try something like
 man 3 Tk::Tk if this does not work check with you system administrator for
 the proper MANPATH.

 In your Tk build directory there should be a doc/ sub-directory in which
 there are a number of .htm files (after you make install). These files were
 originally Tcl/Tk man pages (from the man* sub-directories), but the *.htm
 files have been converted to Perl syntax and rendered in HTML format. You
 can use the Perl/Tk web browser to view them locally with a command like:

     tkweb index.html

 or you may view them on the web itself by installing them in a web-server
 directory tree, or by pointing a browser at:

     http://w4.lns.cornell.edu/~pvhp/ptk/doc/

 The newsgroup
 -------------

 The newsgroup name is comp.lang.perl.tk and this FAQ will be periodically
 posted to that group (as well as a few other newsgroups). The newsgroup
 and/or the ptk mailing list are the appropriate places to post questions - yes
 even simple ones! (Although answers may sometimes be long in coming ... :-(

 The nTk/pTk mailing list
 ------------------------

 The mailing list is an excellent supplement and complement to the newsgroup
 comp.lang.perl.tk. All messages mailed to the list are forwarded to the
 newsgroup. (But not all messages posted to the newsgroup are forwarded to
 the list.) Some Perl/Tk experts only have access to e-mail.

 The nTk/pTk Mailing List Archive is a very useful source of information too,
 and is accesible at either

     http://pubweb.bnl.gov/~ptk/

 or via ftp at

     ftp://ftp.ccd.bnl.gov/pub/ptk/archives/

 (both in the USA). You may search the contents of another ptk mailing list
 hypertext archive thanks to a cgi-bin script written by Achim Bohnet in
 Germany at:

     http://www.rosat.mpe-garching.mpg.de/mailing-lists/ptk/

 You must subscribe to the mailing list to receive e-mail from the list. To
 subscribe to the mailing list you can send mail to
 [e-mail] (i.e. <[e-mail]>) with
 the following command in the body of your e-mail message:

     subscribe ptk joe.user@somewhere (Joe D. User)

 To send a message to all recipients of the mailing list send e-mail to
 <[e-mail]>.

 To remove yourself from the mailing list send e-mail to
 [e-mail] (i.e. <[e-mail]>) with
 the following command in the body of your e-mail message:

     unsubscribe ptk joe.user@somewhere (Joe D. User)

 Where instead of "joe.user@somewhere" you might very well like to
 substitute another string of characters.

 (Please note: one does not send unsubscribe messages to the ptk list. One does
 send "unsubscribe ptk" messages to a special e-mail list administration
 program. In the case of the ptk list you send to [e-mail].
 You must of course do this from the account and computer from which you
 initially subscribed. In particular if you are viewing the hypertext version of
 this FAQ you may not be able to unsubscribe from
 [e-mail] by following the mailto: hyperlinks - if your
 web-browser account/computer is different from your subscribe to
 e-mail-lists account/computer (the details of this might depend on which
 browser you use though). Thank you for your cooperation on this.)

 The demo programs
 -----------------

 Examine (and try running) the code in your Tk#/ build directory tree. You
 might also be interested in test-running the code that gets installed:

  o or perl5/site_perl/Tk/demos/ or
    perl5/site_perl/Tk/demos/widget_lib/ directories (recent
    Tk's).
  o Tk#/ or perl5/Tk/demos/ or perl5/Tk/demos/widget_lib/
    directories (older versions e.g. Tk-b8).

 In order to determine where on your system the perl5/ directory is located
 type the following one-line perl command (at your shell prompt - this is not a
 line from a perl script):

     perl -e 'print join("\n",@INC,"");'

 If that command does not turn up a perl5/ directory then make sure that you
 are running perl 5 with the following: perl -v (this too can simply be
 entered at the shell prompt).

 More on the pod & man documentation
 -----------------------------------

 [As previously mentioned a great number of Tcl/Tk man pages are converted
 from *roff format to html format and are to be found within your Tk build
 directory tree in the doc/ sub-directory. These documents form an
 authoritative and extensive reference set for Perl/Tk.]

 The raw pod files that come with the Tk kit are examples of the perl "plain old
 documentation" format and are just about human readable as they are (e.g. you
 may more, cat, or less them; or send them to a printer). Many (not all) of
 the perl/Tk pod documents get are converted to *roff format and are installed
 in you perl man page area as part of the perl/Tk build process.

 If you have a recent version of perl/Tk try something like man 3 Tk::Tk. If
 this does not work check your manual page path with

     perl -MConfig -e 'print $Config{man1dir},"\n",$Config{man3dir},"\n"'

 And if you still cannot find the manual pages check with your system
 administrator for the proper MANPATH and/or Tk installation version.

 "Raw" .pod (such as UserGuide.pod) can be viewed with the tkpod
 hypertext pod viewer. Raw .pod may also be run through any one or more of a
 large numbers of re-formatting perl filters. Such programs include pod2man,
 pod2text, pod2html, pod2latex, etc. (these get installed when you install
 perl). Other translators pod2texinfo, pod2fm, pod2pdf, etc., also exist.
 Check a CPAN site for these scripts if you do not already have them.

 A command line like the following (but subject to local variations) should
 work for you:

     tkpod site_perl/Tk/UserGuide.pod

 or if you like Unix manual page style:

     pod2man perl5/Tk/UserGuide.pod | nroff -man | more

 (note that I am showing examples with almost full file path names - the
 alternative would be to cd into the appropriate directory then type:

     pod2man UserGuide.pod | nroff -man | more

 There should even be a perl script to run that above command for you. It is
 executed as:

     perldoc UserGuide

 Note that if there is pod like documentation in a perl module you may also
 execute tkpod (or perldoc) on it as in:

     tkpod ColorEditor.pm

 (please note that unfortunately, not all .pm mod files have pod embedded.)

 If you have misplaced your tkpod program but still want that GUI look and
 feel (like xman) make the appropriate changes to the following script:

     #!/usr/bin/perl
     use Tk;
     use Tk::Pod;
     my $m = new MainWindow;
     $m -> Pod(-file => 'ColorEditor.pm');
     # or use command line path/filename:
     # $m -> Pod(-file => $ARGV[0]);
     MainLoop;

 A miscellany of internet perl/Tk resources includes:
 ----------------------------------------------------

 World Wide Web - perl/Tk man pages
     http://pubweb.bnl.gov/~ptk/doc/index.html
     http://w4.lns.cornell.edu/~pvhp/ptk/doc/
     http://w4.lns.cornell.edu/~pvhp/ptk/pod/
 The Perl/Tk Newsgroup
     comp.lang.perl.tk
 Perl Newsgroups
     comp.lang.perl.misc
     comp.lang.perl.anounce
     comp.lang.perl.modules
 Tcl Newsgroups
     comp.lang.tcl
     comp.lang.tcl.announce
 Miscellaneous Newsgroups
     comp.answers
     news.answers
 Perl/Tk FAQ-Archives (ftp sites) [Note: FAQ may be many separate files]
  (see also CPAN sites)
     ftp://rtfm.mit.edu/pub/usenet/comp.lang.perl.tk
     ftp://rtfm.mit.edu/pub/usenet-by-hierarchy/comp/lang/perl/tk
     ftp://ftp.uu.net/usenet/news.answers/perl-faq/ptk-faq
     ftp://ftp.ccd.bnl.gov/pub/ptk/                   130.199.54.188
     ftp://ftp.ccd.bnl.gov/pub/ptk/ptkFAQ.txt         130.199.54.188
     ftp://ftp.wpi.edu/perl5/pTk-FAQ                  130.215.24.209
     ftp://perl.com/pub/perl/doc/ptkFAQ.gz            199.45.129.30
     ftp://perl.com/pub/perl/doc/ptkFAQ.ps.gz         199.45.129.30
 WWW-FAQ for perl/Tk
     http://w4.lns.cornell.edu/~pvhp/ptk/ptkTOC.html
     http://w4.lns.cornell.edu/~pvhp/ptk/ptkFAQ.html
 World Wide Web - perl/Tk info sites
     http://pubweb.bnl.gov/~ptk/
     http://fxfx.com/kgr/compound/ (Perl Tk Compound Widget Page)
     http://w4.lns.cornell.edu/~pvhp/ptk/ptkIMG.html (FAQ image supplement)
     http://w4.lns.cornell.edu/~pvhp/ptk/etc/
     http://w4.lns.cornell.edu/~pvhp/ptk/misc/
     http://w4.lns.cornell.edu/~pvhp/ptk/PNMTYAK/
     http://www.mirai.com/wks/
 The Mailing list
     [e-mail]
     [e-mail]

 Perl Specific Documentation
 +++++++++++++++++++++++++++

 There are a growing number Perl books available. A more complete
 Perl-bibliographic discussion than that given here is available in the Perl
 FAQ or at:

     http://www.perl.com/perl/info/books.html

 For Perl 5 there is (as of September 1996) a "New Camel" by Larry Wall, Tom
 Christiansen, and Randal L. Schwartz, with Stephen Potter.

  Programming Perl 2nd Edition
  Larry Wall, Tom Christiansen, & Randal L. Schwartz with Stephen
  Potter
  (c) 1996 O'Reilly & Associates Inc.
  ISBN 1-56592-149-6 (English)

 A second edition of the Llama is due out soon too:

  Learning Perl, 2ndEdition
  Randal L. Schwartz
  June 1997 (est.) O'Reilly & Associates Inc.
  ISBN 1-56592-284-0 (English)

 The two early Perl books by Schwartz and Wall are very helpful (even if they
 do pertain to perl 4 and not 5. Beware that perl/Tk makes extensive use of perl
 5 object-oriented features.):

  Learning Perl (The Llama)
  Randal L. Schwartz
  Copyright (c) 1993 O'Reilly & Associates Inc.
  ISBN 1-56592-042-2 (English)
  ISBN 2-84177-005-2 (French)
  ISBN 3-930673-08-8 (German)
  ISBN 4-89502-678-1 (Japanese)

  Programming Perl (The Camel)
  Larry Wall and Randal L. Schwartz
  Copyright (c) 1991 O'Reilly & Associates Inc.
  ISBN 0-937175-64-1 (English)
  ISBN 3-446-17257-2 (German) (Programmieren in Perl, translator:
  Hanser Verlag)
  ISBN 4-89052-384-7 (Japanese)

 There is also some Perl5 (book material) information at:

     http://www.metronet.com/1h/perlinfo/perl5/

 Jon Orwant (the organizer of the comp.lang.perl.tk newgroup) has a book on
 Perl 5 that has a chapter that discusses the Tk extension. (Please note that it is
 mostly about Perl 5, there is a some discussion of four simple Perl/Tk
 programs, but it is not a book wholly devoted to Perl/Tk.) It is nevertheless a
 good introduction to object-oriented Perl 5 programming. The relevant info:

  Perl 5 Interactive Course
  Jon Orwant
  (c) 1996 The Waite Group Press
  A Division of SAMS Publishing, Corte Madera, CA USA
  ISBN: 1-57169-064-6

 The Perl 5 Quick Reference Guide (may require LaTeX for installation) can
 be obtained from any CPAN ftp site. Detailed location information is also
 available at the author's website:

     http://www.xs4all.nl/~jvromans/perlref.html

 The quick reference guide has also been turned into a small Nutshell
 handbook:

  Perl 5 Desktop Reference
  Johan Vromans
  Copyright (c) February 1996 O'Reilly & Associates Inc.
  ISBN: 1-56592-187-9; Order number: 1879

 Eric F. Johnson has a book that discusses many perl5 for Unix vs. perl5 for
 Windows NT issues. He includes a final chapter with extensive discussion of
 the Tk extension and the ->Text() widget in particular. The information on
 that book is:

  Cross-Platform Perl
  (c) 1996 Eric F. Johnson
  MIS:Press/M&T Books
  ISBN: 1-55851-483-X

 Kamran Husain and Robert F. Breedlove have written a perl 5 book that
 includes a chapter on Tk with some discussion of Menu()s. That book is:

  Perl 5 Unleashed
  Kamran Husain and Robert F. Breedlove
  (c) 1996 Sams Publishing, Indianapolis, IN
  ISBN: 0-672-30891-6

 There is also a "Perl 5 How-To" book available that contains a great deal of
 erroneous information about perl/Tk. Among other things that book wrongly
 mentions that it is necessary to have a complete Tcl/Tk library installed on
 one's system to compile the Tk extension to perl. (They are incorrect - it is
 only necessary to have the appropriate perl version, libc and Xlib, the Tk
 extension is otherwise "self-contained").

 There is also a book on perl web client. It features a a chapter on perl/Tk that
 was written by Nancy Walsh:

  Web Client Programming with Perl
  Clinton Wong
  1st Edition March 1997
  O'Reilly & Associates Inc.
  ISBN: 1-56592-214-X; Order number: 214X

 Additional book information may be found at Tom Christiansen's perl & cgi
 books page, or at his Perl-related Book Reviews page.

 The multi-part perl 5 manual pages are available (assuming they have been
 installed in your MANPATH, type man perl, man perlmod etc.).

 The perl 5 man pages are also available on the web at a number of locations. In
 general the more recent the documentation the more helpful it is.

 In addition to the CPAN ftp source sites, a miscellany of internet perl
 resources includes:

 Newsgroups
     comp.lang.perl.misc
     comp.lang.perl.announce
     comp.lang.perl.modules
     comp.infosystems.www.authoring.cgi
     comp.answers
     news.answers
 Perl FAQ-Archives (ftp sites) [Note: FAQ may be many separate files]
 (as of 5.004 the FAQ ships in pod format with perl)
     (see also the CPAN sites)
   North America
     ftp://rtfm.mit.edu/pub/usenet/news.answers/perl-faq/
     ftp://ftp.uu.net/usenet/news.answers/perl-faq  192.48.96.9
     ftp://ftp.khoros.unm.edu/pub/perl/faq.gz       198.59.155.28
   Europe
     ftp://ftp.cs.ruu.nl/pub/NEWS.ANSWERS/perl-faq/ 131.211.80.17
     ftp://src.doc.ic.ac.uk/packages/perl/FAQ       146.169.2.10
 Gopher Perl FAQ
     gopher://gopher.metronet.com/11/perlinfo/faq
 WWW-FAQ for Perl
     http://www.perl.com/perl/faq/
     http://www.smartpages.com/bngfaqs/comp/lang/perl/top.html
     http://www.smartpages.com/bngfaqs/comp/lang/perl/misc/top.html
     http://www.smartpages.com/bngfaqs/comp/lang/perl/announce/top.html
     http://www.cis.ohio-state.edu/hypertext/faq/usenet/perl-faq/top.html
 Perl for Win32 FAQ  (discusses Win95)
     http://www.perl.org/CPAN/doc/FAQs/win32/Perl_for_Win32_FAQ.html

 Perl info sites
 Gopher (gopher:70) perl info sites
   USA
     gopher://gopher.metronet.com/11h/perlinfo
 World Wide Web (http:80) perl info sites
   USA
     http://www.yahoo.com/Computers_and_Internet/Languages/Perl/index.html
     http://www.perl.com/
     http://www.khoros.unm.edu/staff/neilb/perl/home.html
     http://www.khoros.unm.edu:80/staff/neilb/perl/metaFAQ/
     http://www.metronet.com/perlinfo/
     http://www.metronet.com/perlinfo/perl5.html (Perl 5)
     http://www.eecs.nwu.edu/perl/perl.html
     http://cesr39.lns.cornell.edu/public/perl/
     http://www.virtualschool.edu/mon/Perl.html
     http://www.hermetica.com/technologia/unexec/
     http://www.oac.uci.edu/indiv/ehood/perlWWW/
     http://web.sau.edu/~mkruse/www/scripts/
     http://orwant.www.media.mit.edu/the_perl_journal/
     http://www.perl.com/Architext/AT-allperl.html
     http://www.mispress.com/introcgi/
     http://www.walrus.com/~smithj/webcan/
     http://web.syr.edu/~chsiao05/cps600_project.html
     http://www.iftech.com/classes/webdev/webdev_perl.htm
     http://www.cc.iastate.edu/perlmenu/
     http://www.ora.com/www/item/cgi_prog.html
   UK
     http://pubweb.nexor.co.uk/public/perl/perl.html
     http://www.bio.cam.ac.uk/web/form.html
 Web references to Perl mailing lists
     http://www.perl.com/perl/info/mailing-lists.html
     http://www.nicoh.com/cgi-bin/lwgate/PERL5-PORTERS/
     http://www.hut.fi/~jhi/perl5-porters.html
     http://www.rosat.mpe-garching.mpg.de/mailing-lists/

 Tcl/Tk Specific Documentation
 +++++++++++++++++++++++++++++

 The two Tcl/Tk books by Ousterhout and Welch are very good starting points
 (you must however, translate the tcl-isms to perl in the sample scripts):

  Tcl and the Tk Toolkit
  John K. Ousterhout
  Copyright (c) 1994 Addison-Wesley Publishing Company
  ISBN 0-201-63337-X (alk. paper)
  LOC QA76.73.T44097 1994; 005.13'3--dc20

  Practical Programming in Tcl and Tk
  Brent Welch
  Copyright (c) 1995 Prentice Hall
  ISBN 0-13-182007-9

 Within the tclsh or wish shells your manpath includes the tcl/tk man pages
 (which may not be in your login MANPATH). Thus from the % prompt within
 either shell type commands like:

     % man -k Tk

 The Tcl/Tk Reference Guide is also a source of useful information. Although
 it's Tcl specific most perl/Tk commands can be, more or less, easily derived
 from it. [Note that in perl/Tk the names of some functions and some
 configuration options have changed slightly from their Tcl/Tk counterparts.
 With recent versions of perl/Tk a great many functions start with an upper
 case letter and continue with all lower case letters (e.g. there is a perl/Tk
 Entry widget but no entry widget), and many configuration options are all
 lower case (e.g. there is a perl/Tk highlightthickness option but no
 highlightThickness option).] You may fetch the Tcl/Tk Reference Guide
 (may require LaTeX for installation) from:

   ftp://ftp.slac.stanford.edu/software/TkMail/tkref-4.0.1.tar.gz 134.79.18.30
   ftp://ftp.aud.alcatel.com/tcl/docs/tkref-4.0.1.tar.gz          198.64.191.10

 There are a number of other Tcl/Tk resources on the internet including:

 Newsgroups
     comp.lang.tcl
     comp.lang.tcl.announce
     comp.infosystems.www.authoring.cgi
     comp.answers
     news.answers
 FAQ-Archive (ftp) [Note: Tcl FAQ may be many files, Tk FAQ is one file]
     ftp://ftp.aud.alcatel.com/tcl/docs/                          198.64.191.10
     ftp://rtfm.mit.edu/pub/usenet/news.answers/tcl-faq
     ftp://rtfm.mit.edu/pub/usenet/news.answers/tcl-faq/tk
 WWW-FAQ for Tcl/Tk
     http://www.teraform.com/%7Elvirden/tcl-faq/
     http://www.smartpages.com/faqs/tcl-faq/top.html
     http://www.smartpages.com/bngfaqs/comp/lang/tcl/top.html
     http://www.cis.ohio-state.edu/hypertext/faq/usenet/tcl-faq/top.html
   http://www.cis.ohio-state.edu/hypertext/faq/bngusenet/comp/lang/tcl/top.html
     http://www.sco.com/Technology/tcl/Tcl.html
 World Wide Web - Tcl/Tk info sites
   Canada
     http://web.cs.ualberta.ca/~wade/Auto/Tcl.html
   UK
     http://http2.brunel.ac.uk:8080/~csstddm/TCL2/TCL2.html
     http://www.cis.rl.ac.uk/proj/TclTk/
   USA
     http://www.yahoo.com/Computers_and_Internet/Languages/Tcl_Tk/index.html
     http://www.sunlabs.com/research/tcl/docs.html
     http://www.sunlabs.com/research/tcl/4.0.html
     http://www.sco.com/Technology/tcl/Tcl.html
     http://www.neosoft.com/tcl/
     http://www.elf.org/tcltk-man-html/contents.html
 Tcl/Tk - miscellaneous extensions
     ftp://ftp.cme.nist.gov/pub/expect/
     http://www.cs.hut.fi/~kjk/porttk.html
     http://www.cis.upenn.edu/~ioi/tix/tix.html
     http://www.ece.cmu.edu/afs/ece/usr/svoboda/www/th/homepage.html
     http://www.tcltk.com/ [incr Tcl]
     http://www.neosoft.com/tcl/TclX.html
     http://www.eolas.com/eolas/webrouse/tcl.htm [WebWish]
     http://www.se.cuhk.hk/~hkng2/big5tk/big5tk.html
     http://www.cs.uoregon.edu/~jhobbs/work/ [BLT etc.]

 X Documentation
 +++++++++++++++

 Tk certainly makes the generation of GUI code a lot easier than hard coding
 things in traditional compiled languages such as C, C++, or Lisp. Nevertheless
 there is a very large body of X documentation out there that will assist all
 widget and GUI builders with issues of design, implementation, etc. Hence it is
 good practice to be informed of the general design goals of X itself as well as
 the other toolkits that have been built on top of X.

 There are a number of X resources on the internet including:

 Newsgroups
     comp.windows.x
     comp.windows.x.announce
     comp.windows.x.apps
 X FAQs:
     ftp://ftp.x.org/contrib/faqs/
 X FAQ on the World Wide Web:
     http://www.x.org/ftp/contrib/faqs/x-faq-multipart/x-faq-1
     http://www.x.org/ftp/contrib/faqs/x-faq-multipart/x-faq-2
     http://www.x.org/ftp/contrib/faqs/x-faq-multipart/x-faq-3
     http://www.x.org/ftp/contrib/faqs/x-faq-multipart/x-faq-4
     http://www.x.org/ftp/contrib/faqs/x-faq-multipart/x-faq-5
     http://www.x.org/ftp/contrib/faqs/x-faq-multipart/x-faq-6
     http://www.x.org/ftp/contrib/faqs/x-faq-multipart/x-faq-7
 X Window System book info on the Web:
     http://www.x.org/ftp/contrib/docs/Xbibliography.OReilly
     http://www.ora.com/catalog/v1/
     http://www.ora.com/catalog/v2/
     http://www.ora.com/catalog/v3/
     http://www.ora.com/catalog/v4/
     http://www.ora.com/catalog/v5/
     http://www.ora.com/catalog/v6a/
     http://www.ora.com/catalog/v6b/
     http://www.ora.com/catalog/v6c/
     http://www.ora.com/catalog/r6/noframes.html
     http://www.ora.com/oracom/prog/flanart.html
 World Wide Web - X Window System info sites
     http://www.x.org/
     http://www.x.org/consortium/GettingX.html
     http://www.x.org/consortium/x_info.html
     http://www.x.org/consortium/R6.1doc/man/X11/
     http://www.wolfram.com/~cwikla/widget/
     http://www.zeta.org.au/~rosko/pigui.htm
     http://www.rahul.net/kenton/xsites.html
     http://www.unx.com/DD/txaCurrent.shtml

 ______________________________________________________________________



 8. How do I write scripts in perl/Tk?

 Start your script as you would any perl script (e.g. #!/usr/bin/perl,
 #!/usr/local/bin/perl, #!/opt/bin/perl, [built static? then
 #!/usr/bin/tkperl], whatever, see the perlrun(1) man page for more
 information).
 Throwing the -w warning switch is recommended.
 The use of the statement use strict; is recommended.
 Use of the statement use Tk; is required.

 A simple "Hello World!" widget script could be written as follows:

     #!/usr/local/bin/perl -w

     use strict;
     use Tk;

     my $main = new MainWindow;
     $main->Label(-text => 'Hello World!'
                  )->pack;
     $main->Button(-text => 'Quit',
                   -command => sub{exit}
                   )->pack;
     MainLoop;

 The MainLoop; statement is the main widget event handler loop and is
 usually found in perl/Tk scripts (usually near the end of the main procedure
 after the widgets have been declared and packed). MainLoop; is actually a
 function call and you may see it written as MainLoop();, &Tk::MainLoop;,
 &Tk::MainLoop();, etc.

 Note the use of the -> infix dereference operator. Most things in calls to
 perl/Tk routines are passed by reference.

 Note also the use of the => operator which is simply a synonym for the comma
 operator (well it is a bit more than that :-). In other words, the arguments that
 get passed to Label and Button in the above example are good old perl
 associative arrays (perl 5 people prefer to call them "hashes" however).
 Indeed, we might have written the above as:

     #!/usr/local/bin/perl -w

     use strict;
     use Tk;

     my $main = new MainWindow;
     $main->Label(-text , 'Hello World!'
                  )->pack;
     $main->Button(-text , 'Quit',
                   -command , sub{exit}
                   )->pack;
     MainLoop;

 Or even as:

     #!/usr/local/bin/perl -w
     use strict;
     use Tk;
     my $main = new MainWindow;

     my %hello = ('-text','Hello World!');
     my %quit_com = ('-text' => 'Quit', '-command' => sub{exit});

     $main->Label(%hello)->pack;
     $main->Button(%quit_com)->pack;
     MainLoop;

 Note however, that the use of the => in the first method of writing this script
 makes it look more "Tcl-ish" :-).

 Lastly, we note the extensive use of the my function in most perl/Tk programs.
 my is roughly equivalent to local in Perl 4 - but is purported to be "faster and
 safer" as well as much more strictly local in scope. See perlfunc(1)
 manpage for more information on my.

 Other examples of code may be found in the perl5/Tk/demos/ directory
 and in perl5/Tk/demos/widget_lib/.

 (A variant on this scipt called hello is available in the file
 perl5/Tk/demos/hello in your own pTk distribution. Also, Source code
 for this and other examples from UserGuide.pod may be found at
 http://w4.lns.cornell.edu/~pvhp/ptk/pod/. To load code from the web save as a
 local filename, edit the first line to point to your perl interpreter, then: chmod
 u+x filename, then execute: filename.)

 ______________________________________________________________________



 9. What widget types are available under perl/Tk?

 The following Tk widget primitives are available under perl/Tk:

  o Button
  o Canvas
  o Checkbutton
  o Entry
  o Frame
  o Label
  o Listbox
  o Menu
  o Menubutton
  o Message
  o Radiobutton
  o Scale
  o Scrollbar
  o Text
  o Toplevel

 The following are Tix widget primitives available under perl/Tk:

  o HList
  o InputOnly

 There are (a lot of) other [compound|composite|constructs] available too. You
 can also synthesize new widgets out of these primitives using perl5's
 object-oriented multiple inheritance features. You can even build entirely new
 widget primitives from raw C (XS) code then use and re-use that. (Perl 5 is
 extremely configurable.)

 A good introduction to the primitives and how they may be used in
 conjunction with each other may be found in the widget demo script. Note
 that all the widget demos have a "Show Code" button. To help figure out what
 is happening in the script you may, when the window appears, edit the text and
 instrument the code with print statements and then simply press "Rerun
 Demo". Another place to see examples of the primitives (on the web) is at the
 image supplement to this FAQ at the following URL:

     http://w4.lns.cornell.edu/~pvhp/ptk/ptkIMG.html