I have had some difficulties to read the Perl documentation. I have tried to understand why. This describes some of my problems to understand the documentation of the function split. I also make some proposals to what could be changed.

Please note, I think I have understood most of what I need to understand, but it has taken a long time.

Definitions of terms use in the description of the Perl language

The definitions in perlglossary are rather general. Examples are:

• function
Mathematically, a mapping of each of a set of input values to a particular output value. In computers, refers to a subroutine or operator that returns a value. It may or may not have input values (called arguments).
• subroutine
A named or otherwise accessible piece of program that can be invoked from elsewhere in the program in order to accomplish some subgoal of the program. A subroutine is often parameterized to accomplish different but related things depending on its input arguments. If the subroutine returns a meaningful value, it is also called a function.
• Operator
A gizmo that transforms some number of input values to some number of output values, often built into a language with a special syntax or symbol. A given operator may have specific expectations about what types of data you give as its arguments (operands) and what type of data you want back from it.
• Operand
An expression that yields a value that an operator operates on. See also precedence.
• Argument
A piece of data supplied to a program, subroutine, function, or method to tell it what it's supposed to do. Also called a "parameter".

Terms I try to use in this post

The Perl's perspective is missing in perlglossary. The definition of the Perl specific meaning of a term when used in the documentation of the Perl language is often missing.

Meaning of terms used here are:

• Function
What you want to be done.
• Syntax pattern
The lines in the beginning of a description of a subroutine or operator. It shows the usages.
• Subroutine
An implementation of a function described in perlsub. The input is called argument. Output is the return value.
• Operator
An implementation of a function described in perlop. The input is called operand.

Are the more implementation mechanisms of functions in Perl?

I am aware of that a subroutine can be used as an operator and the reverse. In this post I have disregarded this.

The description of Perl subroutine

(In the index of "Language reference" the description is called "perlsub - subroutine function". What is a subroutine function?)

I suppose the intention of perlsub is to describe the subroutine mechanism in Perl.

This is one of the key parts to understand the usage of a Perl subroutine: From perlsub:

The Perl model for function call and return values is simple: all functions are passed as parameters one single flat list of scalars, and all functions likewise return to their caller one single flat list of scalars. Any arrays or hashes in these call and return lists will collapse, losing their identities--but you may always use pass-by-reference instead to avoid this. Both call and return lists may contain as many or as few scalar elements as you'd like. (Often a function without an explicit return statement is called a subroutine, but there's really no difference from Perl's perspective.)

(According to the glossary a function refers to a "subroutine or operator that returns a value". The sentence in parenthesis is a bit confusing.)

I have also been misled to think that the text above applies to all the functions described in index-functions.

My proposal is to change the text to:

The Perl model for subroutine call arguments and return values is simple: all subroutines are passed as arguments one single flat list of scalars. All subroutines return a return value, which is one single flat list of scalars. Any arrays or hashes in these call and return lists will collapse, losing their identities--but you may always use pass-by-reference instead to avoid this. Both call and return lists may contain as many or as few scalar elements as you'd like.

And to add this:

The arguments and return values are transferred using the argument stack. The arguments in the script source code is processed (evaluated) to store them in the argument stack. This is done before the subroutine definition is called.

The syntax patterns in the beginning of the descriptions of functions implemented by subroutines, describe the content of the argument stack after the per-processing (evaluation) of the arguments.

(argument stack must be added to perlglossary. Argument stack is described in perlguts

The description of the function split

In the description of the Perl functions it isn't always stated how a function is implemented.

Split is not implemented as a subroutine and does not behave like a subroutine. At least the differences in the processing of the arguments compared to the normal processing of those to a normal Perl subroutine must be described.

The syntax pattern for split describes the source code, not the result after per-processing of the arguments as it is for a subroutine.

If you call split like this @rv = split $_[0], @_[ 1 .. 2 ] you get the return value undef. This is_deeply [ $_[0], @_[ 1 .. 2 ] ], [ qr{(:)}, 'a:b:c', 99 ] is ok.

I had expected a warning or error exception.

All of this is perhaps errors in the implementation if split.

Summary

I understand that it is impossible to do big changes to the documentation of Perl.

Is there something small that can be done?

I believe that one of the first thing to do is to improve is perlglossary. Definitions of meanings from a Perl's perspective should be added.

Perhaps there could be two glossaries. One general and computer science focused and one with the Perl specific definitions used in the documentation of the Perl language.