In the documentation for sprintf ( http://perlcabal.org/syn/S32/Str.html#sprintf) I suggest changing:
The $format is scanned for % characters. Any % introduces a format token. > Format tokens have the following grammar: to: The $format is scanned for % characters. Any % introduces a format token. > The simplest format tokens are a % followed by a letter which is called a > "directive". Directives guide the use (if any) of the rest of sprintf's > arguments. Between the % and the directive, a number of controls such as > precision and width formatting can be introduced. > In detail, format tokens have the following grammar: ... and remove the two sentences that follow the grammar itself. It's a bit harsh to drop the casual reader right into the grammar for format tokens without explaining what the grammar is for. As for the grammar itself, can we remove the commit after the initial %? Is it required for the documentation? On "index" modifiers: Do we need a string variant for named parameters in P6? E.g.: sprintf('%(time)$s: %(msg)$s', :$msg, :$time); as an alternative to: sprintf('%2$s: %1$s', $msg, $time); Python has something like this ( http://docs.python.org/library/stdtypes.html#string-formatting), but they drop the $ and just use "%(name)d" where d is the directive... it's not clear to me if the presence of the $ in P6 helps (because it maintains visual compatibility with numeric indexes) or hinders (because it's not required and therefore just makes the format longer for no reason)... Also documenting each part of the grammar is, of course, required. For example, here's a description of the "index" portion of the grammar: The index modifies the default behavior of pulling needed values from > sprintf's remaining arguments, in order. Instead, the given index number > addresses the positional argument list to sprintf, with the format string > itself being index zero and subsequent positional parameters being one and > so-forth. In that description, I'm implicitly allowing for a format string which includes itself ("%0$s"), which is not part of the previous standards, but I think it doesn't hurt, and avoids arbitrarily disallowing it the way P5 and POSIX do... The vector flag should probably go. Its only primary use is unpacking raw IPv4 addresses, and that can be done in a dozen other trivial ways in Perl 6. TMTOWTDI, but this is a particularly archaic way that I can't imagine any new code wanting to use... For the rest, I think we can copy the documentation for precision and flags from: http://perldoc.perl.org/functions/sprintf.html Also, a review of the POSIX documentation might reveal additional items that should be documented: http://pubs.opengroup.org/onlinepubs/9699919799/functions/sprintf.html -- Aaron Sherman <a...@ajs.com> P: 617-440-4332 Google Talk: a...@ajs.com / aaronjsher...@gmail.com "Toolsmith" and developer. Player of games. Buyer of gadgets.