Re: Doc: make python function/method descriptions look as in Python

[Eli Zaretskii <eliz at gnu dot org>]

> From: <Paul_Koning@Dell.com>
> 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.