From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Chong Yidong Newsgroups: gmane.emacs.devel Subject: Re: doc string of `format' - FLAGS unexplained Date: Mon, 25 Feb 2008 18:13:33 -0500 Message-ID: <87r6f0wrxe.fsf@stupidchicken.com> References: <003c01c8767e$115f1520$0600a8c0@us.oracle.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: ger.gmane.org 1203981326 18505 80.91.229.12 (25 Feb 2008 23:15:26 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 25 Feb 2008 23:15:26 +0000 (UTC) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Feb 26 00:15:49 2008 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1JTmXt-0002cl-MN for ged-emacs-devel@m.gmane.org; Tue, 26 Feb 2008 00:15:41 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1JTmXN-0004qj-Me for ged-emacs-devel@m.gmane.org; Mon, 25 Feb 2008 18:15:09 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1JTmXJ-0004pb-4s for emacs-devel@gnu.org; Mon, 25 Feb 2008 18:15:05 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1JTmXI-0004oa-HG for emacs-devel@gnu.org; Mon, 25 Feb 2008 18:15:04 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1JTmXI-0004oO-CB for emacs-devel@gnu.org; Mon, 25 Feb 2008 18:15:04 -0500 Original-Received: from cyd.mit.edu ([18.115.2.24]) by monty-python.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1JTmXI-0000Zq-4J for emacs-devel@gnu.org; Mon, 25 Feb 2008 18:15:04 -0500 Original-Received: by cyd.mit.edu (Postfix, from userid 1000) id 63A9B4E3F9; Mon, 25 Feb 2008 18:13:33 -0500 (EST) In-Reply-To: <003c01c8767e$115f1520$0600a8c0@us.oracle.com> (Drew Adams's message of "Sat\, 23 Feb 2008 16\:42\:00 -0800") User-Agent: Gnus/5.11 (Gnus v5.11) Emacs/22.1.91 (gnu/linux) X-detected-kernel: by monty-python.gnu.org: Linux 2.6 (newer, 2) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:90442 Archived-At: "Drew Adams" writes: > The doc string includes this: > > The basic structure of a %-sequence is > % character > where flags is [-+ #0]+, width is [0-9]+, and precision is .[0-9]+ > > But there is absolutely no explanation of what FLAGS, WIDTH, and > PRECISION mean. One might be able to guess for WIDTH and PRECISION, > but not for FLAGS. Please include some of the explanation from the > Elisp manual, adapting it as needed. > > Also, the EMACS convention for doc strings is to use uppercase: FLAGS, > not angle brackets: . I'd like to propose the following change to the doc string of `format'. In particular, the statement "flags is [-+ #0]+" is misleading; it should be [+ #]+, since the - and 0 characters are actually used to identify the width specifier instead. Any thoughts? *** emacs/src/editfns.c.~1.439.2.10.~ 2008-01-10 10:26:25.000000000 -0500 --- emacs/src/editfns.c 2008-02-25 18:12:57.000000000 -0500 *************** *** 3383,3389 **** doc: /* Format a string out of a format-string and arguments. The first argument is a format control string. The other arguments are substituted into it to make the result, a string. ! It may contain %-sequences meaning to substitute the next argument. %s means print a string argument. Actually, prints any object, with `princ'. %d means print as number in decimal (%o octal, %x hex). %X is like %x, but uses upper case. --- 3383,3392 ---- doc: /* Format a string out of a format-string and arguments. The first argument is a format control string. The other arguments are substituted into it to make the result, a string. ! ! The format control string may contain %-sequences meaning to substitute ! the next available argument: ! %s means print a string argument. Actually, prints any object, with `princ'. %d means print as number in decimal (%o octal, %x hex). %X is like %x, but uses upper case. *************** *** 3393,3404 **** or decimal-point notation, whichever uses fewer characters. %c means print a number as a single character. %S means print any object as an s-expression (using `prin1'). ! The argument used for %d, %o, %x, %e, %f, %g or %c must be a number. Use %% to put a single % into the output. ! The basic structure of a %-sequence is ! % character ! where flags is [-+ #0]+, width is [0-9]+, and precision is .[0-9]+ usage: (format STRING &rest OBJECTS) */) (nargs, args) --- 3396,3428 ---- or decimal-point notation, whichever uses fewer characters. %c means print a number as a single character. %S means print any object as an s-expression (using `prin1'). ! ! The argument used for %d, %o, %x, %e, %f, %g or %c must be a number. Use %% to put a single % into the output. ! A %-sequence may contain optional flag, width, and precision ! specifiers, as follows: ! ! %character ! ! where flags is [+ #]+, width is [0-9]+, and precision is .[0-9]+ ! ! The + flag character inserts a + before any positive number, while a ! space inserts a space before any positive number; these flags only ! affect %d, %e, %f, and %g sequences, and + takes precedence if both ! flags are present. The # flag means to use an alternate display form ! for %o, %x, %X, %e, %f, and %g sequences. ! ! The width specifier supplies a lower limit for the length of the ! printed representation. The padding, if any, goes on the left if the ! width specifier is positive or starts with a 0, and on the right if it ! is negative. The padding character is normally a space, and 0 if the ! width specifier starts with the character 0. ! ! For %e, %f, and %g sequences, the number after the "." in the ! precision specifier says how many decimal places to show; if zero, the ! decimal point itself is omitted. For %s and %S, the precision ! specifier truncates the string to the given width. usage: (format STRING &rest OBJECTS) */) (nargs, args)