[rt-users] Documentation for installing extensions

[Alex Vandiver]

On 12/12/2014 02:39 AM, Jo Rhett wrote:
> On Dec 11, 2014, at 11:26 AM, Alex Vandiver
> <alexmv at bestpractical.com> wrote:
>> Moving to the topic at hand: the links we provide are to the 
>> documentation of the module, not to the distribution page.  This
>> is intentional, soas to provide the user with a longer description
>> of the extension first, to let them make a more informed decision
>> as to whether the extension suits their needs.
> 
> Linking to the documentation makes sense. Linking to the module docs
> without any clear installation instructions does not.

Picking a commonly-used module, RT::Extension::SLA, and looking at the
documentation we link to:

http://search.cpan.org/~alexmv/RT-Extension-SLA-1.03/lib/RT/Extension/SLA.pm#INSTALLATION

It contains an "INSTALLING" section which details the steps necessary to
install the module.  I believe that all, or nearly all, of the modules
that Best Practical places on CPAN have a similar section.

> Even if one is an established Perl hacker, a large majority of CPAN
> modules are a single .pm file. The fact that one must download the
> entire package, not just the singular file, is not stated anywhere.
> This deserves clarity.

Can you point me at documentation which suggests downloading one file
from CPAN and putting it in place manually?  Perl's own core
documentation (http://perldoc.perl.org/perlmodinstall.html ) suggests:
 * downloading a .tar.gz file
 * unpacking it
 * running `perl Makefile.PL`
 * followed by running `make install`

Note the date in the footer: written 1998, and last updated 2003; these
are not new suggestions.  A search for "install perl module"
additionally confirms that the steps are what are, by and large,
suggested everywhere.  These are thus the steps which RT extensions
mirror in their installation.

This is not to say that we cannot make RT's documentation on this
subject clearer.  I'm happy to take patches atop the docs I just pushed:

https://github.com/bestpractical/rt/blob/4.2/installing-extensions/docs/extensions.pod


> I believe that anything which solves the basic confusion here will be
> an improvement. Links as simple as the following would be a big
> improvement. [Documentation] [Download]

*nod*  Makes sense, and shouldn't be hard.  I'll add a direct download
link to the Extensions page.

 - Alex


N.B.  I have intentionally snipped all discussion of insulting behavior.
 Bringing up that topic further is not productive, and, itself, does not
contribute to a welcoming atmosphere.  Keep the discussion here
technical, not emotional.