[rt-users] plugins link to module file, not package file

[Alex Peters]

No problem.  Sorry to see you go.

On Thu, 11 Dec 2014 12:49 pm Jo Rhett <jrhett at 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 at 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 at 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 at 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 at 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 at 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 at 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 at 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.
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.bestpractical.com/pipermail/rt-users/attachments/20141211/84d7a72e/attachment.htm>