Plugins link to module file, not package file

Hey guys and gals, been a long time.

I’m doing an upgrade from 3.8.5 to 4.2. It seems to be going well. I’m liking the changes. Other than some confusion about what order to do things in (see my other message) the one thing I can’t seem to wrap my head around is the new plugin setup.

First, yay! I like the idea of what you’ve done with plugins, keeping them local and the simplified syntax in RT_SiteConfig.pm.

[in which I wander in the wrong direction… read and giggle]

However, I can’t find any plugins other than yours which are built in these new packages you document at https://www.bestpractical.com/docs/rt/4.2/writing_extensions.html

What is the fallback method for installing the other style modules? How do I get from a .pm file to an installed module. Can I manually create the directory structures and copy these into place? I see some details there but it doesn’t inspire confidence that everything I need to know is there. A breakout of the directory structure would be really helpful.

[forehead slap]

I was almost done with this e-mail when I realized the problem. If you go to http://bestpractical.com/rt/extensions.html and you find the extension you are looking for, the link to the Homepage for the extension actually links to the main module, and not to the extension package. Example for one

Homepage link takes you to:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

If you’re a bit tired and under-caffeniated, or just plain new to RT, it may not be clear to you that you need to remove a bunch from the URL to find the extension package. In my opinion, it would be much better to link to the package instead of the module file, like so:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/

I did some random spot checking, and this appears to be true for every module shown there.

Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.

Hey, dunno if this got overlooked during the short vacation week. This is a pretty serious issue… asking users to manually hack up the URL in their browser bar is not accessible.On Nov 26, 2014, at 2:22 PM, Jo Rhett jrhett@netconsonance.com wrote:

Hey guys and gals, been a long time.

I’m doing an upgrade from 3.8.5 to 4.2. It seems to be going well. I’m liking the changes. Other than some confusion about what order to do things in (see my other message) the one thing I can’t seem to wrap my head around is the new plugin setup.

First, yay! I like the idea of what you’ve done with plugins, keeping them local and the simplified syntax in RT_SiteConfig.pm.

[in which I wander in the wrong direction… read and giggle]

However, I can’t find any plugins other than yours which are built in these new packages you document at https://www.bestpractical.com/docs/rt/4.2/writing_extensions.html

What is the fallback method for installing the other style modules? How do I get from a .pm file to an installed module. Can I manually create the directory structures and copy these into place? I see some details there but it doesn’t inspire confidence that everything I need to know is there. A breakout of the directory structure would be really helpful.

[forehead slap]

I was almost done with this e-mail when I realized the problem. If you go to http://bestpractical.com/rt/extensions.html and you find the extension you are looking for, the link to the Homepage for the extension actually links to the main module, and not to the extension package. Example for one

Homepage link takes you to:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

If you’re a bit tired and under-caffeniated, or just plain new to RT, it may not be clear to you that you need to remove a bunch from the URL to find the extension package. In my opinion, it would be much better to link to the package instead of the module file, like so:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/

I did some random spot checking, and this appears to be true for every module shown there.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.

Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.

Could you please clarify what you’re asking here? How to install the
plugins?

The plugins can be installed like any other CPAN module. Given a link to a
specific .pm file:

http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

you can hit the Download link on the right side of the page to receive a
.tar.gz file of the distribution, which can either be fed directly into the
cpan or cpanm utilities, or unpacked and installed manually using
Makefile.PL and make.

With RT extensions, you may find it useful to set environment variable
RTHOME to the root directory of your RT installation before installing the
plugin:

$ RTHOME=/opt/rt-4.2.7 cpanm RT-Extension-MandatorySubject-0.05.tar.gzOn 3 December 2014 at 16:19, Jo Rhett jrhett@netconsonance.com wrote:

Hey, dunno if this got overlooked during the short vacation week. This is
a pretty serious issue… asking users to manually hack up the URL in their
browser bar is not accessible.

On Nov 26, 2014, at 2:22 PM, Jo Rhett jrhett@netconsonance.com wrote:

Hey guys and gals, been a long time.

I’m doing an upgrade from 3.8.5 to 4.2. It seems to be going well. I’m
liking the changes. Other than some confusion about what order to do things
in (see my other message) the one thing I can’t seem to wrap my head around
is the new plugin setup.

First, yay! I like the idea of what you’ve done with plugins, keeping them
local and the simplified syntax in RT_SiteConfig.pm.

[in which I wander in the wrong direction… read and giggle]

However, I can’t find any plugins other than yours which are built in
these new packages you document at
https://www.bestpractical.com/docs/rt/4.2/writing_extensions.html

What is the fallback method for installing the other style modules? How do
I get from a .pm file to an installed module. Can I manually create the
directory structures and copy these into place? I see some details there
but it doesn’t inspire confidence that everything I need to know is there.
A breakout of the directory structure would be really helpful.

[forehead slap]

I was almost done with this e-mail when I realized the problem. If you go
to http://bestpractical.com/rt/extensions.html and you find the extension
you are looking for, the link to the Homepage for the extension actually
links to the main module, and not to the extension package. Example for one

Homepage link takes you to:

http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

If you’re a bit tired and under-caffeniated, or just plain new to RT, it
may not be clear to you that you need to remove a bunch from the URL to
find the extension package. In my opinion, it would be much better to link
to the package instead of the module file, like so:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/

I did some random spot checking, and this appears to be true for every
module shown there.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and
internet projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and
internet projects.

As I said below, in the Extensions directory the links are broken. For example,

Homepage link takes you to:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

If you’re a bit tired and under-caffeniated, or just plain new to RT, it may not be clear to you that you need to remove a bunch from the URL to find the extension package. In my opinion, it would be much better to link to the package instead of the module file, like so:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/

As I just said, asking the user to edit the URL in their browser window to be able to find the extension to download doesn’t make a lot of sense. The links in the directory should be fixed.On Dec 2, 2014, at 11:34 PM, Alex Peters alex@peters.net wrote:

Could you please clarify what you’re asking here? How to install the plugins?

The plugins can be installed like any other CPAN module. Given a link to a specific .pm file:

http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

you can hit the Download link on the right side of the page to receive a .tar.gz file of the distribution, which can either be fed directly into the cpan or cpanm utilities, or unpacked and installed manually using Makefile.PL and make.

With RT extensions, you may find it useful to set environment variable RTHOME to the root directory of your RT installation before installing the plugin:

$ RTHOME=/opt/rt-4.2.7 cpanm RT-Extension-MandatorySubject-0.05.tar.gz

On 3 December 2014 at 16:19, Jo Rhett jrhett@netconsonance.com wrote:
Hey, dunno if this got overlooked during the short vacation week. This is a pretty serious issue… asking users to manually hack up the URL in their browser bar is not accessible.

On Nov 26, 2014, at 2:22 PM, Jo Rhett jrhett@netconsonance.com wrote:

Hey guys and gals, been a long time.

I’m doing an upgrade from 3.8.5 to 4.2. It seems to be going well. I’m liking the changes. Other than some confusion about what order to do things in (see my other message) the one thing I can’t seem to wrap my head around is the new plugin setup.

First, yay! I like the idea of what you’ve done with plugins, keeping them local and the simplified syntax in RT_SiteConfig.pm.

[in which I wander in the wrong direction… read and giggle]

However, I can’t find any plugins other than yours which are built in these new packages you document at https://www.bestpractical.com/docs/rt/4.2/writing_extensions.html

What is the fallback method for installing the other style modules? How do I get from a .pm file to an installed module. Can I manually create the directory structures and copy these into place? I see some details there but it doesn’t inspire confidence that everything I need to know is there. A breakout of the directory structure would be really helpful.

[forehead slap]

I was almost done with this e-mail when I realized the problem. If you go to http://bestpractical.com/rt/extensions.html and you find the extension you are looking for, the link to the Homepage for the extension actually links to the main module, and not to the extension package. Example for one

Homepage link takes you to:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

If you’re a bit tired and under-caffeniated, or just plain new to RT, it may not be clear to you that you need to remove a bunch from the URL to find the extension package. In my opinion, it would be much better to link to the package instead of the module file, like so:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/

I did some random spot checking, and this appears to be true for every module shown there.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.

Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.

As I just said, asking the user to edit the URL in their browser window
to be able to find the extension to download doesn�t make a lot of
sense. The links in the directory should be fixed.

Why do you want to download the extension?
You can install them by cpan with
cpan RT::Extension::MandatorySubject

Chris

I think I might be missing something crucial in what you are saying/asking.

Linking to the main module within a distribution is a very common practice,
because that module is likely to have the most relevant documentation for
that distribution.

The distribution is clearly linked to on the page of every module belonging
to a particular distribution.

“Asking the user to edit the URL in their browser window to be able to find
the extension to download doesn’t make a lot of sense” is essentially a
fallacy, because:

  1. the download link for the extension is available on that very page;
    and
  2. the home page for the extension itself (which in my opinion is
    generally far less informational anyway) is available as a link on that
    very page.

Can you please rephrase why you feel that the links in the directory should
be changed? Your assertion that these links are “broken” in their current
form is confusing to me.On 3 December 2014 at 18:40, Jo Rhett jrhett@netconsonance.com wrote:

As I said below, in the Extensions directory the links are broken. For
example,

Homepage link takes you to:

http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

If you’re a bit tired and under-caffeniated, or just plain new to RT, it
may not be clear to you that you need to remove a bunch from the URL to
find the extension package. In my opinion, it would be much better to link
to the package instead of the module file, like so:

http://search.cpan.org/dist/RT-Extension-MandatorySubject/

As I just said, asking the user to edit the URL in their browser window to
be able to find the extension to download doesn’t make a lot of sense. The
links in the directory should be fixed.

On Dec 2, 2014, at 11:34 PM, Alex Peters alex@peters.net wrote:

Could you please clarify what you’re asking here? How to install the
plugins?

The plugins can be installed like any other CPAN module. Given a link to
a specific .pm file:

http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

you can hit the Download link on the right side of the page to receive a
.tar.gz file of the distribution, which can either be fed directly into the
cpan or cpanm utilities, or unpacked and installed manually using
Makefile.PL and make.

With RT extensions, you may find it useful to set environment variable
RTHOME to the root directory of your RT installation before installing the
plugin:

$ RTHOME=/opt/rt-4.2.7 cpanm RT-Extension-MandatorySubject-0.05.tar.gz

On 3 December 2014 at 16:19, Jo Rhett jrhett@netconsonance.com wrote:

Hey, dunno if this got overlooked during the short vacation week. This is
a pretty serious issue… asking users to manually hack up the URL in their
browser bar is not accessible.

On Nov 26, 2014, at 2:22 PM, Jo Rhett jrhett@netconsonance.com wrote:

Hey guys and gals, been a long time.

I’m doing an upgrade from 3.8.5 to 4.2. It seems to be going well. I’m
liking the changes. Other than some confusion about what order to do things
in (see my other message) the one thing I can’t seem to wrap my head around
is the new plugin setup.

First, yay! I like the idea of what you’ve done with plugins, keeping
them local and the simplified syntax in RT_SiteConfig.pm.

[in which I wander in the wrong direction… read and giggle]

However, I can’t find any plugins other than yours which are built in
these new packages you document at
https://www.bestpractical.com/docs/rt/4.2/writing_extensions.html

What is the fallback method for installing the other style modules? How
do I get from a .pm file to an installed module. Can I manually create the
directory structures and copy these into place? I see some details there
but it doesn’t inspire confidence that everything I need to know is there.
A breakout of the directory structure would be really helpful.

[forehead slap]

I was almost done with this e-mail when I realized the problem. If you
go to http://bestpractical.com/rt/extensions.html and you find the
extension you are looking for, the link to the Homepage for the extension
actually links to the main module, and not to the extension package.
Example for one

Homepage link takes you to:

http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

If you’re a bit tired and under-caffeniated, or just plain new to RT, it
may not be clear to you that you need to remove a bunch from the URL to
find the extension package. In my opinion, it would be much better to link
to the package instead of the module file, like so:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/

I did some random spot checking, and this appears to be true for every
module shown there.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and
internet projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and
internet projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and
internet projects.

So here’s my perspective. As someone with 25 years of sysadmin experience, who has both used RT for many years (but not in the last three years) and someone who uses CPAN fairly often, when sent to the pm module directly, I did the operations directly in front of me and downloaded the .pm and tried to figure out how to install it.

There is nothing in the documentation as it stands today to inform a new or dead-brained returning user that they need to download a package, not the .pm file —which in CPAN is often the sum total of an extension. Yes, there is a link to the package file on the page — off on the right, out of the “actionable” area of the screen, if you spend any time with usability experts. Given that the link is not in the user working area, and there’s no reason given to the user to search for the link, I suspect many others will make the same mistake.

I outlined this confusion in detail in my original post, showing how I had misunderstood. I believe that any change which makes it clear to the user that they should download the entire package, not just the .pm file, would significantly improve the user experience.On Dec 3, 2014, at 2:09 AM, Alex Peters alex@peters.net wrote:

I think I might be missing something crucial in what you are saying/asking.

Linking to the main module within a distribution is a very common practice, because that module is likely to have the most relevant documentation for that distribution.

The distribution is clearly linked to on the page of every module belonging to a particular distribution.

“Asking the user to edit the URL in their browser window to be able to find the extension to download doesn’t make a lot of sense” is essentially a fallacy, because:
the download link for the extension is available on that very page; and
the home page for the extension itself (which in my opinion is generally far less informational anyway) is available as a link on that very page.
Can you please rephrase why you feel that the links in the directory should be changed? Your assertion that these links are “broken” in their current form is confusing to me.

On 3 December 2014 at 18:40, Jo Rhett jrhett@netconsonance.com wrote:
As I said below, in the Extensions directory the links are broken. For example,

Homepage link takes you to:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

If you’re a bit tired and under-caffeniated, or just plain new to RT, it may not be clear to you that you need to remove a bunch from the URL to find the extension package. In my opinion, it would be much better to link to the package instead of the module file, like so:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/

As I just said, asking the user to edit the URL in their browser window to be able to find the extension to download doesn’t make a lot of sense. The links in the directory should be fixed.

On Dec 2, 2014, at 11:34 PM, Alex Peters alex@peters.net wrote:

Could you please clarify what you’re asking here? How to install the plugins?

The plugins can be installed like any other CPAN module. Given a link to a specific .pm file:

http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

you can hit the Download link on the right side of the page to receive a .tar.gz file of the distribution, which can either be fed directly into the cpan or cpanm utilities, or unpacked and installed manually using Makefile.PL and make.

With RT extensions, you may find it useful to set environment variable RTHOME to the root directory of your RT installation before installing the plugin:

$ RTHOME=/opt/rt-4.2.7 cpanm RT-Extension-MandatorySubject-0.05.tar.gz

On 3 December 2014 at 16:19, Jo Rhett jrhett@netconsonance.com wrote:
Hey, dunno if this got overlooked during the short vacation week. This is a pretty serious issue… asking users to manually hack up the URL in their browser bar is not accessible.

On Nov 26, 2014, at 2:22 PM, Jo Rhett jrhett@netconsonance.com wrote:

Hey guys and gals, been a long time.

I’m doing an upgrade from 3.8.5 to 4.2. It seems to be going well. I’m liking the changes. Other than some confusion about what order to do things in (see my other message) the one thing I can’t seem to wrap my head around is the new plugin setup.

First, yay! I like the idea of what you’ve done with plugins, keeping them local and the simplified syntax in RT_SiteConfig.pm.

[in which I wander in the wrong direction… read and giggle]

However, I can’t find any plugins other than yours which are built in these new packages you document at https://www.bestpractical.com/docs/rt/4.2/writing_extensions.html

What is the fallback method for installing the other style modules? How do I get from a .pm file to an installed module. Can I manually create the directory structures and copy these into place? I see some details there but it doesn’t inspire confidence that everything I need to know is there. A breakout of the directory structure would be really helpful.

[forehead slap]

I was almost done with this e-mail when I realized the problem. If you go to http://bestpractical.com/rt/extensions.html and you find the extension you are looking for, the link to the Homepage for the extension actually links to the main module, and not to the extension package. Example for one

Homepage link takes you to:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

If you’re a bit tired and under-caffeniated, or just plain new to RT, it may not be clear to you that you need to remove a bunch from the URL to find the extension package. In my opinion, it would be much better to link to the package instead of the module file, like so:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/

I did some random spot checking, and this appears to be true for every module shown there.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.

Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.

Why do you want to download the extension?
You can install them by cpan with
cpan RT::Extension::MandatorySubject

Which is said where and how?

The point is to improve the documentation such that available paths for installation are clear. Your suggestion for yet another undocumented path is just further argument that the extensions documentation should be improved.

Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.

Which is said where and how?

The point is to improve the documentation such that available paths for installation are clear. Your suggestion for yet another undocumented path is just further argument that the extensions documentation should be improved.

I think you missed that RT extension are Perl modules.
If they are available on CPAN, you can install them the CPAN way which
is documented here:
http://www.cpan.org/modules/INSTALL.html

Chris

I feel that there are actually several issues to discuss in this thread:

  1. Perl modules vs. Perl module distributions
  2. Perl module distribution sources
  3. Perl module distribution installation
  4. knowledge assumed by the CPAN site
  5. knowledge assumed by RT’s documentation
  6. what documentation should actually change

Based on your description of the steps you performed in an attempt to
install a Perl module from CPAN, with all due respect, I believe you’ve
been improperly advised on Perl module installation and possibly haven’t
been made aware of some crucial things about how Perl’s modules work. I’ll
go over some of those things, then with everything in mind, maybe we can
agree on what documentation changes are needed where.

Perl modules vs. Perl module distributions

A Perl module is (for all intents and purposes of this thread) a single
.pm file. A Perl module distribution consists of a number of Perl
modules (which can be just one), a Makefile (or more commonly, a Makefile
generator in Makefile.PL), and instructions for installation of the
distribution and hence its modules (usually in README or INSTALL).
Distributions exist because often, a single module isn’t enough to provide
some meaningful form of functionality.

Modules are never installed directly. Modules are always made available as
a side effect installing module distributions. The distribution (not the
module) is the smallest unit involved in the action of installation.
Installation of a distribution might result in the installation of only one
module, but nonetheless, it’s the distribution that’s acted upon directly
for installation rather than the module.

In summary, direct installation of single modules doesn’t happen.

Perl module distribution sources

Distributions are typically (but not always) available on the CPAN site
(typically capitalised as “CPAN”), and can be downloaded as an archive.
Other distribution sources include (but are not limited to) GitHub,
Bitbucket, CD-ROMs, FTP sites and personal web pages.

In summary, distribution files can come from many different places.

Perl module distribution installation

Every distribution includes installation instructions in README or INSTALL,
and the most typical experience for installing a Perl module distribution
(after obtaining an archive of it) goes like this:

$ tar xzf My-Perl-Module-0.01.tar.gz
$ cd My-Perl-Module-0.01
$ perl Makefile.PL
$ make
$ make test
$ make install

Distributions on CPAN can be installed without first downloading an
archive, using the CPAN installation tool (typically capitalised as
"cpan"). cpan is actually smart enough to take a module name (rather than
a distribution name) on the command line, determine the distribution to
which that module belongs, and install that distribution. Since one
distribution generally depends on others (“prerequisites”) being installed
in advance, cpan also manages the installation of prerequisite
distributions. This makes the use of a tool like cpan the generally
preferred means of installing distributions (and by extension, modules).

Other similar tools exist which do the job in a more streamlined fashion.
I personally prefer cpanm
https://metacpan.org/pod/distribution/App-cpanminus/bin/cpanm.

In summary, distribution installation tools function on distributions, not
modules—although some tools have the ability to infer the right
distribution if given a module name.

Knowledge assumed by the CPAN site

Given that a CPAN module page
http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm
only offers a single Download link, and that link points to an archive of
the module’s distribution, it’s safe to say that the CPAN site assumes that
its users already know the distinction between modules and distributions,
and expects that the user then refer to the documentation found within the
downloaded archive. I suppose the reasoning is that anyone who knows about
CPAN already knows about Perl modules, and how to install module
distributions.

I don’t feel that the installation of Perl modules/distributions is within
the domain of RT’s documentation. However, given RT’s use of Perl modules
as extensions, and that CPAN would probably be the main source for RT
extensions, I feel that perhaps RT’s documentation could benefit from at
least pointing RT users to the required prerequisite knowledge for using
CPAN (i.e. what modules are, what distributions are, and what to do with a
distribution archive).

The CPAN site explicitly doesn’t offer downloading of individual module
(.pm) files, because direct installation of single modules doesn’t happen.
(In my general experience I’ve found that if something is not making a
particular process easy for me, usually my process is invalid and I’m doing
something wrong.)

Knowledge assumed by RT’s documentation

RT’s documentation clearly assumes that the user knows that RT extensions
are just Perl modules. That’s obvious to anyone who is well-versed in
reading/writing Perl code. I don’t think it’s reasonable to assume that of
everyone administering RT. Therefore, I suppose RT’s documentation could
be enhanced to explicitly state this.

RT’s documentation doesn’t explicitly state how to install Perl module
distributions. My view on this is that RT’s documentation should document
RT. Installation of Perl module distributions is a Perl concern. At most,
RT’s documentation could link to some reputable Perl source on the matter
(as already mentioned above).

What documentation should actually change

Jo, taking the above information into account, how would you personally
adjust RT’s documentation such that others in future wouldn’t experience
what you experienced?

As far as I can see, the only real amendments that concern RT’s
documentation would be to explicitly state that RT extensions are just Perl
modules, and to link to further reading on how Perl modules work and how
Perl module distributions are sourced and installed. What are your
thoughts?On 9 December 2014 at 05:07, Jo Rhett jrhett@netconsonance.com wrote:

So here’s my perspective. As someone with 25 years of sysadmin experience,
who has both used RT for many years (but not in the last three years) and
someone who uses CPAN fairly often, when sent to the pm module directly, I
did the operations directly in front of me and downloaded the .pm and tried
to figure out how to install it.

There is nothing in the documentation as it stands today to inform a new
or dead-brained returning user that they need to download a package, not
the .pm file —which in CPAN is often the sum total of an extension. Yes,
there is a link to the package file on the page — off on the right, out of
the “actionable” area of the screen, if you spend any time with usability
experts. Given that the link is not in the user working area, and there’s
no reason given to the user to search for the link, I suspect many others
will make the same mistake.

I outlined this confusion in detail in my original post, showing how I had
misunderstood. I believe that any change which makes it clear to the user
that they should download the entire package, not just the .pm file, would
significantly improve the user experience.

On Dec 3, 2014, at 2:09 AM, Alex Peters alex@peters.net wrote:

I think I might be missing something crucial in what you are saying/asking.

Linking to the main module within a distribution is a very common
practice, because that module is likely to have the most relevant
documentation for that distribution.

The distribution is clearly linked to on the page of every module
belonging to a particular distribution.

“Asking the user to edit the URL in their browser window to be able to
find the extension to download doesn’t make a lot of sense” is essentially
a fallacy, because:

  1. the download link for the extension is available on that very page;
    and
  2. the home page for the extension itself (which in my opinion is
    generally far less informational anyway) is available as a link on that
    very page.

Can you please rephrase why you feel that the links in the directory
should be changed? Your assertion that these links are “broken” in their
current form is confusing to me.

On 3 December 2014 at 18:40, Jo Rhett jrhett@netconsonance.com wrote:

As I said below, in the Extensions directory the links are broken. For
example,

Homepage link takes you to:

http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

If you’re a bit tired and under-caffeniated, or just plain new to RT, it
may not be clear to you that you need to remove a bunch from the URL to
find the extension package. In my opinion, it would be much better to link
to the package instead of the module file, like so:

http://search.cpan.org/dist/RT-Extension-MandatorySubject/

As I just said, asking the user to edit the URL in their browser window
to be able to find the extension to download doesn’t make a lot of sense.
The links in the directory should be fixed.

On Dec 2, 2014, at 11:34 PM, Alex Peters alex@peters.net wrote:

Could you please clarify what you’re asking here? How to install the
plugins?

The plugins can be installed like any other CPAN module. Given a link to
a specific .pm file:

http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

you can hit the Download link on the right side of the page to receive a
.tar.gz file of the distribution, which can either be fed directly into the
cpan or cpanm utilities, or unpacked and installed manually using
Makefile.PL and make.

With RT extensions, you may find it useful to set environment variable
RTHOME to the root directory of your RT installation before installing the
plugin:

$ RTHOME=/opt/rt-4.2.7 cpanm RT-Extension-MandatorySubject-0.05.tar.gz

On 3 December 2014 at 16:19, Jo Rhett jrhett@netconsonance.com wrote:

Hey, dunno if this got overlooked during the short vacation week. This
is a pretty serious issue… asking users to manually hack up the URL in
their browser bar is not accessible.

On Nov 26, 2014, at 2:22 PM, Jo Rhett jrhett@netconsonance.com wrote:

Hey guys and gals, been a long time.

I’m doing an upgrade from 3.8.5 to 4.2. It seems to be going well. I’m
liking the changes. Other than some confusion about what order to do things
in (see my other message) the one thing I can’t seem to wrap my head around
is the new plugin setup.

First, yay! I like the idea of what you’ve done with plugins, keeping
them local and the simplified syntax in RT_SiteConfig.pm.

[in which I wander in the wrong direction… read and giggle]

However, I can’t find any plugins other than yours which are built in
these new packages you document at
https://www.bestpractical.com/docs/rt/4.2/writing_extensions.html

What is the fallback method for installing the other style modules? How
do I get from a .pm file to an installed module. Can I manually create the
directory structures and copy these into place? I see some details there
but it doesn’t inspire confidence that everything I need to know is there.
A breakout of the directory structure would be really helpful.

[forehead slap]

I was almost done with this e-mail when I realized the problem. If you
go to http://bestpractical.com/rt/extensions.html and you find the
extension you are looking for, the link to the Homepage for the extension
actually links to the main module, and not to the extension package.
Example for one

Homepage link takes you to:

http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

If you’re a bit tired and under-caffeniated, or just plain new to RT, it
may not be clear to you that you need to remove a bunch from the URL to
find the extension package. In my opinion, it would be much better to link
to the package instead of the module file, like so:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/

I did some random spot checking, and this appears to be true for every
module shown there.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and
internet projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and
internet projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and
internet projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and
internet projects.

I’ve been using Perl for 20 years now. I grok perl.

Good run with the insults and rudeness. Because yeah, that’s a great way to treat someone who’s pointing out a way to improve the usability of something. Treat them like dirt, and talk down to them like they’ve never used Perl before.

I’ll stop offering advice on ways to improve the UI. Unintelligible and prone to confusion on the part of people isn’t my problem. I’m not going to be helpful if I get treated like shit when I’m trying to make someone’s profit-making production better and more likely to be used.

I forgot why I dropped this list. Thanks for reminding me.On Dec 9, 2014, at 5:10 AM, Alex Peters alex@peters.net wrote:

I feel that there are actually several issues to discuss in this thread:
Perl modules vs. Perl module distributions
Perl module distribution sources
Perl module distribution installation
knowledge assumed by the CPAN site
knowledge assumed by RT’s documentation
what documentation should actually change
Based on your description of the steps you performed in an attempt to install a Perl module from CPAN, with all due respect, I believe you’ve been improperly advised on Perl module installation and possibly haven’t been made aware of some crucial things about how Perl’s modules work. I’ll go over some of those things, then with everything in mind, maybe we can agree on what documentation changes are needed where.

Perl modules vs. Perl module distributions

A Perl module is (for all intents and purposes of this thread) a single .pm file. A Perl module distribution consists of a number of Perl modules (which can be just one), a Makefile (or more commonly, a Makefile generator in Makefile.PL), and instructions for installation of the distribution and hence its modules (usually in README or INSTALL). Distributions exist because often, a single module isn’t enough to provide some meaningful form of functionality.

Modules are never installed directly. Modules are always made available as a side effect installing module distributions. The distribution (not the module) is the smallest unit involved in the action of installation. Installation of a distribution might result in the installation of only one module, but nonetheless, it’s the distribution that’s acted upon directly for installation rather than the module.

In summary, direct installation of single modules doesn’t happen.

Perl module distribution sources

Distributions are typically (but not always) available on the CPAN site (typically capitalised as “CPAN”), and can be downloaded as an archive. Other distribution sources include (but are not limited to) GitHub, Bitbucket, CD-ROMs, FTP sites and personal web pages.

In summary, distribution files can come from many different places.

Perl module distribution installation

Every distribution includes installation instructions in README or INSTALL, and the most typical experience for installing a Perl module distribution (after obtaining an archive of it) goes like this:

$ tar xzf My-Perl-Module-0.01.tar.gz
$ cd My-Perl-Module-0.01
$ perl Makefile.PL
$ make
$ make test
$ make install

Distributions on CPAN can be installed without first downloading an archive, using the CPAN installation tool (typically capitalised as “cpan”). cpan is actually smart enough to take a module name (rather than a distribution name) on the command line, determine the distribution to which that module belongs, and install that distribution. Since one distribution generally depends on others (“prerequisites”) being installed in advance, cpan also manages the installation of prerequisite distributions. This makes the use of a tool like cpan the generally preferred means of installing distributions (and by extension, modules).

Other similar tools exist which do the job in a more streamlined fashion. I personally prefer cpanm.

In summary, distribution installation tools function on distributions, not modules—although some tools have the ability to infer the right distribution if given a module name.

Knowledge assumed by the CPAN site

Given that a CPAN module page only offers a single Download link, and that link points to an archive of the module’s distribution, it’s safe to say that the CPAN site assumes that its users already know the distinction between modules and distributions, and expects that the user then refer to the documentation found within the downloaded archive. I suppose the reasoning is that anyone who knows about CPAN already knows about Perl modules, and how to install module distributions.

I don’t feel that the installation of Perl modules/distributions is within the domain of RT’s documentation. However, given RT’s use of Perl modules as extensions, and that CPAN would probably be the main source for RT extensions, I feel that perhaps RT’s documentation could benefit from at least pointing RT users to the required prerequisite knowledge for using CPAN (i.e. what modules are, what distributions are, and what to do with a distribution archive).

The CPAN site explicitly doesn’t offer downloading of individual module (.pm) files, because direct installation of single modules doesn’t happen. (In my general experience I’ve found that if something is not making a particular process easy for me, usually my process is invalid and I’m doing something wrong.)

Knowledge assumed by RT’s documentation

RT’s documentation clearly assumes that the user knows that RT extensions are just Perl modules. That’s obvious to anyone who is well-versed in reading/writing Perl code. I don’t think it’s reasonable to assume that of everyone administering RT. Therefore, I suppose RT’s documentation could be enhanced to explicitly state this.

RT’s documentation doesn’t explicitly state how to install Perl module distributions. My view on this is that RT’s documentation should document RT. Installation of Perl module distributions is a Perl concern. At most, RT’s documentation could link to some reputable Perl source on the matter (as already mentioned above).

What documentation should actually change

Jo, taking the above information into account, how would you personally adjust RT’s documentation such that others in future wouldn’t experience what you experienced?

As far as I can see, the only real amendments that concern RT’s documentation would be to explicitly state that RT extensions are just Perl modules, and to link to further reading on how Perl modules work and how Perl module distributions are sourced and installed. What are your thoughts?

On 9 December 2014 at 05:07, Jo Rhett jrhett@netconsonance.com wrote:
So here’s my perspective. As someone with 25 years of sysadmin experience, who has both used RT for many years (but not in the last three years) and someone who uses CPAN fairly often, when sent to the pm module directly, I did the operations directly in front of me and downloaded the .pm and tried to figure out how to install it.

There is nothing in the documentation as it stands today to inform a new or dead-brained returning user that they need to download a package, not the .pm file —which in CPAN is often the sum total of an extension. Yes, there is a link to the package file on the page — off on the right, out of the “actionable” area of the screen, if you spend any time with usability experts. Given that the link is not in the user working area, and there’s no reason given to the user to search for the link, I suspect many others will make the same mistake.

I outlined this confusion in detail in my original post, showing how I had misunderstood. I believe that any change which makes it clear to the user that they should download the entire package, not just the .pm file, would significantly improve the user experience.

On Dec 3, 2014, at 2:09 AM, Alex Peters alex@peters.net wrote:

I think I might be missing something crucial in what you are saying/asking.

Linking to the main module within a distribution is a very common practice, because that module is likely to have the most relevant documentation for that distribution.

The distribution is clearly linked to on the page of every module belonging to a particular distribution.

“Asking the user to edit the URL in their browser window to be able to find the extension to download doesn’t make a lot of sense” is essentially a fallacy, because:
the download link for the extension is available on that very page; and
the home page for the extension itself (which in my opinion is generally far less informational anyway) is available as a link on that very page.
Can you please rephrase why you feel that the links in the directory should be changed? Your assertion that these links are “broken” in their current form is confusing to me.

On 3 December 2014 at 18:40, Jo Rhett jrhett@netconsonance.com wrote:
As I said below, in the Extensions directory the links are broken. For example,

Homepage link takes you to:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

If you’re a bit tired and under-caffeniated, or just plain new to RT, it may not be clear to you that you need to remove a bunch from the URL to find the extension package. In my opinion, it would be much better to link to the package instead of the module file, like so:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/

As I just said, asking the user to edit the URL in their browser window to be able to find the extension to download doesn’t make a lot of sense. The links in the directory should be fixed.

On Dec 2, 2014, at 11:34 PM, Alex Peters alex@peters.net wrote:

Could you please clarify what you’re asking here? How to install the plugins?

The plugins can be installed like any other CPAN module. Given a link to a specific .pm file:

http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

you can hit the Download link on the right side of the page to receive a .tar.gz file of the distribution, which can either be fed directly into the cpan or cpanm utilities, or unpacked and installed manually using Makefile.PL and make.

With RT extensions, you may find it useful to set environment variable RTHOME to the root directory of your RT installation before installing the plugin:

$ RTHOME=/opt/rt-4.2.7 cpanm RT-Extension-MandatorySubject-0.05.tar.gz

On 3 December 2014 at 16:19, Jo Rhett jrhett@netconsonance.com wrote:
Hey, dunno if this got overlooked during the short vacation week. This is a pretty serious issue… asking users to manually hack up the URL in their browser bar is not accessible.

On Nov 26, 2014, at 2:22 PM, Jo Rhett jrhett@netconsonance.com wrote:

Hey guys and gals, been a long time.

I’m doing an upgrade from 3.8.5 to 4.2. It seems to be going well. I’m liking the changes. Other than some confusion about what order to do things in (see my other message) the one thing I can’t seem to wrap my head around is the new plugin setup.

First, yay! I like the idea of what you’ve done with plugins, keeping them local and the simplified syntax in RT_SiteConfig.pm.

[in which I wander in the wrong direction… read and giggle]

However, I can’t find any plugins other than yours which are built in these new packages you document at https://www.bestpractical.com/docs/rt/4.2/writing_extensions.html

What is the fallback method for installing the other style modules? How do I get from a .pm file to an installed module. Can I manually create the directory structures and copy these into place? I see some details there but it doesn’t inspire confidence that everything I need to know is there. A breakout of the directory structure would be really helpful.

[forehead slap]

I was almost done with this e-mail when I realized the problem. If you go to http://bestpractical.com/rt/extensions.html and you find the extension you are looking for, the link to the Homepage for the extension actually links to the main module, and not to the extension package. Example for one

Homepage link takes you to:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

If you’re a bit tired and under-caffeniated, or just plain new to RT, it may not be clear to you that you need to remove a bunch from the URL to find the extension package. In my opinion, it would be much better to link to the package instead of the module file, like so:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/

I did some random spot checking, and this appears to be true for every module shown there.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.

Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.

Jo, I honestly think that Alex simply misunderstood you. That’s not
uncommon in these kind of lists. Better to not attribute to malice what
can be explained by miscommunication. Even in the very rare occasion that
it is malice, you are better off assuming the best of people.

  • Rick

No problem. Sorry to see you go.On Thu, 11 Dec 2014 12:49 pm Jo Rhett jrhett@netconsonance.com wrote:

I’ve been using Perl for 20 years now. I grok perl.

Good run with the insults and rudeness. Because yeah, that’s a great way
to treat someone who’s pointing out a way to improve the usability of
something. Treat them like dirt, and talk down to them like they’ve never
used Perl before.

I’ll stop offering advice on ways to improve the UI. Unintelligible and
prone to confusion on the part of people isn’t my problem. I’m not going to
be helpful if I get treated like shit when I’m trying to make someone’s
profit-making production better and more likely to be used.

I forgot why I dropped this list. Thanks for reminding me.

On Dec 9, 2014, at 5:10 AM, Alex Peters alex@peters.net wrote:

I feel that there are actually several issues to discuss in this thread:

  1. Perl modules vs. Perl module distributions
  2. Perl module distribution sources
  3. Perl module distribution installation
  4. knowledge assumed by the CPAN site
  5. knowledge assumed by RT’s documentation
  6. what documentation should actually change

Based on your description of the steps you performed in an attempt to
install a Perl module from CPAN, with all due respect, I believe you’ve
been improperly advised on Perl module installation and possibly haven’t
been made aware of some crucial things about how Perl’s modules work. I’ll
go over some of those things, then with everything in mind, maybe we can
agree on what documentation changes are needed where.

Perl modules vs. Perl module distributions

A Perl module is (for all intents and purposes of this thread) a single
.pm file. A Perl module distribution consists of a number of Perl
modules (which can be just one), a Makefile (or more commonly, a Makefile
generator in Makefile.PL), and instructions for installation of the
distribution and hence its modules (usually in README or INSTALL).
Distributions exist because often, a single module isn’t enough to provide
some meaningful form of functionality.

Modules are never installed directly. Modules are always made available
as a side effect installing module distributions. The distribution (not
the module) is the smallest unit involved in the action of installation.
Installation of a distribution might result in the installation of only one
module, but nonetheless, it’s the distribution that’s acted upon directly
for installation rather than the module.

In summary, direct installation of single modules doesn’t happen.

Perl module distribution sources

Distributions are typically (but not always) available on the CPAN site
(typically capitalised as “CPAN”), and can be downloaded as an archive.
Other distribution sources include (but are not limited to) GitHub,
Bitbucket, CD-ROMs, FTP sites and personal web pages.

In summary, distribution files can come from many different places.

Perl module distribution installation

Every distribution includes installation instructions in README or
INSTALL, and the most typical experience for installing a Perl module
distribution (after obtaining an archive of it) goes like this:

$ tar xzf My-Perl-Module-0.01.tar.gz
$ cd My-Perl-Module-0.01
$ perl Makefile.PL
$ make
$ make test
$ make install

Distributions on CPAN can be installed without first downloading an
archive, using the CPAN installation tool (typically capitalised as
"cpan"). cpan is actually smart enough to take a module name (rather than
a distribution name) on the command line, determine the distribution to
which that module belongs, and install that distribution. Since one
distribution generally depends on others (“prerequisites”) being installed
in advance, cpan also manages the installation of prerequisite
distributions. This makes the use of a tool like cpan the generally
preferred means of installing distributions (and by extension, modules).

Other similar tools exist which do the job in a more streamlined fashion.
I personally prefer cpanm
https://metacpan.org/pod/distribution/App-cpanminus/bin/cpanm.

In summary, distribution installation tools function on distributions, not
modules—although some tools have the ability to infer the right
distribution if given a module name.

Knowledge assumed by the CPAN site

Given that a CPAN module page
http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm
only offers a single Download link, and that link points to an archive of
the module’s distribution, it’s safe to say that the CPAN site assumes that
its users already know the distinction between modules and distributions,
and expects that the user then refer to the documentation found within the
downloaded archive. I suppose the reasoning is that anyone who knows about
CPAN already knows about Perl modules, and how to install module
distributions.

I don’t feel that the installation of Perl modules/distributions is within
the domain of RT’s documentation. However, given RT’s use of Perl modules
as extensions, and that CPAN would probably be the main source for RT
extensions, I feel that perhaps RT’s documentation could benefit from at
least pointing RT users to the required prerequisite knowledge for using
CPAN (i.e. what modules are, what distributions are, and what to do with a
distribution archive).

The CPAN site explicitly doesn’t offer downloading of individual module
(.pm) files, because direct installation of single modules doesn’t happen.
(In my general experience I’ve found that if something is not making a
particular process easy for me, usually my process is invalid and I’m doing
something wrong.)

Knowledge assumed by RT’s documentation

RT’s documentation clearly assumes that the user knows that RT extensions
are just Perl modules. That’s obvious to anyone who is well-versed in
reading/writing Perl code. I don’t think it’s reasonable to assume that of
everyone administering RT. Therefore, I suppose RT’s documentation could
be enhanced to explicitly state this.

RT’s documentation doesn’t explicitly state how to install Perl module
distributions. My view on this is that RT’s documentation should document
RT. Installation of Perl module distributions is a Perl concern. At most,
RT’s documentation could link to some reputable Perl source on the matter
(as already mentioned above).

What documentation should actually change

Jo, taking the above information into account, how would you personally
adjust RT’s documentation such that others in future wouldn’t experience
what you experienced?

As far as I can see, the only real amendments that concern RT’s
documentation would be to explicitly state that RT extensions are just Perl
modules, and to link to further reading on how Perl modules work and how
Perl module distributions are sourced and installed. What are your
thoughts?

On 9 December 2014 at 05:07, Jo Rhett jrhett@netconsonance.com wrote:

So here’s my perspective. As someone with 25 years of sysadmin
experience, who has both used RT for many years (but not in the last three
years) and someone who uses CPAN fairly often, when sent to the pm module
directly, I did the operations directly in front of me and downloaded the
.pm and tried to figure out how to install it.

There is nothing in the documentation as it stands today to inform a new
or dead-brained returning user that they need to download a package, not
the .pm file —which in CPAN is often the sum total of an extension. Yes,
there is a link to the package file on the page — off on the right, out of
the “actionable” area of the screen, if you spend any time with usability
experts. Given that the link is not in the user working area, and there’s
no reason given to the user to search for the link, I suspect many others
will make the same mistake.

I outlined this confusion in detail in my original post, showing how I
had misunderstood. I believe that any change which makes it clear to the
user that they should download the entire package, not just the .pm file,
would significantly improve the user experience.

On Dec 3, 2014, at 2:09 AM, Alex Peters alex@peters.net wrote:

I think I might be missing something crucial in what you are
saying/asking.

Linking to the main module within a distribution is a very common
practice, because that module is likely to have the most relevant
documentation for that distribution.

The distribution is clearly linked to on the page of every module
belonging to a particular distribution.

“Asking the user to edit the URL in their browser window to be able to
find the extension to download doesn’t make a lot of sense” is essentially
a fallacy, because:

  1. the download link for the extension is available on that very
    page; and
  2. the home page for the extension itself (which in my opinion is
    generally far less informational anyway) is available as a link on that
    very page.

Can you please rephrase why you feel that the links in the directory
should be changed? Your assertion that these links are “broken” in their
current form is confusing to me.

On 3 December 2014 at 18:40, Jo Rhett jrhett@netconsonance.com wrote:

As I said below, in the Extensions directory the links are broken. For
example,

Homepage link takes you to:

http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

If you’re a bit tired and under-caffeniated, or just plain new to RT,
it may not be clear to you that you need to remove a bunch from the URL to
find the extension package. In my opinion, it would be much better to link
to the package instead of the module file, like so:

http://search.cpan.org/dist/RT-Extension-MandatorySubject/

As I just said, asking the user to edit the URL in their browser window
to be able to find the extension to download doesn’t make a lot of sense.
The links in the directory should be fixed.

On Dec 2, 2014, at 11:34 PM, Alex Peters alex@peters.net wrote:

Could you please clarify what you’re asking here? How to install the
plugins?

The plugins can be installed like any other CPAN module. Given a link
to a specific .pm file:

http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

you can hit the Download link on the right side of the page to receive a
.tar.gz file of the distribution, which can either be fed directly into the
cpan or cpanm utilities, or unpacked and installed manually using
Makefile.PL and make.

With RT extensions, you may find it useful to set environment variable
RTHOME to the root directory of your RT installation before installing the
plugin:

$ RTHOME=/opt/rt-4.2.7 cpanm RT-Extension-MandatorySubject-0.05.tar.gz

On 3 December 2014 at 16:19, Jo Rhett jrhett@netconsonance.com wrote:

Hey, dunno if this got overlooked during the short vacation week. This
is a pretty serious issue… asking users to manually hack up the URL in
their browser bar is not accessible.

On Nov 26, 2014, at 2:22 PM, Jo Rhett jrhett@netconsonance.com wrote:

Hey guys and gals, been a long time.

I’m doing an upgrade from 3.8.5 to 4.2. It seems to be going well. I’m
liking the changes. Other than some confusion about what order to do things
in (see my other message) the one thing I can’t seem to wrap my head around
is the new plugin setup.

First, yay! I like the idea of what you’ve done with plugins, keeping
them local and the simplified syntax in RT_SiteConfig.pm.

[in which I wander in the wrong direction… read and giggle]

However, I can’t find any plugins other than yours which are built in
these new packages you document at
https://www.bestpractical.com/docs/rt/4.2/writing_extensions.html

What is the fallback method for installing the other style modules? How
do I get from a .pm file to an installed module. Can I manually create the
directory structures and copy these into place? I see some details there
but it doesn’t inspire confidence that everything I need to know is there.
A breakout of the directory structure would be really helpful.

[forehead slap]

I was almost done with this e-mail when I realized the problem. If you
go to http://bestpractical.com/rt/extensions.html and you find the
extension you are looking for, the link to the Homepage for the extension
actually links to the main module, and not to the extension package.
Example for one

Homepage link takes you to:

http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

If you’re a bit tired and under-caffeniated, or just plain new to RT,
it may not be clear to you that you need to remove a bunch from the URL to
find the extension package. In my opinion, it would be much better to link
to the package instead of the module file, like so:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/

I did some random spot checking, and this appears to be true for every
module shown there.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and
internet projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and
internet projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and
internet projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and
internet projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and
internet projects.

I don’t think there’s anything to misunderstand here any more.

The gist of what Jo conveyed is basically this (and it’s all verifiably
conveyed in earlier messages):

“I have 20 years of experience with Perl and use CPAN fairly often, yet
when I’m presented with a CPAN link to the main module of a distribution, a
common practice pretty much everywhere, I complain that the links are bad,
ignore the provided Download link because it’s on the right side of the
page, manually adjust URLs, manually fetch .pm files, complain about the
usability of this process (which no one else performs), understandably fail
to install the module, admit that I don’t know how to install Perl modules,
and somehow attribute this to a fault with RT’s documentation, all while
failing to visibly consider that hundreds of people before me have used
this RT Extensions page in its current form without a problem, and that
thousands of people use CPAN in its current form without a problem.”

Despite this, I invested quite a bit of time in clarifying the whole
modules-vs.-distributions deal, and that the installation of modules has
nothing to do with downloading individual .pm files. I intended no offence
or malice, even though I wanted to just come out and say, “this method of
yours for attempting to install a module is completely ill-informed.” I
feel that I was entirely cordial and tactful in my earlier responses; if
anyone else disagrees, I’d definitely appreciate some offline coaching as
to how I could have prevented coming across as rude or insulting in this
instance.

I won’t bother to exercise tact here: the crux of the matter is that Jo
didn’t/doesn’t know how to properly install a module distribution from CPAN
(a fact verified by him asking the questions “How do I get from a .pm file
to an installed module? Can I manually create the directory structures and
copy these into place?”), and when he was politely alerted to that, he
launched into a sarcastic, snide, ingracious attack on me, seemed to ignore
any advice from multiple people on how to properly install CPAN modules,
and ignored all my other questions geared towards actually improving RT’s
documentation for everyone’s benefit. He then topped all of that off by
complaining about being “treated like shit.”

While I accept that my responses were clearly not to Jo’s taste, I expect
that my explanation of modules vs. module distributions will at least help
others either now or in the future (even though I’m sure I didn’t write
anything not already available in Perl’s own documentation).

Anyway, to keep things on topic, my summarised view on this thread’s actual
subject matter is as follows:

  • RT’s documentation currently doesn’t mention that RT extensions are in
    fact Perl modules/distributions. It should.
  • RT’s documentation currently doesn’t state that the majority (but not
    all) of RT extensions can be found on CPAN. It probably should, with a
    link to CPAN search results within the appropriate namespace/s
    (RT::Extension, RTx, …?).
  • RT’s documentation currently doesn’t state where non-CPAN-sourced RT
    extensions can be found. It probably could, but that probably wouldn’t be
    very useful.
  • RT’s documentation currently doesn’t detail how to install modules
    from CPAN. It shouldn’t. Installation of CPAN module distributions is a
    Perl concern, not an RT concern. I would consider a link to Perl
    documentation describing the process to be the most documentation required
    at RT’s level on this.
  • RT’s documentation currently doesn’t detail how to install modules
    from non-CPAN sources. It shouldn’t. Installation of non-CPAN-sourced
    module distributions is a Perl concern, not an RT concern.

I don’t suppose anyone is interested in patching the docs to that effect,
or suggesting other edits related to this issue?On 11 December 2014 at 17:35, rick@hiranyaloka.com wrote:

Jo, I honestly think that Alex simply misunderstood you. That’s not
uncommon in these kind of lists. Better to not attribute to malice what
can be explained by miscommunication. Even in the very rare occasion that
it is malice, you are better off assuming the best of people.

  • Rick

I’ve been using Perl for 20 years now. I grok perl.

Good run with the insults and rudeness. Because yeah, that’s a great way
to treat someone who’s pointing out a way to improve the usability of
something. Treat them like dirt, and talk down to them like they’ve never
used Perl before.

I’ll stop offering advice on ways to improve the UI. Unintelligible and
prone to confusion on the part of people isn’t my problem. I’m not going
to be helpful if I get treated like shit when I’m trying to make
someone’s
profit-making production better and more likely to be used.

I forgot why I dropped this list. Thanks for reminding me.

On Dec 9, 2014, at 5:10 AM, Alex Peters alex@peters.net wrote:

I feel that there are actually several issues to discuss in this thread:
Perl modules vs. Perl module distributions
Perl module distribution sources
Perl module distribution installation
knowledge assumed by the CPAN site
knowledge assumed by RT’s documentation
what documentation should actually change
Based on your description of the steps you performed in an attempt to
install a Perl module from CPAN, with all due respect, I believe you’ve
been improperly advised on Perl module installation and possibly haven’t
been made aware of some crucial things about how Perl’s modules work.
I’ll go over some of those things, then with everything in mind, maybe
we can agree on what documentation changes are needed where.

Perl modules vs. Perl module distributions

A Perl module is (for all intents and purposes of this thread) a single
.pm file. A Perl module distribution consists of a number of Perl
modules (which can be just one), a Makefile (or more commonly, a
Makefile generator in Makefile.PL), and instructions for installation of
the distribution and hence its modules (usually in README or INSTALL).
Distributions exist because often, a single module isn’t enough to
provide some meaningful form of functionality.

Modules are never installed directly. Modules are always made available
as a side effect installing module distributions. The distribution (not
the module) is the smallest unit involved in the action of installation.
Installation of a distribution might result in the installation of only
one module, but nonetheless, it’s the distribution that’s acted upon
directly for installation rather than the module.

In summary, direct installation of single modules doesn’t happen.

Perl module distribution sources

Distributions are typically (but not always) available on the CPAN site
(typically capitalised as “CPAN”), and can be downloaded as an archive.
Other distribution sources include (but are not limited to) GitHub,
Bitbucket, CD-ROMs, FTP sites and personal web pages.

In summary, distribution files can come from many different places.

Perl module distribution installation

Every distribution includes installation instructions in README or
INSTALL, and the most typical experience for installing a Perl module
distribution (after obtaining an archive of it) goes like this:

$ tar xzf My-Perl-Module-0.01.tar.gz
$ cd My-Perl-Module-0.01
$ perl Makefile.PL
$ make
$ make test
$ make install

Distributions on CPAN can be installed without first downloading an
archive, using the CPAN installation tool (typically capitalised as
"cpan"). cpan is actually smart enough to take a module name (rather
than a distribution name) on the command line, determine the
distribution to which that module belongs, and install that
distribution. Since one distribution generally depends on others
(“prerequisites”) being installed in advance, cpan also manages the
installation of prerequisite distributions. This makes the use of a
tool like cpan the generally preferred means of installing distributions
(and by extension, modules).

Other similar tools exist which do the job in a more streamlined
fashion. I personally prefer cpanm.

In summary, distribution installation tools function on distributions,
not modules—although some tools have the ability to infer the right
distribution if given a module name.

Knowledge assumed by the CPAN site

Given that a CPAN module page only offers a single Download link, and
that link points to an archive of the module’s distribution, it’s safe
to say that the CPAN site assumes that its users already know the
distinction between modules and distributions, and expects that the user
then refer to the documentation found within the downloaded archive. I
suppose the reasoning is that anyone who knows about CPAN already knows
about Perl modules, and how to install module distributions.

I don’t feel that the installation of Perl modules/distributions is
within the domain of RT’s documentation. However, given RT’s use of
Perl modules as extensions, and that CPAN would probably be the main
source for RT extensions, I feel that perhaps RT’s documentation could
benefit from at least pointing RT users to the required prerequisite
knowledge for using CPAN (i.e. what modules are, what distributions are,
and what to do with a distribution archive).

The CPAN site explicitly doesn’t offer downloading of individual module
(.pm) files, because direct installation of single modules doesn’t
happen. (In my general experience I’ve found that if something is not
making a particular process easy for me, usually my process is invalid
and I’m doing something wrong.)

Knowledge assumed by RT’s documentation

RT’s documentation clearly assumes that the user knows that RT
extensions are just Perl modules. That’s obvious to anyone who is
well-versed in reading/writing Perl code. I don’t think it’s reasonable
to assume that of everyone administering RT. Therefore, I suppose RT’s
documentation could be enhanced to explicitly state this.

RT’s documentation doesn’t explicitly state how to install Perl module
distributions. My view on this is that RT’s documentation should
document RT. Installation of Perl module distributions is a Perl
concern. At most, RT’s documentation could link to some reputable Perl
source on the matter (as already mentioned above).

What documentation should actually change

Jo, taking the above information into account, how would you personally
adjust RT’s documentation such that others in future wouldn’t experience
what you experienced?

As far as I can see, the only real amendments that concern RT’s
documentation would be to explicitly state that RT extensions are just
Perl modules, and to link to further reading on how Perl modules work
and how Perl module distributions are sourced and installed. What are
your thoughts?

On 9 December 2014 at 05:07, Jo Rhett jrhett@netconsonance.com wrote:
So here’s my perspective. As someone with 25 years of sysadmin
experience, who has both used RT for many years (but not in the last
three years) and someone who uses CPAN fairly often, when sent to the pm
module directly, I did the operations directly in front of me and
downloaded the .pm and tried to figure out how to install it.

There is nothing in the documentation as it stands today to inform a new
or dead-brained returning user that they need to download a package, not
the .pm file —which in CPAN is often the sum total of an extension. Yes,
there is a link to the package file on the page — off on the right, out
of the “actionable” area of the screen, if you spend any time with
usability experts. Given that the link is not in the user working area,
and there’s no reason given to the user to search for the link, I
suspect many others will make the same mistake.

I outlined this confusion in detail in my original post, showing how I
had misunderstood. I believe that any change which makes it clear to the
user that they should download the entire package, not just the .pm
file, would significantly improve the user experience.

On Dec 3, 2014, at 2:09 AM, Alex Peters alex@peters.net wrote:

I think I might be missing something crucial in what you are
saying/asking.

Linking to the main module within a distribution is a very common
practice, because that module is likely to have the most relevant
documentation for that distribution.

The distribution is clearly linked to on the page of every module
belonging to a particular distribution.

“Asking the user to edit the URL in their browser window to be able to
find the extension to download doesn’t make a lot of sense” is
essentially a fallacy, because:
the download link for the extension is available on that very page; and
the home page for the extension itself (which in my opinion is
generally far less informational anyway) is available as a link on that
very page.
Can you please rephrase why you feel that the links in the directory
should be changed? Your assertion that these links are “broken” in
their current form is confusing to me.

On 3 December 2014 at 18:40, Jo Rhett jrhett@netconsonance.com wrote:
As I said below, in the Extensions directory the links are broken. For
example,

Homepage link takes you to:

http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

If you’re a bit tired and under-caffeniated, or just plain new to RT,
it may not be clear to you that you need to remove a bunch from the URL
to find the extension package. In my opinion, it would be much better
to link to the package instead of the module file, like so:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/

As I just said, asking the user to edit the URL in their browser window
to be able to find the extension to download doesn’t make a lot of
sense. The links in the directory should be fixed.

On Dec 2, 2014, at 11:34 PM, Alex Peters alex@peters.net wrote:

Could you please clarify what you’re asking here? How to install the
plugins?

The plugins can be installed like any other CPAN module. Given a link
to a specific .pm file:

http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

you can hit the Download link on the right side of the page to receive
a .tar.gz file of the distribution, which can either be fed directly
into the cpan or cpanm utilities, or unpacked and installed manually
using Makefile.PL and make.

With RT extensions, you may find it useful to set environment variable
RTHOME to the root directory of your RT installation before installing
the plugin:

$ RTHOME=/opt/rt-4.2.7 cpanm RT-Extension-MandatorySubject-0.05.tar.gz

On 3 December 2014 at 16:19, Jo Rhett jrhett@netconsonance.com wrote:
Hey, dunno if this got overlooked during the short vacation week. This
is a pretty serious issue… asking users to manually hack up the URL
in their browser bar is not accessible.

On Nov 26, 2014, at 2:22 PM, Jo Rhett jrhett@netconsonance.com wrote:

Hey guys and gals, been a long time.

I’m doing an upgrade from 3.8.5 to 4.2. It seems to be going well.
I’m liking the changes. Other than some confusion about what order to
do things in (see my other message) the one thing I can’t seem to
wrap my head around is the new plugin setup.

First, yay! I like the idea of what you’ve done with plugins, keeping
them local and the simplified syntax in RT_SiteConfig.pm.

[in which I wander in the wrong direction… read and giggle]

However, I can’t find any plugins other than yours which are built in
these new packages you document at
https://www.bestpractical.com/docs/rt/4.2/writing_extensions.html

What is the fallback method for installing the other style modules?
How do I get from a .pm file to an installed module. Can I manually
create the directory structures and copy these into place? I see some
details there but it doesn’t inspire confidence that everything I
need to know is there. A breakout of the directory structure would be
really helpful.

[forehead slap]

I was almost done with this e-mail when I realized the problem. If
you go to http://bestpractical.com/rt/extensions.html and you find
the extension you are looking for, the link to the Homepage for the
extension actually links to the main module, and not to the extension
package. Example for one

Homepage link takes you to:

http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

If you’re a bit tired and under-caffeniated, or just plain new to RT,
it may not be clear to you that you need to remove a bunch from the
URL to find the extension package. In my opinion, it would be much
better to link to the package instead of the module file, like so:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/

I did some random spot checking, and this appears to be true for
every module shown there.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet
projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet
projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet
projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet
projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet
projects.

The levels of abuse and rudeness here are phenomenal. Alex has got his A-hole meter turned up to full strength. And if this list is moderated at all, I’m asking for Alex to be moderated. I’m filing a formal complaint with Best Practical over this.

The funniest bit is that his instructions are simply wrong, which further goes to the point that the documentation needs fixing.On Dec 11, 2014, at 2:50 AM, Alex Peters alex@peters.net wrote:

I don’t think there’s anything to misunderstand here any more.

The gist of what Jo conveyed is basically this (and it’s all verifiably conveyed in earlier messages):

“I have 20 years of experience with Perl and use CPAN fairly often, yet when I’m presented with a CPAN link to the main module of a distribution, a common practice pretty much everywhere, I complain that the links are bad, ignore the provided Download link because it’s on the right side of the page, manually adjust URLs, manually fetch .pm files, complain about the usability of this process (which no one else performs), understandably fail to install the module, admit that I don’t know how to install Perl modules, and somehow attribute this to a fault with RT’s documentation, all while failing to visibly consider that hundreds of people before me have used this RT Extensions page in its current form without a problem, and that thousands of people use CPAN in its current form without a problem.”

Despite this, I invested quite a bit of time in clarifying the whole modules-vs.-distributions deal, and that the installation of modules has nothing to do with downloading individual .pm files. I intended no offence or malice, even though I wanted to just come out and say, “this method of yours for attempting to install a module is completely ill-informed.” I feel that I was entirely cordial and tactful in my earlier responses; if anyone else disagrees, I’d definitely appreciate some offline coaching as to how I could have prevented coming across as rude or insulting in this instance.

I won’t bother to exercise tact here: the crux of the matter is that Jo didn’t/doesn’t know how to properly install a module distribution from CPAN (a fact verified by him asking the questions “How do I get from a .pm file to an installed module? Can I manually create the directory structures and copy these into place?”), and when he was politely alerted to that, he launched into a sarcastic, snide, ingracious attack on me, seemed to ignore any advice from multiple people on how to properly install CPAN modules, and ignored all my other questions geared towards actually improving RT’s documentation for everyone’s benefit. He then topped all of that off by complaining about being “treated like shit.”

While I accept that my responses were clearly not to Jo’s taste, I expect that my explanation of modules vs. module distributions will at least help others either now or in the future (even though I’m sure I didn’t write anything not already available in Perl’s own documentation).

Anyway, to keep things on topic, my summarised view on this thread’s actual subject matter is as follows:
RT’s documentation currently doesn’t mention that RT extensions are in fact Perl modules/distributions. It should.
RT’s documentation currently doesn’t state that the majority (but not all) of RT extensions can be found on CPAN. It probably should, with a link to CPAN search results within the appropriate namespace/s (RT::Extension, RTx, …?).
RT’s documentation currently doesn’t state where non-CPAN-sourced RT extensions can be found. It probably could, but that probably wouldn’t be very useful.
RT’s documentation currently doesn’t detail how to install modules from CPAN. It shouldn’t. Installation of CPAN module distributions is a Perl concern, not an RT concern. I would consider a link to Perl documentation describing the process to be the most documentation required at RT’s level on this.
RT’s documentation currently doesn’t detail how to install modules from non-CPAN sources. It shouldn’t. Installation of non-CPAN-sourced module distributions is a Perl concern, not an RT concern.
I don’t suppose anyone is interested in patching the docs to that effect, or suggesting other edits related to this issue?

On 11 December 2014 at 17:35, rick@hiranyaloka.com wrote:
Jo, I honestly think that Alex simply misunderstood you. That’s not
uncommon in these kind of lists. Better to not attribute to malice what
can be explained by miscommunication. Even in the very rare occasion that
it is malice, you are better off assuming the best of people.

  • Rick

I’ve been using Perl for 20 years now. I grok perl.

Good run with the insults and rudeness. Because yeah, that’s a great way
to treat someone who’s pointing out a way to improve the usability of
something. Treat them like dirt, and talk down to them like they’ve never
used Perl before.

I’ll stop offering advice on ways to improve the UI. Unintelligible and
prone to confusion on the part of people isn’t my problem. I’m not going
to be helpful if I get treated like shit when I’m trying to make someone’s
profit-making production better and more likely to be used.

I forgot why I dropped this list. Thanks for reminding me.

On Dec 9, 2014, at 5:10 AM, Alex Peters alex@peters.net wrote:

I feel that there are actually several issues to discuss in this thread:
Perl modules vs. Perl module distributions
Perl module distribution sources
Perl module distribution installation
knowledge assumed by the CPAN site
knowledge assumed by RT’s documentation
what documentation should actually change
Based on your description of the steps you performed in an attempt to
install a Perl module from CPAN, with all due respect, I believe you’ve
been improperly advised on Perl module installation and possibly haven’t
been made aware of some crucial things about how Perl’s modules work.
I’ll go over some of those things, then with everything in mind, maybe
we can agree on what documentation changes are needed where.

Perl modules vs. Perl module distributions

A Perl module is (for all intents and purposes of this thread) a single
.pm file. A Perl module distribution consists of a number of Perl
modules (which can be just one), a Makefile (or more commonly, a
Makefile generator in Makefile.PL), and instructions for installation of
the distribution and hence its modules (usually in README or INSTALL).
Distributions exist because often, a single module isn’t enough to
provide some meaningful form of functionality.

Modules are never installed directly. Modules are always made available
as a side effect installing module distributions. The distribution (not
the module) is the smallest unit involved in the action of installation.
Installation of a distribution might result in the installation of only
one module, but nonetheless, it’s the distribution that’s acted upon
directly for installation rather than the module.

In summary, direct installation of single modules doesn’t happen.

Perl module distribution sources

Distributions are typically (but not always) available on the CPAN site
(typically capitalised as “CPAN”), and can be downloaded as an archive.
Other distribution sources include (but are not limited to) GitHub,
Bitbucket, CD-ROMs, FTP sites and personal web pages.

In summary, distribution files can come from many different places.

Perl module distribution installation

Every distribution includes installation instructions in README or
INSTALL, and the most typical experience for installing a Perl module
distribution (after obtaining an archive of it) goes like this:

$ tar xzf My-Perl-Module-0.01.tar.gz
$ cd My-Perl-Module-0.01
$ perl Makefile.PL
$ make
$ make test
$ make install

Distributions on CPAN can be installed without first downloading an
archive, using the CPAN installation tool (typically capitalised as
"cpan"). cpan is actually smart enough to take a module name (rather
than a distribution name) on the command line, determine the
distribution to which that module belongs, and install that
distribution. Since one distribution generally depends on others
(“prerequisites”) being installed in advance, cpan also manages the
installation of prerequisite distributions. This makes the use of a
tool like cpan the generally preferred means of installing distributions
(and by extension, modules).

Other similar tools exist which do the job in a more streamlined
fashion. I personally prefer cpanm.

In summary, distribution installation tools function on distributions,
not modules—although some tools have the ability to infer the right
distribution if given a module name.

Knowledge assumed by the CPAN site

Given that a CPAN module page only offers a single Download link, and
that link points to an archive of the module’s distribution, it’s safe
to say that the CPAN site assumes that its users already know the
distinction between modules and distributions, and expects that the user
then refer to the documentation found within the downloaded archive. I
suppose the reasoning is that anyone who knows about CPAN already knows
about Perl modules, and how to install module distributions.

I don’t feel that the installation of Perl modules/distributions is
within the domain of RT’s documentation. However, given RT’s use of
Perl modules as extensions, and that CPAN would probably be the main
source for RT extensions, I feel that perhaps RT’s documentation could
benefit from at least pointing RT users to the required prerequisite
knowledge for using CPAN (i.e. what modules are, what distributions are,
and what to do with a distribution archive).

The CPAN site explicitly doesn’t offer downloading of individual module
(.pm) files, because direct installation of single modules doesn’t
happen. (In my general experience I’ve found that if something is not
making a particular process easy for me, usually my process is invalid
and I’m doing something wrong.)

Knowledge assumed by RT’s documentation

RT’s documentation clearly assumes that the user knows that RT
extensions are just Perl modules. That’s obvious to anyone who is
well-versed in reading/writing Perl code. I don’t think it’s reasonable
to assume that of everyone administering RT. Therefore, I suppose RT’s
documentation could be enhanced to explicitly state this.

RT’s documentation doesn’t explicitly state how to install Perl module
distributions. My view on this is that RT’s documentation should
document RT. Installation of Perl module distributions is a Perl
concern. At most, RT’s documentation could link to some reputable Perl
source on the matter (as already mentioned above).

What documentation should actually change

Jo, taking the above information into account, how would you personally
adjust RT’s documentation such that others in future wouldn’t experience
what you experienced?

As far as I can see, the only real amendments that concern RT’s
documentation would be to explicitly state that RT extensions are just
Perl modules, and to link to further reading on how Perl modules work
and how Perl module distributions are sourced and installed. What are
your thoughts?

On 9 December 2014 at 05:07, Jo Rhett jrhett@netconsonance.com wrote:
So here’s my perspective. As someone with 25 years of sysadmin
experience, who has both used RT for many years (but not in the last
three years) and someone who uses CPAN fairly often, when sent to the pm
module directly, I did the operations directly in front of me and
downloaded the .pm and tried to figure out how to install it.

There is nothing in the documentation as it stands today to inform a new
or dead-brained returning user that they need to download a package, not
the .pm file —which in CPAN is often the sum total of an extension. Yes,
there is a link to the package file on the page — off on the right, out
of the “actionable” area of the screen, if you spend any time with
usability experts. Given that the link is not in the user working area,
and there’s no reason given to the user to search for the link, I
suspect many others will make the same mistake.

I outlined this confusion in detail in my original post, showing how I
had misunderstood. I believe that any change which makes it clear to the
user that they should download the entire package, not just the .pm
file, would significantly improve the user experience.

On Dec 3, 2014, at 2:09 AM, Alex Peters alex@peters.net wrote:

I think I might be missing something crucial in what you are
saying/asking.

Linking to the main module within a distribution is a very common
practice, because that module is likely to have the most relevant
documentation for that distribution.

The distribution is clearly linked to on the page of every module
belonging to a particular distribution.

“Asking the user to edit the URL in their browser window to be able to
find the extension to download doesn’t make a lot of sense” is
essentially a fallacy, because:
the download link for the extension is available on that very page; and
the home page for the extension itself (which in my opinion is
generally far less informational anyway) is available as a link on that
very page.
Can you please rephrase why you feel that the links in the directory
should be changed? Your assertion that these links are “broken” in
their current form is confusing to me.

On 3 December 2014 at 18:40, Jo Rhett jrhett@netconsonance.com wrote:
As I said below, in the Extensions directory the links are broken. For
example,

Homepage link takes you to:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

If you’re a bit tired and under-caffeniated, or just plain new to RT,
it may not be clear to you that you need to remove a bunch from the URL
to find the extension package. In my opinion, it would be much better
to link to the package instead of the module file, like so:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/

As I just said, asking the user to edit the URL in their browser window
to be able to find the extension to download doesn’t make a lot of
sense. The links in the directory should be fixed.

On Dec 2, 2014, at 11:34 PM, Alex Peters alex@peters.net wrote:

Could you please clarify what you’re asking here? How to install the
plugins?

The plugins can be installed like any other CPAN module. Given a link
to a specific .pm file:

http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

you can hit the Download link on the right side of the page to receive
a .tar.gz file of the distribution, which can either be fed directly
into the cpan or cpanm utilities, or unpacked and installed manually
using Makefile.PL and make.

With RT extensions, you may find it useful to set environment variable
RTHOME to the root directory of your RT installation before installing
the plugin:

$ RTHOME=/opt/rt-4.2.7 cpanm RT-Extension-MandatorySubject-0.05.tar.gz

On 3 December 2014 at 16:19, Jo Rhett jrhett@netconsonance.com wrote:
Hey, dunno if this got overlooked during the short vacation week. This
is a pretty serious issue… asking users to manually hack up the URL
in their browser bar is not accessible.

On Nov 26, 2014, at 2:22 PM, Jo Rhett jrhett@netconsonance.com wrote:

Hey guys and gals, been a long time.

I’m doing an upgrade from 3.8.5 to 4.2. It seems to be going well.
I’m liking the changes. Other than some confusion about what order to
do things in (see my other message) the one thing I can’t seem to
wrap my head around is the new plugin setup.

First, yay! I like the idea of what you’ve done with plugins, keeping
them local and the simplified syntax in RT_SiteConfig.pm.

[in which I wander in the wrong direction… read and giggle]

However, I can’t find any plugins other than yours which are built in
these new packages you document at
https://www.bestpractical.com/docs/rt/4.2/writing_extensions.html

What is the fallback method for installing the other style modules?
How do I get from a .pm file to an installed module. Can I manually
create the directory structures and copy these into place? I see some
details there but it doesn’t inspire confidence that everything I
need to know is there. A breakout of the directory structure would be
really helpful.

[forehead slap]

I was almost done with this e-mail when I realized the problem. If
you go to http://bestpractical.com/rt/extensions.html and you find
the extension you are looking for, the link to the Homepage for the
extension actually links to the main module, and not to the extension
package. Example for one

Homepage link takes you to:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

If you’re a bit tired and under-caffeniated, or just plain new to RT,
it may not be clear to you that you need to remove a bunch from the
URL to find the extension package. In my opinion, it would be much
better to link to the package instead of the module file, like so:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/

I did some random spot checking, and this appears to be true for
every module shown there.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet
projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet
projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet
projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet
projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet
projects.

Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.

Thought I’d chime in here. My background: I’ve been on this list for
several months; I work at a site that’s been using RT for several
years – I co-manage our installation; I joined the list because I
needed to figure out a few things, and then stayed on it because it
was low volume and generally helpful and informative; mainly I’m a
software developer, and I’ve been using Perl for over 20 years; I’ve
also been on many product support mailing lists, for both commercial
and open-source products.

That said, I don’t have any problem with what Alex said in this thread
(or any other), and I think the one being out of line here is Jo.
There may have been some inkling of legitimacy to Jo’s issue, but I
had never seen it mentioned on the list, and I’d never run into it
myself (I install lots of modules from CPAN, but not too many
RT-related ones). Alex took the patience to craft a long,
substantial, polite reply to Jo’s issue, and Jo responded with
unjustified indignation. C’mon, if he wasn’t trying to be helpful,
would he have wasted his time writing a 130-line long substantive
reply!

What’s ironic about this is that Alex is one of the most helpful
people on the list. Not sure if he works for Best Practical (although
I’m guessing he does), but he replies to many posts on the list.
Looking over the posts I’ve saved from the list, the posters that
occur most are Alex, Kevin Falcone, and Alex Vandiver (the latter two
post from bestpractical.com email addresses).

If Jo does file a complaint with Best Practical over this, I’d be
happy to file an amicus brief countering it.

Milt Epstein
Applications Developer
Graduate School of Library and Information Science (GSLIS)
University of Illinois at Urbana-Champaign (UIUC)
mepstein@illinois.eduOn Thu, 11 Dec 2014, Jo Rhett wrote:

The levels of abuse and rudeness here are phenomenal. Alex has got his A-hole meter turned up to full strength. And if this list is moderated at all, I’m asking for Alex to be moderated. I’m filing a formal complaint with Best Practical over this.

The funniest bit is that his instructions are simply wrong, which further goes to the point that the documentation needs fixing.

On Dec 11, 2014, at 2:50 AM, Alex Peters alex@peters.net wrote:

I don’t think there’s anything to misunderstand here any more.

The gist of what Jo conveyed is basically this (and it’s all verifiably conveyed in earlier messages):

“I have 20 years of experience with Perl and use CPAN fairly often, yet when I’m presented with a CPAN link to the main module of a distribution, a common practice pretty much everywhere, I complain that the links are bad, ignore the provided Download link because it’s on the right side of the page, manually adjust URLs, manually fetch .pm files, complain about the usability of this process (which no one else performs), understandably fail to install the module, admit that I don’t know how to install Perl modules, and somehow attribute this to a fault with RT’s documentation, all while failing to visibly consider that hundreds of people before me have used this RT Extensions page in its current form without a problem, and that thousands of people use CPAN in its current form without a problem.”

Despite this, I invested quite a bit of time in clarifying the whole modules-vs.-distributions deal, and that the installation of modules has nothing to do with downloading individual .pm files. I intended no offence or malice, even though I wanted to just come out and say, “this method of yours for attempting to install a module is completely ill-informed.” I feel that I was entirely cordial and tactful in my earlier responses; if anyone else disagrees, I’d definitely appreciate some offline coaching as to how I could have prevented coming across as rude or insulting in this instance.

I won’t bother to exercise tact here: the crux of the matter is that Jo didn’t/doesn’t know how to properly install a module distribution from CPAN (a fact verified by him asking the questions “How do I get from a .pm file to an installed module? Can I manually create the directory structures and copy these into place?”), and when he was politely alerted to that, he launched into a sarcastic, snide, ingracious attack on me, seemed to ignore any advice from multiple people on how to properly install CPAN modules, and ignored all my other questions geared towards actually improving RT’s documentation for everyone’s benefit. He then topped all of that off by complaining about being “treated like shit.”

While I accept that my responses were clearly not to Jo’s taste, I expect that my explanation of modules vs. module distributions will at least help others either now or in the future (even though I’m sure I didn’t write anything not already available in Perl’s own documentation).

Anyway, to keep things on topic, my summarised view on this thread’s actual subject matter is as follows:
RT’s documentation currently doesn’t mention that RT extensions are in fact Perl modules/distributions. It should.
RT’s documentation currently doesn’t state that the majority (but not all) of RT extensions can be found on CPAN. It probably should, with a link to CPAN search results within the appropriate namespace/s (RT::Extension, RTx, …?).
RT’s documentation currently doesn’t state where non-CPAN-sourced RT extensions can be found. It probably could, but that probably wouldn’t be very useful.
RT’s documentation currently doesn’t detail how to install modules from CPAN. It shouldn’t. Installation of CPAN module distributions is a Perl concern, not an RT concern. I would consider a link to Perl documentation describing the process to be the most documentation required at RT’s level on this.
RT’s documentation currently doesn’t detail how to install modules from non-CPAN sources. It shouldn’t. Installation of non-CPAN-sourced module distributions is a Perl concern, not an RT concern.
I don’t suppose anyone is interested in patching the docs to that effect, or suggesting other edits related to this issue?

On 11 December 2014 at 17:35, rick@hiranyaloka.com wrote:
Jo, I honestly think that Alex simply misunderstood you. That’s not
uncommon in these kind of lists. Better to not attribute to malice what
can be explained by miscommunication. Even in the very rare occasion that
it is malice, you are better off assuming the best of people.

  • Rick

I’ve been using Perl for 20 years now. I grok perl.

Good run with the insults and rudeness. Because yeah, that’s a great way
to treat someone who’s pointing out a way to improve the usability of
something. Treat them like dirt, and talk down to them like they’ve never
used Perl before.

I’ll stop offering advice on ways to improve the UI. Unintelligible and
prone to confusion on the part of people isn’t my problem. I’m not going
to be helpful if I get treated like shit when I’m trying to make someone’s
profit-making production better and more likely to be used.

I forgot why I dropped this list. Thanks for reminding me.

On Dec 9, 2014, at 5:10 AM, Alex Peters alex@peters.net wrote:

I feel that there are actually several issues to discuss in this thread:
Perl modules vs. Perl module distributions
Perl module distribution sources
Perl module distribution installation
knowledge assumed by the CPAN site
knowledge assumed by RT’s documentation
what documentation should actually change
Based on your description of the steps you performed in an attempt to
install a Perl module from CPAN, with all due respect, I believe you’ve
been improperly advised on Perl module installation and possibly haven’t
been made aware of some crucial things about how Perl’s modules work.
I’ll go over some of those things, then with everything in mind, maybe
we can agree on what documentation changes are needed where.

Perl modules vs. Perl module distributions

A Perl module is (for all intents and purposes of this thread) a single
.pm file. A Perl module distribution consists of a number of Perl
modules (which can be just one), a Makefile (or more commonly, a
Makefile generator in Makefile.PL), and instructions for installation of
the distribution and hence its modules (usually in README or INSTALL).
Distributions exist because often, a single module isn’t enough to
provide some meaningful form of functionality.

Modules are never installed directly. Modules are always made available
as a side effect installing module distributions. The distribution (not
the module) is the smallest unit involved in the action of installation.
Installation of a distribution might result in the installation of only
one module, but nonetheless, it’s the distribution that’s acted upon
directly for installation rather than the module.

In summary, direct installation of single modules doesn’t happen.

Perl module distribution sources

Distributions are typically (but not always) available on the CPAN site
(typically capitalised as “CPAN”), and can be downloaded as an archive.
Other distribution sources include (but are not limited to) GitHub,
Bitbucket, CD-ROMs, FTP sites and personal web pages.

In summary, distribution files can come from many different places.

Perl module distribution installation

Every distribution includes installation instructions in README or
INSTALL, and the most typical experience for installing a Perl module
distribution (after obtaining an archive of it) goes like this:

$ tar xzf My-Perl-Module-0.01.tar.gz
$ cd My-Perl-Module-0.01
$ perl Makefile.PL
$ make
$ make test
$ make install

Distributions on CPAN can be installed without first downloading an
archive, using the CPAN installation tool (typically capitalised as
"cpan"). cpan is actually smart enough to take a module name (rather
than a distribution name) on the command line, determine the
distribution to which that module belongs, and install that
distribution. Since one distribution generally depends on others
(“prerequisites”) being installed in advance, cpan also manages the
installation of prerequisite distributions. This makes the use of a
tool like cpan the generally preferred means of installing distributions
(and by extension, modules).

Other similar tools exist which do the job in a more streamlined
fashion. I personally prefer cpanm.

In summary, distribution installation tools function on distributions,
not modules—although some tools have the ability to infer the right
distribution if given a module name.

Knowledge assumed by the CPAN site

Given that a CPAN module page only offers a single Download link, and
that link points to an archive of the module’s distribution, it’s safe
to say that the CPAN site assumes that its users already know the
distinction between modules and distributions, and expects that the user
then refer to the documentation found within the downloaded archive. I
suppose the reasoning is that anyone who knows about CPAN already knows
about Perl modules, and how to install module distributions.

I don’t feel that the installation of Perl modules/distributions is
within the domain of RT’s documentation. However, given RT’s use of
Perl modules as extensions, and that CPAN would probably be the main
source for RT extensions, I feel that perhaps RT’s documentation could
benefit from at least pointing RT users to the required prerequisite
knowledge for using CPAN (i.e. what modules are, what distributions are,
and what to do with a distribution archive).

The CPAN site explicitly doesn’t offer downloading of individual module
(.pm) files, because direct installation of single modules doesn’t
happen. (In my general experience I’ve found that if something is not
making a particular process easy for me, usually my process is invalid
and I’m doing something wrong.)

Knowledge assumed by RT’s documentation

RT’s documentation clearly assumes that the user knows that RT
extensions are just Perl modules. That’s obvious to anyone who is
well-versed in reading/writing Perl code. I don’t think it’s reasonable
to assume that of everyone administering RT. Therefore, I suppose RT’s
documentation could be enhanced to explicitly state this.

RT’s documentation doesn’t explicitly state how to install Perl module
distributions. My view on this is that RT’s documentation should
document RT. Installation of Perl module distributions is a Perl
concern. At most, RT’s documentation could link to some reputable Perl
source on the matter (as already mentioned above).

What documentation should actually change

Jo, taking the above information into account, how would you personally
adjust RT’s documentation such that others in future wouldn’t experience
what you experienced?

As far as I can see, the only real amendments that concern RT’s
documentation would be to explicitly state that RT extensions are just
Perl modules, and to link to further reading on how Perl modules work
and how Perl module distributions are sourced and installed. What are
your thoughts?

On 9 December 2014 at 05:07, Jo Rhett jrhett@netconsonance.com wrote:
So here’s my perspective. As someone with 25 years of sysadmin
experience, who has both used RT for many years (but not in the last
three years) and someone who uses CPAN fairly often, when sent to the pm
module directly, I did the operations directly in front of me and
downloaded the .pm and tried to figure out how to install it.

There is nothing in the documentation as it stands today to inform a new
or dead-brained returning user that they need to download a package, not
the .pm file —which in CPAN is often the sum total of an extension. Yes,
there is a link to the package file on the page — off on the right, out
of the “actionable” area of the screen, if you spend any time with
usability experts. Given that the link is not in the user working area,
and there’s no reason given to the user to search for the link, I
suspect many others will make the same mistake.

I outlined this confusion in detail in my original post, showing how I
had misunderstood. I believe that any change which makes it clear to the
user that they should download the entire package, not just the .pm
file, would significantly improve the user experience.

On Dec 3, 2014, at 2:09 AM, Alex Peters alex@peters.net wrote:

I think I might be missing something crucial in what you are
saying/asking.

Linking to the main module within a distribution is a very common
practice, because that module is likely to have the most relevant
documentation for that distribution.

The distribution is clearly linked to on the page of every module
belonging to a particular distribution.

“Asking the user to edit the URL in their browser window to be able to
find the extension to download doesn’t make a lot of sense” is
essentially a fallacy, because:
the download link for the extension is available on that very page; and
the home page for the extension itself (which in my opinion is
generally far less informational anyway) is available as a link on that
very page.
Can you please rephrase why you feel that the links in the directory
should be changed? Your assertion that these links are “broken” in
their current form is confusing to me.

On 3 December 2014 at 18:40, Jo Rhett jrhett@netconsonance.com wrote:
As I said below, in the Extensions directory the links are broken. For
example,

Homepage link takes you to:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

If you’re a bit tired and under-caffeniated, or just plain new to RT,
it may not be clear to you that you need to remove a bunch from the URL
to find the extension package. In my opinion, it would be much better
to link to the package instead of the module file, like so:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/

As I just said, asking the user to edit the URL in their browser window
to be able to find the extension to download doesn’t make a lot of
sense. The links in the directory should be fixed.

On Dec 2, 2014, at 11:34 PM, Alex Peters alex@peters.net wrote:

Could you please clarify what you’re asking here? How to install the
plugins?

The plugins can be installed like any other CPAN module. Given a link
to a specific .pm file:

http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

you can hit the Download link on the right side of the page to receive
a .tar.gz file of the distribution, which can either be fed directly
into the cpan or cpanm utilities, or unpacked and installed manually
using Makefile.PL and make.

With RT extensions, you may find it useful to set environment variable
RTHOME to the root directory of your RT installation before installing
the plugin:

$ RTHOME=/opt/rt-4.2.7 cpanm RT-Extension-MandatorySubject-0.05.tar.gz

On 3 December 2014 at 16:19, Jo Rhett jrhett@netconsonance.com wrote:
Hey, dunno if this got overlooked during the short vacation week. This
is a pretty serious issue
asking users to manually hack up the URL

in their browser bar is not accessible.

On Nov 26, 2014, at 2:22 PM, Jo Rhett jrhett@netconsonance.com wrote:

Hey guys and gals, been a long time.

I’m doing an upgrade from 3.8.5 to 4.2. It seems to be going well.
I’m liking the changes. Other than some confusion about what order to
do things in (see my other message) the one thing I can’t seem to
wrap my head around is the new plugin setup.

First, yay! I like the idea of what you’ve done with plugins, keeping
them local and the simplified syntax in RT_SiteConfig.pm.

[in which I wander in the wrong direction
read and giggle]

However, I can’t find any plugins other than yours which are built in
these new packages you document at
https://www.bestpractical.com/docs/rt/4.2/writing_extensions.html

What is the fallback method for installing the other style modules?
How do I get from a .pm file to an installed module. Can I manually
create the directory structures and copy these into place? I see some
details there but it doesn’t inspire confidence that everything I
need to know is there. A breakout of the directory structure would be
really helpful.

[forehead slap]

I was almost done with this e-mail when I realized the problem. If
you go to http://bestpractical.com/rt/extensions.html and you find
the extension you are looking for, the link to the Homepage for the
extension actually links to the main module, and not to the extension
package. Example for one

Homepage link takes you to:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm

If you’re a bit tired and under-caffeniated, or just plain new to RT,
it may not be clear to you that you need to remove a bunch from the
URL to find the extension package. In my opinion, it would be much
better to link to the package instead of the module file, like so:
http://search.cpan.org/dist/RT-Extension-MandatorySubject/

I did some random spot checking, and this appears to be true for
every module shown there.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet
projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet
projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet
projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet
projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet
projects.


Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.

Thought I’d chime in here. […]

And I’m going to step in before this gets any further out of hand. The
amount of high dudgeon in this thread is not acceptable. If it
continues, I will turn on list moderation. Don’t make me turn this
car around, etc, etc.

One concept to bear in mind is that replies to the mailing list are not
merely addressed to the author of the previous post, but for the
entirety of the mailing list, as well as any who come across it in
searches later. If one finds a post overbearingly patronizing, remember
that others who are less well-educated may yet find it useful.

Milt: To clarify, Alex Peters, like the vast majority of the folks on
this list, is a volunteer. Only those who post from @bestpractical.com
addresses are Best Practical employees.

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.

I’d be open to switching existing links from
http://bestpractical.com/rt/extensions.html to point to the metacpan
pages, rather than the search.cpan.org ones – I, personally, have come
to much prefer metacpan’s UI. I’m unclear if that would address Jo’s
original confusion, however.

We do not currently have a documentation page explaining how to download
and install extensions. We quite probably should; patches accepted,
bearing in mind that the exact installation steps vary from extension to
extension.

We generally do no recommend using the cpan or cpanm command-line
client to install RT extensions. Not only does this not suffice for RT
installs that do not live in /opt/rt4, but – more importantly – it
skips any database initialization steps that may be documented. Our
suggested installation path is always to download the .tar.gz from CPAN,
unpack it, and follow its README.

  • Alex

I support the idea of switching to MetaCPAN, which seems to be in active
development and seems to generally get a lot more right in terms of modern
website development. Plus, Download links are on the left there instead of
the right. We’ve established that this is important. :wink:

Since RT extensions can come from many sources, I’d suggest that any RT
documentation on how to download them shouldn’t be too specific because
then it might need to be updated when someone finds a new way to host
them. Maybe “most of them are on CPAN/MetaCPAN and here’s a link to a
search that lists most of them” is enough?

Since extension installation procedures are specific to each extension, I
think installation documentation on RT’s side would need to be nothing more
than the sentence “consult the downloaded extension’s documentation for
installation instructions, especially whether any database changes need to
be made.” I must admit that I’d forgotten about potential database changes
when I wrote everything above.

And I’m going to step in before this gets any further out of hand. The
amount of high dudgeon in this thread is not acceptable. If it
continues, I will turn on list moderation. Don’t make me turn this
car around, etc, etc.

I would appreciate it. I don’t come here to be personally insulted and attacked. What happened today is completely unacceptable in any business forum.

One concept to bear in mind is that replies to the mailing list are not
merely addressed to the author of the previous post, but for the
entirety of the mailing list, as well as any who come across it in
searches later. If one finds a post overbearingly patronizing, remember
that others who are less well-educated may yet find it useful.

Did you read that multi-paragraph personal assault he posted? Do read that and find a single sentence in the first page of his reply that isn’t a personal attack. Please do find and share with me a single statement in those first three paragraphs that is educational or helpful to new members. (other than perhaps to warn them that they’re going to be abused if they ask questions here?)

I had a very real point to make based on reality, with Alex Peters took and deliberately misrepresented so that he could check off every single box on the “how to be a complete and total jerk to a sincere request” bingo card. That is what happened here.

This is completely unacceptable in any forum. I am explicitly requesting that you enable moderation of this forum and prevent further attacks like this.

Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.

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.

The concern here is that the installation process is not clear, and is nowhere made clear, that the extension is more than the single file. Many, many projects have extensions which are single files. Modern sysadmins install JS modules, Java plugins, browser plugins, Python modules, Ruby modules, Puppet modules, Chef cookbooks, Perl modules, etc. Even some of these configuration management packages are single files. The ones which aren’t contain clear instructions on how to install them.

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.

In the current situation a person must be both an RT person and a Perl hacker to find their way through installing an extension. That’s a high bar that I don’t think helps your business. As I pointed out, I have more than 20 years of Perl experience and 10 years experience with RT and because I do things other than work on RT, and I was in the middle of a major number upgrade where everything could have changed, I made no assumption that extensions weren’t a single file. I’m a sysadmin who spent the last 16 months dealing with other software for which the extensions were a single file, and NOTHING IN YOUR DOCS TOLD ME OTHERWISE.

Every system for which a plugin is multiple files focuses on, and makes obvious, how to install the plugin. To pick a random example, when I find an extension on the Puppet forge, the largest piece of text on that very first page is "Use this command to install the latest compatible version:” which is a specific command to install that module. Beneath it in smaller text is another link "Learn about installing and upgrading modules” which covers the general case. (see links at bottom of message)

Obviously, if a confused person comes here Alex Peters’ will abuse them and talk down to them about how they’re stupid for not using CPAN to download an install the module, even though there’s no documentation for doing that either. You would at least need to pass -I /opt/rt4/lib to your CPAN invocation for this to work. So they’ll get insulted, and it still won’t work. Do you really think they’ll post again? Or will they hire someone like me to replace RT instead?

So far we have:

  1. Innocent person won’t know what to do
  2. Experienced perl hacker will probably do the wrong thing on instinct

Best Practical is a professional company who makes money selling services to people using RT. In my experience as a consultant, I keep getting called out to sites to replace RT with “something that works”. I usually find fairly trivial problems in the installation which solve the customer’s problems, but which could not be resolved from the documentation. Experienced sysadmins follow the available instructions, things blow up — and they blame BP. Which frankly has some validity. It gives the sysadmin the impression that you can’t be bothered, and this attitude is projected onto your company and its support programs.

I’d be open to switching existing links from
http://bestpractical.com/rt/extensions.html to point to the metacpan
pages, rather than the search.cpan.org ones – I, personally, have come
to much prefer metacpan’s UI. I’m unclear if that would address Jo’s
original confusion, however.

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]

Something like what Puppet’s Forge, Ruby’s Supermarket, or any of these more successful extension lists do would be much much better.
https://forge.puppetlabs.com/puppetlabs/stdlib
http://cookbooks.opscode.com/cookbooks/mcollective
…etc

I think the poor documentation causes BP to lose a lot of potential business, and you should consider this a priority.

Or you can continue to allow personal attacks in this support forum, and I’ll start ripping RT out everywhere instead of fixing their installations and promoting your services to them. I do a lot of RT promotion for free, at zero gain to myself. I’m not going to do that in the face of personal attacks.

Jo Rhett
+1 (415) 999-1798
Skype: jorhett
Net Consonance : net philanthropy to improve open source and internet projects.