Re: [rt-users] plugins link to module file, not package file
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 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.
Re: [rt-users] plugins link to module file, not package file
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 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 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. > >
Re: [rt-users] plugins link to module file, not package file
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 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 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 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.
Re: [rt-users] plugins link to module file, not package file
Am 03.12.2014 um 10:40 schrieb Jo Rhett: > 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
Re: [rt-users] plugins link to module file, not package file
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 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 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 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 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 pr
Re: [rt-users] plugins link to module file, not package file
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 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 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 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 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 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
Re: [rt-users] plugins link to module file, not package file
On Dec 3, 2014, at 1:55 AM, Christian Loos wrote: > 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.
Re: [rt-users] plugins link to module file, not package file
Am 08.12.2014 um 19:09 schrieb Jo Rhett: > 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
Re: [rt-users] plugins link to module file, not package file
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
.
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 mo
Re: [rt-users] plugins link to module file, not package file
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 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
Re: [rt-users] plugins link to module file, not package file
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
> Ive been using Perl for 20 years now. I grok perl.
>
> Good run with the insults and rudeness. Because yeah, thats a great way
> to treat someone whos pointing out a way to improve the usability of
> something. Treat them like dirt, and talk down to them like theyve never
> used Perl before.
>
> Ill stop offering advice on ways to improve the UI. Unintelligible and
> prone to confusion on the part of people isnt my problem. Im not going
> to be helpful if I get treated like shit when Im trying to make someones
> 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 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 modulesalthough 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 an
Re: [rt-users] plugins link to module file, not package file
No problem. Sorry to see you go.
On Thu, 11 Dec 2014 12:49 pm Jo Rhett 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 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
> .
>
> 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
Re: [rt-users] plugins link to module file, not package file
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, 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 wrote: > >> I feel that there are actually several issues to di
Re: [rt-users] plugins link to module file, not package file
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 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, 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
Re: [rt-users] plugins link to module file, not package file
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) mepst...@illinois.edu On 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 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 o
Re: [rt-users] plugins link to module file, not package file
On 12/11/2014 01:14 PM, Milt Epstein wrote: > 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
Re: [rt-users] plugins link to module file, not package file
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. ;) 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.
