CPAN+changelog.pl TECH DETAILS
==============================
Date: 2007/06/05


- COMPATIBILITY
  - Tested on NetBSD2.1              (perl 5.8.7, perl 5.8.8)
              SuSE Linux 8.1         (perl 5.8.5)
              SuSE Linux 8.2         (perl 5.8.6)
              SuSE Linux 9.0         (perl 5.8.1)
              SuSE Linux 9.1         (perl 5.8.7, perl 5.8.8)
              SuSE Linux 9.2         (perl 5.8.7)
              Debian GNU/Linux sarge (perl 5.8.7)
              SuSE Linux 10.0        (perl 5.8.8)
              SuSE Linux 10.1        (perl 5.8.8)
    CPAN >= 1.76
    File::Basename;
    File::Temp qw/ tempfile /;
    FileHandle;

  - Will not work on Windows because I did not bother to use File::Spec
    for composing path names but used "/" throughout.
    Perhaps in a later version if someone asks me nicely :-)

  - You can continue to use plain CPAN for upgrades without breaking
    this program. You just have fewer hints for the "-history"
    function and the local ChangeLog database gets out of sync for those
    modules, so the next "-r" ChangeLog output might be incorrect for
    them, but they will still be correctly detected as upgradeable.


- PREREQUISITES
  - a working Perl installation with a working CPAN configuration
  - gzip, zgrep, xargs and find within your $PATH
    (ls is also used, but is probably handled by your shell's builtin)


- RECOMMENDATION
  - sometimes the CPAN module behaves strangely when it cannot use
    LWP to handle internet downloads. Do yourself a favour and install
    Bundle::LWP.


- INSTALLATION
  Since it is a single file, not much installation action is required.
  If your perl is not at /usr/bin/perl, edit the first line to point
  to your perl interpreter.
  Copy the program to where you deem adequate, e.g. into
    /usr/local/bin
  Best install it to a directory that's inside your $PATH.

  To "-init" or not to "-init":
  If your Perl modules are already uptodate with CPAN, then you might
  want to first start the software with the "-init" option
  to initialise the local ChangeLog database. This reduces future
  "-r" output to the real novelties in the distributions
  ChangeLog file. Running "-init" may take quite a while as some
  files probably need to be fetched from CPAN.
  ONLY USE "-init" IF YOUR MODULES ARE UP TO DATE!
  Otherwise the ChangeLog database will be filled with the most recent
  CPAN versions and you will not see much ChangeLog on the next "-r"
  run.
  Other than being treated with the full ChangeLog file instead of
  just the changes there are no dangers in not using "-init".


- INVOCATION

        CPAN+changelog.pl [<options>...]
    or  /your/installed/CPAN+changelog.pl [<options>...]
    or  /path/to/perl /your/installed/CPAN+changelog.pl [<options>...]

    If you installed the script to a directory within your $PATH,
    you can use the first form. The first and second form depend
    on the correct interpreter line in the script file itself.
    As it uses your CPAN configuration values, the third form
    of invocation allows you to manage CPAN updates for several
    Perl installations on the same host. Just choose the
    right /path/to/perl.


- OPTIONS

      -r        this is the default action if no options are given.
                shows the list of upgradeable modules and the relevant
                ChangeLog entries. 
                Note: this requires that the latest distribution
                      files of upgradeable modules are downloaded and
                      unpacked. It might therefore take significantly
                      longer than CPAN's native "r" command.

      -install <what>[,<what>...]
                <what> can be the name of a module, a bundle or a
                distribution. To downgrade a module you need to
                "-install" the distribution containing the wanted
                module version.
                While it is possible to mix bundles, modules,
                distributions, upgrades and downgrades into a single
                call, I strongly advise against doing so for the sake
                of clarity.
                It calls CPANs native "install" for every <what> while
                collecting screen output in a BuildLog file.
                If there are any module version changes after the
                install, CPANs "autobundle" is called to generate a
                snapshot of the currently installed modules.
                Additional output: -ChangeLogs of installed modules
                                   -diff against the previous snapshot
                                   -full path of the BuildLog
                                   -modules that have not changed
                                     in spite of having been "install"ed
                Examples for <what>:
                   Time::HiRes                          (module)
                   J/JH/JHI/Time-HiRes-1.85.tar.gz      (distribution)
                   Bundle::Snapshot_2005_12_15_00       (bundle)
                Note: The check for every Perl modules' version number
                      can take a while, depending on your CPU and 
                      disk speed. This check is done before and after
                      CPANs native "install" function to detect version
                      changes.

      -shell    invokes the interactive CPAN shell (CPAN::shell), so you
                can use any of the interactive features it provides.
                As with "-install" above, output is preserved in a
                BuildLog. If you successfully installed anything, the
                ChangeLog database will be updated and autobundle is
                called upon exit.
                Note: because of the output redirection, the command
                      prompts (readline) may not be where you expect
                      them. Usually, an extra RETURN gets the cpan 
                      prompt back, but watch out for readline prompts
                      during module installation.

      -force    (only used with -install)
                Does a "force install" instead of a "install". Use
                with caution! Only use -force if you know what you
                are doing!

      -history <module>[,<module>...]
                searches snapshot bundles and BuildLogs for mentions
                of the named module(s) and displays them in
                chronological order.
                Snapshots are only listed if the version number of the 
                module(s) has changed.
                Also shows the locally available distribution files 
                containing older or newer versions of the module(s).

      -init
                initialize the local ChangeLog database. For every 
                module installed it fetches the most recent CPAN
                version and retrieves the ChangeLog file from it.
                Note: If you run "-init" while your modules are not
                      uptodate with CPAN, "-r" will not show you any
                      changes next time (but it still shows the
                      upgradeable modules). You might as well choose
                      not to run "-init" at all, but expect "-r"
                      output to be very lengthy the first time a
                      module will be reported as upgradeable. After an
                      "-install" the local ChangeLog for the module
                      will be in sync again.
        
      -version
                shows the RCS revision number

      -license
                shows disclaimer, license and notes about the license

      -addignore <module_or_distribution>[,<module_or_distribution>...]
                adds an ignore entry for the given distribution file(s) 
                or the current CPAN version of the distribution for a
                given module name.
                The ignore list is kept at $CPANHOME/CPAN+changelog.ignore

                Effect of ignore list entries:
                  - "-r" will not show that revision as upgradeable anymore,
                    only when a newer version than the ignored one is
                    available on CPAN 
                  - "-install" will not install an ignored distribution file,
                    provided it was explicitly named as an "-install" 
                    argument. 

                This is helpful when you know a certain distribution to be
                buggy, then the "-r" reports will not be cluttered with
                an ignored distribution file anymore.
                If you don't want to see buggy libnet-1.20 anymore in the
                reports, use "-addignore G/GB/GBARR/libnet-1.20.tar.gz"

                Note: this does not help against CPAN's auto dependency 
                      resolution, which might install it e.g. as part of
                      a Bundle. 
                      it only helps you against inadvertedly 
                      upgrading a known bad distribution.
               
      -delignore <module_or_distribution>[,<module_or_distribution>...]
                removes ignore entries from the ignore file

      -showignore
                lists all currently ignored distribution files with their
                date of appearance in the list


- FILES AND DIRECTORIES

    external programs: gzip, zgrep, xargs, find

    $CPAN::Config->{'build_dir'}        CPAN build directory
    $CPAN::Config->{'cpan_home'}        CPAN home directory

    <cpan_home>/Bundle/         contains Snapshot bundles

    <cpan_home>/ChangeLogs/     directory-based ChangeLog db

                          <dist>/<chlog>
                                <dist> is the base name of a
                                   distribution file, with stripped-
                                   off version number,
                                <chlog> ist the name of the ChangeLog
                                   file in this distribution
                                   (Changes/ChangeLog/WhatsNew)

    <cpan_home>/BuildLogs/      directory for the BuildLogs

                          BuildLog-<YYYYMMDD>-<HHMMSS>-<XXXXXX>.gz
                                 BuildLog from an install started at
                                   <YYYYMMDD>-<HHMMSS>

               /CPAN+changelog.ignore
                                list of distribution files to be ignored
