==== NAME ====

Posy::Plugin::Info - Posy plugin which gives supplementary entry
information.


==== VERSION ====

This describes version ``0.04'' of Posy::Plugin::Info.


==== DESCRIPTION ====

This plugin enables the user to provide supplementary information about each
entry in .info files (in Field:Value format), which are parsed and will set
$info_* flavour variables which can be used in flavour templates. This
plugin can also be used to sort entries by the .info information fields.

This enables one to create useful summaries of entry contents for use in
category or chrono listings when one does not want to display the whole
entry. While Posy::Plugin::ShortBody enables one to display just the first
sentence in an entry, the usefulness of that can vary widely depending on
what the first sentence is. With Posy::Plugin::Info one has much more
control over the summary information.

Even more powerful, the sort-by-info ability enables one to sort entries on
much more significant information than just the date or the filename. What
the information actually *is* is entirely up to you.

This plugin requires Posy::Plugin::YamlConfig in order to set the type
information in the info fields.

This plugin replaces the 'sort_entries' action, the 'set_vars' action, and
provides an 'info' method for returning the info, if any, related to an
entry.


==   Configuration   ==

This expects configuration settings in the $self->{config} hash, which, in
the default Posy setup, can be defined in the main "config" file in the data
directory.

``info_sort''
If true, enable sorting on .info information. (default: false)

``info_type_spec''
Define the info-fields and their types.

    info_type_spec:
      Title:
        type: title
      Order:
        type: number
      Rating:
        type: limited
        values:
          - G
          - PG
          - PG13
          - R
      Author:
        type: string
      Summary:
        type: text

This gives a list of all the fields, and their types, with possible options.
This is used for both sorting and for other plugins which depend on this
one. The types are used to determine the kind of comparison or presentation
of the particular field.

string
A short string, which needs normal string comparison. The default.

text
A multi-line string, which also uses normal string comparison, but may need
to be presented differently (needing a textarea in a form, for example).

number
Compare as a number.

title
The field is a title; compare as if any leading "The" or "A" was not there.

limited
A short string which is only allowed a limited number of values. The
"values" part of the definition gives those values. This is not actually
enforced, but can be useful when desiring to present selectable options.

``info_sort_spec''
Define the default order by which the entries will be sorted.

    info_sort_spec:
      order:
        - Author
        - Title
        - Order
      reverse_order:
        Title: 1

The 'order' part of the spec is the order the fields are to be sorted by.
The 'reverse_order' part of the spec defines which fields should be sorted
in reverse order; if the field name is there, with a value of 1/true/on,
then that field is to be sorted in reverse.

If after sorting by the fields, there is still no difference, this will fall
back to sorting by time, name or path, depending on what the value of the
config variable 'sort_type' is.

``info_sort_param''
Defining this parameter enables sorting to be specified with a parameter in
the URL. (default: '')

    posy.cgi?info_sort=Author;info_sort=Title

``info_sort_param_reverse''
If ``info_sort_param'' is defined, this defines the parameter which
specifies what fields are sorted in reverse order.

    posy.cgi?info_sort_reverse=Date


==== INSTALLATION ====

Installation needs will vary depending on the particular setup a person has.


==   Administrator, Automatic   ==

If you are the administrator of the system, then the dead simple method of
installing the modules is to use the CPAN or CPANPLUS system.

    cpanp -i Posy::Plugin::Info

This will install this plugin in the usual places where modules get
installed when one is using CPAN(PLUS).


==   Administrator, By Hand   ==

If you are the administrator of the system, but don't wish to use the
CPAN(PLUS) method, then this is for you. Take the *.tar.gz file and untar it
in a suitable directory.

To install this module, run the following commands:

    perl Build.PL
    ./Build
    ./Build test
    ./Build install

Or, if you're on a platform (like DOS or Windows) that doesn't like the "./"
notation, you can do this:

   perl Build.PL
   perl Build
   perl Build test
   perl Build install


==   User With Shell Access   ==

If you are a user on a system, and don't have root/administrator access, you
need to install Posy somewhere other than the default place (since you don't
have access to it). However, if you have shell access to the system, then
you can install it in your home directory.

Say your home directory is "/home/fred", and you want to install the modules
into a subdirectory called "perl".

Download the *.tar.gz file and untar it in a suitable directory.

    perl Build.PL --install_base /home/fred/perl
    ./Build
    ./Build test
    ./Build install

This will install the files underneath /home/fred/perl.

You will then need to make sure that you alter the PERL5LIB variable to find
the modules.

Therefore you will need to change the PERL5LIB variable to add
/home/fred/perl/lib

        PERL5LIB=/home/fred/perl/lib:${PERL5LIB}


==== REQUIRES ====

    Posy
    Posy::Core
    Posy::Plugin::YamlConfig

    Test::More


==== AUTHOR ====

    Kathryn Andersen (RUBYKAT)
    perlkat AT katspace dot com
    http://www.katspace.com


==== COPYRIGHT AND LICENCE ====

Copyright (c) 2005 by Kathryn Andersen

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