Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl-Sensitive Sunglasses
 
PerlMonks  

comment on

( [id://3333]=superdoc: print w/replies, xml ) Need Help??

This is the important part of this discussion, so I'll put it first:

It still is Debian's fault, though.

I very much disagree. As I said, I believe the offending document should be removed from the Perl distribution pending a license change. If it isn't distributed with exactly the same terms as Perl itself, it shouldn't be distributed with Perl at all. It isn't reasonable to expect every user to inspect every file in the distribution for different licensing terms.

The rest isn't really important but deserves response...

In practice, when someone doesn't understand the documentation, it takes up to one or two hours before they understand how references work.

Not in my substantial experience. I used to op on #perl on openprojects.net starting when there were about 10 people in the channel and continuing until it grew to about 75 regularly. (In fact, that's how I "met" Brendan a.k.a. bod.) I've helped many people get a grasp on references in less than 20 minutes.

We tell them to RTFM, and specify which manual. Depending on the situation, this can be a perldoc, Coping with Scoping, Suffering from Buffering, Beginning Perl, a module's POD, one of the many PM Tutorials, etcetera, etcetera.

You mention several documents that are not part of the perl distribution... so, tell me again... what was wrong with diotalevi's suggestion that you point them to perlreftut on perldoc.com?

I agree that the perl documentation is a maze and that pointing them at the right one can be helpful, however, some personalized help and a pointer to the right TFM to R is almost always more helpful and it leaves a better impression too.

-sauoq
"My two cents aren't worth a dime.";

In reply to Re: RTFM works perlfectly. (Re: Re: Re: Re: Debian removed perlreftut) by sauoq
in thread Debian removed perlreftut by Juerd

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Are you posting in the right place? Check out Where do I post X? to know for sure.
  • Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
    <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>
  • Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
  • Want more info? How to link or How to display code and escape characters are good places to start.
Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others contemplating the Monastery: (4)
As of 2024-06-21 21:25 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found

    Notices?
    erzuuli‥ 🛈The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.