<html><head><meta http-equiv="Content-Type" content="text/html charset=windows-1252"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;">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.<div><br></div><div>The funniest bit is that his instructions are simply wrong, which further goes to the point that the documentation needs fixing.<div><br><div><div>On Dec 11, 2014, at 2:50 AM, Alex Peters <<a href="mailto:alex@peters.net">alex@peters.net</a>> wrote:</div><blockquote type="cite"><div dir="ltr">I don't think there's anything to misunderstand here any more.<div><br></div><div>The gist of what Jo conveyed is basically this (and it's all verifiably conveyed in earlier messages):</div><div><br></div><div>"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."</div><div><div><br></div><div>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.</div><div><br></div><div>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."</div><div><br></div><div>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).</div><div><br></div><div>Anyway, to keep things on topic, my summarised view on this thread's actual subject matter is as follows:</div><div><ul><li>RT's documentation currently doesn't mention that RT extensions are in fact Perl modules/distributions. It should.<br></li><li>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, ...?).</li><li>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.</li><li>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.</li><li>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.</li></ul><div>I don't suppose anyone is interested in patching the docs to that effect, or suggesting other edits related to this issue?</div></div><div><br></div></div></div><div class="gmail_extra"><br><div class="gmail_quote">On 11 December 2014 at 17:35, <span dir="ltr"><<a href="mailto:rick@hiranyaloka.com" target="_blank">rick@hiranyaloka.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Jo, I honestly think that Alex simply misunderstood you. That's not<br>
uncommon in these kind of lists. Better to not attribute to malice what<br>
can be explained by miscommunication. Even in the very rare occasion that<br>
it _is_ malice, you are better off assuming the best of people.<br>
<br>
- Rick<br>
<div class="HOEnZb"><div class="h5"><br>
> I’ve been using Perl for 20 years now. I grok perl.<br>
><br>
> Good run with the insults and rudeness. Because yeah, that’s a great way<br>
> to treat someone who’s pointing out a way to improve the usability of<br>
> something. Treat them like dirt, and talk down to them like they’ve never<br>
> used Perl before.<br>
><br>
> I’ll stop offering advice on ways to improve the UI. Unintelligible and<br>
> prone to confusion on the part of people isn’t my problem. I’m not going<br>
> to be helpful if I get treated like shit when I’m trying to make someone’s<br>
> profit-making production better and more likely to be used.<br>
><br>
> I forgot why I dropped this list. Thanks for reminding me.<br>
><br>
> On Dec 9, 2014, at 5:10 AM, Alex Peters <<a href="mailto:alex@peters.net">alex@peters.net</a>> wrote:<br>
>> I feel that there are actually several issues to discuss in this thread:<br>
>> Perl modules vs. Perl module distributions<br>
>> Perl module distribution sources<br>
>> Perl module distribution installation<br>
>> knowledge assumed by the CPAN site<br>
>> knowledge assumed by RT's documentation<br>
>> what documentation should actually change<br>
>> Based on your description of the steps you performed in an attempt to<br>
>> install a Perl module from CPAN, with all due respect, I believe you've<br>
>> been improperly advised on Perl module installation and possibly haven't<br>
>> been made aware of some crucial things about how Perl's modules work.<br>
>> I'll go over some of those things, then with everything in mind, maybe<br>
>> we can agree on what documentation changes are needed where.<br>
>><br>
>><br>
>> Perl modules vs. Perl module distributions<br>
>><br>
>> A Perl module is (for all intents and purposes of this thread) a single<br>
>> .pm file. A Perl module distribution consists of a number of Perl<br>
>> modules (which can be just one), a Makefile (or more commonly, a<br>
>> Makefile generator in Makefile.PL), and instructions for installation of<br>
>> the distribution and hence its modules (usually in README or INSTALL).<br>
>> Distributions exist because often, a single module isn't enough to<br>
>> provide some meaningful form of functionality.<br>
>><br>
>> Modules are never installed directly. Modules are always made available<br>
>> as a side effect installing module distributions. The distribution (not<br>
>> the module) is the smallest unit involved in the action of installation.<br>
>> Installation of a distribution might result in the installation of only<br>
>> one module, but nonetheless, it's the distribution that's acted upon<br>
>> directly for installation rather than the module.<br>
>><br>
>> In summary, direct installation of single modules doesn't happen.<br>
>><br>
>><br>
>> Perl module distribution sources<br>
>><br>
>> Distributions are typically (but not always) available on the CPAN site<br>
>> (typically capitalised as "CPAN"), and can be downloaded as an archive.<br>
>> Other distribution sources include (but are not limited to) GitHub,<br>
>> Bitbucket, CD-ROMs, FTP sites and personal web pages.<br>
>><br>
>> In summary, distribution files can come from many different places.<br>
>><br>
>><br>
>> Perl module distribution installation<br>
>><br>
>> Every distribution includes installation instructions in README or<br>
>> INSTALL, and the most typical experience for installing a Perl module<br>
>> distribution (after obtaining an archive of it) goes like this:<br>
>><br>
>> $ tar xzf My-Perl-Module-0.01.tar.gz<br>
>> $ cd My-Perl-Module-0.01<br>
>> $ perl Makefile.PL<br>
>> $ make<br>
>> $ make test<br>
>> $ make install<br>
>><br>
>> Distributions on CPAN can be installed without first downloading an<br>
>> archive, using the CPAN installation tool (typically capitalised as<br>
>> "cpan"). cpan is actually smart enough to take a module name (rather<br>
>> than a distribution name) on the command line, determine the<br>
>> distribution to which that module belongs, and install that<br>
>> distribution. Since one distribution generally depends on others<br>
>> ("prerequisites") being installed in advance, cpan also manages the<br>
>> installation of prerequisite distributions. This makes the use of a<br>
>> tool like cpan the generally preferred means of installing distributions<br>
>> (and by extension, modules).<br>
>><br>
>> Other similar tools exist which do the job in a more streamlined<br>
>> fashion. I personally prefer cpanm.<br>
>><br>
>> In summary, distribution installation tools function on distributions,<br>
>> not modules—although some tools have the ability to infer the right<br>
>> distribution if given a module name.<br>
>><br>
>><br>
>> Knowledge assumed by the CPAN site<br>
>><br>
>> Given that a CPAN module page only offers a single Download link, and<br>
>> that link points to an archive of the module's distribution, it's safe<br>
>> to say that the CPAN site assumes that its users already know the<br>
>> distinction between modules and distributions, and expects that the user<br>
>> then refer to the documentation found within the downloaded archive. I<br>
>> suppose the reasoning is that anyone who knows about CPAN already knows<br>
>> about Perl modules, and how to install module distributions.<br>
>><br>
>> I don't feel that the installation of Perl modules/distributions is<br>
>> within the domain of RT's documentation. However, given RT's use of<br>
>> Perl modules as extensions, and that CPAN would probably be the main<br>
>> source for RT extensions, I feel that perhaps RT's documentation could<br>
>> benefit from at least pointing RT users to the required prerequisite<br>
>> knowledge for using CPAN (i.e. what modules are, what distributions are,<br>
>> and what to do with a distribution archive).<br>
>><br>
>> The CPAN site explicitly doesn't offer downloading of individual module<br>
>> (.pm) files, because direct installation of single modules doesn't<br>
>> happen. (In my general experience I've found that if something is not<br>
>> making a particular process easy for me, usually my process is invalid<br>
>> and I'm doing something wrong.)<br>
>><br>
>><br>
>> Knowledge assumed by RT's documentation<br>
>><br>
>> RT's documentation clearly assumes that the user knows that RT<br>
>> extensions are just Perl modules. That's obvious to anyone who is<br>
>> well-versed in reading/writing Perl code. I don't think it's reasonable<br>
>> to assume that of everyone administering RT. Therefore, I suppose RT's<br>
>> documentation could be enhanced to explicitly state this.<br>
>><br>
>> RT's documentation doesn't explicitly state how to install Perl module<br>
>> distributions. My view on this is that RT's documentation should<br>
>> document RT. Installation of Perl module distributions is a Perl<br>
>> concern. At most, RT's documentation could link to some reputable Perl<br>
>> source on the matter (as already mentioned above).<br>
>><br>
>><br>
>> What documentation should actually change<br>
>><br>
>> Jo, taking the above information into account, how would you personally<br>
>> adjust RT's documentation such that others in future wouldn't experience<br>
>> what you experienced?<br>
>><br>
>> As far as I can see, the only real amendments that concern RT's<br>
>> documentation would be to explicitly state that RT extensions are just<br>
>> Perl modules, and to link to further reading on how Perl modules work<br>
>> and how Perl module distributions are sourced and installed. What are<br>
>> your thoughts?<br>
>><br>
>><br>
>> On 9 December 2014 at 05:07, Jo Rhett <<a href="mailto:jrhett@netconsonance.com">jrhett@netconsonance.com</a>> wrote:<br>
>> So here’s my perspective. As someone with 25 years of sysadmin<br>
>> experience, who has both used RT for many years (but not in the last<br>
>> three years) and someone who uses CPAN fairly often, when sent to the pm<br>
>> module directly, I did the operations directly in front of me and<br>
>> downloaded the .pm and tried to figure out how to install it.<br>
>><br>
>> There is nothing in the documentation as it stands today to inform a new<br>
>> or dead-brained returning user that they need to download a package, not<br>
>> the .pm file —which in CPAN is often the sum total of an extension. Yes,<br>
>> there is a link to the package file on the page — off on the right, out<br>
>> of the “actionable” area of the screen, if you spend any time with<br>
>> usability experts. Given that the link is not in the user working area,<br>
>> and there’s no reason given to the user to search for the link, I<br>
>> suspect many others will make the same mistake.<br>
>><br>
>> I outlined this confusion in detail in my original post, showing how I<br>
>> had misunderstood. I believe that any change which makes it clear to the<br>
>> user that they should download the entire package, not just the .pm<br>
>> file, would significantly improve the user experience.<br>
>><br>
>> On Dec 3, 2014, at 2:09 AM, Alex Peters <<a href="mailto:alex@peters.net">alex@peters.net</a>> wrote:<br>
>>> I think I might be missing something crucial in what you are<br>
>>> saying/asking.<br>
>>><br>
>>> Linking to the main module within a distribution is a very common<br>
>>> practice, because that module is likely to have the most relevant<br>
>>> documentation for that distribution.<br>
>>><br>
>>> The distribution is clearly linked to on the page of every module<br>
>>> belonging to a particular distribution.<br>
>>><br>
>>> "Asking the user to edit the URL in their browser window to be able to<br>
>>> find the extension to download doesn’t make a lot of sense" is<br>
>>> essentially a fallacy, because:<br>
>>> the download link for the extension is available on that very page; and<br>
>>> the home page for the extension itself (which in my opinion is<br>
>>> generally far less informational anyway) is available as a link on that<br>
>>> very page.<br>
>>> Can you please rephrase why you feel that the links in the directory<br>
>>> should be changed? Your assertion that these links are "broken" in<br>
>>> their current form is confusing to me.<br>
>>><br>
>>> On 3 December 2014 at 18:40, Jo Rhett <<a href="mailto:jrhett@netconsonance.com">jrhett@netconsonance.com</a>> wrote:<br>
>>> As I said below, in the Extensions directory the links are broken. For<br>
>>> example,<br>
>>><br>
>>> Homepage link takes you to:<br>
>>> <a href="http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm" target="_blank">http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm</a><br>
>>><br>
>>> If you’re a bit tired and under-caffeniated, or just plain new to RT,<br>
>>> it may not be clear to you that you need to remove a bunch from the URL<br>
>>> to find the extension package. In my opinion, it would be much better<br>
>>> to link to the package instead of the module file, like so:<br>
>>> <a href="http://search.cpan.org/dist/RT-Extension-MandatorySubject/" target="_blank">http://search.cpan.org/dist/RT-Extension-MandatorySubject/</a><br>
>>><br>
>>> As I just said, asking the user to edit the URL in their browser window<br>
>>> to be able to find the extension to download doesn’t make a lot of<br>
>>> sense. The links in the directory should be fixed.<br>
>>><br>
>>> On Dec 2, 2014, at 11:34 PM, Alex Peters <<a href="mailto:alex@peters.net">alex@peters.net</a>> wrote:<br>
>>>> Could you please clarify what you're asking here? How to install the<br>
>>>> plugins?<br>
>>>><br>
>>>> The plugins can be installed like any other CPAN module. Given a link<br>
>>>> to a specific .pm file:<br>
>>>><br>
>>>> <a href="http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm" target="_blank">http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm</a><br>
>>>><br>
>>>> you can hit the Download link on the right side of the page to receive<br>
>>>> a .tar.gz file of the distribution, which can either be fed directly<br>
>>>> into the cpan or cpanm utilities, or unpacked and installed manually<br>
>>>> using Makefile.PL and make.<br>
>>>><br>
>>>> With RT extensions, you may find it useful to set environment variable<br>
>>>> RTHOME to the root directory of your RT installation before installing<br>
>>>> the plugin:<br>
>>>><br>
>>>> $ RTHOME=/opt/rt-4.2.7 cpanm RT-Extension-MandatorySubject-0.05.tar.gz<br>
>>>><br>
>>>> On 3 December 2014 at 16:19, Jo Rhett <<a href="mailto:jrhett@netconsonance.com">jrhett@netconsonance.com</a>><br>
>>>> wrote:<br>
>>>> Hey, dunno if this got overlooked during the short vacation week. This<br>
>>>> is a pretty serious issue… asking users to manually hack up the URL<br>
>>>> in their browser bar is not accessible.<br>
>>>><br>
>>>> On Nov 26, 2014, at 2:22 PM, Jo Rhett <<a href="mailto:jrhett@netconsonance.com">jrhett@netconsonance.com</a>><br>
>>>> wrote:<br>
>>>>> Hey guys and gals, been a long time.<br>
>>>>><br>
>>>>> I’m doing an upgrade from 3.8.5 to 4.2. It seems to be going well.<br>
>>>>> I’m liking the changes. Other than some confusion about what order to<br>
>>>>> do things in (see my other message) the one thing I can’t seem to<br>
>>>>> wrap my head around is the new plugin setup.<br>
>>>>><br>
>>>>> First, yay! I like the idea of what you’ve done with plugins, keeping<br>
>>>>> them local and the simplified syntax in RT_SiteConfig.pm.<br>
>>>>><br>
>>>>> [in which I wander in the wrong direction… read and giggle]<br>
>>>>><br>
>>>>> However, I can’t find any plugins other than yours which are built in<br>
>>>>> these new packages you document at<br>
>>>>> <a href="https://www.bestpractical.com/docs/rt/4.2/writing_extensions.html" target="_blank">https://www.bestpractical.com/docs/rt/4.2/writing_extensions.html</a><br>
>>>>><br>
>>>>> What is the fallback method for installing the other style modules?<br>
>>>>> How do I get from a .pm file to an installed module. Can I manually<br>
>>>>> create the directory structures and copy these into place? I see some<br>
>>>>> details there but it doesn’t inspire confidence that everything I<br>
>>>>> need to know is there. A breakout of the directory structure would be<br>
>>>>> really helpful.<br>
>>>>><br>
>>>>> [forehead slap]<br>
>>>>><br>
>>>>> I was almost done with this e-mail when I realized the problem. If<br>
>>>>> you go to <a href="http://bestpractical.com/rt/extensions.html" target="_blank">http://bestpractical.com/rt/extensions.html</a> and you find<br>
>>>>> the extension you are looking for, the link to the Homepage for the<br>
>>>>> extension actually links to the main module, and not to the extension<br>
>>>>> package. Example for one<br>
>>>>><br>
>>>>> Homepage link takes you to:<br>
>>>>> <a href="http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm" target="_blank">http://search.cpan.org/dist/RT-Extension-MandatorySubject/lib/RT/Extension/MandatorySubject.pm</a><br>
>>>>><br>
>>>>> If you’re a bit tired and under-caffeniated, or just plain new to RT,<br>
>>>>> it may not be clear to you that you need to remove a bunch from the<br>
>>>>> URL to find the extension package. In my opinion, it would be much<br>
>>>>> better to link to the package instead of the module file, like so:<br>
>>>>> <a href="http://search.cpan.org/dist/RT-Extension-MandatorySubject/" target="_blank">http://search.cpan.org/dist/RT-Extension-MandatorySubject/</a><br>
>>>>><br>
>>>>> I did some random spot checking, and this appears to be true for<br>
>>>>> every module shown there.<br>
>>>>><br>
>>>>> --<br>
>>>>> Jo Rhett<br>
>>>>> +1 (415) 999-1798<br>
>>>>> Skype: jorhett<br>
>>>>> Net Consonance : net philanthropy to improve open source and internet<br>
>>>>> projects.<br>
>>>>><br>
>>>><br>
>>>> --<br>
>>>> Jo Rhett<br>
>>>> +1 (415) 999-1798<br>
>>>> Skype: jorhett<br>
>>>> Net Consonance : net philanthropy to improve open source and internet<br>
>>>> projects.<br>
>>>><br>
>>>><br>
>>><br>
>>> --<br>
>>> Jo Rhett<br>
>>> +1 (415) 999-1798<br>
>>> Skype: jorhett<br>
>>> Net Consonance : net philanthropy to improve open source and internet<br>
>>> projects.<br>
>>><br>
>>><br>
>><br>
>> --<br>
>> Jo Rhett<br>
>> +1 (415) 999-1798<br>
>> Skype: jorhett<br>
>> Net Consonance : net philanthropy to improve open source and internet<br>
>> projects.<br>
>><br>
>><br>
><br>
> --<br>
> Jo Rhett<br>
> +1 (415) 999-1798<br>
> Skype: jorhett<br>
> Net Consonance : net philanthropy to improve open source and internet<br>
> projects.<br>
><br>
><br>
<br>
</div></div></blockquote></div><br></div>
</blockquote></div><br><div>
-- <br>Jo Rhett<br>+1 (415) 999-1798<br>Skype: jorhett<br>Net Consonance : net philanthropy to improve open source and internet projects.
</div>
<br></div></div></body></html>