[Doc-SIG] docstring grammar

[uche.ogbuji@fourthought.com]

> OK, start with the last: Tibs, you observed a while back that the human
> brain holds up to 7 (or is it 12 ?) things at the same time.  That's the
> `for humans to parse' constraint.  We want to keep to a minimum the set
> of keywords a programmer needs to be familiar with to be able to get
> pay-back from using the document format.

It sounds as if you are going for the Miller 7 +/- 2 rule, which holds that 
most people can hold between 5 and 9 units of related information at a time, 
particularly in short-term memory.

It is always a good idea in API and protocol design to keep main elements 
within the 7 +/- 2, but there is no reason not to have a few less used, 
optional and advisedly more arcane elements for the more experienced users.

So far it seems we're close to that point in "canonical doc-string", so I 
agree that as soon as the scapegoat (too bad it appears to be you, David, but 
that's what you get for introducing such a sterling proposal) comes up with a 
second proposal that takes all the recent discussion into account, we should 
call it alpha and start hacking.

> Various folk discussed language.  My ha'p'n'rth on that would go for a
> variable in the module namespace, nominally
> 
> __language__ = 'en:UK'	# expect English spellings, like colour, sulphur
> 
> and I'd vote for the *default* to be Dutch (to encourage US anglophones
> to get used to admitting that they speak 'en:US' or whatever it's called)
> though I realise I might have to live with 'en:US'.
> 
> Why, you might ask, do I want it in the module namespace ?
> 
> So that the contents of the doc string are *all* in the same language:
> it'd just be perverse to have an anglophone keyword (Language) as the
> one keyword which we don't translate, in doc-strings; and the magic
> names in a module's namespace, like the reserved words of the language
> (*outside* the doc string) are already condemned to monolinguism, so we
> might as well leverage their sacrifice to enable the purity of the doc
> strings.

I rather like this idea.  We are building a similar mechanism into 4Suite to 
support i18n messages, and it would be nice to unify the doc-string and code 
l10n mechanism.  I would rename it

__locale__ = 'en:UK'

To go in line with more common usage.  It would alctually then be nice for 
Python (1.6 feature?) to read the LC_ALL environment variable in UNIX, and the 
 equivalent on other platforms, and set a default for the __locale__.

I also like the idea that all keywords would be in the local language.

> Either that or do something entertaining which involves looking for a
> match to:
> 
> <keyword meaning `language'>: <language in which that keyword means `language'>

Umm.  Or much rather not.

> Celui qui parle trois langues s'appelle un trilangue.
> Celui qui parle deux langues s'appelle un bilangue.
> Mais celui qui parle seulement un langue s'appelle un anglophone.
> 				-- Quebecois joke.

This is an absolute jem (or should I say 'bijou'?)  Strange how often the 
heartiest humor comes from the most cynical attitudes.

-- 
Uche Ogbuji
FourThought LLC, IT Consultants
uche.ogbuji@fourthought.com	(970)481-0805
Software engineering, project management, Intranets and Extranets
http://FourThought.com		http://OpenTechnology.org