TODO

Scratch pad of bugs, missing features, and misbehaviors collected while using tkpod.

BUGS

Tk::Pod

• S<> seems often to be ignored. May be a core Tk::Text bug (i.e. -wrap => "none" in tags being sometimes ignored)
• For Windows: check whether Tk::More/Tk::Tree match the system background colors. Also check if the "Help" menu item is on the correct place.
• Title is not displayed if function or FAQ pod in displayed in a new window or when navigating in the history back or forward to a function/FAQ pod.
• $podtext->configure(-file => ...) does not work always as expected. When set from a command line argument, then one expects to use the name of a module in perl's pod path (specified without .pm or .pod extension) or a (relative) path to a file (with extension). Example:

      cd ~/src/bbbike
      tkpod ESRI/esri2bbd.pl
      * now click on bbbike link => bbbike itself will be loaded, not bbbike.pod
        because of a -f test in findpod

• Do not move focus if already in PodText's search entry.
• The perlfunc subentries do not show up in the history.
• Paragraphs after bullet and number items do not align correctly. Tweaking the _indent functionality in Tk::Pod::SimpleBridge seems to be necessary.
• If .pod and .pm are located in separated directories, then the wrong file (the .pm) might be chosen. Seen on Debian with IO::Handle.
• There is never a horizontal scrollbar, even if a verbatim block exceeds the window width. An workaround would be to have the vertical scrollbar non-optional and the horizontal scrollbar optional (unfortunately both cannot be optional because of a bug in the Scrolled code).

Tk::Pod::FindPods

• The location of the cache file is predictable and on /tmp which is bad. Either choose a unpredictable but unique filename, or use techniques like O_EXCL (is this supported everywhere?).

Tk::Pod::Search

• Reorder modules in the fulltext search results to reflect @INC order.

Tk::Pod::Tree

• Make tree busy while building first time.
• Show a progress bar or an indicator when refreshing the pod index.

Tk::More

• Highlight matches in link text.

tkpod

• In server mode, no commandline options are accepted. Probably at least -h/-? should be supported and errors for other options dropped.
• Get rid of the numerous warnings in server/client mode.
• If the client sends a file which cannot be opened, then the server crashes!
• The tkpod client should send cwd, so relative filenames work in server mode, too.

WISHLIST

Tk::Pod

• History: prefer short pod names over filenames. Do not record temporary file names (as in perldoc -f / -q) in history view.
• If "perlindex -index" is not run yet: ask user to run it? Problematic on Unix, because perlindex should be run as superuser.
• On Windows: show printer selection dialog first, maybe also on KDE/GNOME, if available.
• Optionally save settings on exit, e.g. current base font size.
• Marek Rouchal writes:

  Subject: tkpod - other font

  Fine, there is a central place where I can do adaptations easily - but how can I easily override? The only solution I can imagine right now is to place a Tk::Pod::Styles in some $PERL5LIB directory and shadow the installation's Tk::Pod::Styles; there could be e.g. a -usestyle Tk::Pod::Styles::Mine option, where I can provide my own package, which inherits from Tk::Pod::Styles and overrides one or more subs.

  But I would appreciate a general solution with either a ~/.tkpodrc or the X resources, as already mentioned.

  -> There's now a solution with X resources, which are also settable with -xrm. But maybe a .tkpodrc solution would also be nice, especially for non-X11 people.

• Maybe patch Ulrichs TPJ example code for nroff pages to allow both POD and MAN in fulltext search dialog.
• add meaningful regression tests
• use some kind of access control for the -s option
• new menu entry with a link list (e.g. all L<...> and everything looking like a module /\w+::\w+/)
• make ManViewer into a standalone widget, link entries in "SEE ALSO"
• option for interleaving POD and code
• show "No documentation found for "..."" if there's no pod in the file (just like perldoc)
• maybe you something selectable and copyable (e.g. Tk::ROText) in the About dialog
• support for the new Pod::Index module (similar to the fulltext search)
• some kind of stylesheet support
• It should probably be possible to create the menus Section and History independently of the main Tk::Pod frame, so the user may add these menus to the context menu of the PodText window.
• Have a new popup menu entry "Copy Pod location", and maybe a new menu entry View -> Pod info which shows path and basic Pod information.
• If a Pod could not be found: add a button "Look at search.cpan.org" to the error dialog.
• "Open Pod by name" dialog could be done nicer, e.g. by using a rich Tk::Text instead of the label/message and use "sans serif"+"monospace" fonts.

Tk::More

• Tk/More status bar: filename % line x
• more 'more' like key bindings to Tk::More.
• More.pm: search should scroll per page
• search policies: regexp, glob, incremental (as in xmore) and 'normalized' as in perlindex. Should go into it's own Tk::Text::Util.pm module
• after switching between case sensitive/insensitive highlightning should be updated immediately
• scrolling is not as exact as it shoule be (i.e. scroll forw, then scroll back will not get to the same position as before)
• use Tk::HistEntry for search entry
• implement isearch
• <Return> over a link opens the link (but this needs some kind of "current link" feature, probably by using <Tab> or similar to select the next link).

Tk::Pod::Cache

• use a LRU cache with $MAX_CACHE documents
• maybe do not cache small documents at all
• store modtime of POD files and flush cache automatically if the file changed

Tk::Pod::Tree

• Some zoom functionality, maybe depending on the zoom factor of the main window, and/or an additional menu entry.
• Should I include something similar to perlfunc for perlfaq (perldoc -q)? Maybe a new menu item "Search FAQ"?
• Implement -rememberopen in Fill method.
• Mark modules which appear multiple times in the @INC tree, e.g. with an exclamation mark, and maybe show the paths and versions(?) of both/all versions.

tkpod

• Instead of listening to a tcp socket, maybe one should use a unix domain socket (security, a unix domain socket may be chown'ed and chmod'ed!)

Expired

These bugs are probably fixed or not reproducable or apparent on old systems only:

• Ctrl-O Exporter does not work?!
• What about the reported error on Suse Linux (see Tk-Pod entry on rt.cpan.org)? I can't reproduce this bug...
• Dump does not always work on a RedHat 8.0 system, so I had to use a workaround. Also, Tk::Pod very often dumps core on this system in conjuction with perl5.8.0 and Tk800.025, but this might be a RedHat-related issue.