[Doc-SIG] Docstring syntax discussion

[Jack Jansen]

> Hello all,
> =

> I think the current docstring syntax discussion fails to address a
> very important issue. Not all users of Python are native english
> speakers and writers (I'm of course one of these). I think localizing
> python modules and programs is an important issue. Localizing does not
> only include the programs messages, but also the functions help
> messages. This is a problem, that can't be addressed using the current
> docstring syntax. =


I would suggest extending the proposed scheme with a language indicator =

(probably according to some ISO coding) and an "alternative" keyword that=
 =

would give two alternatives for the same thing. So the following three =

docstrings would be more-or-less equivalent:

"""
Description:
	This function does nothing.
"""

"""
Language: en
Description:
	This function does nothing.
"""

"""
Alternative:
	Language: en
	Description:
		This function does nothing.
Alternative:
	Language: nl
	Description:
		Deze functie doet niets.
"""

It is probably open to discussion whether the default for Language should=
 be =

unspecified/unknown (which is politically correct) or english (which is =

probably a lot more practical, since I don't think we can teach these =

americans to add the Language tag all the time:-).
--
Jack Jansen             | ++++ stop the execution of Mumia Abu-Jamal ++++=

Jack.Jansen@oratrix.com | ++++ if you agree copy these lines to your sig =
++++
www.oratrix.nl/~jack    | see http://www.xs4all.nl/~tank/spg-l/sigaction.=
htm =