NAME
    Pinto - Perl distribution repository manager

VERSION
    version 0.008

DESCRIPTION
    You probably want to look at the documentation for pinto. This is a
    private module (for now) and the interface is subject to change. So the
    API documentation is purely for my own reference. But this document does
    explain what Pinto does and why it exists, so feel free to read on
    anyway.

    This is a work in progress. Comments, criticisms, and suggestions are
    always welcome. Feel free to contact "thaljef@cpan.org".

METHODS
  create()
    Creates a new empty repository.

  mirror()
    Populates your repository with the latest version of all packages found
    on the CPAN mirror. Your locally added packages will always mask those
    pulled from the mirror.

  add(file => 'YourDist.tar.gz', author => 'SOMEONE')
  remove(package => 'Some::Package', author => 'SOMEONE')
  clean()
  list()
  verify()
TERMINOLOGY
    Some of the terms around CPAN are frequently misused. So for the purpose
    of this document, I am going to define some terms. I am not saying that
    these are necessarily the "correct" definitions, but this is what I mean
    when I use them.

    package
        A "package" is the name that appears in a "package" statement. This
        is what PAUSE indexes, and this is what you usually ask cpan or
        cpanm to install for you.

    module
        A "module" is the name that appears in a "use" or (sometimes)
        "require" statement, and it always corresponds to a physical file
        somewhere. A module usually contains only one package, and the name
        of the module usually matches the name of the package. But
        sometimes, a module may contain many packages with completely
        arbitrary names.

    distribution
        An "distribution" is a collection of Perl modules that have been
        packaged in a particular structure. This is what you get when you
        run ""make dist"" or "./Build dist". Distributions may come from a
        "mirror", or you may create your own.

    repository
        A "repository" is a collection of distributions that are organized
        in a particular structure, and having an index describing which
        packages are contained in each distribution. This is where cpan and
        cpanm get the packages from.

    mirror
        A "mirror" is a copy of a public CPAN repository (e.g.
        http://cpan.perl.org). Every "mirror" is a "repository", but not
        every "repository" is a "mirror".

RULES
    There are certain rules that govern how the indexes are managed. These
    rules are intended to ensure that folks pulling packages from your
    repository will always get the *right* packages (according to my
    definitionof "right"). Also, the rules attempt to make Pinto behave
    somewhat like PAUSE does.

    A local package always masks a mirrored package, and all other packages
    that are in the same distribution with the mirrored package.
        This rule is key, so pay attention. If the CPAN mirror has a
        distribution that contains both "Foo" and "Bar" packages, and you
        add your own distribution that contains "Foo" package, then both the
        "Foo" and "Bar" mirroed packages will be removed from your index.
        This ensures that anyone pulling packages from your repository will
        always get *your* version of "Foo". But as a result, they'll never
        be able to get "Bar".

    You can never add an distribution with the same name twice.
        Most distribtuion-building tools will put some kind of version
        number in the name of the distribution, so this is rarely a problem.

    Only the original author of a local package can add a newer version of
    it.
        Ownership is given on a first-come basis, just like PAUSE. So if
        "SALLY" is the first author to add local package "Foo::Bar" to the
        repository, then only "SALLY" can ever add that package again.

    Only the original author of a local package can remove it.
        Just like when adding new versions of a local package, only the
        original author can remove it.

WHY IS IT CALLED "Pinto"
    The term "CPAN" is heavily overloaded. In some contexts, it means the
    CPAN module or the cpan utility. In other contexts, it means a mirror
    like <http://cpan.perl.org> or a site like <http://search.cpan.org>.

    I wanted to avoid confusion, so I picked a name that has no connection
    to "CPAN" at all. "Pinto" is a nickname that I sometimes call my son,
    Wesley.

TODO
    Enable plugins for visiting and filtering
    Implement Pinto::Store::Git
    Fix my Moose abuses
    Consider storing indexes in a DB, instead of files
    Automatically fetch dependecies when adding *VERY COOL*
    New command for listing conflicts between local and mirrored index
    Make file/directory permissions configurable
    Need more error checking and logging
    Lots of tests to write

THANKS
    Randal Schwartz - for pioneering the first mini CPAN back in 2002
    Ricardo Signes - for creating CPAN::Mini, which inspired much of Pinto
    Shawn Sorichetti & Christian Walde - for creating CPAN::Mini::Inject

SUPPORT
  Perldoc
    You can find documentation for this module with the perldoc command.

      perldoc Pinto

  Websites
    The following websites have more information about this module, and may
    be of help to you. As always, in addition to those websites please use
    your favorite search engine to discover more resources.

    *   Search CPAN

        The default CPAN search engine, useful to view POD in HTML format.

        <http://search.cpan.org/dist/Pinto>

    *   RT: CPAN's Bug Tracker

        The RT ( Request Tracker ) website is the default bug/issue tracking
        system for CPAN.

        <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Pinto>

    *   CPAN Ratings

        The CPAN Ratings is a website that allows community ratings and
        reviews of Perl modules.

        <http://cpanratings.perl.org/d/Pinto>

    *   CPAN Testers

        The CPAN Testers is a network of smokers who run automated tests on
        uploaded CPAN distributions.

        <http://www.cpantesters.org/distro/P/Pinto>

    *   CPAN Testers Matrix

        The CPAN Testers Matrix is a website that provides a visual way to
        determine what Perls/platforms PASSed for a distribution.

        <http://matrix.cpantesters.org/?dist=Pinto>

    *   CPAN Testers Dependencies

        The CPAN Testers Dependencies is a website that shows a chart of the
        test results of all dependencies for a distribution.

        <http://deps.cpantesters.org/?module=Pinto>

  Bugs / Feature Requests
    Please report any bugs or feature requests by email to "bug-pinto at
    rt.cpan.org", or through the web interface at
    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Pinto>. You will be
    automatically notified of any progress on the request by the system.

  Source Code
    <https://github.com/thaljef/Pinto>

      git clone https://github.com/thaljef/Pinto

AUTHOR
    Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2011 by Imaginative Software Systems.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.

