use of "specified as" in documentation

[Tshepang Lekhonkhobe]

As an example, given this piece of doc:

"render(renderer_name, value, request=None, package=None)"

As explanation would start with:

"Using the renderer specified as ``renderer_name``...".

I think this can be misleading at first to readers, as it was to me, that renderer_name is some special type of object, but is only a string. It is also overlong, and perhaps overly formal.

There are other variations of this, e.g. "supplied as". I think it would be better to simply change such sentences to say:

"Using the renderer ``renderer_name``..."

This is how CPython documentation does it and should therefore not be strange to Python users.

If this suggestion is acceptable, I will happily provide the patches.

[Steve Piercy]

IMO, "specified as" implies "must be" and it causes me to do a
double-take. "Supplied as" is a strange idiom and could be
challenging to translate out of English. I agree with your suggestion.

--steve



On 1/21/13 at 10:53 PM, tshe...@gmail.com (Tshepang
Lekhonkhobe) pronounced:

--steve

[Paul Everitt]

FWIW, later in the month I plan to do some docs work, so any pull requests you can file would be great.

--Paul

[Tshepang Lekhonkhobe]

I is happy now. This is pretty much done, since my patches have been committed to master.