[Doc-SIG] Proposal: don't nest optional brackets

[A.M. Kuchling]

On Tue, Sep 16, 2008 at 07:10:59PM -0400, Fred Drake wrote:
> The nested notation makes sense for optional arguments, especially where 
> keywords aren't supported.  This is still the case for many of the APIs 
> written in C, and those cases often won't be changed due to performance 
> considerations.  (Adding keyword support definitely slows things down.)

So, the use cases are:

* Python code where arguments are both optional and specifiable as a
  keyword argument.
* C code where keywords are supported.
* C code where keywords are not supported.

I think nesting the optional arguments doesn't actually indicate
whether keywords are supported or not.  For example, 
two functions from the socket module are:

.. function:: getaddrinfo(host, port[, family[, socktype[, proto[, flags]]]])
.. method:: socket.recv_into(buffer[, nbytes[, flags]])

getaddrinfo() doesn't support keyword arguments; recv_into() does.
But nesting the brackets does add a lot of typographical fluff.

Can we invent a new notation for separating which functions support
keywords and which don't?  How would we render that distinction
typographically in the output?

Ideas:

* Boldface parameters that can be provided as keywords.

* Add '=' after parameters that can be provided as keywords:
  buffer=, [nbytes=, flags=] ... 

* Write keyword arguments as unnested square brackets:
  (buffer[, nbytes][, flags])

  This reserves the nesting for functions that don't support keywords.
  I think the difflib docs are mostly written in this style.

> So I guess now someone will tell me this has already been changed, and I 
> missed it.

No, no one's made any changes relating to this yet.

--amk