Re: use of specified as in documentation
I is happy now. This is pretty much done, since my patches have been committed to master. On Tuesday, January 22, 2013 5:37:43 PM UTC+2, Paul Everitt wrote: FWIW, later in the month I plan to do some docs work, so any pull requests you can file would be great. --Paul On Monday, January 21, 2013 10:53:03 PM UTC-8, Tshepang Lekhonkhobe wrote: 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. -- You received this message because you are subscribed to the Google Groups pylons-devel group. To unsubscribe from this group and stop receiving emails from it, send an email to pylons-devel+unsubscr...@googlegroups.com. To post to this group, send email to pylons-devel@googlegroups.com. Visit this group at http://groups.google.com/group/pylons-devel?hl=en. For more options, visit https://groups.google.com/groups/opt_out.
Re: use of specified as in documentation
FWIW, later in the month I plan to do some docs work, so any pull requests you can file would be great. --Paul On Monday, January 21, 2013 10:53:03 PM UTC-8, Tshepang Lekhonkhobe wrote: 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. -- You received this message because you are subscribed to the Google Groups pylons-devel group. To view this discussion on the web visit https://groups.google.com/d/msg/pylons-devel/-/dqJp-8B3J6QJ. To post to this group, send email to pylons-devel@googlegroups.com. To unsubscribe from this group, send email to pylons-devel+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/pylons-devel?hl=en.
use of specified as in documentation
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. -- You received this message because you are subscribed to the Google Groups pylons-devel group. To view this discussion on the web visit https://groups.google.com/d/msg/pylons-devel/-/8jKHbNACxicJ. To post to this group, send email to pylons-devel@googlegroups.com. To unsubscribe from this group, send email to pylons-devel+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/pylons-devel?hl=en.
Re: use of specified as in documentation
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, tshep...@gmail.com (Tshepang Lekhonkhobe) pronounced: 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 -- You received this message because you are subscribed to the Google Groups pylons-devel group. To post to this group, send email to pylons-devel@googlegroups.com. To unsubscribe from this group, send email to pylons-devel+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/pylons-devel?hl=en.