From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 16868 invoked by alias); 3 Sep 2011 10:27:23 -0000 Received: (qmail 16859 invoked by uid 22791); 3 Sep 2011 10:27:22 -0000 X-SWARE-Spam-Status: No, hits=0.9 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_NONE,RCVD_IN_JMF_BL,RCVD_IN_SORBS_WEB,SPF_SOFTFAIL X-Spam-Check-By: sourceware.org Received: from mtaout23.012.net.il (HELO mtaout23.012.net.il) (80.179.55.175) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Sat, 03 Sep 2011 10:27:07 +0000 Received: from conversion-daemon.a-mtaout23.012.net.il by a-mtaout23.012.net.il (HyperSendmail v2007.08) id <0LQX00900Z9I8J00@a-mtaout23.012.net.il> for gdb-patches@sourceware.org; Sat, 03 Sep 2011 13:27:01 +0300 (IDT) Received: from HOME-C4E4A596F7 ([84.229.83.44]) by a-mtaout23.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0LQX009YAZP08B10@a-mtaout23.012.net.il>; Sat, 03 Sep 2011 13:27:01 +0300 (IDT) Date: Sat, 03 Sep 2011 19:46:00 -0000 From: Eli Zaretskii Subject: Re: Doc: make python function/method descriptions look as in Python In-reply-to: <09787EF419216C41A903FD14EE5506DD015343BFAE@AUSX7MCPC103.AMER.DELL.COM> To: Paul_Koning@Dell.com Cc: gdb-patches@sourceware.org Reply-to: Eli Zaretskii Message-id: <837h5p2a6g.fsf@gnu.org> References: <09787EF419216C41A903FD14EE5506DD015343BFAE@AUSX7MCPC103.AMER.DELL.COM> X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2011-09/txt/msg00052.txt.bz2 > From: > Date: Thu, 1 Sep 2011 15:52:59 -0500 > > I found the descriptions of the Python methods/functions hard to read because they are not shown in Python syntax. The attached patch fixes that. Parentheses now appear wherever they would in the Python code. Also, multiple optional arguments are shown as [arg1 [, arg2]] since by Python rule you can omit only consecutive arguments from the right end. (Having them individually bracketed makes it appear that they can be individually omitted.) I have no opinion on whether this is desirable or not; I will go with whatever others think. Python is a read-only language for me. On the pure Texinfo side, in addition to the typo spotted by Pedro, I have the following comments: > -@defun execute command [from_tty] [to_string] > +@defun execute (command @r{[}, from_tty @r{[}, to_string@r{]}@r{]}) You can mark several `]' characters together, like this: @defun execute (command @r{[}, from_tty @r{[}, to_string@r{]]}) There are several of these in the patch. What you did is not wrong, though. > -@defmethod Value string @r{[}encoding@r{]} @r{[}errors@r{]} @r{[}length@r{]} > +@defmethod Value string (@r{[}encoding@r{[}, errors@r{[}, > +length@r{]}@r{]}@r{]}) You cannot break any of the @def* lines, they all must be a single line, even if it is long (here and elsewhere). Finally, please note that the way you put the parentheses (..) in the @def* directives, they will be typeset in slant typeface (I think). So please make a PDF or PS output and eyeball it to make sure you like the result. If you don't like it, you can use @r{(} and @r{)} like we do with square brackets. Thanks.