-Picture lines are printed exactly as they look, except for certain fields
-that substitute values into the line. Each field in a picture line starts
-with either "@" (at) or "^" (caret). These lines do not undergo any kind
-of variable interpolation. The at field (not to be confused with the array
-marker @) is the normal kind of field; the other kind, caret fields, are used
-to do rudimentary multi-line text block filling. The length of the field
-is supplied by padding out the field with multiple "E<lt>", "E<gt>", or "|"
-characters to specify, respectively, left justification, right
-justification, or centering. If the variable would exceed the width
-specified, it is truncated.
-
-As an alternate form of right justification, you may also use "#"
-characters (with an optional ".") to specify a numeric field. This way
-you can line up the decimal points. If any value supplied for these
-fields contains a newline, only the text up to the newline is printed.
-Finally, the special field "@*" can be used for printing multi-line,
-non-truncated values; it should appear by itself on a line.
-
-The values are specified on the following line in the same order as
-the picture fields. The expressions providing the values should be
-separated by commas. The expressions are all evaluated in a list context
+Picture lines contain output field definitions, intermingled with
+literal text. These lines do not undergo any kind of variable interpolation.
+Field definitions are made up from a set of characters, for starting and
+extending a field to its desired width. This is the complete set of
+characters for field definitions:
+X<format, picture line>
+X<@> X<^> X<< < >> X<< | >> X<< > >> X<#> X<0> X<.> X<...>
+X<@*> X<^*> X<~> X<~~>
+
+ @ start of regular field
+ ^ start of special field
+ < pad character for left justification
+ | pad character for centering
+ > pad character for right justification
+ # pad character for a right justified numeric field
+ 0 instead of first #: pad number with leading zeroes
+ . decimal point within a numeric field
+ ... terminate a text field, show "..." as truncation evidence
+ @* variable width field for a multi-line value
+ ^* variable width field for next line of a multi-line value
+ ~ suppress line with all fields empty
+ ~~ repeat line until all fields are exhausted
+
+Each field in a picture line starts with either "@" (at) or "^" (caret),
+indicating what we'll call, respectively, a "regular" or "special" field.
+The choice of pad characters determines whether a field is textual or
+numeric. The tilde operators are not part of a field. Let's look at
+the various possibilities in detail.
+
+
+=head2 Text Fields
+X<format, text field>
+
+The length of the field is supplied by padding out the field with multiple
+"E<lt>", "E<gt>", or "|" characters to specify a non-numeric field with,
+respectively, left justification, right justification, or centering.
+For a regular field, the value (up to the first newline) is taken and
+printed according to the selected justification, truncating excess characters.
+If you terminate a text field with "...", three dots will be shown if
+the value is truncated. A special text field may be used to do rudimentary
+multi-line text block filling; see L</Using Fill Mode> for details.
+
+ Example:
+ format STDOUT =
+ @<<<<<< @|||||| @>>>>>>
+ "left", "middle", "right"
+ .
+ Output:
+ left middle right
+
+
+=head2 Numeric Fields
+X<#> X<format, numeric field>
+
+Using "#" as a padding character specifies a numeric field, with
+right justification. An optional "." defines the position of the
+decimal point. With a "0" (zero) instead of the first "#", the
+formatted number will be padded with leading zeroes if necessary.
+A special numeric field is blanked out if the value is undefined.
+If the resulting value would exceed the width specified the field is
+filled with "#" as overflow evidence.
+
+ Example:
+ format STDOUT =
+ @### @.### @##.### @### @### ^####
+ 42, 3.1415, undef, 0, 10000, undef
+ .
+ Output:
+ 42 3.142 0.000 0 ####
+
+
+=head2 The Field @* for Variable Width Multi-Line Text
+X<@*>
+
+The field "@*" can be used for printing multi-line, nontruncated
+values; it should (but need not) appear by itself on a line. A final
+line feed is chomped off, but all other characters are emitted verbatim.
+
+
+=head2 The Field ^* for Variable Width One-line-at-a-time Text
+X<^*>
+
+Like "@*", this is a variable width field. The value supplied must be a
+scalar variable. Perl puts the first line (up to the first "\n") of the
+text into the field, and then chops off the front of the string so that
+the next time the variable is referenced, more of the text can be printed.
+The variable will I<not> be restored.
+
+ Example:
+ $text = "line 1\nline 2\nline 3";
+ format STDOUT =
+ Text: ^*
+ $text
+ ~~ ^*
+ $text
+ .
+ Output:
+ Text: line 1
+ line 2
+ line 3
+
+
+=head2 Specifying Values
+X<format, specifying values>
+
+The values are specified on the following format line in the same order as
+the picture fields. The expressions providing the values must be
+separated by commas. They are all evaluated in a list context