[vlc-devel] [PATCH 12/13] vout/opengl: add a new API to configure fragment shaders

[Wilawar]

At first I only wanted to tell you that your use of 'in function of' is off, but then, when I read this patch
more closely, I noticed more to improve. Please note that I lack the knowledge to be really sure that
the alternatives I recommend are technically correct.
The original phrasing is given as citations of the diff, I’ll prefix my drop-in replacements with plain '+'
and give the reasoning below.

> + * Callback to initialize a opengl_fmt_cfg_t struct
+ * Callback to initialize an opengl_fmt_cfg_t struct
'an' is used instead of 'a' if the sound that follows is a vocal. (The sound, not just the letter, btw.)
In the same vain:
> + * Structure that is filled by a opengl_fmt_cfg_init_cb function
+ * Structure that is filled by an opengl_fmt_cfg_init_cb function

> This struct can be used to configure a fragment shader in function of a video_format_t.
See below.

> + * The function implementing this callback should initialize a fragment_shader
> + * in function of the video format.
+ * The function implementing this callback should initialize a fragment_shader
+ * based on the referenced video format.
-- or --
+ * The function implementing this callback should initialize a fragment_shader
+ * for the referenced video format.
-- or --
+ * The function implementing this callback should initialize a fragment_shader
+ * to work with the referenced video format.
This use of 'in function of' plainly doesn’t make sense for me, but since I got doubts whether it’s really wrong,
I casually got some references via Google to back me up, making me confident; I read at least those:
http://english.stackexchange.com/questions/30547/is-the-phrase-in-function-of-proper-english
http://forum.wordreference.com/threads/in-as-function-of.2056579/
http://ccnmtl.columbia.edu/projects/mmt/frontiers/web/chapter_3/9121.html (which does not mention it)

> + * \param fc opengl format configuration that need to be filled on success
+ * \param fc OpenGL format configuration that needs to be filled on success
The verb needs to end with an S in the third person singular form.

> +     * attached to the configured shared.
+     * attached to the configured shader.
Typo, I guess.

> +     * \param api function pointer to the GL API
This sounds off, but I’m not sure what to recommend as replacement, maybe someone else does,
but I guess it can be understood without changing it.


I hope the format I’ve chosen this time will be more readable to you. Let me know whether you’re interested in
proof-reading plain English at all.
I also hope that you understand that I neither think this could have been handled by RFC patches in any
sensible way nor that I really want to go through copying out the patch, creating a file for it, applying it in Git
(especially since it won’t necessarily apply on its own as it’s part of a series), followed by eight turns of
changing a few characters (once for every change), doing a format-patch, copying it over and wrapping it up,
then sending an eight part RFC series of nitpick changes to a single patch. (Also called spamming.) ;)

-- 
http://www.fastmail.com - A no graphics, no pop-ups email service