Merge pull request #278 from mortie/patch-1

Some more documentation about put

Author: zoffixznet

doc/Language/faq.pod

@@ -356,21 +356,21 @@ But don't do that.  If the name is public, there is no downside to
 declaring it that way with C<$.x> since the external view is readonly
 by default, and you can still access it internally with C<$!x>.
 
-=head2 How and why do C<say> and C<print> differ?
+=head2 How and why do C<say>, C<put> and C<print> differ?
 
-The most obvious difference is that C<say> appends a newline at the
-end of the output, and C<print> does not.
+The most obvious difference is that C<say> and C<put> appends
+a newline at the end of the output, and C<print> does not.
 
-But there is another difference: C<print> converts its arguments to
-a string by calling the C<Str> method on each item passed to, C<say>
-uses the C<gist> method instead. The former is meant for computers,
-the latter for human interpretation.
+But there is another difference: C<print> and C<put> converts its
+arguments to a string by calling the C<Str> method on each item
+passed to, C<say> uses the C<gist> method instead. The former
+is meant for computers, the latter for human interpretation.
 
 Or phrased differently, C<$obj.Str> gives a string representation,
 C<$obj.gist> a short summary of that object suitable for fast recognition
 by the programmer, and C<$obj.perl> gives a Perlish representation.
 
-For example type objects, also known as "undefined values", stringify
+Example: type objects, also known as "undefined values", stringify
 to an empty string and warn, whereas the C<gist> method returns the name
 of the type, followed by an empty pair of parenthesis (to indicate there's
 nothing in that value except the type).
@@ -380,8 +380,12 @@ nothing in that value except the type).
     say $x;         # (Date)\n
 
 So C<say> is optimized for debugging and display to people, C<print>
-is more suitable for producing output for other programs to consume.
-(Use C<put> if you want C<print> semantics with a newline.)
+and C<put> is more suitable for producing output for other programs
+to consume.
+
+C<put> is thus sort of a hybrid between C<print> and C<say>;
+like C<print>, its output is suitable for other programs,
+and like C<say>, it adds a newline at the end of the output.
 
 =head2 What's the difference between C<token> and C<rule> ?