[doc] perldoc -f print: confusing wording regarding misinterpretation of variable as an operator

[x-qq]

Where https://perldoc.perl.org/perlfunc#print-FILEHANDLE-LIST

Description The following wording is confusing:

(NOTE: If FILEHANDLE is a variable and the next token is a term, it may be misinterpreted as an operator
unless you interpose a + or put parentheses around the arguments.)

• it is unclear what token and term are here
• if this is so important that it can cause an error in interpretation, there should be an example:

  print $foo -3
  vs
  print $foo - 3

  parse differently

In my opinion it would be better to recommend universal use of method-like syntax for print in this document: $fh->print($stuff) because it helps to reduce ambiguity.

[leonerd]

+1.

At the very least, various bits of documentation around syntax sometimes use words like "term", which don't have a clear definition elsewhere in docs - or in the implementation for that matter ;) We could do a good cleaning up of these.

But also I think it would be good to encourage the far-less-ambiguous method style of $fh->print(), and leave the indirect notation forms almost as a historic footnote; explaining what users might come across in old code but not encouraging them to actually use those in newly-written stuff.

[rsFalse]

I will add, that Damian Conway in the book "Perl Best Practices" recommends to use braces:

Putting braces around the filehandle helps it stand out clearly: print {$file} $name, $rank, $serial_num, "\n";

( Once I got the suggestion to use braces after asking a similar question (with similar example) in forum: https://perlmonks.org/?node_id=1231158 - "Ambiguous '~~' in 'print scalar ~~list'" )