Beefy Boxes and Bandwidth Generously Provided by pair Networks
Do you know where your variables are?
 
PerlMonks  

comment on

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

Hello rsFalse

Perl documentation is written for various levels of Perl hacker.

Those already confident with programming generally want a quick overview so they can establish how Perl differs from a language they are already well acquainted with. It is fairly common to see descriptions of how Perl does not behave like C in certain situations. This is true of operators especially.

There are also persons whom are at a high level in other disciplines and have heard that some modules in Perl are very well suited to their purpose. A good example would be Biologists using BioInformatics. They need to know enough to get done what they need for their particular task. At this point the Module Documentation (POD) should be providing suitably usable examples for that level of user.

Then there are just the hackers, like myself, using the Documentation to learn, along with other resources such as Manuals, contributing to Forums, watching/attending Conferences and so on.

For the general hacker, ideas such as associativity and precedence can certainly be confusing and do have a learning curve. In the documentation it says that associativity works in similar way to how it works in math. Then precedence enters the equation. And now it seems transitivity or inequality have crashed the party in the hope of forming some relationships.

Another theme that appears to crop up is that of Perl 5 Documentation unscrupulously objectifying itself. Though this is more of a personal bugbear, I have to admit the use of terminology such as Class for Namespace and Pointers for References within the Documentation is a little misleading/sloppy. Naturally, colloquially using terminology that you are used to is going to occur all around the place, which is completely understandable, as we all do that to some extent.

Such an approach can be useful for introductory and explanative purposes, the drawback being assumptions travel with the learning. Sure in class we can overlook low-level complexities, for the purpose of communicating the high-level idioms. But after a while the documentation starts reading like a manual for another language.

Still, regarding the chaining of operators, the documentation is clear about the operators that now have this capability being relational. In the big picture of things, this is the kind of thing that you might do for a particular purpose. As such the user is more than likely aware of the properties of relationships they are studying.

You provide some arithmetical examples of how chaining might be implemented in some users program. However the string relations also chain now, have you considered how this might be useful for say deciding grammatical order of a sentence based on particular inflections? (lol just made that up, but, for example, I could well imagine people wanting to reinvent unicode using a differnt underlying system). Collation tends to be quite systematic, and again one of the goals of Perl is to be as understandable written as it would be to speak with someone.

Without labouring the point, Perl arrived at us from a heavy influence of the Humanities, as such it stands out from the mainstream language definitions that tend to be derived from mathematical perspectives. Certainly we should be careful to preserve such perspectives.

Learning any language is always going to have a curve, sometimes you are going to write code that is complicated to read, maintain. Surely simplifying Documentation goes a way towards reducing that curve, but when learning, the emphasis should be on writing more code, or rather, writing more well commented code.

In terms of introducing new operators. There are a number of ways in which a user can define operations at a high-level. A straightforward way to start would be to write a subroutine that implements such operations. Then develop from there. Another alternative is to keep in mind that Perl is becoming a family. Raku as far as I am aware, has user-defined operations as standard.

At this time, I would say it is more productive to focus on ensuring the Documentation is in its best format for all levels. Often, being able to effectively ligature the Documentation to the practice is a quarter or more the fun of learning.

In a roundabout way, I am saying there could be scope for improving the operator precedence/associativity list. But, I would also say it does already do what it needs to. Creating a table maybe isnt quite justified on its own, just to highlight a slight update in the way a particular group of operators now has an additional capability. The beauty of this kind of thing is that the operators will more likely appear to just work as someone would expect them to first use around, a little better now than they did previously.

If you wanted to outline how it might look once it was updated, maybe post a short/quick tutorial of how chaining works, including how an updated precedence list might look.


Where is my lib? Where. Is. My. Lib?

In reply to Re: For discussion: operator attributes - associativity, chainity and ability to short-circuit by Don Coyote
in thread For discussion: operator attributes - associativity, chainity and ability to short-circuit by rsFalse

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 scrutinizing the Monastery: (6)
As of 2024-03-28 15:12 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found